@toa.io/extensions.introspection 1.0.0-alpha.262

package/transpiled/Explorer.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Explorer = void 0;
+const core_1 = require("@toa.io/core");
+const openspan_1 = require("openspan");
+/**
+ * The explorer process. It hosts the introspection components — the map is read
+ * through their own operations — and serves the UI.
+ */
+class Explorer extends core_1.Connector {
+    async open() {
+        openspan_1.console.info('Introspection explorer started');
+    }
+    dispose() {
+        openspan_1.console.info('Introspection explorer is closed');
+    }
+}
+exports.Explorer = Explorer;
+//# sourceMappingURL=Explorer.js.map

package/transpiled/Explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Explorer.js","sourceRoot":"","sources":["../source/Explorer.ts"],"names":[],"mappings":";;;AAAA,uCAAwC;AACxC,uCAAkC;AAElC;;;GAGG;AACH,MAAa,QAAS,SAAQ,gBAAS;IAClB,KAAK,CAAC,IAAI;QAC3B,kBAAO,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAA;IAChD,CAAC;IAEkB,OAAO;QACxB,kBAAO,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAA;IAClD,CAAC;CACF;AARD,4BAQC"}

package/transpiled/Factory.d.ts

@@ -0,0 +1,22 @@
+import { Connector } from '@toa.io/core';
+import type { Declaration } from './annotation';
+import type { Manifest } from '@toa.io/norm';
+import type { Component, Locator, extensions } from '@toa.io/core';
+export declare class Factory implements extensions.Factory {
+    private readonly boot;
+    private readonly options;
+    private readonly settings;
+    private reporter;
+    constructor(boot: Bootloader);
+    tenant(locator: Locator, decl: Declaration | null, manifest: Manifest): Connector;
+    component(component: Component): Component;
+    service(): Connector | null;
+    /**
+     * `tenant()` runs before any component is created, so settings are warm.
+     * A component booted on its own (without a composition) falls back to
+     * the environment, with sampling off.
+     */
+    private resolve;
+    private collector;
+}
+export type Bootloader = typeof import('@toa.io/boot');

package/transpiled/Factory.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Factory = void 0;
+const core_1 = require("@toa.io/core");
+const annotation_1 = require("./annotation");
+const const_1 = require("./const");
+const describe_1 = require("./describe");
+const Reporter_1 = require("./Reporter");
+const Tenant_1 = require("./Tenant");
+const Composition_1 = require("./Composition");
+const Explorer_1 = require("./Explorer");
+const UI_1 = require("./UI");
+const sample_1 = require("./sample");
+class Factory {
+    boot;
+    options;
+    settings = {};
+    reporter = null;
+    constructor(boot) {
+        this.boot = boot;
+        this.options = (0, annotation_1.environment)();
+    }
+    tenant(locator, decl, manifest) {
+        const resolved = (0, annotation_1.settings)(locator.namespace, (0, annotation_1.component)(decl), this.options);
+        this.settings[locator.id] = resolved;
+        if (!resolved.enabled || locator.namespace === const_1.NAMESPACE)
+            return new core_1.Connector();
+        return new Tenant_1.Tenant(this.collector(), (0, describe_1.describe)(manifest));
+    }
+    component(component) {
+        const locator = component.locator;
+        const resolved = this.resolve(locator);
+        if (!resolved.enabled)
+            return component;
+        const reporter = this.collector();
+        const invoke = component.invoke.bind(component);
+        component.invoke = async (endpoint, request) => {
+            let outcome = 'ok';
+            let reply;
+            try {
+                reply = await invoke(endpoint, request);
+                if (reply?.exception !== undefined)
+                    outcome = 'exception';
+                else if (reply?.error !== undefined)
+                    outcome = 'error';
+                return reply;
+            }
+            catch (error) {
+                outcome = 'exception';
+                throw error;
+            }
+            finally {
+                // a call that failed is still a connection between two components
+                const src = request?.source ?? UNKNOWN;
+                const dst = { namespace: locator.namespace, component: locator.name, operation: endpoint };
+                const sample = resolved.samples && (0, sample_1.samplable)(request?.input)
+                    ? (0, sample_1.capture)(request?.input, outcome)
+                    : undefined;
+                reporter.observe({ src, dst, sample });
+            }
+        };
+        component.depends(reporter);
+        return component;
+    }
+    service() {
+        if (this.options === null)
+            return null;
+        const composition = new Composition_1.Composition(this.boot);
+        const explorer = new Explorer_1.Explorer();
+        explorer.depends(composition);
+        if (this.options.ui)
+            explorer.depends(new UI_1.UI(const_1.UI_PORT));
+        return explorer;
+    }
+    /**
+     * `tenant()` runs before any component is created, so settings are warm.
+     * A component booted on its own (without a composition) falls back to
+     * the environment, with sampling off.
+     */
+    resolve(locator) {
+        if (locator.namespace === const_1.NAMESPACE)
+            return annotation_1.DISABLED;
+        return this.settings[locator.id] ??
+            (0, annotation_1.settings)(locator.namespace, {}, this.options === null ? null : { ...this.options, samples: false });
+    }
+    collector() {
+        this.reporter ??= new Reporter_1.Reporter(this.boot, this.options);
+        return this.reporter;
+    }
+}
+exports.Factory = Factory;
+const UNKNOWN = { service: 'unknown' };
+//# sourceMappingURL=Factory.js.map

package/transpiled/Factory.js.map

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

package/transpiled/Reporter.d.ts

@@ -0,0 +1,44 @@
+import { Connector } from '@toa.io/core';
+import type { Bootloader } from './Factory';
+import type { Options } from './annotation';
+import type { Edge, Node } from './model';
+/**
+ * Buffers what a process observes and flushes it into the introspection
+ * components.
+ *
+ * Nothing here is on the critical path. Reaching the explorer is a discovery,
+ * which waits as long as it takes, so the collector never holds up a component
+ * starting, running or stopping: it buffers until the connection is there, and
+ * when it has to choose it gives up on the data rather than on the application.
+ */
+export declare class Reporter extends Connector {
+    private readonly boot;
+    private readonly options;
+    private readonly nodes;
+    private readonly edges;
+    /** Holds a remote only once it is connected and usable. */
+    private readonly remotes;
+    private timer;
+    private flushing;
+    private acquiring;
+    private dropped;
+    constructor(boot: Bootloader, options: Options);
+    /** The static description of a component. */
+    expose(node: Node): void;
+    /** A call between two components. */
+    observe(observed: Edge): void;
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+    private ready;
+    private flush;
+    private discard;
+    private dispatch;
+    /**
+     * A mass transition: every affected object is acquired and committed at once,
+     * so a flush is one call per component whatever it carries.
+     */
+    private merge;
+    /** Runs in the background: discovery waits for the explorer as long as it takes. */
+    private acquire;
+    private reach;
+}

package/transpiled/Reporter.js

@@ -0,0 +1,187 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Reporter = void 0;
+const core_1 = require("@toa.io/core");
+const openspan_1 = require("openspan");
+const const_1 = require("./const");
+const keys = __importStar(require("./keys"));
+/**
+ * Buffers what a process observes and flushes it into the introspection
+ * components.
+ *
+ * Nothing here is on the critical path. Reaching the explorer is a discovery,
+ * which waits as long as it takes, so the collector never holds up a component
+ * starting, running or stopping: it buffers until the connection is there, and
+ * when it has to choose it gives up on the data rather than on the application.
+ */
+class Reporter extends core_1.Connector {
+    boot;
+    options;
+    nodes = new Map();
+    edges = new Map();
+    /** Holds a remote only once it is connected and usable. */
+    remotes = {};
+    timer = null;
+    flushing = null;
+    acquiring = false;
+    dropped = 0;
+    constructor(boot, options) {
+        super();
+        this.boot = boot;
+        this.options = options;
+    }
+    /** The static description of a component. */
+    expose(node) {
+        this.nodes.set(keys.node(node.namespace, node.component), node);
+        void this.flush();
+    }
+    /** A call between two components. */
+    observe(observed) {
+        const id = keys.edge(observed.src, observed.dst);
+        const edge = this.edges.get(id);
+        if (edge === undefined) {
+            /*
+             * `source` arrives over the wire, so the number of distinct edges a process
+             * can hold has to be bounded regardless of what peers send — and of whether
+             * anyone is there to take them.
+             */
+            if (this.edges.size >= const_1.MAX_EDGES) {
+                this.dropped++;
+                return;
+            }
+            this.edges.set(id, observed);
+        }
+        else if (observed.sample !== undefined)
+            edge.sample = observed.sample;
+        if (this.edges.size >= this.options.threshold)
+            void this.flush();
+    }
+    async open() {
+        // deliberately not awaited: the explorer may not be there yet, or at all
+        this.acquire();
+        this.timer = setInterval(() => void this.flush(), this.options.interval * 1000);
+        this.timer.unref();
+    }
+    async close() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.flushing;
+        if (!this.ready()) {
+            this.discard('the explorer was never reached');
+            return;
+        }
+        // the remotes are still up: dependencies are disconnected after this returns
+        await this.dispatch().catch((error) => {
+            openspan_1.console.debug('Introspection final flush failed', { message: error.message });
+        });
+    }
+    ready() {
+        return const_1.NODES in this.remotes && const_1.EDGES in this.remotes;
+    }
+    async flush() {
+        // a dispatch in flight keeps observations buffered, they join the next batch
+        if (this.flushing !== null)
+            return;
+        if (this.nodes.size === 0 && this.edges.size === 0)
+            return;
+        if (!this.ready()) {
+            this.acquire();
+            if (this.edges.size >= const_1.MAX_EDGES)
+                this.discard('the explorer is not reachable');
+            return;
+        }
+        this.flushing = this.dispatch()
+            .catch((error) => {
+            openspan_1.console.debug('Introspection flush failed', { message: error.message });
+        })
+            .finally(() => {
+            this.flushing = null;
+        });
+        await this.flushing;
+    }
+    discard(reason) {
+        const nodes = this.nodes.size;
+        const edges = this.edges.size + this.dropped;
+        this.nodes.clear();
+        this.edges.clear();
+        this.dropped = 0;
+        if (nodes === 0 && edges === 0)
+            return;
+        openspan_1.console.warn(`Introspection data discarded, ${reason}`, { nodes, edges });
+    }
+    async dispatch() {
+        const nodes = [...this.nodes.entries()];
+        const edges = [...this.edges.entries()];
+        this.nodes.clear();
+        this.edges.clear();
+        if (this.dropped > 0) {
+            openspan_1.console.warn('Introspection edges dropped', { dropped: this.dropped, limit: const_1.MAX_EDGES });
+            this.dropped = 0;
+        }
+        await Promise.all([
+            this.merge(const_1.NODES, 'nodes', nodes),
+            this.merge(const_1.EDGES, 'edges', edges)
+        ]);
+    }
+    /**
+     * A mass transition: every affected object is acquired and committed at once,
+     * so a flush is one call per component whatever it carries.
+     */
+    async merge(name, property, observed) {
+        if (observed.length === 0)
+            return;
+        const objects = {};
+        for (const [id, object] of observed)
+            objects[id] = object;
+        await this.remotes[name].invoke('merge', {
+            query: { ids: observed.map(([id]) => id) },
+            input: { [property]: objects },
+            task: true
+        });
+    }
+    /** Runs in the background: discovery waits for the explorer as long as it takes. */
+    acquire() {
+        if (this.acquiring)
+            return;
+        this.acquiring = true;
+        void this.reach().catch((error) => {
+            this.acquiring = false;
+            openspan_1.console.error('Introspection cannot reach its explorer', { message: error.message });
+        });
+    }
+    async reach() {
+        await Promise.all([const_1.NODES, const_1.EDGES].map(async (name) => {
+            const remote = await this.boot.remote(new core_1.Locator(name, const_1.NAMESPACE));
+            this.depends(remote);
+            await remote.connect();
+            this.remotes[name] = remote;
+        }));
+    }
+}
+exports.Reporter = Reporter;
+//# sourceMappingURL=Reporter.js.map

package/transpiled/Reporter.js.map

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

package/transpiled/Tenant.d.ts

@@ -0,0 +1,18 @@
+import { Connector } from '@toa.io/core';
+import type { Reporter } from './Reporter';
+import type { Node } from './model';
+/**
+ * Announces the static description of a component.
+ *
+ * Delivery is guaranteed, so the repeat is not about reliability — it keeps
+ * `_updated` fresh, which is how a removed component fades off the map.
+ */
+export declare class Tenant extends Connector {
+    private readonly reporter;
+    private readonly node;
+    private stopped;
+    constructor(reporter: Reporter, node: Node);
+    protected open(): Promise<void>;
+    protected dispose(): void;
+    private announce;
+}

package/transpiled/Tenant.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tenant = void 0;
+const promises_1 = require("node:timers/promises");
+const core_1 = require("@toa.io/core");
+const const_1 = require("./const");
+/**
+ * Announces the static description of a component.
+ *
+ * Delivery is guaranteed, so the repeat is not about reliability — it keeps
+ * `_updated` fresh, which is how a removed component fades off the map.
+ */
+class Tenant extends core_1.Connector {
+    reporter;
+    node;
+    stopped = false;
+    constructor(reporter, node) {
+        super();
+        this.reporter = reporter;
+        this.node = node;
+        this.depends(reporter);
+    }
+    async open() {
+        this.reporter.expose(this.node);
+        void this.announce();
+    }
+    dispose() {
+        this.stopped = true;
+    }
+    async announce() {
+        while (!this.stopped) {
+            await (0, promises_1.setTimeout)(const_1.ANNOUNCE_INTERVAL, undefined, { ref: false });
+            if (this.stopped)
+                break;
+            this.reporter.expose(this.node);
+        }
+    }
+}
+exports.Tenant = Tenant;
+//# sourceMappingURL=Tenant.js.map

package/transpiled/Tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tenant.js","sourceRoot":"","sources":["../source/Tenant.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AACjD,uCAAwC;AACxC,mCAA2C;AAI3C;;;;;GAKG;AACH,MAAa,MAAO,SAAQ,gBAAS;IAClB,QAAQ,CAAU;IAClB,IAAI,CAAM;IACnB,OAAO,GAAG,KAAK,CAAA;IAEvB,YAAoB,QAAkB,EAAE,IAAU;QAChD,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAEhB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAE/B,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAA;IACtB,CAAC;IAEkB,OAAO;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;IACrB,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,IAAA,qBAAU,EAAC,yBAAiB,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAA;YAE9D,IAAI,IAAI,CAAC,OAAO;gBACd,MAAK;YAEP,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,CAAC;IACH,CAAC;CACF;AAlCD,wBAkCC"}

package/transpiled/UI.d.ts

@@ -0,0 +1,25 @@
+import { Connector } from '@toa.io/core';
+/**
+ * Serves the introspection UI: the directory `ui` builds, and nothing else.
+ *
+ * The page is a single-page application whose mount path is baked into the bundle,
+ * so this server routes relative to `UI_PATH` — which is also what the ingress
+ * forwards. `/introspection/*` is left alone: that is the components' own API.
+ */
+export declare class UI extends Connector {
+    private readonly server;
+    private readonly port;
+    private readonly root;
+    constructor(port: number, root?: string);
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+    private listen;
+    private respond;
+    /**
+     * The file a request lands on, or `null` when nothing does. A path that exists is
+     * served as it is; anything else that could be a route falls back to the page,
+     * because the client router — not this server — knows what routes there are.
+     */
+    private resolve;
+    private send;
+}

package/transpiled/UI.js

@@ -0,0 +1,186 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI = void 0;
+const fs = __importStar(require("node:fs"));
+const http = __importStar(require("node:http"));
+const path = __importStar(require("node:path"));
+const core_1 = require("@toa.io/core");
+const openspan_1 = require("openspan");
+const const_1 = require("./const");
+/**
+ * Serves the introspection UI: the directory `ui` builds, and nothing else.
+ *
+ * The page is a single-page application whose mount path is baked into the bundle,
+ * so this server routes relative to `UI_PATH` — which is also what the ingress
+ * forwards. `/introspection/*` is left alone: that is the components' own API.
+ */
+class UI extends core_1.Connector {
+    server = http.createServer();
+    port;
+    root;
+    constructor(port, root = SITE) {
+        super();
+        this.port = port;
+        this.root = root;
+        this.server.on('request', (request, response) => {
+            this.listen(request, response);
+        });
+    }
+    async open() {
+        /*
+         * A taken port is a real error: uniqueness across services is settled at export
+         * time, so nothing here has to negotiate for one.
+         */
+        await new Promise((resolve, reject) => {
+            const failed = (error) => {
+                this.server.off('listening', listening);
+                reject(error);
+            };
+            const listening = () => {
+                this.server.off('error', failed);
+                resolve();
+            };
+            this.server.once('error', failed);
+            this.server.once('listening', listening);
+            this.server.listen(this.port);
+        });
+        if (!isFile(path.join(this.root, 'index.html')))
+            openspan_1.console.warn('Introspection UI is not built', { root: this.root });
+        openspan_1.console.info('Introspection UI started', { port: this.port, path: const_1.UI_PATH + '/' });
+    }
+    async close() {
+        const closed = new Promise((resolve) => this.server.once('close', () => {
+            resolve();
+        }));
+        this.server.close();
+        this.server.closeAllConnections();
+        await closed;
+    }
+    listen(request, response) {
+        void this.respond(request, response).catch((error) => {
+            openspan_1.console.error('Introspection UI failure', { message: error.message });
+            if (!response.writableEnded)
+                response.writeHead(500).end();
+        });
+    }
+    async respond(request, response) {
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            response.writeHead(405, { allow: 'GET, HEAD' }).end();
+            return;
+        }
+        const pathname = decode(request.url ?? '/');
+        if (pathname === null) {
+            response.writeHead(400).end();
+            return;
+        }
+        // the port is the explorer's alone, so the root is the way in
+        if (pathname === '/') {
+            response.writeHead(302, { location: const_1.UI_PATH + '/' }).end();
+            return;
+        }
+        const file = this.resolve(pathname);
+        if (file === null)
+            response.writeHead(404).end();
+        else
+            await this.send(file, request, response);
+    }
+    /**
+     * The file a request lands on, or `null` when nothing does. A path that exists is
+     * served as it is; anything else that could be a route falls back to the page,
+     * because the client router — not this server — knows what routes there are.
+     */
+    resolve(pathname) {
+        if (!pathname.startsWith(const_1.UI_PATH))
+            return null;
+        const relative = pathname.slice(const_1.UI_PATH.length);
+        if (relative !== '' && !relative.startsWith('/'))
+            return null;
+        const file = path.join(this.root, relative);
+        if (file !== this.root && !file.startsWith(this.root + path.sep))
+            return null;
+        if (isFile(file))
+            return file;
+        /*
+         * A missing asset is missing, but a route can look like one: `identity.passkeys` is a
+         * component, not a file with an extension. What this server would have served is what
+         * it knows how to serve, so anything else is a route and falls back to the page — as
+         * does anything ending in a slash, which is no name for a file at all.
+         */
+        const asset = !relative.endsWith('/') && path.extname(relative) in TYPES;
+        return asset ? null : path.join(this.root, 'index.html');
+    }
+    async send(file, request, response) {
+        const stats = await fs.promises.stat(file).catch(() => null);
+        if (stats === null) {
+            response.writeHead(503, { 'content-type': 'text/plain' })
+                .end('The introspection UI is not built. Run `npm run build:ui`.\n');
+            return;
+        }
+        response.writeHead(200, {
+            'content-type': TYPES[path.extname(file)] ?? 'application/octet-stream',
+            'content-length': stats.size,
+            'cache-control': file.startsWith(path.join(this.root, IMMUTABLE)) ? FOREVER : 'no-cache'
+        });
+        if (request.method === 'HEAD')
+            response.end();
+        else
+            fs.createReadStream(file).pipe(response);
+    }
+}
+exports.UI = UI;
+function decode(url) {
+    try {
+        return decodeURIComponent(url.split('?')[0]);
+    }
+    catch {
+        return null;
+    }
+}
+function isFile(file) {
+    return fs.existsSync(file) && fs.statSync(file).isFile();
+}
+/** Where `npm run build:ui` puts the page, from both `source` and `transpiled`. */
+const SITE = path.resolve(__dirname, '..', 'ui', 'dist');
+/** Assets under this prefix carry their build hash in the name. */
+const IMMUTABLE = path.join('_app', 'immutable');
+const FOREVER = 'public, max-age=31536000, immutable';
+const TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.ico': 'image/x-icon',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain; charset=utf-8',
+    '.webmanifest': 'application/manifest+json',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2'
+};
+//# sourceMappingURL=UI.js.map