wsconn

Documentation

Overview

Wraps a server-side websocket connection with its own human-readable unique ID. This helps to clearly map log debug and error messages to their respective websocket connections, thus keeping them clearly separated. Additionally, we also associate the capturing process (if any) with this connection, so we can sanely manage it.

Index

• Constants
• type WSConn
  • func NewWSConn(w http.ResponseWriter, req *http.Request) (*WSConn, error)
  • func (c *WSConn) Debugf(format string, args ...interface{})
  • func (c *WSConn) Errorf(format string, args ...interface{})
  • func (c *WSConn) GracefullyClose(code int, reason string)
  • func (c *WSConn) InitiateGracefulClose(code int, reason string)
  • func (c *WSConn) Watch()
• type WSConnState

Constants

const ClosingDeadline = 5 * time.Second

ClosingDeadline specifies the maximum amount of time to wait for a full (opt. graceful) closing procedure to take.

Types

type WSConn

type WSConn struct {
	*websocket.Conn        // usual (gorilla) websocket connection.
	ID              string // unique ID string for this connection.
	// contains filtered or unexported fields
}

WSConn is a websocket connection with a unique, human-friendly ID. This allows differentiating multiple (concurrent) websocket connections in the logs.

func NewWSConn

func NewWSConn(w http.ResponseWriter, req *http.Request) (*WSConn, error)

NewWSConn returns a new websocket connection wrapper that features an additional ID, so multiple (concurrent) websocket connections can still be differentiated in the logs.

func (*WSConn) Debugf

func (c *WSConn) Debugf(format string, args ...interface{})

Debugf logs a formatted debug message, prefixed by the connection ID.

func (*WSConn) Errorf

func (c *WSConn) Errorf(format string, args ...interface{})

Errorf logs a formatted error message, prefixed by the connection ID.

func (*WSConn) GracefullyClose

func (c *WSConn) GracefullyClose(code int, reason string)

GracefullyClose runs a complete graceful close handshake and only returns after this has completed or completely failed. Use this convenience method when there is yet no process to also wait for or to terminate. Otherwise, use asynchronous InitiateGracefulClose because there's already a Watch() on this websocket as well as a Wait() on the capture process running in parallel.

func (*WSConn) InitiateGracefulClose

func (c *WSConn) InitiateGracefulClose(code int, reason string)

InitiateGracefulClose initiates a graceful close handshake. It immediately returns after kicking off the close procedure. This will then cause the websocket reader to finish the closing handshake and finally terminating the capture process. If there is a problem to initiate the closing procedure, then the websocket will be closed immediately and the capture process terminated.

func (*WSConn) Watch

func (c *WSConn) Watch()

Watch watches the websocket connection for any signs of closing or failure. Additionally, it also handles acknowledging a graceful shutdown or receiving a client's graceful acknowledge.

type WSConnState

type WSConnState int

WSConnState ...

const (
	// WSConnOpen declares the websocket connection being still open.
	WSConnOpen WSConnState = iota
	// WSConnClosing declares the websocket connection being in the handshake
	// for a graceful close.
	WSConnClosing
	// WSConnClosed declares the websocket connection being closed.
	WSConnClosed
)