@buley/relay 4.1.0 → 4.2.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { SyncRoom } from "./sync-room";
+interface Env {
+    SYNC_ROOM: DurableObjectNamespace<SyncRoom>;
+}
+export { SyncRoom };
+declare const _default: {
+    fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,UAAU,GAAG;IACX,SAAS,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC;CAC7C;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC;;mBAGG,OAAO,OAAO,GAAG,OAAO,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;;AADnF,wBAcE"}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { SyncRoom } from "./sync-room";
+export { SyncRoom };
+export default {
+    async fetch(request, env, ctx) {
+        const url = new URL(request.url);
+        const path = url.pathname.slice(1).split("/"); // ["sync", "roomName"]
+        if (path[0] === "sync" && path[1]) {
+            const roomName = path[1];
+            const id = env.SYNC_ROOM.idFromName(roomName);
+            const stub = env.SYNC_ROOM.get(id);
+            return stub.fetch(request);
+        }
+        return new Response("Not Found", { status: 404 });
+    },
+};

package/dist/sync-room.d.ts

@@ -0,0 +1,17 @@
+import { DurableObject } from "cloudflare:workers";
+interface Env {
+    BACKUPS: R2Bucket;
+}
+export declare class SyncRoom extends DurableObject<Env> {
+    sql: SqlStorage;
+    constructor(ctx: DurableObjectState, env: Env);
+    fetch(request: Request): Promise<Response>;
+    handleWebTransportSession(session: any): Promise<void>;
+    handleStream(stream: any): Promise<void>;
+    webSocketMessage(ws: WebSocket, message: ArrayBuffer | string): Promise<void>;
+    private broadcast;
+    webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean): Promise<void>;
+    alarm(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=sync-room.d.ts.map

package/dist/sync-room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-room.d.ts","sourceRoot":"","sources":["../src/sync-room.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,UAAU,GAAG;IACX,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED,qBAAa,QAAS,SAAQ,aAAa,CAAC,GAAG,CAAC;IAC9C,GAAG,EAAE,UAAU,CAAC;gBAEJ,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,GAAG;IAcvC,KAAK,CAAC,OAAO,EAAE,OAAO;IAkDtB,yBAAyB,CAAC,OAAO,EAAE,GAAG;IAgBtC,YAAY,CAAC,MAAM,EAAE,GAAG;IAuCxB,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM;IAqBnE,OAAO,CAAC,SAAS;IAaX,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO;IAI7E,KAAK;CAgBZ"}

package/dist/sync-room.js

@@ -0,0 +1,159 @@
+import { DurableObject } from "cloudflare:workers";
+import * as ucans from 'ucans';
+export class SyncRoom extends DurableObject {
+    sql;
+    constructor(ctx, env) {
+        super(ctx, env);
+        this.sql = ctx.storage.sql;
+        // Initialize Schema
+        this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS messages (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        data BLOB,
+        created_at INTEGER DEFAULT (strftime('%s', 'now'))
+      );
+    `);
+    }
+    async fetch(request) {
+        // 0. UCAN Verification
+        const url = new URL(request.url);
+        const token = url.searchParams.get("token");
+        if (!token) {
+            return new Response("Unauthorized: Missing UCAN", { status: 401 });
+        }
+        try {
+            const result = await ucans.verify(token, {
+                // In a real system, you would verify against a root DID or specific issuer.
+                // For this P2P/Star architecture, we check if the signature is valid 
+                // and if it grants access to THIS room.
+                audience: "did:web:relay.buley.dev",
+                requiredCapabilities: [
+                    {
+                        capability: {
+                            with: { scheme: "room", hierPart: `//${url.pathname.split('/').pop()}` },
+                            can: { namespace: "room", segments: ["write"] }
+                        },
+                        rootIssuer: null // Allow self-issued for now (P2P style)
+                    }
+                ]
+            });
+            if (!result.ok) {
+                return new Response(`Unauthorized: Invalid UCAN - ${result.error}`, { status: 403 });
+            }
+        }
+        catch (e) {
+            return new Response("Unauthorized: Malformed Token", { status: 403 });
+        }
+        // 1. WebSocket Upgrade
+        if (request.headers.get("Upgrade") === "websocket") {
+            const pair = new WebSocketPair();
+            const [client, server] = Object.values(pair);
+            this.ctx.acceptWebSocket(server);
+            return new Response(null, { status: 101, webSocket: client });
+        }
+        // 2. WebTransport Session
+        // Note: Use 'webtransport' npm package or specific Cloudflare types if available.
+        // For this snippet, we assume the environment passes a session or we accept it.
+        // This logic demonstrates the BYOB loop requested.
+        return new Response("Expected WebSocket Upgrade", { status: 426 });
+    }
+    async handleWebTransportSession(session) {
+        // 1. Accept incoming streams
+        const reader = session.incomingBidirectionalStreams.getReader();
+        try {
+            while (true) {
+                const { value: stream, done } = await reader.read();
+                if (done)
+                    break;
+                // Handle individual stream with BYOB
+                this.handleStream(stream);
+            }
+        }
+        catch (e) {
+            // session closed
+        }
+    }
+    async handleStream(stream) {
+        // 2. Zero-Copy Reader (BYOB)
+        let reader;
+        try {
+            reader = stream.readable.getReader({ mode: 'byob' });
+        }
+        catch (e) {
+            reader = stream.readable.getReader();
+        }
+        // Buffer Reuse (Zero Allocation Loop)
+        let buffer = new Uint8Array(65536);
+        try {
+            while (true) {
+                let result;
+                if (reader.readAtLeast) {
+                    // Pass view to kernel/runtime
+                    result = await reader.read(new Uint8Array(buffer.buffer, 0, buffer.byteLength));
+                    if (result.value)
+                        buffer = result.value; // Valid buffer returned
+                }
+                else {
+                    result = await reader.read();
+                }
+                if (result.done)
+                    break;
+                if (result.value) {
+                    // 3. Zero-Copy Insert to Native SQLite
+                    // The buffer 'result.value' contains the data directly from the network packet
+                    this.sql.exec("INSERT INTO messages (data) VALUES (?)", result.value);
+                    // 4. Broadcast (Zero-Copy to outbound buffers?)
+                    // Cloudflare's WebSocket.send() accepts ArrayBuffer, so no copy needed here either ideally.
+                    this.broadcast(result.value);
+                }
+            }
+        }
+        catch (e) {
+            // stream error
+        }
+    }
+    async webSocketMessage(ws, message) {
+        // 1. Store Delta (Zero Latency)
+        // We assume message is a binary CRDT update
+        const data = typeof message === 'string' ? new TextEncoder().encode(message) : message;
+        this.sql.exec("INSERT INTO messages (data) VALUES (?)", data);
+        this.sql.exec("INSERT INTO messages (data) VALUES (?)", data);
+        // 2. Broadcast to others
+        this.broadcast(message, ws);
+        // 3. Set Alarm for Write-back (Debounced)
+        // Hibernation Note: The alarm will wake the DO up even if all clients are hibernating.
+        const currentAlarm = await this.ctx.storage.getAlarm();
+        if (currentAlarm === null) {
+            // Set alarm for 10 seconds from now
+            await this.ctx.storage.setAlarm(Date.now() + 10000);
+        }
+    }
+    broadcast(message, exclude) {
+        // Determine the message to send once
+        for (const client of this.ctx.getWebSockets()) {
+            if (client !== exclude) {
+                try {
+                    client.send(message);
+                }
+                catch (e) {
+                    // fast-fail on dead sockets
+                }
+            }
+        }
+    }
+    async webSocketClose(ws, code, reason, wasClean) {
+        // Clean up if needed
+    }
+    async alarm() {
+        // 1. Snapshot SQLite to R2
+        // In a real app, you might maintain a separate logical "Document" file
+        // Here we just backup the raw messages for safety.
+        const messages = this.sql.exec("SELECT * FROM messages").toArray();
+        const blob = JSON.stringify(messages); // Simple serialization for backup
+        const key = `backups/${this.ctx.id.toString()}/${Date.now()}.json`;
+        await this.env.BACKUPS.put(key, blob);
+        // Optional: Truncate local history if relying on full-state sync later
+        // this.sql.exec("DELETE FROM messages");
+        console.log(`Backed up ${messages.length} messages to ${key}`);
+    }
+}

package/package.json

@@ -1,15 +1,31 @@
 {
   "name": "@buley/relay",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",
-    "build": "wrangler deploy --dry-run --outdir dist",
+    "build": "tsc -p tsconfig.build.json && wrangler deploy --dry-run --outdir dist",
+    "build:types": "tsc -p tsconfig.build.json",
     "test": "NODE_OPTIONS=--experimental-vm-modules vitest"
   },
   "dependencies": {
-    "hono": "^3.12.0"
+    "hono": "^3.12.0",
+    "ucans": "^0.10.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20240117.0",

package/.wrangler/state/v3/r2/dash-backups/blobs/1e21a245f3806f7a14fd8a54bdca8770c80cfd9eac610b042abe42a182df59600000019bee6f5cb7

@@ -1 +0,0 @@
-[{"id":1,"data":{},"created_at":1769231824},{"id":2,"data":{},"created_at":1769231825}]

package/CHANGELOG.md

@@ -1,17 +0,0 @@
-# Changelog
-
-## [4.1.0] - 2026-01-23
-
-### Improvements
-
-- **Hibernation Refinements**: Explicit broadcast handling and improved comments for Cloudflare Hibernation behavior.
-- **Code Cleanup**: Extracted broadcast logic.
-
-## [4.0.0] - 2026-01-23
-
-### Features
-
-- Initial release of `@buley/relay`.
-- "Stateful Serverless" architecture using Cloudflare Durable Objects.
-- Native SQLite support.
-- Hybrid WebSocket/WebTransport Sync Protocol.

package/src/index.ts

@@ -1,23 +0,0 @@
-import { SyncRoom } from "./sync-room";
-
-interface Env {
-  SYNC_ROOM: DurableObjectNamespace<SyncRoom>;
-}
-
-export { SyncRoom };
-
-export default {
-  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
-    const url = new URL(request.url);
-    const path = url.pathname.slice(1).split("/"); // ["sync", "roomName"]
-
-    if (path[0] === "sync" && path[1]) {
-      const roomName = path[1];
-      const id = env.SYNC_ROOM.idFromName(roomName);
-      const stub = env.SYNC_ROOM.get(id);
-      return stub.fetch(request);
-    }
-
-    return new Response("Not Found", { status: 404 });
-  },
-};

package/src/sync-room.ts

@@ -1,95 +0,0 @@
-import { DurableObject } from "cloudflare:workers";
-
-interface Env {
-  BACKUPS: R2Bucket;
-}
-
-export class SyncRoom extends DurableObject<Env> {
-  sql: SqlStorage;
-  
-  constructor(ctx: DurableObjectState, env: Env) {
-    super(ctx, env);
-    this.sql = ctx.storage.sql;
-    
-    // Initialize Schema
-    this.sql.exec(`
-      CREATE TABLE IF NOT EXISTS messages (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        data BLOB,
-        created_at INTEGER DEFAULT (strftime('%s', 'now'))
-      );
-    `);
-  }
-
-  async fetch(request: Request) {
-    // 1. WebSocket Upgrade
-    if (request.headers.get("Upgrade") === "websocket") {
-      const pair = new WebSocketPair();
-      const [client, server] = Object.values(pair);
-      
-      this.ctx.acceptWebSocket(server);
-      return new Response(null, { status: 101, webSocket: client });
-    }
-
-    // 2. WebTransport Session (Example - requires parsing Connect)
-    // For simplicity in this v1, we focus on the WebSocket 'Hibernate' path
-    // accessible via fetch post for high-throughput if needed, or upgrade.
-    
-    return new Response("Expected WebSocket Upgrade", { status: 426 });
-  }
-
-  async webSocketMessage(ws: WebSocket, message: ArrayBuffer | string) {
-    // 1. Store Delta (Zero Latency)
-    // We assume message is a binary CRDT update
-    const data = typeof message === 'string' ? new TextEncoder().encode(message) : message;
-    
-    this.sql.exec("INSERT INTO messages (data) VALUES (?)", data as any);
-
-    this.sql.exec("INSERT INTO messages (data) VALUES (?)", data as any);
-
-    // 2. Broadcast to others
-    this.broadcast(message, ws);
-
-    // 3. Set Alarm for Write-back (Debounced)
-    // Hibernation Note: The alarm will wake the DO up even if all clients are hibernating.
-    const currentAlarm = await this.ctx.storage.getAlarm();
-    if (currentAlarm === null) {
-      // Set alarm for 10 seconds from now
-      await this.ctx.storage.setAlarm(Date.now() + 10000);
-    }
-  }
-
-  private broadcast(message: ArrayBuffer | string, exclude?: WebSocket) {
-    // Determine the message to send once
-    for (const client of this.ctx.getWebSockets()) {
-      if (client !== exclude) {
-        try {
-            client.send(message);
-        } catch (e) {
-            // fast-fail on dead sockets
-        }
-      }
-    }
-  }
-
-  async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
-    // Clean up if needed
-  }
-
-  async alarm() {
-    // 1. Snapshot SQLite to R2
-    // In a real app, you might maintain a separate logical "Document" file
-    // Here we just backup the raw messages for safety.
-    
-    const messages = this.sql.exec("SELECT * FROM messages").toArray();
-    const blob = JSON.stringify(messages); // Simple serialization for backup
-    
-    const key = `backups/${this.ctx.id.toString()}/${Date.now()}.json`;
-    await this.env.BACKUPS.put(key, blob);
-    
-    // Optional: Truncate local history if relying on full-state sync later
-    // this.sql.exec("DELETE FROM messages");
-    
-    console.log(`Backed up ${messages.length} messages to ${key}`);
-  }
-}

package/test/index.spec.ts

@@ -1,72 +0,0 @@
-// @vitest-environment miniflare
-import { describe, it, expect, vi } from "vitest";
-
-// In vitest-environment-miniflare, bindings are often exposed as globals directly.
-declare global {
-  var SYNC_ROOM: DurableObjectNamespace;
-  var BACKUPS: R2Bucket;
-}
-
-describe("SyncRoom", () => {
-  it("should upgrade to websocket", async () => {
-    const id = SYNC_ROOM.idFromName("test-room");
-    const stub = SYNC_ROOM.get(id);
-    
-    // Simulate WebSocket Upgrade Request
-    const resp = await stub.fetch("http://localhost/sync/test-room", {
-      headers: { Upgrade: "websocket" },
-    });
-        expect(resp.status).toBe(101);
-  });
-  
-  it("should store messages and broadcast", async () => {
-     const id = SYNC_ROOM.idFromName("room-2");
-     const stub = SYNC_ROOM.get(id);
-     
-     const { webSocket: ws1, response: resp1 } = await stub.fetch("http://localhost/sync/room-2", {
-        headers: { Upgrade: "websocket" },
-     });
-     expect(resp1.status).toBe(101);
-     
-     const { webSocket: ws2, response: resp2 } = await stub.fetch("http://localhost/sync/room-2", {
-        headers: { Upgrade: "websocket" },
-     });
-     expect(resp2.status).toBe(101);
-
-     if (!ws1 || !ws2) throw new Error("Failed to get sockets");
-     
-     ws1.accept();
-     ws2.accept();
-     
-     const received: any[] = [];
-     ws2.addEventListener("message", (event) => received.push(event.data));
-     
-     // Send Message
-     const data = new Uint8Array([1, 2, 3]);
-     ws1.send(data);
-     
-     // Wait for broadcast
-     await new Promise(r => setTimeout(r, 200));
-     
-     expect(received.length).toBe(1);
-     // Note: Miniflare/Workerd might deliver as string or blob depending on config, checking length for now
-  });
-
-  it("should trigger backup alarm", async () => {
-      // Alarm testing is tricky in unit tests without advancing time.
-      // We can check if alarm is set.
-      const id = SYNC_ROOM.idFromName("room-alarm");
-      const stub = SYNC_ROOM.get(id);
-      
-      
-      const { webSocket: ws1 } = await stub.fetch("http://localhost", { headers: { Upgrade: "websocket" } });
-      ws1?.accept();
-      ws1?.send("test data");
-      
-      // Wait for write
-       await new Promise(r => setTimeout(r, 100));
-       
-      // Unfortunately we can't easily inspect DO internal state from outside unless we add a debug endpoint.
-      // For 100% coverage, we trust the integration or add a method to SyncRoom exposed for testing.
-  });
-});

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "esnext",
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "types": ["@cloudflare/workers-types/2023-07-01"],
-    "strict": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": ["src/**/*"]
-}

package/vitest.config.ts

@@ -1,23 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "miniflare",
-    environmentOptions: {
-      modules: true,
-      scriptPath: "dist/index.js",
-      compatibilityDate: "2024-04-01",
-      shouldLog: true,
-      bindings: { BACKUPS: { type: "R2Bucket" } },
-      durableObjects: {
-        SYNC_ROOM: "SyncRoom",
-      },
-      migrations: [
-          {
-              tag: "v1",
-              new_sqlite_classes: ["SyncRoom"],
-          }
-      ]
-    },
-  },
-});

package/wrangler.toml

@@ -1,22 +0,0 @@
-name = "dash-relay"
-main = "src/index.ts"
-compatibility_date = "2024-01-17"
-
-# Durable Object Bindings
-[[durable_objects.bindings]]
-name = "SYNC_ROOM"
-class_name = "SyncRoom"
-
-# Durable Object Migrations (Required for Native SQLite)
-[[migrations]]
-tag = "v1"
-new_classes = []
-new_sqlite_classes = ["SyncRoom"]
-
-# R2 Bucket for Backups (Alarms)
-[[r2_buckets]]
-binding = "BACKUPS"
-bucket_name = "dash-backups"
-
-[triggers]
-crons = []