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

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

@@ -0,0 +1,38 @@
+/**
+ * Cloudflare WebSocket Adapter
+ *
+ * Adapts Cloudflare Workers WebSocket to the platform-agnostic WebSocketConnection interface
+ */
+import { type WebSocketConnection, WebSocketReadyState, type WebSocketMessageHandler, type WebSocketCloseHandler, type WebSocketErrorHandler } from "@concavejs/core/abstractions";
+export declare class CFWebSocketAdapter implements WebSocketConnection {
+    private ws;
+    private messageHandlers;
+    private closeHandlers;
+    private errorHandlers;
+    constructor(ws: WebSocket);
+    get readyState(): WebSocketReadyState;
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    onMessage(handler: WebSocketMessageHandler): void;
+    onClose(handler: WebSocketCloseHandler): void;
+    onError(handler: WebSocketErrorHandler): void;
+    /**
+     * Internal method to trigger message handlers
+     * Call this from your Durable Object's webSocketMessage handler
+     */
+    triggerMessage(data: string | ArrayBuffer): void;
+    /**
+     * Internal method to trigger close handlers
+     * Call this from your Durable Object's webSocketClose handler
+     */
+    triggerClose(code?: number, reason?: string): void;
+    /**
+     * Internal method to trigger error handlers
+     * Call this from your Durable Object's webSocketError handler
+     */
+    triggerError(error: Error): void;
+    /**
+     * Get the underlying Cloudflare WebSocket
+     */
+    get underlying(): WebSocket;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Cloudflare WebSocket Adapter
+ *
+ * Adapts Cloudflare Workers WebSocket to the platform-agnostic WebSocketConnection interface
+ */
+import { WebSocketReadyState, } from "@concavejs/core/abstractions";
+export class CFWebSocketAdapter {
+    ws;
+    messageHandlers = [];
+    closeHandlers = [];
+    errorHandlers = [];
+    constructor(ws) {
+        this.ws = ws;
+    }
+    get readyState() {
+        // Map CF WebSocket ready states to our enum
+        switch (this.ws.readyState) {
+            case WebSocket.READY_STATE_CONNECTING:
+                return WebSocketReadyState.CONNECTING;
+            case WebSocket.READY_STATE_OPEN:
+                return WebSocketReadyState.OPEN;
+            case WebSocket.READY_STATE_CLOSING:
+                return WebSocketReadyState.CLOSING;
+            case WebSocket.READY_STATE_CLOSED:
+                return WebSocketReadyState.CLOSED;
+            default:
+                return WebSocketReadyState.CLOSED;
+        }
+    }
+    send(data) {
+        this.ws.send(data);
+    }
+    close(code, reason) {
+        if (code !== undefined) {
+            this.ws.close(code, reason);
+        }
+        else {
+            this.ws.close();
+        }
+    }
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    onClose(handler) {
+        this.closeHandlers.push(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.push(handler);
+    }
+    /**
+     * Internal method to trigger message handlers
+     * Call this from your Durable Object's webSocketMessage handler
+     */
+    triggerMessage(data) {
+        for (const handler of this.messageHandlers) {
+            handler(data);
+        }
+    }
+    /**
+     * Internal method to trigger close handlers
+     * Call this from your Durable Object's webSocketClose handler
+     */
+    triggerClose(code, reason) {
+        for (const handler of this.closeHandlers) {
+            handler(code, reason);
+        }
+    }
+    /**
+     * Internal method to trigger error handlers
+     * Call this from your Durable Object's webSocketError handler
+     */
+    triggerError(error) {
+        for (const handler of this.errorHandlers) {
+            handler(error);
+        }
+    }
+    /**
+     * Get the underlying Cloudflare WebSocket
+     */
+    get underlying() {
+        return this.ws;
+    }
+}

package/dist/durable-objects/blobstore-rpc.d.ts

@@ -0,0 +1,13 @@
+import type { BlobStore, StorageOptions, StorageMetadata } from "@concavejs/core/abstractions";
+/**
+ * BlobStore RPC surface for service-binding isolation.
+ * Provides async delegation methods for blob storage operations.
+ */
+export declare class BlobStoreRpc {
+    private readonly blobstore;
+    constructor(blobstore: BlobStore);
+    store(buffer: ArrayBuffer, options?: StorageOptions): Promise<StorageMetadata>;
+    get(storageId: string): Promise<ArrayBuffer | null>;
+    delete(storageId: string): Promise<void>;
+    getUrl(storageId: string): Promise<string | null>;
+}

package/dist/durable-objects/blobstore-rpc.js

@@ -0,0 +1,27 @@
+/**
+ * BlobStore RPC surface for service-binding isolation.
+ * Provides async delegation methods for blob storage operations.
+ */
+export class BlobStoreRpc {
+    blobstore;
+    constructor(blobstore) {
+        this.blobstore = blobstore;
+    }
+    async store(buffer, options) {
+        return this.blobstore.store(buffer, options);
+    }
+    async get(storageId) {
+        const result = await this.blobstore.get(storageId);
+        if (result === null)
+            return null;
+        if (result instanceof Blob)
+            return result.arrayBuffer();
+        return result;
+    }
+    async delete(storageId) {
+        return this.blobstore.delete(storageId);
+    }
+    async getUrl(storageId) {
+        return this.blobstore.getUrl(storageId);
+    }
+}

package/dist/durable-objects/concave-do-base.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Base class for ConcaveDO implementations
+ *
+ * This provides the common functionality shared between runtime-cf and runtime-cloud.
+ * Subclasses provide platform-specific wiring through constructor config.
+ */
+import { DurableObject } from "cloudflare:workers";
+import type { UdfExec, UdfResult } from "@concavejs/core/udf";
+import type { DocStore, DocumentLogEntry, DatabaseIndexUpdate, Interval, Order, IndexKeyBytes, LatestDocument, TimestampRange, InternalDocumentId, GlobalKey, DocumentPrevTsQuery, SearchIndexDefinition, VectorIndexDefinition } from "@concavejs/core/docstore";
+import type { BlobStore, StorageOptions, StorageMetadata } from "@concavejs/core/abstractions";
+import { ScheduledFunctionExecutor, CronExecutor } from "@concavejs/core";
+import type { SerializedKeyRange } from "@concavejs/core/queryengine";
+import type { JSONValue } from "convex/values";
+import type { JWTValidationConfig } from "@concavejs/core/auth";
+/**
+ * Configuration for ConcaveDOBase
+ */
+export interface ConcaveDOAdapterContext<Env = any> {
+    state: DurableObjectState;
+    env: Env;
+    instance: string;
+}
+export interface ConcaveDOExecutorContext<Env = any> extends ConcaveDOAdapterContext<Env> {
+    docstore: DocStore;
+    blobstore?: BlobStore;
+}
+export interface ConcaveDOConfig {
+    /** Override the DocStore implementation (default: DODocStore) */
+    createDocstore?: (context: ConcaveDOAdapterContext) => DocStore;
+    /** Override the BlobStore implementation */
+    createBlobstore?: (context: ConcaveDOAdapterContext) => BlobStore | undefined;
+    /** Create the UDF executor from resolved runtime services */
+    createUdfExecutor: (context: ConcaveDOExecutorContext) => UdfExec;
+    /**
+     * Pre-computed cron specs to sync on initialization.
+     * When provided, these are used directly instead of auto-discovering from modules.
+     * Useful for deploy pipelines that extract specs at build time.
+     */
+    cronSpecs?: Record<string, any>;
+    /**
+     * Whether to auto-discover cron specs from registered modules (default: true).
+     * Set to false to disable auto-discovery (e.g. if no modules are registered globally).
+     * Ignored when `cronSpecs` is explicitly provided.
+     */
+    discoverCrons?: boolean;
+}
+/**
+ * Base class for Concave Durable Objects
+ *
+ * Provides:
+ * - Request handling (fetch, syscall, HTTP)
+ * - Scheduled function execution
+ * - Cron job execution
+ * - SyncDO notification
+ *
+ * Subclasses/configurers provide:
+ * - createUdfExecutor(): Platform-specific UDF executor creation
+ */
+export declare class ConcaveDOBase extends DurableObject {
+    protected _docstore: DocStore;
+    protected _blobstore?: BlobStore;
+    protected udfExecutor: UdfExec;
+    protected doState: DurableObjectState;
+    env: any;
+    protected scheduler: ScheduledFunctionExecutor;
+    protected cronExecutor: CronExecutor;
+    private readonly docStoreRpc;
+    private readonly blobStoreRpc;
+    private readonly syncNotifier;
+    private schedulerManager;
+    /** Cached search/vector index definitions for reuse (e.g. after reset-test-state) */
+    protected cachedSearchIndexes: SearchIndexDefinition[];
+    protected cachedVectorIndexes: VectorIndexDefinition[];
+    /** Cached JWT providers from auth.config.ts */
+    protected cachedJwtProviders: JWTValidationConfig[];
+    constructor(state: DurableObjectState, env: any, config: ConcaveDOConfig);
+    /**
+     * Initialize scheduler and cron executor
+     */
+    private initializeSchedulers;
+    /**
+     * Discover and sync cron specs during DO initialization.
+     * Supports both pre-computed specs (from deploy pipelines) and
+     * runtime auto-discovery from the global module registry.
+     */
+    private initializeCronSpecs;
+    private currentSnapshotTimestamp;
+    /**
+     * Main request handler
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Handle UDF execution request
+     */
+    protected handleUdfRequest(request: Request): Promise<Response>;
+    /**
+     * Handle HTTP action requests
+     */
+    protected handleHttp(request: Request): Promise<Response>;
+    /**
+     * Execute a UDF
+     */
+    protected execute(path: string, args: Record<string, any>, type: "query" | "mutation" | "action", auth?: any, componentPath?: string, requestId?: string, snapshotTimestamp?: bigint): Promise<UdfResult>;
+    /**
+     * Handle scheduled function alarms
+     */
+    alarm(): Promise<void>;
+    /**
+     * Reschedule alarms
+     */
+    protected reschedule(): Promise<void>;
+    /**
+     * Sync cron specs
+     */
+    syncCronSpecs(cronSpecs: Record<string, any>): Promise<void>;
+    setupSchema(options?: {
+        searchIndexes?: SearchIndexDefinition[];
+        vectorIndexes?: VectorIndexDefinition[];
+    }): Promise<void>;
+    write(documents: DocumentLogEntry[], indexes: Set<{
+        ts: bigint;
+        update: DatabaseIndexUpdate;
+    }>, conflictStrategy: "Error" | "Overwrite"): Promise<void>;
+    get(id: InternalDocumentId, readTimestamp?: bigint): Promise<LatestDocument | null>;
+    scan(table: string, readTimestamp?: bigint): Promise<LatestDocument[]>;
+    scanPaginated(table: string, cursor: string | null, limit: number, order: Order, readTimestamp?: bigint): Promise<{
+        documents: LatestDocument[];
+        nextCursor: string | null;
+        hasMore: boolean;
+    }>;
+    /**
+     * Generators return arrays over RPC (cannot stream async generators)
+     */
+    index_scan(indexId: string, tabletId: string, readTimestamp: bigint, interval: Interval, order: Order): Promise<[IndexKeyBytes, LatestDocument][]>;
+    /**
+     * Generators return arrays over RPC (cannot stream async generators)
+     */
+    load_documents(range: TimestampRange, order: Order): Promise<DocumentLogEntry[]>;
+    count(table: string): Promise<number>;
+    search(indexId: string, searchQuery: string, filters: Map<string, unknown>, options?: {
+        limit?: number;
+    }): Promise<{
+        doc: LatestDocument;
+        score: number;
+    }[]>;
+    vectorSearch(indexId: string, vector: number[], limit: number, filters: Map<string, string>): Promise<{
+        doc: LatestDocument;
+        score: number;
+    }[]>;
+    getGlobal(key: GlobalKey): Promise<JSONValue | null>;
+    writeGlobal(key: GlobalKey, value: JSONValue): Promise<void>;
+    previous_revisions(queries: Set<{
+        id: InternalDocumentId;
+        ts: bigint;
+    }>): Promise<[string, DocumentLogEntry][]>;
+    previous_revisions_of_documents(queries: Set<DocumentPrevTsQuery>): Promise<[string, DocumentLogEntry][]>;
+    blobstoreStore(buffer: ArrayBuffer, options?: StorageOptions): Promise<StorageMetadata>;
+    blobstoreGet(storageId: string): Promise<ArrayBuffer | null>;
+    blobstoreDelete(storageId: string): Promise<void>;
+    blobstoreGetUrl(storageId: string): Promise<string | null>;
+    /**
+     * Notify SyncDO of writes for subscription invalidation
+     */
+    protected notifySyncDo(writtenRanges?: SerializedKeyRange[], writtenTables?: string[] | undefined, commitTimestamp?: bigint): Promise<void>;
+    /**
+     * Get CORS headers for responses
+     */
+    protected corsHeaders(request?: Request): Record<string, string>;
+}