lopata 0.18.3 → 0.19.0

package/dist/types/worker-registry.d.ts

@@ -1,4 +1,14 @@
 import type { GenerationManager } from './generation-manager';
+import type { WorkerThreadExecutor } from './worker-thread/executor';
+export type ResolvedTarget = {
+    kind: 'thread';
+    env: Record<string, unknown>;
+    executor: WorkerThreadExecutor;
+} | {
+    kind: 'in-process';
+    env: Record<string, unknown>;
+    workerModule: Record<string, unknown>;
+};
 /**
  * Central registry holding all worker GenerationManagers, keyed by worker name.
  * Used to resolve cross-worker service bindings.
@@ -16,10 +26,7 @@ export declare class WorkerRegistry {
      * Lazily resolve a target worker's module and env from its active generation.
      * Called on each service binding invocation so hot-reloaded workers are picked up.
      */
-    resolveTarget(workerName: string): {
-        workerModule: Record<string, unknown>;
-        env: Record<string, unknown>;
-    };
+    resolveTarget(workerName: string): ResolvedTarget;
     /** List all registered managers (for dashboard) */
     listManagers(): Map<string, GenerationManager>;
 }

package/dist/types/worker-thread/do-protocol.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Message protocol for the main ↔ DO-instance-worker channel.
+ *
+ * Sibling of `protocol.ts` (the main ↔ user-worker channel). The two channels
+ * are structurally parallel — same concepts under channel-specific names
+ * (`do-stream-chunk` here vs `stream-chunk` there, `do-req-stream-*` vs
+ * `req-stream-*`) — and both reuse the unified cross-thread RPC frames
+ * (`RpcCallRequest`, `RpcReply`, …) defined in `protocol.ts`. Keeping the DO
+ * channel's message types here (rather than inline in `do-executor-worker.ts`)
+ * lets the two channels be lined up and cross-referenced in one place; the
+ * executor/entry implementation logic stays in the bindings layer.
+ */
+import type { RpcCallRequest, RpcFetchRequest, RpcGetRequest, RpcReply, RpcReqStreamChunk, RpcReqStreamEnd, RpcReqStreamError, RpcStreamAck, RpcStreamCancel, SerializedError } from './protocol';
+/**
+ * DO worker → main: the instance's lifecycle state changed. Main mirrors these
+ * flags onto the executor so the idle reaper behaves correctly:
+ *  - `aborted` — `state.abort()` was called; the executor must be evicted and
+ *    recreated fresh on next access (otherwise every command keeps throwing).
+ *  - `blocked` — `blockConcurrencyWhile` is running; the executor must not be
+ *    evicted mid-block.
+ */
+export interface DoStateSignal {
+    type: 'do-state';
+    aborted: boolean;
+    blocked: boolean;
+}
+/** Commands sent from main thread to worker */
+export type DOCommand = {
+    type: 'fetch';
+    url: string;
+    method: string;
+    headers: [string, string][];
+    body: ArrayBuffer | null;
+    /**
+     * When set, the request body is streamed: `body` is `null` and main pumps
+     * `do-req-stream-*` for this id so the DO worker reconstructs a
+     * `ReadableStream` for the rebuilt `Request`. Allows large uploads /
+     * streaming proxies to reach `instance.fetch()` incrementally.
+     */
+    streamId?: number;
+} | {
+    type: 'rpc-call';
+    method: string;
+    args: unknown[];
+} | {
+    type: 'rpc-get';
+    prop: string;
+} | {
+    type: 'alarm';
+    retryCount: number;
+} | {
+    type: 'cleanup';
+};
+/** Results returned from worker to main thread */
+export type DOResult = {
+    type: 'fetch';
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+    body: ArrayBuffer | null;
+    /** Set when the DO's fetch handler returned a `Response{status:101, webSocket}`. */
+    fetchWebSocketId?: string;
+    /**
+     * When set, the body is streamed: `body` is `null` and the DO worker pumps
+     * `do-stream-chunk` / `do-stream-end` / `do-stream-error` for this id so
+     * main can reconstruct a `ReadableStream` and ship headers immediately.
+     * Mutually exclusive with `fetchWebSocketId`.
+     */
+    streamId?: number;
+} | {
+    type: 'rpc-call';
+    value: unknown;
+} | {
+    type: 'rpc-get';
+    kind: 'value';
+    value: unknown;
+} | {
+    type: 'rpc-get';
+    kind: 'function';
+} | {
+    type: 'alarm';
+} | {
+    type: 'cleanup';
+} | {
+    type: 'error';
+    error: SerializedError;
+};
+/**
+ * Reverse-streaming for DO instance fetch responses (DO worker → main). When a
+ * DO `fetch()` returns a `Response` with a body, the worker ships the `result`
+ * with `streamId` set and pumps the body via these messages so SSE / chunked
+ * responses reach main (and onward to the caller) incrementally.
+ *
+ * Id space: per-`WorkerExecutor`. Independent of the `RpcStreamRegistry` used
+ * by env-binding fetches (those flow main → DO worker over the same channel).
+ */
+export interface DoStreamChunk {
+    type: 'do-stream-chunk';
+    streamId: number;
+    chunk: Uint8Array;
+}
+export interface DoStreamEnd {
+    type: 'do-stream-end';
+    streamId: number;
+}
+export interface DoStreamError {
+    type: 'do-stream-error';
+    streamId: number;
+    error: SerializedError;
+}
+/** main → DO worker: caller dropped the reconstructed body — stop the pump. */
+export interface DoStreamCancel {
+    type: 'do-stream-cancel';
+    streamId: number;
+}
+/** main → DO worker: main consumed a DO-fetch response-body chunk and grants
+ *  the DO worker one more credit (see `STREAM_BACKPRESSURE_WINDOW`). */
+export interface DoStreamAck {
+    type: 'do-stream-ack';
+    streamId: number;
+}
+/**
+ * Forward-direction streaming for the DOCommand 'fetch' request body (main →
+ * DO worker). Main ships the 'fetch' command with `streamId` set and pumps
+ * the body via these messages so the DO worker reconstructs a
+ * `ReadableStream` for the rebuilt `Request`.
+ *
+ * Id space: per-`WorkerExecutor`, independent of the response-side `streamId`
+ * (`DoStreamChunk`) and the env-binding RPC stream registries.
+ */
+export interface DoReqStreamChunk {
+    type: 'do-req-stream-chunk';
+    streamId: number;
+    chunk: Uint8Array;
+}
+export interface DoReqStreamEnd {
+    type: 'do-req-stream-end';
+    streamId: number;
+}
+export interface DoReqStreamError {
+    type: 'do-req-stream-error';
+    streamId: number;
+    error: SerializedError;
+}
+/** DO worker → main: instance code cancelled the reconstructed request body. */
+export interface DoReqStreamCancel {
+    type: 'do-req-stream-cancel';
+    streamId: number;
+}
+/** DO worker → main: instance code pulled a request-body chunk and grants main's
+ *  pump one more credit (cross-thread backpressure, mirrors {@link DoStreamAck}). */
+export interface DoReqStreamAck {
+    type: 'do-req-stream-ack';
+    streamId: number;
+}
+/** Messages from main thread → worker */
+export type DOWorkerMessage = {
+    type: 'command';
+    id: number;
+    command: DOCommand;
+}
+/** A real client wrote bytes; deliver them to the user's `server` peer inside the DO worker. */
+ | {
+    type: 'fetch-ws-incoming';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'fetch-ws-close-in';
+    wsId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/**
+ * Env-binding fetch returned `Response{status:101, webSocket}`; main adopted
+ * the upstream `CFWebSocket` and ships its events to the DO worker, where a
+ * user-facing peer reconstructed via `WsGuestBridge.createBridgedSocket`
+ * dispatches them on user code's `.addEventListener('message')` / `.onmessage`.
+ */
+ | {
+    type: 'env-ws-incoming';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'env-ws-close-in';
+    wsId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+} | RpcReply
+/** Caller-side cancel for a streamed DO-fetch response body. */
+ | DoStreamCancel
+/** Caller-side credit grant for a streamed DO-fetch response body. */
+ | DoStreamAck
+/** Body chunks for a streamed DO-fetch *request* body (main → DO worker). */
+ | DoReqStreamChunk | DoReqStreamEnd | DoReqStreamError;
+/** Messages from worker → main thread */
+export type DOMainMessage = {
+    type: 'need-init';
+} | {
+    type: 'ready';
+} | {
+    type: 'result';
+    id: number;
+    result: DOResult;
+} | {
+    type: 'alarm-set';
+    time: number | null;
+} | DoStateSignal
+/** The user's `server` peer sent bytes; forward to the real client via the main-side CFWebSocket. */
+ | {
+    type: 'fetch-ws-outgoing';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'fetch-ws-close-out';
+    wsId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/**
+ * User code (inside the DO worker) emitted bytes / closed on a CFWebSocket
+ * reconstructed from an env-binding fetch upgrade. Forward to the upstream
+ * peer adopted on main via `_envBindingWsBridge`.
+ */
+ | {
+    type: 'env-ws-outgoing';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'env-ws-close-out';
+    wsId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+} | RpcCallRequest | RpcGetRequest | RpcFetchRequest | RpcStreamCancel | RpcStreamAck | RpcReqStreamChunk | RpcReqStreamEnd | RpcReqStreamError
+/** Body chunks for a streamed DO-fetch response (see {@link DoStreamChunk}). */
+ | DoStreamChunk | DoStreamEnd | DoStreamError
+/** Instance-side cancel for a streamed DO-fetch request body. */
+ | DoReqStreamCancel
+/** Instance-side credit grant for a streamed DO-fetch request body. */
+ | DoReqStreamAck
+/**
+ * Container lifecycle notifications. Main owns the active-container Set so
+ * one centralized `exit` handler can `docker rm -f` everything, regardless
+ * of which DO worker created it. The label-based reaper handles processes
+ * that die before the handler runs.
+ */
+ | {
+    type: 'container-registered';
+    name: string;
+} | {
+    type: 'container-removed';
+    name: string;
+};

package/dist/types/worker-thread/entry.d.ts

@@ -0,0 +1,2 @@
+/** Worker-thread entry: imports user module, builds env, dispatches fetch. */
+export {};

package/dist/types/worker-thread/execution-context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Worker-thread implementation of CF's `ExecutionContext`. Tracks
+ * `waitUntil()` promises locally (they capture worker-side closures) and
+ * notifies main of each add/settle so reload drain can wait for them.
+ */
+import type { WorkerMessage } from './protocol';
+/**
+ * Register a background promise with main's reload-drain accounting (same
+ * `wait-until-add` / `wait-until-settle` protocol as `ctx.waitUntil`). Used for
+ * worker-side work that isn't tied to an `ExecutionContext` — e.g. an in-flight
+ * queue batch, so reload drain waits for it instead of terminating mid-batch.
+ */
+export declare function trackBackgroundWork(post: (msg: WorkerMessage) => void, promise: Promise<unknown>): void;
+export declare class WorkerExecutionContext {
+    /** `ctx.props` — carries the calling worker's service-binding `props` for
+     *  `entrypoint-rpc` / `fetch` dispatch; `{}` for top-level HTTP. */
+    readonly props: Record<string, unknown>;
+    private _post;
+    constructor(post: (msg: WorkerMessage) => void, props?: Record<string, unknown>);
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}

package/dist/types/worker-thread/executor.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Main-thread side of the worker-thread runtime.
+ *
+ * Spawns a Bun Worker that hosts the user module graph (see `entry.ts`)
+ * and exposes `executeFetch()` to the rest of lopata. Lifecycle is
+ * one-shot: each Generation owns its own executor and `dispose()` is
+ * called when the generation is stopped (i.e. on every reload).
+ */
+import type { WranglerConfig } from '../config';
+import type { WorkflowControlOp, WorkflowControlResult } from './protocol';
+type HandlerResult = {
+    ok: true;
+} | {
+    ok: false;
+    noHandler: true;
+};
+export interface WorkerThreadExecutorOptions {
+    modulePath: string;
+    config: WranglerConfig;
+    baseDir: string;
+    workerName?: string;
+    browserConfig?: {
+        wsEndpoint?: string;
+        executablePath?: string;
+        headless?: boolean;
+    };
+    /** Main-thread env holding the stateful binding instances the worker calls into via RPC. */
+    mainEnv: Record<string, unknown>;
+}
+export interface WorkerReadyInfo {
+    /** className → whether the user's DO class defines an `alarm()` handler. */
+    doAlarmHandlers: Record<string, boolean>;
+}
+export declare class WorkerThreadExecutor {
+    private _worker;
+    private _ready;
+    private _readyResolve;
+    private _readyReject;
+    private _pending;
+    private _pendingHandlers;
+    private _pendingRpc;
+    private _pendingRpcGet;
+    private _pendingWorkflowControl;
+    private _nextId;
+    private _disposed;
+    private _initConfig;
+    private _mainEnv;
+    private _pendingWaitUntil;
+    private _wsBridge;
+    /** Main-side bridge for upstream CFWebSockets adopted from env-binding fetches
+     *  the user worker initiated (`env.DO.fetch('/ws')` returning 101). The worker
+     *  side holds the user-facing peer; events flow both ways so user code can
+     *  consume the socket (`.accept()`/`.send()`), not just reship it. */
+    private _envBindingWsBridge;
+    /** Reconstructed response bodies fed by `stream-chunk` from the worker
+     *  (top-level fetch response → main). */
+    private _responseStreams;
+    /** Main-side host of the unified cross-thread RPC channel — binding call/get/
+     *  fetch from the user's worker, with response/request-body streaming. Shared
+     *  with the DO-worker executor; channel-specifics injected as hooks. */
+    private _rpcChannel;
+    /** Outbound request-body pumps for the top-level fetch path (main → worker).
+     *  A `req-stream-cancel` from the worker (user code cancelled `request.body`)
+     *  stops the source reader. */
+    private _topRequestStreams;
+    constructor(options: WorkerThreadExecutorOptions);
+    /** Reject every outstanding promise and tear down bridges. Shared by `onerror`
+     *  (worker crashed) and `dispose()` (planned teardown). */
+    private _failAll;
+    private _send;
+    private _handleMessage;
+    /** Apply a forwarded trace-store write on main. Wrapped in try/catch because
+     *  these run inside `worker.onmessage`: a write that throws (a `BigInt` /
+     *  circular value `JSON.stringify` chokes on, a transient DB error) would be
+     *  an uncaught exception that takes down the whole dev server. A failed trace
+     *  write is diagnostic-only — never worth crashing for. */
+    private _applyTrace;
+    /** Background `waitUntil` promises still in flight on the worker side. */
+    pendingWaitUntil(): number;
+    /** In-flight scheduled/email handlers and inbound entrypoint RPC/property-get
+     *  calls (another worker calling `env.THIS.method()`). Reload drain consults
+     *  this so a cron/email handler or inbound RPC firing just before reload isn't
+     *  force-terminated mid-execution. */
+    pendingHandlerWork(): number;
+    /** In-flight streamed bodies for the top-level fetch path: response bodies the
+     *  client is still downloading (`_responseStreams`, incl. SSE) plus request-body
+     *  pumps still uploading (`_topRequestStreams`). `executeFetch` resolves at the
+     *  headers, so these aren't reflected by `pendingFetch()` — reload drain must
+     *  consult them or it cuts off an active download/SSE with zero grace. */
+    openStreamCount(): number;
+    /** In-flight top-level `executeFetch` calls. A cross-worker service-binding
+     *  fetch (`env.OTHER.fetch()`) lands here directly via the registry without
+     *  touching the target `Generation.activeRequests`, so the drain must consult
+     *  this too — otherwise reloading the target severs the request mid-flight. */
+    pendingFetch(): number;
+    private _resolveBinding;
+    private _pumpTopRequestBody;
+    /** Resolves when the worker has imported the user module successfully. */
+    ready(): Promise<WorkerReadyInfo>;
+    /**
+     * Allocate an id, register a pending promise, post the command. The `build`
+     * callback receives the id + active span context (so sub-spans on the worker
+     * side link to the caller) and returns the actual `WorkerCommand`.
+     */
+    private _sendAndAwait;
+    executeFetch(request: Request, props?: Record<string, unknown>): Promise<Response>;
+    executeScheduled(cronExpr: string, scheduledTime: number): Promise<HandlerResult>;
+    executeEntrypointRpc(entrypoint: string | undefined, method: string, args: unknown[], props?: Record<string, unknown>): Promise<unknown>;
+    executeEntrypointPropertyGet(entrypoint: string | undefined, property: string, props?: Record<string, unknown>): Promise<{
+        kind: 'value';
+        value: unknown;
+    } | {
+        kind: 'function';
+    }>;
+    executeEmail(messageId: string, from: string, to: string, raw: Uint8Array): Promise<HandlerResult>;
+    /** Run a dashboard workflow control op against the live worker-side binding. */
+    executeWorkflowControl(binding: string, op: WorkflowControlOp): Promise<WorkflowControlResult>;
+    /** Tell the worker to stop its queue consumers from claiming new messages
+     *  (reload drain). In-flight batches finish and are awaited via wait-until. */
+    stopQueueConsumers(): void;
+    dispose(): void;
+}
+export {};