@super-line/transport-cloudflare 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+Generated from conventional commits by [git-cliff](https://git-cliff.org) —
+run `pnpm changelog` rather than editing by hand.
+
+## [transport-cloudflare-v0.2.0] — 2026-10-18
+
+### Features
+
+- A refused credential closes 4401, and the client stops retrying it ([35c6e25])
+
+## [transport-cloudflare-v0.1.0] — 2026-10-15
+
+### Features
+
+- **server:** Ready waits for the connections a transport resumes ([dc6989f])
+- **transport-cloudflare:** A Durable Object is a super-line node ([fc912e8])
+
+### Documentation
+
+- Teach hosting a node on Cloudflare Durable Objects ([a893f83])
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @super-line/transport-cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run a [**super-line**](https://super-line.dogar.biz/) server inside a Cloudflare **Durable Object**: one object is one node. Its WebSockets use the Hibernation API, so the object leaves memory between events while every socket stays open, and the next message wakes a fresh instance that resumes every subscription, open document, room, and `env` before it handles anything. The client never sees a disconnect.
+
+```bash
+pnpm add @super-line/core @super-line/server @super-line/transport-cloudflare
+pnpm add -D wrangler @cloudflare/workers-types
+```
+
+The node must be a **SQLite-backed** class — the transport keeps each connection's snapshot in the object's SQLite:
+
+```jsonc
+// wrangler.jsonc
+{
+  "main": "./src/worker.ts",
+  "compatibility_flags": ["nodejs_compat"], // only for plugin-auth / plugin-inspector
+  "durable_objects": { "bindings": [{ "name": "NODE", "class_name": "Node" }] },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Node"] }]
+}
+```
+
+```ts
+// src/worker.ts
+import { createSuperLineServer } from '@super-line/server'
+import { createDurableNode, routeToNode } from '@super-line/transport-cloudflare'
+import { contract } from './contract'
+
+interface Env {
+  NODE: DurableObjectNamespace
+}
+
+// The factory runs on first use AND on every wake: keep it cheap and idempotent.
+export class Node extends createDurableNode((ctx, env: Env, base) =>
+  createSuperLineServer(contract, {
+    ...base, // the Durable Object transport + a nodeKey stable for this object
+    authenticate: (h) => ({ role: 'user', ctx: verify(h.query.token) }),
+  }).implement({ user: { ping: async () => 'pong' } }),
+) {}
+
+export default {
+  // Every request the object receives wakes it, so forward only the socket path.
+  fetch: (request, env) =>
+    new URL(request.url).pathname === '/ws'
+      ? routeToNode(request, env.NODE)
+      : new Response('Not found', { status: 404 }),
+} satisfies ExportedHandler<Env>
+```
+
+Clients use the ordinary WebSocket client. The node runs no heartbeat (a timer would keep it awake), so set `keepalive` — Cloudflare answers those pings without waking the object:
+
+```ts
+import { webSocketClientTransport } from '@super-line/transport-websocket'
+
+createSuperLineClient(contract, {
+  transport: webSocketClientTransport({ url: 'wss://my-app.example.workers.dev/ws' }),
+  role: 'user',
+  keepalive: 30_000,
+})
+```
+
+For durable state in the same object, pair it with [`@super-line/collections-cloudflare`](https://github.com/mertdogar/super-line/tree/main/packages/collections-cloudflare) (rows) and [`@super-line/collections-crdt-cloudflare`](https://github.com/mertdogar/super-line/tree/main/packages/collections-crdt-cloudflare) (CRDT documents).
+
+## API
+
+| Export | Meaning |
+| --- | --- |
+| `createDurableNode(build)` | A Durable Object class that is one node. `build(ctx, env, base)` returns the server built with `...base`; the class forwards `fetch` and the WebSocket handlers to the transport and resumes every surviving connection before any event is delivered. Exposes `this.server` and `this.transport`. |
+| `routeToNode(request, namespace, { name? })` | Forward a Worker request to the node object — `'super-line'` by default; `name(request)` picks one object per tenant. |
+| `cloudflareServerTransport(ctx)` | The transport itself, for a Durable Object class you write by hand: forward `fetch` / `webSocketMessage` / `webSocketClose` / `webSocketError`, and await `server.ready` inside `blockConcurrencyWhile`: on a wake it resolves once every surviving socket is back. |
+| `CLOSE_NOT_RESUMABLE` | `4409` — closes a socket whose connection could not be resumed on wake; the client reconnects as after any drop. |
+
+## Behavior notes
+
+- **Handshake** — `transport: 'cloudflare'`, `query` from the URL, `headers` from the request, `raw` is the `Request`. An `authenticate` that throws `SuperLineError('UNAUTHORIZED')`, and a refused Control Center connection, are closed `4401` after the upgrade, so the client can tell them from an outage; any other throw gets a plain `401` and no socket.
+- **What a wake loses** — everything in memory: `conn.data` (`onConnection` runs again for each resumed socket), memory collection backends, module state. Keep `ctx` and `env` JSON-serializable; the snapshot is stored as JSON.
+- **A subscription can end with the socket open** — a wake runs each subscription's policy again, and one it now refuses reaches the client's `onError` with `kind: 'resubscribe'`.
+- **Timers keep the node awake** — your own, `plugin-queue`'s polling (always), `plugin-inspector`'s keepalive (while a Control Center watches). A plugin's `ctx.hold()` keeps it awake on purpose.
+- **One object, one node** — there is no adapter; objects don't share rooms, topics, or state.
+
+- 📖 Guide: [Host a node on Cloudflare Durable Objects](https://super-line.dogar.biz/how-to/cloudflare-durable-objects)
+- 🧪 Example: [`examples/cloudflare`](https://github.com/mertdogar/super-line/tree/main/examples/cloudflare)
+- 🧩 Source: <https://github.com/mertdogar/super-line>
+
+MIT © Mert

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { ServerTransport } from '@super-line/core';
+import { DurableObject } from 'cloudflare:workers';
+
+/** Closes a socket whose connection could not be resumed on wake; the client reconnects on it like any drop. */
+declare const CLOSE_NOT_RESUMABLE = 4409;
+/**
+ * The transport a Durable Object hosts: a {@link ServerTransport} plus the handlers the object forwards from
+ * its own `fetch` and `webSocket*` methods. {@link createDurableNode} does that forwarding for you.
+ */
+interface CloudflareServerTransport extends ServerTransport {
+    /** Accept a WebSocket upgrade (any other request gets a 426). */
+    fetch(request: Request): Promise<Response>;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void;
+    webSocketClose(ws: WebSocket, code: number, reason: string): void;
+    webSocketError(ws: WebSocket, error: unknown): void;
+}
+/**
+ * A super-line transport over the Durable Object WebSocket Hibernation API. Sockets are accepted with
+ * `ctx.acceptWebSocket`, so the object can hibernate while they stay open; each connection's snapshot is kept in
+ * the object's SQLite storage (the object must be a SQLite-backed class). When the object wakes, the server's
+ * `ready` resolves only after every surviving socket is back with its subscriptions (one that cannot be resumed is
+ * closed 4409) — await it inside `blockConcurrencyWhile` so no event lands before then. Liveness is the socket's:
+ * client pings are answered by the platform without waking the object, so the server runs no heartbeat.
+ */
+declare function cloudflareServerTransport(ctx: DurableObjectState): CloudflareServerTransport;
+
+/** Spread into `createSuperLineServer`'s options: the Durable Object transport and a `nodeKey` stable per object. */
+interface DurableNodeBase {
+    transports: ServerTransport[];
+    nodeKey: string;
+}
+/** The class {@link createDurableNode} returns: a Durable Object exposing its transport and its server. */
+type DurableNodeClass<Env, S> = new (ctx: DurableObjectState, env: Env) => DurableObject<Env> & {
+    readonly transport: CloudflareServerTransport;
+    readonly server: S;
+};
+/**
+ * A Durable Object class that is one super-line node. `build` runs in the constructor — on first use AND on every
+ * wake from hibernation — and returns the server, built with `...base`. The class forwards `fetch` and the
+ * WebSocket handlers to the transport and resumes every surviving connection before any event is delivered.
+ * Extend it and export the subclass under the name your wrangler config binds; `this.server` is the server.
+ *
+ * ```ts
+ * export class Node extends createDurableNode((ctx, env: Env, base) =>
+ *   createSuperLineServer(contract, { ...base, authenticate }).implement({ user: { ping: async () => 'pong' } }),
+ * ) {}
+ * ```
+ */
+declare function createDurableNode<Env = Cloudflare.Env, S extends {
+    readonly ready: Promise<void>;
+} = {
+    readonly ready: Promise<void>;
+}>(build: (ctx: DurableObjectState, env: Env, base: DurableNodeBase) => S): DurableNodeClass<Env, S>;
+/**
+ * Forward a Worker request to the Durable Object that is the node. One named object per deployment by default;
+ * pass `name` to pick one per request (a tenant from the host or path).
+ */
+declare function routeToNode(request: Request, namespace: DurableObjectNamespace, opts?: {
+    name?: (request: Request) => string;
+}): Promise<Response>;
+
+export { CLOSE_NOT_RESUMABLE, type CloudflareServerTransport, type DurableNodeBase, type DurableNodeClass, cloudflareServerTransport, createDurableNode, routeToNode };

package/dist/index.js

@@ -0,0 +1,221 @@
+// src/transport.ts
+import { getLogger } from "@logtape/logtape";
+import { SuperLineError } from "@super-line/core";
+var log = getLogger(["super-line", "transport-cloudflare"]);
+var CLOSE_NOT_RESUMABLE = 4409;
+var SNAPSHOTS = "_sl_conn";
+var encoder = new TextEncoder();
+function cloudflareServerTransport(ctx) {
+  let hooks;
+  const conns = /* @__PURE__ */ new Map();
+  const sql = ctx.storage.sql;
+  sql.exec(`CREATE TABLE IF NOT EXISTS ${SNAPSHOTS} (id TEXT PRIMARY KEY, snapshot TEXT NOT NULL)`);
+  ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair('{"t":"ping"}', '{"t":"pong"}'));
+  const forget = (ws, id) => {
+    conns.delete(ws);
+    sql.exec(`DELETE FROM ${SNAPSHOTS} WHERE id = ?`, id);
+  };
+  function adopt(ws, id) {
+    const conn = new DurableConn(ws, id, () => forget(ws, id));
+    conns.set(ws, conn);
+    return conn;
+  }
+  let busy;
+  async function fetch(request) {
+    if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") return new Response("Expected a WebSocket upgrade", { status: 426 });
+    if (!hooks) return new Response("Not started", { status: 503 });
+    const handshake = buildHandshake(request);
+    const reserved = reservedFor(hooks.reserved ?? [], request, handshake);
+    let auth;
+    if (reserved) {
+      try {
+        auth = { role: reserved.role, ctx: await reserved.authenticate?.(handshake) ?? {} };
+      } catch (err) {
+        log.warn("reserved connection rejected for role={role} {error}", { role: reserved.role, error: err });
+        return refuseAfterUpgrade(reserved.subprotocol, err);
+      }
+    } else {
+      try {
+        auth = await hooks.authenticate(handshake);
+      } catch (err) {
+        log.warn("authenticate threw \u2014 refusing the connection {error}", { error: err });
+        if (err instanceof SuperLineError && err.code === "UNAUTHORIZED") return refuseAfterUpgrade(void 0, err);
+        return new Response("Unauthorized", { status: 401 });
+      }
+    }
+    const id = auth.connectionId ?? crypto.randomUUID();
+    const [client, server] = Object.values(new WebSocketPair());
+    ctx.acceptWebSocket(server, [id]);
+    server.serializeAttachment({ id });
+    hooks.onConnection(adopt(server, id), { ...auth, connectionId: id });
+    return new Response(null, {
+      status: 101,
+      webSocket: client,
+      ...reserved?.subprotocol ? { headers: { "Sec-WebSocket-Protocol": reserved.subprotocol } } : {}
+    });
+  }
+  async function resume() {
+    const adoptConnection = hooks?.adoptConnection;
+    const live = /* @__PURE__ */ new Set();
+    for (const ws of ctx.getWebSockets()) {
+      const id = ws.deserializeAttachment()?.id;
+      const row = id ? sql.exec(`SELECT snapshot FROM ${SNAPSHOTS} WHERE id = ?`, id).toArray()[0] : void 0;
+      if (!id || !row || !adoptConnection) {
+        ws.close(CLOSE_NOT_RESUMABLE, "connection could not be resumed");
+        continue;
+      }
+      live.add(id);
+      try {
+        await adoptConnection(adopt(ws, id), JSON.parse(row.snapshot));
+      } catch (err) {
+        log.error("resuming connection {id} failed {error}", { id, error: err });
+        conns.delete(ws);
+        ws.close(CLOSE_NOT_RESUMABLE, "connection could not be resumed");
+      }
+    }
+    for (const { id } of sql.exec(`SELECT id FROM ${SNAPSHOTS}`).toArray())
+      if (!live.has(id)) sql.exec(`DELETE FROM ${SNAPSHOTS} WHERE id = ?`, id);
+  }
+  return {
+    liveness: "socket",
+    start(h) {
+      hooks = h;
+      return Promise.resolve().then(resume);
+    },
+    stop() {
+      hooks = void 0;
+    },
+    onSnapshotChanged(id, snapshot) {
+      sql.exec(`INSERT OR REPLACE INTO ${SNAPSHOTS} (id, snapshot) VALUES (?, ?)`, id, JSON.stringify(snapshot));
+    },
+    onHold(count) {
+      if (count > 0 && busy === void 0) busy = setInterval(() => {
+      }, 3e4);
+      if (count === 0 && busy !== void 0) {
+        clearInterval(busy);
+        busy = void 0;
+      }
+    },
+    fetch,
+    webSocketMessage(ws, message) {
+      const conn = conns.get(ws);
+      if (!conn) {
+        ws.close(CLOSE_NOT_RESUMABLE, "connection could not be resumed");
+        return;
+      }
+      conn.deliver(typeof message === "string" ? encoder.encode(message) : new Uint8Array(message));
+    },
+    webSocketClose(ws, code, reason) {
+      conns.get(ws)?.closed(code, reason);
+    },
+    webSocketError(ws) {
+      conns.get(ws)?.closed(1006);
+    }
+  };
+}
+var DurableConn = class {
+  constructor(ws, id, onGone) {
+    this.ws = ws;
+    this.id = id;
+    this.onGone = onGone;
+  }
+  ws;
+  id;
+  onGone;
+  msgCb;
+  closeCb;
+  done = false;
+  get writable() {
+    return !this.done && this.ws.readyState === WebSocket.OPEN;
+  }
+  send(bytes) {
+    if (this.writable) this.ws.send(bytes);
+  }
+  onMessage(cb) {
+    this.msgCb = cb;
+  }
+  onClose(cb) {
+    this.closeCb = cb;
+  }
+  onDrain() {
+  }
+  // the platform exposes no send-buffer signal
+  close(code = 1e3, reason) {
+    if (this.done) return;
+    this.ws.close(code, reason);
+    this.closed(code, reason);
+  }
+  terminate() {
+    this.close(1011, "terminated");
+  }
+  deliver(bytes) {
+    if (!this.done) this.msgCb?.(bytes);
+  }
+  closed(code, reason) {
+    if (this.done) return;
+    this.done = true;
+    this.closeCb?.(code, reason);
+    this.onGone();
+  }
+};
+function buildHandshake(request) {
+  const url = new URL(request.url);
+  const query = {};
+  for (const [k, v] of url.searchParams) query[k] = v;
+  const headers = {};
+  request.headers.forEach((v, k) => {
+    headers[k] = v;
+  });
+  return { transport: "cloudflare", headers, query, raw: request };
+}
+function reservedFor(list, request, handshake) {
+  if (list.length === 0) return void 0;
+  const offered = (request.headers.get("Sec-WebSocket-Protocol") ?? "").split(",").map((p) => p.trim());
+  return list.find((rc) => rc.subprotocol && offered.includes(rc.subprotocol)) ?? list.find((rc) => rc.match?.(handshake));
+}
+function refuseAfterUpgrade(subprotocol, err) {
+  const [client, server] = Object.values(new WebSocketPair());
+  server.accept();
+  server.close(4401, truncateReason(err instanceof Error && err.message ? err.message : "unauthorized"));
+  return new Response(null, { status: 101, webSocket: client, ...subprotocol ? { headers: { "Sec-WebSocket-Protocol": subprotocol } } : {} });
+}
+function truncateReason(reason) {
+  const bytes = encoder.encode(reason);
+  return bytes.length <= 123 ? reason : new TextDecoder().decode(bytes.slice(0, 123)).replace(/�$/, "");
+}
+
+// src/node.ts
+import { DurableObject } from "cloudflare:workers";
+function createDurableNode(build) {
+  return class DurableNode extends DurableObject {
+    transport;
+    server;
+    constructor(ctx, env) {
+      super(ctx, env);
+      this.transport = cloudflareServerTransport(ctx);
+      this.server = build(ctx, env, { transports: [this.transport], nodeKey: ctx.id.toString() });
+      void ctx.blockConcurrencyWhile(() => this.server.ready);
+    }
+    fetch(request) {
+      return this.transport.fetch(request);
+    }
+    webSocketMessage(ws, message) {
+      this.transport.webSocketMessage(ws, message);
+    }
+    webSocketClose(ws, code, reason) {
+      this.transport.webSocketClose(ws, code, reason);
+    }
+    webSocketError(ws, error) {
+      this.transport.webSocketError(ws, error);
+    }
+  };
+}
+function routeToNode(request, namespace, opts = {}) {
+  return namespace.getByName(opts.name?.(request) ?? "super-line").fetch(request);
+}
+export {
+  CLOSE_NOT_RESUMABLE,
+  cloudflareServerTransport,
+  createDurableNode,
+  routeToNode
+};

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@super-line/transport-cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Cloudflare Durable Object transport for super-line: one Durable Object is one node, with hibernatable WebSockets that resume transparently on wake.",
+  "license": "MIT",
+  "author": "Mert",
+  "keywords": [
+    "super-line",
+    "transport",
+    "cloudflare",
+    "durable-objects",
+    "websocket",
+    "hibernation",
+    "realtime"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mertdogar/super-line.git",
+    "directory": "packages/transport-cloudflare"
+  },
+  "homepage": "https://mertdogar.github.io/super-line/",
+  "bugs": "https://github.com/mertdogar/super-line/issues",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@logtape/logtape": "^2.2.4"
+  },
+  "peerDependencies": {
+    "@super-line/core": ">=0.21.0 <1.0.0",
+    "@super-line/server": ">=0.22.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261013.1",
+    "@super-line/core": "^0.22.0",
+    "@super-line/server": "^0.23.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
 }