@venizia/ignis-worker 0.2.0-2 → 0.2.0-4

package/dist/cjs/transport/fetch-bridge.d.ts

@@ -0,0 +1,35 @@
+import type { IBffTransport } from './common/types';
+type TFetch = typeof globalThis.fetch;
+/** The carrier whose `fetch` is replaced - `globalThis` in a page, an object a test controls otherwise. */
+interface IFetchCarrier {
+    fetch: TFetch;
+}
+export interface IInstallBffFetchOptions {
+    /** Anything implementing the transport contract, so an in-process transport works in a test. */
+    transport: IBffTransport;
+    /**
+     * Path prefixes the BFF owns, matched against the request's PATHNAME. Everything else is passed
+     * to the original `fetch` untouched.
+     */
+    basePath: string | Array<string>;
+    /** Defaults to `globalThis`. */
+    carrier?: IFetchCarrier;
+}
+/**
+ * Routes the page's own `fetch` into a BFF transport for anything under `basePath`, and leaves every
+ * other call on the network untouched.
+ *
+ * This is the seam that lets an existing HTTP client talk to an in-browser IGNIS application without
+ * knowing one exists. A data provider, an SDK or a generated client reaches the network through the
+ * global `fetch` and usually accepts no custom fetcher, so answering that `fetch` is the only place
+ * an in-browser backend becomes a drop-in swap rather than a fork of the client.
+ *
+ * Install it BEFORE the application that will use it boots: a request issued while the original
+ * `fetch` is still in place leaves the page and 404s against whatever is serving it.
+ *
+ * @returns The uninstall function. It restores the previous `fetch` only if this bridge is still the
+ * installed one - if something patched `fetch` afterwards, restoring would silently discard that.
+ */
+export declare const installBffFetch: (opts: IInstallBffFetchOptions) => (() => void);
+export {};
+//# sourceMappingURL=fetch-bridge.d.ts.map

package/dist/cjs/transport/fetch-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-bridge.d.ts","sourceRoot":"","sources":["../../../src/transport/fetch-bridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAQpD,KAAK,MAAM,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAEtC,2GAA2G;AAC3G,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,SAAS,EAAE,aAAa,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACjC,gCAAgC;IAChC,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AA+CD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,uBAAuB,KAAG,CAAC,MAAM,IAAI,CA2C1E,CAAC"}

package/dist/cjs/transport/fetch-bridge.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installBffFetch = void 0;
+const core_1 = require("@venizia/ignis-helpers/core");
+/**
+ * Marks the patched `fetch` so a second install is refused rather than silently stacking. `Symbol.for`
+ * and not a private symbol: two copies of this package in one page must still see each other's mark.
+ */
+const BRIDGE_MARKER = Symbol.for('@venizia/ignis-worker/bff-fetch');
+/**
+ * Resolves a request's absolute URL WITHOUT constructing a `Request`.
+ *
+ * This is the whole reason this helper exists rather than one obvious line. `new Request(input)`,
+ * where `input` is a `Request` carrying a body, marks that body disturbed - so building one just to
+ * read `.url` breaks the very pass-through it is deciding about: the next line hands the same, now
+ * unreadable, request to the network.
+ *
+ * Measured, because the runtimes disagree. Chromium:
+ *
+ *     original.bodyUsed            // false
+ *     new Request(original)
+ *     original.bodyUsed            // true
+ *     await original.text()        // TypeError: body stream already read
+ *
+ * Bun does NOT disturb it, so the unit tests pass either way and cannot guard this. The browser is
+ * where this code runs, so the browser is the behaviour to write for.
+ */
+const resolveRequestUrl = (input) => {
+    if (typeof input === 'string') {
+        return new URL(input, globalThis.location?.href).href;
+    }
+    if (input instanceof URL) {
+        return input.href;
+    }
+    return input.url;
+};
+const toPrefixList = (basePath) => {
+    const prefixes = (Array.isArray(basePath) ? basePath : [basePath]).filter(prefix => prefix.length > 0);
+    if (prefixes.length === 0) {
+        throw (0, core_1.getError)({
+            message: '[installBffFetch] Invalid basePath | At least one non-empty path prefix is required',
+        });
+    }
+    return prefixes;
+};
+/**
+ * Routes the page's own `fetch` into a BFF transport for anything under `basePath`, and leaves every
+ * other call on the network untouched.
+ *
+ * This is the seam that lets an existing HTTP client talk to an in-browser IGNIS application without
+ * knowing one exists. A data provider, an SDK or a generated client reaches the network through the
+ * global `fetch` and usually accepts no custom fetcher, so answering that `fetch` is the only place
+ * an in-browser backend becomes a drop-in swap rather than a fork of the client.
+ *
+ * Install it BEFORE the application that will use it boots: a request issued while the original
+ * `fetch` is still in place leaves the page and 404s against whatever is serving it.
+ *
+ * @returns The uninstall function. It restores the previous `fetch` only if this bridge is still the
+ * installed one - if something patched `fetch` afterwards, restoring would silently discard that.
+ */
+const installBffFetch = (opts) => {
+    const { transport, basePath } = opts;
+    const carrier = opts.carrier ?? globalThis;
+    const prefixes = toPrefixList(basePath);
+    const previousFetch = carrier.fetch;
+    if (Object.getOwnPropertyDescriptor(previousFetch, BRIDGE_MARKER)) {
+        throw (0, core_1.getError)({
+            message: '[installBffFetch] A BFF fetch bridge is already installed | Uninstall it first, or pass every prefix to a single install',
+        });
+    }
+    const networkFetch = previousFetch.bind(carrier);
+    const bridged = async (input, init) => {
+        const { pathname } = new URL(resolveRequestUrl(input));
+        if (!prefixes.some(prefix => pathname.startsWith(prefix))) {
+            return networkFetch(input, init);
+        }
+        // Constructed only now, on the branch that owns the request - so the pass-through above never
+        // disturbs a body it is about to hand to the network.
+        return transport.fetch({ request: new Request(input, init) });
+    };
+    // Whatever the runtime hung on `fetch` comes along - Bun puts `preconnect` there, and a
+    // replacement that dropped it would break any caller reaching for it. Copying the descriptors is
+    // also what makes this satisfy `typeof fetch` rather than merely resembling it.
+    Object.defineProperties(bridged, Object.getOwnPropertyDescriptors(previousFetch));
+    Object.defineProperty(bridged, BRIDGE_MARKER, { value: true });
+    carrier.fetch = bridged;
+    return () => {
+        if (carrier.fetch !== bridged) {
+            return;
+        }
+        carrier.fetch = previousFetch;
+    };
+};
+exports.installBffFetch = installBffFetch;
+//# sourceMappingURL=fetch-bridge.js.map

package/dist/cjs/transport/fetch-bridge.js.map

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

package/dist/cjs/transport/index.d.ts

@@ -1,4 +1,6 @@
 export * from './common';
+export * from './fetch-bridge';
 export * from './in-process';
+export * from './shared';
 export * from './worker';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/transport/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transport/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transport/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/cjs/transport/index.js

@@ -15,6 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./common"), exports);
+__exportStar(require("./fetch-bridge"), exports);
 __exportStar(require("./in-process"), exports);
+__exportStar(require("./shared"), exports);
 __exportStar(require("./worker"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/transport/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,+CAA6B;AAC7B,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/transport/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,iDAA+B;AAC/B,+CAA6B;AAC7B,2CAAyB;AACzB,2CAAyB"}

package/dist/cjs/transport/shared.d.ts

@@ -0,0 +1,102 @@
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+import type { TConstValue } from '@venizia/ignis-helpers/common';
+import type { IBffTransport } from './common/types';
+/** Which part this tab plays. `ELECTING` is the brief window before the lock answers. */
+export declare class BffRoles {
+    static readonly ELECTING = "electing";
+    static readonly LEADER = "leader";
+    static readonly FOLLOWER = "follower";
+}
+export type TBffRole = TConstValue<typeof BffRoles>;
+export interface ISharedBffTransportOptions {
+    /** Builds the Worker. Called ONLY by whichever tab wins the election - the others never start one. */
+    createWorker: () => Worker;
+    /** Distinguishes independent BFFs on one origin. The lock name is derived from it. */
+    channelName?: string;
+    timeoutMs?: number;
+    scope?: string;
+}
+/**
+ * One BFF for every tab of an origin, instead of one per tab.
+ *
+ * The problem it solves is not a framework limitation, it is a storage one. PGlite in
+ * `opfs-ahp://` mode holds an exclusive access handle on the database file, and OPFS access handles
+ * are exclusive PER ORIGIN. Measured in Chromium with two tabs of the same page: the first tab
+ * works, and the second never boots its database -
+ * `Failed to execute 'createSyncAccessHandle' on 'FileSystemFileHandle': Access Handles cannot be
+ * created if there is another open Access Handle or Writable stream associated with the same file`.
+ * The first tab is unaffected, and closing it lets the second recover on reload - so the failure is
+ * contained and self-healing, but the second tab is simply dead until then.
+ *
+ * So exactly one tab may own the database. This transport elects that tab with the Web Locks API,
+ * gives it the Worker, and forwards every other tab's request to it over a `BroadcastChannel`,
+ * carried in the same envelope the Worker itself speaks. When the leader's tab closes, the lock is
+ * released by the browser and a follower is promoted automatically - no heartbeat, no timeout, no
+ * stale-leader window to reason about.
+ *
+ * A host with no `navigator.locks` runs single-tab, exactly as before. That is not a compromise:
+ * measured on a plain-http origin, `navigator.locks` and `navigator.storage.getDirectory` are BOTH
+ * undefined, because both are secure-context only. Wherever OPFS works the lock exists, and where it
+ * does not the database could not have started either.
+ */
+export declare class SharedBffTransport extends BaseHelper implements IBffTransport {
+    private readonly createWorker;
+    private readonly channel;
+    private readonly lockName;
+    private readonly timeoutMs;
+    private readonly requestIdGenerator;
+    private readonly pendingRequests;
+    private role;
+    private leaderTransport?;
+    private isClosed;
+    /**
+     * Held because THIS class created it. `WorkerBffTransport.close()` deliberately leaves a worker
+     * running - it did not create the one it was handed - so without this reference the worker would
+     * outlive `close()` still holding the exclusive OPFS access handle, while the lock has already
+     * gone to another tab that opens the same database.
+     */
+    private leaderWorker?;
+    /** Set when `createWorker()` throws, so callers get that failure instead of parking forever. */
+    private leaderStartupError?;
+    /** Resolving this releases the Web Lock, which is what promotes a follower. */
+    private releaseLeadership?;
+    /** Drops this tab out of the lock QUEUE on close, so a closed transport cannot be promoted. */
+    private readonly leadershipQueueAbort;
+    /** Callers parked in `fetch()` while the election is still running. */
+    private roleWaiters;
+    constructor(opts: ISharedBffTransportOptions);
+    getRole(): TBffRole;
+    fetch(opts: {
+        request: Request;
+    }): Promise<Response>;
+    close(): void;
+    private elect;
+    private becomeLeader;
+    private becomeFollower;
+    private heldUntilClosed;
+    private whenRoleSettled;
+    private settleRoleWaiters;
+    /**
+     * The caller's `AbortSignal` is honoured HERE as well as in `WorkerBffTransport`. Without it the
+     * same page code behaves differently depending on which tab won the lock: abort works in the
+     * leader and silently does nothing in every follower, so a data provider that aborts on unmount
+     * leaves promises pending for the full timeout in every tab but one.
+     *
+     * Aborting settles the CALLER. It does not cancel the leader's work - there is no cancel message,
+     * and a write already dispatched cannot be taken back.
+     */
+    private fetchViaLeader;
+    /** `signal.reason` first, the way `globalThis.fetch` rejects, so a custom abort reason survives. */
+    private toAbortError;
+    private takePending;
+    private rejectAllPending;
+    /**
+     * A `BroadcastChannel` never delivers a message to the instance that sent it, so a leader does not
+     * hear its own answers and a follower does not hear its own requests. Every tab does hear every
+     * OTHER tab, which is why a response is matched by id and silently ignored when it belongs to
+     * someone else.
+     */
+    private readonly handleChannelMessage;
+    private serveAsLeader;
+}
+//# sourceMappingURL=shared.d.ts.map

package/dist/cjs/transport/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/transport/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAgC,MAAM,6BAA6B,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAOjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,yFAAyF;AACzF,qBAAa,QAAQ;IACnB,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAc;IACtC,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAClC,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAc;CACvC;AAED,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,QAAQ,CAAC,CAAC;AA0BpD,MAAM,WAAW,0BAA0B;IACzC,sGAAsG;IACtG,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAmB,SAAQ,UAAW,YAAW,aAAa;IACzE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IAEtE,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,eAAe,CAAC,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAC,CAAS;IAE9B,gGAAgG;IAChG,OAAO,CAAC,kBAAkB,CAAC,CAAU;IAErC,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB,CAAC,CAAa;IAEvC,+FAA+F;IAC/F,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAyB;IAE9D,uEAAuE;IACvE,OAAO,CAAC,WAAW,CAAyB;gBAEhC,IAAI,EAAE,0BAA0B;IAkC5C,OAAO,IAAI,QAAQ;IAIb,KAAK,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAkC1D,KAAK,IAAI,IAAI;YA+BC,KAAK;IA4DnB,OAAO,CAAC,YAAY;IA6BpB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,iBAAiB;IASzB;;;;;;;;OAQG;YACW,cAAc;IAoD5B,oGAAoG;IACpG,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,gBAAgB;IAUxB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CA4EnC;YAEY,aAAa;CAyB5B"}