realtime

type DBEvent struct {
	Collection string
	Op         Op
	DocID      string
	Doc        *docstore.Doc // nil for deletes
}

type Hub interface {
	// ServeWS upgrades the request and serves the connection until it closes.
	// The caller has already authenticated user and resolved site; ServeWS
	// performs the Origin check (allowedOrigins: exact origins such as
	// "https://foo.backyard.acme.com"; empty = same-origin only).
	ServeWS(w http.ResponseWriter, r *http.Request, site string, user *identity.User, allowedOrigins []string)
	// PublishDB fans out a database change to subscribers on all instances.
	PublishDB(ctx context.Context, site string, ev DBEvent) error
	// Stats returns current local connection counts (for metrics).
	Stats() Stats
	// Close disconnects all clients and unsubscribes from the broker.
	Close() error
}

type Op string

type Options struct {
	Config config.RealtimeConfig
	// InstanceID distinguishes this server instance in presence gossip
	// (default: random). It is used as a readable label: a random suffix is
	// always appended, so instances given the same value (e.g. a hostname
	// that is not unique) still tell each other apart.
	InstanceID string

	// Logger receives operational logs (default slog.Default()).
	Logger *slog.Logger
	// PingInterval is how often the server pings every connection
	// (default 25s).
	PingInterval time.Duration
	// PongTimeout closes a connection that has not answered a ping for this
	// long (default 60s).
	PongTimeout time.Duration
	// HeartbeatInterval is how often this instance re-announces its local
	// room members to other instances (default 20s).
	HeartbeatInterval time.Duration
	// MemberTTL expires members of other instances that were not refreshed by
	// gossip for this long (default 60s; raised to three heartbeat intervals
	// when shorter than two).
	MemberTTL time.Duration
	// WriteTimeout bounds writing one frame to a client (default 10s).
	WriteTimeout time.Duration
	// SendQueue is the number of outbound frames buffered per connection; a
	// client that falls further behind is disconnected as a slow consumer
	// (default 4096). The queue is allocated on demand, so a generous bound
	// costs nothing for clients that keep up; it must absorb bursts such as
	// one presence event per member when a large room is first synced.
	SendQueue int
	// SendQueueBytes bounds the bytes buffered per connection in the same
	// way (default 4 MiB; a single larger frame is still accepted).
	SendQueueBytes int
	// BrokerTimeout bounds each broker Publish/Subscribe call made on behalf
	// of a client (default 5s).
	BrokerTimeout time.Duration
	// OnFrame, if set, is called once per websocket frame received from
	// (dir "in") or written to (dir "out") a client, e.g. to feed the
	// ws_messages_total metric. It must be fast and safe for concurrent use.
	OnFrame func(dir string)
}

type Stats struct {
	Connections int
	Rooms       int
	Subs        int
}