websocketRouter

Documentation

Index

• Constants
• Variables
• func NewConnection(uri string, headers map[string]string, readBufferSize, writeBufferSize int, ...) (c *websocket.Conn, err error)
• type SubProtoClient
  • func NewSubProtoClient(uri string, headers map[string]string, readBufferSize, writeBufferSize int, ...) (*SubProtoClient, error)
  • func (spc *SubProtoClient) AddSubProtocol(sub string) error
  • func (spc *SubProtoClient) Close() error
  • func (spc *SubProtoClient) CloseSubProtoConn(subProto string) error
  • func (spc *SubProtoClient) GetSubProtoConn(subProto string) (*SubProtoConn, error)
  • func (spc *SubProtoClient) Run() error
  • func (spc *SubProtoClient) Start() error
  • func (spc *SubProtoClient) SubProtocols() ([]string, error)
  • func (spc *SubProtoClient) WriteErrorMsg(err error) error
• type SubProtoConn
  • func (sc SubProtoConn) AddMessage(data json.RawMessage) error
  • func (sc *SubProtoConn) Close() error
  • func (sc *SubProtoConn) ReadJSON(obj interface{}) error
  • func (sc *SubProtoConn) SetTimeout(to time.Duration) error
  • func (sc *SubProtoConn) String() string
  • func (sc SubProtoConn) WriteJSON(obj interface{}) error
• type SubProtoServer
  • func NewSubProtoServer(w http.ResponseWriter, r *http.Request, readBufferSize, writeBufferSize int, ...) (*SubProtoServer, error)
  • func (ss *SubProtoServer) AddSubProtocol(subproto string) error
  • func (ss *SubProtoServer) Close() error
  • func (ss *SubProtoServer) GetDefaultMessageChan() (chan UnkProtoMsg, error)
  • func (ss *SubProtoServer) GetSubProtoConn(subProto string) (*SubProtoConn, error)
  • func (ss *SubProtoServer) Run() error
  • func (ss *SubProtoServer) Start() error
  • func (ss *SubProtoServer) SubProtocols() ([]string, error)
  • func (ss *SubProtoServer) WriteDefaultMessage(proto string, obj interface{}) error
  • func (ss *SubProtoServer) WriteErrorMsg(err error) error
• type SubProtocolsReq
• type SubProtocolsResp
• type UnkProtoMsg

Constants

const (
	SecWebsocketProtocol string = `Sec-Websocket-Protocol`
)

Variables

var (
	ErrInvalidTimeout = errors.New("Invalid timeout")
	ErrTimeout        = errors.New("Read timed out")
)

var (
	ErrSubProtocolsRequested = errors.New("No Subprotocols Requested")
	ErrSubProtoClosed        = errors.New("SubProtoConn closed")
	ErrSubProtoNotFound      = errors.New("Subprotocol not found")
	ErrServerClosed          = errors.New("SubProtoServer closed")
	ErrAlreadyRunning        = errors.New("Already Running")
	ACK_RESP                 = SubProtocolsResp{`ACK`}
	ERR_RESP                 = SubProtocolsResp{`ERROR`}
)

var (
	ErrZeroSubProtocols = errors.New("requested zero subprotocols")
)

Functions

func NewConnection

func NewConnection(uri string, headers map[string]string, readBufferSize, writeBufferSize int, enforceCert bool) (c *websocket.Conn, err error)

NewConnection will attempt to connect to a webserver endpoint and upgrade the connection to a websocket. Once a websocket connection has been established, it is up to the caller to negotiate subprotocol connections. The default subproto connection is established.

Types

type SubProtoClient

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

SubProtoClient is the main client object used to connect to a SubProtoServer and negotiate subproto connections.

func NewSubProtoClient

func NewSubProtoClient(uri string, headers map[string]string, readBufferSize, writeBufferSize int, enforceCert bool, subs []string, ol objlog.ObjLog) (*SubProtoClient, error)

NewSubProtoClient connects to a remote websocket and negotiates a routingWebsocket. A list of required websockets must be provided at the start.

func (*SubProtoClient) AddSubProtocol

func (spc *SubProtoClient) AddSubProtocol(sub string) error

AddSubProtocol adds another subprotocol to the client additional protocols can be added at any time so long as the client is active. Adding a subprotocol does not inform the other side of the fact

func (*SubProtoClient) Close

func (spc *SubProtoClient) Close() error

Close will terminate the subprotocol client and close all active subprotocol connections. Callers with handles on subprotocol connections will receive errors on read or write. Closing the parent connection will close the underlying socket, there is no guaruntee that any messages read or written asynchronously will be delivered intact.

func (*SubProtoClient) CloseSubProtoConn

func (spc *SubProtoClient) CloseSubProtoConn(subProto string) error

CloseSubProtoConn will close a subprotocol connection if it exists

if the connection does not exist we just return, no error

func (*SubProtoClient) GetSubProtoConn

func (spc *SubProtoClient) GetSubProtoConn(subProto string) (*SubProtoConn, error)

GetSubProtoConn will attempt to retrieve a previously negotiated subprotocol connection. If the subprotocol connection has not been negotiated, an ErrSubProtoNotFound error is returned.

func (*SubProtoClient) Run

func (spc *SubProtoClient) Run() error

Run fires up the main muxing routine and starts throwing messages to subprotocol connections. It waits for the subproto to complete.

func (*SubProtoClient) Start

func (spc *SubProtoClient) Start() error

Start fires up the main muxing routine and starts throwing messages to subprotocol conns. It waits for the routine to start, but will not block while servicing messages.

func (*SubProtoClient) SubProtocols

func (spc *SubProtoClient) SubProtocols() ([]string, error)

SubProtocols returns the negotiated and/or added subprotocols

func (*SubProtoClient) WriteErrorMsg

func (spc *SubProtoClient) WriteErrorMsg(err error) error

WriteErrorMessage sends an error down the default subproto connection.

type SubProtoConn

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

SubProtoConn implements a subprotcol over the main routing websocket. A subprotocol connection can be treated as an independent connection with asynchronous read and write.

func (SubProtoConn) AddMessage

func (sc SubProtoConn) AddMessage(data json.RawMessage) error

AddMessage is a convienence wrapper that allows for droping a raw JSON object onto the subprotocol connection. This API is primarily used for testing.

func (*SubProtoConn) Close

func (sc *SubProtoConn) Close() error

Close terminates the subprotocol connection and cleans up. Any outstanding messages on the subprotocol connection will still be written. Any unread messages will be discarded.

func (*SubProtoConn) ReadJSON

func (sc *SubProtoConn) ReadJSON(obj interface{}) error

ReadJSON will read a message off of a SubProtoConn and attempt to unmarshal it into the provided object. If the object is nil or the message cannot be unmarshalled an error is returned.

func (*SubProtoConn) SetTimeout

func (sc *SubProtoConn) SetTimeout(to time.Duration) error

SetTimeout sets the per message timeout on the Subprotocol connection. The timeout is adhered to for reads and writes and only ensures that a message can be placed on the message queue. A completed write does not mean the message made it all the way to the wire.

func (*SubProtoConn) String

func (sc *SubProtoConn) String() string

String implements the Stringer interface, essentially handing back the Subprotocol ID.

func (SubProtoConn) WriteJSON

func (sc SubProtoConn) WriteJSON(obj interface{}) error

WriteJSON will attempt to marshal the given object and write it to the subprotocol connection. If the object cannot be marshalled or if the subprotocol connection is down, an error is returned.

type SubProtoServer

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

SubProtoServer is the main routing system for use in handling new clients. A server is in charge of upgrading a websocket to a subprotocol websocket and routing messages to the appropriate subprotocon.

func NewSubProtoServer

func NewSubProtoServer(w http.ResponseWriter, r *http.Request, readBufferSize, writeBufferSize int, allowedOrigin string) (*SubProtoServer, error)

NewSubProtoServer upgrades a connection to a websocket and attempts to instantiate subprotocol routers. If no subprotocols are specified in the handshake NewSubProtoServer returns an error

func (*SubProtoServer) AddSubProtocol

func (ss *SubProtoServer) AddSubProtocol(subproto string) error

AddSubProtocol adds another subprotocol to our router these can be added at any time so long as the connection is active

func (*SubProtoServer) Close

func (ss *SubProtoServer) Close() error

Close closes the websocket connection and closes all the subproto connections subprotoconns can still retrieve data after a close

func (*SubProtoServer) GetDefaultMessageChan

func (ss *SubProtoServer) GetDefaultMessageChan() (chan UnkProtoMsg, error)

GetDefaultMessageChan gets direct access to the channel receiving default messages

func (*SubProtoServer) GetSubProtoConn

func (ss *SubProtoServer) GetSubProtoConn(subProto string) (*SubProtoConn, error)

GetSubProtoconn gets a subprotocol talker using the named subProto. If the named subProto is not found, ErrSubProtoNotFound is returned

func (*SubProtoServer) Run

func (ss *SubProtoServer) Run() error

Run fires up the main muxing routine and starts throwing messages to sub. This routine blocks.

func (*SubProtoServer) Start

func (ss *SubProtoServer) Start() error

Start fires up the main muxing routine and starts throwing messages to sub. This routine DOES NOT block.

func (*SubProtoServer) SubProtocols

func (ss *SubProtoServer) SubProtocols() ([]string, error)

SubProtocols returns the negotiated and/or added subprotocols

func (*SubProtoServer) WriteDefaultMessage

func (ss *SubProtoServer) WriteDefaultMessage(proto string, obj interface{}) error

WriteDefaultMessage sends an object down the default subproto connection.

func (*SubProtoServer) WriteErrorMsg

func (ss *SubProtoServer) WriteErrorMsg(err error) error

WriteErrorMsg sends an error message down the "erro" protocol channel

type SubProtocolsReq

type SubProtocolsReq struct {
	Subs []string //the string IDs of subprotocols to be used
}

SubProtocolsReq is used to request websocket subprotocol channels during intialization.

type SubProtocolsResp

type SubProtocolsResp struct {
	Resp string
}

SubProtocolsResp defines the structure that a websocket router uses when responding to a request to initalize subprotocols.

type UnkProtoMsg

type UnkProtoMsg struct {
	Type string
	Data json.RawMessage
}

UnkProtoMsg represents a subprotocol packet with an uknown type and unknown structure. This type is useful for handling erroneous messages.