slotlock 0.6.2 → 0.7.0

package/mcp-modern.js

@@ -1,9 +1,8 @@
 import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
 /*
- * MCP 2026-07-28 wire mechanics for the Slotlock agent server: the per-request `_meta` envelope, the
- * Streamable HTTP request headers, the sealed multi-round-trip `requestState`, SSE framing and W3C
- * trace context. Which method does what — authorization, dispatch, results — stays in
- * agent-server.ts, the orchestration owner.
+ * MCP 2026-07-28 wire mechanics: the per-request `_meta` envelope, Streamable HTTP headers, sealed
+ * `requestState`, SSE framing and W3C trace context. Authorization, dispatch and results stay in
+ * agent-server.ts.
  */
 export const MCP_META_PROTOCOL_VERSION = 'io.modelcontextprotocol/protocolVersion';
 const MCP_META_CLIENT_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
@@ -23,16 +22,15 @@ const MCP_NAMED_METHODS = new Map([
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-// RFC 9110 field value: visible ASCII, space and horizontal tab. Anything else must arrive in the
-// `=?base64?…?=` sentinel (Streamable HTTP §Value Encoding).
+// RFC 9110 field value: visible ASCII, space and tab; anything else must use the `=?base64?…?=`
+// sentinel (Streamable HTTP §Value Encoding).
 const PLAIN_HEADER_VALUE = /^[\x20-\x7E\t]*$/;
 const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 const BASE64_SENTINEL_PREFIX = '=?base64?';
 const BASE64_SENTINEL_SUFFIX = '?=';
 /**
- * The value an `Mcp-Name` (or `Mcp-Param-*`) header stands for, decoded from the Base64 sentinel when
- * used; `null` when it is malformed: bad Base64, invalid UTF-8, or raw characters outside the
- * header-safe set.
+ * The value an `Mcp-Name` or `Mcp-Param-*` header stands for, Base64-sentinel decoded when used;
+ * `null` when malformed.
  */
 function decodeMcpHeaderValue(value) {
     if (value.length >= BASE64_SENTINEL_PREFIX.length + BASE64_SENTINEL_SUFFIX.length &&
@@ -51,11 +49,10 @@ function decodeMcpHeaderValue(value) {
     return PLAIN_HEADER_VALUE.test(value) ? value : null;
 }
 /**
- * Validate a 2026-07-28 request's `_meta` envelope and the HTTP headers that mirror its body, in the
- * specification's order: the required `_meta` fields (-32602, basic §_meta), `MCP-Protocol-Version`
- * against the body (-32020), a revision the server implements (-32022, basic/versioning), then
- * `Mcp-Method` and `Mcp-Name` against the body, the latter after Base64-sentinel decoding (-32020,
- * streamable-http §Server Validation). Every refusal is HTTP 400.
+ * Validate a 2026-07-28 request's `_meta` envelope and the headers mirroring its body, in the
+ * specification's order: required `_meta` fields (-32602), `MCP-Protocol-Version` against the body
+ * (-32020), a supported revision (-32022), then `Mcp-Method` and `Mcp-Name` against the body
+ * (-32020). Every refusal is HTTP 400.
  */
 export function checkModernMcpRequest(args) {
     const invalid = (message) => ({ ok: false, status: 400, code: -32602, message });
@@ -139,8 +136,8 @@ export function stateSecrets(secrets) {
     });
 }
 /**
- * Seal a JSON payload for a client to carry and echo: `v1.<payload>.<HMAC-SHA256>`, both base64url.
- * It is integrity-protected, not encrypted, so it must never hold anything the client may not see.
+ * Seal a JSON payload for a client to echo: `v1.<payload>.<HMAC-SHA256>`, base64url.
+ * Integrity-protected, not encrypted: never put anything the client may not see in it.
  */
 export function sealRequestState(key, payload) {
     const body = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
@@ -148,8 +145,8 @@ export function sealRequestState(key, payload) {
     return `${STATE_VERSION}.${body}.${mac}`;
 }
 /**
- * The payload of a state this server sealed with any of `keys`, and the key that verified it; `null`
- * for anything else. The MAC is checked in constant time before the payload is parsed.
+ * The payload of a state this server sealed with any of `keys`, and the verifying key; `null`
+ * otherwise. The MAC is checked in constant time before parsing.
  */
 export function openRequestState(keys, state) {
     if (typeof state !== 'string' || state.length > MAX_REQUEST_STATE_LENGTH)
@@ -163,8 +160,8 @@ export function openRequestState(keys, state) {
         !BASE64URL.test(mac)) {
         return null;
     }
-    // Compared as text: decoding drops the two spare bits of the last character, so three other
-    // spellings of the same MAC would pass.
+    // Compared as text: decoding drops the last character's spare bits, so other spellings of the
+    // same MAC would pass.
     const given = Buffer.from(mac);
     for (const key of keys) {
         const expected = Buffer.from(createHmac('sha256', key).update(`${STATE_MAC_CONTEXT}.${body}`).digest('base64url'));
@@ -196,9 +193,9 @@ const SSE_KEEP_ALIVE = encoder.encode(':\n\n');
 /** Messages a reader may leave unread before the stream counts it as gone. */
 const MAX_UNREAD_EVENTS = 256;
 /**
- * An SSE response (streamable-http §Receiving Messages): never cached, not buffered by a reverse
- * proxy (`X-Accel-Buffering: no`). `onCancel` runs once when the reader goes away first — the client
- * closed the stream, which on HTTP is how it cancels the request.
+ * An SSE response (streamable-http §Receiving Messages): uncached and unbuffered by proxies
+ * (`X-Accel-Buffering: no`). `onCancel` runs once if the reader leaves first, which is how an HTTP
+ * client cancels.
  */
 export function openMcpEventStream(onCancel) {
     let open = true;
@@ -266,10 +263,9 @@ function validTraceparent(value) {
         parentId !== '0'.repeat(16));
 }
 /**
- * Trace context from the request's `_meta` (MCP reserves `traceparent`, `tracestate` and `baggage`
- * there) or, when `_meta` has none, from the HTTP headers of the same names. One source only, never
- * a mix; an invalid `traceparent` discards the context, and an invalid `tracestate` or `baggage` is
- * dropped on its own (W3C Trace Context §3.3, Baggage §3.3).
+ * Trace context from `_meta` (MCP reserves `traceparent`, `tracestate` and `baggage` there) or, if
+ * absent, the HTTP headers; never a mix. An invalid `traceparent` discards it all; an invalid
+ * `tracestate` or `baggage` is dropped alone (W3C Trace Context §3.3, Baggage §3.3).
  */
 export function traceContextFrom(meta, headers) {
     const fromMeta = typeof meta?.traceparent === 'string';

package/metrics.d.ts

@@ -2,6 +2,8 @@ import type { SlotlockAgentServerEvent } from './agent-server.js';
 import type { SlotlockMaintenanceResult } from './maintenance.js';
 import type { SlotlockRefusalCounts } from './rate-limit.js';
 import type { SlotlockWebhookPassResult } from './webhooks.js';
+/** A metric's labels, by name. */
+export type Labels = Readonly<Record<string, string>>;
 export interface SlotlockMetrics {
     /** Count what the agent server reports (its `onEvent`). */
     event(event: SlotlockAgentServerEvent): void;
@@ -13,8 +15,47 @@ export interface SlotlockMetrics {
     webhooks(result: SlotlockWebhookPassResult): void;
     /** Count a scrape refused for its credential. */
     refusedScrape(): void;
+    /**
+     * Count an authenticated request by the integrator its `Slotlock-Client` field names (RFC 0003
+     * P5): a name from the deployment's known list, `other` or `none` (slotlockClientLabel).
+     */
+    client(name: string): void;
     /** Everything counted so far, as a scrape answers it. */
     render(): string;
+    /** Everything counted so far, as data: for an OpenTelemetry metrics export (otel.ts). */
+    collect(): SlotlockMetricsSnapshot;
+}
+/** The counters and histograms of one server since it started (cumulative). */
+export interface SlotlockMetricsSnapshot {
+    startedAtMs: number;
+    counters: {
+        name: string;
+        help: string;
+        points: {
+            labels: Labels;
+            value: number;
+        }[];
+    }[];
+    histograms: {
+        name: string;
+        help: string;
+        /** Upper bounds, in seconds; each point's buckets count what fell at or under each one. */
+        bounds: readonly number[];
+        points: {
+            labels: Labels;
+            cumulative: number[];
+            sum: number;
+            count: number;
+        }[];
+    }[];
+    gauges: {
+        name: string;
+        help: string;
+        points: {
+            labels: Labels;
+            value: number;
+        }[];
+    }[];
 }
 /** Counters for one server process, reset when it restarts (`slotlock_start_time_seconds`). */
 export declare function createSlotlockMetrics(info: {

package/metrics.js

@@ -7,6 +7,7 @@ const REFUSAL_REASONS = [
     'series_writes_busy',
     'maintenance_busy',
     'request_too_large',
+    'quota_exceeded',
 ];
 const MAINTENANCE_COUNTS = [
     'extended',
@@ -17,6 +18,7 @@ const MAINTENANCE_COUNTS = [
     'staleSources',
     'noShows',
     'waitlistOffers',
+    'approvalsExpired',
 ];
 /** A label value: an operation, protocol or outcome code. Anything else is counted as `other`. */
 const LABEL = /^[a-z0-9_.]{1,64}$/;
@@ -26,7 +28,6 @@ function formatLabels(labels) {
     const entries = Object.entries(labels);
     if (entries.length === 0)
         return '';
-    // Label values are from LABEL's set or the version strings below: escaped anyway.
     const escaped = entries.map(([name, value]) => `${name}="${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n')}"`);
     return `{${escaped.join(',')}}`;
 }
@@ -44,6 +45,9 @@ class Counter {
         current.value += amount;
         this.values.set(id, current);
     }
+    points() {
+        return [...this.values.values()].map(({ labels, value }) => ({ labels, value }));
+    }
     render(type = 'counter') {
         const lines = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} ${type}`];
         for (const { labels, value } of this.values.values()) {
@@ -76,6 +80,9 @@ class Histogram {
         current.count += 1;
         this.series.set(id, current);
     }
+    points() {
+        return [...this.series.values()].map(({ labels, buckets, sum, count }) => ({ labels, cumulative: [...buckets], sum, count }));
+    }
     render() {
         const lines = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} histogram`];
         for (const { labels, buckets, sum, count } of this.series.values()) {
@@ -100,6 +107,7 @@ export function createSlotlockMetrics(info) {
     const refused = new Counter('slotlock_refusals_total', 'Requests refused before they ran, by reason.');
     const passes = new Counter('slotlock_maintenance_passes_total', 'Maintenance passes, by whether one was capped.');
     const upkeep = new Counter('slotlock_maintenance_items_total', 'What maintenance did, by kind: series extended, holds pruned, no-shows released, waitlist offers made, and so on.');
+    const clients = new Counter('slotlock_requests_by_client_total', 'Authenticated requests by the integrator their Slotlock-Client field names (known ones, other or none).');
     const deliveries = new Counter('slotlock_webhook_deliveries_total', 'Webhook changes delivered, and deliveries that failed and will be retried.');
     return {
         event(event) {
@@ -135,6 +143,9 @@ export function createSlotlockMetrics(info) {
         refusedScrape() {
             refused.add({ reason: 'metrics_auth_refused' });
         },
+        client(name) {
+            clients.add({ client: label(name) });
+        },
         webhooks(result) {
             if (result.delivered > 0)
                 deliveries.add({ result: 'delivered' }, result.delivered);
@@ -160,8 +171,18 @@ export function createSlotlockMetrics(info) {
                 ...passes.render(),
                 ...upkeep.render(),
                 ...deliveries.render(),
+                ...clients.render(),
             ];
             return `${lines.join('\n')}\n`;
         },
+        collect() {
+            const counter = (metric) => ({ name: metric.name, help: metric.help, points: metric.points() });
+            return {
+                startedAtMs: started * 1000,
+                counters: [calls, confirmations, subscriptions, refused, passes, upkeep, deliveries, clients].map(counter),
+                histograms: [{ name: duration.name, help: duration.help, bounds: BUCKETS, points: duration.points() }],
+                gauges: [{ name: 'slotlock_subscriptions_open', help: 'MCP subscriptions open now.', points: [{ labels: {}, value: open }] }],
+            };
+        },
     };
 }

package/node-server.d.ts

@@ -4,8 +4,8 @@ export type SlotlockNodeServerErrorPhase = 'client' | 'listen' | 'request' | 'se
 /** What the listener knows about a request's connection, beside the Request itself. */
 export interface SlotlockNodeServerConnection {
     /**
-     * The peer's address as the socket reports it (an IPv4 client of a dual-stack listener reads
-     * `::ffff:a.b.c.d`). Behind a proxy it is the proxy's; never taken from a request field.
+     * The peer's address as the socket reports it (`::ffff:a.b.c.d` for IPv4 on a dual-stack
+     * listener). Behind a proxy it is the proxy's; never taken from a request field.
      */
     remoteAddress?: string;
 }
@@ -13,15 +13,15 @@ export interface SlotlockNodeServerConnection {
 export interface SlotlockNodeServerFetchTarget {
     fetch(request: Request, connection?: SlotlockNodeServerConnection): Promise<Response>;
     /**
-     * Called once when `close()` begins, after the listener stops accepting connections, to end
-     * long-lived responses (MCP subscription streams) so they drain within the grace period.
+     * Called once when `close()` begins, after the listener stops accepting, to end long-lived
+     * responses (MCP subscription streams) within the grace period.
      */
     shutdown?(): Promise<void> | void;
 }
 export interface SlotlockNodeServerOptions {
     /**
-     * Canonical origin used to construct the Request passed to authentication and policy callbacks.
-     * It is explicit so an untrusted Host or forwarding header can never choose security context.
+     * Canonical origin for the Request passed to authentication and policy callbacks, explicit so an
+     * untrusted Host or forwarding header can never choose security context.
      */
     requestOrigin: string;
     handlerTimeoutMs?: number;
@@ -57,8 +57,8 @@ export interface SlotlockNodeServer {
     }): Promise<SlotlockNodeServerCloseResult>;
 }
 /**
- * Adapt the Fetch boundary returned by `createSlotlockAgentServer` to a hardened Node HTTP listener.
- * The listener is intentionally HTTP-only; public HTTPS termination and trusted proxy policy remain
- * deployment concerns, while Request identity always uses the explicit canonical `requestOrigin`.
+ * Adapt the Fetch boundary from `createSlotlockAgentServer` to a hardened Node HTTP listener.
+ * HTTP-only by design: TLS termination and proxy trust are deployment concerns, and Request
+ * identity always uses the explicit `requestOrigin`.
  */
 export declare function createSlotlockNodeServer(target: SlotlockNodeServerFetchTarget, options: SlotlockNodeServerOptions): SlotlockNodeServer;

package/node-server.js

@@ -75,16 +75,13 @@ function appendIncomingHeaders(request) {
     return headers;
 }
 /**
- * The request body as a web stream that a target may cancel, as it does a body over its size limit.
- * Cancelling a `Readable.toWeb` stream destroys the IncomingMessage: Node emits 'aborted', read
- * here as the client leaving, and the unread rest stays on the connection, which then holds
- * `close()` until it is forced. Cancelling this one only stops delivery; once the response is
- * written the rest is discarded as it arrives, as Node discards a body no handler reads, within
- * `requestTimeout`.
+ * The request body as a cancellable web stream. Cancelling a `Readable.toWeb` stream destroys the
+ * IncomingMessage (Node emits 'aborted') and leaves the unread rest on the connection, holding
+ * `close()` until forced. Cancelling this one only stops delivery; once the response is written the
+ * rest is discarded as it arrives, within `requestTimeout`.
  */
 function requestBody(request) {
     let controller;
-    // Once the stream is closed, errored or cancelled, what arrives is dropped.
     let settled = false;
     const stream = new ReadableStream({
         start(started) {
@@ -112,7 +109,7 @@ function requestBody(request) {
                 request.resume();
         },
         cancel() {
-            // Held until the response is written, so the client is not read from while it waits.
+            // Held until the response is written, so the client is not read from meanwhile.
             settled = true;
             request.pause();
         },
@@ -120,8 +117,7 @@ function requestBody(request) {
     return {
         stream,
         discard() {
-            // A target still reading a body it has already answered gets an error, not a read that
-            // never settles.
+            // A target still reading an answered body gets an error, not a read that never settles.
             if (!settled) {
                 settled = true;
                 controller?.error(abortReason('request_body_discarded'));
@@ -135,9 +131,9 @@ function toWebRequest(request, requestOrigin, signal) {
     if (!target.startsWith('/') || target.startsWith('//')) {
         throw new Error('invalid_request_target');
     }
-    // URL parsing resolves dot segments, `%2E` spellings included: `/v1/resources/%2E%2E/availability`
-    // would reach the target as `/v1/availability`, a path parameter of `..` naming another route.
-    // It also takes a backslash for a slash, so a segment ends at either.
+    // URL parsing resolves dot segments, `%2E` spellings included
+    // (`/v1/resources/%2E%2E/availability` would become `/v1/availability`), and treats a backslash
+    // as a slash.
     const path = target.split(/[?#]/, 1)[0] ?? '';
     if (path.split(/[\\/]/).some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment))) {
         throw new Error('invalid_request_target');
@@ -145,9 +141,8 @@ function toWebRequest(request, requestOrigin, signal) {
     const url = new URL(target, requestOrigin);
     if (url.origin !== requestOrigin)
         throw new Error('invalid_request_target');
-    // Node's fetch implementation requires `duplex: 'half'` for streamed request bodies, but the
-    // DOM RequestInit visible to workspace consumers does not declare that Node-only extension.
-    // Keep the cast at this adapter boundary; real-socket tests exercise the actual undici contract.
+    // Node's fetch needs `duplex: 'half'` for streamed bodies, which the DOM RequestInit does not
+    // declare; the cast stays at this boundary and real-socket tests cover undici's contract.
     const init = {
         method: request.method ?? 'GET',
         headers: appendIncomingHeaders(request),
@@ -163,7 +158,7 @@ function toWebRequest(request, requestOrigin, signal) {
         return { request: new Request(url, init), ...(body ? { body } : {}) };
     }
     catch (error) {
-        // A method the Fetch API forbids, say: nothing will read the body, so drop it as it arrives.
+        // A method the Fetch API forbids: nothing will read the body, so drop it.
         body?.discard();
         throw error;
     }
@@ -212,9 +207,9 @@ function formatListenerOrigin(host, port) {
     return `http://${host.includes(':') ? `[${host}]` : host}:${port}`;
 }
 /**
- * Adapt the Fetch boundary returned by `createSlotlockAgentServer` to a hardened Node HTTP listener.
- * The listener is intentionally HTTP-only; public HTTPS termination and trusted proxy policy remain
- * deployment concerns, while Request identity always uses the explicit canonical `requestOrigin`.
+ * Adapt the Fetch boundary from `createSlotlockAgentServer` to a hardened Node HTTP listener.
+ * HTTP-only by design: TLS termination and proxy trust are deployment concerns, and Request
+ * identity always uses the explicit `requestOrigin`.
  */
 export function createSlotlockNodeServer(target, options) {
     const requestTimeoutMs = boundedInteger('requestTimeoutMs', options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, 1, MAX_TIMEOUT_MS);
@@ -231,8 +226,8 @@ export function createSlotlockNodeServer(target, options) {
         config.onError = options.onError;
     const activeRequests = new Set();
     let state = 'new';
-    // Read through a function: inside a request handler TypeScript would keep the narrowing of its
-    // opening check, but `close()` can change the state while the handler awaits.
+    // A function, so TypeScript does not keep the narrowing across awaits: `close()` can change the
+    // state meanwhile.
     const closing = () => state === 'closing';
     let removeLifecycleAbort;
     /** Rejects a listen() still starting with `listen_aborted`; set while one is. */
@@ -241,8 +236,8 @@ export function createSlotlockNodeServer(target, options) {
     const server = createServer({
         headersTimeout: headersTimeoutMs,
         requestTimeout: requestTimeoutMs,
-        // Node enforces both only when it checks its connections (every 30 s by default), so a body
-        // trickled after its answer could outlast requestTimeout by that much.
+        // Node enforces both only when it checks connections (every 30 s by default), so a trickled
+        // body could outlast requestTimeout by that much.
         connectionsCheckingInterval: Math.min(DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS, headersTimeoutMs, requestTimeoutMs),
         keepAliveTimeout: boundedInteger('keepAliveTimeoutMs', options.keepAliveTimeoutMs ?? DEFAULT_KEEP_ALIVE_TIMEOUT_MS, 1, MAX_TIMEOUT_MS),
         maxHeaderSize: boundedInteger('maxHeaderBytes', options.maxHeaderBytes ?? DEFAULT_MAX_HEADER_BYTES, 1_024, MAX_HEADER_BYTES),
@@ -307,11 +302,9 @@ export function createSlotlockNodeServer(target, options) {
             if (timeout)
                 clearTimeout(timeout);
             activeRequests.delete(controller);
-            // The answer is written: what is left of a body the target did not read (one it refused as
-            // too large, say) is discarded as it arrives rather than held.
+            // The answer is written: discard what is left of an unread body as it arrives.
             if (!request.complete) {
                 body?.discard();
-                // The connection is idle only once that rest has arrived: close it then if shutting down.
                 request.once('end', () => {
                     setImmediate(() => {
                         if (closing())
@@ -319,8 +312,8 @@ export function createSlotlockNodeServer(target, options) {
                     });
                 });
             }
-            // A keep-alive connection whose response finished during shutdown would otherwise hold
-            // `server.close()` open until its idle timeout; Node closed only the idle ones at the start.
+            // Otherwise a keep-alive connection finishing during shutdown holds `server.close()` until
+            // its idle timeout.
             if (closing())
                 server.closeIdleConnections();
         }
@@ -341,9 +334,8 @@ export function createSlotlockNodeServer(target, options) {
             removeLifecycleAbort?.();
             removeLifecycleAbort = undefined;
             if (state === 'starting') {
-                // Closed before it was listening. Node abandons a listen whose server closes first, with
-                // neither 'listening' nor 'error', so the pending listen() is rejected here, as an aborted
-                // signal rejects it.
+                // Closed before listening: Node abandons such a listen with neither 'listening' nor
+                // 'error', so reject the pending listen() here.
                 state = 'closing';
                 cancelStartup?.();
                 await new Promise((resolve) => server.close(() => resolve()));
@@ -363,7 +355,7 @@ export function createSlotlockNodeServer(target, options) {
                 });
                 server.closeIdleConnections();
             });
-            // Not awaited: a slow or failing hook must not hold shutdown past its grace period.
+            // Not awaited: a slow hook must not hold shutdown past its grace period.
             void (async () => {
                 try {
                     await target.shutdown?.();
@@ -434,7 +426,6 @@ export function createSlotlockNodeServer(target, options) {
                 const onListening = () => {
                     cleanupStartup();
                     if (cancelled) {
-                        // close() came first; a listener that bound all the same goes with it.
                         server.close();
                         return;
                     }