lopata 0.18.3 → 0.19.0

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

@@ -0,0 +1,553 @@
+/**
+ * Message protocol between main thread and worker-thread runtime.
+ *
+ * Main thread owns Bun.serve, file watcher, GenerationManager, dashboard.
+ * Worker thread owns the user module graph + per-thread env. Reload =
+ * terminate + respawn.
+ */
+import type { WranglerConfig } from '../config';
+import type { TraceStore } from '../tracing/store';
+import type { SpanData, SpanEventData } from '../tracing/types';
+/** Parent span context handed to the worker so its spans nest under main's server span. */
+export interface ParentSpanContext {
+    traceId: string;
+    spanId: string;
+}
+export type TraceErrorPayload = Parameters<TraceStore['insertError']>[0];
+export interface SerializedRequest {
+    url: string;
+    method: string;
+    headers: [string, string][];
+    body: ArrayBuffer | null;
+    /**
+     * When set, the body is streamed (not buffered): `body` is `null` and the
+     * sender pumps chunk messages keyed by this id. The channel decides which
+     * message family (`req-stream-*` for top-level main→worker fetch,
+     * `rpc-req-stream-*` for cross-thread binding fetch, `do-req-stream-*` for
+     * main→DO-worker fetch). Receiver reconstructs a `ReadableStream` and uses
+     * it as the rebuilt Request's body.
+     */
+    streamId?: number;
+}
+export interface SerializedResponse {
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+    body: ArrayBuffer | null;
+    /** When set, the response carries a WebSocket upgrade — main rebuilds a
+     *  `CFWebSocket` whose peer bridges send/close to this id on the worker. */
+    webSocketId?: string;
+    /**
+     * When set, the body is streamed (not buffered): `body` is `null` and the
+     * worker pumps `stream-chunk` / `stream-end` / `stream-error` for this id.
+     * Main rebuilds a `ReadableStream` so SSE / chunked / otherwise-unbounded
+     * responses reach the client incrementally instead of hanging on a never-
+     * resolving `arrayBuffer()`.
+     */
+    streamId?: number;
+}
+export interface SerializedError {
+    message: string;
+    stack?: string;
+    name?: string;
+    /** Recursively serialized `error.cause` chain (depth-capped). */
+    cause?: SerializedError;
+    /** Enumerable own-properties (err.code, err.status, err.data, …) that user
+     *  or library error handling branches on. Only structured-cloneable values
+     *  are kept (the whole SerializedError must survive postMessage). */
+    props?: Record<string, unknown>;
+}
+/**
+ * Serialize a thrown value for postMessage. MUST be total — it runs inside every
+ * worker-side catch block, so a secondary throw here (a non-stringifiable value,
+ * a throwing getter) would escalate a handled error into `worker.onerror` and
+ * tear down the whole generation. Every value read is guarded.
+ *
+ * Non-Error thrown values (`throw { status: 404 }`, `throw 'boom'`) keep their
+ * cloneable own-enumerable properties so `catch (e) { e.status }` survives the
+ * hop — class identity is lost (it always was, even in-process the wire is
+ * structured-clone), but the payload is preserved.
+ */
+export declare function serializeError(e: unknown, depth?: number): SerializedError;
+export declare function deserializeError(err: SerializedError): Error;
+export interface WorkerInitConfig {
+    modulePath: string;
+    /** Wrangler config — already parsed, with `env.<name>` overrides applied. */
+    config: WranglerConfig;
+    baseDir: string;
+    /**
+     * Main's resolved `.lopata` data dir (`getDataDir()`). The worker thread MUST
+     * open the same SQLite file / r2 / d1 dirs main and the DO workers use —
+     * `baseDir` is per-worker (`dirname(workerDef.config)` in multi-worker mode)
+     * and would otherwise split state into a second db. `baseDir` is kept only for
+     * `.dev.vars`/`.env`/assets resolution, which IS per-worker.
+     */
+    dataDir: string;
+    /** Worker name from `lopata.config.ts` (or single-worker wrangler config). Used
+     *  for span attribution + error attribution; mirrors `Generation.workerName`. */
+    workerName?: string;
+    /** Browser Rendering local dev config (Chrome wsEndpoint or executable path). */
+    browserConfig?: {
+        wsEndpoint?: string;
+        executablePath?: string;
+        headless?: boolean;
+    };
+}
+/** Names of the worker handlers we know how to invoke via RPC. */
+export type WorkerHandlerName = 'fetch' | 'scheduled' | 'email' | 'queue';
+/**
+ * Workflow control operation, routed to the *live* worker-side
+ * `SqliteWorkflowBinding` (which owns the real abort controllers / event
+ * waiters / sleep resolvers — main's binding is hollow in thread mode).
+ * Initiated by the dashboard AND by DO workers, whose `this.env.WF` proxy
+ * models create/get/instance methods as these ops. `binding` is the wrangler
+ * binding name; `instanceId` targets a specific instance for everything except
+ * `create`.
+ */
+export type WorkflowControlOp = {
+    kind: 'create';
+    params: unknown;
+    id?: string;
+} | {
+    kind: 'resumeInterrupted';
+} | {
+    kind: 'terminate';
+    instanceId: string;
+} | {
+    kind: 'pause';
+    instanceId: string;
+} | {
+    kind: 'resume';
+    instanceId: string;
+} | {
+    kind: 'restart';
+    instanceId: string;
+    fromStep?: string;
+} | {
+    kind: 'skipSleep';
+    instanceId: string;
+} | {
+    kind: 'sendEvent';
+    instanceId: string;
+    eventType: string;
+    payload?: unknown;
+} | {
+    kind: 'isSleeping';
+    instanceId: string;
+} | {
+    kind: 'waitingEventTypes';
+    instanceId: string;
+} | {
+    kind: 'status';
+    instanceId: string;
+};
+/** `WorkflowInstance.status()` payload (see `SqliteWorkflowInstance.status`). */
+export interface WorkflowInstanceStatus {
+    status: string;
+    output?: unknown;
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+/** Result payload of a {@link WorkflowControlOp}. `create` reports the new id,
+ *  the introspection reads report their value; mutating ops report nothing. */
+export type WorkflowControlResult = {
+    kind: 'create';
+    id: string;
+} | {
+    kind: 'ok';
+} | {
+    kind: 'isSleeping';
+    value: boolean;
+} | {
+    kind: 'waitingEventTypes';
+    value: string[];
+} | {
+    kind: 'status';
+    value: WorkflowInstanceStatus;
+};
+export interface BindingTarget {
+    binding: string;
+    /**
+     * DO instance target. When set, the resolving side routes through
+     * `env[binding].get(instanceId)` before invoking `method` / `fetch`, so
+     * cross-DO and self-DO access via env-RPC lands on the right instance. Used
+     * by both the DO-stub proxies and the executors' `_resolveBinding`.
+     */
+    instanceId?: string;
+    /**
+     * @internal For DO instance targets created via `idFromName(name)`: the
+     * original name string. Main reconstructs `DurableObjectIdImpl(instanceId,
+     * instanceName)` before calling `binding.get()` so `ctx.id.name` is
+     * preserved across the thread boundary (matches the in-process path).
+     */
+    instanceName?: string;
+}
+/**
+ * Unified cross-thread RPC frame. Used in both directions:
+ *  - user-worker → main (`WorkerThreadExecutor`): stateful binding access from the user's worker
+ *  - DO-worker → main (`WorkerExecutor`): same, from a DO instance worker
+ *
+ * `parent` propagates trace context so spans created on the receiving side
+ * (including spans inside *further* nested cross-thread hops) link back to the
+ * caller's active span. Without it nested service-binding calls float at root.
+ */
+export interface RpcCallRequest {
+    type: 'rpc-call';
+    id: number;
+    target: BindingTarget;
+    method: string;
+    args: unknown[];
+    parent?: ParentSpanContext;
+}
+export interface RpcFetchRequest {
+    type: 'rpc-fetch';
+    id: number;
+    target: BindingTarget;
+    request: SerializedRequest;
+    parent?: ParentSpanContext;
+}
+/**
+ * Property read on a cross-thread binding (`await env.SVC.someProp`). The
+ * worker-side binding proxy is callable (for method calls) AND thenable (for
+ * property reads); awaiting it posts this and main resolves the property on the
+ * main-side binding (which itself implements the thenable property-get). The
+ * reply reuses {@link RpcCallReply} / {@link RpcCallErrorReply}.
+ */
+export interface RpcGetRequest {
+    type: 'rpc-call-get';
+    id: number;
+    target: BindingTarget;
+    property: string;
+    parent?: ParentSpanContext;
+}
+export interface RpcCallReply {
+    type: 'rpc-call-result';
+    id: number;
+    value: unknown;
+}
+export interface RpcCallErrorReply {
+    type: 'rpc-call-error';
+    id: number;
+    error: SerializedError;
+}
+export interface RpcFetchReply {
+    type: 'rpc-fetch-result';
+    id: number;
+    response: SerializedResponse;
+}
+export interface RpcFetchErrorReply {
+    type: 'rpc-fetch-error';
+    id: number;
+    error: SerializedError;
+}
+/**
+ * Reverse-direction streaming for {@link RpcFetchReply}. When main's
+ * `dispatchRpcFetch` resolves a response with a body, it ships headers + a
+ * `streamId` immediately and pumps the body via these messages so SSE / chunked
+ * responses returned from a service binding reach the caller incrementally
+ * instead of waiting for the source to finish.
+ *
+ * Direction: main → worker (mirrors `stream-chunk` / `stream-end` /
+ * `stream-error` which carry the worker → main top-level fetch path).
+ *
+ * Id space: independent counter inside `dispatchRpcFetch`; carried in
+ * {@link SerializedResponse}.streamId on the matching `rpc-fetch-result`.
+ */
+export interface RpcStreamChunk {
+    type: 'rpc-stream-chunk';
+    streamId: number;
+    chunk: Uint8Array;
+}
+export interface RpcStreamEnd {
+    type: 'rpc-stream-end';
+    streamId: number;
+}
+export interface RpcStreamError {
+    type: 'rpc-stream-error';
+    streamId: number;
+    error: SerializedError;
+}
+/** worker → main: the caller cancelled the reconstructed response body
+ *  (consumer dropped, AbortController, etc). Main stops the source reader. */
+export interface RpcStreamCancel {
+    type: 'rpc-stream-cancel';
+    streamId: number;
+}
+/** worker → main: the caller consumed an rpc-fetch response-body chunk and
+ *  grants the sender one more credit (see `STREAM_BACKPRESSURE_WINDOW`). */
+export interface RpcStreamAck {
+    type: 'rpc-stream-ack';
+    streamId: number;
+}
+/**
+ * Forward-direction streaming for {@link RpcFetchRequest}'s body. The sender
+ * (worker-side `RpcClient.callFetch`) ships the request shell + a
+ * `requestStreamId` immediately and pumps the body via these messages so
+ * uploads / streaming proxies reach the binding's `fetch()` incrementally
+ * instead of waiting for the full body to buffer.
+ *
+ * Direction: sender → receiver of the unified RPC channel. For the
+ * user-worker channel that's worker → main; for the DO-worker channel that's
+ * DO worker → main. Both `WorkerThreadExecutor` and `WorkerExecutor` host an
+ * inbound request-stream receiver and route these messages into it.
+ *
+ * Id space: independent counter inside the sending `RpcClient`; carried in
+ * {@link SerializedRequest}.streamId on the matching `rpc-fetch`.
+ */
+export interface RpcReqStreamChunk {
+    type: 'rpc-req-stream-chunk';
+    streamId: number;
+    chunk: Uint8Array;
+}
+export interface RpcReqStreamEnd {
+    type: 'rpc-req-stream-end';
+    streamId: number;
+}
+export interface RpcReqStreamError {
+    type: 'rpc-req-stream-error';
+    streamId: number;
+    error: SerializedError;
+}
+/** receiver → sender: the binding consumer cancelled the reconstructed
+ *  request body. Sender stops the source reader. */
+export interface RpcReqStreamCancel {
+    type: 'rpc-req-stream-cancel';
+    streamId: number;
+}
+/** receiver → sender: the binding consumer pulled a request-body chunk and
+ *  grants the sender one more credit (cross-thread backpressure, mirrors
+ *  {@link RpcStreamAck} on the response side). */
+export interface RpcReqStreamAck {
+    type: 'rpc-req-stream-ack';
+    streamId: number;
+}
+export type RpcReply = RpcCallReply | RpcCallErrorReply | RpcFetchReply | RpcFetchErrorReply | RpcStreamChunk | RpcStreamEnd | RpcStreamError | RpcReqStreamCancel | RpcReqStreamAck;
+/** Main → worker */
+export type WorkerCommand = {
+    type: 'init';
+    config: WorkerInitConfig;
+} | {
+    type: 'fetch';
+    id: number;
+    request: SerializedRequest;
+    parent?: ParentSpanContext;
+    props?: Record<string, unknown>;
+} | {
+    type: 'scheduled';
+    id: number;
+    cronExpr: string;
+    scheduledTime: number;
+    parent?: ParentSpanContext;
+} | {
+    type: 'email';
+    id: number;
+    messageId: string;
+    from: string;
+    to: string;
+    raw: Uint8Array;
+    parent?: ParentSpanContext;
+} | RpcCallReply | RpcCallErrorReply | RpcFetchReply | RpcFetchErrorReply | RpcStreamChunk | RpcStreamEnd | RpcStreamError | RpcReqStreamCancel | RpcReqStreamAck | {
+    type: 'entrypoint-rpc';
+    id: number;
+    entrypoint: string | undefined;
+    method: string;
+    args: unknown[];
+    props?: Record<string, unknown>;
+    parent?: ParentSpanContext;
+} | {
+    type: 'entrypoint-rpc-get';
+    id: number;
+    entrypoint: string | undefined;
+    property: string;
+    props?: Record<string, unknown>;
+    parent?: ParentSpanContext;
+} | {
+    type: 'workflow-control';
+    id: number;
+    binding: string;
+    op: WorkflowControlOp;
+    parent?: ParentSpanContext;
+} | {
+    type: 'ws-client-message';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'ws-client-close';
+    wsId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+} | {
+    type: 'env-ws-incoming';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'env-ws-close-in';
+    wsId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+} | {
+    type: 'stream-cancel';
+    id: number;
+} | {
+    type: 'stream-ack';
+    id: number;
+} | {
+    type: 'req-stream-chunk';
+    streamId: number;
+    chunk: Uint8Array;
+} | {
+    type: 'req-stream-end';
+    streamId: number;
+} | {
+    type: 'req-stream-error';
+    streamId: number;
+    error: SerializedError;
+} | {
+    type: 'stop-queue-consumers';
+} | {
+    type: 'fetch-abort';
+    id: number;
+};
+/** Worker → main */
+export type WorkerMessage = {
+    type: 'need-init';
+}
+/**
+ * Sent after the user module imports successfully.
+ *
+ * `doAlarmHandlers` maps each DO/container class name declared in the
+ * wrangler config to whether its prototype defines an `alarm()` method. Main
+ * uses it to forward `_setAlarmHandlerHint` to each namespace — without this,
+ * thread-mode `hasAlarmHandler()` would always return `false` (the main-side
+ * namespace doesn't load the user module). Missing exports report `false`.
+ */
+ | {
+    type: 'ready';
+    doAlarmHandlers: Record<string, boolean>;
+} | {
+    type: 'init-error';
+    error: SerializedError;
+} | {
+    type: 'fetch-result';
+    id: number;
+    response: SerializedResponse;
+} | {
+    type: 'fetch-error';
+    id: number;
+    error: SerializedError;
+} | {
+    type: 'scheduled-result';
+    id: number;
+} | {
+    type: 'scheduled-error';
+    id: number;
+    error: SerializedError;
+    noHandler?: boolean;
+} | {
+    type: 'email-result';
+    id: number;
+} | {
+    type: 'email-error';
+    id: number;
+    error: SerializedError;
+    noHandler?: boolean;
+} | {
+    type: 'entrypoint-rpc-result';
+    id: number;
+    value: unknown;
+} | {
+    type: 'entrypoint-rpc-error';
+    id: number;
+    error: SerializedError;
+} | {
+    type: 'entrypoint-rpc-get-result';
+    id: number;
+    kind: 'value';
+    value: unknown;
+} | {
+    type: 'entrypoint-rpc-get-result';
+    id: number;
+    kind: 'function';
+} | {
+    type: 'entrypoint-rpc-get-error';
+    id: number;
+    error: SerializedError;
+} | {
+    type: 'workflow-control-result';
+    id: number;
+    result: WorkflowControlResult;
+} | {
+    type: 'workflow-control-error';
+    id: number;
+    error: SerializedError;
+} | RpcCallRequest | RpcGetRequest | RpcFetchRequest | RpcStreamCancel | RpcStreamAck | RpcReqStreamChunk | RpcReqStreamEnd | RpcReqStreamError | {
+    type: 'wait-until-add';
+    id: number;
+} | {
+    type: 'wait-until-settle';
+    id: number;
+} | {
+    type: 'trace-span-insert';
+    span: SpanData;
+} | {
+    type: 'trace-span-end';
+    spanId: string;
+    endTime: number;
+    status: 'ok' | 'error';
+    statusMessage: string | null;
+} | {
+    type: 'trace-span-status';
+    spanId: string;
+    status: 'ok' | 'error';
+    statusMessage: string | null;
+} | {
+    type: 'trace-span-attrs';
+    spanId: string;
+    attrs: Record<string, unknown>;
+} | {
+    type: 'trace-span-event';
+    event: Omit<SpanEventData, 'id'>;
+} | {
+    type: 'trace-error';
+    error: TraceErrorPayload;
+} | {
+    type: 'ws-worker-send';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'ws-worker-close';
+    wsId: string;
+    code: number;
+    reason: string;
+} | {
+    type: 'env-ws-outgoing';
+    wsId: string;
+    data: string | ArrayBuffer;
+} | {
+    type: 'env-ws-close-out';
+    wsId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+} | {
+    type: 'stream-chunk';
+    id: number;
+    chunk: Uint8Array;
+} | {
+    type: 'stream-end';
+    id: number;
+} | {
+    type: 'stream-error';
+    id: number;
+    error: SerializedError;
+} | {
+    type: 'req-stream-cancel';
+    streamId: number;
+} | {
+    type: 'req-stream-ack';
+    streamId: number;
+};

package/dist/types/worker-thread/remote-trace-store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Worker-side stand-in for `TraceStore`. Each operation is forwarded to
+ * main via postMessage so the single persistent store + dashboard
+ * subscribers stay the source of truth. We keep a tiny local mirror of
+ * span statuses because `startSpan` reads `getSpanStatus(spanId)`
+ * synchronously and the bridge is async-only.
+ */
+import type { TraceStore } from '../tracing/store';
+import type { SpanData, SpanEventData } from '../tracing/types';
+import type { TraceErrorPayload, WorkerMessage } from './protocol';
+/** Methods of `TraceStore` actually called from worker-side code. Adding a new
+ *  call site against the store from `span.ts` / `instrument.ts` / `setup-globals.ts`
+ *  must extend this list (and `RemoteTraceStore` below). */
+type RemotedMethods = 'insertSpan' | 'endSpan' | 'setSpanStatus' | 'getSpanStatus' | 'updateAttributes' | 'addEvent' | 'insertError';
+export declare class RemoteTraceStore implements Pick<TraceStore, RemotedMethods> {
+    private _statuses;
+    private _post;
+    constructor(post: (msg: WorkerMessage) => void);
+    insertSpan(span: SpanData): void;
+    endSpan(spanId: string, endTime: number, status: 'ok' | 'error', statusMessage?: string): void;
+    setSpanStatus(spanId: string, status: 'ok' | 'error', statusMessage: string | null): void;
+    getSpanStatus(spanId: string): string | null;
+    updateAttributes(spanId: string, attrs: Record<string, unknown>): void;
+    addEvent(event: Omit<SpanEventData, 'id'>): void;
+    insertError(opts: TraceErrorPayload): void;
+}
+export {};

package/dist/types/worker-thread/rpc-client.d.ts

@@ -0,0 +1,4 @@
+/** Re-export of the shared cross-thread RPC client. Kept as a stable import
+ *  path for callers in `./thread-env.ts`; new code should import directly
+ *  from `./rpc-shared`. */
+export { RpcClient } from './rpc-shared';