@ni-c/mcp-hub 0.9.2 → 0.11.0

package/dist/subscriptions.js

@@ -0,0 +1,236 @@
+import { booleanEnv, nonNegativeIntegerEnv, positiveIntegerEnv } from './mcp-limits.js';
+/**
+ * Carrying a child's change notifications to the client that asked for them.
+ *
+ * On the 2026-07-28 revision a client opens a notification stream with
+ * `subscriptions/listen` and names the event types it wants. The state that
+ * makes this work is the open HTTP response, not a session table — which is the
+ * only reason a stateless gateway can carry it at all. It is the same property
+ * that made elicitation forwardable: nothing is remembered between requests
+ * that is not held by a socket somebody is still holding open.
+ *
+ * The SDK owns the downstream wire: acknowledgment first, per-stream filtering,
+ * `subscriptionId` stamping, teardown, keepalive. What this module owns is the
+ * half the SDK cannot know about — that behind one route sits a child process
+ * the hub may have put to sleep, and that several clients share it.
+ *
+ * Two consequences shape everything below:
+ *
+ * 1. The event bus is publish-only. It never reports which URIs a stream asked
+ *    for, so the hub reads the filter off the request itself and keeps its own
+ *    book. That book is what tells the upstream side which URIs to subscribe to.
+ * 2. One bus serves a whole route. A `publish` reaches every open stream on it,
+ *    not just the one that prompted it — so a resync meant for a client that
+ *    just connected also nudges the others. Harmless (they re-read a list they
+ *    already had) and damped by the debounce, but it is a real property and it
+ *    is documented rather than hidden.
+ */
+/** Global off switch, mirroring `MCP_ELICITATION`. */
+export const SUBSCRIPTIONS_ENABLED = booleanEnv('MCP_SUBSCRIPTIONS', true);
+/** Open listen streams one route will serve before refusing the next. */
+export const MAX_SUBSCRIPTIONS = positiveIntegerEnv('MCP_MAX_SUBSCRIPTIONS', 1024);
+/**
+ * URIs one `subscriptions/listen` filter may name.
+ *
+ * Every URI becomes an upstream subscription the hub has to hold and reconcile,
+ * so an unbounded list is a way to make the hub do unbounded work on one
+ * request. Well above what a resource picker produces, far below what a script
+ * could ask for.
+ */
+export const MAX_SUBSCRIPTION_URIS = positiveIntegerEnv('MCP_SUBSCRIPTION_MAX_URIS', 64);
+/** SSE comment-frame keepalive for listen streams; `0` disables it. */
+export const KEEPALIVE_MS = nonNegativeIntegerEnv('MCP_SUBSCRIPTION_KEEPALIVE_MS', 15_000);
+/**
+ * How long change events are collected before they are delivered.
+ *
+ * A child that rewrites its resource list in a loop would otherwise turn one
+ * upstream storm into one downstream storm per connected client. Within the
+ * window, repeats of the same event collapse to one — which is exactly what the
+ * notification means anyway: "read it again", not "here is what changed".
+ * `0` disables the window and delivers each event as it arrives.
+ */
+export const DEBOUNCE_MS = nonNegativeIntegerEnv('MCP_SUBSCRIPTION_DEBOUNCE_MS', 250);
+/**
+ * How long one listen stream may stay open; `0` lets it live as long as the
+ * socket does.
+ *
+ * This is a reaper for clients that go away without closing anything, not a
+ * protocol feature. The specification's graceful closure — answering the
+ * original request with a completion result before closing — is not reachable
+ * from here: the SDK owns the stream and exposes no hook for it. So the stream
+ * simply ends, which the client sees as the same unexpected disconnect it would
+ * see from an HTTP timeout, and reconnects. Spec-legal, and named as what it is
+ * rather than dressed up as the graceful variant.
+ */
+export const MAX_STREAM_MS = nonNegativeIntegerEnv('MCP_SUBSCRIPTION_MAX_MS', 30 * 60_000);
+/** True unless an operator said otherwise, globally or for this server. */
+export function subscriptionsAllowed(config) {
+    return SUBSCRIPTIONS_ENABLED && config.subscriptions !== 'off';
+}
+/** Whether a parsed request body is a `subscriptions/listen` call. */
+export function isListenRequest(body) {
+    if (Array.isArray(body))
+        return body.some(entry => isListenRequest(entry));
+    return typeof body === 'object' && body !== null && body.method === 'subscriptions/listen';
+}
+/**
+ * Reads the filter off a parsed request body.
+ *
+ * Deliberately forgiving: this is not the validator. The SDK parses the request
+ * properly a moment later and owns every error answer, so anything malformed
+ * here just yields an empty demand and is rejected downstream with the SDK's
+ * own message. Reading it early buys one thing only — knowing which URIs to
+ * hold upstream before the stream opens.
+ */
+export function parseListenFilter(body) {
+    const empty = {
+        toolsListChanged: false,
+        promptsListChanged: false,
+        resourcesListChanged: false,
+        resourceSubscriptions: []
+    };
+    if (Array.isArray(body)) {
+        // A batch may not contain a listen at all; if it does, take the first.
+        const listen = body.find(entry => isListenRequest(entry));
+        return listen ? parseListenFilter(listen) : empty;
+    }
+    if (typeof body !== 'object' || body === null)
+        return empty;
+    const params = body.params;
+    if (typeof params !== 'object' || params === null)
+        return empty;
+    const notifications = params.notifications;
+    if (typeof notifications !== 'object' || notifications === null)
+        return empty;
+    const filter = notifications;
+    const uris = Array.isArray(filter.resourceSubscriptions)
+        ? filter.resourceSubscriptions.filter((uri) => typeof uri === 'string')
+        : [];
+    return {
+        toolsListChanged: filter.toolsListChanged === true,
+        promptsListChanged: filter.promptsListChanged === true,
+        resourcesListChanged: filter.resourcesListChanged === true,
+        // Deduplicated here so the cap counts distinct resources, not repetitions
+        // of one, and so the upstream union below never holds the same URI twice.
+        resourceSubscriptions: [...new Set(uris)]
+    };
+}
+export class SubscriptionRegistry {
+    notifier;
+    options;
+    leases = new Map();
+    pending = new Map();
+    nextId = 1;
+    timer;
+    closed = false;
+    constructor(notifier, options = {}) {
+        this.notifier = notifier;
+        this.options = options;
+    }
+    /** Open listen streams on this route, for the `maxSubscriptions` ceiling. */
+    get size() {
+        return this.leases.size;
+    }
+    /** The union of every live lease. Empty when nobody is listening. */
+    demand() {
+        const uris = new Set();
+        let tools = false;
+        let prompts = false;
+        let resources = false;
+        for (const filter of this.leases.values()) {
+            tools ||= filter.toolsListChanged;
+            prompts ||= filter.promptsListChanged;
+            resources ||= filter.resourcesListChanged;
+            for (const uri of filter.resourceSubscriptions)
+                uris.add(uri);
+        }
+        return { toolsListChanged: tools, promptsListChanged: prompts, resourcesListChanged: resources, uris: [...uris] };
+    }
+    acquire(filter) {
+        const id = this.nextId++;
+        this.leases.set(id, filter);
+        this.options.onDemandChange?.();
+        return {
+            release: () => {
+                // Idempotent: the release is wired to both `finish` and `close` on the
+                // response, and a stream that ends normally fires both.
+                if (!this.leases.delete(id))
+                    return;
+                this.options.onDemandChange?.();
+            }
+        };
+    }
+    /** Hand one upstream change event to every stream that opted in. */
+    publish(event) {
+        if (this.closed)
+            return;
+        const debounceMs = this.options.debounceMs ?? DEBOUNCE_MS;
+        if (debounceMs <= 0) {
+            this.deliver(event);
+            return;
+        }
+        this.pending.set(event.kind === 'resource_updated' ? `${event.kind}:${event.uri}` : event.kind, event);
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => this.flush(), debounceMs);
+        // Never a reason to hold the process open for a coalescing window.
+        this.timer.unref();
+    }
+    /**
+     * Tell every listener to read everything it is watching again.
+     *
+     * Sent after a child wakes or restarts, because the hub held no upstream
+     * subscription while it was gone and cannot know what happened in the
+     * meantime. A `resources/updated` here does not claim the resource changed —
+     * it says "read it again", which is all the notification ever meant, and it
+     * is the only way to make the gap at the end of a nap recoverable rather than
+     * silent.
+     */
+    resync() {
+        const demand = this.demand();
+        if (demand.toolsListChanged)
+            this.publish({ kind: 'tools_list_changed' });
+        if (demand.promptsListChanged)
+            this.publish({ kind: 'prompts_list_changed' });
+        if (demand.resourcesListChanged)
+            this.publish({ kind: 'resources_list_changed' });
+        for (const uri of demand.uris)
+            this.publish({ kind: 'resource_updated', uri });
+    }
+    flush() {
+        this.timer = undefined;
+        const events = [...this.pending.values()];
+        this.pending.clear();
+        for (const event of events)
+            this.deliver(event);
+    }
+    deliver(event) {
+        if (this.closed)
+            return;
+        // No filtering here on purpose: the SDK delivers each event only to the
+        // streams whose filter asked for it. Publishing one nobody wants costs a
+        // function call and reaches no client.
+        switch (event.kind) {
+            case 'tools_list_changed':
+                this.notifier.toolsChanged();
+                return;
+            case 'prompts_list_changed':
+                this.notifier.promptsChanged();
+                return;
+            case 'resources_list_changed':
+                this.notifier.resourcesChanged();
+                return;
+            case 'resource_updated':
+                this.notifier.resourceUpdated(event.uri);
+                return;
+        }
+    }
+    close() {
+        this.closed = true;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.pending.clear();
+        this.leases.clear();
+    }
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/subscriptions.js.map

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