Documentation
¶
Overview ¶
Package websocket provides a Hub + Connection abstraction over WebSockets, modelled on Laravel Echo's room/channel semantics.
The adapter is a separate Go module so the core lagodev module stays dependency-free:
go get github.com/devituz/lagodev/adapters/websocket@latest
Architecture:
- Hub — the per-app singleton. Tracks all live connections by ID and by channel (Laravel "room").
- Connection — a single open WebSocket; sends are non-blocking with a bounded outbox.
- Handler — http.Handler that performs the WebSocket handshake and registers the connection on the Hub.
Usage:
hub := websocket.NewHub()
go hub.Run(ctx)
mux.Handle("/ws", hub.Handler(func(ctx context.Context, c *websocket.Connection, m []byte) error {
// m is one incoming text/binary message
return hub.Broadcast(ctx, "chat.42", m)
}))
// later, from anywhere:
_ = hub.Broadcast(ctx, "chat.42", []byte(`{"text":"hello"}`))
The connection lifecycle (join channel, receive, broadcast, leave) is fully exposed so applications can layer auth, presence, or per-message ACK semantics on top.
Index ¶
- Variables
- type Connection
- type Hub
- func (h *Hub) Broadcast(_ context.Context, channel string, payload []byte) error
- func (h *Hub) ChannelCount(channel string) int
- func (h *Hub) Close()
- func (h *Hub) Count() int
- func (h *Hub) Handler(onMessage MessageHandler) http.Handler
- func (h *Hub) Run(ctx context.Context)
- func (h *Hub) SendTo(connID string, payload []byte) error
- type HubOption
- type MessageHandler
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("websocket: closed")
ErrClosed is returned when an operation is attempted on a closed Hub or Connection.
Functions ¶
This section is empty.
Types ¶
type Connection ¶
type Connection struct {
// contains filtered or unexported fields
}
Connection represents one live WebSocket. Methods are safe for concurrent use unless otherwise noted.
func (*Connection) Dropped ¶
func (c *Connection) Dropped() uint64
Dropped returns how many outbound payloads have been dropped due to a full outbox. Useful as a saturation metric.
func (*Connection) ID ¶
func (c *Connection) ID() string
ID returns the connection's identifier within its Hub.
func (*Connection) Join ¶
func (c *Connection) Join(channel string)
Join adds the connection to a channel. Idempotent.
func (*Connection) Leave ¶
func (c *Connection) Leave(channel string)
Leave removes the connection from a channel. Idempotent.
func (*Connection) Send ¶
func (c *Connection) Send(payload []byte)
Send queues payload for delivery to the client. Non-blocking — a full outbox drops the payload and bumps the dropped counter.
type Hub ¶
type Hub struct {
// contains filtered or unexported fields
}
Hub orchestrates Connections.
func (*Hub) Broadcast ¶
Broadcast sends payload to every connection joined to channel. Per-connection delivery is best-effort: full outboxes drop the message and increment the connection's drop counter.
func (*Hub) ChannelCount ¶
ChannelCount returns the number of subscribers on channel.
func (*Hub) Close ¶
func (h *Hub) Close()
Close terminates every open connection. After Close, further Handler calls accept handshakes but immediately reject them.
func (*Hub) Handler ¶
func (h *Hub) Handler(onMessage MessageHandler) http.Handler
Handler returns an http.Handler that upgrades the request to a WebSocket connection, registers it on the Hub, and runs onMessage for each incoming frame until the connection closes.
type HubOption ¶
type HubOption func(*Hub)
HubOption customises Hub construction.
func WithOrigins ¶
WithOrigins restricts the handshake's Origin header. Empty list disables the check (DEV ONLY). Default empty.
func WithOutbox ¶
WithOutbox sets the per-connection outbound buffer size. Default 64.
func WithPingInterval ¶
WithPingInterval sets the server-side keep-alive ping cadence. Default 30s.
type MessageHandler ¶
type MessageHandler func(ctx context.Context, c *Connection, message []byte) error
MessageHandler receives each frame the client sends. Return non-nil to close the connection.
Source Files