@b9g/platform-cloudflare 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform-cloudflare",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Cloudflare Workers platform adapter for Shovel - already ServiceWorker-based!",
   "keywords": [
     "shovel",
@@ -12,16 +12,16 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/bikeshaving/shovel.git",
+    "url": "git+https://github.com/bikeshaving/shovel.git",
     "directory": "packages/platform-cloudflare"
   },
   "dependencies": {
     "@b9g/assets": "^0.2.1",
     "@b9g/async-context": "^0.2.1",
     "@b9g/cache": "^0.2.2",
-    "@b9g/filesystem": "^0.1.10",
-    "@b9g/platform": "^0.1.17",
-    "@logtape/logtape": "^1.2.0",
+    "@b9g/filesystem": "^0.2.0",
+    "@b9g/platform": "^0.1.18",
+    "@logtape/logtape": "^2.0.0",
     "mime": "^4.0.4",
     "miniflare": "^4.20251118.1"
   },
@@ -84,6 +84,15 @@
     "./platform.js": {
       "types": "./src/platform.d.ts",
       "import": "./src/platform.js"
-    }
+    },
+    "./pubsub": {
+      "types": "./src/pubsub.d.ts",
+      "import": "./src/pubsub.js"
+    },
+    "./pubsub.js": {
+      "types": "./src/pubsub.d.ts",
+      "import": "./src/pubsub.js"
+    },
+    "./cloudflare.d.ts": "./src/cloudflare.d.ts"
   }
 }

package/src/caches.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./cloudflare.d.ts" />
 /**
  * Cloudflare Native Cache
  *

package/src/cloudflare.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Minimal Cloudflare Workers type declarations.
+ *
+ * We declare only the types this package needs rather than using
+ * @cloudflare/workers-types globally, which would pollute Request/Response
+ * with Cloudflare-specific generics across the entire monorepo.
+ */
+
+// cloudflare:workers module (runtime imports)
+declare module "cloudflare:workers" {
+	export abstract class DurableObject {
+		ctx: DurableObjectState;
+		env: Record<string, unknown>;
+		constructor(ctx: DurableObjectState, env: Record<string, unknown>);
+		fetch?(request: Request): Promise<Response>;
+		alarm?(): Promise<void>;
+		webSocketMessage?(
+			ws: WebSocket,
+			message: string | ArrayBuffer,
+		): Promise<void>;
+		webSocketClose?(
+			ws: WebSocket,
+			code: number,
+			reason: string,
+			wasClean: boolean,
+		): Promise<void>;
+		webSocketError?(ws: WebSocket, error: unknown): Promise<void>;
+	}
+}
+
+// Cloudflare-specific globals available in the Workers runtime
+declare class DurableObjectState {
+	id: DurableObjectId;
+	storage: DurableObjectStorage;
+	acceptWebSocket(ws: WebSocket, tags?: string[]): void;
+	getWebSockets(tag?: string): WebSocket[];
+	waitUntil(promise: Promise<unknown>): void;
+}
+
+declare class DurableObjectStorage {
+	get<T = unknown>(key: string): Promise<T | undefined>;
+	get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+	put<T>(key: string, value: T): Promise<void>;
+	put<T>(entries: Record<string, T>): Promise<void>;
+	delete(key: string): Promise<boolean>;
+	delete(keys: string[]): Promise<number>;
+	list<T = unknown>(options?: {
+		prefix?: string;
+		limit?: number;
+	}): Promise<Map<string, T>>;
+}
+
+declare class DurableObjectId {
+	toString(): string;
+	readonly name?: string;
+}
+
+declare interface DurableObjectNamespace {
+	newUniqueId(): DurableObjectId;
+	idFromName(name: string): DurableObjectId;
+	idFromString(id: string): DurableObjectId;
+	get(id: DurableObjectId): DurableObjectStub;
+}
+
+declare interface DurableObjectStub {
+	readonly id: DurableObjectId;
+	readonly name?: string;
+	fetch(requestOrUrl: string | Request, init?: RequestInit): Promise<Response>;
+}
+
+declare var WebSocketPair: {
+	new (): {0: WebSocket; 1: WebSocket};
+};
+
+// Augment Response constructor options for Cloudflare's webSocket field
+declare interface ResponseInit {
+	webSocket?: WebSocket;
+}
+
+// Augment WebSocket with Cloudflare's accept() method
+interface WebSocket {
+	accept(): void;
+}

package/src/directories.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./cloudflare.d.ts" />
 /**
  * Cloudflare Directory Implementations
  *

package/src/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./cloudflare.d.ts" />
 /**
  * @b9g/platform-cloudflare - Cloudflare Workers platform adapter for Shovel
  *

package/src/index.js

@@ -252,6 +252,7 @@ export default { fetch: createFetchHandler(registration) };
       // Include both node:* prefix and bare module names for compatibility
       external: [
         "node:*",
+        "cloudflare:*",
         "path",
         "fs",
         "fs/promises",

package/src/platform.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./cloudflare.d.ts" />
 /**
  * Cloudflare Platform Module
  *

package/src/platform.js

@@ -1,6 +1,7 @@
 /// <reference types="./platform.d.ts" />
 // src/platform.ts
 import { getLogger } from "@logtape/logtape";
+import { dirname, join } from "path";
 var logger = getLogger(["shovel", "platform"]);
 var name = "cloudflare";
 function getEntryPoints(userEntryPath, _mode) {
@@ -26,6 +27,7 @@ function getESBuildConfig() {
     conditions: ["worker", "browser"],
     external: [
       "node:*",
+      "cloudflare:*",
       "path",
       "fs",
       "fs/promises",
@@ -57,14 +59,20 @@ async function createDevServer(options) {
   const { port, host, workerPath } = options;
   logger.info("Starting Miniflare dev server", { workerPath });
   const { Miniflare } = await import("miniflare");
-  let miniflare = new Miniflare({
+  const publicDir = join(dirname(dirname(workerPath)), "public");
+  const getMiniflareOptions = (scriptPath) => ({
     modules: true,
-    scriptPath: workerPath,
+    scriptPath,
     compatibilityDate: "2024-09-23",
     compatibilityFlags: ["nodejs_compat"],
     port,
-    host
+    host,
+    assets: {
+      directory: publicDir,
+      binding: "ASSETS"
+    }
   });
+  let miniflare = new Miniflare(getMiniflareOptions(workerPath));
   await miniflare.ready;
   logger.info("Miniflare dev server ready");
   const url = `http://${host}:${port}`;
@@ -73,14 +81,7 @@ async function createDevServer(options) {
     async reload(newWorkerPath) {
       logger.info("Reloading Miniflare", { workerPath: newWorkerPath });
       await miniflare.dispose();
-      miniflare = new Miniflare({
-        modules: true,
-        scriptPath: newWorkerPath,
-        compatibilityDate: "2024-09-23",
-        compatibilityFlags: ["nodejs_compat"],
-        port,
-        host
-      });
+      miniflare = new Miniflare(getMiniflareOptions(newWorkerPath));
       await miniflare.ready;
       logger.info("Miniflare reloaded");
     },

package/src/pubsub.d.ts

@@ -0,0 +1,46 @@
+/// <reference path="./cloudflare.d.ts" />
+/**
+ * Cloudflare Durable Object PubSub Backend
+ *
+ * Provides cross-isolate BroadcastChannel relay via a Durable Object.
+ * - CloudflarePubSubBackend: BroadcastChannelBackend that publishes to a DO
+ * - ShovelPubSubDO: Durable Object that broadcasts to connected WebSocket clients
+ *
+ * Opt-in: only active when env.SHOVEL_PUBSUB binding is present.
+ *
+ * Architecture:
+ * - publish() sends a POST to the DO with {channel, data, sender}
+ * - subscribe() opens a WebSocket to the DO to receive broadcasts
+ * - The DO fans out POST payloads to all connected WebSocket clients
+ * - Sender filtering happens client-side (same pattern as Redis backend)
+ *
+ * Note: Cloudflare Workers are ephemeral, so WebSocket subscriptions only
+ * live as long as the Worker's execution context. For typical request/response
+ * Workers this means subscriptions are short-lived. For Durable Object contexts
+ * or Workers using waitUntil(), subscriptions can persist longer.
+ */
+import { DurableObject } from "cloudflare:workers";
+import type { BroadcastChannelBackend } from "@b9g/platform/runtime";
+/**
+ * BroadcastChannel backend that routes messages through a Durable Object.
+ *
+ * Uses an instance ID to filter out own messages (prevents echo),
+ * matching the pattern used by RedisPubSubBackend.
+ */
+export declare class CloudflarePubSubBackend implements BroadcastChannelBackend {
+    #private;
+    constructor(ns: DurableObjectNamespace);
+    publish(channelName: string, data: unknown): void;
+    subscribe(channelName: string, callback: (data: unknown) => void): () => void;
+    dispose(): Promise<void>;
+}
+/**
+ * Durable Object that fans out BroadcastChannel messages to connected
+ * WebSocket clients. Uses WebSocket Hibernation API for efficiency.
+ */
+export declare class ShovelPubSubDO extends DurableObject {
+    fetch(request: Request): Promise<Response>;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(_ws: WebSocket, _code: number, _reason: string, _wasClean: boolean): Promise<void>;
+    webSocketError(_ws: WebSocket, _error: unknown): Promise<void>;
+}

package/src/pubsub.js

@@ -0,0 +1,128 @@
+/// <reference types="./pubsub.d.ts" />
+// src/pubsub.ts
+import { DurableObject } from "cloudflare:workers";
+import { getLogger } from "@logtape/logtape";
+var logger = getLogger(["shovel", "pubsub"]);
+var CloudflarePubSubBackend = class {
+  #ns;
+  #instanceId;
+  #ws;
+  #wsReady;
+  #callbacks;
+  constructor(ns) {
+    this.#ns = ns;
+    this.#instanceId = crypto.randomUUID();
+    this.#ws = null;
+    this.#wsReady = null;
+    this.#callbacks = /* @__PURE__ */ new Map();
+  }
+  #ensureConnection() {
+    if (this.#wsReady)
+      return;
+    this.#wsReady = this.#connect().catch((err) => {
+      logger.error("PubSub WebSocket connection failed: {error}", {
+        error: err
+      });
+      this.#wsReady = null;
+    });
+  }
+  async #connect() {
+    const id = this.#ns.idFromName("pubsub");
+    const stub = this.#ns.get(id);
+    const response = await stub.fetch("http://internal/subscribe", {
+      headers: { Upgrade: "websocket" }
+    });
+    const ws = response.webSocket;
+    if (!ws) {
+      throw new Error("WebSocket upgrade to PubSub DO failed");
+    }
+    ws.accept();
+    this.#ws = ws;
+    ws.addEventListener("message", (ev) => {
+      try {
+        const { channel, data, sender } = JSON.parse(ev.data);
+        if (sender === this.#instanceId)
+          return;
+        const cbs = this.#callbacks.get(channel);
+        if (cbs) {
+          for (const cb of cbs)
+            cb(data);
+        }
+      } catch (err) {
+        logger.debug("Failed to parse pubsub message: {error}", {
+          error: err
+        });
+      }
+    });
+  }
+  publish(channelName, data) {
+    const id = this.#ns.idFromName("pubsub");
+    const stub = this.#ns.get(id);
+    stub.fetch("http://internal/broadcast", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        channel: channelName,
+        data,
+        sender: this.#instanceId
+      })
+    }).catch((err) => {
+      logger.error("PubSub publish failed: {error}", { error: err });
+    });
+  }
+  subscribe(channelName, callback) {
+    this.#ensureConnection();
+    let cbs = this.#callbacks.get(channelName);
+    if (!cbs) {
+      cbs = /* @__PURE__ */ new Set();
+      this.#callbacks.set(channelName, cbs);
+    }
+    cbs.add(callback);
+    return () => {
+      cbs.delete(callback);
+      if (cbs.size === 0)
+        this.#callbacks.delete(channelName);
+    };
+  }
+  async dispose() {
+    this.#ws?.close();
+    this.#ws = null;
+    this.#wsReady = null;
+    this.#callbacks.clear();
+  }
+};
+var ShovelPubSubDO = class extends DurableObject {
+  async fetch(request) {
+    const url = new URL(request.url);
+    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 });
+    }
+    if (request.method === "POST" && url.pathname === "/broadcast") {
+      const payload = await request.text();
+      for (const ws of this.ctx.getWebSockets()) {
+        ws.send(payload);
+      }
+      return new Response("OK");
+    }
+    return new Response("Not Found", { status: 404 });
+  }
+  async webSocketMessage(ws, message) {
+    const data = typeof message === "string" ? message : message;
+    for (const peer of this.ctx.getWebSockets()) {
+      if (peer !== ws) {
+        peer.send(data);
+      }
+    }
+  }
+  async webSocketClose(_ws, _code, _reason, _wasClean) {
+  }
+  async webSocketError(_ws, _error) {
+  }
+};
+export {
+  CloudflarePubSubBackend,
+  ShovelPubSubDO
+};

package/src/runtime.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./cloudflare.d.ts" />
 /**
  * Cloudflare Worker Runtime
  *

package/src/runtime.js

@@ -9,7 +9,8 @@ import {
   createCacheFactory,
   createDirectoryFactory,
   runLifecycle,
-  dispatchRequest
+  dispatchRequest,
+  setBroadcastChannelBackend
 } from "@b9g/platform/runtime";
 import { CustomCacheStorage } from "@b9g/cache";
 import { CustomDirectoryStorage } from "@b9g/filesystem";
@@ -50,17 +51,28 @@ async function initializeRuntime(config) {
 }
 function createFetchHandler(registration) {
   let lifecyclePromise = null;
+  let bcBackendConfigured = false;
   return async (request, env, ctx) => {
     if (!lifecyclePromise) {
       lifecyclePromise = runLifecycle(registration, "activate");
     }
     await lifecyclePromise;
+    const envRecord = env;
+    if (!bcBackendConfigured && envRecord.SHOVEL_PUBSUB) {
+      const { CloudflarePubSubBackend } = await import("./pubsub.js");
+      setBroadcastChannelBackend(
+        new CloudflarePubSubBackend(
+          envRecord.SHOVEL_PUBSUB
+        )
+      );
+      bcBackendConfigured = true;
+    }
     const event = new CloudflareFetchEvent(request, {
-      env,
+      env: envRecord,
       platformWaitUntil: (promise) => ctx.waitUntil(promise)
     });
     return envStorage.run(
-      env,
+      envRecord,
       () => dispatchRequest(registration, event)
     );
   };

package/src/variables.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./cloudflare.d.ts" />
 /**
  * Cloudflare Environment Storage
  *