@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/modules/marketplace/marketplace-repo.service.js

@@ -0,0 +1,318 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { WorkspaceMutex } from '../kb-fs/mutex.js';
+/**
+ * ONE bare repository, ONE git namespace per caller.
+ *
+ * Every person's compiled marketplace is a branch in its own namespace
+ * (`refs/namespaces/<ns>/refs/heads/main`), which is exactly what git
+ * namespaces exist for (gitnamespaces(7)): `git http-backend` run with
+ * `GIT_NAMESPACE=<ns>` advertises only that namespace's refs, so a clone sees
+ * a repository whose `main` is their tree and nothing else — while every
+ * identical skill across callers is one blob in one object store.
+ *
+ * Freshness is LAZY and keyed on the knowledge base's default-branch commit:
+ * every input to a compile (skills, manifests, access rules, roles, groups)
+ * lives in that repository, so "same source commit" means "same answer".
+ * The last compiled source per namespace sits in a sidecar file rather than
+ * a commit trailer, so an unchanged tree costs no commit and no re-check.
+ *
+ * Each recompile appends a commit whose parent is the namespace's current
+ * head, so a client's `git pull` is always a fast-forward — including when
+ * access was withdrawn and files vanish. Writes go through git plumbing
+ * against a temporary index: no working tree of the bare repo, no checkout.
+ *
+ * Read-only by construction: `http.receivepack` is pinned off (http-backend
+ * would otherwise enable pushes for an authenticated REMOTE_USER), and the
+ * route refuses the receive-pack service before git ever sees it.
+ */
+export class MarketplaceRepoService {
+    repoDir;
+    compiler;
+    gitRunner;
+    committer;
+    locks = new WorkspaceMutex();
+    initialised = null;
+    constructor(
+    /** Absolute path of the bare repository (created on first use). */
+    repoDir, compiler, 
+    /** How git is run — see `shared/git.contract.ts`. */
+    gitRunner, committer = {
+        name: 'Hexis',
+        email: 'hexis@localhost',
+    }) {
+        this.repoDir = repoDir;
+        this.compiler = compiler;
+        this.gitRunner = gitRunner;
+        this.committer = committer;
+    }
+    /** The directory `GIT_PROJECT_ROOT` points at, and the repo's name under it. */
+    get projectRoot() {
+        return path.dirname(this.repoDir);
+    }
+    get repoName() {
+        return path.basename(this.repoDir);
+    }
+    /** The namespace for a user id — one path segment, stable, opaque. */
+    static namespaceFor(userId) {
+        return `u-${userId.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 120)}`;
+    }
+    async ensureRepo() {
+        this.initialised ??= (async () => {
+            await fs.mkdir(this.projectRoot, { recursive: true });
+            const isRepo = await fs
+                .access(path.join(this.repoDir, 'HEAD'))
+                .then(() => true, () => false);
+            if (!isRepo)
+                await this.git(['init', '--bare', '--quiet', this.repoDir]);
+            await this.git(['-C', this.repoDir, 'config', 'http.receivepack', 'false']);
+            await this.git(['-C', this.repoDir, 'config', 'http.uploadpack', 'true']);
+            await fs.mkdir(this.sidecarDir(), { recursive: true });
+        })().catch((err) => {
+            // A failed initialisation is retried by the next request, not
+            // remembered until restart: a volume that was briefly unavailable must
+            // not turn every later fetch into a 500.
+            this.initialised = null;
+            throw err;
+        });
+        await this.initialised;
+    }
+    /**
+     * Bring the caller's namespace up to the knowledge base's current commit,
+     * compiling only when it moved. Serialised per namespace: two fetches
+     * arriving together compile once.
+     */
+    async ensureCompiled(user) {
+        await this.ensureRepo();
+        const namespace = MarketplaceRepoService.namespaceFor(user.id);
+        return this.locks.run(`ns:${namespace}`, async () => {
+            const last = await this.readSidecar(namespace);
+            const head = await this.headOf(namespace);
+            let current = await this.compiler.sourceCommit();
+            if (last === current && head !== null) {
+                // Unchanged source is still a served namespace: its HEAD is checked
+                // on every fetch (a read) and written only when it is missing, so a
+                // crash after an earlier branch update cannot leave a clone that sees
+                // no default branch — and the cache hit stays a read on a healthy repo.
+                await this.ensureHead(namespace);
+                return { namespace, compiled: false, sourceCommit: current };
+            }
+            // The commit just read is the one the tree is stamped with: a second
+            // read that failed would otherwise record a placeholder as the compiled
+            // source and make every later fetch recompile. And the checkout can
+            // move WHILE we compile from it (a merge landing mid-read), so the
+            // commit is re-read afterwards: a tree stamped with a commit it was
+            // not compiled from would freeze that caller on a stale tree until the
+            // next change. Bounded — a checkout that moves on every attempt is
+            // served the latest attempt rather than never.
+            let tree = await this.compiler.compileFor({ userEmail: user.email }, current);
+            for (let attempt = 0; attempt < 3; attempt++) {
+                const after = await this.compiler.sourceCommit();
+                if (after === current)
+                    break;
+                current = after;
+                tree = await this.compiler.compileFor({ userEmail: user.email }, current);
+            }
+            const sha = await this.commitTree(namespace, tree, head);
+            await this.writeSidecar(namespace, tree.sourceCommit);
+            return { namespace, compiled: sha !== head, sourceCommit: tree.sourceCommit };
+        });
+    }
+    /**
+     * The caller's namespace and its head commit, compiled if stale — what the
+     * GitHub-shaped REST surface (the Cowork path) reads instead of cloning.
+     */
+    async headFor(user) {
+        const { namespace } = await this.ensureCompiled(user);
+        const sha = await this.headOf(namespace);
+        if (!sha)
+            throw new Error(`namespace ${namespace} has no head after compiling`);
+        return { namespace, sha };
+    }
+    /** One commit as the REST surface describes it. */
+    async describeCommit(sha) {
+        assertObjectId(sha);
+        const { stdout } = await this.git(['-C', this.repoDir, 'log', '-1', '--format=%H%n%T%n%an%n%ae%n%aI%n%B', sha]);
+        const [full, tree, authorName, authorEmail, date, ...rest] = stdout.split('\n');
+        return {
+            sha: full ?? sha,
+            tree: tree ?? '',
+            message: rest.join('\n').trim(),
+            authorName: authorName ?? '',
+            authorEmail: authorEmail ?? '',
+            date: date ?? '',
+        };
+    }
+    /**
+     * Whether `sha` is the namespace's head or one of its ancestors — the only
+     * commits a caller may read as that namespace. The object store is shared
+     * across everyone, so a sha alone is never enough.
+     */
+    async contains(namespace, sha) {
+        if (!looksLikeObjectId(sha))
+            return false;
+        const head = await this.headOf(namespace);
+        if (!head)
+            return false;
+        // Two questions with two answers each, and only "no" is ever silent:
+        // a commit git does not have is simply not contained; a commit it has
+        // is an ancestor (exit 0) or not (exit 1); anything else — a corrupt
+        // store, a lock, a bad ref — is a failure the caller must hear about,
+        // not a 404 wearing its clothes.
+        try {
+            await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', `${sha}^{commit}`]);
+        }
+        catch (err) {
+            if (exitCodeOf(err) === 1)
+                return false;
+            throw err;
+        }
+        try {
+            await this.git(['-C', this.repoDir, 'merge-base', '--is-ancestor', sha, head]);
+            return true;
+        }
+        catch (err) {
+            if (exitCodeOf(err) === 1)
+                return false;
+            throw err;
+        }
+    }
+    /** The tree at `sha` as a zip stream, every path under `prefix/`. Check {@link contains} first. */
+    archiveZip(sha, prefix) {
+        assertObjectId(sha);
+        return spawn('git', ['-C', this.repoDir, 'archive', '--format=zip', `--prefix=${prefix}/`, sha], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    // --- internal --------------------------------------------------------------
+    refOf(namespace) {
+        return `refs/namespaces/${namespace}/refs/heads/main`;
+    }
+    async headOf(namespace) {
+        try {
+            const { stdout } = await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', this.refOf(namespace)]);
+            return stdout.trim() || null;
+        }
+        catch (err) {
+            // "No such ref" is the answer this null stands for, and `rev-parse
+            // --verify --quiet` says it with exit code 1 and nothing else. Every
+            // other failure — a deadline, a repository git cannot open, a spawn that
+            // never ran — is not an answer about the ref, and read as one it would
+            // have `ensureCompiled` start a namespace's history over on top of the
+            // one it has.
+            if (exitCodeOf(err) !== 1)
+                throw err;
+            return null;
+        }
+    }
+    /**
+     * Write `tree` as a commit on the namespace's branch. Materialises the
+     * virtual tree into a scratch directory, stages it into a throwaway index
+     * against the bare object store, and commits — no working tree involved.
+     * When the tree hash equals the head's, nothing is committed.
+     */
+    async commitTree(namespace, tree, parent) {
+        const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-marketplace-'));
+        // The throwaway index lives BESIDE the scratch worktree, never inside it:
+        // `git add -A` would otherwise stage the index (and its lock) into every
+        // compiled tree.
+        const indexDir = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-marketplace-index-'));
+        try {
+            for (const [rel, bytes] of tree.files) {
+                // The compiler sanitises every segment it invents, but the tree is
+                // built from repository content, so the sink checks containment
+                // itself: nothing is written outside the scratch directory.
+                const abs = path.resolve(scratch, rel);
+                if (!abs.startsWith(scratch + path.sep)) {
+                    throw new Error(`refusing to materialise "${rel}": escapes the scratch tree`);
+                }
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                await fs.writeFile(abs, bytes);
+            }
+            const index = path.join(indexDir, 'index');
+            const env = { ...process.env, GIT_INDEX_FILE: index, GIT_DIR: this.repoDir, GIT_WORK_TREE: scratch };
+            await this.git(['add', '-A', '--', '.'], { cwd: scratch, env });
+            const treeSha = (await this.git(['write-tree'], { env })).stdout.trim();
+            if (parent) {
+                const parentTree = (await this.git(['-C', this.repoDir, 'rev-parse', `${parent}^{tree}`])).stdout.trim();
+                if (parentTree === treeSha)
+                    return parent;
+            }
+            const message = `Compile marketplace from ${tree.sourceCommit}\n\nHexis-Source-Commit: ${tree.sourceCommit}\n`;
+            const commitEnv = {
+                ...process.env,
+                GIT_AUTHOR_NAME: this.committer.name,
+                GIT_AUTHOR_EMAIL: this.committer.email,
+                GIT_COMMITTER_NAME: this.committer.name,
+                GIT_COMMITTER_EMAIL: this.committer.email,
+            };
+            const args = ['-C', this.repoDir, 'commit-tree', treeSha, '-m', message, ...(parent ? ['-p', parent] : [])];
+            const sha = (await this.git(args, { env: commitEnv })).stdout.trim();
+            // HEAD FIRST, then the branch: a symbolic ref may dangle, a branch
+            // without a HEAD is a clone that checks out nothing. Ordered so that a
+            // crash between the two leaves the recoverable state.
+            await this.ensureHead(namespace);
+            await this.git(['-C', this.repoDir, 'update-ref', this.refOf(namespace), sha, ...(parent ? [parent] : [])]);
+            return sha;
+        }
+        finally {
+            await fs.rm(scratch, { recursive: true, force: true });
+            await fs.rm(indexDir, { recursive: true, force: true });
+        }
+    }
+    /**
+     * Point the namespace's HEAD at its branch — valid before the branch
+     * exists. A read first: the symref is written only when absent or wrong,
+     * so the common path touches nothing.
+     */
+    async ensureHead(namespace) {
+        const head = `refs/namespaces/${namespace}/HEAD`;
+        const current = await this.git(['-C', this.repoDir, 'symbolic-ref', '--quiet', head]).then((r) => r.stdout.trim(), () => null);
+        if (current === this.refOf(namespace))
+            return;
+        await this.git(['-C', this.repoDir, 'symbolic-ref', head, this.refOf(namespace)]);
+    }
+    sidecarDir() {
+        return path.join(this.repoDir, 'hexis-namespaces');
+    }
+    async readSidecar(namespace) {
+        try {
+            return (await fs.readFile(path.join(this.sidecarDir(), `${namespace}.json`), 'utf-8')).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeSidecar(namespace, sourceCommit) {
+        await fs.writeFile(path.join(this.sidecarDir(), `${namespace}.json`), sourceCommit);
+    }
+    /**
+     * Every command names the bare repository with `-C`, so the working
+     * directory only has to be somewhere that EXISTS: the process's own, as
+     * before. Not the repository — the first command ever run here is the `init`
+     * that creates it, and a spawn into a directory that is not there fails as
+     * `ENOENT` on git itself, which reads as git being missing. The plumbing
+     * that reads a scratch checkout passes its own `cwd`.
+     */
+    git(args, opts = {}) {
+        return this.gitRunner.run(opts.cwd ?? process.cwd(), args, { env: opts.env });
+    }
+}
+/** The exit code a git failure carries, or null when the process never ran. */
+function exitCodeOf(err) {
+    const code = err?.exitCode;
+    return typeof code === 'number' ? code : null;
+}
+function looksLikeObjectId(sha) {
+    return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha);
+}
+function assertObjectId(sha) {
+    // An object id is the only thing these commands accept as a revision — a
+    // ref name, an option, anything git would interpret, is refused before it
+    // reaches the argument list.
+    if (!looksLikeObjectId(sha))
+        throw new Error(`not an object id: ${sha}`);
+}
+//# sourceMappingURL=marketplace-repo.service.js.map

package/dist/modules/marketplace/marketplace-repo.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marketplace-repo.service.js","sourceRoot":"","sources":["../../../src/modules/marketplace/marketplace-repo.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAsBnD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,sBAAsB;IAMtB;IACQ;IAEA;IACA;IATF,KAAK,GAAG,IAAI,cAAc,EAAE,CAAC;IACtC,WAAW,GAAyB,IAAI,CAAC;IAEjD;IACE,mEAAmE;IAC1D,OAAe,EACP,QAA6B;IAC9C,qDAAqD;IACpC,SAAqB,EACrB,YAA6C;QAC5D,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,iBAAiB;KACzB;QAPQ,YAAO,GAAP,OAAO,CAAQ;QACP,aAAQ,GAAR,QAAQ,CAAqB;QAE7B,cAAS,GAAT,SAAS,CAAY;QACrB,cAAS,GAAT,SAAS,CAGzB;IACA,CAAC;IAEJ,gFAAgF;IAChF,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,sEAAsE;IACtE,MAAM,CAAC,YAAY,CAAC,MAAc;QAChC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACvE,CAAC;IAED,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,WAAW,KAAK,CAAC,KAAK,IAAI,EAAE;YAC/B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,MAAM,MAAM,GAAG,MAAM,EAAE;iBACpB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;iBACvC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACzE,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC,CAAC;YAC5E,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;YAC1E,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YAC1B,8DAA8D;YAC9D,uEAAuE;YACvE,yCAAyC;YACzC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,WAAW,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,cAAc,CAAC,IAAmC;QACtD,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,sBAAsB,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,SAAS,EAAE,EAAE,KAAK,IAAI,EAAE;YAClD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;YAC/C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC1C,IAAI,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC;YACjD,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBACtC,oEAAoE;gBACpE,oEAAoE;gBACpE,sEAAsE;gBACtE,wEAAwE;gBACxE,MAAM,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;gBACjC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;YAC/D,CAAC;YAED,qEAAqE;YACrE,wEAAwE;YACxE,oEAAoE;YACpE,mEAAmE;YACnE,oEAAoE;YACpE,uEAAuE;YACvE,mEAAmE;YACnE,+CAA+C;YAC/C,IAAI,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;YAC9E,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;gBAC7C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC;gBACjD,IAAI,KAAK,KAAK,OAAO;oBAAE,MAAM;gBAC7B,OAAO,GAAG,KAAK,CAAC;gBAChB,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;YAC5E,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACzD,MAAM,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YACtD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QAChF,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,IAAmC;QAC/C,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,SAAS,8BAA8B,CAAC,CAAC;QAChF,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IAC5B,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,cAAc,CAAC,GAAW;QAQ9B,cAAc,CAAC,GAAG,CAAC,CAAC;QACpB,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,oCAAoC,EAAE,GAAG,CAAC,CAAC,CAAC;QAChH,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChF,OAAO;YACL,GAAG,EAAE,IAAI,IAAI,GAAG;YAChB,IAAI,EAAE,IAAI,IAAI,EAAE;YAChB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE;YAC/B,UAAU,EAAE,UAAU,IAAI,EAAE;YAC5B,WAAW,EAAE,WAAW,IAAI,EAAE;YAC9B,IAAI,EAAE,IAAI,IAAI,EAAE;SACjB,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,SAAiB,EAAE,GAAW;QAC3C,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,qEAAqE;QACrE,sEAAsE;QACtE,qEAAqE;QACrE,sEAAsE;QACtE,iCAAiC;QACjC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC;QAC9F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACxC,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAC/E,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACxC,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,mGAAmG;IACnG,UAAU,CAAC,GAAW,EAAE,MAAc;QACpC,cAAc,CAAC,GAAG,CAAC,CAAC;QACpB,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,MAAM,GAAG,EAAE,GAAG,CAAC,EAAE;YAC/F,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAEtE,KAAK,CAAC,SAAiB;QAC7B,OAAO,mBAAmB,SAAS,kBAAkB,CAAC;IACxD,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,SAAiB;QACpC,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YACnH,OAAO,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,mEAAmE;YACnE,qEAAqE;YACrE,yEAAyE;YACzE,uEAAuE;YACvE,uEAAuE;YACvE,cAAc;YACd,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,MAAM,GAAG,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,UAAU,CACtB,SAAiB,EACjB,IAA4C,EAC5C,MAAqB;QAErB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,oBAAoB,CAAC,CAAC,CAAC;QAC/E,0EAA0E;QAC1E,yEAAyE;QACzE,iBAAiB;QACjB,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,0BAA0B,CAAC,CAAC,CAAC;QACtF,IAAI,CAAC;YACH,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACtC,mEAAmE;gBACnE,gEAAgE;gBAChE,4DAA4D;gBAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;gBACvC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBACxC,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,6BAA6B,CAAC,CAAC;gBAChF,CAAC;gBACD,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACvD,MAAM,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC3C,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC;YACrG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YAChE,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACxE,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACzG,IAAI,UAAU,KAAK,OAAO;oBAAE,OAAO,MAAM,CAAC;YAC5C,CAAC;YACD,MAAM,OAAO,GAAG,4BAA4B,IAAI,CAAC,YAAY,4BAA4B,IAAI,CAAC,YAAY,IAAI,CAAC;YAC/G,MAAM,SAAS,GAAG;gBAChB,GAAG,OAAO,CAAC,GAAG;gBACd,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;gBACpC,gBAAgB,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK;gBACtC,kBAAkB,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;gBACvC,mBAAmB,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK;aAC1C,CAAC;YACF,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC5G,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACrE,mEAAmE;YACnE,uEAAuE;YACvE,sDAAsD;YACtD,MAAM,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YACjC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC5G,OAAO,GAAG,CAAC;QACb,CAAC;gBAAS,CAAC;YACT,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACvD,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,UAAU,CAAC,SAAiB;QACxC,MAAM,IAAI,GAAG,mBAAmB,SAAS,OAAO,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CACxF,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EACtB,GAAG,EAAE,CAAC,IAAI,CACX,CAAC;QACF,IAAI,OAAO,KAAK,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;YAAE,OAAO;QAC9C,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACpF,CAAC;IAEO,UAAU;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;IACrD,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,SAAiB;QACzC,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,SAAS,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;QACxG,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,SAAiB,EAAE,YAAoB;QAChE,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,SAAS,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC;IACtF,CAAC;IAED;;;;;;;OAOG;IACK,GAAG,CAAC,IAAc,EAAE,OAAkD,EAAE;QAC9E,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAChF,CAAC;CACF;AAED,+EAA+E;AAC/E,SAAS,UAAU,CAAC,GAAY;IAC9B,MAAM,IAAI,GAAI,GAAqC,EAAE,QAAQ,CAAC;IAC9D,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,OAAO,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,yEAAyE;IACzE,0EAA0E;IAC1E,6BAA6B;IAC7B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/modules/mcp/downstream-pool.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The ONE piece of state the stateless MCP endpoint keeps between requests: a
+ * pool of connections to proxied third-party MCP servers (`mcp.json` manuals),
+ * keyed by (user, server).
+ *
+ * Everything else a request needs is re-derived from its own bearer. These
+ * connections are the exception because a downstream MCP server is session-ful
+ * by nature — dialing a fresh handshake on every tool call would add a round
+ * trip per call and hammer the provider. So they are cached, and the pool is
+ * built so that losing any of it costs a reconnect, never correctness:
+ *
+ *   - created LAZILY, on the first request that needs the server;
+ *   - SINGLE-FLIGHT per key: concurrent first calls share one creation, so a
+ *     burst produces one connection instead of N with all but one orphaned;
+ *   - IDLE-EVICTED and SIZE-BOUNDED, with the retired session store's proven
+ *     defaults (4 hours idle, 5000 entries);
+ *   - every eviction CLOSES what it evicts (`dispose`) — the pool is the owner
+ *     of each connection it opened, and nothing else closes them;
+ *   - LEASED: `acquire` hands out a lease the caller releases when its
+ *     operation ends. A leased entry is in use, so it is never idle and never
+ *     the LRU victim; an entry invalidated while leased leaves the pool at once
+ *     but is closed only when its last lease is released. A call in progress
+ *     never has its connection closed underneath it.
+ *
+ * Eviction is lazy, like the store it replaces: `acquire` sweeps idle entries
+ * first and enforces the cap on insert. No background timer, so constructing a
+ * pool never leaks an interval handle (in tests or anywhere else). When every
+ * entry is leased the cap cannot evict anything, and the pool holds more than
+ * `maxEntries` until leases are released — and the release that ends an
+ * entry's last lease re-applies the cap, so the overflow ends with the leases,
+ * not with whenever the next acquire happens to run.
+ *
+ * Healing a connection whose server restarted is NOT this class's job: the
+ * pooled value carries the existing session-recovery wrapper, which
+ * re-registers on the spec's 404 in place. The pool only decides how long a
+ * value lives.
+ */
+export interface DownstreamPoolOptions<V> {
+    /** Close a value the pool is dropping. Errors are logged, never thrown. */
+    dispose: (value: V) => Promise<void>;
+    /** Drop entries unused for longer than this. Default: 4 hours. */
+    idleTtlMs?: number;
+    /** Hard cap on pooled entries; the least-recently-used is evicted first. Default: 5000. */
+    maxEntries?: number;
+    /** Override `Date.now` — injected only by tests. */
+    now?: () => number;
+}
+/** A pooled value in use. `release` ends the use; calling it again is a no-op. */
+export interface Lease<V> {
+    readonly value: V;
+    release(): void;
+}
+export declare const DEFAULT_DOWNSTREAM_IDLE_TTL_MS: number;
+export declare const DEFAULT_DOWNSTREAM_MAX_ENTRIES = 5000;
+export declare class DownstreamPool<V> {
+    private readonly entries;
+    private readonly pending;
+    private readonly dispose;
+    private readonly idleTtlMs;
+    private readonly maxEntries;
+    private readonly now;
+    constructor(opts: DownstreamPoolOptions<V>);
+    /**
+     * Lease the pooled value for `key`, creating it with `create` when absent.
+     * The caller MUST release the lease when its operation ends (try/finally).
+     * A creation that rejects is NOT cached — every waiter sees the rejection and
+     * the next `acquire` tries again (retry pacing is the caller's policy, see
+     * ManualFailureMemo).
+     */
+    acquire(key: string, create: () => Promise<V>): Promise<Lease<V>>;
+    /**
+     * Evict every entry whose key matches — the hook for "this user's
+     * credentials changed". Idle entries are closed now; leased ones leave the
+     * pool now and are closed when released. A creation in flight for a matching
+     * key is marked stale, so its result is closed and rebuilt instead of cached.
+     */
+    evictWhere(predicate: (key: string) => boolean): void;
+    /** Evict and close everything (leased entries close on release). */
+    closeAll(): void;
+    /** Pooled (resolved) entries; diagnostics and tests. Does not sweep. */
+    size(): number;
+    private awaitPending;
+    private lease;
+    private insert;
+    /**
+     * Evict idle entries, least recently used first, until at most
+     * `maxEntries - reserve` remain — or nothing idle is left, in which case
+     * the pool stays over the cap until a lease is released (which calls this
+     * again). `reserve` is the room an insert needs for the entry it is about
+     * to add.
+     */
+    private enforceCap;
+    private sweep;
+    /** Evict the least-recently-used entry not in use; false when every entry is leased. */
+    private evictLeastRecentlyUsed;
+    /** Take an entry out of the pool; close it now, or on its last release when leased. */
+    private retire;
+    /**
+     * Fire-and-forget close: a slow downstream teardown must not block the
+     * request that happened to trigger the sweep, and a failing one must not
+     * stop the rest of the sweep.
+     */
+    private disposeQuietly;
+}
+/** Separator for (user, manual, fingerprint) keys — cannot occur in any of the parts. */
+export declare const POOL_KEY_SEPARATOR = "\0";
+//# sourceMappingURL=downstream-pool.d.ts.map

package/dist/modules/mcp/downstream-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downstream-pool.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/downstream-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAMH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,2EAA2E;IAC3E,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,kFAAkF;AAClF,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,eAAO,MAAM,8BAA8B,QAAqB,CAAC;AACjE,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAkBnD,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAO1C;;;;;;OAMG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IA2BvE;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI;IASrD,oEAAoE;IACpE,QAAQ,IAAI,IAAI;IAIhB,wEAAwE;IACxE,IAAI,IAAI,MAAM;YAIA,YAAY;IAW1B,OAAO,CAAC,KAAK;IAwBb,OAAO,CAAC,MAAM;IAQd;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,KAAK;IAOb,wFAAwF;IACxF,OAAO,CAAC,sBAAsB;IAW9B,uFAAuF;IACvF,OAAO,CAAC,MAAM;IAMd;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAOvB;AAQD,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,OAAW,CAAC"}

package/dist/modules/mcp/downstream-pool.js

@@ -0,0 +1,221 @@
+/**
+ * The ONE piece of state the stateless MCP endpoint keeps between requests: a
+ * pool of connections to proxied third-party MCP servers (`mcp.json` manuals),
+ * keyed by (user, server).
+ *
+ * Everything else a request needs is re-derived from its own bearer. These
+ * connections are the exception because a downstream MCP server is session-ful
+ * by nature — dialing a fresh handshake on every tool call would add a round
+ * trip per call and hammer the provider. So they are cached, and the pool is
+ * built so that losing any of it costs a reconnect, never correctness:
+ *
+ *   - created LAZILY, on the first request that needs the server;
+ *   - SINGLE-FLIGHT per key: concurrent first calls share one creation, so a
+ *     burst produces one connection instead of N with all but one orphaned;
+ *   - IDLE-EVICTED and SIZE-BOUNDED, with the retired session store's proven
+ *     defaults (4 hours idle, 5000 entries);
+ *   - every eviction CLOSES what it evicts (`dispose`) — the pool is the owner
+ *     of each connection it opened, and nothing else closes them;
+ *   - LEASED: `acquire` hands out a lease the caller releases when its
+ *     operation ends. A leased entry is in use, so it is never idle and never
+ *     the LRU victim; an entry invalidated while leased leaves the pool at once
+ *     but is closed only when its last lease is released. A call in progress
+ *     never has its connection closed underneath it.
+ *
+ * Eviction is lazy, like the store it replaces: `acquire` sweeps idle entries
+ * first and enforces the cap on insert. No background timer, so constructing a
+ * pool never leaks an interval handle (in tests or anywhere else). When every
+ * entry is leased the cap cannot evict anything, and the pool holds more than
+ * `maxEntries` until leases are released — and the release that ends an
+ * entry's last lease re-applies the cap, so the overflow ends with the leases,
+ * not with whenever the next acquire happens to run.
+ *
+ * Healing a connection whose server restarted is NOT this class's job: the
+ * pooled value carries the existing session-recovery wrapper, which
+ * re-registers on the spec's 404 in place. The pool only decides how long a
+ * value lives.
+ */
+import { logger } from '../../shared/logging.js';
+const log = logger('mcp');
+export const DEFAULT_DOWNSTREAM_IDLE_TTL_MS = 4 * 60 * 60 * 1000;
+export const DEFAULT_DOWNSTREAM_MAX_ENTRIES = 5000;
+export class DownstreamPool {
+    entries = new Map();
+    pending = new Map();
+    dispose;
+    idleTtlMs;
+    maxEntries;
+    now;
+    constructor(opts) {
+        this.dispose = opts.dispose;
+        this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_DOWNSTREAM_IDLE_TTL_MS;
+        this.maxEntries = Math.max(1, opts.maxEntries ?? DEFAULT_DOWNSTREAM_MAX_ENTRIES);
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Lease the pooled value for `key`, creating it with `create` when absent.
+     * The caller MUST release the lease when its operation ends (try/finally).
+     * A creation that rejects is NOT cached — every waiter sees the rejection and
+     * the next `acquire` tries again (retry pacing is the caller's policy, see
+     * ManualFailureMemo).
+     */
+    async acquire(key, create) {
+        this.sweep();
+        const hit = this.entries.get(key);
+        if (hit)
+            return this.lease(hit);
+        const inflight = this.pending.get(key);
+        if (inflight)
+            return this.awaitPending(key, inflight, create);
+        const record = { promise: create(), stale: false };
+        this.pending.set(key, record);
+        const forget = () => {
+            if (this.pending.get(key) === record)
+                this.pending.delete(key);
+        };
+        let value;
+        try {
+            value = await record.promise;
+        }
+        finally {
+            forget();
+        }
+        if (record.stale) {
+            // Invalidated mid-creation (the user's credentials changed): the value
+            // was built from the old state. Close it and build a current one.
+            this.disposeQuietly(key, value);
+            return this.acquire(key, create);
+        }
+        return this.lease(this.insert(key, value));
+    }
+    /**
+     * Evict every entry whose key matches — the hook for "this user's
+     * credentials changed". Idle entries are closed now; leased ones leave the
+     * pool now and are closed when released. A creation in flight for a matching
+     * key is marked stale, so its result is closed and rebuilt instead of cached.
+     */
+    evictWhere(predicate) {
+        for (const [key, entry] of [...this.entries]) {
+            if (predicate(key))
+                this.retire(entry);
+        }
+        for (const [key, record] of this.pending) {
+            if (predicate(key))
+                record.stale = true;
+        }
+    }
+    /** Evict and close everything (leased entries close on release). */
+    closeAll() {
+        this.evictWhere(() => true);
+    }
+    /** Pooled (resolved) entries; diagnostics and tests. Does not sweep. */
+    size() {
+        return this.entries.size;
+    }
+    async awaitPending(key, record, create) {
+        const value = await record.promise;
+        // The creator owns closing a stale value; a joiner just asks again.
+        if (record.stale)
+            return this.acquire(key, create);
+        // The creator pooled the value before this continuation ran. If it has
+        // already left the pool again, lease whatever the pool holds now.
+        const entry = this.entries.get(key);
+        if (!entry || entry.value !== value)
+            return this.acquire(key, create);
+        return this.lease(entry);
+    }
+    lease(entry) {
+        entry.leases += 1;
+        entry.lastUsedAt = this.now();
+        let released = false;
+        return {
+            value: entry.value,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                entry.leases -= 1;
+                // Idleness is measured from the end of the last use.
+                entry.lastUsedAt = this.now();
+                if (entry.retired && entry.leases === 0)
+                    this.disposeQuietly(entry.key, entry.value);
+                // An insert that found every entry leased could not evict and let the
+                // pool overflow the cap. The overflow has to end with the leases, not
+                // with whenever the next acquire happens to run — so the release that
+                // ends an entry's last lease re-applies the cap. The entry just
+                // released is the newest by `lastUsedAt`, so older idle entries go
+                // first.
+                if (entry.leases === 0)
+                    this.enforceCap();
+            },
+        };
+    }
+    insert(key, value) {
+        this.sweep();
+        this.enforceCap(1);
+        const entry = { key, value, lastUsedAt: this.now(), leases: 0, retired: false };
+        this.entries.set(key, entry);
+        return entry;
+    }
+    /**
+     * Evict idle entries, least recently used first, until at most
+     * `maxEntries - reserve` remain — or nothing idle is left, in which case
+     * the pool stays over the cap until a lease is released (which calls this
+     * again). `reserve` is the room an insert needs for the entry it is about
+     * to add.
+     */
+    enforceCap(reserve = 0) {
+        while (this.entries.size + reserve > this.maxEntries && this.evictLeastRecentlyUsed()) {
+            // each pass evicted one idle entry
+        }
+    }
+    sweep() {
+        const cutoff = this.now() - this.idleTtlMs;
+        for (const entry of [...this.entries.values()]) {
+            if (entry.leases === 0 && entry.lastUsedAt < cutoff)
+                this.retire(entry);
+        }
+    }
+    /** Evict the least-recently-used entry not in use; false when every entry is leased. */
+    evictLeastRecentlyUsed() {
+        let oldest;
+        for (const entry of this.entries.values()) {
+            if (entry.leases > 0)
+                continue;
+            if (!oldest || entry.lastUsedAt < oldest.lastUsedAt)
+                oldest = entry;
+        }
+        if (!oldest)
+            return false;
+        this.retire(oldest);
+        return true;
+    }
+    /** Take an entry out of the pool; close it now, or on its last release when leased. */
+    retire(entry) {
+        if (this.entries.get(entry.key) === entry)
+            this.entries.delete(entry.key);
+        entry.retired = true;
+        if (entry.leases === 0)
+            this.disposeQuietly(entry.key, entry.value);
+    }
+    /**
+     * Fire-and-forget close: a slow downstream teardown must not block the
+     * request that happened to trigger the sweep, and a failing one must not
+     * stop the rest of the sweep.
+     */
+    disposeQuietly(key, value) {
+        void Promise.resolve()
+            .then(() => this.dispose(value))
+            .catch((err) => {
+            log.warn(`closing pooled downstream connection failed (${poolKeyLabel(key)}):`, { err });
+        });
+    }
+}
+/** A log-safe rendering of a pool key: user and manual, never the template fingerprint. */
+function poolKeyLabel(key) {
+    const [userId, manual] = key.split(POOL_KEY_SEPARATOR);
+    return `user=${userId ?? '?'} manual=${manual ?? '?'}`;
+}
+/** Separator for (user, manual, fingerprint) keys — cannot occur in any of the parts. */
+export const POOL_KEY_SEPARATOR = '\u0000';
+//# sourceMappingURL=downstream-pool.js.map