Distributed backplane and Redis · WebSocket

Carry live broadcasts across multiple application nodes and define Required/Optional and readiness behavior.

A backplane carries local client targets to other nodes. lily_websocket_redis is an online Redis Pub/Sub adapter. Room and principal memberships remain in each node's own connection manager.

Explicitly select an adapter#

Update the first application's lilyrs dependency to use the following feature list. websocket-redis enables only the adapter; select websocket as well for the server module. The cache component's redis feature is a separate requirement.

lilyrs = { version = "0.1.0", features = ["websocket", "websocket-redis"] }

use lilyrs::websocket::{BackplaneRequirement, WsAppBuilder};
use lilyrs::websocket_redis::RedisWebSocketBackplane;

let builder = WsAppBuilder::default()
    .backplane::<RedisWebSocketBackplane>(BackplaneRequirement::Required);

Use this builder in the normal build/start flow. Configuration alone does not enable the backplane. Select one backplane per app. The adapter manages its own publisher/subscriber connections; it does not share the lily_redis pool.

Configuration#

[websocket.backplane]
redis_url = "${secret:websocket.redis_url}"
use_tls = true
application_namespace = "orders-api"
environment_namespace = "production"
channel_namespace = "events"
publish_capacity = 64
ingress_capacity = 256
connection_timeout_millis = 5000
operation_timeout_millis = 2000
reconnect_initial_delay_millis = 100
reconnect_max_delay_millis = 5000
reconnect_jitter_ratio = 0.2

The secret placeholder must be resolved by a real SecretResolver. Production validation requires credential-bearing rediss:// and TLS. If using custom_ca_bundle, supply a canonical absolute PEM file path; custom CAs replace the connection's trust roots rather than augmenting the existing public roots.

Required and Optional#

Situation	Result
No adapter	Local dispatch
Required constructor fails	Build fails
Optional constructor fails	Observable degraded, local-only app
Required backplane fails at runtime	Readiness drops; existing socket loops do not close solely for this reason
Publisher and initial subscription are healthy	The backplane's required readiness condition is met
Publish fails after local sending	Local effects remain; the error carries the local report
New publication during a known outage	Fails; no replay after reconnection

Other required application-health checks must also be satisfied. Observability explains connecting the snapshot to your own probe endpoint.

Protocol and extensions#

Channels use lily.websocket.v4.<environment>.<application>.<channel>. Backplane routing generation v4 and client envelope v2 are different layers. Nodes in one deployment must use the same generation and namespace settings.

WebSocketBackplane is an opaque transport SPI for custom adapters; an adapter does not recreate the routing envelope itself. It implements bounded publish/ingress, health, and close contracts. Duplicate/origin-loop suppression is bounded; it does not guarantee exactly-once behavior over an unlimited history.

Delivery and capacity boundaries#

Redis publish acceptance is not delivery to a remote client. There is no offline inbox, persistent history, replay, strict global ordering, or aggregate remote-recipient ACK count. Receipts report only their defined acceptance milestones.

Native Redis Cluster/Sentinel discovery is not provided; deployment must supply a stable endpoint for high availability. The Redis client may decode a bulk payload before adapter admission; this is not a full pre-allocation memory bound against an untrusted Redis publisher. Queue limits alone do not bound total process memory.