realtime

Documentation

Overview

Package realtime provides explicit, in-process fan-out over WebSocket and server-sent events. It is intentionally a single-process primitive: use a broker-backed adapter when messages must cross application instances.

Index

• Variables
• func Forward[T any](bus *events.Bus, hub *Hub, channel, event string, transform ...func(T) any) func()
• type AuthFunc
• type Hub
  • func New(options ...Options) *Hub
  • func NewHub(options ...Options) *Hub
  • func (h *Hub) Close()
  • func (h *Hub) Handler() gin.HandlerFunc
  • func (h *Hub) Private(name string, auth AuthFunc) error
  • func (h *Hub) Public(name string) error
  • func (h *Hub) Publish(channelName, event string, data any) error
  • func (h *Hub) Run(ctx context.Context) error
  • func (h *Hub) SSE() gin.HandlerFunc
  • func (h *Hub) SSEHandler() gin.HandlerFunc
  • func (h *Hub) WebSocket() gin.HandlerFunc
• type Options

Variables

var (
	// ErrUnknownChannel define package-level implementation state.
	ErrUnknownChannel = errors.New("realtime: unknown channel")
	// ErrForbidden define package-level implementation state.
	ErrForbidden = errors.New("realtime: channel subscription forbidden")
)

Functions

func Forward

func Forward[T any](bus *events.Bus, hub *Hub, channel, event string, transform ...func(T) any) func()

Forward subscribes to typed in-process events and publishes each value to a realtime channel. With no transform, the event value becomes data. The returned function unsubscribes the bridge from the events bus.

Types

type AuthFunc

type AuthFunc func(*gin.Context) error

AuthFunc decides whether the current HTTP request may subscribe to a private channel. It is called before the subscription is created.

type Hub

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

Hub owns named public and private channels and their current subscribers. Register channels during application setup, before accepting connections.

func New

func New(options ...Options) *Hub

New creates a Hub. The optional form supports New() with secure defaults as well as New(Options{...}). Only the first options value is used.

func NewHub

func NewHub(options ...Options) *Hub

NewHub is an alias for New.

func (*Hub) Close

func (h *Hub) Close()

Close ends all live client streams. It is safe to call more than once.

func (*Hub) Handler

func (h *Hub) Handler() gin.HandlerFunc

Handler returns the WebSocket endpoint. Clients send {"action":"subscribe","channel":"name"} and {"action":"unsubscribe","channel":"name"}. Successful requests emit acknowledgements; malformed or unauthorized requests emit error messages.

func (*Hub) Private

func (h *Hub) Private(name string, auth AuthFunc) error

Private registers name as a private channel. auth must authorize every WebSocket or SSE subscription to that channel.

func (*Hub) Public

func (h *Hub) Public(name string) error

Public registers name as a public channel. Re-registering a name returns an error so channel access cannot be changed accidentally at runtime.

func (*Hub) Publish

func (h *Hub) Publish(channelName, event string, data any) error

Publish sends an event to every current subscriber of channel. A client whose outbound queue is full is evicted rather than allowing one slow peer to block application work.

func (*Hub) Run

func (h *Hub) Run(ctx context.Context) error

Run waits for ctx cancellation, closes all live connections, and returns. Register it with application.Go("realtime", hub.Run) so it participates in the application's graceful shutdown.

func (*Hub) SSE

func (h *Hub) SSE() gin.HandlerFunc

SSE returns a server-sent-events endpoint. Provide one or more channel query values (for example ?channel=orders&channel=alerts); comma-separated names are also accepted. It uses the same authorization and subscription lifecycle as WebSocket connections.

func (*Hub) SSEHandler

func (h *Hub) SSEHandler() gin.HandlerFunc

SSEHandler is an alias for SSE.

func (*Hub) WebSocket

func (h *Hub) WebSocket() gin.HandlerFunc

WebSocket is an alias for Handler.

type Options

type Options struct {
	// ClientBuffer store data used by this type.
	ClientBuffer int
	// OriginPatterns store data used by this type.
	OriginPatterns []string
}

Options controls a Hub. A zero ClientBuffer uses the safe default of 16. OriginPatterns are passed to coder/websocket and match origin hosts, not full URLs. The request host remains allowed by the WebSocket library.