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 (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
Constants ¶
This section is empty.
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 ¶
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 ¶
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 (*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 ¶
Private registers name as a private channel. auth must authorize every WebSocket or SSE subscription to that channel.
func (*Hub) Public ¶
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 ¶
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 ¶
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) 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.
Source Files