@thotischner/observability-mcp 1.6.0 → 1.7.1

package/dist/connectors/kubernetes.js

@@ -0,0 +1,195 @@
+import { TopologyStore, podResource, podEdges, nodeResource, deploymentResource, deploymentEdges, replicaSetResource, replicaSetEdges, namespaceResource, namespacedId, clusterScopedId, } from "./kubernetes-graph.js";
+import { validateSnapshot } from "./topology-vocabulary.js";
+// Default provider is loaded lazily so tests don't pay the
+// @kubernetes/client-node import cost (and so the module is usable in
+// environments where the SDK isn't installed yet — e.g. unit tests in CI
+// before the dep lands).
+let defaultProvider;
+export function setDefaultInformerFactoryProvider(p) {
+    defaultProvider = p;
+}
+async function loadDefaultProvider() {
+    if (defaultProvider)
+        return defaultProvider;
+    const mod = await import("./kubernetes-client.js");
+    defaultProvider = mod.createInformerFactory;
+    return defaultProvider;
+}
+export class KubernetesConnector {
+    type = "kubernetes";
+    signalType = "topology";
+    name = "";
+    store;
+    warnedVocab = new Set();
+    factory;
+    informers = [];
+    providerOverride;
+    /** Constructor injection used by tests. */
+    constructor(provider) {
+        this.providerOverride = provider;
+    }
+    async connect(config) {
+        this.name = config.name;
+        this.store = new TopologyStore(config.name);
+        const provider = this.providerOverride ?? (await loadDefaultProvider());
+        this.factory = await provider(config);
+        // Wire each informer to the store. Pure builders translate Kube
+        // objects → Resource/Edge; the store dedupes and emits diffs.
+        const pods = this.factory.pods();
+        pods.on("add", (p) => this.applyPod(p));
+        pods.on("update", (p) => this.applyPod(p));
+        pods.on("delete", (p) => {
+            const id = idOfPod(p);
+            if (id)
+                this.store.removeResource(id);
+        });
+        pods.on("error", (err) => logWatchError(this.name, "pods", err));
+        const nodes = this.factory.nodes();
+        nodes.on("add", (n) => this.applyNode(n));
+        nodes.on("update", (n) => this.applyNode(n));
+        nodes.on("delete", (n) => {
+            const id = idOfNode(n);
+            if (id)
+                this.store.removeResource(id);
+        });
+        nodes.on("error", (err) => logWatchError(this.name, "nodes", err));
+        const deps = this.factory.deployments();
+        deps.on("add", (d) => this.applyDeployment(d));
+        deps.on("update", (d) => this.applyDeployment(d));
+        deps.on("delete", (d) => {
+            const id = idOfNamespaced("deployment", d);
+            if (id)
+                this.store.removeResource(id);
+        });
+        deps.on("error", (err) => logWatchError(this.name, "deployments", err));
+        const rs = this.factory.replicaSets();
+        rs.on("add", (r) => this.applyReplicaSet(r));
+        rs.on("update", (r) => this.applyReplicaSet(r));
+        rs.on("delete", (r) => {
+            const id = idOfNamespaced("replicaset", r);
+            if (id)
+                this.store.removeResource(id);
+        });
+        rs.on("error", (err) => logWatchError(this.name, "replicasets", err));
+        const ns = this.factory.namespaces();
+        ns.on("add", (n) => this.applyNamespace(n));
+        ns.on("update", (n) => this.applyNamespace(n));
+        ns.on("delete", (n) => {
+            const name = n.metadata?.name;
+            if (name)
+                this.store.removeResource(clusterScopedId("namespace", name));
+        });
+        ns.on("error", (err) => logWatchError(this.name, "namespaces", err));
+        this.informers = [pods, nodes, deps, rs, ns];
+        await Promise.all(this.informers.map((i) => i.start()));
+    }
+    applyPod(p) {
+        const r = podResource(this.name, p);
+        if (!r)
+            return;
+        this.store.upsertResource(r, podEdges(this.name, p));
+    }
+    applyNode(n) {
+        const r = nodeResource(this.name, n);
+        if (!r)
+            return;
+        this.store.upsertResource(r, []);
+    }
+    applyDeployment(d) {
+        const r = deploymentResource(this.name, d);
+        if (!r)
+            return;
+        this.store.upsertResource(r, deploymentEdges(this.name, d));
+    }
+    applyReplicaSet(rs) {
+        const r = replicaSetResource(this.name, rs);
+        if (!r)
+            return;
+        this.store.upsertResource(r, replicaSetEdges(this.name, rs));
+    }
+    applyNamespace(n) {
+        const r = namespaceResource(this.name, n);
+        if (!r)
+            return;
+        this.store.upsertResource(r, []);
+    }
+    async healthCheck() {
+        if (!this.factory)
+            return { status: "down", latencyMs: 0, message: "not connected" };
+        const r = await this.factory.healthCheck();
+        return { status: r.ok ? "up" : "down", latencyMs: r.latencyMs, message: r.message };
+    }
+    async disconnect() {
+        await Promise.all(this.informers.map((i) => i.stop().catch(() => { })));
+        this.informers = [];
+        await this.factory?.close().catch(() => { });
+        this.factory = undefined;
+    }
+    // Topology has no metric/service surface — these stay empty/inert.
+    getDefaultMetrics() {
+        return [];
+    }
+    getMetrics() {
+        return [];
+    }
+    async listServices() {
+        return [];
+    }
+    // --- Topology capability ---
+    async listResources() {
+        return this.store?.listResources() ?? [];
+    }
+    async listEdges() {
+        return this.store?.listEdges() ?? [];
+    }
+    async getTopologySnapshot() {
+        const snap = this.store?.snapshot() ?? {
+            source: this.name,
+            resources: [],
+            edges: [],
+            revision: 0,
+        };
+        for (const w of validateSnapshot(snap.resources, snap.edges)) {
+            const key = `${w.kind}:${w.value}`;
+            if (this.warnedVocab.has(key))
+                continue;
+            this.warnedVocab.add(key);
+            console.warn("topology vocabulary warning (source=%s): %s", this.name, w.message);
+        }
+        return snap;
+    }
+    watchTopology(listener) {
+        if (!this.store)
+            return () => { };
+        // Initial resync so subscribers see the current state without
+        // racing the next watch event.
+        queueMicrotask(() => listener({ type: "resync", snapshot: this.store.snapshot() }));
+        return this.store.subscribe(listener);
+    }
+}
+// --- helpers ---
+function idOfPod(p) {
+    const n = p.metadata?.name;
+    const ns = p.metadata?.namespace;
+    if (!n || !ns)
+        return undefined;
+    return namespacedId("pod", ns, n);
+}
+function idOfNode(n) {
+    return n.metadata?.name ? clusterScopedId("node", n.metadata.name) : undefined;
+}
+function idOfNamespaced(kind, obj) {
+    const n = obj.metadata?.name;
+    const ns = obj.metadata?.namespace;
+    if (!n || !ns)
+        return undefined;
+    return namespacedId(kind, ns, n);
+}
+function logWatchError(source, kind, err) {
+    // AbortError is what makeInformer emits when we cleanly stop the watch
+    // (disconnect, process shutdown) — not actually an error to surface.
+    const msg = String(err);
+    if (msg.includes("AbortError") || /aborted a request/i.test(msg))
+        return;
+    console.warn("k8s watch error: source=%s kind=%s err=%s", source, kind, msg);
+}

package/dist/connectors/kubernetes.test.d.ts

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

package/dist/connectors/kubernetes.test.js

@@ -0,0 +1,136 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { KubernetesConnector } from "./kubernetes.js";
+import { isTopologyProvider } from "./interface.js";
+class FakeInformer {
+    handlers = {};
+    started = false;
+    stopped = false;
+    on(event, handler) {
+        (this.handlers[event] ??= []).push(handler);
+    }
+    async start() {
+        this.started = true;
+    }
+    async stop() {
+        this.stopped = true;
+    }
+    emit(event, obj) {
+        for (const h of this.handlers[event] ?? [])
+            h(obj);
+    }
+}
+function makeFakeFactory() {
+    const pods = new FakeInformer();
+    const nodes = new FakeInformer();
+    const deps = new FakeInformer();
+    const rs = new FakeInformer();
+    const ns = new FakeInformer();
+    const factory = {
+        pods: () => pods,
+        nodes: () => nodes,
+        deployments: () => deps,
+        replicaSets: () => rs,
+        namespaces: () => ns,
+        async healthCheck() {
+            return { ok: true, latencyMs: 1 };
+        },
+        async close() { },
+    };
+    return { factory, pods, nodes, deps, rs, ns };
+}
+const CFG = {
+    name: "test-cluster",
+    type: "kubernetes",
+    url: "",
+    enabled: true,
+};
+describe("KubernetesConnector", () => {
+    it("implements the TopologyProvider capability", async () => {
+        const { factory } = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => factory);
+        await conn.connect(CFG);
+        assert.equal(isTopologyProvider(conn), true);
+        assert.equal(conn.signalType, "topology");
+        await conn.disconnect();
+    });
+    it("starts every informer on connect and stops them on disconnect", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        for (const inf of [fake.pods, fake.nodes, fake.deps, fake.rs, fake.ns]) {
+            assert.equal(inf.started, true);
+        }
+        await conn.disconnect();
+        for (const inf of [fake.pods, fake.nodes, fake.deps, fake.rs, fake.ns]) {
+            assert.equal(inf.stopped, true);
+        }
+    });
+    it("builds the graph from watch events", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        fake.nodes.emit("add", { metadata: { name: "worker-1" } });
+        fake.ns.emit("add", { metadata: { name: "default" } });
+        fake.deps.emit("add", { metadata: { name: "checkout", namespace: "default" } });
+        fake.rs.emit("add", {
+            metadata: {
+                name: "checkout-7f89",
+                namespace: "default",
+                ownerReferences: [{ kind: "Deployment", name: "checkout" }],
+            },
+        });
+        fake.pods.emit("add", {
+            metadata: {
+                name: "checkout-7f89d",
+                namespace: "default",
+                ownerReferences: [{ kind: "ReplicaSet", name: "checkout-7f89" }],
+            },
+            spec: { nodeName: "worker-1" },
+        });
+        const snap = await conn.getTopologySnapshot();
+        const ids = snap.resources.map((r) => r.id).sort();
+        assert.deepEqual(ids, [
+            "k8s:deployment:default/checkout",
+            "k8s:namespace:default",
+            "k8s:node:worker-1",
+            "k8s:pod:default/checkout-7f89d",
+            "k8s:replicaset:default/checkout-7f89",
+        ]);
+        // Full RCA chain present: pod → rs → deployment, pod → node, * → namespace.
+        const e = snap.edges;
+        assert.ok(e.some((x) => x.from === "k8s:pod:default/checkout-7f89d" && x.relation === "RUNS_ON"));
+        assert.ok(e.some((x) => x.from === "k8s:pod:default/checkout-7f89d" && x.relation === "OWNED_BY"));
+        assert.ok(e.some((x) => x.from === "k8s:replicaset:default/checkout-7f89" && x.relation === "OWNED_BY"));
+        await conn.disconnect();
+    });
+    it("removes a pod's edges when the pod is deleted", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        const pod = {
+            metadata: { name: "p1", namespace: "default" },
+            spec: { nodeName: "n1" },
+        };
+        fake.pods.emit("add", pod);
+        assert.equal((await conn.listEdges()).length > 0, true);
+        fake.pods.emit("delete", pod);
+        assert.equal((await conn.listResources()).length, 0);
+        assert.equal((await conn.listEdges()).length, 0);
+        await conn.disconnect();
+    });
+    it("watchTopology delivers a resync then live diffs", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        fake.nodes.emit("add", { metadata: { name: "n0" } });
+        const events = [];
+        const unsub = conn.watchTopology((e) => events.push(e));
+        await new Promise((r) => setImmediate(r));
+        assert.equal(events[0]?.type, "resync");
+        fake.nodes.emit("add", { metadata: { name: "n1" } });
+        assert.ok(events.some((e) => e.type === "resource_added"));
+        unsub();
+        await conn.disconnect();
+    });
+});

package/dist/connectors/loader.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from "node:url";
 import { manifestSchema } from "../sdk/manifest-schema.js";
 import { PrometheusConnector } from "./prometheus.js";
 import { LokiConnector } from "./loki.js";
+import { KubernetesConnector } from "./kubernetes.js";
 import { sanitizeForLog } from "../util/sanitize.js";
 import { instrumentConnector } from "../metrics/instrument-connector.js";
 import { loadTrustRoot, verifyIntegrity, verifyManifestSignature, PluginVerificationError, } from "./verify.js";
@@ -96,6 +97,11 @@ export class PluginLoader {
             source: "builtin",
             factory: () => new LokiConnector(),
         });
+        this.register({
+            name: "kubernetes",
+            source: "builtin",
+            factory: () => new KubernetesConnector(),
+        });
     }
     async loadFilesystem() {
         const dir = this.pluginsDir;

package/dist/connectors/topology-vocabulary.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical vocabulary for the connector-agnostic topology graph.
+ *
+ * The set is intentionally small: only values that are emitted by a shipped
+ * connector OR are reserved as the agreed name for a near-term connector.
+ * Adding a value is a documentation change in docs/topology-vocabulary.md
+ * plus an entry in the const arrays below; never invent a value at the call
+ * site without that paper trail.
+ *
+ * Validation is warn-only by design — a connector that emits an unknown
+ * value still works, but the warning shows up in logs and unit tests so
+ * vocabulary drift gets caught before it spreads.
+ */
+import type { Edge, Resource } from "../types.js";
+export declare const KINDS: readonly ["pod", "node", "deployment", "replicaset", "namespace", "service", "container", "vm", "host", "hypervisor", "cluster"];
+export type Kind = (typeof KINDS)[number];
+export declare const RELATIONS: readonly ["RUNS_ON", "OWNED_BY", "IN_NAMESPACE", "CALLS", "CONTAINS", "DEPENDS_ON"];
+export type Relation = (typeof RELATIONS)[number];
+export declare function isKnownKind(k: string): k is Kind;
+export declare function isKnownRelation(r: string): r is Relation;
+export interface VocabularyWarning {
+    kind: "unknown_resource_kind" | "unknown_relation" | "case_mismatch";
+    message: string;
+    value: string;
+}
+/**
+ * Lint a single resource. Returns warnings for unknown or miscased `kind`
+ * values; an empty array means the resource passes the vocabulary.
+ */
+export declare function validateResource(r: Pick<Resource, "kind">): VocabularyWarning[];
+/**
+ * Lint a single edge. Returns warnings for unknown or miscased `relation`
+ * values; an empty array means the edge passes the vocabulary.
+ */
+export declare function validateEdge(e: Pick<Edge, "relation">): VocabularyWarning[];
+/**
+ * Convenience: lint a full snapshot. Returns the de-duplicated set of
+ * warnings (one per distinct value) so a noisy connector does not flood
+ * the log on each tick.
+ */
+export declare function validateSnapshot(resources: Pick<Resource, "kind">[], edges: Pick<Edge, "relation">[]): VocabularyWarning[];

package/dist/connectors/topology-vocabulary.js

@@ -0,0 +1,120 @@
+/**
+ * Canonical vocabulary for the connector-agnostic topology graph.
+ *
+ * The set is intentionally small: only values that are emitted by a shipped
+ * connector OR are reserved as the agreed name for a near-term connector.
+ * Adding a value is a documentation change in docs/topology-vocabulary.md
+ * plus an entry in the const arrays below; never invent a value at the call
+ * site without that paper trail.
+ *
+ * Validation is warn-only by design — a connector that emits an unknown
+ * value still works, but the warning shows up in logs and unit tests so
+ * vocabulary drift gets caught before it spreads.
+ */
+export const KINDS = [
+    "pod",
+    "node",
+    "deployment",
+    "replicaset",
+    "namespace",
+    "service",
+    "container",
+    "vm",
+    "host",
+    "hypervisor",
+    "cluster",
+];
+export const RELATIONS = [
+    "RUNS_ON",
+    "OWNED_BY",
+    "IN_NAMESPACE",
+    "CALLS",
+    "CONTAINS",
+    "DEPENDS_ON",
+];
+const KIND_SET = new Set(KINDS);
+const RELATION_SET = new Set(RELATIONS);
+export function isKnownKind(k) {
+    return KIND_SET.has(k);
+}
+export function isKnownRelation(r) {
+    return RELATION_SET.has(r);
+}
+/**
+ * Lint a single resource. Returns warnings for unknown or miscased `kind`
+ * values; an empty array means the resource passes the vocabulary.
+ */
+export function validateResource(r) {
+    const out = [];
+    if (!isKnownKind(r.kind)) {
+        const lower = r.kind.toLowerCase();
+        if (isKnownKind(lower)) {
+            out.push({
+                kind: "case_mismatch",
+                value: r.kind,
+                message: `resource kind "${r.kind}" should be lowercase "${lower}" — see docs/topology-vocabulary.md`,
+            });
+        }
+        else {
+            out.push({
+                kind: "unknown_resource_kind",
+                value: r.kind,
+                message: `resource kind "${r.kind}" is not in the canonical vocabulary; either rename or extend docs/topology-vocabulary.md + KINDS`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Lint a single edge. Returns warnings for unknown or miscased `relation`
+ * values; an empty array means the edge passes the vocabulary.
+ */
+export function validateEdge(e) {
+    const out = [];
+    if (!isKnownRelation(e.relation)) {
+        const upper = e.relation.toUpperCase();
+        if (isKnownRelation(upper)) {
+            out.push({
+                kind: "case_mismatch",
+                value: e.relation,
+                message: `relation "${e.relation}" should be UPPER_SNAKE "${upper}" — see docs/topology-vocabulary.md`,
+            });
+        }
+        else {
+            out.push({
+                kind: "unknown_relation",
+                value: e.relation,
+                message: `relation "${e.relation}" is not in the canonical vocabulary; either rename or extend docs/topology-vocabulary.md + RELATIONS`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Convenience: lint a full snapshot. Returns the de-duplicated set of
+ * warnings (one per distinct value) so a noisy connector does not flood
+ * the log on each tick.
+ */
+export function validateSnapshot(resources, edges) {
+    const seen = new Set();
+    const out = [];
+    for (const r of resources) {
+        for (const w of validateResource(r)) {
+            const key = `r:${w.kind}:${w.value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(w);
+            }
+        }
+    }
+    for (const e of edges) {
+        for (const w of validateEdge(e)) {
+            const key = `e:${w.kind}:${w.value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(w);
+            }
+        }
+    }
+    return out;
+}

package/dist/connectors/topology-vocabulary.test.d.ts

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

package/dist/connectors/topology-vocabulary.test.js

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { KINDS, RELATIONS, isKnownKind, isKnownRelation, validateResource, validateEdge, validateSnapshot, } from "./topology-vocabulary.js";
+test("vocabulary — KINDS and RELATIONS contain what the kubernetes connector emits today", () => {
+    for (const k of ["pod", "node", "deployment", "replicaset", "namespace"]) {
+        assert.equal(isKnownKind(k), true, `kind "${k}" must be in the canonical vocabulary`);
+    }
+    for (const r of ["RUNS_ON", "OWNED_BY", "IN_NAMESPACE"]) {
+        assert.equal(isKnownRelation(r), true, `relation "${r}" must be in the canonical vocabulary`);
+    }
+});
+test("vocabulary — CALLS is reserved for the upcoming trace connector", () => {
+    assert.equal(isKnownRelation("CALLS"), true);
+});
+test("validateResource — canonical kinds produce no warnings", () => {
+    for (const k of KINDS) {
+        assert.deepEqual(validateResource({ kind: k }), []);
+    }
+});
+test("validateResource — unknown kind warns", () => {
+    const w = validateResource({ kind: "frobnicator" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "unknown_resource_kind");
+    assert.equal(w[0].value, "frobnicator");
+});
+test("validateResource — uppercase kind triggers a case-mismatch hint", () => {
+    const w = validateResource({ kind: "Pod" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "case_mismatch");
+    assert.match(w[0].message, /lowercase "pod"/);
+});
+test("validateEdge — canonical relations produce no warnings", () => {
+    for (const r of RELATIONS) {
+        assert.deepEqual(validateEdge({ relation: r }), []);
+    }
+});
+test("validateEdge — unknown relation warns", () => {
+    const w = validateEdge({ relation: "FROBNICATES" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "unknown_relation");
+});
+test("validateEdge — lowercase relation triggers a case-mismatch hint", () => {
+    const w = validateEdge({ relation: "runs_on" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "case_mismatch");
+    assert.match(w[0].message, /UPPER_SNAKE "RUNS_ON"/);
+});
+test("validateSnapshot — de-duplicates repeated offenders", () => {
+    const warnings = validateSnapshot([
+        { kind: "frobnicator" },
+        { kind: "frobnicator" },
+        { kind: "pod" },
+    ], [
+        { relation: "FROBNICATES" },
+        { relation: "FROBNICATES" },
+        { relation: "RUNS_ON" },
+    ]);
+    assert.equal(warnings.length, 2, `expected one warning per distinct offender, got ${warnings.length}`);
+});
+test("validateSnapshot — a fully canonical snapshot is silent", () => {
+    const warnings = validateSnapshot([{ kind: "pod" }, { kind: "node" }, { kind: "deployment" }], [{ relation: "RUNS_ON" }, { relation: "OWNED_BY" }, { relation: "IN_NAMESPACE" }]);
+    assert.deepEqual(warnings, []);
+});

package/dist/connectors/topology.test.d.ts

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