Alpha

Sockethub 5.0.0-alpha.12 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

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

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