websocket_client

README

wsclient

wsclient is a client library which implements a subset of the Iris websocket server interface. wsclient provides a wrapper of the (gorilla websocket Dialer)[https://godoc.org/github.com/gorilla/websocket#Dialer] interface to initiate client connections. Once this connection is established, the client interface follows the Iris server functions for On(), OnMessage(), Emit() and EmitMessage().

wsclient does not (yet) implement Joining/Leaving rooms.

Documentation

Overview

Note: with the exclusion of the package name the message protocol logic is a verbatim copy of iris/websocket/message.go

Index

• type ClientConnection
• type ConnectCallback
• type WSDialer
  • func (wsd *WSDialer) Dial(urlStr string, requestHeader http.Header, config iwebsocket.Config) (ClientConnection, *http.Response, error)
• type WSHandler
  • func (wsh *WSHandler) HandleRequest(w http.ResponseWriter, r *http.Request)
  • func (wsh *WSHandler) OnConnect(cb ConnectCallback)

Types

type ClientConnection

type ClientConnection interface {
	// EmitMessage sends a native websocket message
	EmitMessage([]byte) error
	// Emit sends a message on a particular event
	Emit(string, interface{}) error

	// OnDisconnect registers a callback which fires when this connection is closed by an error or manual
	OnDisconnect(iwebsocket.DisconnectFunc)

	// OnMessage registers a callback which fires when native websocket message received
	OnMessage(iwebsocket.NativeMessageFunc)
	// On registers a callback to a particular event which fires when a message to this event received
	On(string, iwebsocket.MessageFunc)
	// Disconnect disconnects the client, close the underline websocket conn and removes it from the conn list
	// returns the error, if any, from the underline connection
	Disconnect() error
}

ClientConnection defines proper subset of Connection interface which is satisfied by Client

type ConnectCallback

type ConnectCallback func(cc ClientConnection)

type WSDialer

type WSDialer struct {
	// NetDial specifies the dial function for creating TCP connections. If
	// NetDial is nil, net.Dial is used.
	NetDial func(network, addr string) (net.Conn, error)

	// Proxy specifies a function to return a proxy for a given
	// Request. If the function returns a non-nil error, the
	// request is aborted with the provided error.
	// If Proxy is nil or returns a nil *URL, no proxy is used.
	Proxy func(*http.Request) (*url.URL, error)

	// TLSClientConfig specifies the TLS configuration to use with tls.Client.
	// If nil, the default configuration is used.
	TLSClientConfig *tls.Config

	// HandshakeTimeout specifies the duration for the handshake to complete.
	HandshakeTimeout time.Duration

	// ReadBufferSize and WriteBufferSize specify I/O buffer sizes. If a buffer
	// size is zero, then a useful default size is used. The I/O buffer sizes
	// do not limit the size of the messages that can be sent or received.
	ReadBufferSize, WriteBufferSize int

	// Subprotocols specifies the client's requested subprotocols.
	Subprotocols []string

	// EnableCompression specifies if the client should attempt to negotiate
	// per message compression (RFC 7692). Setting this value to true does not
	// guarantee that compression will be supported. Currently only "no context
	// takeover" modes are supported.
	EnableCompression bool

	// Jar specifies the cookie jar.
	// If Jar is nil, cookies are not sent in requests and ignored
	// in responses.
	Jar http.CookieJar
	// contains filtered or unexported fields
}

WSDialer here is a wrapper around the gorilla.websocket.Dialer which returns a wsclient.Client instead of the gorilla Connection on Dial()

func (*WSDialer) Dial

func (wsd *WSDialer) Dial(urlStr string, requestHeader http.Header, config iwebsocket.Config) (ClientConnection, *http.Response, error)

Dial initiates a connection to a remote Iris server websocket listener using the gorilla websocket Dialer and returns a Client connection which can be used to emit and handle messages

type WSHandler

type WSHandler struct {
	// HandshakeTimeout specifies the duration for the handshake to complete.
	HandshakeTimeout time.Duration

	// ReadBufferSize and WriteBufferSize specify I/O buffer sizes. If a buffer
	// size is zero, then buffers allocated by the HTTP server are used. The
	// I/O buffer sizes do not limit the size of the messages that can be sent
	// or received.
	ReadBufferSize, WriteBufferSize int

	// Subprotocols specifies the server's supported protocols in order of
	// preference. If this field is set, then the Upgrade method negotiates a
	// subprotocol by selecting the first match in this list with a protocol
	// requested by the client.
	Subprotocols []string

	// Error specifies the function for generating HTTP error responses. If Error
	// is nil, then http.Error is used to generate the HTTP response.
	Error func(w http.ResponseWriter, r *http.Request, status int, reason error)

	// CheckOrigin returns true if the request Origin header is acceptable. If
	// CheckOrigin is nil, the host in the Origin header must not be set or
	// must match the host of the request.
	CheckOrigin func(r *http.Request) bool

	// EnableCompression specify if the server should attempt to negotiate per
	// message compression (RFC 7692). Setting this value to true does not
	// guarantee that compression will be supported. Currently only "no context
	// takeover" modes are supported.
	EnableCompression bool

	Config iwebsocket.Config
	// contains filtered or unexported fields
}

WSHandler is mostly a wrapper around Gorilla's websocket.Upgrader component Generally any framework can use this handler to upgrade and manage a websocket connection

func (*WSHandler) HandleRequest

func (wsh *WSHandler) HandleRequest(w http.ResponseWriter, r *http.Request)

func (*WSHandler) OnConnect

func (wsh *WSHandler) OnConnect(cb ConnectCallback)

OnConnect registers a callback function which is called after an incoming HTTP(S) request is upgraded to enable Websocket traffic and before message traffic handling (send/receive) starts. The