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)
• 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 (
	// Stores all Conn types by their uuid.
	ConnManager = struct {
		sync.Mutex
		Conns map[string]*Conn
	}{
		Conns: make(map[string]*Conn),
	}
	// Emits received Messages with non-reserved event names.
	Emitter = emission.NewEmitter()
)

var RoomManager = struct {
	sync.Mutex
	Rooms map[string]*Room
}{
	Rooms: make(map[string]*Room, 0),
}

Stores all Room types by their name.

Functions

func HandleData

func HandleData(c *Conn, msg *Message)

Handles incoming, error free messages.

func SocketHandler

func SocketHandler(cr CookieReader) http.HandlerFunc

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 {
	sync.Mutex
	Cookie map[string]string
	Socket *websocket.Conn
	ID     string
	Send   chan []byte
	Rooms  map[string]string
}

The Conn type represents a single client.

func NewConnection

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

Upgrades an HTTP connection and creates a new Conn type.

func (*Conn) Emit

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

Broadcasts a Message to all members of a Room.

func (*Conn) Join

func (c *Conn) Join(name string)

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

func (*Conn) Leave

func (c *Conn) Leave(name string)

Removes the Conn from a Room.

type CookieReader

type CookieReader func(*http.Request) map[string]string

type Message

type Message struct {
	RoomLength    int    // room name length
	Room          string // room name
	EventLength   int    // event name length
	Event         string // event name
	DstLength     int    // destination id length
	Dst           string // destination id
	SrcLength     int    // source id length
	Src           string // source id
	PayloadLength int    // payload length
	Payload       []byte // payload
}

Message protocol followed by wsrooms servers and clients.

func BytesToMessage

func BytesToMessage(data []byte) *Message

Returns a Message type from bytes.

func ConstructMessage

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

Constructs and returns a new Message type.

func (*Message) Bytes

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

Returns bytes from a Message type.

type Room

type Room struct {
	sync.Mutex
	Name    string
	Members map[string]string

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

The Room type represents a communication channel.

func NewRoom

func NewRoom(name string) *Room

Creates a new Room type and starts it.

func (*Room) Emit

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

Broadcasts data to all members of the Room.

func (*Room) Join

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

Adds a Conn to the Room.

func (*Room) Leave

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

Removes a Conn from the Room.

func (*Room) Start

func (r *Room) Start()

Starts the Room.

func (*Room) Stop

func (r *Room) Stop()

Stops the Room.

type RoomMessage

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

Message protocol used only with a room's Send channel.