@velajs/cloudflare 1.9.0 → 1.10.0

package/dist/cloudflare-factory.js

@@ -2,6 +2,7 @@ import { VelaFactory } from "@velajs/vela";
 import { BindingRef } from "./binding-ref.js";
 import { CloudflareApplication } from "./cloudflare-application.js";
 import { EnvRef } from "./env-ref.js";
+import { initializeWorkerLive } from "./websocket/do-live.js";
 import { registerWebSocketRoutes } from "./websocket/websocket-routing.js";
 // Walks every provider registered in the container and pulls out the
 // BindingRef instances. Replaces the old module-level `bindingsRegistry`
@@ -63,6 +64,7 @@ function collectBindingRefs(container) {
  */ export function cloudflareAdapter() {
     let initialized = false;
     let refs = [];
+    let liveContainer;
     return {
         name: 'cloudflare',
         requestMiddleware: [
@@ -75,11 +77,15 @@ function collectBindingRefs(container) {
                         if (ref instanceof EnvRef) ref._initialize(env);
                         else ref._initialize(env[ref.bindingName]);
                     }
+                    // Live queries: hand the durableObjectLive() driver its env so
+                    // Worker-side invalidations can resolve the room DO namespace.
+                    if (liveContainer) initializeWorkerLive(liveContainer, env);
                 }
                 await next();
             }
         ],
         onBootstrap: ({ container })=>{
+            liveContainer = container;
             refs = collectBindingRefs(container);
         }
     };

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';
 export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom, } from './websocket/index';
 export type { WsGatewayRoute } from './websocket/index';
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, liveInvalidateToRoom, } from './websocket/index';
+export type { CfLiveDriver, DurableObjectLiveOptions } from './websocket/index';
 export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException, } from '@velajs/vela/websocket';
 export type { WsClient, WsServer, WsResponse, WsMessage, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from '@velajs/vela/websocket';
 export type { CloudflareEnv, ScheduledRegistration, QueueRegistration } from './types';

package/dist/index.js

@@ -33,5 +33,7 @@ export { Scheduled } from "./decorators/scheduled.js";
 export { QueueConsumer } from "./decorators/queue-consumer.js";
 // WebSocket (Durable Object transport for the Vela WebSocketModule)
 export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom } from "./websocket/index.js";
+// Live queries (Durable Object transport for @velajs/vela/live)
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, liveInvalidateToRoom } from "./websocket/index.js";
 // Re-export the core gateway API so a Cloudflare app can import it from one place.
 export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException } from "@velajs/vela/websocket";

package/dist/websocket/do-bootstrap.d.ts

@@ -1,6 +1,7 @@
 import type { Type } from '@velajs/vela';
 import { WsDispatcher } from '@velajs/vela/websocket';
 import type { WsServer } from '@velajs/vela/websocket';
+import type { LiveEngine } from '@velajs/vela/live';
 import { CfRoomRegistry } from './cf-room-registry';
 import type { DoStateLike } from './do-state';
 export interface DoRuntime {
@@ -9,6 +10,8 @@ export interface DoRuntime {
     server: WsServer;
     /** Gateway paths from `app.entrypoints.ofKind('websocket')` (discovery order). */
     gatewayPaths: string[];
+    /** The live-query engine (undefined when the app doesn't import LiveModule). */
+    live?: LiveEngine;
     close(signal?: string): Promise<void>;
 }
 /**

package/dist/websocket/do-bootstrap.js

@@ -3,6 +3,7 @@ import { local, WsDispatcher, WsServerImpl, WS_SERVER } from "@velajs/vela/webso
 import { BindingRef } from "../binding-ref.js";
 import { EnvRef } from "../env-ref.js";
 import { CfRoomRegistry } from "./cf-room-registry.js";
+import { initDoLive } from "./do-live.js";
 import { WsServerHolder } from "./ws-server-holder.js";
 /**
  * Slim DI bootstrap for the Durable Object isolate: wires the container and runs
@@ -38,6 +39,9 @@ import { WsServerHolder } from "./ws-server-holder.js";
     // per discovered gateway ({ meta: { path, dispatcher } }). Built by
     // callOnApplicationBootstrap(), so this slim no-routes path has it too.
     const wsEntrypoints = app.entrypoints.ofKind('websocket');
+    // Live queries: wire the SQLite cursor log + local driver mode and replay
+    // hibernation-persisted subscriptions into the fresh engine.
+    const live = initDoLive(app, container, ctx);
     return {
         // Zero gateways still yields a live dispatcher (module imported, nothing
         // decorated) — fall back to resolving it directly.
@@ -45,6 +49,7 @@ import { WsServerHolder } from "./ws-server-holder.js";
         registry,
         server,
         gatewayPaths: wsEntrypoints.map((ep)=>ep.meta.path),
+        live,
         close: (signal)=>app.close(signal)
     };
 }

package/dist/websocket/do-live.d.ts

@@ -0,0 +1,81 @@
+import type { Container } from '@velajs/vela';
+import type { CommitStamp, CursorLog, LiveDriver, LiveEngine, ResumeVerdict } from '@velajs/vela/live';
+import type { DoStateLike, SqlStorageLike } from './do-state';
+/**
+ * The durable `CursorLog`: an append-only tag-invalidation log in the DO's
+ * SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in
+ * `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is
+ * read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting
+ * client whose gap the log still covers gets a tiny `resume` instead of a
+ * re-run — the real-resume half of the live protocol.
+ *
+ * Constructed un-initialized at module-composition time (the same app module
+ * bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite
+ * handle inside the DO. In the Worker isolate it stays un-initialized — and is
+ * never consulted there, because `durableObjectLive()` routes every
+ * invalidation to the room DO's log (one log scope per room, exactly the
+ * protocol's model).
+ */
+export declare class DoCursorLog implements CursorLog {
+    private readonly maxRows;
+    private sql?;
+    private epoch?;
+    constructor(maxRows?: number);
+    /** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */
+    _initialize(sql: SqlStorageLike): void;
+    append(tags: string[]): CommitStamp;
+    current(): CommitStamp;
+    evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict;
+    private assertReady;
+}
+export interface DurableObjectLiveOptions {
+    /** The wrangler binding name of the WebSocket DO namespace (e.g. `'CHAT_ROOM'`). */
+    binding: string;
+    /** Room used when an invalidation names none. Matches the client default. */
+    defaultRoom?: string;
+}
+export interface CfLiveDriver extends LiveDriver {
+    /** @internal — Worker isolate: capture `env` so the namespace binding resolves per dispatch. */
+    _initializeEnv(env: Record<string, unknown>): void;
+    /** @internal — DO isolate: deliver invalidations straight to this DO's engine. */
+    _setLocalMode(): void;
+}
+/**
+ * The Cloudflare `LiveDriver`. Dual-mode, because the SAME app module
+ * bootstraps in both isolates:
+ *
+ * - **Worker** (HTTP mutations, queue consumers, crons): route the command to
+ *   the room's Durable Object over the `invalidate` RPC — the same canonical
+ *   `roomToDurableId` mapping the upgrade route and `broadcastToRoom` use —
+ *   and return THAT log scope's commit stamp (what `Vela-Commit-Cursor`
+ *   must carry).
+ * - **DO** (writes issued from inside the object): apply to the local engine.
+ */
+export declare function durableObjectLive(options: DurableObjectLiveOptions): CfLiveDriver;
+/** Worker-side wiring, called from `cloudflareAdapter`'s first-request middleware. */
+export declare function initializeWorkerLive(container: Container, env: Record<string, unknown>): void;
+/** The app-facing surface of the engine reached through `app.entrypoints.ofKind('live')`. */
+interface EntrypointsApp {
+    entrypoints: {
+        ofKind<M>(kind: string): Array<{
+            meta: M;
+        }>;
+    };
+}
+/**
+ * DO-side wiring, called from `buildDoRuntime`: initialize the SQLite cursor
+ * log, flip the driver to local mode, and replay every hibernation-persisted
+ * subscription into the (fresh) engine so an eviction is invisible to
+ * subscribers. Returns the engine for the `invalidate` RPC, or undefined when
+ * the app doesn't use LiveModule.
+ */
+export declare function initDoLive(app: EntrypointsApp, container: Container, ctx: DoStateLike): LiveEngine | undefined;
+/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */
+export declare function durableObjectCursorLog(maxRows?: number): DoCursorLog;
+/**
+ * Invalidate live tags in a room from a Worker (controller / cron / queue
+ * consumer) — the live sibling of `broadcastToRoom`. Returns the room log
+ * scope's commit stamp for `Vela-Commit-Cursor` stamping.
+ */
+export declare function liveInvalidateToRoom(ns: DurableObjectNamespace, room: string, tags: string[]): Promise<CommitStamp | undefined>;
+export {};

package/dist/websocket/do-live.js

@@ -0,0 +1,197 @@
+import { LIVE_CURSOR_LOG, LIVE_DRIVER, readPersistedLiveSubscriptions } from "@velajs/vela/live";
+import { CfWsClient } from "./cf-ws-client.js";
+import { roomToDurableId } from "./room-id.js";
+const DEFAULT_ROOM = 'default';
+const DEFAULT_MAX_LOG_ROWS = 4096;
+/**
+ * The durable `CursorLog`: an append-only tag-invalidation log in the DO's
+ * SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in
+ * `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is
+ * read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting
+ * client whose gap the log still covers gets a tiny `resume` instead of a
+ * re-run — the real-resume half of the live protocol.
+ *
+ * Constructed un-initialized at module-composition time (the same app module
+ * bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite
+ * handle inside the DO. In the Worker isolate it stays un-initialized — and is
+ * never consulted there, because `durableObjectLive()` routes every
+ * invalidation to the room DO's log (one log scope per room, exactly the
+ * protocol's model).
+ */ export class DoCursorLog {
+    maxRows;
+    sql;
+    epoch;
+    constructor(maxRows = DEFAULT_MAX_LOG_ROWS){
+        this.maxRows = maxRows;
+    }
+    /** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */ _initialize(sql) {
+        this.sql = sql;
+        sql.exec('CREATE TABLE IF NOT EXISTS __vela_live_log (seq INTEGER PRIMARY KEY AUTOINCREMENT, ts REAL NOT NULL, tags TEXT NOT NULL)');
+        sql.exec('CREATE TABLE IF NOT EXISTS __vela_live_meta (k TEXT PRIMARY KEY, v TEXT NOT NULL)');
+        const row = sql.exec("SELECT v FROM __vela_live_meta WHERE k = 'epoch'").toArray()[0];
+        if (row && typeof row.v === 'string') {
+            this.epoch = row.v;
+        } else {
+            this.epoch = crypto.randomUUID();
+            sql.exec("INSERT INTO __vela_live_meta (k, v) VALUES ('epoch', ?)", this.epoch);
+        }
+    }
+    append(tags) {
+        const sql = this.assertReady();
+        sql.exec('INSERT INTO __vela_live_log (ts, tags) VALUES (?, ?)', Date.now(), JSON.stringify(tags));
+        const stamp = this.current();
+        // Bounded retention: trimmed gaps degrade to snapshot-on-reconnect.
+        if (stamp.cursor > this.maxRows) {
+            sql.exec('DELETE FROM __vela_live_log WHERE seq <= ?', stamp.cursor - this.maxRows);
+        }
+        return stamp;
+    }
+    current() {
+        const sql = this.assertReady();
+        // sqlite_sequence survives DELETE-based trims, so the cursor never
+        // rewinds. The table itself only materializes on the first AUTOINCREMENT
+        // insert — before that the log is empty and the cursor is 0.
+        let cursor = 0;
+        try {
+            const row = sql.exec("SELECT seq FROM sqlite_sequence WHERE name = '__vela_live_log'").toArray()[0];
+            cursor = typeof row?.seq === 'number' ? row.seq : Number(row?.seq ?? 0);
+        } catch  {
+            cursor = 0;
+        }
+        return {
+            cursor,
+            epoch: this.epoch
+        };
+    }
+    evaluateResume(sinceCursor, sinceEpoch, subscriptionTags) {
+        const sql = this.assertReady();
+        const { cursor, epoch } = this.current();
+        if (sinceEpoch !== epoch) return 'snapshot'; // forked timeline (reset/recreated DO)
+        if (sinceCursor > cursor) return 'snapshot'; // rollback guard
+        if (sinceCursor === cursor) return 'resume';
+        const minRow = sql.exec('SELECT MIN(seq) AS m FROM __vela_live_log').toArray()[0];
+        const min = minRow?.m == null ? undefined : Number(minRow.m);
+        // The log must still cover (sinceCursor, cursor] — a trimmed gap cannot be reasoned about.
+        if (min === undefined || min > sinceCursor + 1) return 'snapshot';
+        const subTags = new Set(subscriptionTags);
+        for (const row of sql.exec('SELECT tags FROM __vela_live_log WHERE seq > ?', sinceCursor).toArray()){
+            let tags;
+            try {
+                tags = JSON.parse(String(row.tags));
+            } catch  {
+                return 'snapshot';
+            }
+            if (Array.isArray(tags) && tags.some((tag)=>subTags.has(tag))) return 'rerun';
+        }
+        return 'resume';
+    }
+    assertReady() {
+        if (!this.sql) {
+            throw new Error('DoCursorLog is not initialized. It only runs inside a SQLite-backed Durable Object ' + '(wrangler: new_sqlite_classes) — Worker-side invalidations must go through durableObjectLive(), ' + "which routes them to the room DO's log.");
+        }
+        return this.sql;
+    }
+}
+/**
+ * The Cloudflare `LiveDriver`. Dual-mode, because the SAME app module
+ * bootstraps in both isolates:
+ *
+ * - **Worker** (HTTP mutations, queue consumers, crons): route the command to
+ *   the room's Durable Object over the `invalidate` RPC — the same canonical
+ *   `roomToDurableId` mapping the upgrade route and `broadcastToRoom` use —
+ *   and return THAT log scope's commit stamp (what `Vela-Commit-Cursor`
+ *   must carry).
+ * - **DO** (writes issued from inside the object): apply to the local engine.
+ */ export function durableObjectLive(options) {
+    let sink;
+    let env;
+    let localMode = false;
+    return {
+        kind: 'durable-object',
+        bind (boundSink) {
+            sink = boundSink;
+        },
+        _initializeEnv (capturedEnv) {
+            env = capturedEnv;
+        },
+        _setLocalMode () {
+            localMode = true;
+        },
+        dispatch (cmd) {
+            if (localMode) return sink?.applyInvalidation(cmd);
+            const namespace = env?.[options.binding];
+            if (!namespace) {
+                throw new Error(`durableObjectLive: binding '${options.binding}' is not available. In a Worker, ` + 'createCloudflareApp() captures env on the first request; check the wrangler binding name.');
+            }
+            const room = cmd.room ?? options.defaultRoom ?? DEFAULT_ROOM;
+            const stub = namespace.get(roomToDurableId(namespace, room));
+            return stub.invalidate({
+                ...cmd,
+                room
+            });
+        }
+    };
+}
+const isCfLiveDriver = (value)=>typeof value === 'object' && value !== null && typeof value._setLocalMode === 'function' && typeof value._initializeEnv === 'function';
+/** Worker-side wiring, called from `cloudflareAdapter`'s first-request middleware. */ export function initializeWorkerLive(container, env) {
+    let driver;
+    try {
+        driver = container.resolve(LIVE_DRIVER);
+    } catch  {
+        return; // LiveModule not imported
+    }
+    if (isCfLiveDriver(driver)) driver._initializeEnv(env);
+}
+/**
+ * DO-side wiring, called from `buildDoRuntime`: initialize the SQLite cursor
+ * log, flip the driver to local mode, and replay every hibernation-persisted
+ * subscription into the (fresh) engine so an eviction is invisible to
+ * subscribers. Returns the engine for the `invalidate` RPC, or undefined when
+ * the app doesn't use LiveModule.
+ */ export function initDoLive(app, container, ctx) {
+    const entry = app.entrypoints.ofKind('live')[0];
+    if (!entry) return undefined;
+    const engine = entry.meta.engine;
+    try {
+        const log = container.resolve(LIVE_CURSOR_LOG);
+        if (log instanceof DoCursorLog) {
+            const sql = ctx.storage?.sql;
+            if (!sql) {
+                throw new Error('DoCursorLog requires a SQLite-backed Durable Object: add this class to ' + "wrangler's `migrations[].new_sqlite_classes`. Falling back is not possible — " + 'either enable SQLite or drop the `log: durableObjectCursorLog()` option ' + '(snapshot-on-reconnect semantics).');
+            }
+            log._initialize(sql);
+        }
+    } catch (err) {
+        // Surface misconfiguration loudly — a silently un-initialized log would
+        // throw on the first subscribe instead.
+        if (err instanceof Error && err.message.includes('new_sqlite_classes')) throw err;
+    }
+    try {
+        const driver = container.resolve(LIVE_DRIVER);
+        if (isCfLiveDriver(driver)) driver._setLocalMode();
+    } catch  {
+    // LiveModule always provides LIVE_DRIVER when the engine exists; defensive only.
+    }
+    // Wake-time replay: subscriptions ride the hibernation attachments.
+    for (const ws of ctx.getWebSockets()){
+        const client = new CfWsClient(ctx, ws);
+        for (const record of readPersistedLiveSubscriptions(client)){
+            engine.restoreSubscription(client.path, client, record);
+        }
+    }
+    return engine;
+}
+/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */ export function durableObjectCursorLog(maxRows) {
+    return new DoCursorLog(maxRows);
+}
+/**
+ * Invalidate live tags in a room from a Worker (controller / cron / queue
+ * consumer) — the live sibling of `broadcastToRoom`. Returns the room log
+ * scope's commit stamp for `Vela-Commit-Cursor` stamping.
+ */ export async function liveInvalidateToRoom(ns, room, tags) {
+    const stub = ns.get(roomToDurableId(ns, room));
+    return stub.invalidate({
+        room,
+        tags
+    });
+}

package/dist/websocket/do-state.d.ts

@@ -4,6 +4,12 @@ export interface WsLike {
     serializeAttachment(value: unknown): void;
     deserializeAttachment(): unknown;
 }
+/** Structural view of the DO's SQLite handle (`ctx.storage.sql`, requires `new_sqlite_classes`). */
+export interface SqlStorageLike {
+    exec(query: string, ...bindings: unknown[]): {
+        toArray(): Record<string, unknown>[];
+    };
+}
 export interface DoStateLike {
     readonly id: {
         toString(): string;
@@ -12,6 +18,10 @@ export interface DoStateLike {
     acceptWebSocket(ws: WsLike, tags?: string[]): void;
     getWebSockets(tag?: string): WsLike[];
     setWebSocketAutoResponse?(pair: unknown): void;
+    /** Present on SQLite-backed DOs — the live cursor log lives here. */
+    readonly storage?: {
+        sql?: SqlStorageLike;
+    };
 }
 /** Per-connection metadata persisted in the hibernation attachment (≤ 16 KiB). */
 export interface WsAttachment {

package/dist/websocket/index.d.ts

@@ -1,6 +1,8 @@
 export { VelaWebSocketDurableObject } from './websocket.durable-object';
 export { CloudflareWebSocketModule } from './cloudflare-websocket.module';
 export { broadcastToRoom } from './broadcast';
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, initDoLive, initializeWorkerLive, liveInvalidateToRoom, } from './do-live';
+export type { CfLiveDriver, DurableObjectLiveOptions } from './do-live';
 export { CfWsClient } from './cf-ws-client';
 export { CfRoomRegistry } from './cf-room-registry';
 export { DoWebSocketHost } from './do-websocket-host';
@@ -10,4 +12,4 @@ export type { DoRuntime } from './do-bootstrap';
 export { registerWebSocketRoutes, collectWsGatewayRoutes } from './websocket-routing';
 export type { WsGatewayRoute } from './websocket-routing';
 export { roomTag, connTag, roomToDurableId } from './room-id';
-export type { DoStateLike, WsLike, WsAttachment } from './do-state';
+export type { DoStateLike, SqlStorageLike, WsLike, WsAttachment } from './do-state';

package/dist/websocket/index.js

@@ -3,6 +3,8 @@ export { VelaWebSocketDurableObject } from "./websocket.durable-object.js";
 // Module + server-initiated emit helper
 export { CloudflareWebSocketModule } from "./cloudflare-websocket.module.js";
 export { broadcastToRoom } from "./broadcast.js";
+// Live queries: durable cursor log + DO-routed invalidation driver
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, initDoLive, initializeWorkerLive, liveInvalidateToRoom } from "./do-live.js";
 // Transport internals (advanced use / testing)
 export { CfWsClient } from "./cf-ws-client.js";
 export { CfRoomRegistry } from "./cf-room-registry.js";

package/dist/websocket/websocket.durable-object.js

@@ -17,6 +17,7 @@ const PONG = '{"event":"pong"}';
  */ export function VelaWebSocketDurableObject(rootModule) {
     return class VelaWsDurableObject extends DurableObject {
         host;
+        liveEngine;
         ready;
         constructor(ctx, env){
             super(ctx, env);
@@ -29,6 +30,7 @@ const PONG = '{"event":"pong"}';
             this.ready = ctx.blockConcurrencyWhile(async ()=>{
                 const runtime = await buildDoRuntime(rootModule, ctx, env);
                 this.host = new DoWebSocketHost(ctx, runtime.dispatcher, runtime.registry, runtime.gatewayPaths);
+                this.liveEngine = runtime.live;
             });
         }
         async fetch(request) {
@@ -68,5 +70,14 @@ const PONG = '{"event":"pong"}';
             await this.ready;
             this.host.broadcast(cmd);
         }
+        /**
+     * DO RPC — live tag invalidation forwarded from a Worker (durableObjectLive /
+     * liveInvalidateToRoom). Appends to THIS log scope's cursor log and returns
+     * the commit stamp (what `Vela-Commit-Cursor` carries); the subscription
+     * refreshes fan out asynchronously.
+     */ async invalidate(cmd) {
+            await this.ready;
+            return this.liveEngine?.applyInvalidation(cmd);
+        }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,7 +46,7 @@
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
     "@velajs/feature-flags": "^0.1.0",
-    "@velajs/vela": ">=1.11.0",
+    "@velajs/vela": ">=1.17.0",
     "hono": ">=4"
   },
   "peerDependenciesMeta": {
@@ -59,7 +59,7 @@
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.43",
     "@velajs/feature-flags": "^0.1.0",
-    "@velajs/vela": "^1.12.0",
+    "@velajs/vela": "^1.17.0",
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",