herald

README

go-herald

go-herald provides a very simple way for clients to exchange messages with a central server using WebSockets.

Basic Usage

Begin by importing the package with:

import "github.com/nathan-osman/go-herald"

Next, create an instance of the Herald class and start it with:

herald := herald.New()
herald.Start()

When a WebSocket connection is received, call the AddClient method:

func someHandler(w http.ResponseWriter, r *http.Request) {
    herald.AddClient(w, r, nil)
}

The third parameter to AddClient is an interface{} that can be used to associate custom data with that particular client.

To send messages to the clients, prepare them with the NewMessage function and pass them to the Herald's Send method:

msg, err := herald.NewMessage("test", "data")
// TODO: handle err
herald.Send(msg, nil)

The second parameter is a list of clients to send the message to. Passing nil means send the message to all clients.

A JavaScript client for the above example might look something like the following:

let ws = new WebSocket("ws://server/ws");

ws.send(
  JSON.stringify(
    { type: "test", data: "data" }
  )
);

By default, messages received by the Herald are simply rebroadcast to all other connected clients.

To shutdown the Herald, use the Close() method. It will block until all of the connected clients have been disconnected.

herald.Close()

Documentation

Index

• type Client
  • func (c *Client) Close()
  • func (c *Client) Wait()
• type Herald
  • func New() *Herald
  • func (h *Herald) AddClient(w http.ResponseWriter, r *http.Request, data interface{}) (*Client, error)
  • func (h *Herald) Clients() []*Client
  • func (h *Herald) Close()
  • func (h *Herald) Send(message *Message, clients []*Client)
  • func (h *Herald) SetCheckOrigin(fn func(*http.Request) bool)
  • func (h *Herald) Start()
• type Message
  • func NewMessage(messageType string, v interface{}) (*Message, error)

Types

type Client

type Client struct {
	Data interface{}
	// contains filtered or unexported fields
}

Client maintains information about an active client.

func (*Client) Close

func (c *Client) Close()

Close disconnects the client. To ensure the client has completely shut down, use the Wait() method.

func (*Client) Wait

func (c *Client) Wait()

Wait waits for the client goroutines to shut down.

type Herald

type Herald struct {

	// MessageHandler processes messages as they are coming in. If nil,
	// messages will simply be re-broadcast to all clients.
	MessageHandler func(message *Message, client *Client)

	// ClientAddedHandler processes new clients after they connect. This field
	// is optional.
	ClientAddedHandler func(client *Client)

	// ClientRemovedHandler processes clients after they disconnect. This field
	// is optional.
	ClientRemovedHandler func(client *Client)
	// contains filtered or unexported fields
}

Herald maintains a set of WebSocket connections and facilitates the exchange of messages between them.

func New

func New() *Herald

New creates and begins initializing a new Herald instance. The Herald is not started until the Start() method is invoked.

func (*Herald) AddClient

func (h *Herald) AddClient(w http.ResponseWriter, r *http.Request, data interface{}) (*Client, error)

AddClient adds a new WebSocket client and begins exchanging messages.

func (*Herald) Clients

func (h *Herald) Clients() []*Client

Clients returns a slice of all currently connected clients.

func (*Herald) Close

func (h *Herald) Close()

Close disconnects all clients and stops exchanging messages.

func (*Herald) Send

func (h *Herald) Send(message *Message, clients []*Client)

Send sends the specified message to the client specified in the message or all clients if nil. The send operation takes place in a separate goroutine to enable the call to be made from handlers without triggering a deadlock.

func (*Herald) SetCheckOrigin

func (h *Herald) SetCheckOrigin(fn func(*http.Request) bool)

SetCheckOrigin provides a function that will be invoked for every new connection. If the function returns true, it will be allowed.

func (*Herald) Start

func (h *Herald) Start()

Start completes initialization and begins processing messages.

type Message

type Message struct {
	Type string          `json:"type"`
	Data json.RawMessage `json:"data"`
}

Message stores information for broadcasting to other clients. The Client field is a pointer to either the client who sent the message or the one that should receive it.

func NewMessage

func NewMessage(messageType string, v interface{}) (*Message, error)

NewMessage creates a new Message instance of the specified type with the specified data.