Documentation
¶
Index ¶
- type Client
- type Emitter
- type Event
- type EventType
- type Hub
- func (h *Hub) AssociateSubject(sessionID, subjectID string)
- func (h *Hub) Broadcast(msg []byte) int
- func (h *Hub) Close()
- func (h *Hub) Handler() echo.HandlerFunc
- func (h *Hub) JoinRoom(c *Client, room string)
- func (h *Hub) LeaveRoom(c *Client, room string)
- func (h *Hub) SendToRoom(room string, msg []byte) int
- func (h *Hub) SendToRoomExcept(room string, msg []byte, exceptSessionID string) int
- func (h *Hub) SendToSession(sessionID string, msg []byte) bool
- func (h *Hub) SendToSubject(subjectID string, msg []byte) int
- func (h *Hub) Stats() HubStats
- type HubOption
- func WithAcceptOptions(opts *ws.AcceptOptions) HubOption
- func WithLogger(l *slog.Logger) HubOption
- func WithOnMessage(fn func(*Client, []byte)) HubOption
- func WithSendBufferSize(n int) HubOption
- func WithSessionIDFunc(fn func(r *http.Request) string) HubOption
- func WithSubjectIDFunc(fn func(r *http.Request) string) HubOption
- type HubStats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
SessionID string
SubjectID string
Rooms map[string]bool
Meta map[string]any
// contains filtered or unexported fields
}
Client represents a single WebSocket connection managed by a Hub.
type Emitter ¶
type Emitter struct {
// contains filtered or unexported fields
}
Emitter is a thin typed wrapper over Hub that accepts *Event values instead of raw bytes.
func NewEmitter ¶
NewEmitter creates an Emitter backed by the given Hub.
func (*Emitter) ToRoomExcept ¶
ToRoomExcept sends an event to all room clients except one session.
type Event ¶
type Event struct {
Type EventType `json:"type"`
Payload json.RawMessage `json:"payload,omitempty"`
Target string `json:"target,omitempty"` // CSS selector
Swap string `json:"swap,omitempty"` // "innerHTML" or "outerHTML"
HTML string `json:"html,omitempty"` // rendered HTML to swap in
Trigger string `json:"trigger,omitempty"` // HTMX event name
}
Event is the standard WebSocket event structure. Supports three delivery modes:
- HTML Direct: set Target + HTML, client swaps HTML into target
- HTMX Trigger: set Target + Trigger, client calls htmx.trigger()
- Data Only: set Payload only, client handles via registered callback
func NewHTMLEvent ¶
NewHTMLEvent creates an event that swaps HTML into a target element (innerHTML).
func NewOuterHTMLEvent ¶
NewOuterHTMLEvent creates an event that replaces a target element entirely (outerHTML).
func NewTriggerEvent ¶
NewTriggerEvent creates an event that triggers an HTMX event on a target.
type EventType ¶
type EventType string
EventType represents the type of WebSocket event. No domain-specific constants are defined here — projects define their own.
type Hub ¶
type Hub struct {
// contains filtered or unexported fields
}
Hub manages WebSocket clients with session, subject, and room routing. It uses a pure mutex design with no background event-loop goroutine.
func (*Hub) AssociateSubject ¶
AssociateSubject associates a session with a subject ID at runtime (e.g. after authentication completes post-connection).
func (*Hub) Broadcast ¶
Broadcast sends a message to every connected client. Returns the number of dropped messages.
func (*Hub) Close ¶
func (h *Hub) Close()
Close cancels the hub context, waits for all pumps to exit, and clears maps. Safe to call multiple times.
func (*Hub) Handler ¶
func (h *Hub) Handler() echo.HandlerFunc
Handler returns an Echo handler that upgrades HTTP connections to WebSocket.
func (*Hub) JoinRoom ¶
JoinRoom adds a client to a room. No-op if the client is no longer the registered client for its session (e.g. it disconnected, or was replaced by a reconnect): adding a stale client whose send channel is already closed would make the next SendToRoom/Broadcast panic on send-to-closed-channel.
func (*Hub) SendToRoom ¶
SendToRoom sends a message to all clients in a room. Returns the number of dropped messages.
func (*Hub) SendToRoomExcept ¶
SendToRoomExcept sends a message to all clients in a room except one session. Returns the number of dropped messages.
func (*Hub) SendToSession ¶
SendToSession sends a message to the client with the given session ID. Returns true if the message was sent, false if the session was not found or the message was dropped.
func (*Hub) SendToSubject ¶
SendToSubject sends a message to all clients associated with a subject ID. Returns the number of dropped messages.
type HubOption ¶
type HubOption func(*Hub)
HubOption configures a Hub.
func WithAcceptOptions ¶
func WithAcceptOptions(opts *ws.AcceptOptions) HubOption
WithAcceptOptions sets the websocket.AcceptOptions used when upgrading.
func WithLogger ¶
WithLogger sets the logger for the hub. Defaults to slog.Default().
func WithOnMessage ¶
WithOnMessage registers a callback invoked for every inbound client message. When nil (the default), the hub operates in server-push-only mode.
func WithSendBufferSize ¶
WithSendBufferSize sets the per-client send channel buffer size. Default: 256. Values <= 0 are treated as the default.
func WithSessionIDFunc ¶
WithSessionIDFunc sets the function used to derive a session ID from the HTTP request. The default generates a random UUID.
Source Files