@miragon/pulse-widget-shell 0.0.0-stage → 0.21.0

package/dist/http-edge.test.js

@@ -0,0 +1,255 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_MAX_BODY_BYTES, describeHttpEdgePolicy, edgeRejection, hostRejection, IN_FLIGHT_BODY_MULTIPLE, installHttpEdgeGuard, jsonRpcErrorBody, originRejection, resolveHttpEdgePolicy, } from "./http-edge.js";
+const LOCAL = ["localhost", "127.0.0.1", "[::1]"];
+describe("resolveHttpEdgePolicy", () => {
+    it("defaults to localhost-class only, a 4 MiB cap, a 16 MiB in-flight budget and an open /metrics", () => {
+        expect(resolveHttpEdgePolicy({})).toEqual({
+            allowedHosts: LOCAL,
+            allowedOrigins: LOCAL,
+            maxBodyBytes: 4 * 1024 * 1024,
+            maxInFlightBodyBytes: 16 * 1024 * 1024,
+        });
+        expect(DEFAULT_MAX_BODY_BYTES).toBe(4194304);
+        expect(IN_FLIGHT_BODY_MULTIPLE).toBe(4);
+    });
+    it("scales the in-flight budget with MCP_MAX_BODY_BYTES", () => {
+        expect(resolveHttpEdgePolicy({ MCP_MAX_BODY_BYTES: "1000" }).maxInFlightBodyBytes).toBe(4000);
+    });
+    it("derives the host and the origin from MCP_URL", () => {
+        const policy = resolveHttpEdgePolicy({ MCP_URL: "https://MCP.example.com:8443/base" });
+        expect(policy.allowedHosts).toEqual([...LOCAL, "mcp.example.com"]);
+        expect(policy.allowedOrigins).toEqual([...LOCAL, "https://mcp.example.com:8443"]);
+    });
+    it("adds the comma lists, normalized and de-duplicated", () => {
+        const policy = resolveHttpEdgePolicy({
+            MCP_URL: "https://mcp.example.com",
+            MCP_ALLOWED_HOSTS: " Internal.svc:8400 , mcp.example.com,,https://gw.example.com/x ",
+            MCP_ALLOWED_ORIGINS: "https://App.example.com/, app2.example.com",
+        });
+        expect(policy.allowedHosts).toEqual([
+            ...LOCAL,
+            "mcp.example.com",
+            "internal.svc",
+            "gw.example.com",
+        ]);
+        expect(policy.allowedOrigins).toEqual([
+            ...LOCAL,
+            "https://mcp.example.com",
+            "https://app.example.com",
+            "app2.example.com",
+        ]);
+    });
+    it("treats * as an explicit opt-out of that check", () => {
+        const policy = resolveHttpEdgePolicy({ MCP_ALLOWED_HOSTS: "*", MCP_ALLOWED_ORIGINS: "a.com,*" });
+        expect(policy.allowedHosts).toBe("*");
+        expect(policy.allowedOrigins).toBe("*");
+    });
+    it("reads the body cap and the metrics token", () => {
+        const policy = resolveHttpEdgePolicy({
+            MCP_MAX_BODY_BYTES: " 1024 ",
+            MCP_METRICS_TOKEN: " s3cret ",
+        });
+        expect(policy.maxBodyBytes).toBe(1024);
+        expect(policy.metricsToken).toBe("s3cret");
+        expect(resolveHttpEdgePolicy({ MCP_METRICS_TOKEN: "  " })).not.toHaveProperty("metricsToken");
+    });
+    it.each([
+        [{ MCP_URL: "not a url" }, /MCP_URL "not a url" is not an absolute URL/],
+        [{ MCP_URL: "ftp://mcp.example.com" }, /must be an http\(s\) URL/],
+        [{ MCP_MAX_BODY_BYTES: "4MB" }, /MCP_MAX_BODY_BYTES "4MB" must be a positive integer/],
+        [{ MCP_MAX_BODY_BYTES: "0" }, /must be a positive integer/],
+        [{ MCP_MAX_BODY_BYTES: "1.5" }, /must be a positive integer/],
+        [{ MCP_ALLOWED_HOSTS: "bad host" }, /MCP_ALLOWED_HOSTS: "bad host" is not a hostname/],
+        [{ MCP_ALLOWED_ORIGINS: "https://" }, /MCP_ALLOWED_ORIGINS: "https:\/\/" is not an origin/],
+        [{ MCP_ALLOWED_ORIGINS: "data://x" }, /is not an origin/],
+    ])("fails the boot on %j", (env, message) => {
+        expect(() => resolveHttpEdgePolicy(env)).toThrow(message);
+    });
+});
+describe("describeHttpEdgePolicy", () => {
+    it("states hosts, origins, the cap and the metrics protection in one line", () => {
+        expect(describeHttpEdgePolicy(resolveHttpEdgePolicy({ MCP_URL: "https://mcp.example.com", MCP_METRICS_TOKEN: "t" }))).toBe("HTTP edge — hosts: localhost, 127.0.0.1, [::1], mcp.example.com; " +
+            "origins: localhost, 127.0.0.1, [::1], https://mcp.example.com; " +
+            "max body 4 MiB (16 MiB in flight); /metrics token-protected");
+        expect(describeHttpEdgePolicy(resolveHttpEdgePolicy({
+            MCP_ALLOWED_HOSTS: "*",
+            MCP_ALLOWED_ORIGINS: "*",
+            MCP_MAX_BODY_BYTES: "1572864",
+        }))).toBe("HTTP edge — hosts: any (validation off); origins: any (validation off); " +
+            "max body 1.5 MiB (6 MiB in flight); /metrics open");
+    });
+    it.each([
+        ["1048576", "max body 1 MiB (4 MiB in flight);"],
+        ["1024", "max body 1 KiB (4 KiB in flight);"],
+        ["2560", "max body 2.5 KiB (10 KiB in flight);"],
+        ["1023", "max body 1023 bytes (4 KiB in flight);"],
+        ["640", "max body 640 bytes (2.5 KiB in flight);"],
+        ["255", "max body 255 bytes (1020 bytes in flight);"],
+    ])("formats a %s-byte cap readably", (bytes, expected) => {
+        expect(describeHttpEdgePolicy(resolveHttpEdgePolicy({ MCP_MAX_BODY_BYTES: bytes }))).toContain(expected);
+    });
+});
+const policy = resolveHttpEdgePolicy({
+    MCP_URL: "https://mcp.example.com",
+    MCP_ALLOWED_ORIGINS: "https://app.example.com,tools.example.com",
+});
+describe("hostRejection", () => {
+    it.each([
+        "localhost",
+        "localhost:8400",
+        "127.0.0.1:1",
+        "[::1]:8400",
+        "mcp.example.com",
+        "MCP.EXAMPLE.COM:443",
+    ])("admits %s", (host) => {
+        expect(hostRejection(host, policy)).toBeUndefined();
+    });
+    it("rejects a foreign host (port-agnostic) and points at the remedy", () => {
+        const reason = hostRejection("attacker.example:8400", policy);
+        expect(reason).toContain('Host "attacker.example" is not allowed');
+        expect(reason).toContain("MCP_URL");
+        expect(reason).toContain("MCP_ALLOWED_HOSTS");
+        // An IP that happens to reach the server is still not "ours".
+        expect(hostRejection("10.0.0.7:8400", policy)).toBeDefined();
+    });
+    it("rejects a missing or unparsable Host", () => {
+        expect(hostRejection(undefined, policy)).toBe("missing Host header");
+        expect(hostRejection("", policy)).toBe("missing Host header");
+        expect(hostRejection("a b", policy)).toBe('invalid Host header "a b"');
+    });
+    it("admits anything when Host validation is off", () => {
+        expect(hostRejection("attacker.example", { ...policy, allowedHosts: "*" })).toBeUndefined();
+        expect(hostRejection(undefined, { ...policy, allowedHosts: "*" })).toBeUndefined();
+    });
+});
+describe("originRejection", () => {
+    it("admits requests without an Origin (non-browser MCP clients)", () => {
+        expect(originRejection(undefined, "POST", policy)).toBeUndefined();
+        expect(originRejection("", "POST", policy)).toBeUndefined();
+    });
+    it("skips the safe methods, whatever the origin", () => {
+        expect(originRejection("https://attacker.example", "GET", policy)).toBeUndefined();
+        expect(originRejection("null", "HEAD", policy)).toBeUndefined();
+    });
+    it.each([
+        "http://localhost:6274",
+        "https://127.0.0.1",
+        "http://[::1]:3000",
+        "https://mcp.example.com",
+        "https://app.example.com",
+        "http://tools.example.com:9000",
+    ])("admits %s", (origin) => {
+        expect(originRejection(origin, "POST", policy)).toBeUndefined();
+    });
+    it.each([
+        "https://attacker.example",
+        "http://app.example.com", // exact origin: scheme counts
+        "https://app.example.com:8443", // and so does the port
+        "https://mcp.example.com.attacker.example",
+        "null",
+        "not a url",
+    ])("rejects %s on a POST", (origin) => {
+        const reason = originRejection(origin, "POST", policy);
+        expect(reason).toContain(`Origin "${origin}" is not allowed`);
+        expect(reason).toContain("MCP_ALLOWED_ORIGINS");
+    });
+    it("admits anything when Origin validation is off", () => {
+        expect(originRejection("https://attacker.example", "POST", { ...policy, allowedOrigins: "*" })).toBeUndefined();
+    });
+});
+describe("edgeRejection", () => {
+    const request = (overrides = {}) => ({
+        method: "POST",
+        path: "/mcp",
+        host: "mcp.example.com",
+        origin: undefined,
+        ...overrides,
+    });
+    it("passes a request whose Host and Origin are allowed", () => {
+        expect(edgeRejection(request({ origin: "https://app.example.com" }), policy)).toBeUndefined();
+    });
+    it("reports the Host before the Origin", () => {
+        const reason = edgeRejection(request({ host: "attacker.example", origin: "https://attacker.example" }), policy);
+        expect(reason).toMatch(/^Host "attacker\.example" is not allowed/);
+    });
+    it("reports a foreign Origin when the Host passes", () => {
+        const reason = edgeRejection(request({ origin: "https://attacker.example" }), policy);
+        expect(reason).toMatch(/^Origin "https:\/\/attacker\.example" is not allowed/);
+    });
+    it("passes the exempt path prefixes whatever their headers", () => {
+        const foreign = { host: "10.0.0.7", origin: "https://attacker.example" };
+        expect(edgeRejection(request({ path: "/metrics", ...foreign }), policy, ["/metrics"])).toBe(undefined);
+        expect(edgeRejection(request({ path: "/metrics2", ...foreign }), policy, ["/metrics"])).toBeDefined();
+    });
+});
+describe("jsonRpcErrorBody", () => {
+    it("is a JSON-RPC error with a null id", () => {
+        expect(JSON.parse(jsonRpcErrorBody("nope"))).toEqual({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "nope" },
+            id: null,
+        });
+    });
+});
+describe("installHttpEdgeGuard", () => {
+    function install(edge, exemptPaths) {
+        let middleware;
+        const host = {
+            use: (path, handler) => {
+                expect(path).toBe("*");
+                middleware = handler;
+            },
+        };
+        installHttpEdgeGuard(host, edge, exemptPaths ? { exemptPaths } : undefined);
+        return async (method, path, headers) => {
+            const ctx = {
+                req: { method, path, header: (name) => headers[name] },
+            };
+            let passed = false;
+            const response = await middleware(ctx, () => {
+                passed = true;
+                return Promise.resolve();
+            });
+            return { passed, response: response ?? undefined };
+        };
+    }
+    it("passes allowed requests through", async () => {
+        const run = install(policy);
+        const result = await run("POST", "/mcp", {
+            host: "mcp.example.com",
+            origin: "https://app.example.com",
+        });
+        expect(result).toEqual({ passed: true, response: undefined });
+    });
+    it("answers 403 with a JSON-RPC body for a foreign Host, before the route runs", async () => {
+        const run = install(policy);
+        const { passed, response } = await run("POST", "/mcp", { host: "attacker.example" });
+        expect(passed).toBe(false);
+        expect(response?.status).toBe(403);
+        expect(response?.headers.get("content-type")).toBe("application/json");
+        const body = (await response.json());
+        expect(body.error.message).toMatch(/^Forbidden: Host "attacker\.example" is not allowed/);
+    });
+    it("answers 403 for a foreign Origin even when the Host is fine", async () => {
+        const run = install(policy);
+        const { passed, response } = await run("POST", "/mcp", {
+            host: "localhost:8400",
+            origin: "https://attacker.example",
+        });
+        expect(passed).toBe(false);
+        expect(response?.status).toBe(403);
+    });
+    it("exempts the listed path prefixes (probes reach the container by IP)", async () => {
+        const run = install(policy, ["/health"]);
+        for (const path of ["/health", "/health/ready"]) {
+            expect((await run("GET", path, { host: "10.0.0.7:8400" })).passed, path).toBe(true);
+        }
+        expect((await run("GET", "/healthz", { host: "10.0.0.7:8400" })).passed).toBe(false);
+        expect((await run("GET", "/mcp", { host: "10.0.0.7:8400" })).passed).toBe(false);
+    });
+    it("guards every path when nothing is exempt", async () => {
+        const run = install(policy);
+        expect((await run("GET", "/health", { host: "10.0.0.7" })).passed).toBe(false);
+    });
+});
+//# sourceMappingURL=http-edge.test.js.map

package/dist/http-edge.test.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,48 @@
+import { Registry } from "prom-client";
+import type { HttpRouteHost } from "./health.js";
+import { type ToolCallMiddlewareHost } from "./host-boot.js";
+/** The slice of hono's context the HTTP middleware reads — structural, like the other host ports. */
+export interface HttpMiddlewareContext {
+    req: {
+        method: string;
+        path: string;
+    };
+    res: {
+        status: number;
+    };
+}
+/** `server.use("*", middleware)` — hono's catch-all middleware registration. */
+export interface HttpMiddlewareHost {
+    use(path: "*", handler: (ctx: HttpMiddlewareContext, next: () => Promise<void>) => Promise<void>): unknown;
+}
+export type MetricsHost = HttpRouteHost & HttpMiddlewareHost & ToolCallMiddlewareHost;
+export interface MetricsOptions {
+    /** Scrape route (default `/metrics`). */
+    path?: string;
+    /** Name prefix for the server's own metrics (default `mcp_`). */
+    prefix?: string;
+    /** Collect prom-client's process/Node.js default metrics (default true). */
+    defaultMetrics?: boolean;
+    /** Routes kept verbatim in the `route` label; everything else is `other`. */
+    routes?: readonly string[];
+    /** Registry to populate (default: a fresh one — never the global registry, so hosts and tests stay isolated). */
+    registry?: Registry;
+    /** Bearer token the scrape requires (401 otherwise); unset = open. */
+    token?: string;
+}
+/** Constant-time `Authorization: Bearer <token>` check (hashing equalizes the lengths). */
+export declare function bearerMatches(authorization: string | undefined, token: string): boolean;
+/** Exact match or a sub-path of a known route keeps its label; anything else folds into `other`. */
+export declare function routeLabel(path: string, routes?: readonly string[]): string;
+/**
+ * Register the collectors and the scrape route. Returns the registry so a
+ * host can add its own instruments or serve it elsewhere.
+ *
+ * Call it BEFORE registering routes that should be counted — the health
+ * probes included: hono runs handlers in registration order and stops at the
+ * first response, so a route registered earlier never reaches the `*`
+ * middleware. The MCP transport and the OAuth discovery routes are mounted
+ * by `listen()`, i.e. always after this.
+ */
+export declare function installMetrics(server: MetricsHost, options?: MetricsOptions): Registry;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAuBA,OAAO,EAA6C,QAAQ,EAAE,MAAM,aAAa,CAAA;AACjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAA+B,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAEzF,qGAAqG;AACrG,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACxB;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,GAAG,CACD,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,CAAC,GAAG,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAChF,OAAO,CAAA;CACX;AAED,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,kBAAkB,GAAG,sBAAsB,CAAA;AAErF,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,iHAAiH;IACjH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAOD,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAGvF;AAQD,oGAAoG;AACpG,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,SAAS,MAAM,EAAmB,GAAG,MAAM,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,QAAQ,CAkF1F"}

package/dist/metrics.js

@@ -0,0 +1,124 @@
+/**
+ * Prometheus metrics for composed-server hosts (server path only): a scrape
+ * endpoint (pull — a ServiceMonitor target, unlike the engine's OTLP push)
+ * fed by three sources:
+ *
+ * - `mcp:tools/call` middleware → per-tool call counter + duration histogram.
+ *   Tool names are a finite catalogue, so the `tool` label stays bounded;
+ *   arguments, users and sessions are never labels (cardinality + PII). It
+ *   counts the calls that reached a tool's handler: the SDK refuses an unknown
+ *   tool or arguments that fail the input schema before that, so those show
+ *   only in mcp-use's request log (and as `/mcp` requests below).
+ * - hono `*` middleware → HTTP request counter + duration histogram. The
+ *   `route` label is folded onto the known route set (`other` for the rest)
+ *   because request paths are caller-controlled.
+ * - prom-client's default collectors → process/event-loop/heap gauges under
+ *   their standard names (`process_*`, `nodejs_*`), which the stock Node.js
+ *   Grafana dashboards expect — deliberately NOT prefixed.
+ *
+ * Outside mcp-use's OAuth gate like the health probes (scoped to the MCP base
+ * path): set `token` (the composed server's `MCP_METRICS_TOKEN`) to require
+ * `Authorization: Bearer <token>`, or front `/metrics` with network policy.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { collectDefaultMetrics, Counter, Histogram, Registry } from "prom-client";
+import { toolCallOutcome, toolNameOf } from "./host-boot.js";
+const DEFAULT_ROUTES = ["/mcp", "/health", "/metrics", "/.well-known", "/fonts"];
+const DURATION_BUCKETS = [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30];
+const digest = (value) => createHash("sha256").update(value).digest();
+/** Constant-time `Authorization: Bearer <token>` check (hashing equalizes the lengths). */
+export function bearerMatches(authorization, token) {
+    const match = /^Bearer\s+(.+)$/i.exec(authorization?.trim() ?? "");
+    return match !== null && timingSafeEqual(digest(match[1]), digest(token));
+}
+/** The `Authorization` header from a hono-shaped route ctx (structural, like the other ports). */
+const authorizationOf = (ctx) => ctx?.req?.header?.("authorization");
+/** Exact match or a sub-path of a known route keeps its label; anything else folds into `other`. */
+export function routeLabel(path, routes = DEFAULT_ROUTES) {
+    return routes.find((route) => path === route || path.startsWith(`${route}/`)) ?? "other";
+}
+/**
+ * Register the collectors and the scrape route. Returns the registry so a
+ * host can add its own instruments or serve it elsewhere.
+ *
+ * Call it BEFORE registering routes that should be counted — the health
+ * probes included: hono runs handlers in registration order and stops at the
+ * first response, so a route registered earlier never reaches the `*`
+ * middleware. The MCP transport and the OAuth discovery routes are mounted
+ * by `listen()`, i.e. always after this.
+ */
+export function installMetrics(server, options = {}) {
+    const { path = "/metrics", prefix = "mcp_", defaultMetrics = true, routes = DEFAULT_ROUTES, registry = new Registry(), token, } = options;
+    if (defaultMetrics)
+        collectDefaultMetrics({ register: registry });
+    const toolCalls = new Counter({
+        name: `${prefix}tool_calls_total`,
+        help: "MCP tools/call invocations by tool and outcome (ok | error).",
+        labelNames: ["tool", "outcome"],
+        registers: [registry],
+    });
+    const toolDuration = new Histogram({
+        name: `${prefix}tool_call_duration_seconds`,
+        help: "MCP tools/call handler duration in seconds.",
+        labelNames: ["tool"],
+        buckets: DURATION_BUCKETS,
+        registers: [registry],
+    });
+    const httpRequests = new Counter({
+        name: `${prefix}http_requests_total`,
+        help: "HTTP requests by method, route and status code.",
+        labelNames: ["method", "route", "status"],
+        registers: [registry],
+    });
+    const httpDuration = new Histogram({
+        name: `${prefix}http_request_duration_seconds`,
+        help: "HTTP request duration in seconds by method and route.",
+        labelNames: ["method", "route"],
+        buckets: DURATION_BUCKETS,
+        registers: [registry],
+    });
+    server.use("mcp:tools/call", async (ctx, next) => {
+        const tool = toolNameOf(ctx);
+        const stop = toolDuration.startTimer({ tool });
+        // A throwing handler never reaches the assignment below — it stays `error`.
+        let outcome = "error";
+        try {
+            const result = await next();
+            outcome = toolCallOutcome(result);
+            return result;
+        }
+        finally {
+            stop();
+            toolCalls.inc({ tool, outcome });
+        }
+    });
+    server.use("*", async (ctx, next) => {
+        const method = ctx.req.method;
+        const route = routeLabel(ctx.req.path, routes);
+        const stop = httpDuration.startTimer({ method, route });
+        // hono routes handler errors through its error handler (c.res = 500), so
+        // `next()` normally resolves; the fallback covers an error escaping it.
+        let status = "500";
+        try {
+            await next();
+            status = String(ctx.res.status);
+        }
+        finally {
+            stop();
+            httpRequests.inc({ method, route, status });
+        }
+    });
+    server.get(path, async (ctx) => {
+        if (token !== undefined && !bearerMatches(authorizationOf(ctx), token)) {
+            return new Response("Unauthorized\n", {
+                status: 401,
+                headers: { "www-authenticate": 'Bearer realm="metrics"', "cache-control": "no-store" },
+            });
+        }
+        return new Response(await registry.metrics(), {
+            headers: { "content-type": registry.contentType, "cache-control": "no-store" },
+        });
+    });
+    return registry;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/dist/metrics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metrics.test.d.ts.map

package/dist/metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.test.d.ts","sourceRoot":"","sources":["../src/metrics.test.ts"],"names":[],"mappings":""}

package/dist/metrics.test.js

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import { Registry } from "prom-client";
+import { bearerMatches, installMetrics, routeLabel, } from "./metrics.js";
+function install(options) {
+    const routes = new Map();
+    let http;
+    let tool;
+    const server = {
+        get: (path, handler) => routes.set(path, handler),
+        use: (pattern, handler) => {
+            if (pattern === "*")
+                http = handler;
+            else
+                tool = handler;
+            return undefined;
+        },
+    };
+    const registry = installMetrics(server, { defaultMetrics: false, ...options });
+    if (!http || !tool)
+        throw new Error("middlewares were not registered");
+    const scrape = async (path = "/metrics", authorization) => {
+        const handler = routes.get(path);
+        if (!handler)
+            throw new Error(`no route registered for ${path}`);
+        const res = await handler({
+            req: { header: (name) => (name === "authorization" ? authorization : undefined) },
+        });
+        return { status: res.status, headers: res.headers, text: await res.text() };
+    };
+    const request = (method, path, status, next) => http({ req: { method, path }, res: { status } }, next ?? (async () => { }));
+    return { routes, registry, scrape, request, tool };
+}
+describe("bearerMatches", () => {
+    it("accepts exactly `Bearer <token>` (scheme case-insensitive)", () => {
+        expect(bearerMatches("Bearer s3cret", "s3cret")).toBe(true);
+        expect(bearerMatches("bearer   s3cret ", "s3cret")).toBe(true);
+        expect(bearerMatches("Bearer s3cret2", "s3cret")).toBe(false);
+        expect(bearerMatches("Bearer s3cre", "s3cret")).toBe(false);
+        expect(bearerMatches("Basic s3cret", "s3cret")).toBe(false);
+        expect(bearerMatches("s3cret", "s3cret")).toBe(false);
+        expect(bearerMatches("Bearer ", "s3cret")).toBe(false);
+        expect(bearerMatches(undefined, "s3cret")).toBe(false);
+    });
+});
+describe("routeLabel", () => {
+    it("keeps known routes and their sub-paths, folds everything else into other", () => {
+        expect(routeLabel("/mcp")).toBe("/mcp");
+        expect(routeLabel("/mcp/inspector")).toBe("/mcp");
+        expect(routeLabel("/health/ready")).toBe("/health");
+        expect(routeLabel("/.well-known/oauth-authorization-server")).toBe("/.well-known");
+        expect(routeLabel("/metrics")).toBe("/metrics");
+        expect(routeLabel("/mcpx")).toBe("other");
+        expect(routeLabel("/admin/../etc/passwd")).toBe("other");
+        expect(routeLabel("/")).toBe("other");
+    });
+    it("honors a custom route set", () => {
+        expect(routeLabel("/api/v1/x", ["/api"])).toBe("/api");
+        expect(routeLabel("/mcp", ["/api"])).toBe("other");
+    });
+});
+describe("installMetrics token", () => {
+    it("answers 401 with a Bearer challenge unless the scrape carries the token", async () => {
+        const { scrape } = install({ token: "s3cret" });
+        const anonymous = await scrape();
+        expect(anonymous.status).toBe(401);
+        expect(anonymous.headers.get("www-authenticate")).toBe('Bearer realm="metrics"');
+        expect(anonymous.text).not.toContain("mcp_tool_calls_total");
+        expect((await scrape("/metrics", "Bearer wrong")).status).toBe(401);
+        const authorized = await scrape("/metrics", "Bearer s3cret");
+        expect(authorized.status).toBe(200);
+        expect(authorized.text).toContain("mcp_tool_calls_total");
+    });
+    it("stays open without a token", async () => {
+        const { scrape } = install();
+        expect((await scrape()).status).toBe(200);
+    });
+});
+describe("installMetrics", () => {
+    it("serves the registry as Prometheus text on the scrape route", async () => {
+        const { routes, scrape } = install();
+        expect([...routes.keys()]).toEqual(["/metrics"]);
+        const res = await scrape();
+        expect(res.status).toBe(200);
+        expect(res.headers.get("content-type")).toContain("text/plain");
+        expect(res.headers.get("cache-control")).toBe("no-store");
+        expect(res.text).toContain("# HELP mcp_tool_calls_total");
+        expect(res.text).toContain("# HELP mcp_http_requests_total");
+    });
+    it("honors a custom scrape path, prefix and registry", async () => {
+        const registry = new Registry();
+        const { routes, registry: returned, scrape, } = install({
+            path: "/internal/metrics",
+            prefix: "acme_",
+            registry,
+        });
+        expect(returned).toBe(registry);
+        expect([...routes.keys()]).toEqual(["/internal/metrics"]);
+        const { text } = await scrape("/internal/metrics");
+        expect(text).toContain("acme_tool_calls_total");
+        expect(text).not.toContain("mcp_tool_calls_total");
+    });
+    it("collects the default process metrics unless disabled", async () => {
+        const { scrape } = install({ defaultMetrics: true });
+        expect((await scrape()).text).toContain("process_cpu_user_seconds_total");
+        const { scrape: scrapeWithout } = install();
+        expect((await scrapeWithout()).text).not.toContain("process_cpu_user_seconds_total");
+    });
+    it("counts tool calls by name and outcome and observes their duration", async () => {
+        const { tool, scrape } = install();
+        const ok = { content: [] };
+        await expect(tool({ params: { name: "notes_list_notes" } }, async () => ok)).resolves.toBe(ok);
+        await tool({ params: { name: "notes_list_notes" } }, async () => ok);
+        await tool({ params: { name: "notes_show_notes" } }, async () => ({ isError: true }));
+        await tool({}, async () => ok);
+        const { text } = await scrape();
+        expect(text).toContain('mcp_tool_calls_total{tool="notes_list_notes",outcome="ok"} 2');
+        expect(text).toContain('mcp_tool_calls_total{tool="notes_show_notes",outcome="error"} 1');
+        expect(text).toContain('mcp_tool_calls_total{tool="unknown",outcome="ok"} 1');
+        expect(text).toContain('mcp_tool_call_duration_seconds_count{tool="notes_list_notes"} 2');
+    });
+    it("counts a throwing tool handler as error and rethrows", async () => {
+        const { tool, scrape } = install();
+        const boom = new Error("boom");
+        await expect(tool({ params: { name: "notes_list_notes" } }, async () => {
+            throw boom;
+        })).rejects.toBe(boom);
+        const { text } = await scrape();
+        expect(text).toContain('mcp_tool_calls_total{tool="notes_list_notes",outcome="error"} 1');
+        expect(text).toContain('mcp_tool_call_duration_seconds_count{tool="notes_list_notes"} 1');
+    });
+    it("counts HTTP requests by method, normalised route and status", async () => {
+        const { request, scrape } = install();
+        await request("GET", "/health/ready", 200);
+        await request("GET", "/health/live", 200);
+        await request("POST", "/mcp", 401);
+        await request("GET", "/does/not/exist", 404);
+        const { text } = await scrape();
+        expect(text).toContain('mcp_http_requests_total{method="GET",route="/health",status="200"} 2');
+        expect(text).toContain('mcp_http_requests_total{method="POST",route="/mcp",status="401"} 1');
+        expect(text).toContain('mcp_http_requests_total{method="GET",route="other",status="404"} 1');
+        expect(text).toContain('mcp_http_request_duration_seconds_count{method="GET",route="/health"} 2');
+        expect(text).not.toContain("/does/not/exist");
+    });
+    it("records 500 for an error escaping hono's error handler and rethrows", async () => {
+        const { request, scrape } = install();
+        const boom = new Error("boom");
+        await expect(request("POST", "/mcp", 200, async () => {
+            throw boom;
+        })).rejects.toBe(boom);
+        const { text } = await scrape();
+        expect(text).toContain('mcp_http_requests_total{method="POST",route="/mcp",status="500"} 1');
+    });
+});
+//# sourceMappingURL=metrics.test.js.map