@braidlabs/gateway 0.1.1

package/src/appd.js

@@ -0,0 +1,93 @@
+import { BRAID_FRAGMENT_PREFIX } from './protocol.js';
+/**
+ * Projects one manifest into an AppD record.
+ *
+ * `details.url` is the interesting decision. AppD asks where a web app lives, and a fragment does
+ * not live anywhere on its own — it appears inside a host page. So:
+ *
+ * - if the fragment declares `pierce`, the first pattern names a page it actually appears on, and
+ *   that page *is* the answer: an operator following the link sees the app;
+ * - otherwise the fragment's mount is used, which is honest but is a namespace path rather than a
+ *   page, and `hostManifests.braid.standalonePage` says so.
+ *
+ * Either way the Braid-aware path is `hostManifests`, because "open this URL" is the wrong verb.
+ */
+export function toAppdApplication(manifest, origin) {
+    const mount = `${BRAID_FRAGMENT_PREFIX}${encodeURIComponent(manifest.id)}/`;
+    const page = firstPiercePage(manifest.pierce);
+    const application = {
+        appId: manifest.id,
+        name: manifest.id,
+        type: 'web',
+        details: { url: new URL(page ?? mount, origin).href },
+        title: manifest.title ?? manifest.id,
+        hostManifests: {
+            braid: { fragmentId: manifest.id, mount, adapter: manifest.adapter, standalonePage: page !== null },
+        },
+    };
+    if (manifest.description)
+        application.description = manifest.description;
+    if (manifest.tags?.length)
+        application.categories = [...manifest.tags];
+    const appd = manifest.appd;
+    if (appd?.publisher)
+        application.publisher = appd.publisher;
+    if (appd?.contactEmail)
+        application.contactEmail = appd.contactEmail;
+    if (appd?.supportEmail)
+        application.supportEmail = appd.supportEmail;
+    if (appd?.moreInfo)
+        application.moreInfo = appd.moreInfo;
+    if (appd?.version)
+        application.version = appd.version;
+    if (appd?.tooltip)
+        application.tooltip = appd.tooltip;
+    if (appd?.icons?.length)
+        application.icons = appd.icons.map((icon) => ({ ...icon }));
+    const interop = toInterop(manifest.fdc3);
+    if (interop)
+        application.interop = interop;
+    return application;
+}
+function toInterop(fdc3) {
+    if (!fdc3)
+        return undefined;
+    const listensFor = Object.entries(fdc3.listensFor ?? {}).reduce((accumulator, [intent, declaration]) => {
+        // `name` is required on an AppD intent record and duplicates the key. Filling it from the key
+        // rather than requiring it in the manifest keeps one source of truth for the intent's name.
+        accumulator[intent] = {
+            name: intent,
+            contexts: declaration.contexts ?? [],
+            ...(declaration.displayName ? { displayName: declaration.displayName } : {}),
+            ...(declaration.resultType ? { resultType: declaration.resultType } : {}),
+        };
+        return accumulator;
+    }, {});
+    const intents = {
+        ...(Object.keys(listensFor ?? {}).length > 0 ? { listensFor } : {}),
+        ...(fdc3.raises && Object.keys(fdc3.raises).length > 0 ? { raises: { ...fdc3.raises } } : {}),
+    };
+    const interop = {
+        ...(Object.keys(intents).length > 0 ? { intents } : {}),
+        ...(fdc3.userChannels ? { userChannels: { ...fdc3.userChannels } } : {}),
+    };
+    return Object.keys(interop).length > 0 ? interop : undefined;
+}
+/**
+ * The first pierce pattern reduced to a concrete page path.
+ *
+ * A wildcard suffix is dropped rather than filled — `/billing/*` becomes `/billing`, which is a
+ * page an operator can open. A pattern with a named parameter (`/orders/:id`) names no particular
+ * page, so it yields nothing rather than a link to `/orders/undefined`.
+ */
+function firstPiercePage(pierce) {
+    for (const pattern of pierce ?? []) {
+        if (pattern.includes(':'))
+            continue;
+        const trimmed = pattern.replace(/\/?\*+$/, '');
+        if (trimmed)
+            return trimmed;
+    }
+    return null;
+}
+//# sourceMappingURL=appd.js.map

package/src/appd.js.map

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

package/src/breaker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A per-fragment circuit breaker.
+ *
+ * **The problem it solves is compounding, not failure.** A fragment endpoint that is down already
+ * costs its full `timeoutMs` — but it costs that on *every* request, because nothing remembers the
+ * last one. Four fragments at a 3s budget means a page held hostage to the worst of them, over and
+ * over, with the shell's own response waiting behind it. The fallback machinery already handles a
+ * fragment that fails; what it cannot do is stop paying to rediscover that it fails.
+ *
+ * So the breaker's job is to convert a slow, repeated failure into a fast, cheap one. It is a
+ * latency control first and an availability control second.
+ *
+ * Deliberately per fragment id, never global: fragments are independently deployed, and one team's
+ * bad release must not open a circuit in front of another team's healthy app.
+ */
+export interface BreakerOptions {
+    /** Consecutive failures before the circuit opens. */
+    failureThreshold: number;
+    /** How long it stays open before a single probe is allowed through, in ms. */
+    resetTimeoutMs: number;
+}
+export declare const DEFAULT_BREAKER: BreakerOptions;
+export type BreakerState = 'closed' | 'open' | 'half-open';
+export interface BreakerTransition {
+    fragmentId: string;
+    from: BreakerState;
+    to: BreakerState;
+    /** Consecutive failures at the moment of the transition. */
+    failures: number;
+}
+export interface Breaker {
+    /**
+     * Whether a request may proceed.
+     *
+     * Calling this *claims* the half-open probe when it returns true in that state, so a caller
+     * that asks must go on to report the outcome — otherwise recovery stalls behind a probe that
+     * never resolves.
+     */
+    allows(fragmentId: string): boolean;
+    succeeded(fragmentId: string): void;
+    failed(fragmentId: string): void;
+    stateOf(fragmentId: string): BreakerState;
+}
+/**
+ * Creates a breaker.
+ *
+ * `onTransition` fires only on genuine state changes, never per request — a hook that fired on
+ * every call would be a metrics firehose describing nothing, and the interesting events here are
+ * exactly the four edges between states.
+ */
+export declare function createBreaker(options?: Partial<BreakerOptions>, onTransition?: (transition: BreakerTransition) => void, now?: () => number): Breaker;

package/src/breaker.js

@@ -0,0 +1,96 @@
+/**
+ * A per-fragment circuit breaker.
+ *
+ * **The problem it solves is compounding, not failure.** A fragment endpoint that is down already
+ * costs its full `timeoutMs` — but it costs that on *every* request, because nothing remembers the
+ * last one. Four fragments at a 3s budget means a page held hostage to the worst of them, over and
+ * over, with the shell's own response waiting behind it. The fallback machinery already handles a
+ * fragment that fails; what it cannot do is stop paying to rediscover that it fails.
+ *
+ * So the breaker's job is to convert a slow, repeated failure into a fast, cheap one. It is a
+ * latency control first and an availability control second.
+ *
+ * Deliberately per fragment id, never global: fragments are independently deployed, and one team's
+ * bad release must not open a circuit in front of another team's healthy app.
+ */
+export const DEFAULT_BREAKER = {
+    // Three, not one: a single failure is noise — a deploy rolling, a pod cycling, a dropped
+    // connection. Opening on the first one would make the breaker itself the outage.
+    failureThreshold: 3,
+    resetTimeoutMs: 10_000,
+};
+/**
+ * Creates a breaker.
+ *
+ * `onTransition` fires only on genuine state changes, never per request — a hook that fired on
+ * every call would be a metrics firehose describing nothing, and the interesting events here are
+ * exactly the four edges between states.
+ */
+export function createBreaker(options = {}, onTransition, now = Date.now) {
+    const { failureThreshold, resetTimeoutMs } = { ...DEFAULT_BREAKER, ...options };
+    const circuits = new Map();
+    const circuitFor = (fragmentId) => {
+        let circuit = circuits.get(fragmentId);
+        if (!circuit) {
+            circuit = { state: 'closed', failures: 0, openedAt: 0, probing: false };
+            circuits.set(fragmentId, circuit);
+        }
+        return circuit;
+    };
+    const transition = (fragmentId, circuit, to) => {
+        if (circuit.state === to)
+            return;
+        const from = circuit.state;
+        circuit.state = to;
+        onTransition?.({ fragmentId, from, to, failures: circuit.failures });
+    };
+    return {
+        allows(fragmentId) {
+            const circuit = circuitFor(fragmentId);
+            if (circuit.state === 'closed')
+                return true;
+            if (circuit.state === 'open') {
+                if (now() - circuit.openedAt < resetTimeoutMs)
+                    return false;
+                // The cooldown has elapsed: promote to half-open and let exactly this caller probe.
+                transition(fragmentId, circuit, 'half-open');
+                circuit.probing = true;
+                return true;
+            }
+            // half-open: one probe at a time. Everything else is still shed, because a recovering
+            // endpoint hit with the full load that took it down is an endpoint that goes down again.
+            if (circuit.probing)
+                return false;
+            circuit.probing = true;
+            return true;
+        },
+        succeeded(fragmentId) {
+            const circuit = circuitFor(fragmentId);
+            circuit.failures = 0;
+            circuit.probing = false;
+            transition(fragmentId, circuit, 'closed');
+        },
+        failed(fragmentId) {
+            const circuit = circuitFor(fragmentId);
+            circuit.failures += 1;
+            circuit.probing = false;
+            // A failed probe re-opens immediately and restarts the cooldown, rather than counting
+            // toward the threshold again — the endpoint has already proved it is still broken.
+            if (circuit.state === 'half-open' || circuit.failures >= failureThreshold) {
+                circuit.openedAt = now();
+                transition(fragmentId, circuit, 'open');
+            }
+        },
+        stateOf(fragmentId) {
+            const circuit = circuits.get(fragmentId);
+            if (!circuit)
+                return 'closed';
+            // Report the state a caller would actually get, so an operator reading this does not see
+            // `open` for a circuit whose cooldown lapsed minutes ago and which is really ready to probe.
+            if (circuit.state === 'open' && now() - circuit.openedAt >= resetTimeoutMs)
+                return 'half-open';
+            return circuit.state;
+        },
+    };
+}
+//# sourceMappingURL=breaker.js.map

package/src/breaker.js.map

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

package/src/discovery.d.ts

@@ -0,0 +1,91 @@
+import { Principal, Registry } from './registry.js';
+/**
+ * The discovery endpoint: a probeable, paginated listing of the fragments this gateway serves.
+ *
+ * It answers "what can I compose here?" for shells that build their UI from the registry rather
+ * than hard-coding slot names — a launcher, an admin console, a dashboard of available apps.
+ *
+ * It is **off by default**. A registry lists internal service topology, so publishing it is a
+ * decision, not a default.
+ */
+export interface DiscoveryOptions {
+    /** Where to serve the listing. Defaults to `/__braid/registry`. */
+    path?: string;
+    /** Items per page when the caller doesn't ask. Defaults to 100. */
+    pageSize?: number;
+    /** Hard ceiling on `pageSize`, whatever the caller asks for. Defaults to 100. */
+    maxPageSize?: number;
+    /**
+     * Include each fragment's `endpoint` in the listing. Defaults to false, because endpoints are
+     * usually internal origins and a public listing of them is a map of your private network.
+     * Forced on in development mode.
+     */
+    includeEndpoints?: boolean;
+    /**
+     * Also serve the registry in FDC3 **App Directory** shape, under `<path>/appd/v2/apps`.
+     *
+     * Off by default. It is a projection over the same manifests and the same `access.list` rules —
+     * not a second directory — so turning it on adds a shape, never a source of truth.
+     */
+    appd?: boolean;
+}
+export interface DiscoveryEntry {
+    id: string;
+    title: string;
+    description?: string;
+    tags?: string[];
+    adapter: string;
+    contractVersion?: string;
+    /** Where this fragment is addressable — what a `<fragment-slot name>` resolves to. */
+    mount: string;
+    /** Page URL patterns this fragment is server-rendered into, if any. */
+    pierce?: string[];
+    /**
+     * Whether *this caller* may actually load the fragment.
+     *
+     * Listing and loading are separate rules, so a launcher can legitimately show an app the user
+     * cannot open yet — this flag is what lets it render that state instead of a broken tile.
+     */
+    loadable: boolean;
+    /**
+     * Whether the fragment renders the page's route (a screen) or sits at a fixed path (a widget).
+     *
+     * Published because it changes how a host embeds it: a widget needs {@link DiscoveryEntry.src},
+     * a screen does not. Without this a consumer has to guess, and guessing wrong is the "widget
+     * renders an empty shell on every page" failure.
+     */
+    bound: boolean;
+    /** Where an unbound fragment's content lives, as a path on its own endpoint. */
+    src?: string;
+    /** Present only when `includeEndpoints` is on (or in development). */
+    endpoint?: string;
+}
+export interface DiscoveryPage {
+    items: DiscoveryEntry[];
+    page: number;
+    pageSize: number;
+    /** Total *visible* to this caller, not total registered. */
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+    protocolVersion: string;
+    /** True when filtering was skipped because the gateway is in development mode. */
+    unfiltered?: boolean;
+}
+export interface DiscoveryHandler {
+    /** The listing path itself. */
+    path: string;
+    /** Whether this handler answers for a pathname — the listing, or its App Directory projection. */
+    owns(pathname: string): boolean;
+    handle(request: Request, url: URL): Promise<Response>;
+}
+export declare const DEFAULT_DISCOVERY_PATH = "/__braid/registry";
+export declare const DEFAULT_DISCOVERY_PAGE_SIZE = 100;
+/**
+ * Builds the discovery handler, or null when discovery is not enabled.
+ *
+ * In development every fragment is listed with its endpoint regardless of `visibility`, because
+ * a registry you cannot see is hard to debug — and the gateway says so loudly at startup, since
+ * that is precisely the configuration you must not ship.
+ */
+export declare function createDiscoveryHandler(registry: Registry, options: DiscoveryOptions | undefined, mode: 'production' | 'development', resolvePrincipal: (request: Request) => Promise<Principal | undefined>): DiscoveryHandler | null;

package/src/discovery.js

@@ -0,0 +1,127 @@
+import { BRAID_FRAGMENT_PREFIX, BRAID_PROTOCOL_VERSION } from './protocol.js';
+import { toAppdApplication } from './appd.js';
+import { canFetch, canList } from './registry.js';
+export const DEFAULT_DISCOVERY_PATH = '/__braid/registry';
+export const DEFAULT_DISCOVERY_PAGE_SIZE = 100;
+/**
+ * Builds the discovery handler, or null when discovery is not enabled.
+ *
+ * In development every fragment is listed with its endpoint regardless of `visibility`, because
+ * a registry you cannot see is hard to debug — and the gateway says so loudly at startup, since
+ * that is precisely the configuration you must not ship.
+ */
+export function createDiscoveryHandler(registry, options, mode, resolvePrincipal) {
+    if (!options)
+        return null;
+    const path = options.path ?? DEFAULT_DISCOVERY_PATH;
+    const maxPageSize = Math.max(1, options.maxPageSize ?? DEFAULT_DISCOVERY_PAGE_SIZE);
+    const defaultPageSize = Math.min(Math.max(1, options.pageSize ?? DEFAULT_DISCOVERY_PAGE_SIZE), maxPageSize);
+    const isDevelopment = mode === 'development';
+    const includeEndpoints = isDevelopment || (options.includeEndpoints ?? false);
+    if (isDevelopment) {
+        console.warn(`braid-gateway: the discovery endpoint at "${path}" is running in development mode — it lists every ` +
+            `fragment with its endpoint, ignoring each manifest's "access" rules. Do not ship this configuration.`);
+    }
+    const appdEnabled = options.appd ?? false;
+    const appdPath = `${path}/appd/v2/apps`;
+    return {
+        path,
+        /** True for the discovery path and, when enabled, its App Directory projection. */
+        owns(pathname) {
+            return pathname === path || (appdEnabled && (pathname === appdPath || pathname.startsWith(`${appdPath}/`)));
+        },
+        async handle(request, url) {
+            if (request.method !== 'GET' && request.method !== 'HEAD') {
+                return json({ error: 'method not allowed' }, 405, { Allow: 'GET, HEAD' });
+            }
+            const principal = isDevelopment ? undefined : await resolvePrincipal(request);
+            const all = await registry.listFragments();
+            const visible = isDevelopment ? all : all.filter((manifest) => canList(manifest, principal));
+            // The App Directory is the same list, in AppD's shape — same manifests, same access rules,
+            // so a caller can never see a resolver through AppD that discovery would have hidden.
+            if (appdEnabled && url.pathname.startsWith(appdPath)) {
+                const requested = url.pathname.slice(appdPath.length).replace(/^\//, '');
+                if (!requested) {
+                    const body = {
+                        applications: visible.map((manifest) => toAppdApplication(manifest, url.origin)),
+                        message: 'OK',
+                    };
+                    return json(body, 200, { 'Cache-Control': 'no-store', Vary: 'cookie, authorization' });
+                }
+                const appId = decodeURIComponent(requested);
+                const match = visible.find((manifest) => manifest.id === appId);
+                if (!match) {
+                    // 404 for "not visible to you" as well as "not registered" — distinguishing them would
+                    // let an unauthorized caller enumerate the registry one id at a time.
+                    return json({ message: `No application with appId "${appId}"` }, 404, { 'Cache-Control': 'no-store' });
+                }
+                const body = { application: toAppdApplication(match, url.origin), message: 'OK' };
+                return json(body, 200, { 'Cache-Control': 'no-store', Vary: 'cookie, authorization' });
+            }
+            const pageSize = clampPageSize(url.searchParams.get('pageSize'), defaultPageSize, maxPageSize);
+            const totalPages = Math.max(1, Math.ceil(visible.length / pageSize));
+            const page = clampPage(url.searchParams.get('page'), totalPages);
+            const start = (page - 1) * pageSize;
+            const items = visible
+                .slice(start, start + pageSize)
+                .map((manifest) => toEntry(manifest, includeEndpoints, isDevelopment || canFetch(manifest, principal)));
+            const body = {
+                items,
+                page,
+                pageSize,
+                total: visible.length,
+                totalPages,
+                hasMore: start + items.length < visible.length,
+                protocolVersion: BRAID_PROTOCOL_VERSION,
+                ...(isDevelopment ? { unfiltered: true } : {}),
+            };
+            // the listing depends on who asked, so it must never land in a shared cache
+            return json(body, 200, {
+                'Cache-Control': 'no-store',
+                Vary: 'cookie, authorization',
+            });
+        },
+    };
+}
+function toEntry(manifest, includeEndpoints, loadable) {
+    const entry = {
+        id: manifest.id,
+        title: manifest.title ?? manifest.id,
+        adapter: manifest.adapter,
+        mount: `${BRAID_FRAGMENT_PREFIX}${encodeURIComponent(manifest.id)}/`,
+        loadable,
+        bound: manifest.bound,
+    };
+    if (manifest.description)
+        entry.description = manifest.description;
+    if (manifest.tags?.length)
+        entry.tags = [...manifest.tags];
+    if (manifest.contractVersion)
+        entry.contractVersion = manifest.contractVersion;
+    if (manifest.pierce?.length)
+        entry.pierce = [...manifest.pierce];
+    if (manifest.src)
+        entry.src = manifest.src;
+    if (includeEndpoints && typeof manifest.endpoint === 'string')
+        entry.endpoint = manifest.endpoint;
+    return entry;
+}
+function clampPageSize(requested, fallback, max) {
+    const parsed = Number.parseInt(requested ?? '', 10);
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return fallback;
+    return Math.min(parsed, max);
+}
+function clampPage(requested, totalPages) {
+    const parsed = Number.parseInt(requested ?? '', 10);
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return 1;
+    return Math.min(parsed, totalPages);
+}
+function json(body, status, headers = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'Content-Type': 'application/json;charset=UTF-8', ...headers },
+    });
+}
+//# sourceMappingURL=discovery.js.map

package/src/discovery.js.map

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