@concavejs/runtime-cf-base 0.0.1-alpha.4

package/dist/routing/instance.d.ts

@@ -0,0 +1,25 @@
+export declare const DEFAULT_INSTANCE_KEY = "x-concave-instance";
+export declare const DEFAULT_INSTANCE_VALUE = "singleton";
+export declare const DEFAULT_INSTANCE_COOKIE_PATH = "/";
+export type InstanceResolutionSource = "query" | "header" | "cookie" | "default";
+export type InstanceResolution = {
+    value: string;
+    source: InstanceResolutionSource;
+    queryValue?: string;
+    headerValue?: string;
+    cookieValue?: string;
+};
+export type InstanceResolutionOptions = {
+    instanceKey?: string;
+    defaultInstance?: string;
+};
+export type InstanceCookieOptions = {
+    path?: string;
+    sameSite?: "Lax" | "Strict" | "None";
+    secure?: boolean;
+    httpOnly?: boolean;
+};
+export declare function resolveInstanceFromRequest(request: Request, options?: InstanceResolutionOptions): InstanceResolution;
+export declare function maybeAttachInstanceCookie(response: Response, request: Request, resolution: InstanceResolution, options?: InstanceResolutionOptions & InstanceCookieOptions): Response;
+export declare function readCookieValue(cookieHeader: string | null, name: string): string | undefined;
+export declare function buildInstanceCookie(request: Request, name: string, value: string, options?: InstanceCookieOptions): string;

package/dist/routing/instance.js

@@ -0,0 +1,101 @@
+// Centralized instance routing rules for HTTP + WS entry points.
+// Precedence: query param -> header -> cookie -> default.
+export const DEFAULT_INSTANCE_KEY = "x-concave-instance";
+export const DEFAULT_INSTANCE_VALUE = "singleton";
+export const DEFAULT_INSTANCE_COOKIE_PATH = "/";
+export function resolveInstanceFromRequest(request, options = {}) {
+    const instanceKey = options.instanceKey ?? DEFAULT_INSTANCE_KEY;
+    const defaultInstance = options.defaultInstance ?? DEFAULT_INSTANCE_VALUE;
+    const url = new URL(request.url);
+    const queryValue = url.searchParams.get(instanceKey) ?? undefined;
+    if (queryValue) {
+        return {
+            value: queryValue,
+            source: "query",
+            queryValue,
+            headerValue: request.headers.get(instanceKey) ?? undefined,
+            cookieValue: readCookieValue(request.headers.get("Cookie"), instanceKey),
+        };
+    }
+    const headerValue = request.headers.get(instanceKey) ?? undefined;
+    if (headerValue) {
+        return {
+            value: headerValue,
+            source: "header",
+            queryValue: undefined,
+            headerValue,
+            cookieValue: readCookieValue(request.headers.get("Cookie"), instanceKey),
+        };
+    }
+    const cookieValue = readCookieValue(request.headers.get("Cookie"), instanceKey);
+    if (cookieValue) {
+        return {
+            value: cookieValue,
+            source: "cookie",
+            queryValue: undefined,
+            headerValue: undefined,
+            cookieValue,
+        };
+    }
+    return {
+        value: defaultInstance,
+        source: "default",
+    };
+}
+export function maybeAttachInstanceCookie(response, request, resolution, options = {}) {
+    // Only persist explicit instance selections (query/header) into cookies.
+    if (resolution.source !== "query" && resolution.source !== "header") {
+        return response;
+    }
+    const instanceKey = options.instanceKey ?? DEFAULT_INSTANCE_KEY;
+    const existingCookie = readCookieValue(request.headers.get("Cookie"), instanceKey);
+    if (existingCookie === resolution.value) {
+        return response;
+    }
+    const headers = new Headers(response.headers);
+    const cookie = buildInstanceCookie(request, instanceKey, resolution.value, options);
+    headers.append("Set-Cookie", cookie);
+    const webSocket = response.webSocket;
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        ...(webSocket ? { webSocket } : {}),
+    });
+}
+export function readCookieValue(cookieHeader, name) {
+    if (!cookieHeader) {
+        return undefined;
+    }
+    const target = name.toLowerCase();
+    const entries = cookieHeader.split(";").map((part) => part.trim());
+    for (const entry of entries) {
+        if (!entry) {
+            continue;
+        }
+        const equals = entry.indexOf("=");
+        if (equals === -1) {
+            continue;
+        }
+        const key = entry.slice(0, equals).trim().toLowerCase();
+        if (key !== target) {
+            continue;
+        }
+        return decodeURIComponent(entry.slice(equals + 1).trim());
+    }
+    return undefined;
+}
+export function buildInstanceCookie(request, name, value, options = {}) {
+    const path = options.path ?? DEFAULT_INSTANCE_COOKIE_PATH;
+    const sameSite = options.sameSite ?? "Lax";
+    const secure = options.secure ?? new URL(request.url).protocol === "https:";
+    const httpOnly = options.httpOnly ?? true;
+    const parts = [`${name}=${encodeURIComponent(value)}`, `Path=${path}`, `SameSite=${sameSite}`];
+    if (secure) {
+        parts.push("Secure");
+    }
+    if (httpOnly) {
+        parts.push("HttpOnly");
+    }
+    return parts.join("; ");
+}

package/dist/rpc/blobstore-proxy.d.ts

@@ -0,0 +1,11 @@
+import type { BlobStore } from "@concavejs/core/abstractions";
+/**
+ * Wraps a DO stub as a BlobStore.
+ * Blobstore methods are prefixed with "blobstore" on the DO to avoid collisions.
+ */
+export declare function createBlobStoreProxy(stub: any): BlobStore;
+/**
+ * Wraps a SyscallGateway service binding as a BlobStore.
+ * Prepends projectId and instance to each call for multi-tenant routing.
+ */
+export declare function createGatewayBlobStoreProxy(gateway: any, projectId: string, instance: string): BlobStore;

package/dist/rpc/blobstore-proxy.js

@@ -0,0 +1,28 @@
+/**
+ * Wraps a DO stub as a BlobStore.
+ * Blobstore methods are prefixed with "blobstore" on the DO to avoid collisions.
+ */
+export function createBlobStoreProxy(stub) {
+    return createBlobStoreProxyInternal(stub, (...args) => args);
+}
+/**
+ * Wraps a SyscallGateway service binding as a BlobStore.
+ * Prepends projectId and instance to each call for multi-tenant routing.
+ */
+export function createGatewayBlobStoreProxy(gateway, projectId, instance) {
+    return createBlobStoreProxyInternal(gateway, (...args) => [projectId, instance, ...args]);
+}
+/**
+ * Internal helper that creates a BlobStore proxy with configurable argument transformation.
+ */
+function createBlobStoreProxyInternal(target, transformArgs) {
+    return {
+        async store(blob, options) {
+            const buffer = blob instanceof Blob ? await blob.arrayBuffer() : blob;
+            return target.blobstoreStore(...transformArgs(buffer, options));
+        },
+        get: (id) => target.blobstoreGet(...transformArgs(id)),
+        delete: (id) => target.blobstoreDelete(...transformArgs(id)),
+        getUrl: (id) => target.blobstoreGetUrl(...transformArgs(id)),
+    };
+}

package/dist/rpc/docstore-proxy.d.ts

@@ -0,0 +1,11 @@
+import type { DocStore } from "@concavejs/core/docstore";
+/**
+ * Wraps a DO stub as a DocStore.
+ * Generator methods are converted from arrays back to async generators.
+ */
+export declare function createDocStoreProxy(stub: any): DocStore;
+/**
+ * Wraps a SyscallGateway service binding as a DocStore.
+ * Prepends projectId and instance to each call for multi-tenant routing.
+ */
+export declare function createGatewayDocStoreProxy(gateway: any, projectId: string, instance: string): DocStore;

package/dist/rpc/docstore-proxy.js

@@ -0,0 +1,72 @@
+/**
+ * Wraps a DO stub as a DocStore.
+ * Generator methods are converted from arrays back to async generators.
+ */
+export function createDocStoreProxy(stub) {
+    return createDocStoreProxyInternal(stub, (...args) => args);
+}
+/**
+ * Wraps a SyscallGateway service binding as a DocStore.
+ * Prepends projectId and instance to each call for multi-tenant routing.
+ */
+export function createGatewayDocStoreProxy(gateway, projectId, instance) {
+    return createDocStoreProxyInternal(gateway, (...args) => [projectId, instance, ...args]);
+}
+/**
+ * Internal helper that creates a DocStore proxy with configurable argument transformation.
+ */
+function createDocStoreProxyInternal(target, transformArgs) {
+    return new Proxy({}, {
+        get(_, prop) {
+            // Convert array results back to async generators
+            if (prop === "index_scan") {
+                return async function* (...args) {
+                    const results = await target.index_scan(...transformArgs(...args));
+                    for (const item of results) {
+                        yield item;
+                    }
+                };
+            }
+            if (prop === "load_documents") {
+                return async function* (...args) {
+                    const results = await target.load_documents(...transformArgs(...args));
+                    for (const item of results) {
+                        yield item;
+                    }
+                };
+            }
+            // Convert array results back to Map for previous_revisions
+            if (prop === "previous_revisions") {
+                return async function (...args) {
+                    const result = await target.previous_revisions(...transformArgs(...args));
+                    return new Map(result);
+                };
+            }
+            if (prop === "previous_revisions_of_documents") {
+                return async function (...args) {
+                    const result = await target.previous_revisions_of_documents(...transformArgs(...args));
+                    return new Map(result);
+                };
+            }
+            // Provide a local timestampOracle (DO-side oracle cannot be accessed via RPC)
+            if (prop === "timestampOracle") {
+                return {
+                    observeTimestamp: () => { },
+                    allocateTimestamp: () => BigInt(Date.now()),
+                    getCurrentTimestamp: () => BigInt(Date.now()),
+                    beginSnapshot: () => BigInt(Date.now()),
+                };
+            }
+            // No-op close
+            if (prop === "close") {
+                return async () => { };
+            }
+            // Bind methods to target with transformed args
+            const method = target[prop];
+            if (typeof method === "function") {
+                return (...args) => method.call(target, ...transformArgs(...args));
+            }
+            return method;
+        },
+    });
+}

package/dist/rpc/index.d.ts

@@ -0,0 +1,2 @@
+export { createDocStoreProxy, createGatewayDocStoreProxy } from "./docstore-proxy";
+export { createBlobStoreProxy, createGatewayBlobStoreProxy } from "./blobstore-proxy";

package/dist/rpc/index.js

@@ -0,0 +1,2 @@
+export { createDocStoreProxy, createGatewayDocStoreProxy } from "./docstore-proxy";
+export { createBlobStoreProxy, createGatewayBlobStoreProxy } from "./blobstore-proxy";

package/dist/sync/cf-websocket-adapter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cloudflare WebSocket adapter for the platform-agnostic sync protocol.
+ * This adapter wraps a Cloudflare Worker WebSocket to implement the SyncWebSocket interface.
+ */
+import type { SyncWebSocket } from "@concavejs/core/sync";
+/**
+ * WebSocket wrapper to adapt CF WebSocket to platform-agnostic interface
+ */
+export declare class CFWebSocketAdapter implements SyncWebSocket {
+    private ws;
+    constructor(ws: WebSocket);
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    get readyState(): number;
+}

package/dist/sync/cf-websocket-adapter.js

@@ -0,0 +1,22 @@
+/**
+ * Cloudflare WebSocket adapter for the platform-agnostic sync protocol.
+ * This adapter wraps a Cloudflare Worker WebSocket to implement the SyncWebSocket interface.
+ */
+/**
+ * WebSocket wrapper to adapt CF WebSocket to platform-agnostic interface
+ */
+export class CFWebSocketAdapter {
+    ws;
+    constructor(ws) {
+        this.ws = ws;
+    }
+    send(data) {
+        this.ws.send(data);
+    }
+    close(code, reason) {
+        this.ws.close(code, reason);
+    }
+    get readyState() {
+        return this.ws.readyState;
+    }
+}

package/dist/sync/concave-do-udf-executor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * UDF executor that delegates to ConcaveDO via stub.
+ * Shared between runtime-cf and runtime-cloud.
+ */
+import type { SyncUdfExecutor, AuthContext } from "@concavejs/core/sync";
+import type { JSONValue } from "convex/values";
+import type { SerializedKeyRange } from "@concavejs/core/queryengine";
+type MinimalDOStub = {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+};
+/**
+ * UDF executor that delegates to ConcaveDO
+ */
+export declare class ConcaveDOUdfExecutor implements SyncUdfExecutor {
+    private readonly getConcaveStub;
+    private readonly projectId?;
+    constructor(getConcaveStub: () => MinimalDOStub, projectId?: string | undefined);
+    private createAdapter;
+    executeQuery(path: string, args: Record<string, any>, auth: AuthContext, componentPath?: string): Promise<{
+        result: JSONValue;
+        readRanges?: SerializedKeyRange[];
+        logLines?: string[];
+    }>;
+    executeMutation(path: string, args: Record<string, any>, auth: AuthContext, componentPath?: string): Promise<{
+        result: JSONValue;
+        writtenRanges?: SerializedKeyRange[];
+        writtenTables?: string[];
+        logLines?: string[];
+    }>;
+    executeAction(path: string, args: Record<string, any>, auth: AuthContext, componentPath?: string): Promise<{
+        result: JSONValue;
+        writtenRanges?: SerializedKeyRange[];
+        writtenTables?: string[];
+        logLines?: string[];
+    }>;
+}
+export {};

package/dist/sync/concave-do-udf-executor.js

@@ -0,0 +1,67 @@
+/**
+ * UDF executor that delegates to ConcaveDO via stub.
+ * Shared between runtime-cf and runtime-cloud.
+ */
+import { createClientAdapter } from "@concavejs/core/udf/execution-adapter";
+import { writtenTablesFromRanges } from "@concavejs/core/utils";
+import { ConcaveStubExecutor } from "../udf/executor/do-client-executor";
+/**
+ * UDF executor that delegates to ConcaveDO
+ */
+export class ConcaveDOUdfExecutor {
+    getConcaveStub;
+    projectId;
+    constructor(getConcaveStub, projectId) {
+        this.getConcaveStub = getConcaveStub;
+        this.projectId = projectId;
+    }
+    createAdapter() {
+        const stub = this.getConcaveStub();
+        // Create a wrapper stub that adds the projectId header to all requests
+        const wrappedStub = {
+            fetch: async (input, init) => {
+                const headers = new Headers(init?.headers);
+                if (this.projectId) {
+                    headers.set("X-Concave-Project-Id", this.projectId);
+                }
+                return stub.fetch(input, {
+                    ...init,
+                    headers,
+                });
+            },
+        };
+        // Cast to any to satisfy ConcaveStubExecutor which expects full DurableObjectStub
+        // We only use the fetch method, so this is safe
+        const executor = new ConcaveStubExecutor(wrappedStub);
+        return createClientAdapter(executor);
+    }
+    async executeQuery(path, args, auth, componentPath) {
+        const adapter = this.createAdapter();
+        const result = await adapter.executeUdf(path, args, "query", auth, componentPath);
+        return {
+            result: result.result,
+            readRanges: result.readRanges,
+            logLines: result.logLines,
+        };
+    }
+    async executeMutation(path, args, auth, componentPath) {
+        const adapter = this.createAdapter();
+        const result = await adapter.executeUdf(path, args, "mutation", auth, componentPath);
+        return {
+            result: result.result,
+            writtenRanges: result.writtenRanges,
+            writtenTables: result.writtenRanges ? writtenTablesFromRanges(result.writtenRanges) : undefined,
+            logLines: result.logLines,
+        };
+    }
+    async executeAction(path, args, auth, componentPath) {
+        const adapter = this.createAdapter();
+        const result = await adapter.executeUdf(path, args, "action", auth, componentPath);
+        return {
+            result: result.result,
+            writtenRanges: result.writtenRanges,
+            writtenTables: result.writtenRanges ? writtenTablesFromRanges(result.writtenRanges) : undefined,
+            logLines: result.logLines,
+        };
+    }
+}

package/dist/sync/index.d.ts

@@ -0,0 +1,2 @@
+export { CFWebSocketAdapter } from "./cf-websocket-adapter";
+export { ConcaveDOUdfExecutor } from "./concave-do-udf-executor";

package/dist/sync/index.js

@@ -0,0 +1,2 @@
+export { CFWebSocketAdapter } from "./cf-websocket-adapter";
+export { ConcaveDOUdfExecutor } from "./concave-do-udf-executor";

package/dist/udf/executor/do-client-executor.d.ts

@@ -0,0 +1,14 @@
+import type { UserIdentityAttributes } from "convex/server";
+import type { DurableObjectStub } from "@cloudflare/workers-types";
+import type { UdfExec, UdfResult } from "@concavejs/core/udf";
+import type { AuthContext } from "@concavejs/core/sync/protocol-handler";
+/**
+ * Durable Object stub executor that bridges HTTP API requests to ConcaveDO.
+ * Converts Convex values to JSON-safe payloads and forwards auth/context metadata.
+ */
+export declare class ConcaveStubExecutor implements UdfExec {
+    private readonly stub;
+    constructor(stub: DurableObjectStub);
+    execute(path: string, args: Record<string, any>, type: "query" | "mutation" | "action", auth?: AuthContext | UserIdentityAttributes, componentPath?: string, requestId?: string): Promise<UdfResult>;
+    executeHttp(request: Request): Promise<Response>;
+}

package/dist/udf/executor/do-client-executor.js

@@ -0,0 +1,42 @@
+import { convexToJson } from "convex/values";
+/**
+ * Durable Object stub executor that bridges HTTP API requests to ConcaveDO.
+ * Converts Convex values to JSON-safe payloads and forwards auth/context metadata.
+ */
+export class ConcaveStubExecutor {
+    stub;
+    constructor(stub) {
+        this.stub = stub;
+    }
+    async execute(path, args, type, auth, componentPath, requestId) {
+        const payload = {
+            path,
+            args: convexToJson(args),
+            type,
+            auth,
+            componentPath,
+            caller: "client",
+            requestId,
+        };
+        const response = await this.stub.fetch("http://do/execute", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Function execution failed with status ${response.status}: ${errorText}`);
+        }
+        const result = (await response.json());
+        if (result.commitTimestamp) {
+            return {
+                ...result,
+                commitTimestamp: BigInt(result.commitTimestamp),
+            };
+        }
+        return result;
+    }
+    async executeHttp(request) {
+        return this.stub.fetch(request);
+    }
+}

package/dist/udf/executor/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * UDF Executor Module
+ *
+ * UDF execution strategies (inline, isolated)
+ */
+export * from "./udf-executor";
+export * from "./inline-executor";
+export * from "./isolated-executor";
+export * from "./do-client-executor";

package/dist/udf/executor/index.js

@@ -0,0 +1,9 @@
+/**
+ * UDF Executor Module
+ *
+ * UDF execution strategies (inline, isolated)
+ */
+export * from "./udf-executor";
+export * from "./inline-executor";
+export * from "./isolated-executor";
+export * from "./do-client-executor";

package/dist/udf/executor/inline-executor.d.ts

@@ -0,0 +1,13 @@
+import type { DocStore } from "@concavejs/core/docstore";
+import type { BlobStore } from "@concavejs/core/abstractions";
+import { InlineUdfExecutor } from "@concavejs/core/udf";
+export declare class UdfExecInline extends InlineUdfExecutor {
+    /**
+     * Create an inline UDF executor.
+     *
+     * @param docstore - Document store for data storage
+     * @param blobstoreOrBucket - Either a BlobStore or an R2Bucket
+     * @param r2PublicUrl - Public URL for R2 (only used if blobstoreOrBucket is an R2Bucket)
+     */
+    constructor(docstore: DocStore, blobstoreOrBucket?: BlobStore | R2Bucket, r2PublicUrl?: string);
+}

package/dist/udf/executor/inline-executor.js

@@ -0,0 +1,25 @@
+import { InlineUdfExecutor } from "@concavejs/core/udf";
+import { R2BlobStore } from "@concavejs/blobstore-cf-r2";
+export class UdfExecInline extends InlineUdfExecutor {
+    /**
+     * Create an inline UDF executor.
+     *
+     * @param docstore - Document store for data storage
+     * @param blobstoreOrBucket - Either a BlobStore or an R2Bucket
+     * @param r2PublicUrl - Public URL for R2 (only used if blobstoreOrBucket is an R2Bucket)
+     */
+    constructor(docstore, blobstoreOrBucket, r2PublicUrl) {
+        let blobstore;
+        if (blobstoreOrBucket) {
+            // Check if it's already a BlobStore (has store method)
+            if (typeof blobstoreOrBucket.store === "function") {
+                blobstore = blobstoreOrBucket;
+            }
+            else {
+                // It's an R2Bucket, wrap it
+                blobstore = new R2BlobStore(blobstoreOrBucket, r2PublicUrl);
+            }
+        }
+        super({ docstore, blobstore, logger: console });
+    }
+}

package/dist/udf/executor/isolated-executor.d.ts

@@ -0,0 +1,24 @@
+import type { UdfExec, UdfResult } from "@concavejs/core/udf";
+import type { UdfExecutorRpc } from "../../worker/udf-worker";
+export interface UdfExecIsolatedOptions {
+    /** The RPC stub for the UDF worker */
+    stub: UdfExecutorRpc;
+    /** Instance name for syscall routing (default: "singleton") */
+    instance?: string;
+    /** Project ID for syscall routing (default: "default") */
+    projectId?: string;
+}
+/**
+ * Executes a UDF in an isolated worker via RPC.
+ * This class acts as an RPC client.
+ *
+ * Supports passing instance context for proper syscall routing through the DO.
+ */
+export declare class UdfExecIsolated implements UdfExec {
+    private rpc;
+    private instance;
+    private projectId;
+    constructor(stubOrOptions: UdfExecutorRpc | UdfExecIsolatedOptions);
+    execute(path: string, args: Record<string, any>, type: "query" | "mutation" | "action", auth?: any, componentPath?: string, requestId?: string): Promise<UdfResult>;
+    executeHttp(request: Request, auth?: any, requestId?: string): Promise<Response>;
+}

package/dist/udf/executor/isolated-executor.js

@@ -0,0 +1,31 @@
+/**
+ * Executes a UDF in an isolated worker via RPC.
+ * This class acts as an RPC client.
+ *
+ * Supports passing instance context for proper syscall routing through the DO.
+ */
+export class UdfExecIsolated {
+    rpc;
+    instance;
+    projectId;
+    constructor(stubOrOptions) {
+        if ("stub" in stubOrOptions) {
+            this.rpc = stubOrOptions.stub;
+            this.instance = stubOrOptions.instance ?? "singleton";
+            this.projectId = stubOrOptions.projectId ?? "default";
+        }
+        else {
+            // Backwards compatibility: just the stub
+            this.rpc = stubOrOptions;
+            this.instance = "singleton";
+            this.projectId = "default";
+        }
+    }
+    async execute(path, args, type, auth, componentPath, requestId) {
+        // Pass instance context for syscall routing
+        return this.rpc.execute(path, args, type, auth, componentPath, requestId, this.instance, this.projectId);
+    }
+    async executeHttp(request, auth, requestId) {
+        return this.rpc.executeHttp(request, auth, requestId, this.instance, this.projectId);
+    }
+}