websocket

README

websocket

Opinionated wrapper around Gorilla Websocket that:

• Provides Connection for client and server that automatically:
  • Handles ping/pong, and resets ping schedule on read/write as necessary.
  • Handles close messages, and closes the connection.
  • Makes awaiting a connection-closure easy with a context, and close-reason with context-cause.
• Provides a Server[E] that maintains the set of active connections and their metadata (generic for customization).
• Provides a Dial function to get a connection to an endpoint as client.
• Provides a Client that handles reconnects.
• Provides Go typing for websocket message-types.
• Provides a Messenger interface for common client/connection message handling (read/write/close).

License

MIT, see LICENSE file.

Documentation

Index

• Variables
• type Client
  • func NewClient(endpoint string) *Client
  • func (rc *Client) Close() error
  • func (rc *Client) Err() error
  • func (rc *Client) Read() (messageType MessageType, p []byte, err error)
  • func (rc *Client) Write(messageType MessageType, data []byte) error
• type Connection
  • func Dial(ctx context.Context, endpoint string) (*Connection, error)
  • func (wc *Connection) Close() error
  • func (wc *Connection) CloseCtx() context.Context
  • func (wc *Connection) CloseWithCause(cause error)
  • func (wc *Connection) Err() error
  • func (wc *Connection) Read() (messageType MessageType, p []byte, err error)
  • func (wc *Connection) Write(messageType MessageType, data []byte) error
• type ConnectionMetadata
• type MessageType
  • func (typ MessageType) String() string
• type Messenger
• type OnConnectFn
• type OnDisconnectFn
• type Server
  • func NewServer[E any](onConnect OnConnectFn[E], opts ...ServerOpt[E]) *Server[E]
  • func (s *Server[E]) Count() int64
  • func (s *Server[E]) Handle(w http.ResponseWriter, r *http.Request)
  • func (s *Server[E]) Range(fn func(e E) bool)
• type ServerOpt
  • func WithCheckOrigin[E any](fn func(r *http.Request) bool) ServerOpt[E]
  • func WithOnDisconnect[E any](onDisconnect OnDisconnectFn[E]) ServerOpt[E]
  • func WithOnUpgradeFailed[E any](fn func(r *http.Request, err error)) ServerOpt[E]
  • func WithReadLimit[E any](readLimit int64) ServerOpt[E]

Variables

var ErrNotConnected = errors.New("not connected")

var ErrNotReconnecting = errors.New("not reconnecting")

Types

type Client

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

Client lazily connects to the configured endpoint on writes/reads when necessary, until the reconnecting-client is Close-ed. The status of the current connection can be checked with Err().

func NewClient

func NewClient(endpoint string) *Client

func (*Client) Close

func (rc *Client) Close() error

func (*Client) Err

func (rc *Client) Err() error

Err returns nil if the client is connected. It returns ErrNotConnected if not connected. It returns context.Canceled if the Reconnecting client was closed. It returns another error if the underlying connection failed or closed in some way. Client will attempt re-connection upon next Read or Write.

func (*Client) Read

func (rc *Client) Read() (messageType MessageType, p []byte, err error)

func (*Client) Write

func (rc *Client) Write(messageType MessageType, data []byte) error

type Connection

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

Connection is an opinionated wrapper around the Gorilla websocket connection library. It handles pings/pongs/reads/writes/close. This manages the closing of a connection by reporting *why* the connection was closed, and sending a close-message to the wbesocket if we are closing.

func Dial

func Dial(ctx context.Context, endpoint string) (*Connection, error)

func (*Connection) Close

func (wc *Connection) Close() error

Close closes the connection, if it's not already closed. It then returns the error of the connection closing, or nil if successfully closed without issue.

func (*Connection) CloseCtx

func (wc *Connection) CloseCtx() context.Context

CloseCtx returns the context that terminates when the connection closed. The context Cause shares the reason for closure. This may simply be "context.Canceled" if Close() was called. This may be a websocket.CloseError if the connection itself was broken.

func (*Connection) CloseWithCause

func (wc *Connection) CloseWithCause(cause error)

func (*Connection) Err

func (wc *Connection) Err() error

Err is a shorthand for the Cause error of the CloseCtx.

func (*Connection) Read

func (wc *Connection) Read() (messageType MessageType, p []byte, err error)

Read reads from the connection. Note: reads on the underlying connection are timed out by the underlying ping-pong message system.

func (*Connection) Write

func (wc *Connection) Write(messageType MessageType, data []byte) error

Write writes to the connection.

type ConnectionMetadata

type ConnectionMetadata struct {
	RemoteAddr string
	Origin     string
	UserAgent  string
	Context    context.Context
}

type MessageType

type MessageType uint

MessageType is a type-safe enum, replacing the message-types by the underlying gorilla-websocket library.

const (
	// TextMessage denotes a text data message. The text message payload is
	// interpreted as UTF-8 encoded text data.
	TextMessage MessageType = 1

	// BinaryMessage denotes a binary data message.
	BinaryMessage MessageType = 2

	// CloseMessage denotes a close control message. The optional message
	// payload contains a numeric code and text. Use the FormatCloseMessage
	// function to format a close message payload.
	CloseMessage MessageType = 8

	// PingMessage denotes a ping control message. The optional message payload
	// is UTF-8 encoded text.
	PingMessage MessageType = 9

	// PongMessage denotes a pong control message. The optional message payload
	// is UTF-8 encoded text.
	PongMessage MessageType = 10
)

The message types are defined in RFC 6455, section 11.8.

func (MessageType) String

func (typ MessageType) String() string

type Messenger

type Messenger interface {
	Write(messageType MessageType, data []byte) error
	Read() (messageType MessageType, p []byte, err error)
	Close() error
	Err() error
}

type OnConnectFn

type OnConnectFn[E any] func(c *Connection, meta *ConnectionMetadata) (E, error)

type OnDisconnectFn

type OnDisconnectFn[E any] func(e E)

type Server

type Server[E any] struct {
	// contains filtered or unexported fields
}

func NewServer

func NewServer[E any](onConnect OnConnectFn[E], opts ...ServerOpt[E]) *Server[E]

func (*Server[E]) Count

func (s *Server[E]) Count() int64

func (*Server[E]) Handle

func (s *Server[E]) Handle(w http.ResponseWriter, r *http.Request)

func (*Server[E]) Range

func (s *Server[E]) Range(fn func(e E) bool)

type ServerOpt

type ServerOpt[E any] func(c *serverConfig[E])

func WithCheckOrigin

func WithCheckOrigin[E any](fn func(r *http.Request) bool) ServerOpt[E]

func WithOnDisconnect

func WithOnDisconnect[E any](onDisconnect OnDisconnectFn[E]) ServerOpt[E]

func WithOnUpgradeFailed

func WithOnUpgradeFailed[E any](fn func(r *http.Request, err error)) ServerOpt[E]

func WithReadLimit

func WithReadLimit[E any](readLimit int64) ServerOpt[E]