ss

README

Sacrificial-Socket

A Go server library and pure JS client library for managing communication between websockets, that has an API similar to Socket.IO, but feels less... well, Javascripty. Socket.IO is great, but nowadays all modern browsers support websockets natively, so in most cases there is no need to have websocket simulation fallbacks like XHR long polling or Flash. Removing these allows Sacrificial-Socket to be lightweight and very performant.

Sacrificial-Socket supports rooms, roomcasts, broadcasts, and event emitting just like Socket.IO, but with one key difference. The data passed into event functions is not an interface{} that is implied to be a string or map[string]interface{}, but is always passed in as a []byte making it easier to unmarshal into your own JSON data structs, convert to a string, or keep as binary data without the need to check the data's type before processing it. It also means there aren't any unnecessary conversions to the data between the client and the server.

Sacrificial-Socket also has a MultihomeBackend interface for syncronizing broadcasts and roomcasts across multiple instances of Sacrificial-Socket running on multiple machines. Out of the box Sacrificial-Socket provides a MultihomeBackend interface for the popular noSQL database MongoDB, one for the moderately popular key/value storage engine Redis, and one for the not so popular GRPC protocol, for syncronizing instances on multiple machines.

In depth examples can be found in the examples directory.

Usage

Client Javascript:

(function(SS){ 'use strict';
    var ss = new SS('ws://localhost:8080/socket');
    ss.onConnect(function(){
        ss.emit('echo', 'hello echo!');
    });
    
    ss.on('echo', function(data){
        alert('got echo:', data);
        ss.close();
    });
    
    ss.onDisconnect(function(){
        console.log('socket connection closed');
    });
})(window.SS);

Server Go:

package main

import(
    "net/http"
    ss "github.com/raz-varren/sacrificial-socket"
)

func doEcho(s *ss.Socket, data []byte) {
    s.Emit("echo", string(data))
}

func main() {
    s := ss.NewServer()
    s.On("echo", doEcho)
    
    http.Handle("/socket", s)
    http.ListenAndServe(":8080", nil);
}

Documentation

Overview

Package ss (Sacrificial-Socket) is a Go server library and pure JS client library for managing communication between websockets, that has an API similar to Socket.IO, but feels less... well, Javascripty. Socket.IO is great, but nowadays all modern browsers support websockets natively, so in most cases there is no need to have websocket simulation fallbacks like XHR long polling or Flash. Removing these allows Sacrificial-Socket to be lightweight and very performant.

Sacrificial-Socket supports rooms, roomcasts, broadcasts, and event emitting just like Socket.IO, but with one key difference. The data passed into event functions is not an interface{} that is implied to be a string or map[string]interface{}, but is always passed in as a []byte making it easier to unmarshal into your own JSON data structs, convert to a string, or keep as binary data without the need to check the data's type before processing it. It also means there aren't any unnecessary conversions to the data between the client and the server.

Sacrificial-Socket also has a MultihomeBackend interface for syncronizing broadcasts and roomcasts across multiple instances of Sacrificial-Socket running on multiple machines. Out of the box Sacrificial-Socket provides a MultihomeBackend interface for the popular noSQL database MongoDB, one for the moderately popular key/value storage engine Redis, and one for the not so popular GRPC protocol, for syncronizing instances on multiple machines.

Index

• Constants
• func DefaultUpgrader() *websocket.Upgrader
• type BroadcastMsg
• type EventHandler
• type RNG
  • func NewRNG() *RNG
  • func (r *RNG) Read(b []byte) (int, error)
• type RoomMsg
• type Socket
  • func (s *Socket) Broadcast(eventName string, data interface{})
  • func (s *Socket) Close()
  • func (s *Socket) Emit(eventName string, data interface{}) error
  • func (s *Socket) GetRooms() []string
  • func (s *Socket) ID() string
  • func (s *Socket) InRoom(roomName string) bool
  • func (s *Socket) Join(roomName string)
  • func (s *Socket) Leave(roomName string)
  • func (s *Socket) Roomcast(roomName, eventName string, data interface{})
• type SocketServer
  • func NewServer() *SocketServer
  • func (serv *SocketServer) Broadcast(eventName string, data interface{})
  • func (serv *SocketServer) EnableSignalShutdown(complete chan<- bool)
  • func (serv *SocketServer) On(eventName string, handleFunc func(*Socket, []byte))
  • func (serv *SocketServer) OnConnect(handleFunc func(*Socket))
  • func (serv *SocketServer) OnDisconnect(handleFunc func(*Socket))
  • func (serv *SocketServer) OnEvent(h EventHandler)
  • func (serv *SocketServer) Roomcast(roomName, eventName string, data interface{})
  • func (serv *SocketServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (serv *SocketServer) SetUpgrader(u *websocket.Upgrader)
  • func (serv *SocketServer) Shutdown() bool
  • func (serv *SocketServer) WebHandler() http.Handler

Examples

• NewServer

Constants

const (

	//SubProtocol is the official sacrificial-socket sub protocol
	SubProtocol string = "sac-sock"
)

Functions

func DefaultUpgrader

func DefaultUpgrader() *websocket.Upgrader

DefaultUpgrader returns a websocket upgrader suitable for creating sacrificial-socket websockets.

Types

type BroadcastMsg

type BroadcastMsg struct {
	EventName      string
	Data           interface{}
	SocketOriginID string
}

BroadcastMsg represents an event to be dispatched to all Sockets on the SocketServer

type EventHandler

type EventHandler interface {
	HandleEvent(*Socket, []byte)
	EventName() string
}

EventHandler is an interface for registering events using SockerServer.OnEvent

type RNG

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

RNG is a random number generator that is safe for concurrent use by multiple go routines

func NewRNG

func NewRNG() *RNG

NewRNG creates a new random number generator

func (*RNG) Read

func (r *RNG) Read(b []byte) (int, error)

Read reads len(b) random bytes into b and always returns a nil error

type RoomMsg

type RoomMsg struct {
	RoomName       string
	EventName      string
	Data           interface{}
	SocketOriginID string
}

RoomMsg represents an event to be dispatched to a room of sockets

type Socket

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

Socket represents a websocket connection

func (*Socket) Broadcast

func (s *Socket) Broadcast(eventName string, data interface{})

Broadcast dispatches an event to all Sockets on the SocketServer.

func (*Socket) Close

func (s *Socket) Close()

Close closes the Socket connection and removes the Socket from any rooms that it was a member of

func (*Socket) Emit

func (s *Socket) Emit(eventName string, data interface{}) error

Emit dispatches an event to s.

func (*Socket) GetRooms

func (s *Socket) GetRooms() []string

GetRooms returns a list of rooms that s is a member of

func (*Socket) ID

func (s *Socket) ID() string

ID returns the unique ID of s

func (*Socket) InRoom

func (s *Socket) InRoom(roomName string) bool

InRoom returns true if s is currently a member of roomName

func (*Socket) Join

func (s *Socket) Join(roomName string)

Join adds s to the specified room. If the room does not exist, it will be created

func (*Socket) Leave

func (s *Socket) Leave(roomName string)

Leave removes s from the specified room. If s is not a member of the room, nothing will happen. If the room is empty upon removal of s, the room will be closed

func (*Socket) Roomcast

func (s *Socket) Roomcast(roomName, eventName string, data interface{})

Roomcast dispatches an event to all Sockets in the specified room.

type SocketServer

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

SocketServer manages the coordination between sockets, rooms, events and the socket hub

func NewServer

func NewServer() *SocketServer

NewServer creates a new instance of SocketServer

Example

package main

import (
	"encoding/json"
	"github.com/raz-varren/sacrificial-socket"
	"log"
	"net/http"
	"os"
)

func main() {
	serv := ss.NewServer()
	serv.On("echo", Echo)
	serv.On("join", Join)
	serv.On("leave", Leave)
	serv.On("roomcast", Roomcast)
	serv.On("broadcast", Broadcast)

	done := make(chan bool)

	go func() {
		serv.EnableSignalShutdown(done)
		<-done
		os.Exit(0)
	}()

	http.Handle("/socket", s)
	log.Fatalln(http.ListenAndServe(":8080", nil))
}

type JoinJSON struct {
	Room string
}

type LeaveJSON struct {
	Room string
}

type RoomcastJSON struct {
	Room, Event, Data string
}

type BroadcastJSON struct {
	Event, Data string
}

func Echo(s *ss.Socket, data []byte) {
	s.Emit("echo", string(data))
}

func Join(s *ss.Socket, data []byte) {
	var j JoinJSON
	err := json.Unmarshal(data, &j)
	check(err)

	s.Join(j.Room)
	s.Emit("echo", "joined: "+j.Room)
}

func Leave(s *ss.Socket, data []byte) {
	var l LeaveJSON
	err := json.Unmarshal(data, &l)
	check(err)

	s.Leave(l.Room)
	s.Emit("echo", "left: "+l.Room)
}

func Broadcast(s *ss.Socket, data []byte) {
	var b BroadcastJSON
	err := json.Unmarshal(data, &b)
	check(err)

	s.Broadcast(b.Event, b.Data)
}

func Roomcast(s *ss.Socket, data []byte) {
	var r RoomcastJSON
	err := json.Unmarshal(data, &r)
	check(err)

	s.Roomcast(r.Room, r.Event, r.Data)
}

func check(err error) {
	if err != nil {
		log.Fatalln(err)
	}
}

func (*SocketServer) Broadcast

func (serv *SocketServer) Broadcast(eventName string, data interface{})

Broadcast dispatches an event to all Sockets on the SocketServer.

func (*SocketServer) EnableSignalShutdown

func (serv *SocketServer) EnableSignalShutdown(complete chan<- bool)

EnableSignalShutdown listens for linux syscalls SIGHUP, SIGINT, SIGTERM, SIGQUIT, SIGKILL and calls the SocketServer.Shutdown() to perform a clean shutdown. true will be passed into complete after the Shutdown proccess is finished

func (*SocketServer) On

func (serv *SocketServer) On(eventName string, handleFunc func(*Socket, []byte))

On registers event functions to be called on individual Socket connections when the server's socket receives an Emit from the client's socket.

Any event functions registered with On, must be safe for concurrent use by multiple go routines

func (*SocketServer) OnConnect

func (serv *SocketServer) OnConnect(handleFunc func(*Socket))

OnConnect registers an event function to be called whenever a new Socket connection is created

func (*SocketServer) OnDisconnect

func (serv *SocketServer) OnDisconnect(handleFunc func(*Socket))

OnDisconnect registers an event function to be called as soon as a Socket connection is closed

func (*SocketServer) OnEvent

func (serv *SocketServer) OnEvent(h EventHandler)

OnEvent has the same functionality as On, but accepts an EventHandler interface instead of a handler function.

func (*SocketServer) Roomcast

func (serv *SocketServer) Roomcast(roomName, eventName string, data interface{})

Roomcast dispatches an event to all Sockets in the specified room.

func (*SocketServer) ServeHTTP

func (serv *SocketServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP will upgrade a http request to a websocket using the sac-sock subprotocol

func (*SocketServer) SetUpgrader

func (serv *SocketServer) SetUpgrader(u *websocket.Upgrader)

SetUpgrader sets the websocket.Upgrader used by the SocketServer.

func (*SocketServer) Shutdown

func (serv *SocketServer) Shutdown() bool

Shutdown closes all active sockets and triggers the Shutdown() method on any MultihomeBackend that is currently set.

func (*SocketServer) WebHandler

func (serv *SocketServer) WebHandler() http.Handler

WebHandler returns a http.Handler to be passed into http.Handle

Depricated: The SocketServer struct now satisfies the http.Handler interface, use that instead