relayr

README

RelayR

RelayR is a Go package that provides easy-to-use real time communication APIs for Go web applications.

Current version: 0.2.1

Please see CHANGELOG.md for details about the changes between versions.

Installation

IMPORTANT:

RelayR relies on the Gorilla WebSocket package for WebSocket support. Please head over to that repository, give it a star, and ``go getit into yourGOPATH`.

Also important: RelayR currently only supports WebSockets. Server Sent Events and Long Polling options are on the roadmap.

Installing RelayR

After you have installed the Gorilla WebSocket package, you can run the following:

go get https://github.com/simon-whitehead/relayr

Examples

The /examples directory contains three examples.

The first one is a simple Server -> Client timestamp push. The server will push the current time down to all connected clients every second.

It looks like this:

The second one is a replica of the famous SignalR sample, "High-Frequency Realtime with SignalR" where a shape can be dragged around a browser and broadcast to all clients.

It looks like this:

The third one demonstrates Groups and membership. It allows clients to subscribe to groups and receive notifications that are pushed to groups they are subscribed to.

Project status

This is very much a work in progress - some might say, pre-alpha. The code is horrible .. but it works. I am opening it up to the world early for feedback and contributions (in any form).

Contributing

Please! Fork away .. improve it .. create a PR .. whatever you want to do. I am open to any and all help.

Licence

This code is released under the Apache 2.0 licence.

Documentation

Overview

Package relayr provides high level functionality for real-time web communication. It allows communication between front-end clients and back-end servers via easy-to-use constructs.

Index

• Variables
• func DisableScriptCache()
• type ClientOperations
  • func (c *ClientOperations) All(fn string, args ...interface{})
  • func (c *ClientOperations) Others(fn string, args ...interface{})
• type Exchange
  • func NewExchange() *Exchange
  • func (e *Exchange) RegisterRelay(x interface{})
  • func (e *Exchange) Relay(x interface{}) *Relay
  • func (e *Exchange) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type GroupOperations
  • func (g *GroupOperations) Add(connectionID string)
  • func (g *GroupOperations) Call(fn string, args ...interface{})
  • func (g *GroupOperations) Remove(connectionID string)
• type Relay
  • func (r *Relay) Call(fn string, args ...interface{})
  • func (r *Relay) Groups(group string) *GroupOperations
• type Transport

Variables

var ClientScriptFunc func([]byte) []byte

ClientScriptFunc is a callback for altering the client side generated Javascript. This can be used to minify/alter the generated client-side RelayR library before it gets to the browser.

Functions

func DisableScriptCache

func DisableScriptCache()

DisableScriptCache forces the RelayR client-side script to be regenerated on each request, rather than serving it from an internal cache.

Types

type ClientOperations

type ClientOperations struct {
	// contains filtered or unexported fields
}

ClientOperations provides helper methods for interacting with Clients connected to a Relay.

func (*ClientOperations) All

func (c *ClientOperations) All(fn string, args ...interface{})

All invokes a client side method on all clients for the given relay.

func (*ClientOperations) Others

func (c *ClientOperations) Others(fn string, args ...interface{})

Others invokes a client side method on all clients except the one who calls it.

type Exchange

type Exchange struct {
	// contains filtered or unexported fields
}

Exchange represents a hub where clients exchange information via Relays. Relays registered with the Exchange expose methods that can be invoked by clients.

func NewExchange

func NewExchange() *Exchange

NewExchange initializes and returns a new Exchange

func (*Exchange) RegisterRelay

func (e *Exchange) RegisterRelay(x interface{})

RegisterRelay registers a struct as a Relay with the Exchange. This allows clients to invoke server methods on a Relay and allows the Exchange to invoke methods on a Relay on the server side.

func (*Exchange) Relay

func (e *Exchange) Relay(x interface{}) *Relay

Relay generates an instance of a Relay, allowing calls to be made to it on the server side. It is generated a random ConnectionID for the duration of the call and it does not represent an actual client.

func (*Exchange) ServeHTTP

func (e *Exchange) ServeHTTP(w http.ResponseWriter, r *http.Request)

type GroupOperations

type GroupOperations struct {
	// contains filtered or unexported fields
}

GroupOperations provides helper methods for communicating with clients in groups. Clients must be added to a group to be considered a member of a group.

func (*GroupOperations) Add

func (g *GroupOperations) Add(connectionID string)

Add adds a client to a group via its ConnectionID. It is a member of the group for the remainder of its connection. At that point, the client must re-negotiate its place within the group to be considered a member of it.

func (*GroupOperations) Call

func (g *GroupOperations) Call(fn string, args ...interface{})

Call invokes a client-side method across a Group of clients, passing args to them.

func (*GroupOperations) Remove

func (g *GroupOperations) Remove(connectionID string)

Remove removes a client from a group via its ConnectionID.

type Relay

type Relay struct {
	Name         string            // The name of the relay it is associated with
	ConnectionID string            // The connectionID of the client that this Relay interacts with
	Clients      *ClientOperations // An abstraction over clients currently connected to this Relay
	// contains filtered or unexported fields
}

Relay encapsulates a connection with a client during an interaction with the server. It provides methods for interacting with clients and groups.

func (*Relay) Call

func (r *Relay) Call(fn string, args ...interface{})

Call will execute a function on another server-side Relay, passing along the details of the currently connected client.

func (*Relay) Groups

func (r *Relay) Groups(group string) *GroupOperations

Groups returns a GroupOperations object, which offers helper methods for communicating with and grouping clients.

type Transport

type Transport interface {
	CallClientFunction(relay *Relay, fn string, args ...interface{})
}

Transport represents a communication mechanism between a Relay and a client.