@jmfederico/pi-web 1.202608.2 → 1.202609.1

package/dist/server/plugins/pluginBackendRegistry.js

@@ -0,0 +1,740 @@
+import { isAbsolute, resolve } from "node:path";
+import { isPiWebPluginId } from "../../shared/pluginIds.js";
+import { boundedPluginBackendChannelCloseReason, cloneBoundedPluginBackendJson, PLUGIN_BACKEND_CHANNEL_CALLBACK_TIMEOUT_MS, PLUGIN_BACKEND_CHANNEL_DATA_JSON_MAX_BYTES, PLUGIN_BACKEND_CHANNEL_MAX_LIFETIME_MS, PLUGIN_BACKEND_CHANNEL_MAX_PER_PLUGIN, PLUGIN_BACKEND_CHANNEL_MAX_PER_PLUGIN_WORKSPACE, PLUGIN_BACKEND_CHANNEL_MAX_TOTAL, PLUGIN_BACKEND_CHANNEL_OPEN_TIMEOUT_MS, PLUGIN_BACKEND_CHANNEL_TEARDOWN_TIMEOUT_MS, PLUGIN_BACKEND_DISPATCH_TIMEOUT_MS, PLUGIN_BACKEND_REQUEST_TIMEOUT_MS, PLUGIN_BACKEND_RESPONSE_JSON_MAX_BYTES, requirePluginBackendOperation, requirePluginBackendRevision, } from "../../shared/pluginBackendProtocol.js";
+import { PluginCallbackDrain } from "../pluginCallbackDrain.js";
+export class PluginBackendRequestError extends Error {
+    constructor(code, statusCode, message, options = {}) {
+        super(message, options);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = "PluginBackendRequestError";
+    }
+}
+export class PluginBackendChannelError extends Error {
+    constructor(code, closeCode, message, options = {}) {
+        super(message, options);
+        this.code = code;
+        this.closeCode = closeCode;
+        this.name = "PluginBackendChannelError";
+    }
+}
+/** Keep active paired backends whose bounded startup health is not unhealthy. */
+export function eligiblePluginBackendContributions(contributions, inspections) {
+    const healthByPluginId = new Map(inspections.map(({ pluginId, health }) => [pluginId, health.status]));
+    return Object.freeze(contributions.filter(({ pluginId }) => {
+        const status = healthByPluginId.get(pluginId);
+        return status === "healthy" || status === "degraded";
+    }));
+}
+/** Dispatches only to a browser package's revision-matched paired server entry. */
+export class PluginBackendRegistry {
+    constructor(options) {
+        this.options = options;
+        this.channels = new Set();
+        this.channelAdmissions = new Set();
+        this.openingChannelControllers = new Set();
+        this.openingChannelTasks = new Set();
+        this.openingChannelCleanup = new PluginCallbackDrain();
+        this.requestTasks = new Set();
+        this.requestCallbacks = new PluginCallbackDrain();
+        this.shutdown = new AbortController();
+        this.channelAdmissionCount = 0;
+        this.channelsByPlugin = new Map();
+        this.channelsByPluginWorkspace = new Map();
+        this.contributions = snapshotContributions(options.contributions);
+        this.callbackTimeoutMs = positiveInteger(options.callbackTimeoutMs, PLUGIN_BACKEND_REQUEST_TIMEOUT_MS, "callbackTimeoutMs");
+        this.dispatchTimeoutMs = positiveInteger(options.dispatchTimeoutMs, PLUGIN_BACKEND_DISPATCH_TIMEOUT_MS, "dispatchTimeoutMs");
+        this.channelCallbackTimeoutMs = positiveInteger(options.channelCallbackTimeoutMs, PLUGIN_BACKEND_CHANNEL_CALLBACK_TIMEOUT_MS, "channelCallbackTimeoutMs");
+        this.channelOpenTimeoutMs = positiveInteger(options.channelOpenTimeoutMs, PLUGIN_BACKEND_CHANNEL_OPEN_TIMEOUT_MS, "channelOpenTimeoutMs");
+        this.channelLifetimeMs = positiveInteger(options.channelLifetimeMs, PLUGIN_BACKEND_CHANNEL_MAX_LIFETIME_MS, "channelLifetimeMs");
+        this.channelMaxTotal = positiveInteger(options.channelMaxTotal, PLUGIN_BACKEND_CHANNEL_MAX_TOTAL, "channelMaxTotal");
+        this.channelMaxPerPlugin = positiveInteger(options.channelMaxPerPlugin, PLUGIN_BACKEND_CHANNEL_MAX_PER_PLUGIN, "channelMaxPerPlugin");
+        this.channelMaxPerPluginWorkspace = positiveInteger(options.channelMaxPerPluginWorkspace, PLUGIN_BACKEND_CHANNEL_MAX_PER_PLUGIN_WORKSPACE, "channelMaxPerPluginWorkspace");
+    }
+    async request(request, signal) {
+        if (this.channelsAreShuttingDown())
+            throw requestShutdownError(request.pluginId);
+        const operationSignal = signal === undefined
+            ? this.shutdown.signal
+            : AbortSignal.any([signal, this.shutdown.signal]);
+        const task = runBoundedPluginBackendOperation(request.pluginId, "dispatch", this.dispatchTimeoutMs, (dispatchSignal) => this.dispatch(request, dispatchSignal), operationSignal);
+        this.requestTasks.add(task);
+        try {
+            return await task;
+        }
+        catch (error) {
+            if (signal?.aborted === true) {
+                throw backendError("request-cancelled", 499, `Server plugin ${request.pluginId} backend request was cancelled`, error);
+            }
+            if (this.channelsAreShuttingDown())
+                throw requestShutdownError(request.pluginId, error);
+            if (error instanceof PluginBackendTimeoutError) {
+                throw backendError("request-timeout", 504, boundedErrorMessage(error), error);
+            }
+            throw error;
+        }
+        finally {
+            this.requestTasks.delete(task);
+        }
+    }
+    reserveChannel(request) {
+        if (this.channelsAreShuttingDown())
+            throw channelError("shutdown", 1012, "Plugin backend channels are shutting down");
+        if (!isPiWebPluginId(request.pluginId))
+            throw channelError("inactive-plugin", 1008, `Server plugin is not active: ${request.pluginId}`);
+        if (request.projectId === "" || request.workspaceId === "") {
+            throw channelError("workspace-not-found", 1008, `Workspace not found for server plugin ${request.pluginId} channel`);
+        }
+        const pluginCount = this.channelsByPlugin.get(request.pluginId) ?? 0;
+        const scopeKey = channelScopeKey(request.pluginId, request.projectId, request.workspaceId);
+        const scopeCount = this.channelsByPluginWorkspace.get(scopeKey) ?? 0;
+        if (this.channelAdmissionCount >= this.channelMaxTotal || pluginCount >= this.channelMaxPerPlugin || scopeCount >= this.channelMaxPerPluginWorkspace) {
+            throw channelError("admission-denied", 1013, `Server plugin ${request.pluginId} channel admission limit was reached`);
+        }
+        this.channelAdmissionCount += 1;
+        this.channelsByPlugin.set(request.pluginId, pluginCount + 1);
+        this.channelsByPluginWorkspace.set(scopeKey, scopeCount + 1);
+        const admission = new ManagedPluginBackendChannelAdmission(request, () => {
+            this.channelAdmissions.delete(admission);
+            this.channelAdmissionCount -= 1;
+            decrementCount(this.channelsByPlugin, request.pluginId);
+            decrementCount(this.channelsByPluginWorkspace, scopeKey);
+        });
+        this.channelAdmissions.add(admission);
+        return admission;
+    }
+    async openChannel(request, transport, signal, reservedAdmission) {
+        if (this.channelsAreShuttingDown())
+            throw channelError("shutdown", 1012, "Plugin backend channels are shutting down");
+        const pluginId = parsePluginId(request.pluginId);
+        const operation = parseOperation(request.operation);
+        const moduleRevision = parseRevision(request.moduleRevision, operation);
+        const input = parseInput(request.input, pluginId, operation, "channel open input");
+        const contribution = this.contributions.find((candidate) => candidate.pluginId === pluginId);
+        const openChannel = contribution?.backend.openChannel?.bind(contribution.backend);
+        if (contribution === undefined || openChannel === undefined) {
+            throw channelError("channel-unavailable", 1008, `Server plugin ${pluginId} does not expose channel operation ${operation}`);
+        }
+        if (contribution.moduleRevision !== moduleRevision) {
+            throw channelError("stale-plugin-revision", 1008, `Server plugin ${pluginId} backend revision is stale for channel operation ${operation}; reload after the session daemon restarts`);
+        }
+        const admission = reservedAdmission === undefined
+            ? this.reserveChannel({ pluginId, projectId: request.project.id, workspaceId: request.workspaceId })
+            : requireManagedChannelAdmission(reservedAdmission, { pluginId, projectId: request.project.id, workspaceId: request.workspaceId });
+        const releaseAdmission = () => { admission.release(); };
+        const releaseAdmissionOnManagedClose = reservedAdmission === undefined;
+        const lifetimeController = new AbortController();
+        this.openingChannelControllers.add(lifetimeController);
+        let resolveOpeningTask = () => undefined;
+        const openingTask = new Promise((resolve) => { resolveOpeningTask = resolve; });
+        this.openingChannelTasks.add(openingTask);
+        const finishOpeningTask = () => {
+            this.openingChannelControllers.delete(lifetimeController);
+            this.openingChannelTasks.delete(openingTask);
+            resolveOpeningTask();
+        };
+        const abortFromCaller = () => {
+            if (!lifetimeController.signal.aborted)
+                lifetimeController.abort(abortError(signal ?? lifetimeController.signal));
+        };
+        if (signal?.aborted === true)
+            abortFromCaller();
+        else
+            signal?.addEventListener("abort", abortFromCaller, { once: true });
+        let managed;
+        let openingChannel;
+        let sendFailure;
+        const send = (data) => {
+            if (lifetimeController.signal.aborted)
+                throw channelError("channel-closed", 1008, `Server plugin ${pluginId} channel ${operation} is closed`);
+            try {
+                const cloned = cloneBoundedPluginBackendJson(data, `Server plugin ${pluginId} channel ${operation} data`, PLUGIN_BACKEND_CHANNEL_DATA_JSON_MAX_BYTES);
+                transport.send(cloned);
+            }
+            catch (error) {
+                const failure = error instanceof Error ? error : new Error(String(error));
+                sendFailure = failure;
+                if (managed !== undefined) {
+                    void managed.fail("send-failed", `Server plugin ${pluginId} channel ${operation} send failed: ${boundedErrorMessage(failure)}`, 1011).catch(() => undefined);
+                }
+                throw failure;
+            }
+        };
+        try {
+            const channel = await runBoundedPluginBackendOperation(pluginId, `channel ${operation} open`, this.channelOpenTimeoutMs, async (openSignal) => {
+                const { project, workspace } = await resolveDirectScope(this.options.workspaces, request, pluginId, operation, openSignal);
+                const context = Object.freeze({
+                    project,
+                    workspace,
+                    operation,
+                    input,
+                    signal: lifetimeController.signal,
+                    send,
+                });
+                openingChannel = Promise.resolve().then(() => openChannel(context));
+                return await openingChannel;
+            }, lifetimeController.signal);
+            if (sendFailure !== undefined)
+                throw sendFailure;
+            managed = new ManagedPluginBackendChannel({
+                pluginId,
+                workspaceId: request.workspaceId,
+                operation,
+                channel,
+                transport,
+                lifetimeController,
+                callbackTimeoutMs: this.channelCallbackTimeoutMs,
+                lifetimeMs: this.channelLifetimeMs,
+                onReleased: (released) => {
+                    this.channels.delete(released);
+                    if (releaseAdmissionOnManagedClose)
+                        releaseAdmission();
+                    signal?.removeEventListener("abort", abortFromCaller);
+                },
+                onCleanupFailure: (error) => {
+                    this.options.logger?.error({ err: error, pluginId, operation }, "plugin backend channel cleanup failed");
+                },
+            });
+            finishOpeningTask();
+            this.channels.add(managed);
+            return managed;
+        }
+        catch (error) {
+            signal?.removeEventListener("abort", abortFromCaller);
+            if (!lifetimeController.signal.aborted)
+                lifetimeController.abort(error);
+            // A route-provided reservation remains tied to its physical socket; the
+            // route releases it only after attributed teardown completes.
+            if (reservedAdmission === undefined)
+                releaseAdmission();
+            if (openingChannel !== undefined) {
+                const cleanup = openingChannel.then(async (channel) => {
+                    await closeUnpublishedChannel(channel, pluginId, operation, this.channelCallbackTimeoutMs, (callback) => { this.openingChannelCleanup.track(callback); });
+                }).catch((cleanupError) => {
+                    this.options.logger?.error({ err: cleanupError, pluginId, operation }, "unpublished plugin backend channel cleanup failed");
+                });
+                this.openingChannelCleanup.track(cleanup);
+            }
+            // Let shutdown snapshot the cleanup task only after this failed opening
+            // has either registered its late-result cleanup or proved none can run.
+            finishOpeningTask();
+            if (error instanceof PluginBackendChannelError)
+                throw error;
+            if (error instanceof PluginBackendTimeoutError) {
+                throw channelError("open-timeout", 1011, boundedErrorMessage(error), error);
+            }
+            if (this.channelsAreShuttingDown()) {
+                throw channelError("shutdown", 1012, `Server plugin ${pluginId} channel ${operation} was interrupted by shutdown`, error);
+            }
+            if (signal?.aborted === true) {
+                throw channelError("channel-closed", 1008, `Server plugin ${pluginId} channel ${operation} was cancelled`, error);
+            }
+            throw channelError("open-failed", 1011, `Server plugin ${pluginId} channel ${operation} failed to open: ${boundedErrorMessage(error)}`, error);
+        }
+    }
+    closeAll(reason = "Session daemon shutdown") {
+        this.closePromise ??= this.performCloseAll(reason);
+        return this.closePromise;
+    }
+    async performCloseAll(reason) {
+        if (!this.shutdown.signal.aborted)
+            this.shutdown.abort(new DOMException(reason, "AbortError"));
+        const admissions = [...this.channelAdmissions];
+        for (const admission of admissions)
+            admission.abort(reason);
+        for (const controller of this.openingChannelControllers) {
+            if (!controller.signal.aborted)
+                controller.abort(new DOMException(reason, "AbortError"));
+        }
+        await Promise.allSettled([...this.requestTasks, ...this.openingChannelTasks]);
+        const channels = [...this.channels];
+        const results = await Promise.allSettled([
+            this.requestCallbacks.waitForSettled(this.callbackTimeoutMs, "Plugin backend request callbacks"),
+            // Allow a late open, its bounded close invocation, and one final
+            // cooperative settlement window after the close signal aborts.
+            this.openingChannelCleanup.waitForSettled(this.channelOpenTimeoutMs + (2 * this.channelCallbackTimeoutMs), "Plugin backend abandoned channel cleanup callbacks"),
+            ...channels.map(async (channel) => {
+                await channel.fail("shutdown", reason, 1012);
+            }),
+        ]);
+        const failures = [];
+        for (const result of results) {
+            if (result.status === "rejected") {
+                const reason = result.reason;
+                failures.push(reason);
+            }
+        }
+        await Promise.all(admissions.map(async (admission) => {
+            try {
+                await waitForPromise(admission.released, PLUGIN_BACKEND_CHANNEL_CALLBACK_TIMEOUT_MS + (2 * PLUGIN_BACKEND_CHANNEL_TEARDOWN_TIMEOUT_MS), "Plugin backend channel admission teardown");
+            }
+            catch (error) {
+                // Do not counterfeit teardown by dropping admission while a physical
+                // owner has not confirmed close; shutdown reports the bounded failure.
+                failures.push(error);
+            }
+        }));
+        if (failures.length !== 0)
+            throw new AggregateError(failures, "One or more plugin backend channels failed to close");
+    }
+    activeChannelCount() {
+        return this.channelAdmissionCount;
+    }
+    channelsAreShuttingDown() {
+        return this.shutdown.signal.aborted;
+    }
+    async dispatch(request, dispatchSignal) {
+        const pluginId = parsePluginId(request.pluginId);
+        const operation = parseOperation(request.operation);
+        const moduleRevision = parseRevision(request.moduleRevision, operation);
+        const input = parseInput(request.input, pluginId, operation);
+        const contribution = this.contributions.find((candidate) => candidate.pluginId === pluginId);
+        if (contribution === undefined) {
+            throw backendError("inactive-plugin", 409, `Server plugin ${pluginId} does not expose a paired backend for operation ${operation}`);
+        }
+        if (contribution.moduleRevision !== moduleRevision) {
+            throw backendError("stale-plugin-revision", 409, `Server plugin ${pluginId} backend revision is stale for operation ${operation}; reload after the session daemon restarts`);
+        }
+        const pairedRequest = contribution.backend.request?.bind(contribution.backend);
+        if (pairedRequest === undefined) {
+            throw backendError("operation-unavailable", 501, `Server plugin ${pluginId} does not expose paired request operation ${operation}`);
+        }
+        if (request.workspaceId === "") {
+            throw backendError("workspace-not-found", 404, `Workspace not found for server plugin ${pluginId} operation ${operation}`);
+        }
+        const project = snapshotProject(request.project);
+        let target;
+        try {
+            const resolution = await this.options.workspaces.resolve(request.project, dispatchSignal);
+            target = resolution.workspaces.find((workspace) => workspace.id === request.workspaceId);
+        }
+        catch (error) {
+            if (dispatchSignal.aborted)
+                throw abortError(dispatchSignal);
+            throw backendError("resolution-failed", 502, `Server plugin ${pluginId} could not resolve workspace scope for operation ${operation}: ${boundedErrorMessage(error)}`, error);
+        }
+        if (target === undefined) {
+            throw backendError("workspace-not-found", 404, `Workspace ${request.workspaceId} is stale or unavailable for server plugin ${pluginId} operation ${operation}`);
+        }
+        let workspace;
+        try {
+            workspace = snapshotWorkspace(target, project.id);
+        }
+        catch (error) {
+            throw backendError("invalid-scope", 502, `Server plugin ${pluginId} received an invalid host workspace scope for operation ${operation}: ${boundedErrorMessage(error)}`, error);
+        }
+        const context = Object.freeze({
+            project,
+            workspace,
+            operation,
+            input,
+            signal: dispatchSignal,
+        });
+        let result;
+        try {
+            result = await runBoundedPluginBackendOperation(pluginId, operation, this.callbackTimeoutMs, (callbackSignal) => pairedRequest(Object.freeze({ ...context, signal: callbackSignal })), dispatchSignal, (callback) => { this.requestCallbacks.track(callback); });
+        }
+        catch (error) {
+            if (dispatchSignal.aborted)
+                throw abortError(dispatchSignal);
+            if (error instanceof PluginBackendTimeoutError) {
+                throw backendError("request-timeout", 504, boundedErrorMessage(error), error);
+            }
+            throw backendError("request-failed", 502, `Server plugin ${pluginId} operation ${operation} failed: ${boundedErrorMessage(error)}`, error);
+        }
+        try {
+            return cloneBoundedPluginBackendJson(result, `Server plugin ${pluginId} operation ${operation} result`, PLUGIN_BACKEND_RESPONSE_JSON_MAX_BYTES);
+        }
+        catch (error) {
+            throw backendError("invalid-result", 502, boundedErrorMessage(error), error);
+        }
+    }
+}
+class ManagedPluginBackendChannelAdmission {
+    constructor(request, onRelease) {
+        this.request = request;
+        this.onRelease = onRelease;
+        this.controller = new AbortController();
+        this.isReleased = false;
+        this.resolveReleased = () => undefined;
+        this.released = new Promise((resolve) => { this.resolveReleased = resolve; });
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    abort(reason) {
+        if (!this.controller.signal.aborted)
+            this.controller.abort(new DOMException(reason, "AbortError"));
+    }
+    release() {
+        if (this.isReleased)
+            return;
+        this.isReleased = true;
+        this.onRelease();
+        this.resolveReleased();
+    }
+}
+function requireManagedChannelAdmission(admission, expected) {
+    if (!(admission instanceof ManagedPluginBackendChannelAdmission)
+        || admission.request.pluginId !== expected.pluginId
+        || admission.request.projectId !== expected.projectId
+        || admission.request.workspaceId !== expected.workspaceId) {
+        throw channelError("admission-denied", 1013, `Server plugin ${expected.pluginId} channel admission reservation is invalid`);
+    }
+    if (admission.signal.aborted) {
+        throw channelError("shutdown", 1012, `Server plugin ${expected.pluginId} channel admission was cancelled`);
+    }
+    return admission;
+}
+class ManagedPluginBackendChannel {
+    constructor(options) {
+        this.options = options;
+        this.receiveCallbacks = new PluginCallbackDrain();
+        this.closeCallbacks = new PluginCallbackDrain();
+        this.failureSignalled = false;
+        this.pluginId = options.pluginId;
+        this.workspaceId = options.workspaceId;
+        this.lifetimeTimer = setTimeout(() => {
+            void this.fail("lifetime-expired", `Server plugin ${this.pluginId} channel ${options.operation} reached its maximum lifetime`, 1001).catch(() => undefined);
+        }, options.lifetimeMs);
+        this.lifetimeTimer.unref();
+        this.observePluginCompletion();
+    }
+    async receive(data) {
+        if (this.isClosed()) {
+            throw channelError("channel-closed", 1008, `Server plugin ${this.pluginId} channel ${this.options.operation} is closed`);
+        }
+        let cloned;
+        try {
+            cloned = cloneBoundedPluginBackendJson(data, `Server plugin ${this.pluginId} channel ${this.options.operation} data`, PLUGIN_BACKEND_CHANNEL_DATA_JSON_MAX_BYTES);
+        }
+        catch (error) {
+            throw channelError("invalid-input", 1008, boundedErrorMessage(error), error);
+        }
+        try {
+            await runBoundedPluginBackendOperation(this.pluginId, `channel ${this.options.operation} receive`, this.options.callbackTimeoutMs, (signal) => this.options.channel.receive(cloned, signal), this.options.lifetimeController.signal, (callback) => { this.receiveCallbacks.track(callback); });
+        }
+        catch (error) {
+            if (this.isClosed()) {
+                throw channelError("channel-closed", 1008, `Server plugin ${this.pluginId} channel ${this.options.operation} closed during receive`, error);
+            }
+            if (error instanceof PluginBackendTimeoutError) {
+                throw channelError("receive-timeout", 1011, boundedErrorMessage(error), error);
+            }
+            throw channelError("receive-failed", 1011, `Server plugin ${this.pluginId} channel ${this.options.operation} receive failed: ${boundedErrorMessage(error)}`, error);
+        }
+    }
+    isClosed() {
+        return this.closePromise !== undefined || this.options.lifetimeController.signal.aborted;
+    }
+    observePluginCompletion() {
+        const closed = this.options.channel.closed;
+        if (closed === undefined)
+            return;
+        void Promise.resolve(closed).then(async () => {
+            if (this.isClosed())
+                return;
+            const reason = "Plugin completed channel";
+            try {
+                await this.close(1000, reason);
+                await this.options.transport.close(1000, reason);
+            }
+            catch (error) {
+                await this.fail("channel-closed", `Server plugin ${this.pluginId} channel ${this.options.operation} completion cleanup failed: ${boundedErrorMessage(error)}`, 1011);
+            }
+        }, async (error) => {
+            if (this.isClosed())
+                return;
+            await this.fail("channel-closed", `Server plugin ${this.pluginId} channel ${this.options.operation} completion failed: ${boundedErrorMessage(error)}`, 1011);
+        }).catch((error) => {
+            this.options.onCleanupFailure(error);
+        });
+    }
+    close(code = 1000, reason = "Channel closed") {
+        this.closePromise ??= this.performClose(code, boundedPluginBackendChannelCloseReason(reason));
+        return this.closePromise;
+    }
+    async fail(code, message, closeCode) {
+        if (!this.failureSignalled) {
+            this.failureSignalled = true;
+            try {
+                this.options.transport.sendError(code, message);
+            }
+            catch {
+                // The transport may already be gone; cleanup and admission release remain authoritative.
+            }
+        }
+        try {
+            await this.close(closeCode, message);
+        }
+        finally {
+            try {
+                await this.options.transport.close(closeCode, boundedPluginBackendChannelCloseReason(message));
+            }
+            catch {
+                // Closing an already-disconnected transport is expected and does not change cleanup ownership.
+            }
+        }
+    }
+    async performClose(code, reason) {
+        clearTimeout(this.lifetimeTimer);
+        if (!this.options.lifetimeController.signal.aborted) {
+            this.options.lifetimeController.abort(new DOMException(reason || "Plugin backend channel closed", "AbortError"));
+        }
+        const failures = [];
+        try {
+            try {
+                await this.receiveCallbacks.waitForSettled(this.options.callbackTimeoutMs, `Server plugin ${this.pluginId} channel ${this.options.operation} receive callbacks`);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            const close = this.options.channel.close?.bind(this.options.channel);
+            if (close !== undefined) {
+                try {
+                    await runBoundedPluginBackendOperation(this.pluginId, `channel ${this.options.operation} close`, this.options.callbackTimeoutMs, (signal) => close(Object.freeze({ code, reason, signal })), undefined, (callback) => { this.closeCallbacks.track(callback); });
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                try {
+                    await this.closeCallbacks.waitForSettled(this.options.callbackTimeoutMs, `Server plugin ${this.pluginId} channel ${this.options.operation} close callbacks`);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+        }
+        finally {
+            this.options.onReleased(this);
+        }
+        if (failures.length !== 0) {
+            const failure = failures.length === 1
+                ? failures[0]
+                : new AggregateError(failures, `Server plugin ${this.pluginId} channel ${this.options.operation} cleanup failed`);
+            this.options.onCleanupFailure(failure);
+            throw channelError("close-failed", 1011, `Server plugin ${this.pluginId} channel ${this.options.operation} close failed: ${boundedErrorMessage(failure)}`, failure);
+        }
+    }
+}
+async function closeUnpublishedChannel(channel, pluginId, operation, callbackTimeoutMs, onCallbackStarted) {
+    const close = channel.close?.bind(channel);
+    if (close === undefined)
+        return;
+    await runBoundedPluginBackendOperation(pluginId, `channel ${operation} abandoned-open close`, callbackTimeoutMs, (signal) => close(Object.freeze({
+        code: 1011,
+        reason: "Channel open did not complete",
+        signal,
+    })), undefined, onCallbackStarted);
+}
+async function resolveDirectScope(workspaces, request, pluginId, operation, signal) {
+    if (request.workspaceId === "") {
+        throw channelError("workspace-not-found", 1008, `Workspace not found for server plugin ${pluginId} channel ${operation}`);
+    }
+    let project;
+    try {
+        project = snapshotProject(request.project);
+    }
+    catch (error) {
+        throw channelError("invalid-scope", 1011, boundedErrorMessage(error), error);
+    }
+    let target;
+    try {
+        const resolution = await workspaces.resolve(request.project, signal);
+        target = resolution.workspaces.find((workspace) => workspace.id === request.workspaceId);
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw abortError(signal);
+        throw channelError("resolution-failed", 1011, `Server plugin ${pluginId} could not resolve workspace scope for channel ${operation}: ${boundedErrorMessage(error)}`, error);
+    }
+    if (target === undefined) {
+        throw channelError("workspace-not-found", 1008, `Workspace ${request.workspaceId} is stale or unavailable for server plugin ${pluginId} channel ${operation}`);
+    }
+    try {
+        return { project, workspace: snapshotWorkspace(target, project.id) };
+    }
+    catch (error) {
+        throw channelError("invalid-scope", 1011, `Server plugin ${pluginId} received an invalid host workspace scope for channel ${operation}: ${boundedErrorMessage(error)}`, error);
+    }
+}
+function channelScopeKey(pluginId, projectId, workspaceId) {
+    return `${pluginId}\u0000${projectId}\u0000${workspaceId}`;
+}
+function decrementCount(map, key) {
+    const count = map.get(key);
+    if (count === undefined || count <= 1)
+        map.delete(key);
+    else
+        map.set(key, count - 1);
+}
+function channelError(code, closeCode, message, cause) {
+    return new PluginBackendChannelError(code, closeCode, message, cause === undefined ? {} : { cause });
+}
+function snapshotContributions(contributions) {
+    const sorted = [...contributions].sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+    for (let index = 1; index < sorted.length; index += 1) {
+        if (sorted[index - 1]?.pluginId === sorted[index]?.pluginId) {
+            throw new Error(`Duplicate paired plugin backend contribution: ${String(sorted[index]?.pluginId)}`);
+        }
+    }
+    return Object.freeze(sorted);
+}
+function parsePluginId(value) {
+    if (!isPiWebPluginId(value)) {
+        throw backendError("inactive-plugin", 409, `Server plugin is not active: ${value}`);
+    }
+    return value;
+}
+function parseOperation(value) {
+    try {
+        return requirePluginBackendOperation(value);
+    }
+    catch (error) {
+        throw backendError("invalid-operation", 400, boundedErrorMessage(error), error);
+    }
+}
+function parseRevision(value, operation) {
+    try {
+        return requirePluginBackendRevision(value);
+    }
+    catch (error) {
+        throw backendError("stale-plugin-revision", 409, `Plugin backend revision is unavailable for operation ${operation}: ${boundedErrorMessage(error)}`, error);
+    }
+}
+function parseInput(value, pluginId, operation, suffix = "input") {
+    try {
+        return cloneBoundedPluginBackendJson(value, `Server plugin ${pluginId} operation ${operation} ${suffix}`);
+    }
+    catch (error) {
+        throw backendError("invalid-input", 400, boundedErrorMessage(error), error);
+    }
+}
+function snapshotProject(project) {
+    if (typeof project.id !== "string" || project.id === "") {
+        throw backendError("invalid-scope", 500, "Project id must be a non-empty string");
+    }
+    if (typeof project.name !== "string" || project.name === "") {
+        throw backendError("invalid-scope", 500, "Project name must be a non-empty string");
+    }
+    if (!isAbsolute(project.path)) {
+        throw backendError("invalid-scope", 500, "Project path must be absolute");
+    }
+    return Object.freeze({ id: project.id, name: project.name, path: resolve(project.path) });
+}
+function snapshotWorkspace(workspace, projectId) {
+    if (workspace.id === "")
+        throw new Error("Workspace id must be non-empty");
+    if (workspace.projectId !== projectId)
+        throw new Error("Workspace project scope does not match the resolved project");
+    if (!isAbsolute(workspace.path))
+        throw new Error("Workspace path must be absolute");
+    if (workspace.label === "")
+        throw new Error("Workspace label must be non-empty");
+    const provider = workspace.provider === undefined ? undefined : snapshotProvider(workspace.provider);
+    return Object.freeze({
+        id: workspace.id,
+        projectId: workspace.projectId,
+        path: resolve(workspace.path),
+        label: workspace.label,
+        isMain: workspace.isMain,
+        ...(provider === undefined ? {} : { provider }),
+    });
+}
+function snapshotProvider(provider) {
+    if (!isPiWebPluginId(provider.pluginId))
+        throw new Error("Workspace provider plugin id is invalid");
+    const metadata = provider.metadata === undefined
+        ? undefined
+        : cloneJsonObject(provider.metadata, "Workspace provider public metadata");
+    return Object.freeze({
+        pluginId: provider.pluginId,
+        capabilities: Object.freeze({ ...provider.capabilities }),
+        ...(metadata === undefined ? {} : { metadata }),
+    });
+}
+function cloneJsonObject(value, label) {
+    const cloned = cloneBoundedPluginBackendJson(value, label);
+    if (!isJsonObject(cloned))
+        throw new Error(`${label} must be a JSON object`);
+    return cloned;
+}
+function isJsonObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function waitForPromise(operation, timeoutMs, label) {
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => { reject(new Error(`${label} timed out after ${String(timeoutMs)}ms`)); }, timeoutMs);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([operation, deadline]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+async function runBoundedPluginBackendOperation(pluginId, operation, timeoutMs, callback, parentSignal, onCallbackStarted) {
+    const controller = new AbortController();
+    const abortFromParent = () => {
+        if (parentSignal !== undefined && !controller.signal.aborted) {
+            controller.abort(abortError(parentSignal));
+        }
+    };
+    if (parentSignal?.aborted === true)
+        abortFromParent();
+    else
+        parentSignal?.addEventListener("abort", abortFromParent, { once: true });
+    const timeoutError = new PluginBackendTimeoutError(`Server plugin ${pluginId} operation ${operation} timed out after ${String(timeoutMs)}ms`);
+    const timeout = setTimeout(() => { controller.abort(timeoutError); }, timeoutMs);
+    timeout.unref();
+    const deadline = controller.signal.aborted
+        ? Promise.reject(abortError(controller.signal))
+        : new Promise((_resolve, rejectPromise) => {
+            controller.signal.addEventListener("abort", () => { rejectPromise(abortError(controller.signal)); }, { once: true });
+        });
+    const result = controller.signal.aborted
+        ? new Promise(() => { })
+        : Promise.resolve().then(() => callback(controller.signal));
+    if (!controller.signal.aborted)
+        onCallbackStarted?.(result);
+    try {
+        return await Promise.race([result, deadline]);
+    }
+    finally {
+        clearTimeout(timeout);
+        parentSignal?.removeEventListener("abort", abortFromParent);
+        if (!controller.signal.aborted) {
+            controller.abort(new DOMException("Plugin backend operation completed", "AbortError"));
+        }
+    }
+}
+function requestShutdownError(pluginId, cause) {
+    return backendError("shutdown", 503, `Server plugin ${pluginId} backend requests are shutting down`, cause);
+}
+function backendError(code, statusCode, message, cause) {
+    return new PluginBackendRequestError(code, statusCode, message, cause === undefined ? {} : { cause });
+}
+function abortError(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error("Plugin backend operation aborted", { cause: reason });
+}
+function positiveInteger(value, fallback, key) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved <= 0)
+        throw new Error(`${key} must be a positive integer`);
+    return resolved;
+}
+function boundedErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length <= 2_048 ? message : `${message.slice(0, 2_045)}...`;
+}
+class PluginBackendTimeoutError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "TimeoutError";
+    }
+}
+//# sourceMappingURL=pluginBackendRegistry.js.map