@thotischner/observability-mcp 3.0.0 → 3.1.0

package/dist/tools/validation.js

@@ -41,6 +41,80 @@ export function validateServiceName(service) {
     }
     return null;
 }
+/** A Prometheus/Loki label name: letter/underscore, then word chars. */
+const LABEL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validate a structured `labels` filter map for query_logs. Fail-closed:
+ * any bad key/value rejects the whole request rather than silently
+ * dropping a filter (a dropped filter could widen results past what the
+ * caller intended). Bounds the map size + value length so a crafted input
+ * can't build a pathological query.
+ */
+export function validateLogLabels(labels) {
+    if (labels === undefined)
+        return null;
+    if (typeof labels !== "object" || labels === null || Array.isArray(labels)) {
+        return "Invalid labels: must be an object mapping label names to string values.";
+    }
+    const entries = Object.entries(labels);
+    if (entries.length > 20) {
+        return "Too many labels (max 20).";
+    }
+    for (const [k, v] of entries) {
+        if (!LABEL_NAME_RE.test(k)) {
+            return `Invalid label name "${k}". Must match [a-zA-Z_][a-zA-Z0-9_]* (no dots, dashes, or quotes).`;
+        }
+        if (typeof v !== "string") {
+            return `Invalid value for label "${k}": must be a string.`;
+        }
+        if (v.length > 1024) {
+            return `Value for label "${k}" too long (max 1024 chars).`;
+        }
+    }
+    return null;
+}
+const AGGREGATE_OPS = new Set(["count_over_time", "sum", "topk"]);
+/**
+ * Validate the query_logs `aggregate` spec. Fail-closed, like the labels
+ * validator. Returns an error string or null.
+ */
+export function validateLogAggregate(aggregate) {
+    if (aggregate === undefined)
+        return null;
+    if (typeof aggregate !== "object" || aggregate === null || Array.isArray(aggregate)) {
+        return "Invalid aggregate: must be an object with an `op`.";
+    }
+    const a = aggregate;
+    if (typeof a.op !== "string" || !AGGREGATE_OPS.has(a.op)) {
+        return `Invalid aggregate.op. Must be one of: ${[...AGGREGATE_OPS].join(", ")}.`;
+    }
+    if (a.by !== undefined) {
+        if (!Array.isArray(a.by) || !a.by.every((x) => typeof x === "string")) {
+            return "aggregate.by must be an array of label-name strings.";
+        }
+        if (a.by.length > 10)
+            return "aggregate.by has too many labels (max 10).";
+        for (const name of a.by) {
+            if (!LABEL_NAME_RE.test(name)) {
+                return `Invalid aggregate.by label "${name}". Must match [a-zA-Z_][a-zA-Z0-9_]*.`;
+            }
+        }
+    }
+    if (a.k !== undefined) {
+        if (typeof a.k !== "number" || !Number.isFinite(a.k) || a.k <= 0 || a.k > 1000) {
+            return "aggregate.k must be a positive integer (max 1000).";
+        }
+    }
+    if (a.step !== undefined) {
+        if (typeof a.step !== "string" || validateDuration(a.step)) {
+            return "aggregate.step must be a duration like '15m', '1h'.";
+        }
+    }
+    if (a.op === "topk" && (a.by === undefined || a.by.length === 0)) {
+        return "aggregate.op 'topk' requires at least one `by` label to rank.";
+    }
+    return null;
+}
 export function errorResponse(message) {
     return {
         content: [{ type: "text", text: JSON.stringify({ error: message }) }],

package/dist/tools/validation.test.js

@@ -1,6 +1,59 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { validateDuration, validateServiceName, sanitizeLabelValue, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, sanitizeLabelValue, validateLogLabels, validateLogAggregate, errorResponse } from "./validation.js";
+describe("validateLogAggregate (Q-LOG2)", () => {
+    it("accepts undefined and valid specs", () => {
+        assert.equal(validateLogAggregate(undefined), null);
+        assert.equal(validateLogAggregate({ op: "count_over_time" }), null);
+        assert.equal(validateLogAggregate({ op: "sum", by: ["url", "status"] }), null);
+        assert.equal(validateLogAggregate({ op: "topk", by: ["url"], k: 5, step: "15m" }), null);
+    });
+    it("rejects a bad/missing op", () => {
+        assert.ok(validateLogAggregate({}));
+        assert.ok(validateLogAggregate({ op: "median" }));
+        assert.ok(validateLogAggregate("nope"));
+    });
+    it("rejects bad by labels", () => {
+        assert.ok(validateLogAggregate({ op: "sum", by: ["a.b"] }));
+        assert.ok(validateLogAggregate({ op: "sum", by: "url" }));
+    });
+    it("rejects bad k and step", () => {
+        assert.ok(validateLogAggregate({ op: "topk", by: ["url"], k: 0 }));
+        assert.ok(validateLogAggregate({ op: "topk", by: ["url"], k: 99999 }));
+        assert.ok(validateLogAggregate({ op: "count_over_time", step: "soon" }));
+    });
+    it("requires a by label for topk", () => {
+        assert.ok(validateLogAggregate({ op: "topk" }));
+        assert.ok(validateLogAggregate({ op: "topk", by: [] }));
+    });
+});
+describe("validateLogLabels (Q-LOG1)", () => {
+    it("accepts undefined (no filter) and a valid map", () => {
+        assert.equal(validateLogLabels(undefined), null);
+        assert.equal(validateLogLabels({ method: "GET", status: "200", environment: "prod" }), null);
+    });
+    it("rejects non-object inputs", () => {
+        assert.ok(validateLogLabels("nope"));
+        assert.ok(validateLogLabels(["a"]));
+        assert.ok(validateLogLabels(42));
+    });
+    it("rejects label names with dots, dashes, or quotes (injection-safe, fail-closed)", () => {
+        assert.ok(validateLogLabels({ "a.b": "x" }));
+        assert.ok(validateLogLabels({ "a-b": "x" }));
+        assert.ok(validateLogLabels({ 'a"x': "y" }));
+        assert.ok(validateLogLabels({ "1abc": "x" })); // can't start with a digit
+    });
+    it("rejects non-string and over-long values", () => {
+        assert.ok(validateLogLabels({ method: 123 }));
+        assert.ok(validateLogLabels({ method: "x".repeat(1025) }));
+    });
+    it("rejects too many labels", () => {
+        const many = {};
+        for (let i = 0; i < 21; i++)
+            many[`k${i}`] = "v";
+        assert.ok(validateLogLabels(many));
+    });
+});
 describe("validateDuration", () => {
     it("accepts valid durations", () => {
         assert.equal(validateDuration("5m"), null);

package/dist/transport/transportSessionMap.d.ts

@@ -0,0 +1,70 @@
+import type { SessionStore } from "./sessionStore.js";
+export interface TransportSessionMeta {
+    /** Stable id of the replica that owns the underlying SDK
+     *  Transport object. Set on creation. */
+    ownerReplica: string;
+    /** Optional virtual-server product slug. Undefined for the
+     *  root /mcp surface. */
+    product?: string;
+    /** Epoch ms — bumped on every successful request. */
+    lastActive: number;
+}
+export interface TransportSessionMap {
+    /** Stable backend identifier (used in /api/info diagnostics). */
+    readonly backend: string;
+    /** True iff there's a metadata entry — does NOT imply a local
+     *  Transport exists. */
+    has(sessionId: string): Promise<boolean>;
+    get(sessionId: string): Promise<TransportSessionMeta | undefined>;
+    set(sessionId: string, meta: TransportSessionMeta, ttlSeconds?: number): Promise<void>;
+    /** Convenience: bump lastActive while preserving the rest. */
+    touch(sessionId: string, ttlSeconds?: number): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    /** Return every session id this map knows about. Used for the
+     *  cleanup tick. Implementations MAY cap; in-memory returns the
+     *  full set, Redis pages via SCAN under the prefix. */
+    keys(): Promise<string[]>;
+    /** Evict entries with lastActive older than `maxIdleMs`. Returns
+     *  the evicted ids (caller logs / records metrics). */
+    cleanup(maxIdleMs: number): Promise<string[]>;
+}
+export declare class InMemoryTransportSessionMap implements TransportSessionMap {
+    readonly backend = "memory";
+    private readonly map;
+    has(id: string): Promise<boolean>;
+    get(id: string): Promise<TransportSessionMeta | undefined>;
+    set(id: string, meta: TransportSessionMeta): Promise<void>;
+    touch(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    keys(): Promise<string[]>;
+    cleanup(maxIdleMs: number): Promise<string[]>;
+}
+/**
+ * Wraps an existing SessionStore so the per-session metadata lives
+ * wherever the SessionStore decided — InMemorySessionStore (no
+ * cross-replica visibility, identical to InMemoryTransportSessionMap
+ * but useful for tests / when a future backend is plugged in) or
+ * RedisSessionStore (cross-replica safe).
+ *
+ * Each entry stored at `<KEY_PREFIX><sessionId>` as JSON.
+ */
+export declare class SessionStoreBackedTransportSessionMap implements TransportSessionMap {
+    readonly backend: string;
+    private readonly store;
+    private readonly defaultTtlSeconds;
+    constructor(store: SessionStore, defaultTtlSeconds?: number);
+    has(id: string): Promise<boolean>;
+    get(id: string): Promise<TransportSessionMeta | undefined>;
+    set(id: string, meta: TransportSessionMeta, ttlSeconds?: number): Promise<void>;
+    touch(id: string, ttlSeconds?: number): Promise<void>;
+    delete(id: string): Promise<void>;
+    keys(): Promise<string[]>;
+    cleanup(maxIdleMs: number): Promise<string[]>;
+}
+/**
+ * Pick the right implementation. When `sessionStore` is the
+ * in-memory default, return InMemoryTransportSessionMap so we
+ * avoid the (synchronous → async) layering tax. Otherwise wrap
+ * the supplied store.
+ */
+export declare function createTransportSessionMap(sessionStore?: SessionStore): TransportSessionMap;

package/dist/transport/transportSessionMap.js

@@ -0,0 +1,128 @@
+// Multi-replica-safe MCP transport session metadata.
+//
+// The actual SDK `StreamableHTTPServerTransport` object MUST live in
+// the replica that originated the session — it owns the open HTTP
+// response handles. What CAN be shared across replicas is the
+// per-session metadata (last-active timestamp, virtual-server
+// product slug, owner-replica id). This module promotes that map
+// from a process-local `Map` to a small `TransportSessionMap` KV
+// surface backed by either in-memory state (default) or the existing
+// SessionStore Redis backend (opt-in via OMCP_REDIS_URL).
+//
+// Multi-replica behaviour:
+//   - Replica A creates session S. Writes metadata {ownerReplica:A,
+//     lastActive, product} to the shared map.
+//   - Subsequent request lands on Replica B with the same S header.
+//     B consults the shared map, sees ownerReplica:A, replies 410
+//     so the load balancer rehashes or the client retries.
+//   - This keeps the gateway functional even when sticky ingress
+//     drops the affinity — the worst case is a single 410 retry,
+//     not a silent NEW transport (which today races against the
+//     real one).
+//
+// The TTL on each entry mirrors SESSION_TTL_MS so the map doesn't
+// grow unbounded if a replica disappears without graceful
+// shutdown — TTL-based eviction is the safety net.
+// ---------------------------------------------------------------- in-memory
+export class InMemoryTransportSessionMap {
+    backend = "memory";
+    map = new Map();
+    async has(id) { return this.map.has(id); }
+    async get(id) {
+        return this.map.get(id);
+    }
+    async set(id, meta) {
+        this.map.set(id, meta);
+    }
+    async touch(id) {
+        const cur = this.map.get(id);
+        if (!cur)
+            return;
+        cur.lastActive = Date.now();
+    }
+    async delete(id) { this.map.delete(id); }
+    async keys() { return [...this.map.keys()]; }
+    async cleanup(maxIdleMs) {
+        const now = Date.now();
+        const evicted = [];
+        for (const [id, meta] of this.map) {
+            if (now - meta.lastActive > maxIdleMs) {
+                this.map.delete(id);
+                evicted.push(id);
+            }
+        }
+        return evicted;
+    }
+}
+// ---------------------------------------------------------------- SessionStore-backed
+const KEY_PREFIX = "transport:";
+/**
+ * Wraps an existing SessionStore so the per-session metadata lives
+ * wherever the SessionStore decided — InMemorySessionStore (no
+ * cross-replica visibility, identical to InMemoryTransportSessionMap
+ * but useful for tests / when a future backend is plugged in) or
+ * RedisSessionStore (cross-replica safe).
+ *
+ * Each entry stored at `<KEY_PREFIX><sessionId>` as JSON.
+ */
+export class SessionStoreBackedTransportSessionMap {
+    backend;
+    store;
+    defaultTtlSeconds;
+    constructor(store, defaultTtlSeconds = 30 * 60) {
+        this.store = store;
+        this.backend = `session-store:${store.backend}`;
+        this.defaultTtlSeconds = defaultTtlSeconds;
+    }
+    async has(id) {
+        return (await this.store.get(KEY_PREFIX + id)) !== undefined;
+    }
+    async get(id) {
+        return (await this.store.get(KEY_PREFIX + id)) ?? undefined;
+    }
+    async set(id, meta, ttlSeconds) {
+        await this.store.setEx(KEY_PREFIX + id, ttlSeconds ?? this.defaultTtlSeconds, meta);
+    }
+    async touch(id, ttlSeconds) {
+        const cur = await this.get(id);
+        if (!cur)
+            return;
+        cur.lastActive = Date.now();
+        await this.set(id, cur, ttlSeconds);
+    }
+    async delete(id) {
+        await this.store.del(KEY_PREFIX + id);
+    }
+    async keys() {
+        const raw = await this.store.keys(KEY_PREFIX);
+        return raw.map((k) => k.slice(KEY_PREFIX.length));
+    }
+    async cleanup(maxIdleMs) {
+        const now = Date.now();
+        const ids = await this.keys();
+        const evicted = [];
+        for (const id of ids) {
+            const meta = await this.get(id);
+            if (!meta)
+                continue;
+            if (now - meta.lastActive > maxIdleMs) {
+                await this.delete(id);
+                evicted.push(id);
+            }
+        }
+        return evicted;
+    }
+}
+// ---------------------------------------------------------------- factory
+/**
+ * Pick the right implementation. When `sessionStore` is the
+ * in-memory default, return InMemoryTransportSessionMap so we
+ * avoid the (synchronous → async) layering tax. Otherwise wrap
+ * the supplied store.
+ */
+export function createTransportSessionMap(sessionStore) {
+    if (!sessionStore || sessionStore.backend === "memory") {
+        return new InMemoryTransportSessionMap();
+    }
+    return new SessionStoreBackedTransportSessionMap(sessionStore);
+}

package/dist/transport/transportSessionMap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transport/transportSessionMap.test.js

@@ -0,0 +1,111 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { InMemoryTransportSessionMap, SessionStoreBackedTransportSessionMap, createTransportSessionMap, } from "./transportSessionMap.js";
+import { InMemorySessionStore } from "./sessionStore.js";
+function meta(p = {}) {
+    return {
+        ownerReplica: p.ownerReplica ?? "replica-A",
+        product: p.product,
+        lastActive: p.lastActive ?? Date.now(),
+    };
+}
+test("InMemoryTransportSessionMap: get/set/has/delete round-trip", async () => {
+    const m = new InMemoryTransportSessionMap();
+    assert.equal(await m.has("s1"), false);
+    await m.set("s1", meta({ product: "checkout" }));
+    assert.equal(await m.has("s1"), true);
+    const got = await m.get("s1");
+    assert.equal(got?.ownerReplica, "replica-A");
+    assert.equal(got?.product, "checkout");
+    await m.delete("s1");
+    assert.equal(await m.has("s1"), false);
+});
+test("InMemoryTransportSessionMap: touch bumps lastActive", async () => {
+    const m = new InMemoryTransportSessionMap();
+    const before = Date.now() - 10_000;
+    await m.set("s1", meta({ lastActive: before }));
+    await new Promise((r) => setTimeout(r, 2));
+    await m.touch("s1");
+    const got = await m.get("s1");
+    assert.ok((got?.lastActive ?? 0) > before);
+});
+test("InMemoryTransportSessionMap: keys + cleanup", async () => {
+    const m = new InMemoryTransportSessionMap();
+    await m.set("fresh", meta({ lastActive: Date.now() }));
+    await m.set("stale", meta({ lastActive: Date.now() - 10_000 }));
+    const all = await m.keys();
+    assert.equal(all.length, 2);
+    const evicted = await m.cleanup(5_000);
+    assert.deepEqual(evicted, ["stale"]);
+    assert.equal(await m.has("stale"), false);
+    assert.equal(await m.has("fresh"), true);
+});
+test("SessionStoreBackedTransportSessionMap: round-trip via SessionStore", async () => {
+    const store = new InMemorySessionStore();
+    const m = new SessionStoreBackedTransportSessionMap(store);
+    await m.set("s1", meta({ product: "p" }));
+    assert.equal(await m.has("s1"), true);
+    const got = await m.get("s1");
+    assert.equal(got?.product, "p");
+    await m.delete("s1");
+    assert.equal(await m.has("s1"), false);
+});
+test("SessionStoreBackedTransportSessionMap: keys excludes the prefix in returned ids", async () => {
+    const store = new InMemorySessionStore();
+    const m = new SessionStoreBackedTransportSessionMap(store);
+    await m.set("alpha", meta());
+    await m.set("beta", meta());
+    const ids = (await m.keys()).sort();
+    assert.deepEqual(ids, ["alpha", "beta"]);
+    // Unrelated keys on the same SessionStore must not pollute the map.
+    await store.set("scim:user:1", { foo: "bar" });
+    const idsAfter = (await m.keys()).sort();
+    assert.deepEqual(idsAfter, ["alpha", "beta"]);
+});
+test("SessionStoreBackedTransportSessionMap: cleanup evicts stale entries", async () => {
+    const store = new InMemorySessionStore();
+    const m = new SessionStoreBackedTransportSessionMap(store);
+    await m.set("fresh", meta({ lastActive: Date.now() }));
+    await m.set("stale", meta({ lastActive: Date.now() - 60_000 }));
+    const evicted = await m.cleanup(30_000);
+    assert.deepEqual(evicted, ["stale"]);
+});
+test("SessionStoreBackedTransportSessionMap: touch is no-op on missing id", async () => {
+    const store = new InMemorySessionStore();
+    const m = new SessionStoreBackedTransportSessionMap(store);
+    await m.touch("ghost");
+    assert.equal(await m.has("ghost"), false);
+});
+test("SessionStoreBackedTransportSessionMap: backend tag exposes underlying store name", () => {
+    const store = new InMemorySessionStore();
+    const m = new SessionStoreBackedTransportSessionMap(store);
+    assert.equal(m.backend, "session-store:memory");
+});
+test("createTransportSessionMap: memory backend returns in-memory impl", () => {
+    const store = new InMemorySessionStore();
+    const m = createTransportSessionMap(store);
+    assert.equal(m.backend, "memory");
+});
+test("createTransportSessionMap: non-memory backend returns wrapper", () => {
+    // Fake a non-memory backend by stubbing the backend tag.
+    const fake = {
+        backend: "redis",
+        async get() { return undefined; },
+        async set() { },
+        async setEx() { },
+        async del() { },
+        async keys() { return []; },
+        async close() { },
+    };
+    const m = createTransportSessionMap(fake);
+    assert.equal(m.backend, "session-store:redis");
+});
+test("createTransportSessionMap: undefined sessionStore → memory impl (back-compat)", () => {
+    const m = createTransportSessionMap();
+    assert.equal(m.backend, "memory");
+});
+test("InMemoryTransportSessionMap.touch: ghost id is no-op", async () => {
+    const m = new InMemoryTransportSessionMap();
+    await m.touch("ghost");
+    assert.equal(await m.has("ghost"), false);
+});

package/dist/types.d.ts

@@ -109,6 +109,54 @@ export interface LogQuery {
     duration: string;
     limit?: number;
     level?: string;
+    /** Structured label/field equality filters, AND'd together. For Loki
+     *  these compile to LogQL label-filter expressions after `| json`, so
+     *  fields the backend already extracts (method, status, url, ip,
+     *  environment, …) become first-class selectors instead of brittle
+     *  free-text regex. */
+    labels?: Record<string, string>;
+}
+/** Server-side log aggregation (Q-LOG2). Pushes count/group/topk down to
+ *  the backend's metric-query path so an agent gets a *number*, not a
+ *  *haystack*. */
+export interface LogAggregateQuery {
+    service: string;
+    duration: string;
+    /** Same structured filters as LogQuery, applied before aggregation. */
+    labels?: Record<string, string>;
+    /** Optional line filter applied before aggregation. */
+    query?: string;
+    /** count_over_time → time series of counts per bucket; sum → total per
+     *  group over the window; topk → the top-k groups by total. */
+    op: "count_over_time" | "sum" | "topk";
+    /** Group-by label names. */
+    by?: string[];
+    /** k for topk (default 10). */
+    k?: number;
+    /** Bucket size for count_over_time, e.g. "15m". Defaults to the window. */
+    step?: string;
+}
+export interface LogAggregateSeries {
+    /** The group key (the `by` label values). Empty object for an ungrouped total. */
+    labels: Record<string, string>;
+    /** Single value — present for instant ops (sum / topk). */
+    value?: number;
+    /** Time series — present for count_over_time. */
+    points?: Array<{
+        t: number;
+        value: number;
+    }>;
+}
+export interface LogAggregateResult {
+    source: string;
+    op: string;
+    by: string[];
+    step?: string;
+    /** "instant" (vector) for sum/topk, "range" (matrix) for count_over_time. */
+    mode: "instant" | "range";
+    series: LogAggregateSeries[];
+    /** Operator-facing notes, e.g. that `limit` is ignored in aggregate mode. */
+    note?: string;
 }
 export interface DataPoint {
     timestamp: string;