@venizia/ignis-worker 0.2.0-10

package/dist/cjs/transport/worker.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerBffTransport = void 0;
+const core_1 = require("@venizia/ignis-helpers/core");
+const core_2 = require("@venizia/ignis-helpers/core");
+const encode_1 = require("../envelope/encode");
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** How long a still-serving worker gets to answer after it reports an error - see `handleWorkerError`. */
+const WORKER_ERROR_GRACE_MS = 250;
+const isErrorEnvelope = (data) => {
+    return 'error' in data;
+};
+/**
+ * UI-side half of the BFF: posts an encoded request to a real `Worker` and resolves the matching
+ * response by `id` - the far side of `WorkerApplication.listen()`.
+ *
+ * The three worker listeners are attached ONCE, in the constructor, and every request is tracked in
+ * `pendingRequests` instead. Registering them per request looks equivalent and is not: they are
+ * scoped to the shared `Worker`, so a single `messageerror` - which means exactly one message
+ * failed to deserialise - would fire every in-flight request's handler, rejecting nine healthy
+ * requests that are about to be answered normally.
+ */
+class WorkerBffTransport extends core_1.BaseHelper {
+    constructor(opts) {
+        super({ scope: WorkerBffTransport.name });
+        this.requestIdGenerator = new core_2.RequestIdGenerator({
+            scope: WorkerBffTransport.name,
+        });
+        this.pendingRequests = new Map();
+        /** Set by `close()`, so a later `fetch()` is refused instead of reaching a worker nothing listens to. */
+        this.isClosed = false;
+        /** Outstanding `handleWorkerError` grace timers, cleared by `close()` so none outlives the transport. */
+        this.graceTimers = new Set();
+        /** Removes a pending request from the map and releases its timer and abort listener, so nothing can settle it twice. */
+        this.takePending = (opts) => {
+            const pending = this.pendingRequests.get(opts.id);
+            if (!pending) {
+                return undefined;
+            }
+            this.pendingRequests.delete(opts.id);
+            pending.release();
+            return pending;
+        };
+        this.handleMessage = (event) => {
+            // `event.data` is untyped (`any`) until narrowed below - a worker posts to this page for its own
+            // reasons too (a dev-server ping, a library handshake), and none of those carry an `id` this
+            // transport is waiting on.
+            const data = event.data;
+            if (!data?.id) {
+                return;
+            }
+            const pending = this.takePending({ id: data.id });
+            if (!pending) {
+                return;
+            }
+            if (isErrorEnvelope(data)) {
+                pending.reject(encode_1.BffEnvelope.decodeError({ envelope: data }));
+                return;
+            }
+            // Settled inside its own try: `decodeResponse` throws a `RangeError` for a status outside
+            // 200-599 and a `TypeError` on a malformed header tuple, and by this point the timer and the
+            // listeners are already gone - a throw that escaped here would leave the promise with nothing
+            // left to settle it, ever.
+            try {
+                pending.resolve(encode_1.BffEnvelope.decodeResponse({ envelope: data }));
+            }
+            catch (error) {
+                pending.reject((0, core_1.getError)({
+                    message: `[WorkerBffTransport] Failed to decode the response envelope | id: ${data.id} | error: ${error}`,
+                }));
+            }
+        };
+        /**
+         * An `error` event does NOT mean the worker is dead.
+         *
+         * Measured in Chromium: a synchronous uncaught throw anywhere in the worker - a third-party timer,
+         * say - fires this event while the worker keeps serving, and the genuine responses to the
+         * in-flight requests arrive a moment later. Rejecting immediately reported a committed POST as
+         * failed and then dropped its real 200 on the floor, because nothing was left waiting for it.
+         *
+         * So the event is logged at once and the requests are given a grace window. Whatever the worker
+         * still answers inside it settles normally; whatever is left after it really is lost, and is
+         * rejected with the diagnostics rather than left to run out its own timeout.
+         */
+        this.handleWorkerError = (event) => {
+            // `String(event)` is always `[object ErrorEvent]` - it says nothing. Read the fields a browser
+            // actually populates, so the log names the file and line that failed.
+            const detail = this.describeErrorEvent(event);
+            this.logger
+                .for('handleWorkerError')
+                .error('Worker reported an error | pending: %s | detail: %s', this.pendingRequests.size, detail);
+            const affected = [...this.pendingRequests.keys()];
+            // Held so `close()` can clear it. A grace timer that outlives the transport keeps the process
+            // (or a test runner) awake and fires against a map nobody is watching any more.
+            const timer = setTimeout(() => {
+                this.graceTimers.delete(timer);
+                for (const id of affected) {
+                    // `takePending` answers undefined for anything the worker managed to settle in the window.
+                    this.takePending({ id })?.reject((0, core_1.getError)({
+                        message: `[WorkerBffTransport] Worker failed while awaiting a response | id: ${id} | detail: ${detail}`,
+                    }));
+                }
+            }, WORKER_ERROR_GRACE_MS);
+            this.graceTimers.add(timer);
+        };
+        /**
+         * `messageerror` means exactly ONE posted message failed to deserialise, and the event carries
+         * nothing that says which. With a single request in flight that is unambiguous, so it settles
+         * now; with several, the lost answer belongs to one of them and rejecting the rest would be a
+         * lie - each then ends on its own timeout, under its own id.
+         */
+        this.handleMessageError = (event) => {
+            if (this.pendingRequests.size !== 1) {
+                this.logger
+                    .for(this.handleMessageError.name)
+                    .warn('A worker message could not be deserialised and no single request owns it | inFlight: %d | event: %s', this.pendingRequests.size, String(event));
+                return;
+            }
+            const [id] = [...this.pendingRequests.keys()];
+            this.takePending({ id: id })?.reject((0, core_1.getError)({
+                message: `[WorkerBffTransport] The worker's response could not be deserialised | id: ${id} | event: ${String(event)}`,
+            }));
+        };
+        this.worker = opts.worker;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.worker.addEventListener('message', this.handleMessage);
+        this.worker.addEventListener('error', this.handleWorkerError);
+        this.worker.addEventListener('messageerror', this.handleMessageError);
+    }
+    /** `ErrorEvent` carries the useful fields; a plain `Event` does not, so both shapes are handled. */
+    describeErrorEvent(event) {
+        const candidate = event;
+        if (!candidate.message) {
+            return event.type;
+        }
+        return `${candidate.message} (${candidate.filename ?? 'unknown'}:${candidate.lineno ?? 0}:${candidate.colno ?? 0})`;
+    }
+    async fetch(opts) {
+        const { request } = opts;
+        const { signal } = request;
+        // Refused, not queued. `close()` detaches the message listener, so a request posted after it
+        // still reached the worker - which EXECUTED it, writes included - while the answer had nowhere
+        // to land and the caller waited out the full timeout.
+        if (this.isClosed) {
+            throw (0, core_1.getError)({
+                message: '[WorkerBffTransport] The transport is closed | open a new one to make requests',
+            });
+        }
+        if (signal?.aborted) {
+            throw this.toAbortError({ signal });
+        }
+        const id = this.requestIdGenerator.nextId();
+        // The URL is overridden rather than the request rebuilt: rebuilding reads the body once here
+        // and once inside `encodeRequest`, and it silently drops `signal` on the way.
+        const requestEnvelope = await encode_1.BffEnvelope.encodeRequest({
+            request,
+            id,
+            url: encode_1.BffEnvelope.toSyntheticUrl({ url: request.url }),
+        });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.takePending({ id })?.reject((0, core_1.getError)({
+                    message: `[WorkerBffTransport] Timed out waiting for a response | id: ${id} | timeoutMs: ${this.timeoutMs}`,
+                }));
+            }, this.timeoutMs);
+            const handleAbort = () => {
+                this.takePending({ id })?.reject(this.toAbortError({ signal }));
+            };
+            signal?.addEventListener('abort', handleAbort);
+            this.pendingRequests.set(id, {
+                resolve,
+                reject,
+                release: () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener('abort', handleAbort);
+                },
+            });
+            // Buffering the body took an await, and `addEventListener('abort')` never fires on a signal
+            // that aborted before it was attached - without this re-read that window loses the abort and
+            // the caller waits out the whole timeout.
+            if (signal?.aborted) {
+                handleAbort();
+                return;
+            }
+            // `close()` can land during that same await. The entry guard above is then stale, and posting
+            // reaches a worker that EXECUTES the request - writes included - while the answer has nowhere
+            // to land, because `close()` already detached the listener.
+            if (this.isClosed) {
+                this.takePending({ id })?.reject((0, core_1.getError)({
+                    message: `[WorkerBffTransport] The transport closed while the request was being encoded | id: ${id}`,
+                }));
+                return;
+            }
+            this.worker.postMessage(requestEnvelope, requestEnvelope.body ? [requestEnvelope.body] : []);
+        });
+    }
+    /** `signal.reason` first, the way `globalThis.fetch` rejects, so `controller.abort(myReason)` still reaches the caller. */
+    toAbortError(opts) {
+        return (opts.signal?.reason ??
+            (0, core_1.getError)({ message: '[WorkerBffTransport] The request was aborted by its caller' }));
+    }
+    /**
+     * Detaches the three worker listeners and fails whatever is still in flight. The worker itself is
+     * left alone - this transport did not create it, and a page may hand the same one to another.
+     */
+    close() {
+        this.isClosed = true;
+        for (const timer of this.graceTimers) {
+            clearTimeout(timer);
+        }
+        this.graceTimers.clear();
+        this.worker.removeEventListener('message', this.handleMessage);
+        this.worker.removeEventListener('error', this.handleWorkerError);
+        this.worker.removeEventListener('messageerror', this.handleMessageError);
+        for (const id of [...this.pendingRequests.keys()]) {
+            this.takePending({ id })?.reject((0, core_1.getError)({
+                message: `[WorkerBffTransport] The transport was closed while awaiting a response | id: ${id}`,
+            }));
+        }
+    }
+}
+exports.WorkerBffTransport = WorkerBffTransport;
+//# sourceMappingURL=worker.js.map

package/dist/cjs/transport/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../src/transport/worker.ts"],"names":[],"mappings":"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"}

package/dist/esm/applications/index.d.ts

@@ -0,0 +1,2 @@
+export * from './worker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/applications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/applications/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/esm/applications/index.js

@@ -0,0 +1,2 @@
+export * from './worker.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/applications/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/applications/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/esm/applications/worker.d.ts

@@ -0,0 +1,67 @@
+import { RestApplication } from '@venizia/ignis-kernel';
+import type { Env, Schema } from 'hono';
+/**
+ * Structural shape of the two globals `listen()` can attach to. Never `DedicatedWorkerGlobalScope`:
+ * naming it emits it into the published `.d.ts` and forces every consumer to compile with
+ * `lib.webworker`. `start` is optional because a `MessagePort`s queue starts disabled and only
+ * `start()` enables it, while a worker global scope has no such method at all.
+ */
+export interface IWorkerMessageScope {
+    postMessage(message: unknown, transfer?: Array<ArrayBuffer | MessagePort>): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener?(type: 'message', listener: (event: MessageEvent) => void): void;
+    start?(): void;
+}
+/**
+ * Runs an IGNIS application inside a browser Web Worker: `listen()` replaces what
+ * `ServerApplication.start()` does with a socket, attaching `onmessage` instead. Gets REST
+ * controller registration by inheritance - `RestApplication.registerControllers()` - the whole
+ * reason the DI helpers and `RestComponent` sit in the kernel.
+ */
+export declare abstract class WorkerApplication<AppEnv extends Env = Env, AppSchema extends Schema = {}, BasePath extends string = '/'> extends RestApplication<AppEnv, AppSchema, BasePath> {
+    /** Resolves once the router tree is mounted - what an envelope arriving during boot waits on. */
+    private servingPromise?;
+    /** The whole `listen()` call, kept so a second one is a no-op instead of a second listener. */
+    private listenPromise?;
+    private detachFromScope?;
+    private isStopped;
+    /**
+     * Every failure here is posted back as an `IBffErrorEnvelope`, the failed `postMessage` included:
+     * an exception nobody posts leaves the UI waiting out the transport timeout.
+     */
+    private handleMessage;
+    /** No transfer list: an error envelope carries no `ArrayBuffer` body, and this is already the fallback path - nothing left to hand off if this post fails too. */
+    private postErrorEnvelope;
+    /** Everything `ServerApplication.start()` does short of binding a socket. Once this resolves the application answers requests. */
+    private startServing;
+    /**
+     * Holds an envelope until the application is serving. A dedicated worker's queue is enabled when
+     * its module script is evaluated, so anything posted during boot - PGlite takes ~350ms - reaches
+     * this listener and would otherwise be dropped. One shared promise also hands them on in arrival
+     * order.
+     */
+    private dispatchMessage;
+    private attachTo;
+    /**
+     * `ServerApplication.start()` minus the socket. `opts.scope` defaults to `globalThis`, never a
+     * bare `self`, which would tie the published types to `lib.webworker`. Idempotent: without the
+     * guard one envelope runs its handler once per call - a POST inserting two rows - and Vite HMR
+     * re-evaluating the worker module is the everyday trigger. A boot failure keeps the listener
+     * attached so every request hears the failure instead of waiting out the transport timeout.
+     */
+    listen(opts?: {
+        scope?: MessagePort | IWorkerMessageScope;
+    }): Promise<void>;
+    /**
+     * The counterpart to `listen()`, and to `ServerApplication.stop()`: without it nothing drains the
+     * post-stop hooks, so a datasource's `end()` never runs and the OPFS exclusive lock a PGlite
+     * holds is never released - the next Worker then fails with `NoModificationAllowedError` until a
+     * full page reload. The Vite recipe is `import.meta.hot?.dispose(() => application.stop())`.
+     *
+     * Detaches BEFORE draining, unlike the server: here the listener IS the socket, and a request
+     * admitted while the hooks are closing a datasource has nothing left to run against. A stopped
+     * application is not restartable - build a new one.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=worker.d.ts.map

package/dist/esm/applications/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/applications/worker.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAIxC;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC;IACjF,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACjF,mBAAmB,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACrF,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,8BAAsB,iBAAiB,CACrC,MAAM,SAAS,GAAG,GAAG,GAAG,EACxB,SAAS,SAAS,MAAM,GAAG,EAAE,EAC7B,QAAQ,SAAS,MAAM,GAAG,GAAG,CAC7B,SAAQ,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC;IACpD,iGAAiG;IACjG,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,+FAA+F;IAC/F,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;YACW,aAAa;IAoC3B,kKAAkK;IAClK,OAAO,CAAC,iBAAiB;IAgBzB,kIAAkI;YACpH,YAAY;IAW1B;;;;;OAKG;YACW,eAAe;IAqC7B,OAAO,CAAC,QAAQ;IAsChB;;;;;;OAMG;IACG,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,GAAG,mBAAmB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBjF;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAU5B"}

package/dist/esm/applications/worker.js

@@ -0,0 +1,171 @@
+import { getError } from '@venizia/ignis-helpers/core';
+import { HTTP } from '@venizia/ignis-helpers/common';
+import { RestApplication } from '@venizia/ignis-kernel';
+import { BffEnvelope } from '../envelope/encode.js';
+/**
+ * Runs an IGNIS application inside a browser Web Worker: `listen()` replaces what
+ * `ServerApplication.start()` does with a socket, attaching `onmessage` instead. Gets REST
+ * controller registration by inheritance - `RestApplication.registerControllers()` - the whole
+ * reason the DI helpers and `RestComponent` sit in the kernel.
+ */
+export class WorkerApplication extends RestApplication {
+    constructor() {
+        super(...arguments);
+        this.isStopped = false;
+    }
+    /**
+     * Every failure here is posted back as an `IBffErrorEnvelope`, the failed `postMessage` included:
+     * an exception nobody posts leaves the UI waiting out the transport timeout.
+     */
+    async handleMessage(opts) {
+        const { scope, envelope } = opts;
+        const logger = this.logger.for(this.handleMessage.name);
+        let responseEnvelope;
+        let failure;
+        try {
+            const request = BffEnvelope.decodeRequest({ envelope });
+            const response = await this.getServer().fetch(request);
+            responseEnvelope = await BffEnvelope.encodeResponse({ response, id: envelope.id });
+        }
+        catch (error) {
+            logger.error('Failed to handle worker message | id: %s | error: %s', envelope.id, error);
+            failure = error;
+        }
+        if (responseEnvelope) {
+            try {
+                scope.postMessage(responseEnvelope, responseEnvelope.body ? [responseEnvelope.body] : []);
+                return;
+            }
+            catch (postError) {
+                logger.error('Failed to post response back to scope, falling back to an error envelope | id: %s | error: %s', envelope.id, postError);
+                failure = postError;
+            }
+        }
+        this.postErrorEnvelope({ scope, id: envelope.id, error: failure });
+    }
+    /** No transfer list: an error envelope carries no `ArrayBuffer` body, and this is already the fallback path - nothing left to hand off if this post fails too. */
+    postErrorEnvelope(opts) {
+        const { scope, id, error } = opts;
+        try {
+            scope.postMessage(BffEnvelope.encodeError({ id, error }));
+        }
+        catch (postError) {
+            this.logger
+                .for(this.postErrorEnvelope.name)
+                .error('Failed to post error envelope back to scope | id: %s | error: %s', id, postError);
+        }
+    }
+    /** Everything `ServerApplication.start()` does short of binding a socket. Once this resolves the application answers requests. */
+    async startServing() {
+        // The stack itself is `RestApplication.registerDefaultMiddlewares()` - a BFF must answer with
+        // the framework's envelope exactly as the server does, so it adds nothing and overrides nothing.
+        await this.registerDefaultMiddlewares();
+        await this.initialize();
+        await this.setupMiddlewares();
+        this.getServer().route(this.configs.path.base, this.rootRouter);
+    }
+    /**
+     * Holds an envelope until the application is serving. A dedicated worker's queue is enabled when
+     * its module script is evaluated, so anything posted during boot - PGlite takes ~350ms - reaches
+     * this listener and would otherwise be dropped. One shared promise also hands them on in arrival
+     * order.
+     */
+    async dispatchMessage(opts) {
+        const { scope, envelope } = opts;
+        const logger = this.logger.for(this.dispatchMessage.name);
+        try {
+            await this.servingPromise;
+        }
+        catch (error) {
+            logger.error('The application failed to start, answering with an error envelope | id: %s | error: %s', envelope.id, error);
+            this.postErrorEnvelope({ scope, id: envelope.id, error });
+            return;
+        }
+        // Answered, not dropped: a request admitted before `stop()` and still waiting on the boot has
+        // a caller holding a promise, and silence there is the timeout this whole path exists to avoid.
+        if (this.isStopped) {
+            logger.warn('Refusing a request that arrived after stop() | id: %s', envelope.id);
+            this.postErrorEnvelope({
+                scope,
+                id: envelope.id,
+                error: getError({
+                    statusCode: HTTP.ResultCodes.RS_5.ServiceUnavailable,
+                    message: `[WorkerApplication] The application was stopped before this request could run | id: ${envelope.id}`,
+                }),
+            });
+            return;
+        }
+        await this.handleMessage({ scope, envelope });
+    }
+    attachTo(opts) {
+        const { scope } = opts;
+        const logger = this.logger.for(this.attachTo.name);
+        // Typed as the broader `Event`, not `MessageEvent`: Node's ambient `worker_threads.MessagePort`
+        // (the fallback this package's DOM-less tsconfig resolves `MessagePort` to) declares
+        // `addEventListener` over `Event | MessageEvent`, and a handler narrower than that is not
+        // assignable to it.
+        const listener = (event) => {
+            const envelope = event.data;
+            // A worker scope receives every `postMessage` sent to it, not only ours - a dev-server ping,
+            // a devtools/extension probe, a library's own init handshake. None of those carry an `id`;
+            // silently dropping them (rather than dereferencing `envelope.id` inside `handleMessage`'s
+            // own catch block) is what keeps a foreign message from throwing a bare `TypeError` that
+            // would otherwise escape this listener entirely, unlogged and unposted.
+            if (!envelope?.id) {
+                logger.debug('Ignoring worker message with no request id | data: %j', envelope);
+                return;
+            }
+            // `dispatchMessage` never rejects - every failure inside it, including a failed post, is
+            // caught and handled internally. This `.catch` only guards the sliver of code before its own
+            // try block ever runs.
+            this.dispatchMessage({ scope, envelope }).catch(error => {
+                logger.error('Unexpected failure handling worker message | error: %s', error);
+            });
+        };
+        scope.addEventListener('message', listener);
+        scope.start?.();
+        this.detachFromScope = () => {
+            scope.removeEventListener?.('message', listener);
+        };
+    }
+    /**
+     * `ServerApplication.start()` minus the socket. `opts.scope` defaults to `globalThis`, never a
+     * bare `self`, which would tie the published types to `lib.webworker`. Idempotent: without the
+     * guard one envelope runs its handler once per call - a POST inserting two rows - and Vite HMR
+     * re-evaluating the worker module is the everyday trigger. A boot failure keeps the listener
+     * attached so every request hears the failure instead of waiting out the transport timeout.
+     */
+    async listen(opts) {
+        if (this.listenPromise) {
+            this.logger
+                .for(this.listen.name)
+                .warn('Already listening - ignoring this call | one scope, one listener');
+            return this.listenPromise;
+        }
+        // Everything down to the first `await` runs synchronously with the caller, which is what makes
+        // the listener observable to anything posted in the same turn.
+        const scope = opts?.scope ?? globalThis;
+        this.attachTo({ scope });
+        this.servingPromise = this.startServing();
+        this.listenPromise = this.servingPromise.then(() => this.executePostStartHooks());
+        return this.listenPromise;
+    }
+    /**
+     * The counterpart to `listen()`, and to `ServerApplication.stop()`: without it nothing drains the
+     * post-stop hooks, so a datasource's `end()` never runs and the OPFS exclusive lock a PGlite
+     * holds is never released - the next Worker then fails with `NoModificationAllowedError` until a
+     * full page reload. The Vite recipe is `import.meta.hot?.dispose(() => application.stop())`.
+     *
+     * Detaches BEFORE draining, unlike the server: here the listener IS the socket, and a request
+     * admitted while the hooks are closing a datasource has nothing left to run against. A stopped
+     * application is not restartable - build a new one.
+     */
+    async stop() {
+        this.isStopped = true;
+        this.detachFromScope?.();
+        this.detachFromScope = undefined;
+        await this.executePostStopHooks();
+        this.logger.for(this.stop.name).info('Worker application STOPPED');
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/esm/applications/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../src/applications/worker.ts"],"names":[],"mappings":"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"}

package/dist/esm/envelope/encode.d.ts

@@ -0,0 +1,61 @@
+import type { ApplicationError } from '@venizia/ignis-helpers/core';
+import type { IBffErrorEnvelope, IBffRequestEnvelope, IBffResponseEnvelope } from './types.js';
+/**
+ * Every request built inside the Worker uses this origin. Never `self.location.href`: a `blob:`
+ * worker origin is opaque and `new URL(path, blobUrl)` throws, and Hono's `getPath()` mis-parses
+ * `file://`. Hono never resolves the host - it string-scans from `indexOf(':') + 4`.
+ */
+export declare const BFF_SYNTHETIC_ORIGIN = "http://ignis.internal";
+/** Turns `Request`/`Response`/`Error` into plain structured-cloneable shapes and back - none of the three survives `postMessage` as itself. */
+export declare class BffEnvelope {
+    /**
+     * Statuses the Fetch spec forbids a body on - `new Response(body, { status })` throws if `body`
+     * is anything but `null` for one of these, even an empty `ArrayBuffer`.
+     */
+    private static readonly NULL_BODY_STATUSES;
+    /**
+     * Moves a URL onto the synthetic origin, keeping everything below it. A caller builds a request
+     * against the page's real origin (or a relative path resolved against it); `decodeRequest` on the
+     * far side always reconstructs on `BFF_SYNTHETIC_ORIGIN`.
+     */
+    static toSyntheticUrl(opts: {
+        url: string;
+    }): string;
+    /**
+     * `url` overrides the request's own, so the origin rewrite costs nothing: rebuilding the `Request`
+     * to change its URL would read the body a second time, and a 10 MB upload would hold 20 MB on the
+     * UI thread. Reading the body here disturbs the caller's request exactly as `globalThis.fetch`
+     * does with the one it is handed.
+     */
+    static encodeRequest(opts: {
+        request: Request;
+        id: string;
+        url?: string;
+    }): Promise<IBffRequestEnvelope>;
+    static decodeRequest(opts: {
+        envelope: IBffRequestEnvelope;
+    }): Request;
+    static encodeResponse(opts: {
+        response: Response;
+        id: string;
+    }): Promise<IBffResponseEnvelope>;
+    static decodeResponse(opts: {
+        envelope: IBffResponseEnvelope;
+    }): Response;
+    /**
+     * Builds the shape an error crosses `postMessage` as. An `ApplicationError` cannot cross as itself
+     * - a custom `Error` subclass loses its name, its own properties and its prototype through
+     * structured clone - so it crosses normalised and `decodeError` rebuilds it on the far side.
+     *
+     * A foreign error gets `500`, matching what the framework's error middleware gives an UNEXPECTED
+     * one on the server. Anything reaching here already escaped the whole HTTP layer.
+     */
+    static encodeError(opts: {
+        id: string;
+        error: unknown;
+    }): IBffErrorEnvelope;
+    static decodeError(opts: {
+        envelope: IBffErrorEnvelope;
+    }): ApplicationError;
+}
+//# sourceMappingURL=encode.d.ts.map

package/dist/esm/envelope/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../../src/envelope/encode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D,+IAA+I;AAC/I,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAA4B;IAEtE;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAKpD;;;;;OAKG;WACU,aAAa,CAAC,IAAI,EAAE;QAC/B,OAAO,EAAE,OAAO,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAahC,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,mBAAmB,CAAA;KAAE,GAAG,OAAO;WAUzD,cAAc,CAAC,IAAI,EAAE;QAChC,QAAQ,EAAE,QAAQ,CAAC;QACnB,EAAE,EAAE,MAAM,CAAC;KACZ,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAajC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,oBAAoB,CAAA;KAAE,GAAG,QAAQ;IAazE;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,iBAAiB;IAoB3E,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAA;KAAE,GAAG,gBAAgB;CAc5E"}