Pub/Sub

Master switch for the pub/sub subsystem. Requires Redis to be configured — the whole subsystem only registers when a Redis manager exists; enabling pub/sub without Redis silently disables it (only a startup warning, 'pubsub is enabled but Redis is not configured. Disabling PubSub.', is logged — no error).

Base path for Dapr subscription endpoints (the routes Dapr posts delivered messages to).

The WebSocket endpoint clients connect to for the realtime feed. The handshake is authenticated whenever an access-token secret is configured: identity (userId) is derived from the verified token and an unauthenticated handshake is closed with code 4001 ('Unauthorized'). Absent an access-token secret, authentication is skipped and identity falls back to the client-supplied userId query param.

Intended as the name of the Dapr pub/sub component used to publish and subscribe across instances. This is the real config-level default, but the value is currently accepted and stored yet never consumed by the pub/sub routes — it has no runtime effect and does not select the component used by the Dapr publish path (DaprPubSubClient.publish / publishBulk both default to DEFAULT_PUBSUB_NAME, 'pubsub-rabbitmq').

Cap on simultaneous WebSocket connections per user — prevents a single account exhausting sockets. Past the limit the user's oldest connection is evicted, not the new one rejected.

Max distinct topics a single client may subscribe to. Bounds the in-memory subscription set against an attacker-controlled topics array (memory-exhaustion DoS); enforced on both the handshake and every subscribe message, with each topic string also clamped to 256 chars and de-duplicated. Excess topics are silently dropped.

Shared secret that gates the POST {basePath}/:topic Dapr subscription (ingress) endpoint. When set, delivered events must present a matching dapr-api-token header (constant-time compare) or get HTTP 403; falls back to env APP_API_TOKEN, then DAPR_API_TOKEN. If unset the endpoint is unauthenticated (one warning is logged on the first unauthenticated inbound event, not at startup) and anyone reaching it can inject realtime events to any user — set it wherever the route is network-reachable.

Seconds of inactivity before an idle WebSocket is closed. Tune against any proxy idle timeouts in front of the service.

At-least-once delivery configuration.

Broadcast user presence (enabled default true). debounceMs (default 5000) coalesces rapid connect/disconnect flaps into a single update.

Interval (default every 60s) for the periodic client-count log. Stale clients are actually pruned lazily — a failed send or a WebSocket close unregisters them; a value <= 0 disables just the log timer.

Clients connect at wsPath and subscribe to topics; the server applies the ack and presence behaviour from the config above (acknowledged delivery, presence broadcasts, heartbeats). This is what the usePubSub hook on the Realtime page talks to.

For cross-service messaging the Dapr transport exposes publish(topic, data) and publishBulk(topic, messages[]) against a named pubsub component, with per-message metadata and content type — so one service can emit an event that another consumes via its Dapr subscription.

publishBulk sends many messages in one request and returns failedEntries (entryId + error) for any that didn't make it, so a partial failure is observable rather than silent.