Sockudo Documentation

Sockudo is a self-hosted realtime platform for teams that want Pusher-compatible APIs with deeper control over protocol evolution, horizontal scaling, history, recovery, observability, and SDK behavior.

Production topology

Sockudo sits between realtime clients and trusted backends. Clients hold WebSocket connections and subscribe to public, private, presence, or encrypted channels. Backends use the HTTP API or server SDKs to publish events, sign channel auth, mutate V2 messages, manage push devices, and inspect operational state.

Runtime shape

One protocol edge, multiple durability choices.

Start with the in-memory local profile, then move app records, caches, queues, adapters, history, and push status into production backends as the deployment grows.

• WebSocket ingress: client connect, subscribe, auth, presence, and realtime delivery.
• HTTP control plane: trusted publishes, channel state, history reads, message mutations, annotations, and push workflows.
• Horizontal fanout: Redis, NATS, Kafka, RabbitMQ, Pulsar, Google Pub/Sub, Iggy, or another configured adapter.

Recommended path

1. Run a local Sockudo server from Installation.
2. Publish and receive your first event from First connection.
3. Add private and presence channel auth from Authentication.
4. Choose Protocol V1 or V2 from Compatibility.
5. Wire your client from Realtime Clients and your backend from Server SDKs.
6. Harden the deployment with Scaling, Security, and Observability.

Developer quick loops

The examples use the default development app. Keep these values local only:

export SOCKUDO_APP_ID=app-id
export SOCKUDO_APP_KEY=app-key
export SOCKUDO_APP_SECRET=app-secret
export SOCKUDO_HOST=127.0.0.1
export SOCKUDO_PORT=6001

Run Sockudo and check health

docker compose up sockudo redis
curl -f http://127.0.0.1:6001/up
curl -f http://127.0.0.1:9601/metrics | head

Use Docker Compose when you want Redis and repeatable local dependencies. Use cargo run --release when you want to validate a source build or a specific feature set.

Subscribe from a client

import Sockudo from "@sockudo/client";

const client = new Sockudo("app-key", {
  wsHost: "127.0.0.1",
  wsPort: 6001,
  forceTLS: false,
  enabledTransports: ["ws"],
  protocolVersion: 2,
});

client.subscribe("orders").bind("order.created", (payload) => {
  console.log("received", payload);
});

Set protocolVersion: 2 when the client needs Sockudo-native recovery, rewind, message IDs, tags, deltas, annotations, or mutable messages. Leave existing Pusher-compatible clients on Protocol V1 until you are ready to adopt V2 behavior.

Publish from a trusted backend

import { Sockudo } from "sockudo";

const sockudo = new Sockudo({
  appId: "app-id",
  key: "app-key",
  secret: "app-secret",
  host: "127.0.0.1",
  port: 6001,
  useTLS: false,
});

await sockudo.trigger(
  "orders",
  "order.created",
  { id: "ord_123", total: 4200 },
  { idempotency_key: "order-created-ord_123" },
);

Server SDKs sign requests, format payloads, and hide HMAC details. Use raw HTTP only when you are implementing or debugging an SDK.

Turn local config into a production shape

port = 6001
host = "0.0.0.0"
debug = false

[app_manager]
driver = "postgres"

[adapter]
driver = "redis"

[cache]
driver = "redis"

[queue]
driver = "redis"

[metrics]
enabled = true
port = 9601

The important move is not a single backend choice. It is separating connection fanout, app records, cache state, queue work, durable history, push status, and metrics so each subsystem can fail, scale, and be observed independently.

Local baseline

The examples use the default development app:

port = 6001
host = "0.0.0.0"

[app_manager]
driver = "memory"

[[app_manager.array.apps]]
id = "app-id"
key = "app-key"
secret = "app-secret"
enabled = true

For production, replace every example credential, enable TLS at the edge, use managed app storage, and keep app secrets only on trusted servers.

Production readiness checklist

• Compatibility: decide which clients stay on Protocol V1 and which channels may use Protocol V2 features.
• Authentication: keep app secrets server-side, sign private and presence auth responses, and reject stale HTTP signatures.
• Fanout: choose an adapter, configure sticky sessions when required, and test cross-node broadcast delivery before launch.
• Durability: enable history, recovery, version storage, annotations, and push status only for channels that need those contracts.
• Idempotency: attach stable keys to retried publishes, message mutations, push requests, and backend workflows.
• Observability: scrape /metrics, alert on connection churn, publish failures, adapter errors, webhook retries, push provider outcomes, and recovery failures.
• Operations: document feature flags, runtime config, secret rotation, rollout order, and rollback behavior for every backend dependency.