@thotischner/observability-mcp 1.5.1 → 1.7.0

package/dist/tools/topology.test.js

@@ -0,0 +1,210 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ConnectorRegistry } from "../connectors/registry.js";
+import { PluginLoader } from "../connectors/loader.js";
+import { getTopologyHandler, getBlastRadiusHandler, resolveResource, } from "./topology.js";
+// --- A minimal stand-alone topology connector used as test fixture -----
+// Lets the suite drive the tool handlers without a real K8s cluster.
+class FakeTopologyConnector {
+    type = "fake";
+    signalType = "topology";
+    name = "fake-cluster";
+    resources;
+    edges;
+    constructor(resources, edges) {
+        this.resources = resources;
+        this.edges = edges;
+    }
+    async connect(c) { this.name = c.name; }
+    async healthCheck() { return { status: "up", latencyMs: 1 }; }
+    async disconnect() { }
+    getDefaultMetrics() { return []; }
+    getMetrics() { return []; }
+    async listServices() { return []; }
+    async listResources() { return this.resources; }
+    async listEdges() { return this.edges; }
+    async getTopologySnapshot() {
+        return { source: this.name, resources: this.resources, edges: this.edges, revision: 1 };
+    }
+    watchTopology(_l) { return () => { }; }
+}
+// Build a small but realistic topology covering both happy and edge cases:
+// two services, two hosts, ownership chain, one orphan, one cross-kind link.
+function fixture() {
+    const r = [
+        // Hosts
+        { id: "k8s:node:n1", kind: "node", name: "n1", source: "fake", labels: {} },
+        { id: "k8s:node:n2", kind: "node", name: "n2", source: "fake", labels: {} },
+        // Scope
+        { id: "k8s:namespace:prod", kind: "namespace", name: "prod", source: "fake", labels: {} },
+        { id: "k8s:namespace:staging", kind: "namespace", name: "staging", source: "fake", labels: {} },
+        // Ownership roots (deployments)
+        { id: "k8s:deployment:prod/api", kind: "deployment", name: "api", source: "fake", labels: {} },
+        { id: "k8s:deployment:prod/db", kind: "deployment", name: "db", source: "fake", labels: {} },
+        // Intermediate
+        { id: "k8s:replicaset:prod/api-1", kind: "replicaset", name: "api-1", source: "fake", labels: {} },
+        // Workloads
+        { id: "k8s:pod:prod/api-aaa", kind: "pod", name: "api-aaa", source: "fake", labels: { app: "api" } },
+        { id: "k8s:pod:prod/api-bbb", kind: "pod", name: "api-bbb", source: "fake", labels: { app: "api" } },
+        { id: "k8s:pod:prod/db-aaa", kind: "pod", name: "db-aaa", source: "fake", labels: { app: "db" } },
+        // Orphan with no RUNS_ON (e.g. pending)
+        { id: "k8s:pod:staging/pending-1", kind: "pod", name: "pending-1", source: "fake", labels: {} },
+    ];
+    const e = [
+        // ownership chain
+        { from: "k8s:pod:prod/api-aaa", to: "k8s:replicaset:prod/api-1", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/api-bbb", to: "k8s:replicaset:prod/api-1", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        { from: "k8s:replicaset:prod/api-1", to: "k8s:deployment:prod/api", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/db-aaa", to: "k8s:deployment:prod/db", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        // RUNS_ON — api-aaa shares n1 with db-aaa (blast-radius case);
+        // api-bbb alone on n2 (no shared-host case)
+        { from: "k8s:pod:prod/api-aaa", to: "k8s:node:n1", relation: "RUNS_ON", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/db-aaa", to: "k8s:node:n1", relation: "RUNS_ON", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/api-bbb", to: "k8s:node:n2", relation: "RUNS_ON", source: "fake", confidence: 1 },
+        // IN_NAMESPACE
+        { from: "k8s:pod:prod/api-aaa", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/api-bbb", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/db-aaa", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:deployment:prod/api", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:deployment:prod/db", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:replicaset:prod/api-1", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:pod:staging/pending-1", to: "k8s:namespace:staging", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+    ];
+    return { resources: r, edges: e };
+}
+async function makeRegistry() {
+    const { resources, edges } = fixture();
+    const loader = new PluginLoader();
+    // Don't load builtins/filesystem — we plug a single fake connector in
+    // directly so the suite is hermetic and fast.
+    const reg = new ConnectorRegistry(loader);
+    const conn = new FakeTopologyConnector(resources, edges);
+    await conn.connect({ name: "fake-cluster", type: "fake", url: "", enabled: true });
+    // ConnectorRegistry has no public "register a live instance" method,
+    // so we install via the documented addSource path with a fake loader.
+    loader.connectors.set("fake", {
+        name: "fake",
+        source: "builtin",
+        factory: () => conn,
+    });
+    await reg.addSource({ name: "fake-cluster", type: "fake", url: "", enabled: true });
+    return reg;
+}
+function parseTool(result) {
+    return JSON.parse(result.content[0].text);
+}
+describe("resolveResource", () => {
+    const { resources } = fixture();
+    it("matches an exact id", () => {
+        const r = resolveResource("k8s:node:n1", resources);
+        assert.ok(!("error" in r));
+        if (!("error" in r))
+            assert.equal(r.kind, "node");
+    });
+    it("matches a unique exact name", () => {
+        const r = resolveResource("api-aaa", resources);
+        assert.ok(!("error" in r));
+    });
+    it("returns candidates for an ambiguous fuzzy match", () => {
+        // "aaa" doesn't exactly match any name, but fuzzy-matches api-aaa and db-aaa
+        const r = resolveResource("aaa", resources);
+        assert.ok("error" in r);
+        if ("error" in r) {
+            assert.ok((r.candidates?.length ?? 0) >= 2);
+        }
+    });
+    it("returns a clean error for no match", () => {
+        const r = resolveResource("does-not-exist", resources);
+        assert.ok("error" in r);
+    });
+});
+describe("get_topology tool", () => {
+    it("returns the full graph by default", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        assert.equal(out.sources.length, 1);
+        assert.equal(out.resources.length, fixture().resources.length);
+        assert.equal(out.edges.length, fixture().edges.length);
+        assert.equal(out.truncated, false);
+    });
+    it("filters by kind", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, { kind: "pod" }));
+        for (const r of out.resources)
+            assert.equal(r.kind, "pod");
+        // edges must reference only the kept resources
+        const ids = new Set(out.resources.map((r) => r.id));
+        for (const e of out.edges) {
+            assert.ok(ids.has(e.from) && ids.has(e.to));
+        }
+    });
+    it("filters by scope name or id", async () => {
+        const reg = await makeRegistry();
+        const byName = parseTool(await getTopologyHandler(reg, { scope: "prod" }));
+        const byId = parseTool(await getTopologyHandler(reg, { scope: "k8s:namespace:prod" }));
+        assert.equal(byName.resources.length, byId.resources.length);
+        // staging pod must not appear
+        assert.ok(!byName.resources.some((r) => r.name === "pending-1"));
+    });
+    it("respects the limit and reports truncation", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, { limit: 3 }));
+        assert.equal(out.resources.length, 3);
+        assert.equal(out.truncated, true);
+        assert.equal(out.total.resources, fixture().resources.length);
+    });
+});
+describe("get_blast_radius tool", () => {
+    it("reports shared-host blast radius for a co-located pod", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "api-aaa" }));
+        assert.equal(out.target.name, "api-aaa");
+        assert.equal(out.hosts.length, 1);
+        const host = out.hosts[0];
+        assert.equal(host.host.name, "n1");
+        // Two ownership roots on n1: deployment/api and deployment/db
+        assert.equal(host.ownershipRoots, 2);
+        const rootNames = new Set(host.coTenants.map((c) => c.ownershipRootName));
+        assert.ok(rootNames.has("api"));
+        assert.ok(rootNames.has("db"));
+        assert.match(out.summary, /blast-radius candidate/i);
+    });
+    it("reports no shared-host for a pod alone on its node", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "api-bbb" }));
+        assert.equal(out.hosts.length, 1);
+        assert.equal(out.hosts[0].host.name, "n2");
+        assert.equal(out.hosts[0].ownershipRoots, 1);
+        assert.match(out.summary, /limited shared-host/i);
+    });
+    it("treats a host resource as its own host (incoming RUNS_ON pivot)", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "k8s:node:n1" }));
+        assert.equal(out.target.kind, "node");
+        assert.equal(out.hosts.length, 1);
+        assert.equal(out.hosts[0].host.id, "k8s:node:n1");
+    });
+    it("returns a note when a resource has no RUNS_ON edges", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "pending-1" }));
+        assert.equal(out.hosts.length, 0);
+        assert.match(out.note, /no RUNS_ON/i);
+    });
+    it("surfaces a structured error for unknown resources", async () => {
+        const reg = await makeRegistry();
+        const result = await getBlastRadiusHandler(reg, { resource: "totally-not-here" });
+        assert.equal(result.isError, true);
+        const out = parseTool(result);
+        assert.match(out.error, /No resource found/);
+    });
+    it("uses ownership root, not direct owner, when grouping co-tenants", async () => {
+        // api-aaa is OWNED_BY a ReplicaSet which is OWNED_BY a Deployment.
+        // The blast-radius should bucket api-aaa under the Deployment, not the RS.
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "api-aaa" }));
+        const onN1 = out.hosts[0];
+        const apiBucket = onN1.coTenants.find((c) => c.ownershipRootName === "api");
+        assert.ok(apiBucket, "expected an 'api' deployment bucket on n1");
+        assert.equal(apiBucket.ownershipRootKind, "deployment");
+    });
+});

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type SignalType = "metrics" | "logs" | "traces";
+export type SignalType = "metrics" | "logs" | "traces" | "topology";
 export type HealthStatus = "healthy" | "degraded" | "critical";
 export type Trend = "rising" | "falling" | "stable";
 export type AnomalySeverity = "low" | "medium" | "high";
@@ -151,6 +151,72 @@ export interface LogResult {
     entries: LogEntry[];
     summary: LogSummary;
 }
+/**
+ * A discrete infrastructure entity discovered by a topology-aware connector.
+ *
+ * `kind` and the relation strings on Edge are intentionally open (not unions):
+ * future connectors (vCenter, NetBox, SNMP, ...) will introduce new kinds and
+ * relations. Document common values here, but do not hard-restrict the type.
+ *
+ * `id` is a stable, human-readable canonical key. For Kubernetes we use
+ *   `k8s:<kind>:<namespace>/<name>` for namespaced kinds, `k8s:<kind>:<name>`
+ *   for cluster-scoped kinds. Pod names are ephemeral by design — that's
+ *   acceptable since pods are short-lived; deployments/nodes/services are
+ *   stable. Backend identifiers (e.g. K8s metadata.uid) belong in `attributes`.
+ *
+ * `source` is mandatory so a future entity-resolution layer can merge views
+ * from multiple connectors without ambiguity.
+ *
+ * Common kinds (Kubernetes): "pod", "node", "deployment", "service", "namespace".
+ */
+export interface Resource {
+    id: string;
+    kind: string;
+    name: string;
+    source: string;
+    labels: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * A directed relationship between two Resources.
+ *
+ * Common relations (Kubernetes):
+ *   - "RUNS_ON"      pod -> node, container -> host, vm -> hypervisor
+ *   - "OWNED_BY"     pod -> replicaset/deployment
+ *   - "ROUTES_TO"    service -> pod
+ *   - "IN_NAMESPACE" pod/service/deployment -> namespace
+ *
+ * `confidence` is 0..1. For data that comes straight from an authoritative
+ * source (K8s API), use 1.0. Inferred relations (e.g. label-based matching)
+ * should report lower values.
+ */
+export interface Edge {
+    from: string;
+    to: string;
+    relation: string;
+    source: string;
+    confidence: number;
+}
+/** Snapshot of the topology graph as known by a single connector. */
+export interface TopologySnapshot {
+    source: string;
+    resources: Resource[];
+    edges: Edge[];
+    /** Monotonic counter; bumped on each successful watch event apply. */
+    revision: number;
+}
+/** Event emitted by a watching connector when its in-memory graph changes. */
+export type TopologyChangeEvent = {
+    type: "resource_added" | "resource_updated" | "resource_removed";
+    resource: Resource;
+} | {
+    type: "edge_added" | "edge_removed";
+    edge: Edge;
+} | {
+    type: "resync";
+    snapshot: TopologySnapshot;
+};
+export type TopologyChangeListener = (event: TopologyChangeEvent) => void;
 export interface AnomalyReport {
     metric: string;
     severity: AnomalySeverity;