orbitcast

Crates.ioorbitcast
lib.rsorbitcast
version0.1.10
created_at2025-12-22 23:00:03.65419+00
updated_at2026-01-05 00:15:34.072732+00
descriptionReal-time WebSocket server with ActionCable protocol for Mothership
homepagehttps://github.com/seuros/orbitcast
repositoryhttps://github.com/seuros/orbitcast
max_upload_size
id2000436
size273,349
Abdelkader Boudih (seuros)

documentation

https://docs.rs/orbitcast

README

OrbitCast

ActionCable WebSocket server for Mothership. Runs as a bay using the docking protocol.

What It Does

OrbitCast handles ActionCable WebSocket connections, multiplexed through Mothership's docking protocol. Multiple client connections share a single Unix socket.

Clients (WS) → Mothership → Unix Socket → OrbitCast
                                              ↓
                                          RPC
                                     (anycable-rails)
                                              ↓
                                         Pub/Sub
                                    (PostgreSQL or Memory)

Installation

# Production (multi-node coordination via PostgreSQL)
cargo install orbitcast
# Or explicitly:
# cargo install orbitcast --features postgres

# Development (single-node, in-memory)
cargo install orbitcast --no-default-features --features memory

Exactly one backend is required. Use --no-default-features to disable the default PostgreSQL backend when using memory.

Configuration

Add to your ship-manifest.toml:

[[bays.websocket]]
name = "orbitcast"
command = "orbitcast"
routes = [{ bind = "ws", pattern = "/cable" }]
config = { database_url = "postgres://localhost/myapp" }

Config Options

Key Description
database_url PostgreSQL connection (required for postgres feature)
ping_interval Seconds between pings (default: 3)
rpc_host AnyCable RPC host (default: 127.0.0.1:50051)
rpc_request_timeout_ms RPC request timeout in ms (optional)
rpc_headers Comma-separated header allowlist (default: cookie, * for all)

Environment Variables

Set automatically by Mothership:

Variable Description
MS_PID Mothership process ID
MS_SHIP Bay name
MS_SOCKET_DIR Unix socket directory

Pub/Sub Backends

PostgreSQL (--features postgres)

Uses LISTEN/NOTIFY for cross-node broadcasting. Required for multi-instance deployments.

TLS / sslmode

OrbitCast honors the sslmode query param in database_url:

  • disable: non-TLS only
  • allow: try non-TLS, then TLS
  • prefer (default): try TLS, then non-TLS
  • require: TLS only
  • verify-ca, verify-full: TLS only (certificate verification uses system roots)

Memory (--features memory)

Uses tokio::sync::broadcast. Single process only. Good for development.

Limitations:

  • No cross-node coordination
  • No persistence
  • Lagging receivers lose messages

Redis / NATS (not supported here)

OrbitCast requires PostgreSQL for multi-node pub/sub. If you need Redis or NATS backends, use AnyCable-Go directly as your WebSocket server instead of OrbitCast.

CLI

orbitcast --help
orbitcast --log-level debug

AnyCable RPC

OrbitCast speaks the AnyCable RPC protocol. Run the anycable-rails RPC server and point OrbitCast to it via rpc_host.

Protocol compatibility: AnyCable RPC protocol 1.6.2+.

Example ship config:

[[bays.websocket]]
name = "orbitcast"
command = "orbitcast"
routes = [{ bind = "ws", pattern = "/cable" }]
config = { rpc_host = "127.0.0.1:50051", database_url = "postgres://localhost/myapp" }

License

MIT

Commit count: 0

cargo fmt