@weft-js/realtime-durable-object 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+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,9 @@
-# Temporary Holding Version
+# @weft-js/realtime-durable-object
 
-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.
+> **Early release (0.1.0).** APIs will change between minor versions.
+
+A Cloudflare Durable Object as the realtime bus, on cloudflare_durable.
+
+```bash
+npm install @weft-js/realtime-durable-object
+```

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@weft-js/realtime-durable-object",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "@weft-js/realtime-durable-object: a Cloudflare Durable Object as the realtime bus, on cloudflare_durable",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin": "./plugin.mjs"
+  },
+  "peerDependencies": {
+    "@weft-js/start": "^0.1.0",
+    "@weft-js/core": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "plugin.mjs",
+    "plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "overrides": {
+    "undici": "7.30.1",
+    "sharp": "0.35.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.d.mts

@@ -0,0 +1,5 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** `durableObject()` for `weft.config.ts`: declares the `WEFT_BUS` binding. The bus itself is set in `src/realtime.server.ts`. */
+export default plugin

package/plugin.mjs

@@ -0,0 +1,15 @@
+// durableObject() for weft.config.ts: declares what the bus reaches. A binding only exists at run time, so unlike the
+// other buses it can't be built from options: `src/realtime.server.ts` sets `durableObjectBus({ namespace })`.
+import { definePlugin } from '@weft-js/core/plugin'
+
+export const durableObject = definePlugin({
+  name: '@weft-js/realtime-durable-object',
+  version: '0.1.0',
+  weft: '*',
+  permissions: { net: ['binding:WEFT_BUS'] },
+  contribute: () => ({
+    agents: { title: 'Realtime bus (Durable Object)', text: 'Set `bus: durableObjectBus({ namespace: env.WEFT_BUS })` in `src/realtime.server.ts`, and export `WeftBusObject` from the worker with a `new_sqlite_classes` migration. It needs the `cloudflare_durable` preset (R002): a stateless Worker can\'t hold the socket.' },
+  }),
+})
+
+export default durableObject

package/src/index.ts

@@ -0,0 +1,85 @@
+// A Durable Object per channel (research 32 §6). `WeftBusObject` holds the sockets, through the hibernation API, and
+// nothing else: a publish is a POST it writes to all of them. A hub's subscribe is a WebSocket to the object, and a
+// lost one is a `gap`. No runtime imports, so workerd can run this file as it is.
+//
+// A Worker's I/O belongs to the request that opened it, so a stateless Worker can't hold that socket: this needs a hub
+// that lives in a Durable Object, Nitro's `cloudflare_durable` preset (`weft build` refuses the others, R002).
+
+import type { Bus } from '@weft-js/start/bus'
+
+/** The parts of Workers' API used here, so an app doesn't need `@cloudflare/workers-types` for this file. */
+interface Stub { fetch(url: string, init?: RequestInit): Promise<Response & { webSocket?: CfSocket | null }> }
+/** A Durable Object namespace binding, as far as the bus uses one: `env.WEFT_BUS` fits it. */
+export interface DurableObjectNamespaceLike { idFromName(name: string): unknown; get(id: unknown): Stub }
+interface CfSocket { accept(): void; send(m: string): void; close(code?: number): void; addEventListener(t: string, f: (e: { data?: unknown }) => void): void }
+interface CfState { acceptWebSocket(ws: CfSocket): void; getWebSockets(): CfSocket[] }
+declare const WebSocketPair: new () => [CfSocket, CfSocket]
+
+const BASE = 'https://weft-bus/'
+
+/** Export it from the worker entry and bind it: `new_sqlite_classes: ['WeftBusObject']`, binding `WEFT_BUS`. */
+export class WeftBusObject {
+  constructor(private state: CfState, _env?: unknown) {}
+
+  async fetch(request: Request): Promise<Response> {
+    if (request.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+      const pair = new WebSocketPair()
+      this.state.acceptWebSocket(pair[1])
+      return new Response(null, { status: 101, webSocket: pair[0] } as ResponseInit)
+    }
+    const message = await request.text()
+    for (const ws of this.state.getWebSockets()) {
+      try { ws.send(message) } catch {} // a socket mid-close: its own `gap` covers it
+    }
+    return new Response(null, { status: 204 })
+  }
+
+  webSocketMessage() {}
+  webSocketClose(ws: CfSocket) {
+    try { ws.close(1000) } catch {}
+  }
+}
+
+/** The `realtime.bus` for `src/realtime.server.ts`: one `WeftBusObject` per channel, which must be reached from a Durable Object hub. */
+export function durableObjectBus({ namespace }: { namespace: DurableObjectNamespaceLike }): Bus {
+  const stub = (channel: string) => namespace.get(namespace.idFromName(channel))
+  const open = new Set<() => void>()
+  return {
+    name: 'durable-object',
+    async publish(channel, message) {
+      const res = await stub(channel).fetch(BASE, { method: 'POST', body: message })
+      if (!res.ok) throw new Error(`durable object bus: publish answered ${res.status}`)
+    },
+    async subscribe(channel, on, gap) {
+      let stopped = false, attempt = 0, ws: CfSocket | undefined
+      const dial = async (): Promise<void> => {
+        const res = await stub(channel).fetch(BASE, { headers: { upgrade: 'websocket' } })
+        ws = res.webSocket ?? undefined
+        if (!ws) throw new Error(`durable object bus: subscribe answered ${res.status}`)
+        ws.accept()
+        if (stopped) return ws.close(1000) // stopped while this redial was out
+        ws.addEventListener('message', e => on(String(e.data)))
+        const lost = () => {
+          ws = undefined
+          if (stopped) return
+          gap?.()
+          setTimeout(() => void dial().then(() => { attempt = 0 }, lost), Math.min(30_000, 500 * 2 ** attempt++))
+        }
+        ws.addEventListener('close', lost)
+        ws.addEventListener('error', () => {})
+      }
+      await dial()
+      const stop = () => {
+        stopped = true
+        open.delete(stop)
+        try { ws?.close(1000) } catch {}
+      }
+      open.add(stop)
+      return stop
+    },
+    close() {
+      for (const stop of open) stop()
+      return Promise.resolve()
+    },
+  }
+}