arbit

Documentation

Overview

Package arbit is a minimal event-driven, websocket library.

Message Format

Messages are formatted as 2-element JSON arrays: [eventName, messageData]. Therefore, the message data must be JSON-serializable.

Concurrency

All functions and methods in this package are safe for concurrent use, with the exception of the On and OnClose handlers. arbit handles the concurrency problems for you.

Example: As Server

arb := arbit.NewServer()

arb.On("echo", func(cl *arbit.Client, data interface{}) {
	cl.Send("echo", "Echo: " + fmt.Sprint(data))
})

http.Handle("/ws", srv)
http.ListenAndServe(":8080", nil)

Example: As Client

arb := arbit.NewClient("http://localhost:8080/ws", http.Header{})

arb.On("echo", func(data interface{}) {
	log.Println("Message: " + fmt.Sprint(data))
	arb.Close()
})
arb.Send("echo", "Hello world!")
arb.Listen()

Index

• func Broadcast(clients []*Client, event string, data interface{}) error
• type Client
  • func NewClient(url string, header http.Header) (*Client, error)
  • func (cl *Client) Close(code uint16) error
  • func (cl *Client) Listen() error
  • func (cl *Client) On(event string, handler func(data interface{}))
  • func (cl *Client) OnClose(event string, handler func(code int))
  • func (cl *Client) Send(event string, data interface{}) error
• type Server
  • func NewServer() *Server
  • func (s *Server) Clients() []*Client
  • func (s *Server) On(event string, handler func(cl *Client, data interface{}))
  • func (s *Server) OnClose(handler func(cl *Client, code int))
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Functions

func Broadcast

func Broadcast(clients []*Client, event string, data interface{}) error

Function Broadcast sends a message to multiple Clients.

Types

type Client

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

Type Client represents a websocket connection.

func NewClient

func NewClient(url string, header http.Header) (*Client, error)

Function NewClient creates a new Client from a given url.

func (*Client) Close

func (cl *Client) Close(code uint16) error

Method Close closes the connection with a given code. Codes 4000–4999 are available for use by applications.

See https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent for more information about close codes.

func (*Client) Listen

func (cl *Client) Listen() error

Method Listen starts the event loop that will call the event and close handlers.

func (*Client) On

func (cl *Client) On(event string, handler func(data interface{}))

Method On registers an event handler. Each event can have at most one handler.

The event handler will be executed in the goroutine that called Listen.

func (*Client) OnClose

func (cl *Client) OnClose(event string, handler func(code int))

Method OnClose registers a close handler, to be called when the connection is closed. Each Client can only have one close handler.

The close handler will be executed in the goroutine that called Listen.

func (*Client) Send

func (cl *Client) Send(event string, data interface{}) error

Method Send sends a message through the connection represented by the Client.

type Server

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

Type Server represents a server. It manages a set of websocket connections.

func NewServer

func NewServer() *Server

Function NewServer creates a new Server and returns it.

func (*Server) Clients

func (s *Server) Clients() []*Client

Method Clients returns a list of Clients that are currently connected to the server.

func (*Server) On

func (s *Server) On(event string, handler func(cl *Client, data interface{}))

Method On registers a handler for a given event. Each event can have at most one handler.

Calling On and OnClose on the given client will have no effect.

func (*Server) OnClose

func (s *Server) OnClose(handler func(cl *Client, code int))

Method OnClose registers a close handler, which is called when a connection is closed. There can be at most one close handler.

The code passed in is the code passed to Client.Close; see Client.Close for more information.

Calling On and OnClose on the given client will have no effect.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Method ServeHTTP satisfies the http.Handler interface. It will spawn a new goroutine for each websocket connection.