@syncular/server-cloudflare 0.0.1-60

package/dist/worker.js

@@ -0,0 +1,59 @@
+/**
+ * @syncular/server-cloudflare - Worker handler (polling only)
+ *
+ * Creates a stateless Cloudflare Worker that serves sync routes via Hono.
+ * No WebSocket support — use the Durable Object adapter for realtime.
+ *
+ * @example
+ * ```typescript
+ * import { createSyncWorker } from '@syncular/server-cloudflare/worker';
+ * import { createD1Db } from '@syncular/dialect-d1';
+ * import { createSqliteServerDialect } from '@syncular/server-dialect-sqlite';
+ * import { ensureSyncSchema } from '@syncular/server';
+ * import { createSyncServer } from '@syncular/server-hono';
+ *
+ * type Env = { DB: D1Database };
+ *
+ * export default createSyncWorker<Env>((app, env) => {
+ *   const db = createD1Db(env.DB);
+ *   const dialect = createSqliteServerDialect();
+ *   const { syncRoutes, consoleRoutes } = createSyncServer({
+ *     db, dialect,
+ *     handlers: [tasksHandler],
+ *     authenticate: async (c) => ({ actorId: c.req.header('x-user-id')! }),
+ *   });
+ *   app.route('/sync', syncRoutes);
+ *   if (consoleRoutes) app.route('/console', consoleRoutes);
+ * });
+ * ```
+ */
+import { Hono } from 'hono';
+/**
+ * Create a Cloudflare Worker export that lazily initializes a Hono app.
+ *
+ * The `setup` callback is called once per isolate on the first request.
+ * It receives a fresh Hono app and the Worker env bindings.
+ */
+export function createSyncWorker(setup) {
+    let app = null;
+    let initPromise = null;
+    async function getApp(env) {
+        if (app)
+            return app;
+        if (!initPromise) {
+            const honoApp = new Hono();
+            initPromise = Promise.resolve(setup(honoApp, env)).then(() => {
+                app = honoApp;
+            });
+        }
+        await initPromise;
+        return app;
+    }
+    return {
+        async fetch(request, env, ctx) {
+            const honoApp = await getApp(env);
+            return honoApp.fetch(request, env, ctx);
+        },
+    };
+}
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAO5B;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAE9B,KAAgC,EAA6B;IAE7D,IAAI,GAAG,GAAmB,IAAI,CAAC;IAC/B,IAAI,WAAW,GAAyB,IAAI,CAAC;IAE7C,KAAK,UAAU,MAAM,CAAC,GAAa,EAAoB;QACrD,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;QACpB,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,IAAI,IAAI,EAAK,CAAC;YAC9B,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC5D,GAAG,GAAG,OAAO,CAAC;YAAA,CACf,CAAC,CAAC;QACL,CAAC;QACD,MAAM,WAAW,CAAC;QAClB,OAAO,GAAI,CAAC;IAAA,CACb;IAED,OAAO;QACL,KAAK,CAAC,KAAK,CACT,OAAgB,EAChB,GAAa,EACb,GAAqB,EACF;YACnB,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAAA,CACzC;KACF,CAAC;AAAA,CACH"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@syncular/server-cloudflare",
+  "version": "0.0.1-60",
+  "description": "Cloudflare Workers adapter for the Syncular server",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/server-cloudflare"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "cloudflare",
+    "workers",
+    "edge"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./worker": {
+      "bun": "./src/worker.ts",
+      "import": {
+        "types": "./dist/worker.d.ts",
+        "default": "./dist/worker.js"
+      }
+    },
+    "./durable-object": {
+      "bun": "./src/durable-object.ts",
+      "import": {
+        "types": "./dist/durable-object.d.ts",
+        "default": "./dist/durable-object.js"
+      }
+    },
+    "./r2": {
+      "bun": "./src/r2.ts",
+      "import": {
+        "types": "./dist/r2.d.ts",
+        "default": "./dist/r2.js"
+      }
+    }
+  },
+  "scripts": {
+    "tsgo": "tsgo --noEmit",
+    "build": "rm -rf dist && tsgo",
+    "release": "bun pm pack --destination . && npm publish ./*.tgz --tag latest && rm -f ./*.tgz"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "*",
+    "@syncular/config": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/durable-object.ts

@@ -0,0 +1,241 @@
+/**
+ * @syncular/server-cloudflare - Durable Object handler (WebSocket + polling)
+ *
+ * Provides a base DurableObject class with Hono routing and WebSocket support.
+ * The DO's stateful nature allows it to hold persistent WebSocket connections,
+ * bridging Cloudflare's hibernation API to Hono's `upgradeWebSocket` interface.
+ *
+ * @example
+ * ```typescript
+ * import { SyncDurableObject, createSyncWorkerWithDO } from '@syncular/server-cloudflare/durable-object';
+ * import { createD1Db } from '@syncular/dialect-d1';
+ * import { createSqliteServerDialect } from '@syncular/server-dialect-sqlite';
+ * import { ensureSyncSchema } from '@syncular/server';
+ * import { createSyncServer } from '@syncular/server-hono';
+ *
+ * type Env = { DB: D1Database; SYNC_DO: DurableObjectNamespace };
+ *
+ * export class SyncDO extends SyncDurableObject<Env> {
+ *   setup(app, env, upgradeWebSocket) {
+ *     const db = createD1Db(env.DB);
+ *     const dialect = createSqliteServerDialect();
+ *     const { syncRoutes, consoleRoutes } = createSyncServer({
+ *       db, dialect,
+ *       handlers: [tasksHandler],
+ *       authenticate: async (c) => ({ actorId: c.req.header('x-user-id')! }),
+ *       upgradeWebSocket,
+ *     });
+ *     app.route('/sync', syncRoutes);
+ *     if (consoleRoutes) app.route('/console', consoleRoutes);
+ *   }
+ * }
+ *
+ * // Worker entry — routes all requests to the DO
+ * export default createSyncWorkerWithDO<Env>('SYNC_DO');
+ * ```
+ */
+
+import { Hono } from 'hono';
+import type { UpgradeWebSocket, WSEvents } from 'hono/ws';
+import { defineWebSocketHelper, WSContext } from 'hono/ws';
+
+// ---------------------------------------------------------------------------
+// WebSocket ↔ Hono bridge
+// ---------------------------------------------------------------------------
+
+interface WebSocketTag {
+  events: WSEvents<WebSocket>;
+}
+
+/**
+ * WeakMap from server-side WebSocket → tag with event handlers.
+ * Populated on upgrade, read in webSocketMessage/webSocketClose.
+ */
+const socketTags = new WeakMap<WebSocket, WebSocketTag>();
+
+function createWSContext(ws: WebSocket): WSContext<WebSocket> {
+  return new WSContext<WebSocket>({
+    send(data) {
+      ws.send(data);
+    },
+    close(code, reason) {
+      ws.close(code, reason);
+    },
+    raw: ws,
+    get readyState() {
+      return ws.readyState as 0 | 1 | 2 | 3;
+    },
+  });
+}
+
+/**
+ * Create an `upgradeWebSocket` function backed by the Durable Object
+ * hibernation API (`state.acceptWebSocket`).
+ *
+ * Each accepted socket is tagged with its Hono `WSEvents` handlers so the
+ * DO's `webSocketMessage` / `webSocketClose` callbacks can dispatch to them.
+ */
+function createDOUpgradeWebSocket(
+  doState: DurableObjectState
+): UpgradeWebSocket<WebSocket> {
+  return defineWebSocketHelper((_c, events) => {
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair) as [WebSocket, WebSocket];
+
+    // Accept via hibernation API so the DO can wake on messages
+    doState.acceptWebSocket(server);
+
+    // Tag the server socket so webSocketMessage/webSocketClose can find handlers
+    socketTags.set(server, { events: events as WSEvents<WebSocket> });
+
+    // Fire onOpen synchronously (socket is already accepted)
+    const wsCtx = createWSContext(server);
+    events.onOpen?.(new Event('open'), wsCtx);
+
+    return new Response(null, { status: 101, webSocket: client });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// SyncDurableObject base class
+// ---------------------------------------------------------------------------
+
+/**
+ * Base class for a Syncular Durable Object with Hono routing and WebSocket.
+ *
+ * Subclass and implement `setup()` to configure routes.
+ */
+export abstract class SyncDurableObject<
+  E extends object = Record<string, unknown>,
+> {
+  protected ctx: DurableObjectState;
+  protected env: E;
+
+  private app: Hono<{ Bindings: E }> | null = null;
+  private initPromise: Promise<void> | null = null;
+  private doUpgradeWebSocket: UpgradeWebSocket<WebSocket>;
+
+  constructor(ctx: DurableObjectState, env: E) {
+    this.ctx = ctx;
+    this.env = env;
+    this.doUpgradeWebSocket = createDOUpgradeWebSocket(ctx);
+  }
+
+  /**
+   * Configure the Hono app with sync routes.
+   *
+   * Called once when the DO first receives a request.
+   * Use `upgradeWebSocket` when creating the sync server to enable realtime.
+   */
+  abstract setup(
+    app: Hono<{ Bindings: E }>,
+    env: E,
+    upgradeWebSocket: UpgradeWebSocket<WebSocket>
+  ): void | Promise<void>;
+
+  private async getApp(): Promise<Hono<{ Bindings: E }>> {
+    if (this.app) return this.app;
+    if (!this.initPromise) {
+      const honoApp = new Hono<{ Bindings: E }>();
+      this.initPromise = Promise.resolve(
+        this.setup(honoApp, this.env, this.doUpgradeWebSocket)
+      ).then(() => {
+        this.app = honoApp;
+      });
+    }
+    await this.initPromise;
+    return this.app!;
+  }
+
+  /** Handle incoming HTTP requests (and WebSocket upgrades). */
+  async fetch(request: Request): Promise<Response> {
+    const app = await this.getApp();
+    return app.fetch(request, this.env);
+  }
+
+  /** Dispatch incoming WebSocket messages to Hono event handlers. */
+  async webSocketMessage(
+    ws: WebSocket,
+    message: string | ArrayBuffer
+  ): Promise<void> {
+    const tag = socketTags.get(ws);
+    if (!tag?.events.onMessage) return;
+
+    const wsCtx = createWSContext(ws);
+    const evt = new MessageEvent('message', { data: message });
+    tag.events.onMessage(evt, wsCtx);
+  }
+
+  /** Dispatch WebSocket close events to Hono event handlers. */
+  async webSocketClose(
+    ws: WebSocket,
+    code: number,
+    reason: string,
+    _wasClean: boolean
+  ): Promise<void> {
+    const tag = socketTags.get(ws);
+    if (!tag?.events.onClose) return;
+
+    const wsCtx = createWSContext(ws);
+    const evt = new CloseEvent('close', { code, reason });
+    tag.events.onClose(evt, wsCtx);
+    socketTags.delete(ws);
+  }
+
+  /** Dispatch WebSocket error events to Hono event handlers. */
+  async webSocketError(ws: WebSocket, _error: unknown): Promise<void> {
+    const tag = socketTags.get(ws);
+    if (!tag?.events.onError) return;
+
+    const wsCtx = createWSContext(ws);
+    const evt = new Event('error');
+    tag.events.onError(evt, wsCtx);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Worker → DO router
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Worker export that routes all requests to a Durable Object.
+ *
+ * Uses a single DO instance (derived from a stable ID) to hold all
+ * connections. For multi-tenant setups, override `getStubId`.
+ *
+ * @example
+ * ```typescript
+ * export default createSyncWorkerWithDO<Env>('SYNC_DO');
+ * ```
+ */
+export function createSyncWorkerWithDO<E extends object>(
+  bindingName: string & keyof E,
+  options?: {
+    /**
+     * Derive a DurableObject ID from the request.
+     * Defaults to a single global instance via `idFromName('sync')`.
+     */
+    getStubId?: (
+      ns: DurableObjectNamespace,
+      request: Request,
+      env: E
+    ) => DurableObjectId;
+  }
+): ExportedHandler<E> {
+  return {
+    async fetch(
+      request: Request,
+      env: E,
+      _ctx: ExecutionContext
+    ): Promise<Response> {
+      const ns = env[
+        bindingName as keyof E
+      ] as unknown as DurableObjectNamespace;
+      const id = options?.getStubId
+        ? options.getStubId(ns, request, env)
+        : ns.idFromName('sync');
+      const stub = ns.get(id);
+      return stub.fetch(request);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @syncular/server-cloudflare - Cloudflare adapters for Syncular
+ *
+ * Two deployment modes:
+ * - Worker (polling only): `@syncular/server-cloudflare/worker`
+ * - Durable Object (WebSocket + polling): `@syncular/server-cloudflare/durable-object`
+ *
+ * Blob storage:
+ * - R2 native: `@syncular/server-cloudflare/r2`
+ *
+ * Dialect is user-provided:
+ * - D1 + SQLite: `@syncular/dialect-d1` + `@syncular/server-dialect-sqlite`
+ * - Neon + Postgres: `@syncular/dialect-neon` + `@syncular/server-dialect-postgres`
+ */
+
+export * from './durable-object';
+export * from './r2';
+export * from './worker';