slotlock 0.2.0 → 0.5.0

package/metrics.js

@@ -0,0 +1,167 @@
+/** Call duration buckets, in seconds. */
+const BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+const REFUSAL_REASONS = [
+    'auth_refused',
+    'rate_limited',
+    'lookup_overflow',
+    'series_writes_busy',
+    'maintenance_busy',
+    'request_too_large',
+];
+const MAINTENANCE_COUNTS = [
+    'extended',
+    'conflicts',
+    'refused',
+    'pruned',
+    'zoneShifts',
+    'staleSources',
+    'noShows',
+    'waitlistOffers',
+];
+/** A label value: an operation, protocol or outcome code. Anything else is counted as `other`. */
+const LABEL = /^[a-z0-9_.]{1,64}$/;
+const label = (value) => (LABEL.test(value) ? value : 'other');
+const key = (labels) => JSON.stringify(Object.entries(labels));
+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(',')}}`;
+}
+class Counter {
+    name;
+    help;
+    values = new Map();
+    constructor(name, help) {
+        this.name = name;
+        this.help = help;
+    }
+    add(labels, amount = 1) {
+        const id = key(labels);
+        const current = this.values.get(id) ?? { labels, value: 0 };
+        current.value += amount;
+        this.values.set(id, current);
+    }
+    render(type = 'counter') {
+        const lines = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} ${type}`];
+        for (const { labels, value } of this.values.values()) {
+            lines.push(`${this.name}${formatLabels(labels)} ${value}`);
+        }
+        return lines;
+    }
+}
+class Histogram {
+    name;
+    help;
+    series = new Map();
+    constructor(name, help) {
+        this.name = name;
+        this.help = help;
+    }
+    observe(labels, seconds) {
+        const id = key(labels);
+        const current = this.series.get(id) ?? {
+            labels,
+            buckets: BUCKETS.map(() => 0),
+            sum: 0,
+            count: 0,
+        };
+        BUCKETS.forEach((bound, index) => {
+            if (seconds <= bound)
+                current.buckets[index] = (current.buckets[index] ?? 0) + 1;
+        });
+        current.sum += seconds;
+        current.count += 1;
+        this.series.set(id, current);
+    }
+    render() {
+        const lines = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} histogram`];
+        for (const { labels, buckets, sum, count } of this.series.values()) {
+            BUCKETS.forEach((bound, index) => {
+                lines.push(`${this.name}_bucket${formatLabels({ ...labels, le: String(bound) })} ${buckets[index]}`);
+            });
+            lines.push(`${this.name}_bucket${formatLabels({ ...labels, le: '+Inf' })} ${count}`);
+            lines.push(`${this.name}_sum${formatLabels(labels)} ${sum}`);
+            lines.push(`${this.name}_count${formatLabels(labels)} ${count}`);
+        }
+        return lines;
+    }
+}
+/** Counters for one server process, reset when it restarts (`slotlock_start_time_seconds`). */
+export function createSlotlockMetrics(info) {
+    const started = (info.now ?? Date.now)() / 1000;
+    const calls = new Counter('slotlock_calls_total', 'Agent and REST calls by protocol, operation and outcome (ok, a refusal code, or an HTTP status).');
+    const duration = new Histogram('slotlock_call_duration_seconds', 'How long agent and REST calls took, by protocol and operation.');
+    const confirmations = new Counter('slotlock_confirmations_total', 'Write confirmations asked of a person, by operation and outcome.');
+    const subscriptions = new Counter('slotlock_subscriptions_total', 'MCP subscriptions opened and closed, by outcome and the reason one closed.');
+    let open = 0;
+    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 deliveries = new Counter('slotlock_webhook_deliveries_total', 'Webhook changes delivered, and deliveries that failed and will be retried.');
+    return {
+        event(event) {
+            if (event.type === 'call' || event.type === 'rest') {
+                const protocol = event.type === 'rest' ? 'rest' : event.protocol;
+                const operation = label(event.operation);
+                const outcome = event.type === 'rest' ? String(event.status) : label(event.outcome);
+                calls.add({ protocol, operation, outcome });
+                duration.observe({ protocol, operation }, Math.max(0, event.durationMs) / 1000);
+            }
+            else if (event.type === 'confirmation') {
+                confirmations.add({ operation: label(event.operation), outcome: event.outcome });
+            }
+            else if (event.type === 'subscription') {
+                subscriptions.add({ outcome: event.outcome, reason: event.reason ?? 'none' });
+                open = Math.max(0, open + (event.outcome === 'opened' ? 1 : -1));
+            }
+        },
+        refusals(counts) {
+            for (const reason of REFUSAL_REASONS) {
+                const amount = counts[reason];
+                if (amount > 0)
+                    refused.add({ reason }, amount);
+            }
+        },
+        maintenance(result) {
+            passes.add({ capped: String(result.capped) });
+            for (const kind of MAINTENANCE_COUNTS) {
+                if (result[kind] > 0)
+                    upkeep.add({ kind }, result[kind]);
+            }
+        },
+        refusedScrape() {
+            refused.add({ reason: 'metrics_auth_refused' });
+        },
+        webhooks(result) {
+            if (result.delivered > 0)
+                deliveries.add({ result: 'delivered' }, result.delivered);
+            if (result.failed > 0)
+                deliveries.add({ result: 'failed' }, result.failed);
+        },
+        render() {
+            const lines = [
+                '# HELP slotlock_build_info The Slotlock version and tz database the server runs.',
+                '# TYPE slotlock_build_info gauge',
+                `slotlock_build_info${formatLabels({ version: info.version, tzdata: info.tzdata ?? 'unknown' })} 1`,
+                '# HELP slotlock_start_time_seconds When the server started, in seconds since the epoch.',
+                '# TYPE slotlock_start_time_seconds gauge',
+                `slotlock_start_time_seconds ${started}`,
+                '# HELP slotlock_subscriptions_open MCP subscriptions open now.',
+                '# TYPE slotlock_subscriptions_open gauge',
+                `slotlock_subscriptions_open ${open}`,
+                ...calls.render(),
+                ...duration.render(),
+                ...confirmations.render(),
+                ...subscriptions.render(),
+                ...refused.render(),
+                ...passes.render(),
+                ...upkeep.render(),
+                ...deliveries.render(),
+            ];
+            return `${lines.join('\n')}\n`;
+        },
+    };
+}

package/node-server.d.ts

@@ -1,9 +1,17 @@
 /// <reference types="node" preserve="true" />
 import { type Server } from 'node:http';
 export type SlotlockNodeServerErrorPhase = 'client' | 'listen' | 'request' | 'server' | 'shutdown';
+/** 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.
+     */
+    remoteAddress?: string;
+}
 /** The narrow Fetch-compatible boundary returned by `createSlotlockAgentServer`. */
 export interface SlotlockNodeServerFetchTarget {
-    fetch(request: Request): Promise<Response>;
+    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.

package/node-server.js

@@ -137,8 +137,9 @@ function toWebRequest(request, requestOrigin, signal) {
     }
     // 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.
     const path = target.split(/[?#]/, 1)[0] ?? '';
-    if (path.split('/').some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment))) {
+    if (path.split(/[\\/]/).some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment))) {
         throw new Error('invalid_request_target');
     }
     const url = new URL(target, requestOrigin);
@@ -281,7 +282,11 @@ export function createSlotlockNodeServer(target, options) {
             timeout.unref();
         });
         try {
-            const outcome = await Promise.race([target.fetch(webRequest), handlerTimeout]);
+            const connection = {};
+            if (request.socket.remoteAddress !== undefined) {
+                connection.remoteAddress = request.socket.remoteAddress;
+            }
+            const outcome = await Promise.race([target.fetch(webRequest, connection), handlerTimeout]);
             if (outcome === HANDLER_TIMEOUT) {
                 controller.abort(abortReason('handler_timeout'));
                 safeReport(config.onError, new Error('handler_timeout'), 'request');