Gateway

The Gateway is LocalUniverse's WebSocket protocol for real-time events: messages arriving, presence changing, equipment updating, channels mutating. One socket per client receives everything the user is subscribed to.

It's a separate Cloudflare Workers deployment from the REST API, backed by Durable Objects. Auth happens at the upgrade — there is no IDENTIFY round-trip on this protocol. The server validates the token via a service binding to the API, then HELLO + READY fire immediately.

Connect

wss://gateway.localuniverse.io/v1?v=1&token=<token>

const ws = new WebSocket(
  `wss://gateway.localuniverse.io/v1?v=1&token=${token}`
);

Payload shape

Every frame in either direction shares one envelope:

{
  "op": 0,
  "d": {},
  "s": 1,
  "t": "MESSAGE_CREATE"
}

Opcodes

Connection lifecycle

1. Upgrade

Client opens the WebSocket with ?v=1&token=.... The Gateway validates the token by calling /v1/auth/verify on the API via service binding. On failure the upgrade returns 401.

2. HELLO

The server immediately dispatches:

{ "op": 10, "d": { "heartbeat_interval": 30000 } }

heartbeat_interval is the cadence the client must keep, in milliseconds. The server times out a socket whose last activity is older than 90_000 ms (three missed heartbeats).

3. READY

For a fresh connection (no ?resume), the server dispatches READY next:

{
  "op": 0,
  "s": 1,
  "t": "READY",
  "d": {
    "user": { "id": "...", "email": "...", "display_name": "...", ... },
    "session_id": "31293...",
    "heartbeat_interval": 30000
  }
}

The user field is the same shape REST returns from /v1/users/@me — clients can hydrate the entire app state from this one frame.

Persist session_id immediately. If the connection drops, RESUME uses it to replay missed events.

4. Heartbeat loop

{ "op": 1 }

Client sends every heartbeat_interval ms. Server replies { "op": 11 }. Both sides treat lack of activity for 3 × interval as a dead connection.

Resume

If the socket drops and the client still has session_id + the last s it processed, reconnect with ?resume:

wss://gateway.localuniverse.io/v1?v=1&token=...&resume=31293...&last_seq=4287

The Gateway routes to the same Durable Object instance that owned the original socket. If the DO still has the in-memory buffer and your last_seq falls inside it, you get RESUMED followed by a replay of every event with s > last_seq. Once the replay drains, normal dispatch resumes.

If the DO has been evicted, or the buffer doesn't reach back to last_seq, the server sends:

{ "op": 12, "d": { "resumable": false } }

The client should drop the cached session_id, reconnect without ?resume, and re-hydrate from READY.

Subscriptions

A client only receives events for resources it has subscribed to. The Gateway maintains per-channel subscriber sets in a ChannelTopic Durable Object.

{ "op": 4, "d": "3123..." }

{ "op": 5, "d": "3123..." }

User-scoped events (USER_UPDATE, EQUIPMENT_UPDATE, INVENTORY_ADD, INVENTORY_REMOVE, RELATIONSHIP_UPDATE) are auto-delivered without an explicit subscribe — they fan out to every live session for the affected user via the UserPresence DO.

Close codes

1xxx codes follow the WebSocket spec (1000 normal close, 1011 server error). Well-behaved clients should distinguish "permanent close, log the user out" from "transient close, retry with backoff" — only 4004 and a deliberate user-initiated 1000 should drop the user back to login.