@thotischner/observability-mcp 3.0.0 → 3.0.1

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);
+});