lopata 0.18.4 → 0.19.0

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

@@ -0,0 +1,138 @@
+/**
+ * Cross-thread binding RPC — shared core used by both worker channels.
+ *
+ * One frame ({@link RpcCallRequest} / {@link RpcFetchRequest} + their
+ * replies in `./protocol.ts`) covers both:
+ *  - main ↔ user-worker thread (`WorkerThreadExecutor` in `./executor.ts`)
+ *  - main ↔ DO-instance worker thread (`WorkerExecutor` in `../bindings/do-executor-worker.ts`)
+ *
+ * The two channels carry channel-specific messages on top (fetch/scheduled,
+ * ws-bridge events, container lifecycle, …) but the binding RPC half is
+ * identical: resolve binding from `target`, invoke under the caller's trace
+ * context, serialize the result. This module hosts that half.
+ */
+import type { BindingTarget, ParentSpanContext, RpcCallRequest, RpcFetchRequest, RpcGetRequest, RpcReply, RpcReqStreamChunk, RpcReqStreamEnd, RpcReqStreamError, RpcStreamAck, RpcStreamCancel, SerializedResponse } from './protocol';
+import { OutboundStreamRegistry, StreamReceiver } from './stream-shared';
+/**
+ * Cross-thread class-identity registry. `structuredClone` (Bun postMessage)
+ * strips class prototypes — bindings whose RPC args/returns rely on class
+ * identity register a reviver here, and the sender side wraps instances with
+ * `tagCloneable` to ship them over the wire.
+ */
+type Reviver = (raw: Record<string, unknown>) => unknown;
+export declare function registerCloneable(tag: string, revive: Reviver): void;
+/** Sender-side tag: produces a structured-clone-safe payload that the
+ *  receiver rebuilds via the registered reviver. */
+export declare function tagCloneable<T extends Record<string, unknown>>(tag: string, payload: T): T & {
+    __lopata_class: string;
+};
+export declare function reifyArgs(args: unknown[]): unknown[];
+export interface RpcDispatchHooks {
+    /** Resolve a binding from main env (channel-specific: user-worker supports
+     *  `instanceId` namespace .get(), DO channel doesn't). */
+    resolveBinding(target: BindingTarget): Record<string, unknown>;
+    /** Post a reply back through the channel's transport. */
+    post(reply: RpcReply): void;
+    /** Return false once the channel is torn down so we drop late replies. */
+    isAlive(): boolean;
+    /** Optional hook to add transport-specific fields (e.g. webSocketId) to a
+     *  serialized response after fetch resolves. */
+    decorateResponse?(response: Response, serialized: SerializedResponse): void;
+}
+export declare function dispatchRpcCall(req: RpcCallRequest, hooks: RpcDispatchHooks): Promise<void>;
+/**
+ * Resolve a property read on a binding (`await env.SVC.prop`). The main-side
+ * binding is itself a thenable-property proxy (service-binding `toProxy`), so
+ * awaiting `resolved[property]` runs its property-get (including the nested
+ * main→target-thread hop when the target is a worker thread). The resolved
+ * value ships back via the same reply types as a method call. Returning a
+ * non-cloneable value (RpcTarget/function) surfaces as `rpc-call-error` — the
+ * documented cross-thread limitation, same as method returns.
+ */
+export declare function dispatchRpcGet(req: RpcGetRequest, hooks: RpcDispatchHooks): Promise<void>;
+/**
+ * Resolve a binding's fetch and stream the body back to the caller. Headers +
+ * status ship immediately (TTFB preserved); the body flows in
+ * `rpc-stream-chunk` messages and terminates with `rpc-stream-end` or
+ * `rpc-stream-error`. WS upgrades (status 101) are short-circuited — they
+ * carry `webSocketId`, not a body stream. Body-less responses ship without a
+ * `streamId` and no pump.
+ *
+ * The request body is reconstructed from the inbound request-stream messages
+ * when `req.request.streamId` is set, so streaming uploads / proxies reach the
+ * binding's `fetch()` incrementally.
+ */
+export declare function dispatchRpcFetch(req: RpcFetchRequest, hooks: RpcDispatchHooks, streams: OutboundStreamRegistry, requestStreams: StreamReceiver): Promise<void>;
+/**
+ * Main-side host of the unified cross-thread RPC channel. Both
+ * `WorkerThreadExecutor` (user-worker channel) and `WorkerExecutor` (DO-instance
+ * channel) own one. It bundles the outbound response-body pump registry, the
+ * inbound request-body receiver (with backpressure), the call/get/fetch
+ * dispatch, and teardown — so the two executors share a single wiring +
+ * `isAlive`/teardown contract instead of re-implementing (and drifting on) the
+ * glue. The executor supplies channel-specific behavior via {@link RpcDispatchHooks}:
+ * `resolveBinding` (env lookup), `post` (transport), `isAlive` (liveness), and an
+ * optional `decorateResponse` (WS adoption). All hooks should close over the
+ * executor so they read live state lazily.
+ */
+export declare class RpcHostChannel {
+    /** Outbound response-body pumps started by `dispatchRpcFetch`. */
+    private _streams;
+    /** Inbound request-body streams (worker → main binding fetch with body). */
+    private _requestStreams;
+    private _hooks;
+    constructor(hooks: RpcDispatchHooks);
+    /**
+     * Route an inbound message if it belongs to the RPC channel; returns true if
+     * consumed (the caller stops processing it). Mirrors {@link RpcClient.handle}
+     * on the sender side.
+     */
+    handle(msg: {
+        type: string;
+    }): boolean;
+    disposeAll(err: Error): void;
+}
+type RpcClientPost = (req: RpcCallRequest | RpcGetRequest | RpcFetchRequest | RpcStreamCancel | RpcStreamAck | RpcReqStreamChunk | RpcReqStreamEnd | RpcReqStreamError) => void;
+/**
+ * Worker-side RPC caller: posts {@link RpcCallRequest}/{@link RpcFetchRequest},
+ * resolves the matching reply.
+ *
+ * Reads the active span context on every call so spans created on the
+ * receiving thread (including spans inside nested cross-thread hops) nest
+ * under the caller's current span.
+ *
+ * Also reconstructs streamed response bodies: when a `rpc-fetch-result`
+ * carries a `streamId`, the matching `Response` is built around a
+ * `ReadableStream` fed by `rpc-stream-chunk` messages. Consumer cancel posts
+ * `rpc-stream-cancel` so an unbounded source on main stops pumping.
+ */
+export declare class RpcClient {
+    private _pending;
+    private _nextId;
+    private _post;
+    private _getParent;
+    /** Reconstructed inbound response-body streams (rpc-fetch-result.streamId). */
+    private _streams;
+    /** Outbound request-body pumps started by `callFetch`. A receiver-side
+     *  `rpc-req-stream-cancel` arrives via `handle()` and stops the source
+     *  reader so an unbounded upload doesn't pump forever. */
+    private _requestStreams;
+    constructor(post: RpcClientPost, getParent: () => ParentSpanContext | undefined);
+    call(target: BindingTarget, method: string, args: unknown[]): Promise<unknown>;
+    /** Property read on a binding (`await env.SVC.prop`). Reply reuses the
+     *  rpc-call-result/error path via {@link handle}. */
+    callGet(target: BindingTarget, property: string): Promise<unknown>;
+    callFetch(target: BindingTarget, request: Request): Promise<SerializedResponse>;
+    /**
+     * Build a `Response` from a `SerializedResponse`. When `streamId` is set,
+     * the body becomes a `ReadableStream` fed by `rpc-stream-chunk` messages;
+     * otherwise a buffered body. WebSocket adoption is the caller's job (only
+     * `proxyFetch` / `makeEnvBindingProxy` know the channel's wsId convention).
+     */
+    makeResponse(serialized: SerializedResponse): Response;
+    /** Returns true when `msg` was a unified RPC reply we consumed. */
+    handle(msg: {
+        type: string;
+    }): boolean;
+}
+export {};

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

@@ -0,0 +1,12 @@
+/** Request/Response serialization helpers shared between the worker bridges. */
+import type { SerializedRequest, SerializedResponse } from './protocol';
+/**
+ * Build the headers/method/url shell of a `SerializedRequest`. Body handling
+ * is the caller's responsibility — sender code allocates a `streamId` and
+ * pumps the body via channel-specific stream messages, or sets `body: null`
+ * for body-less requests. (`request.body` is *never* materialised here, which
+ * is what allows streaming uploads to cross the worker boundary incrementally.)
+ */
+export declare function serializeRequestShell(request: Request): Omit<SerializedRequest, 'body' | 'streamId'>;
+export declare function deserializeRequest(req: SerializedRequest, body?: ReadableStream<Uint8Array> | null, signal?: AbortSignal): Request;
+export declare function deserializeResponse(serialized: SerializedResponse): Response;

package/dist/types/worker-thread/stream-shared.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Cross-thread stream plumbing — sender and receiver primitives used by every
+ * worker channel (top-level user-worker fetch, DO instance fetch, unified
+ * cross-thread binding-fetch RPC) on both request and response sides.
+ *
+ * `OutboundStreamRegistry` tracks active source pumps so an inbound cancel can
+ * stop the reader. `StreamReceiver` reconstructs a `ReadableStream` on the
+ * receiving end, buffering chunks that race ahead of `start()` (the controller
+ * only registers when the consumer pulls the body, which on Bun lands after
+ * the first chunk message in some interleavings). `pumpStream` is the
+ * symmetric sender-side helper: it consumes a `ReadableStream`, registers the
+ * source reader so an inbound cancel can stop it, and posts channel-specific
+ * envelope messages until the body completes or errors.
+ */
+import type { SerializedError } from './protocol';
+/**
+ * Default cross-thread backpressure window (chunk count) for response-body
+ * streams. Bounds in-flight chunks so a fast producer (e.g. proxying a large R2
+ * object, a tight SSE/generated stream) can't race ahead of a slow consumer and
+ * grow memory unbounded. Small enough to bound memory, large enough to keep the
+ * pipe full across the postMessage round-trip.
+ *
+ * The effective ceiling is ~2x this value: the sender is seeded `window`
+ * credits up front (so it can burst without waiting a round-trip) AND the
+ * receiver's `ReadableStream` grants one more credit per `pull()` while its
+ * own queue (highWaterMark = `window`) has room. Both halves are intentional —
+ * seeding 0 would clock the pump to one chunk per postMessage round-trip from
+ * a cold start. "Window" below means this seeded half; double it for the hard
+ * memory bound.
+ */
+export declare const STREAM_BACKPRESSURE_WINDOW = 8;
+export declare class OutboundStreamRegistry {
+    private _nextStreamId;
+    private _streams;
+    allocateId(): number;
+    /** Number of source pumps still running. Reload drain consults this so an
+     *  in-flight upload / response-body pump isn't force-terminated mid-stream. */
+    activeCount(): number;
+    register(streamId: number, reader: {
+        cancel(reason?: unknown): Promise<unknown>;
+    }, initialCredits?: number): void;
+    /**
+     * Sender: take one permit to post a chunk, parking until the receiver grants
+     * one if none are left. Returns `false` if the stream was cancelled/disposed
+     * while parked (the pump should stop). With the default `Infinity` credits
+     * this never blocks — eager behavior, unchanged.
+     */
+    acquireCredit(streamId: number): Promise<boolean>;
+    /** Receiver granted `n` more permits — replenish and wake a parked pump. */
+    grantCredit(streamId: number, n?: number): void;
+    complete(streamId: number): void;
+    /** Receiver-side cancel arrived — stop the source pump if still running. */
+    cancel(streamId: number): void;
+    disposeAll(): void;
+}
+/**
+ * Receiver-side state for an inbound stream channel. Holds open `ReadableStream`
+ * controllers keyed by streamId and a small per-streamId pending-events queue
+ * for chunks that arrive before the consumer's `start()` registers the
+ * controller.
+ *
+ * Wiring code (each channel's `onmessage` dispatcher) routes channel-specific
+ * `*-chunk` / `*-end` / `*-error` messages into {@link push} / {@link end} /
+ * {@link error}. The `onCancel` callback is invoked when the consumer cancels
+ * the reconstructed stream, so the wiring code can post the channel-specific
+ * `*-cancel` message back to the sender.
+ */
+export interface StreamReceiverOptions {
+    /**
+     * Enable cross-thread backpressure. When set, the reconstructed
+     * `ReadableStream` uses this as its highWaterMark (chunk count) and the
+     * receiver grants the sender a credit (via {@link StreamReceiverOptions.onCredit})
+     * as it pulls — bounding the number of in-flight chunks instead of letting a
+     * fast producer race ahead and grow memory unbounded. Omit for eager
+     * (unbounded) behavior — the default.
+     */
+    window?: number;
+    /** Post the channel-specific `*-stream-ack` message granting one credit. Only
+     *  consulted when `window` is set. */
+    onCredit?: (streamId: number) => void;
+}
+export declare class StreamReceiver {
+    private _controllers;
+    private _pending;
+    private _cancelled;
+    /** Streams reconstructed via `open()` that haven't reached a terminal event
+     *  (end/error/cancel) yet. Reload drain consults `activeCount()` so a response
+     *  the client is still downloading (SSE, large proxy) isn't cut off mid-body. */
+    private _open;
+    private _onCancel;
+    private _window?;
+    private _onCredit?;
+    /**
+     * Cancels a reconstructed stream that was dropped (garbage-collected) before
+     * reaching a terminal event — e.g. a handler that never read a request body, or
+     * a caller that ignored a binding-fetch response body. Without this the sender's
+     * pump parks in `acquireCredit` forever (holding the locked source reader) until
+     * the generation is disposed. GC only collects truly-unreferenced streams, so a
+     * body still held by `waitUntil` is never wrongly cancelled.
+     */
+    private _finalizer;
+    constructor(onCancel: (streamId: number) => void, options?: StreamReceiverOptions);
+    /** Number of reconstructed streams not yet terminated. */
+    activeCount(): number;
+    open(streamId: number): ReadableStream<Uint8Array>;
+    /**
+     * Receiver-side cancel for an inbound stream that never reached a consumer
+     * (e.g. dispatcher errored before `open()` registered the controller, or the
+     * request was torn down post-open). Drops any buffered events, marks the id
+     * stale so late chunks are ignored, and signals the sender via `onCancel`.
+     */
+    cancel(streamId: number): void;
+    push(streamId: number, chunk: Uint8Array): void;
+    end(streamId: number): void;
+    error(streamId: number, err: Error): void;
+    disposeAll(err: Error): void;
+    private _onEvent;
+    private _apply;
+}
+/**
+ * Channel-specific envelope builders. Each callsite supplies its own message
+ * shapes (e.g. `{ type: 'stream-chunk', id, chunk }` vs `{ type:
+ * 'do-stream-chunk', streamId, chunk }`); the pump loop itself is identical.
+ */
+export interface PumpEnvelopes<TChunk, TEnd, TError> {
+    chunk: (streamId: number, chunk: Uint8Array) => TChunk;
+    end: (streamId: number) => TEnd;
+    error: (streamId: number, error: SerializedError) => TError;
+}
+/**
+ * Read a body to completion and post channel-specific envelopes for each
+ * chunk + the terminator. The reader is registered with `registry` so an
+ * inbound cancel can stop the source; `complete()` runs on every exit path.
+ *
+ * `isAlive` is optional — worker-side callers omit it (worker termination
+ * kills the loop). Main-side callers pass a closure over their disposal flag
+ * so a posted message after teardown is dropped at the source (matches the
+ * pre-refactor main-side pumps).
+ */
+export declare function pumpStream<TChunk, TEnd, TError>(streamId: number, body: ReadableStream<Uint8Array>, registry: OutboundStreamRegistry, post: (msg: TChunk | TEnd | TError) => void, envelopes: PumpEnvelopes<TChunk, TEnd, TError>, isAlive?: () => boolean, 
+/** When set, post at most `window` chunks ahead of the receiver's credits
+ *  (cross-thread backpressure). Requires the receiver's `StreamReceiver` to be
+ *  constructed with a matching `window` + `onCredit`. Omit for eager. */
+window?: number, 
+/** Called once the pump exits for any reason (end / error / cancel / teardown).
+ *  Lets callers tie per-stream resource cleanup to the body's completion. */
+onComplete?: () => void): void;

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

@@ -0,0 +1,42 @@
+/**
+ * Stateless-binding env builder for the main worker-thread runtime.
+ *
+ * Builds the bindings whose state lives on disk (.lopata SQLite/files) —
+ * the same physical files the main thread uses. WAL mode + busy_timeout
+ * make multiple `bun:sqlite` handles to the same file safe.
+ */
+import { Database } from 'bun:sqlite';
+import { SqliteWorkflowBinding } from '../bindings/workflow';
+import type { WranglerConfig } from '../config';
+import type { WorkerMessage } from './protocol';
+import type { RpcClient } from './rpc-client';
+import type { WsGuestBridge } from './ws-bridge-shared';
+export interface ThreadEnvOptions {
+    config: WranglerConfig;
+    /** Per-worker dir for `.dev.vars`/`.env`/assets resolution only. */
+    baseDir: string;
+    /** Shared `.lopata` data dir (main's `getDataDir()`) — the SQLite/r2/d1 files
+     *  main and the DO workers use. Distinct from `baseDir` in multi-worker mode. */
+    dataDir: string;
+    rpc: RpcClient;
+    /** Guest-side bridge for WebSockets returned by env-binding fetches. */
+    envWsBridge: WsGuestBridge<WorkerMessage>;
+    browserConfig?: {
+        wsEndpoint?: string;
+        executablePath?: string;
+        headless?: boolean;
+    };
+}
+export interface ThreadEnvBuilt {
+    env: Record<string, unknown>;
+    /** Thread-local DB handle — shared with the workflow + queue consumer wiring
+     *  the caller does after the user module loads. */
+    db: Database;
+    /** Workflows the caller still needs to wire after the user module loads. */
+    workflows: {
+        bindingName: string;
+        className: string;
+        binding: SqliteWorkflowBinding;
+    }[];
+}
+export declare function buildThreadEnv({ config, baseDir, dataDir, rpc, envWsBridge, browserConfig }: ThreadEnvOptions): ThreadEnvBuilt;

package/dist/types/worker-thread/wire-handlers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Workflow + queue wiring that runs after the user module loads in the worker
+ * thread. Kept out of `thread-env.ts` so the env builder doesn't need to
+ * receive the user module — buildThreadEnv runs before `import(modulePath)`.
+ */
+import type { Database } from 'bun:sqlite';
+import { QueueConsumer } from '../bindings/queue';
+import type { WranglerConfig } from '../config';
+import type { ThreadEnvBuilt } from './thread-env';
+export declare function wireWorkflows(built: ThreadEnvBuilt, workerModule: Record<string, unknown>): void;
+/**
+ * Spawn queue consumers in the worker thread. Shared SQLite means the consumer
+ * can poll, manage leases, and apply ack/retry decisions locally — exactly
+ * like the in-process flow — without any cross-thread RPC.
+ */
+export declare function startThreadQueueConsumers(config: WranglerConfig, db: Database, env: Record<string, unknown>, workerModule: Record<string, unknown>, workerName?: string, trackBatch?: (p: Promise<unknown>) => void): QueueConsumer[];

package/dist/types/worker-thread/ws-bridge-shared.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Cross-thread WebSocket bridge — shared primitive.
+ *
+ * Used by both worker channels (main ↔ user-worker, main ↔ DO-instance worker)
+ * to ferry events for a CFWebSocket whose two halves live on opposite threads.
+ *
+ * Direction & terminology:
+ *  - *Guest* — the side that owns the user-facing peer (worker thread).
+ *    The user code created a `WebSocketPair` locally and shipped `pair[0]`
+ *    in a `Response{webSocket}`. The guest keeps `pair[1]` and forwards
+ *    everything the user does on it through to the host.
+ *  - *Host* — the side that hands the upgraded `CFWebSocket` to `Bun.serve`
+ *    (main thread). It owns a synthetic CFWebSocket whose `_peer` posts every
+ *    inbound event (from the real client) back to the guest.
+ *
+ * Each bridged socket is identified by an opaque `wsId` generated on the
+ * guest side. The host-side `register()` call is the message that ferries
+ * the id over and creates the local half. A late `deliverRemote*` for a
+ * wsId that hasn't been `register()`ed yet is buffered until it appears —
+ * see `_pendingEvents` for why.
+ *
+ * Channel-specific envelopes (`ws-worker-send` vs `fetch-ws-outgoing`, etc.)
+ * are encoded by the `WsBridgeEnvelopes` callbacks each consumer supplies.
+ */
+import { CFWebSocket } from '../bindings/websocket-pair';
+/**
+ * Channel-specific message builders. Each callback returns the exact envelope
+ * the consumer's transport expects; the bridge just calls `post(envelope)`.
+ */
+export interface WsHostEnvelopes<O> {
+    /** Inbound from the real client → guest's user peer. */
+    clientMessage(wsId: string, data: string | ArrayBuffer): O;
+    clientClose(wsId: string, code: number, reason: string, wasClean: boolean): O;
+}
+export interface WsGuestEnvelopes<O> {
+    /** User-facing peer sent bytes → forward to real client via host. */
+    remoteMessage(wsId: string, data: string | ArrayBuffer): O;
+    remoteClose(wsId: string, code: number, reason: string, wasClean: boolean): O;
+}
+/**
+ * Host side: owns the `CFWebSocket` that gets handed to `Bun.serve.upgrade`
+ * and bridges events to/from the guest worker.
+ */
+export declare class WsHostBridge<O> {
+    /** wsId → cfSocket (the side handed to `Bun.serve.upgrade`). */
+    private _sockets;
+    /**
+     * Events from the guest that arrived before the matching `register()` /
+     * `adoptExisting()` was called. The guest's `accept()` flushes queued events
+     * synchronously and posts them; those posts race ahead of the binding-fetch /
+     * fetch result that triggers host-side registration. Without buffering, the
+     * first message would be lost.
+     */
+    private _pendingEvents;
+    /**
+     * Subset of `_sockets` that was adopted with `bridgeEvents: true` — outbound
+     * `deliverRemoteMessage` must `cfSocket.send(data)` (dispatch on peer) for
+     * these, instead of `dispatchOrQueue` (dispatch on the adopted socket
+     * itself, which is the right behavior only for the `Bun.serve` passthrough).
+     */
+    private _bridgedAdoptions;
+    /**
+     * wsIds that were previously registered/adopted and have since closed.
+     * Used to drop late `deliverRemote*` calls cleanly instead of stashing
+     * them in `_pendingEvents` (where they'd be unreachable — wsIds are
+     * unique per upgrade, so no future `register()` will ever match).
+     */
+    private _forgotten;
+    private _post;
+    private _envelopes;
+    constructor(post: (msg: O) => void, envelopes: WsHostEnvelopes<O>);
+    private _forget;
+    /**
+     * Build a host-side `CFWebSocket` paired with a bridge peer that posts every
+     * inbound event back to the guest. Drains any pending events queued before
+     * this call.
+     */
+    register(wsId: string): CFWebSocket;
+    /**
+     * Adopt an already-real `CFWebSocket` (typically the client peer returned
+     * from a DO/service binding inside a nested binding fetch). The peer is
+     * already wired to its server counterpart, so we just need to keep it
+     * addressable by id when the guest echoes the response back up.
+     *
+     * For the *passthrough* use (user-worker channel): the guest never reads or
+     * writes through this socket — main eventually hands the same `cfSocket`
+     * to `Bun.serve.upgrade()`, which owns both directions.
+     *
+     * For the *guest-driven* use (DO-worker env-binding channel): pass
+     * `bridgeEvents: true` so we accept the socket here, forward every inbound
+     * message/close to the guest as `clientMessage` / `clientClose` envelopes,
+     * and `deliverRemoteMessage` routes outbound bytes via `cfSocket.send`
+     * (which dispatches on its real peer) instead of dispatching on the
+     * adopted socket itself.
+     */
+    adoptExisting(ws: CFWebSocket, options?: {
+        bridgeEvents?: boolean;
+    }): string;
+    private _wireBridgedAdoption;
+    /** Look up a previously-registered or adopted CFWebSocket. */
+    getSocket(wsId: string): CFWebSocket | undefined;
+    /** Guest reports its user-facing peer emitted a message → fire it on the host socket. */
+    deliverRemoteMessage(wsId: string, data: string | ArrayBuffer): void;
+    /** Guest reports its user-facing peer closed → fire close on the host socket. */
+    deliverRemoteClose(wsId: string, code: number, reason: string, wasClean: boolean): void;
+    private _bufferPending;
+    /**
+     * Notify any active real clients that this generation is going away, then
+     * drop them. Mirrors the `1012 Service Restart` close code WebSockets use
+     * for planned restarts. Also drops any stranded pending events for ids that
+     * never reached `register()` (e.g. binding-fetch errored mid-flight).
+     */
+    disposeAll(): void;
+}
+/**
+ * Guest side: hooks the CFWebSocket that's about to ship in a Response and
+ * forwards events between the user-facing peer and the host.
+ */
+export declare class WsGuestBridge<O> {
+    private _sockets;
+    /**
+     * Client events that arrived before the matching `createBridgedSocket()` was
+     * called. On the env-binding channel main adopts the upstream WS with
+     * `bridgeEvents: true`, whose `accept()` flushes already-queued client events
+     * synchronously — those posts race ahead of the `rpc-fetch-result` that
+     * triggers `createBridgedSocket` here. Without buffering, the first inbound
+     * message (or an early close) would be lost. Mirrors `WsHostBridge`.
+     */
+    private _pendingEvents;
+    /** wsIds already created+closed; drop late client events instead of re-buffering. */
+    private _forgotten;
+    private _post;
+    private _envelopes;
+    constructor(post: (msg: O) => void, envelopes: WsGuestEnvelopes<O>);
+    private _forget;
+    private _bufferPending;
+    /**
+     * Reverse of `register`: build a fresh `CFWebSocket` for a wsId allocated on
+     * the host (e.g. main adopted an upstream WS returned from an env-binding
+     * fetch). The returned socket is what user code interacts with — calling
+     * `accept()` / `send()` / `addEventListener('message')` here drives the
+     * remote peer through the bridge.
+     */
+    createBridgedSocket(wsId: string): CFWebSocket;
+    /**
+     * Hook up a `CFWebSocket` that's about to ship in a Response. Listeners must
+     * be attached BEFORE `accept()` so the synchronous flush of any queued events
+     * (e.g. the user already called `server.send()` before returning the response)
+     * reaches the bridge instead of being lost.
+     *
+     * If the shipped peer was pre-accepted by user code (e.g. `client.accept()`
+     * before returning the Response), any events dispatched between that
+     * pre-accept and this `register()` call were emitted with no listeners
+     * attached — they're already gone. We still attach listeners so anything
+     * *after* this point flows correctly, and emit a console.warn so the user
+     * knows to drop the early `accept()`.
+     */
+    register(shipped: CFWebSocket): string;
+    /** Host delivered a message from the real client → fire it on the user peer. */
+    deliverClientMessage(wsId: string, data: string | ArrayBuffer): void;
+    /** Host delivered a close from the real client → fire close on the user peer. */
+    deliverClientClose(wsId: string, code: number, reason: string, wasClean: boolean): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "lopata",
-	"version": "0.18.4",
+	"version": "0.19.0",
 	"type": "module",
 	"license": "MIT",
 	"repository": {

package/src/api/handlers/containers.ts

@@ -1,5 +1,6 @@
 import { $ } from 'bun'
 import type { ContainerBase } from '../../bindings/container'
+import { unregisterContainer } from '../../bindings/container-cleanup'
 import { DockerManager } from '../../bindings/container-docker'
 import { getDatabase } from '../../db'
 import type { ContainerDetail, ContainerInstance, ContainerSummary, HandlerContext, OkResponse } from '../types'
@@ -186,7 +187,7 @@ export const handlers = {
 	},
 
 	async 'containers.destroy'({ className, id }: { className: string; id: string }, ctx: HandlerContext): Promise<OkResponse> {
-		const docker = new DockerManager()
+		const docker = new DockerManager({ onRemove: unregisterContainer })
 		const containerName = `lopata-${className}-${id.slice(0, 12)}`
 		await docker.remove(containerName)
 		return { ok: true }