websockets

Documentation

Index

• Constants
• Variables
• func DisableLog()
• func Read(c *websocket.Conn) (string, string, interface{}, error)
• func SubsciptionReqAuth(cmd string) bool
• func UseLogger(logger slog.Logger)
• func ValidSubscription(cmd string) bool
• func WSJSON(cmd, id string, payload interface{}) ([][]byte, error)
• func Write(c *websocket.Conn, cmd, id string, payload interface{}) error
• type Manager
  • func NewManager(readLimit int64) *Manager
  • func (m *Manager) HandleWebsocket(w http.ResponseWriter, r *http.Request, id string)
• type WSError
• type WSHeader
• type WSPing
• type WSSubscribe

Constants

const (
	WSCError     = "error"
	WSCPing      = "ping"
	WSCSubscribe = "subscribe"
)

Websocket commands

Variables

var (
	// ErrInvalidWSCommand is returned when an invalid command is attempted to be
	// written to a websocket connection or when an invalid message or command is
	// read from a websocket connection.
	ErrInvalidWSCommand = errors.New("invalid webssocket command")
)

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func Read

func Read(c *websocket.Conn) (string, string, interface{}, error)

Read reads a command from the websocket connection. Reads are performed in two steps. First, a WSHeader is read from the connection. If a valid header is found then the command payload is read and returned.

func SubsciptionReqAuth

func SubsciptionReqAuth(cmd string) bool

SubscriptionReqAuth returns whether the command requires the client to be authenticated.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using slog.

func ValidSubscription

func ValidSubscription(cmd string) bool

ValidSubcription returns whether the command is a valid client subscription.

func WSJSON

func WSJSON(cmd, id string, payload interface{}) ([][]byte, error)

WSJSON returns the JSON representation of a wire command. This function must always match WSWrite.

func Write

func Write(c *websocket.Conn, cmd, id string, payload interface{}) error

Write writes a command to the websocket connection. A WSHeader is written to the connection prior to sending the command payload.

Types

type Manager

type Manager struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Manager provides an API for managing websocket connections.

NOTE: this memory store needs to be replaced by a data store that allows for horizontal scaling.

func NewManager

func NewManager(readLimit int64) *Manager

NewManager returns a new websocket Manager.

func (*Manager) HandleWebsocket

func (m *Manager) HandleWebsocket(w http.ResponseWriter, r *http.Request, id string)

HandleWebsocket upgrades a regular HTTP connection to a websocket.

type WSError

type WSError struct {
	Command string   `json:"command,omitempty"` // Command from client
	ID      string   `json:"id,omitempty"`      // Client set client id
	Errors  []string `json:"errors"`            // Errors returned by server
}

WSError is a generic websocket error. It returns in ID the client side id and all errors it encountered in Errors.

type WSHeader

type WSHeader struct {
	Command string `json:"command"`      // Following command
	ID      string `json:"id,omitempty"` // Client setable client id
}

WSHeader is required to be sent before any other command. The point is to make decoding easier without too much magic. E.g. a ping command WSHeader<ping>WSPing<timestamp>

type WSPing

type WSPing struct {
	Timestamp int64 `json:"timestamp"` // Server side timestamp
}

WSPing is a server side push to the client to see if it is still alive.

type WSSubscribe

type WSSubscribe struct {
	RPCS []string `json:"rpcs"` // Commands that the client wants to subscribe to
}

WSSubscribe is a client side push to tell the server what RPCs it wishes to subscribe to.