wsrooms

README

wsrooms

A Gorilla WebSocket implementation with support for rooms.

Installation

go get -u github.com/joncody/wsrooms

Browser API

• wsrooms
• Room
  • on
  • name
  • open
  • members
  • id
  • send
  • join
  • leave
  • parse
  • purge
  • rooms

wsrooms(url) -> {Room}

Connects to a wsrooms WebSocket server and returns the root Room.

Parameters

Name	Type	Description
url	String	The WebSocket URL to connect to.

Room

A wsrooms communication channel.

Properties

name -> {String}

The Room name.

Methods

on(event, executable)

Adds an event listener to the Room.

Parameters

Name	Type	Description
event	String	The event to listen for.
executable	Function	The callback to run.

open() -> {Boolean}

Gets the Room connection status.

members() -> {Array}

Gets the Room members (a list of their uuids).

id() -> {String}

Gets the local WebSocket connection uuid.

send(event, payload, dst)

Sends a message to the server.

Parameters

Name	Type	Description
event	String	The name of the event.
payload	Any	The message data.
dst	String (optional, default: "")	The destination uuid.

join(roomname) -> {Room}

Joins a Room. If the Room does not exist, it is created.

Parameters

Name	Type	Description
roomname	String	The name of the room.

leave()

Leaves the Room.

parse(packet)

Handles received messages after they have been converted to an object. The Room emits the event, payload, and source of the message if the event name is not reserved.

Parameters

Name	Type	Description
packet	Object	The message adhering to the wsrooms protocol.

purge() *root room only

Leaves all Rooms other than the root Room.

rooms() *root room only

Returns all currently joined rooms.

Events

Name	Parameters	Description
open		Fired when the Room has been successfully joined.
joined	id (String)	Fired when another connection is made to the Room.
left	id (String)	Fired when another member disconnects from the Room.
close		Fired when the Room has been successfully left.

Documentation

Index

• Variables
• func HandleData(c *Conn, msg *Message)
• func SocketHandler(cr CookieReader) http.HandlerFunc
• type Conn
  • func NewConnection(w http.ResponseWriter, r *http.Request, cr CookieReader) *Conn
  • func (c *Conn) Emit(msg *Message)
  • func (c *Conn) Join(name string)
  • func (c *Conn) Leave(name string)
  • func (c *Conn) ReadPump()
  • func (c *Conn) WritePump()
• type CookieReader
• type Message
  • func BytesToMessage(data []byte) *Message
  • func ConstructMessage(room, event, dst, src string, payload []byte) *Message
  • func (msg *Message) Bytes() []byte
• type Room
  • func NewRoom(name string) *Room
  • func (r *Room) Emit(c *Conn, msg *Message)
  • func (r *Room) Join(c *Conn)
  • func (r *Room) Leave(c *Conn)
  • func (r *Room) Start()
  • func (r *Room) Stop()
• type RoomMessage

Variables

var (
	// ConnManager stores all Conn types by their uuid
	ConnManager = struct {
		Conns *sync.Map
	}{
		Conns: new(sync.Map),
	}
	// Emitter emits received Messages with non-reserved event names
	Emitter = emission.NewEmitter()
)

var RoomManager = struct {
	Rooms *sync.Map
}{
	Rooms: new(sync.Map),
}

RoomManager stores all Room types by their name

Functions

func HandleData

func HandleData(c *Conn, msg *Message)

HandleData handles incoming, error free messages

func SocketHandler

func SocketHandler(cr CookieReader) http.HandlerFunc

SocketHandler calls NewConnection, starts the returned Conn's writer, joins the root room, and finally starts the Conn's reader

Types

type Conn

type Conn struct {
	Cookie *sync.Map
	Socket *websocket.Conn
	ID     string
	Send   chan []byte
	Rooms  *sync.Map
}

Conn type represents a single client

func NewConnection

func NewConnection(w http.ResponseWriter, r *http.Request, cr CookieReader) *Conn

NewConnection upgrades an HTTP connection and creates a new Conn type

func (*Conn) Emit

func (c *Conn) Emit(msg *Message)

Emit broadcasts a Message to all members of a Room

func (*Conn) Join

func (c *Conn) Join(name string)

Join adds the Conn to a Room. If the Room does not exist, it is created

func (*Conn) Leave

func (c *Conn) Leave(name string)

Leave removes the Conn from a Room

func (*Conn) ReadPump

func (c *Conn) ReadPump()

ReadPump is loop for reading

func (*Conn) WritePump

func (c *Conn) WritePump()

WritePump is loop for writing

type CookieReader

type CookieReader func(*http.Request) *sync.Map

CookieReader reads cookie

type Message

type Message struct {
	RoomLength    int    `json:"roomLength"`    // room name length
	Room          string `json:"room"`          // room name
	EventLength   int    `json:"eventLength"`   // event name length
	Event         string `json:"event"`         // event name
	DstLength     int    `json:"dstLength"`     // destination id length
	Dst           string `json:"dst"`           // destination id
	SrcLength     int    `json:"srcLength"`     // source id length
	Src           string `json:"src"`           // source id
	PayloadLength int    `json:"payloadLength"` // payload length
	Payload       []byte `json:"payload"`       // payload
}

Message protocol followed by wsrooms servers and clients

func BytesToMessage

func BytesToMessage(data []byte) *Message

BytesToMessage returns a Message type from bytes

func ConstructMessage

func ConstructMessage(room, event, dst, src string, payload []byte) *Message

ConstructMessage constructs and returns a new Message type

func (*Message) Bytes

func (msg *Message) Bytes() []byte

Bytes returns bytes from a Message type

type Room

type Room struct {
	Name    string
	Members *sync.Map

	Send chan *RoomMessage
	// contains filtered or unexported fields
}

Room type represents a communication channel

func NewRoom

func NewRoom(name string) *Room

NewRoom creates a new Room type and starts it

func (*Room) Emit

func (r *Room) Emit(c *Conn, msg *Message)

Emit broadcasts data to all members of the Room

func (*Room) Join

func (r *Room) Join(c *Conn)

Join adds a Conn to the Room

func (*Room) Leave

func (r *Room) Leave(c *Conn)

Leave removes a Conn from the Room

func (*Room) Start

func (r *Room) Start()

Start starts the Room

func (*Room) Stop

func (r *Room) Stop()

Stop stops the Room

type RoomMessage

type RoomMessage struct {
	Sender *Conn
	Data   []byte
}

RoomMessage used only with a room's Send channel