Documentation
¶
Overview ¶
Package async provides a channel-based async event delivery interface with implementations for WebSocket, SSE, Pusher, and Ably.
Two behavior classes ¶
The providers differ in one way the AsyncNotifier interface does not express, and it is the difference that matters most in production:
- pusher and ably are fleet-safe. A hosted broker holds the client connections, so a Publish from any replica reaches every subscriber.
- sse and websocket hold connections in this process's memory. A Publish on replica A reaches only the subscribers connected to replica A — and misses the rest silently, as absent notifications rather than as an error.
The self-hosted providers are therefore correct only at a single replica. That constraint used to be written down nowhere, which is the failure this documentation and the Topology declaration in the config subpackage exist to prevent: a service that scales from one replica to two acquires a notification bug with no error, no log line, and no failed request to trace.
Declaring topology ¶
A process cannot detect how many replicas of itself are running, so the constraint cannot be enforced automatically — it has to be declared. The config subpackage requires an explicit Topology for the self-hosted providers, and refuses the combination of a self-hosted provider and a fleet. Choosing sse or websocket therefore means choosing single-replica out loud, and wanting more than one replica means choosing a hosted provider.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AsyncNotifier ¶
type AsyncNotifier interface {
// Publish sends an event to all subscribers of the given channel.
Publish(ctx context.Context, channel string, event *Event) error
// Close releases resources held by the notifier.
Close() error
}
AsyncNotifier publishes events to named channels. Implementations may deliver via WebSocket, SSE, Pusher, Ably, or other backends.
type ConnectionAcceptor ¶
type ConnectionAcceptor interface {
// AcceptConnection upgrades an HTTP request to a persistent connection
// and registers it under the given channel and memberID.
// The connection is managed internally; events published to the channel
// will be delivered to this connection.
AcceptConnection(w http.ResponseWriter, r *http.Request, channel, memberID string) error
}
ConnectionAcceptor is an optional interface implemented by backends that require server-side HTTP connection management (WebSocket, SSE). Callers may type-assert an AsyncNotifier to ConnectionAcceptor when they need to accept inbound client connections.
type Event ¶
type Event struct {
Type string `json:"type"`
Data json.RawMessage `json:"data,omitempty"`
}
Event represents an async notification event to be published to a channel.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ably is an Ably-backed AsyncNotifier.
|
Package ably is an Ably-backed AsyncNotifier. |
|
Package asynccfg selects and builds an async.AsyncNotifier from configuration: Pusher, Ably, WebSocket, SSE, or noop.
|
Package asynccfg selects and builds an async.AsyncNotifier from configuration: Pusher, Ably, WebSocket, SSE, or noop. |
|
Package noop is the async.AsyncNotifier that publishes to nobody.
|
Package noop is the async.AsyncNotifier that publishes to nobody. |
|
Package pusher is a Pusher-backed AsyncNotifier.
|
Package pusher is a Pusher-backed AsyncNotifier. |
|
Package sse is an SSE-backed AsyncNotifier that holds its client connections in process memory.
|
Package sse is an SSE-backed AsyncNotifier that holds its client connections in process memory. |
|
Package websocket is a WebSocket-backed AsyncNotifier that holds its client connections in process memory.
|
Package websocket is a WebSocket-backed AsyncNotifier that holds its client connections in process memory. |