Alpha

Sockethub 5.0.0-alpha.17 is the current active-use release. See the changelog.

Sockethub

How it works

How it works

Sockethub is a small set of well-defined parts: an envelope format, a gateway, protocol workers, and a queue. This page explains what each part does and how a message gets from your browser to a channel on IRC.

01 — The problem

The browser sandbox

IRC wants a TCP stream. XMPP wants a long-lived connection that survives credential rotation. Feed polling wants a cron. A browser tab can do none of these — the sandbox blocks raw sockets, CORS blocks arbitrary hosts, and page lifecycle breaks long-lived connections.

The classic workaround is a backend per protocol. Sockethub is the alternative: one gateway that speaks all of them.

Browser tab one sandboxed origin sandbox IRC server XMPP server Feed origin Metadata source CalDAV server

02 — The envelope

A shared envelope format

Every message — outgoing or incoming — is a JSON-LD ActivityStreams 2.0 object. @context names the vocabularies in play — AS2, Sockethub, and the target platform. type says what you're doing; actor, target, and object say to whom and what.

Swap the platform URL (here irc) for another and the same call reaches a different network. The rest of your code stays put. 

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://sockethub.org/ns/context/v1.jsonld",
    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
  ],
  "type":   "send",
  "actor":  {
    "id":   "alice@irc.libera.chat",
    "type": "person"
  },
  "target": {
    "id":   "#sockethub@irc.libera.chat",
    "type": "room"
  },
  "object": {
    "type":    "message",
    "content": "Hello from the browser!"
  }
}

03 — The flow

The client flow

Three actions in that order. Credentials are stored encrypted per session. Connect spins up a worker and holds the live socket. Operate is everything after — send, join, fetch.

Every step is the same JSON envelope, just with a different type.

  1. 1

    credentials

    Stored encrypted. Scoped to the session.

    sc.credentials('irc', creds)
  2. 2

    connect

    Spawns (or reuses) a worker; opens the live socket.

    sc.connect('irc')
  3. 3

    operate

    Send, join, leave, follow, update — all the same shape.

    sc.send({ type, actor, target, object })

04 — The architecture

Gateway, queue, and workers

The gateway validates and routes. The queue ( BullMQ on Redis ) moves jobs between the gateway and the workers. Each platform runs in its own worker process, so an IRC reconnect loop can't stall XMPP, and a metadata parse error can't take down feeds.

Events flow back the other way — from worker, through the queue, to the right session on the gateway, to your browser.

Browser Socket.IO Sockethub gateway Redis BullMQ queue IRC worker XMPP worker Feeds worker Metadata CalDAV

05 — Session isolation

Per-session credentials

Every client gets its own session key on connect. Credentials are encrypted at rest with that key, so one session can never read another's secrets — not even at the Redis layer.

When the session ends, its key disappears. Whatever was encrypted under it is unreadable forever. No vendor lock-in, no shared secret store, no cross-session leakage.

  • session A own key · own creds · own workers
  • session B own key · own creds · own workers
  • session C own key · own creds · own workers

See what's built in → Supported platforms Get started