@ajnart/self-host-testkit 1.2.1 → 1.3.0

package/index.mjs

@@ -5,6 +5,22 @@ import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { inspect } from "node:util";
 import { installedBinary } from "./binary.mjs";
+import { startupReasons } from "./reasons.mjs";
+const pairStates = [
+    "running",
+    "exited",
+    "created",
+    "restarting",
+    "paused",
+    "missing",
+    "unknown",
+    "dead",
+    "removing",
+    "degraded",
+];
+function pairState(value) {
+    return pairStates.includes(value);
+}
 const MAX_MESSAGE = 65536;
 const CLEANUP_TIMEOUT = 50000;
 const messages = new Map([
@@ -16,49 +32,31 @@ const messages = new Map([
     ["CLEANUP", "Fixture cleanup failed; run manifest cleanup."],
     ["TIMEOUT", "Fixture operation timed out."],
     ["TRANSPORT", "Testkit helper transport failed."],
+    ["OPERATION", "Fixture pair action or inspection failed."],
+    ["CANCELED", "Fixture operation was canceled."],
     [
         "BINARY",
         "Testkit helper not found. Run self-host-testkit-setup or set SELF_HOST_TESTKIT_BINARY.",
     ],
 ]);
-const startupReasons = new Map([
-    ["APP", "Choose one supported Catalog App."],
-    ["OPTIONS", "Check the selected image and lifetime options."],
-    ["DOCKER", "Check the local Unix Docker socket, daemon and Compose plugin."],
-    ["CAPABILITIES", "Docker must support memory, CPU quota and PID limits."],
-    ["PORT", "A required local port could not be reserved."],
-    ["OWNERSHIP", "Fixture ownership or isolation could not be verified."],
-    [
-        "LIMITS",
-        "Container resource caps or selected image could not be verified.",
-    ],
-    ["LOCK", "The private startup lock is unavailable."],
-    [
-        "UNSUPPORTED",
-        "This App's Compose configuration or operations are unsupported.",
-    ],
-    [
-        "STORAGE",
-        "Private fixture storage or the recovery manifest is unavailable.",
-    ],
-    ["CONTAINER", "The selected App container is absent."],
-    ["SETUP", "App Setup failed or requires a Manual step."],
-]);
 export class TestkitError extends Error {
     code;
     reason;
-    constructor(code, reason) {
+    cleanupFailed;
+    constructor(code, reason, recoveryPath, cleanupFailed = false) {
         let message = messages.get(code);
-        if (code === "START" && reason)
-            message = `${message} ${startupReasons.get(reason)}`;
+        if ((code === "START" || code === "OPERATION") && reason)
+            message = `${message} ${startupReasons[reason]}`;
         super(message);
         this.name = "TestkitError";
         this.code = code;
         this.reason = reason;
+        this.cleanupFailed = cleanupFailed;
+        Object.defineProperty(this, "recoveryPath", { value: recoveryPath });
     }
 }
-function fault(code, reason) {
-    return new TestkitError(code, reason);
+function fault(code, reason, recoveryPath, cleanupFailed = false) {
+    return new TestkitError(code, reason, recoveryPath, cleanupFailed);
 }
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -85,20 +83,20 @@ function privateCredentials(value) {
 function runCleanup(binary, manifest, owner) {
     return new Promise((resolve, reject) => {
         const child = spawn(binary, ["--cleanup-manifest", manifest, "--owner", owner], { stdio: "ignore" });
+        let failed = false;
         const timer = setTimeout(() => {
+            failed = true;
             child.kill("SIGKILL");
-            reject(fault("CLEANUP"));
         }, CLEANUP_TIMEOUT);
         child.once("error", () => {
-            clearTimeout(timer);
-            reject(fault("CLEANUP"));
+            failed = true;
         });
-        child.once("exit", (code) => {
+        child.once("close", (code) => {
             clearTimeout(timer);
-            if (code === 0)
+            if (!failed && code === 0)
                 resolve(undefined);
             else
-                reject(fault("CLEANUP"));
+                reject(fault("CLEANUP", undefined, manifest));
         });
     });
 }
@@ -137,12 +135,18 @@ class Bridge {
         this.#child.stdin.on("error", () => this.#fail("TRANSPORT"));
         this.#child.stdout.on("data", (chunk) => this.#receive(chunk));
     }
+    get recoveryPath() {
+        return this.#manifest;
+    }
+    #fault(code, reason, cleanupFailed = false) {
+        return fault(code, reason, this.#manifest, cleanupFailed);
+    }
     #fail(code) {
         this.#failed = true;
         this.#buffer = Buffer.alloc(0);
         for (const pending of this.#pending.values()) {
             clearTimeout(pending.timer);
-            pending.reject(fault(code));
+            pending.reject(this.#fault(code));
         }
         this.#pending.clear();
         this.#child.kill("SIGTERM");
@@ -167,33 +171,40 @@ class Bridge {
                     !Number.isSafeInteger(response.id) ||
                     !this.#pending.has(response.id) ||
                     Object.hasOwn(response, "error") === Object.hasOwn(response, "result")) {
-                    throw fault("PROTOCOL");
+                    throw this.#fault("PROTOCOL");
                 }
                 const pending = this.#pending.get(response.id);
                 if (!pending)
-                    throw fault("PROTOCOL");
+                    throw this.#fault("PROTOCOL");
                 this.#pending.delete(response.id);
                 clearTimeout(pending.timer);
                 if (Object.hasOwn(response, "error")) {
                     if (!record(response.error) ||
                         typeof response.error.code !== "string" ||
                         !isErrorCode(response.error.code)) {
-                        pending.reject(fault("PROTOCOL"));
+                        pending.reject(this.#fault("PROTOCOL"));
                         this.#fail("PROTOCOL");
                         return;
                     }
                     let reason;
                     if (response.error.reason !== undefined) {
-                        if (response.error.code !== "START" ||
+                        if ((response.error.code !== "START" &&
+                            response.error.code !== "OPERATION") ||
                             typeof response.error.reason !== "string" ||
                             !isStartupReason(response.error.reason)) {
-                            pending.reject(fault("PROTOCOL"));
+                            pending.reject(this.#fault("PROTOCOL"));
                             this.#fail("PROTOCOL");
                             return;
                         }
                         reason = response.error.reason;
                     }
-                    pending.reject(fault(response.error.code, reason));
+                    if (response.error.cleanupFailed !== undefined &&
+                        typeof response.error.cleanupFailed !== "boolean") {
+                        pending.reject(this.#fault("PROTOCOL"));
+                        this.#fail("PROTOCOL");
+                        return;
+                    }
+                    pending.reject(this.#fault(response.error.code, reason, response.error.cleanupFailed === true));
                 }
                 else {
                     pending.resolve(response.result);
@@ -208,7 +219,9 @@ class Bridge {
     }
     request(method, params = {}, timeout = 35000) {
         if (this.#failed)
-            return Promise.reject(fault("TRANSPORT"));
+            return Promise.reject(this.#fault("TRANSPORT"));
+        if (this.#closing)
+            return Promise.reject(this.#fault("STATE"));
         const id = ++this.#sequence;
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => this.#fail("TIMEOUT"), timeout);
@@ -224,19 +237,37 @@ class Bridge {
             });
         });
     }
+    async failAndClose(primary) {
+        let code = "PROTOCOL";
+        if (primary instanceof TestkitError)
+            code = primary.code;
+        this.#fail(code);
+        try {
+            await this.close();
+        }
+        catch {
+            if (primary instanceof TestkitError)
+                throw this.#fault(primary.code, primary.reason, true);
+            throw primary;
+        }
+        throw primary;
+    }
     close() {
-        if (!this.#closing)
-            this.#closing = this.#close();
+        if (!this.#closing) {
+            this.#closing = this.#close().catch((error) => {
+                this.#closing = undefined;
+                throw error;
+            });
+        }
         return this.#closing;
     }
     async #close() {
-        let failure;
         if (!this.#failed) {
             try {
                 await this.request("close", {}, CLEANUP_TIMEOUT);
             }
             catch {
-                failure = fault("CLEANUP");
+                this.#fail("TRANSPORT");
             }
         }
         this.#child.stdin.end();
@@ -245,14 +276,7 @@ class Bridge {
         clearTimeout(kill);
         if (!this.#spawned)
             return;
-        try {
-            await runCleanup(this.#binary, this.#manifest, this.#owner);
-        }
-        catch {
-            failure = fault("CLEANUP");
-        }
-        if (failure)
-            throw failure;
+        await runCleanup(this.#binary, this.#manifest, this.#owner);
     }
     [inspect.custom]() {
         return "[TestkitBridge]";
@@ -262,46 +286,74 @@ class AppHandle {
     #bridge;
     #url;
     #closed = false;
-    constructor(bridge, url) {
+    #app;
+    constructor(bridge, url, app) {
         this.#bridge = bridge;
         this.#url = url;
+        this.#app = app;
     }
     get url() {
         return this.#url;
     }
+    get recoveryPath() {
+        return this.#bridge.recoveryPath;
+    }
+    #validate(read) {
+        try {
+            return read();
+        }
+        catch (error) {
+            if (this.#app !== undefined)
+                return this.#bridge.failAndClose(error);
+            throw error;
+        }
+    }
     async getApiKey(name = "") {
         if (this.#closed || typeof name !== "string")
             throw fault("STATE");
-        const value = await this.#bridge.request("getApiKey", { name });
-        if (!strings(value, ["apiKey"]))
-            throw fault("PROTOCOL");
-        return value.apiKey;
+        const value = await this.#bridge.request("getApiKey", {
+            name,
+            app: this.#app,
+        });
+        return this.#validate(() => {
+            if (!strings(value, ["apiKey"]))
+                throw fault("PROTOCOL");
+            return value.apiKey;
+        });
     }
     async credentials() {
         if (this.#closed)
             throw fault("STATE");
-        return privateCredentials(await this.#bridge.request("credentials"));
+        const value = await this.#bridge.request("credentials", { app: this.#app });
+        return this.#validate(() => privateCredentials(value));
     }
     async info() {
         if (this.#closed)
             throw fault("STATE");
-        const value = await this.#bridge.request("info");
-        if (!strings(value, ["id", "url", "image", "imageId"]) ||
-            !Array.isArray(value.repoDigests) ||
-            !value.repoDigests.every((digest) => typeof digest === "string")) {
-            throw fault("PROTOCOL");
-        }
-        return {
-            id: value.id,
-            url: value.url,
-            image: value.image,
-            imageId: value.imageId,
-            repoDigests: [...value.repoDigests],
-        };
+        const value = await this.#bridge.request("info", { app: this.#app });
+        return this.#validate(() => {
+            if (!strings(value, ["id", "url", "image", "imageId"]) ||
+                !Array.isArray(value.repoDigests) ||
+                !value.repoDigests.every((digest) => typeof digest === "string")) {
+                throw fault("PROTOCOL");
+            }
+            if (this.#app !== undefined &&
+                (value.id !== this.#app ||
+                    !loopback(value.url) ||
+                    value.url !== this.#url))
+                throw fault("PROTOCOL");
+            return {
+                id: value.id,
+                url: value.url,
+                image: value.image,
+                imageId: value.imageId,
+                repoDigests: [...value.repoDigests],
+            };
+        });
     }
-    async close() {
+    close() {
         this.#closed = true;
-        await this.#bridge.close();
+        return this.#bridge.close();
     }
     toJSON() {
         return "[App]";
@@ -310,6 +362,240 @@ class AppHandle {
         return "[App]";
     }
 }
+function appID(value) {
+    return typeof value === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(value);
+}
+function loopback(value) {
+    try {
+        const address = new URL(value);
+        return (address.protocol === "http:" &&
+            address.hostname === "127.0.0.1" &&
+            address.port !== "" &&
+            address.username === "" &&
+            address.password === "" &&
+            address.search === "" &&
+            address.hash === "");
+    }
+    catch {
+        return false;
+    }
+}
+function pairAppStatus(value, id, url) {
+    if (!strings(value, ["id", "url", "state", "setup"]) ||
+        value.id !== id ||
+        !loopback(value.url) ||
+        value.url !== url ||
+        typeof value.installed !== "boolean" ||
+        !pairState(value.state) ||
+        (value.setup !== "ok" &&
+            value.setup !== "manual" &&
+            value.setup !== "incomplete" &&
+            value.setup !== "pending") ||
+        !Array.isArray(value.steps))
+        throw fault("PROTOCOL");
+    const seen = new Set();
+    const steps = value.steps.map((step) => {
+        if (!strings(step, ["id", "status"]) ||
+            !appID(step.id) ||
+            (step.status !== "ok" &&
+                step.status !== "manual" &&
+                step.status !== "fail" &&
+                step.status !== "skip") ||
+            (step.verified !== undefined && typeof step.verified !== "boolean") ||
+            (step.verified === true && step.status !== "skip"))
+            throw fault("PROTOCOL");
+        if (seen.has(step.id))
+            throw fault("PROTOCOL");
+        seen.add(step.id);
+        return {
+            id: step.id,
+            status: step.status,
+            verified: step.verified === true,
+        };
+    });
+    return {
+        id,
+        url: value.url,
+        installed: value.installed,
+        state: value.state,
+        setup: value.setup,
+        steps,
+    };
+}
+function linked(step) {
+    return step.status === "ok" || (step.status === "skip" && step.verified);
+}
+function pairInspection(value, ids, urls) {
+    if (!strings(value, ["link", "outcome", "reason"]) ||
+        !appID(value.link) ||
+        !Array.isArray(value.apps) ||
+        value.apps.length !== 2)
+        throw fault("PROTOCOL");
+    const rawApps = value.apps;
+    const apps = ids.map((id, index) => pairAppStatus(rawApps[index], id, urls[index] ?? ""));
+    const base = { link: value.link, apps };
+    const failed = apps.some((app) => app.steps.some((step) => step.status === "fail"));
+    if ((value.outcome === "failed") !== failed)
+        throw fault("PROTOCOL");
+    if (!failed &&
+        (value.outcome === "manual") !== apps.some((app) => app.setup === "manual"))
+        throw fault("PROTOCOL");
+    if (value.outcome === "complete" && value.reason === "verified") {
+        if (apps.some((app) => !app.installed ||
+            app.setup !== "ok" ||
+            app.steps.some((step) => step.status === "fail" || step.status === "manual")) ||
+            !apps[0]?.steps.some((step) => step.id === base.link && linked(step)))
+            throw fault("PROTOCOL");
+        return { ...base, outcome: "complete", reason: "verified" };
+    }
+    if ((value.outcome === "manual" || value.outcome === "failed") &&
+        value.reason === "setup")
+        return { ...base, outcome: value.outcome, reason: "setup" };
+    if (value.outcome === "prerequisite" &&
+        (value.reason === "absent" ||
+            value.reason === "unready" ||
+            value.reason === "not-run")) {
+        const absent = apps.some((app) => !app.installed);
+        const unready = apps.some((app) => app.setup !== "ok");
+        if ((value.reason === "absent") !== absent ||
+            (!absent && (value.reason === "unready") !== unready) ||
+            (!absent &&
+                !unready &&
+                apps[0]?.steps.some((step) => step.id === base.link && linked(step))))
+            throw fault("PROTOCOL");
+        return { ...base, outcome: "prerequisite", reason: value.reason };
+    }
+    throw fault("PROTOCOL");
+}
+function sonarrFilterWitness(value) {
+    if (!record(value) ||
+        Object.keys(value).length !== 3 ||
+        value.kind !== "sonarr-custom-filter-v1" ||
+        typeof value.objectId !== "number" ||
+        !Number.isSafeInteger(value.objectId) ||
+        value.objectId < 1 ||
+        value.objectId > 2147483647 ||
+        typeof value.contentSha256 !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.contentSha256))
+        throw fault("PROTOCOL");
+    return Object.freeze({
+        kind: "sonarr-custom-filter-v1",
+        objectId: value.objectId,
+        contentSha256: value.contentSha256,
+    });
+}
+class PairAppHandle {
+    #view;
+    constructor(bridge, id, url) {
+        this.#view = new AppHandle(bridge, url, id);
+    }
+    get url() {
+        return this.#view.url;
+    }
+    get recoveryPath() {
+        return this.#view.recoveryPath;
+    }
+    getApiKey(name) {
+        return this.#view.getApiKey(name);
+    }
+    credentials() {
+        return this.#view.credentials();
+    }
+    info() {
+        return this.#view.info();
+    }
+    toJSON() {
+        return "[PairApp]";
+    }
+    [inspect.custom]() {
+        return "[PairApp]";
+    }
+}
+class PairHandle {
+    #bridge;
+    #ids;
+    #initial;
+    #timeout;
+    #consumer;
+    #target;
+    #witnessEnabled;
+    constructor(bridge, consumer, target, consumerURL, targetURL, initial, timeout, witnessEnabled) {
+        this.#bridge = bridge;
+        this.#ids = [consumer, target];
+        this.#initial = initial;
+        this.#timeout = timeout;
+        this.#witnessEnabled = witnessEnabled;
+        this.#consumer = new PairAppHandle(bridge, consumer, consumerURL);
+        this.#target = new PairAppHandle(bridge, target, targetURL);
+    }
+    get consumer() {
+        return this.#consumer;
+    }
+    get target() {
+        return this.#target;
+    }
+    get initial() {
+        return pairInspection(this.#initial, this.#ids, this.#initial.apps.map((app) => app.url));
+    }
+    get recoveryPath() {
+        return this.#bridge.recoveryPath;
+    }
+    async #action(method, app) {
+        if (app !== undefined && !this.#ids.includes(app))
+            throw fault("STATE");
+        const result = await this.#bridge.request(method, { app }, this.#timeout + 1000);
+        try {
+            if (!record(result) || result.link !== this.#initial.link)
+                throw fault("PROTOCOL");
+            return pairInspection(result, this.#ids, this.#initial.apps.map((app) => app.url));
+        }
+        catch (error) {
+            return this.#bridge.failAndClose(error);
+        }
+    }
+    inspect() {
+        return this.#action("inspect");
+    }
+    setup(app) {
+        return this.#action("setup", app);
+    }
+    remove(app) {
+        if (!this.#ids.includes(app))
+            return Promise.reject(fault("STATE"));
+        return this.#action("remove", app);
+    }
+    install(app) {
+        if (!this.#ids.includes(app))
+            return Promise.reject(fault("STATE"));
+        return this.#action("install", app);
+    }
+    async #sonarrWitness(method) {
+        if (!this.#witnessEnabled)
+            throw fault("STATE");
+        const value = await this.#bridge.request(method);
+        try {
+            return sonarrFilterWitness(value);
+        }
+        catch (error) {
+            return this.#bridge.failAndClose(error);
+        }
+    }
+    createSonarrFilterWitness() {
+        return this.#sonarrWitness("createSonarrFilterWitness");
+    }
+    readSonarrFilterWitness() {
+        return this.#sonarrWitness("readSonarrFilterWitness");
+    }
+    close() {
+        return this.#bridge.close();
+    }
+    toJSON() {
+        return "[Pair]";
+    }
+    [inspect.custom]() {
+        return "[Pair]";
+    }
+}
 class SelfHostHandle {
     #binary;
     #timeout;
@@ -350,6 +636,9 @@ class SelfHostHandle {
             }
         }
     }
+    get recoveryPath() {
+        return this.#manifest;
+    }
     async spinup(app, options) {
         const selected = options ?? {};
         if (this.#closed)
@@ -378,23 +667,99 @@ class SelfHostHandle {
                 image: options.image,
                 timeoutMs: this.#timeout,
             }, this.#timeout + 1000);
-            if (!strings(value, ["url"]) ||
-                !/^http:\/\/127\.0\.0\.1:\d+\/?$/.test(value.url)) {
-                throw fault("PROTOCOL");
+            if (!strings(value, ["url"]) || !loopback(value.url)) {
+                throw fault("PROTOCOL", undefined, this.#manifest);
             }
             if (this.#closed)
-                throw fault("STATE");
+                throw fault("STATE", undefined, this.#manifest);
             return new AppHandle(bridge, value.url);
         }
         catch (error) {
-            await bridge.close();
+            try {
+                await bridge.close();
+            }
+            catch {
+                throw error;
+            }
             throw error;
         }
     }
+    async spinupPair(consumer, target, options) {
+        if (this.#closed)
+            throw fault("STATE");
+        if (!appID(consumer) ||
+            !appID(target) ||
+            consumer === target ||
+            !record(options) ||
+            (options.order !== "consumer-first" && options.order !== "target-first"))
+            throw fault("PROTOCOL");
+        if (options.sonarrFilterWitness !== undefined &&
+            (options.sonarrFilterWitness !== true ||
+                consumer !== "homarr" ||
+                target !== "sonarr" ||
+                typeof options.images?.sonarr !== "string" ||
+                !/^[a-zA-Z0-9][a-zA-Z0-9._/:-]*@sha256:[a-f0-9]{64}$/.test(options.images.sonarr) ||
+                options.images.sonarr.length > 512))
+            throw fault("PROTOCOL");
+        if (options.images !== undefined &&
+            (!record(options.images) ||
+                Object.entries(options.images).some(([id, image]) => (id !== consumer && id !== target) || typeof image !== "string")))
+            throw fault("PROTOCOL");
+        const bridge = new Bridge(this.#binary, this.#manifest);
+        this.#bridges.add(bridge);
+        const start = this.#spinupPair(bridge, consumer, target, options);
+        this.#starts.add(start);
+        try {
+            return await start;
+        }
+        finally {
+            this.#starts.delete(start);
+        }
+    }
+    async #spinupPair(bridge, consumer, target, options) {
+        try {
+            if (options.sonarrFilterWitness) {
+                const capabilities = await bridge.request("capabilities", {}, Math.min(35000, this.#timeout));
+                if (!record(capabilities) ||
+                    Object.keys(capabilities).length !== 1 ||
+                    capabilities.sonarrFilterWitness !== 1)
+                    throw fault("PROTOCOL");
+            }
+            const value = await bridge.request("spinupPair", {
+                consumer,
+                target,
+                order: options.order,
+                images: options.images,
+                timeoutMs: this.#timeout,
+                sonarrFilterWitness: options.sonarrFilterWitness,
+            }, this.#timeout + 1000);
+            if (!record(value) ||
+                !strings(value.consumer, ["id", "url"]) ||
+                !strings(value.target, ["id", "url"]) ||
+                value.consumer.id !== consumer ||
+                value.target.id !== target ||
+                !loopback(value.consumer.url) ||
+                !loopback(value.target.url) ||
+                value.consumer.url === value.target.url)
+                throw fault("PROTOCOL", undefined, this.#manifest);
+            const initial = pairInspection(value.initial, [consumer, target], [value.consumer.url, value.target.url]);
+            if (options.sonarrFilterWitness && value.sonarrFilterWitness !== 1)
+                throw fault("PROTOCOL");
+            if (this.#closed)
+                throw fault("STATE", undefined, this.#manifest);
+            return new PairHandle(bridge, consumer, target, value.consumer.url, value.target.url, initial, this.#timeout, options.sonarrFilterWitness === true);
+        }
+        catch (error) {
+            return bridge.failAndClose(error);
+        }
+    }
     close() {
         if (!this.#closing) {
             this.#closed = true;
-            this.#closing = this.#close();
+            this.#closing = this.#close().catch((error) => {
+                this.#closing = undefined;
+                throw error;
+            });
         }
         return this.#closing;
     }
@@ -402,7 +767,7 @@ class SelfHostHandle {
         const results = await Promise.allSettled([...this.#bridges].map((bridge) => bridge.close()));
         await Promise.allSettled([...this.#starts]);
         if (results.some((result) => result.status === "rejected"))
-            throw fault("CLEANUP");
+            throw fault("CLEANUP", undefined, this.#manifest);
         if (this.#directory) {
             try {
                 try {
@@ -417,7 +782,7 @@ class SelfHostHandle {
                 rmdirSync(this.#directory);
             }
             catch {
-                throw fault("CLEANUP");
+                throw fault("CLEANUP", undefined, this.#manifest);
             }
         }
     }
@@ -432,10 +797,41 @@ function isErrorCode(value) {
     return [...messages.keys()].some((code) => code === value);
 }
 function isStartupReason(value) {
-    return [...startupReasons.keys()].some((reason) => reason === value);
+    return Object.hasOwn(startupReasons, value);
 }
 export function createSelfHost(options = {}) {
     if (!record(options))
         throw fault("PROTOCOL");
     return new SelfHostHandle(options);
 }
+async function scopedLifetime(work, close, onCleanupError) {
+    let result;
+    try {
+        result = { ok: true, value: await work() };
+    }
+    catch (error) {
+        result = { ok: false, error };
+    }
+    try {
+        await close();
+    }
+    catch (error) {
+        if (result.ok)
+            throw error;
+        if (onCleanupError && error instanceof TestkitError)
+            await Promise.allSettled([
+                Promise.resolve().then(() => onCleanupError(error)),
+            ]);
+    }
+    if (!result.ok)
+        throw result.error;
+    return result.value;
+}
+export async function withApp(app, callback, options = {}) {
+    const selfHost = createSelfHost(options);
+    return scopedLifetime(async () => callback(await selfHost.spinup(app, options)), () => selfHost.close(), options.onCleanupError);
+}
+export async function withPair(consumer, target, callback, options) {
+    const selfHost = createSelfHost(options);
+    return scopedLifetime(async () => callback(await selfHost.spinupPair(consumer, target, options)), () => selfHost.close(), options.onCleanupError);
+}