ws

Documentation

Overview

Package ws provides a higher-level abstraction to work with WebSockets.

Index

• Variables
• func NewID() string
• func WrapError(err error, sentinel *sentinelError) error
• type Connection
  • func NewConnection(conn *websocket.Conn, manager *Manager) *Connection
  • func (c *Connection) ClearErr() error
  • func (c *Connection) Close()
  • func (c *Connection) Closed() bool
  • func (c *Connection) IsErr() bool
  • func (c *Connection) LastError() error
  • func (c *Connection) Manager() *Manager
  • func (c *Connection) ReadMessages(ctx context.Context)
  • func (c *Connection) SendClose() error
  • func (c *Connection) SendMessage(outgoing Message)
  • func (c *Connection) SetUserData(value any)
  • func (c *Connection) UserData() any
  • func (c *Connection) Valid() bool
  • func (c *Connection) WriteMessages(ctx context.Context)
• type ConnectionList
• type Manager
  • func NewManager(role ManagerRole, opts ...ManagerOption) *Manager
  • func (m *Manager) AddConnection(conn *Connection)
  • func (m *Manager) AddHandler(msgType string, handler MessageHandler) *Manager
  • func (m *Manager) Connections() ConnectionList
  • func (m *Manager) GetWSHandler(ctx context.Context) func(w http.ResponseWriter, r *http.Request)
  • func (m *Manager) RemoveConnection(conn *Connection)
  • func (m *Manager) Role() ManagerRole
  • func (m *Manager) SetUserData(value any)
  • func (m *Manager) Upgrade(outerCtx context.Context, w http.ResponseWriter, r *http.Request) *Connection
  • func (m *Manager) UpgradeExt(outerCtx context.Context, wg *sync.WaitGroup, w http.ResponseWriter, ...) *Connection
  • func (m *Manager) UserData() any
• type ManagerOption
  • func ManagerBuffers(readBufferSize int, writeBufferSize int) ManagerOption
  • func ManagerCheckOrigin(logger zerolog.Logger, origins []string) ManagerOption
  • func ManagerLogger(logger zerolog.Logger) ManagerOption
  • func ManagerMaxMessageSize(maxMessageSize int64) ManagerOption
• type ManagerRole
  • func (role ManagerRole) String() string
• type Message
• type MessageHandler

Variables

var (
	ErrConnectionClosed = &sentinelError{msg: "connection closed"} // not an error actually
	ErrContextCanceled  = &sentinelError{msg: "context canceled"}
	ErrAbnormalClose    = &sentinelError{msg: "abnormal close"}
	ErrPing             = &sentinelError{msg: "can't send ping"}
	ErrReadMessage      = &sentinelError{msg: "can't read message"}
	ErrSendMessage      = &sentinelError{msg: "can't send message"}
)

var (
	ErrMessageNotSupported = errors.New("this message type is not supported")
)

Functions

func NewID

func NewID() string

NewID generates a short random base-58 ID.

func WrapError

func WrapError(err error, sentinel *sentinelError) error

WrapError wraps an error using a sentinel..

Types

type Connection

type Connection struct {
	ID string // short ID identifying this connection
	// contains filtered or unexported fields
}

Connection is a websocket connection (either for a server or a client).

func NewConnection

func NewConnection(conn *websocket.Conn, manager *Manager) *Connection

NewConnection is used to initialize a new websocket connection.

func (*Connection) ClearErr

func (c *Connection) ClearErr() error

func (*Connection) Close

func (c *Connection) Close()

Close cleanly closes the connection

func (*Connection) Closed

func (c *Connection) Closed() bool

Closed returns true if the connection has been closed.

func (*Connection) IsErr

func (c *Connection) IsErr() bool

func (*Connection) LastError

func (c *Connection) LastError() error

func (*Connection) Manager

func (c *Connection) Manager() *Manager

Manager returns the manager associated with this connection.

func (*Connection) ReadMessages

func (c *Connection) ReadMessages(ctx context.Context)

ReadMessages will read messages for this connection in a cycle and handle them appropriately. This is supposed to be run in a goroutine.

func (*Connection) SendClose

func (c *Connection) SendClose() error

func (*Connection) SendMessage

func (c *Connection) SendMessage(outgoing Message)

func (*Connection) SetUserData

func (c *Connection) SetUserData(value any)

SetUserData sets the user-data associated with this connection.

func (*Connection) UserData

func (c *Connection) UserData() any

UserData returns the user-data associated with this connection.

func (*Connection) Valid

func (c *Connection) Valid() bool

Valid returns true if the connection is still active (established and not closed).

func (*Connection) WriteMessages

func (c *Connection) WriteMessages(ctx context.Context)

WriteMessages listens on the channel for new messages and pipes them onto the websocket connection.

type ConnectionList

type ConnectionList map[*Connection]bool

ConnectionList is a map used to help manage a map of connections (connections).

type Manager

type Manager struct {

	// Using a syncMutex here to be able to lcok state before editing connections
	// Could also use Channels to block
	sync.RWMutex
	// contains filtered or unexported fields
}

Manager is used on the server side to hold references to all active connections, handle broadcasting, etc.

func NewManager

func NewManager(role ManagerRole, opts ...ManagerOption) *Manager

NewManager creates and returns a Manager.

func (*Manager) AddConnection

func (m *Manager) AddConnection(conn *Connection)

AddConnection will add a connection to our connection list.

func (*Manager) AddHandler

func (m *Manager) AddHandler(msgType string, handler MessageHandler) *Manager

func (*Manager) Connections

func (m *Manager) Connections() ConnectionList

Connections return the (active) connections associated with this Manager.

func (*Manager) GetWSHandler

func (m *Manager) GetWSHandler(ctx context.Context) func(w http.ResponseWriter, r *http.Request)

GetWSHandler returns an HTTP Handler to serve websocket connections through the Manager.

func (*Manager) RemoveConnection

func (m *Manager) RemoveConnection(conn *Connection)

RemoveConnection will remove the connection (closing it).

func (*Manager) Role

func (m *Manager) Role() ManagerRole

Role returns the manager role (server or client).

func (*Manager) SetUserData

func (m *Manager) SetUserData(value any)

SetUserData sets the user-data associated with this manager.

func (*Manager) Upgrade

func (m *Manager) Upgrade(outerCtx context.Context, w http.ResponseWriter, r *http.Request) *Connection

Upgrade upgrades the HTTP server connection to the WebSocket protocol, creates a new high-level connection and starts read/write goroutines.

func (*Manager) UpgradeExt

func (m *Manager) UpgradeExt(outerCtx context.Context, wg *sync.WaitGroup, w http.ResponseWriter, r *http.Request) *Connection

Upgrade upgrades the HTTP server connection to the WebSocket protocol, creates a new high-level connection and starts read/write goroutines.

func (*Manager) UserData

func (m *Manager) UserData() any

UserData returns the user-data associated with this manager.

type ManagerOption

type ManagerOption func(m *Manager)

func ManagerBuffers

func ManagerBuffers(readBufferSize int, writeBufferSize int) ManagerOption

func ManagerCheckOrigin

func ManagerCheckOrigin(logger zerolog.Logger, origins []string) ManagerOption

func ManagerLogger

func ManagerLogger(logger zerolog.Logger) ManagerOption

func ManagerMaxMessageSize

func ManagerMaxMessageSize(maxMessageSize int64) ManagerOption

type ManagerRole

type ManagerRole int

const (
	ManagerRoleUnset ManagerRole = iota
	ManagerRoleServer
	ManagerRoleClient
)

func (ManagerRole) String

func (role ManagerRole) String() string

type Message

type Message struct {
	Type    string          `json:"type"`
	Payload json.RawMessage `json:"payload"`
}

Message holds the data sent over the websocket. The Type field differentiates the actual payload.

type MessageHandler

type MessageHandler func(msg Message, c *Connection) error

MessageHandler is the type for message handlers differentiated on type.