@shortlink-org/portolan 0.3.0 → 0.4.0

package/scripts/host-plugins/k8s-topology.mjs

@@ -0,0 +1,183 @@
+// The part of reading Kubernetes objects that does not care where they came
+// from: which names a workload answers on, and which in-cluster names it is
+// configured to dial. fetch-k8s hands it what `kubectl get -o json` said;
+// the same rules, in Go, read the manifests in a repository (extract-k8s),
+// and the two are held together by the same table of cases in their tests.
+//
+// Nothing here writes a value. A value is looked at once, for one question -
+// does it name a host inside the cluster - and the host alone survives.
+
+export const WORKLOAD_KINDS = {
+  Deployment: "",
+  StatefulSet: "",
+  DaemonSet: "",
+  ReplicaSet: "",
+  Job: "job",
+  CronJob: "job",
+};
+
+/** Every DNS form the cluster answers for one Service. */
+export function hostForms(name, namespace) {
+  const ns = namespace || "default";
+  return [name, `${name}.${ns}`, `${name}.${ns}.svc`, `${name}.${ns}.svc.cluster.local`];
+}
+
+const BARE_HOST = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[0-9]+)?$/;
+// A name only a cluster's DNS answers for, which is what lets a name from
+// another namespace's Service through: nothing else looks like `pricing.shop.svc`.
+const SVC_FORM = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?\.[a-z0-9]([a-z0-9-]*[a-z0-9])?\.svc(\.cluster\.local)?$/;
+
+/**
+ * The in-cluster host a configured value names, or undefined. A URL gives up
+ * its hostname and keeps nothing else - not the scheme, port, path, query,
+ * nor the user and password in front of the host. A bare `host[:port]`
+ * gives up the port. What is left qualifies when the tree's own Services
+ * answer to it, or when it has the `<name>.<namespace>.svc` shape. A
+ * password, a token, a level, a flag: none is a host, and none passes.
+ *
+ * @param {string} value
+ * @param {Set<string>} known
+ */
+export function hostOnly(value, known) {
+  const trimmed = String(value ?? "").trim();
+  if (!trimmed) return undefined;
+  let host;
+  if (trimmed.includes("://")) {
+    try {
+      host = new URL(trimmed).hostname.toLowerCase();
+    } catch {
+      return undefined;
+    }
+  } else {
+    const lower = trimmed.toLowerCase();
+    if (!BARE_HOST.test(lower)) return undefined;
+    host = lower.replace(/:[0-9]+$/, "");
+  }
+  if (!host) return undefined;
+  return known.has(host) || SVC_FORM.test(host) ? host : undefined;
+}
+
+/** Whether a Service's selector matches a pod's labels: every key, with its value. */
+export function selects(selector, podLabels) {
+  const keys = Object.keys(selector ?? {});
+  if (keys.length === 0) return false;
+  return keys.every((key) => (podLabels ?? {})[key] === selector[key]);
+}
+
+export function podTemplate(object) {
+  const spec = object.spec ?? {};
+  if (object.kind === "CronJob") return spec.jobTemplate?.spec?.template ?? {};
+  return spec.template ?? {};
+}
+
+/**
+ * Every configured value of one container this reader may look at: a literal
+ * `value`, a `configMapKeyRef` followed into the ConfigMaps read, and what an
+ * `envFrom.configMapRef` brings in. A `secretKeyRef` or `secretRef` is not
+ * followed, by rule.
+ */
+export function containerValues(container, namespace, configMaps) {
+  const out = [];
+  for (const env of container.env ?? []) {
+    if (typeof env.value === "string" && env.value.trim()) {
+      out.push(env.value);
+      continue;
+    }
+    const ref = env.valueFrom?.configMapKeyRef;
+    if (!ref) continue;
+    const data = configMaps.get(`${namespace}/${ref.name ?? ""}`);
+    if (data && Object.hasOwn(data, ref.key ?? "")) out.push(String(data[ref.key]));
+  }
+  for (const from of container.envFrom ?? []) {
+    const ref = from.configMapRef;
+    if (!ref) continue;
+    const data = configMaps.get(`${namespace}/${ref.name ?? ""}`) ?? {};
+    for (const key of Object.keys(data).sort()) out.push(String(data[key]));
+  }
+  return out;
+}
+
+/** The hosts an Ingress or a Gateway API route answers on for the named Services. */
+export function frontingHosts(objects, backends) {
+  const out = [];
+  for (const object of objects) {
+    const spec = object.spec ?? {};
+    if (object.kind === "Ingress") {
+      const rules = Array.isArray(spec.rules) ? spec.rules : [];
+      if (backends.has(spec.defaultBackend?.service?.name ?? "")) {
+        for (const rule of rules) if (rule.host) out.push(rule.host);
+      }
+      for (const rule of rules) {
+        if (!rule.host) continue;
+        const paths = Array.isArray(rule.http?.paths) ? rule.http.paths : [];
+        if (paths.some((path) => backends.has(path.backend?.service?.name ?? ""))) out.push(rule.host);
+      }
+    } else if (["HTTPRoute", "GRPCRoute", "TLSRoute"].includes(object.kind)) {
+      const hostnames = Array.isArray(spec.hostnames) ? spec.hostnames : [];
+      if (hostnames.length === 0) continue;
+      const rules = Array.isArray(spec.rules) ? spec.rules : [];
+      if (rules.some((rule) => (rule.backendRefs ?? []).some((ref) => backends.has(ref.name ?? "")))) out.push(...hostnames);
+    }
+  }
+  return out;
+}
+
+function sortedUnique(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+/**
+ * Every workload among the objects, with the names it answers on and the
+ * names it dials. Objects are what the API returned: `kind`, `metadata`,
+ * `spec`, and for a ConfigMap `data`. A Secret is never among them, because
+ * it is never asked for.
+ *
+ * @returns {{object: object, kind: string, hosts: string[], dials: string[]}[]}
+ */
+export function topology(objects) {
+  const configMaps = new Map();
+  const services = [];
+  const known = new Set();
+  for (const object of objects) {
+    const ns = object.metadata?.namespace ?? "";
+    const name = object.metadata?.name ?? "";
+    if (!name) continue;
+    if (object.kind === "ConfigMap") {
+      const data = configMaps.get(`${ns}/${name}`) ?? {};
+      for (const [key, value] of Object.entries(object.data ?? {})) data[key] = value;
+      configMaps.set(`${ns}/${name}`, data);
+    } else if (object.kind === "Service") {
+      services.push({ name, namespace: ns, selector: object.spec?.selector ?? {} });
+      for (const form of hostForms(name, ns)) known.add(form);
+    }
+  }
+
+  const out = [];
+  for (const object of objects) {
+    if (!Object.hasOwn(WORKLOAD_KINDS, object.kind ?? "")) continue;
+    const ns = object.metadata?.namespace ?? "";
+    if (!object.metadata?.name) continue;
+    const template = podTemplate(object);
+    const podLabels = template.metadata?.labels ?? {};
+    const backends = new Set();
+    const hosts = [];
+    for (const service of services) {
+      if (service.namespace === ns && selects(service.selector, podLabels)) {
+        hosts.push(...hostForms(service.name, service.namespace));
+        backends.add(service.name);
+      }
+    }
+    hosts.push(...frontingHosts(objects.filter((o) => (o.metadata?.namespace ?? "") === ns), backends));
+    const own = new Set(hosts);
+    const dials = [];
+    const spec = template.spec ?? {};
+    for (const container of [...(spec.initContainers ?? []), ...(spec.containers ?? [])]) {
+      for (const value of containerValues(container, ns, configMaps)) {
+        const host = hostOnly(value, known);
+        if (host && !own.has(host)) dials.push(host);
+      }
+    }
+    out.push({ object, kind: WORKLOAD_KINDS[object.kind], hosts: sortedUnique(hosts), dials: sortedUnique(dials) });
+  }
+  return out;
+}

package/scripts/json-format.mjs

@@ -0,0 +1,192 @@
+// Writes a JSON value the way the file already on disk writes it.
+//
+// A manifest is edited by hand and by the page, and the two must not fight:
+// a page that adds one glob to one array and rewrites every other array in
+// the file has made a diff nobody can review. So the value is written against
+// the old text. A subtree that did not change is copied out of the old text
+// byte for byte; one that did is written in the style its old self had - an
+// array on one line stays on one line, one spread over lines stays spread -
+// and only something with no old self at all gets the default shape: scalars
+// on one line, objects and arrays of objects spread.
+
+/** A parsed value with where it sat in the text it came from. */
+class Node {
+  constructor(type, start, end, value) {
+    this.type = type;
+    this.start = start;
+    this.end = end;
+    this.value = value;
+    /** For objects: key -> Node, in source order. For arrays: Node[]. */
+    this.children = type === "object" ? new Map() : type === "array" ? [] : null;
+  }
+}
+
+/**
+ * Parses JSON into nodes that remember their source range. Strict JSON, the
+ * same grammar JSON.parse accepts; anything else throws, and the caller
+ * falls back to writing from scratch.
+ */
+export function parseWithRanges(text) {
+  let at = 0;
+  const skip = () => {
+    while (at < text.length && /\s/.test(text[at])) at += 1;
+  };
+  const expect = (ch) => {
+    if (text[at] !== ch) throw new SyntaxError(`Expected ${ch} at ${at}`);
+    at += 1;
+  };
+  const scalarEnd = () => {
+    if (text[at] === '"') {
+      let i = at + 1;
+      while (i < text.length) {
+        if (text[i] === "\\") i += 2;
+        else if (text[i] === '"') return i + 1;
+        else i += 1;
+      }
+      throw new SyntaxError("Unterminated string");
+    }
+    const m = /^(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)/.exec(text.slice(at));
+    if (!m) throw new SyntaxError(`Unexpected token at ${at}`);
+    return at + m[0].length;
+  };
+  const value = () => {
+    skip();
+    const start = at;
+    if (text[at] === "{") {
+      at += 1;
+      const node = new Node("object", start, 0, {});
+      skip();
+      if (text[at] === "}") {
+        at += 1;
+        node.end = at;
+        return node;
+      }
+      for (;;) {
+        skip();
+        const keyEnd = scalarEnd();
+        if (text[at] !== '"') throw new SyntaxError(`Expected a key at ${at}`);
+        const key = JSON.parse(text.slice(at, keyEnd));
+        at = keyEnd;
+        skip();
+        expect(":");
+        const child = value();
+        node.children.set(key, child);
+        node.value[key] = child.value;
+        skip();
+        if (text[at] === ",") {
+          at += 1;
+
+          continue;
+        }
+        expect("}");
+        node.end = at;
+
+        return node;
+      }
+    }
+    if (text[at] === "[") {
+      at += 1;
+      const node = new Node("array", start, 0, []);
+      skip();
+      if (text[at] === "]") {
+        at += 1;
+        node.end = at;
+        return node;
+      }
+      for (;;) {
+        const child = value();
+        node.children.push(child);
+        node.value.push(child.value);
+        skip();
+        if (text[at] === ",") {
+          at += 1;
+
+          continue;
+        }
+        expect("]");
+        node.end = at;
+
+        return node;
+      }
+    }
+    const end = scalarEnd();
+    const node = new Node("scalar", start, end, JSON.parse(text.slice(start, end)));
+    at = end;
+
+    return node;
+  };
+  const root = value();
+  skip();
+  if (at !== text.length) throw new SyntaxError(`Trailing content at ${at}`);
+
+  return root;
+}
+
+function same(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) return a.length === b.length && a.every((item, i) => same(item, b[i]));
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+
+  return keys.every((key) => Object.hasOwn(b, key) && same(a[key], b[key]));
+}
+
+function isScalar(value) {
+  return value === null || typeof value !== "object";
+}
+
+/** The indent step the old text uses, or two spaces. */
+function indentOf(text) {
+  const m = /\n([ \t]+)\S/.exec(text);
+
+  return m ? m[1] : "  ";
+}
+
+/**
+ * Writes `value` in the style of `oldText`. Keys already in the old text
+ * keep their order; new keys go after them. A value with no old self is
+ * written the default way.
+ */
+export function formatLike(oldText, value) {
+  let root = null;
+  try {
+    root = parseWithRanges(oldText);
+  } catch {
+    return JSON.stringify(value, null, 2);
+  }
+  const step = indentOf(oldText);
+  const slice = (node) => oldText.slice(node.start, node.end);
+  const multiline = (node) => slice(node).includes("\n");
+
+  const write = (node, next, indent) => {
+    if (node && same(node.value, next)) return slice(node);
+    if (isScalar(next)) return JSON.stringify(next);
+    const inner = indent + step;
+
+    if (Array.isArray(next)) {
+      if (next.length === 0) return "[]";
+      const old = node && node.type === "array" ? node : null;
+      const spread = old ? multiline(old) : !next.every(isScalar);
+      const items = next.map((item, i) => write(old?.children[i], item, spread ? inner : indent));
+      if (!spread) return "[" + items.join(", ") + "]";
+
+      return "[\n" + items.map((item) => inner + item).join(",\n") + "\n" + indent + "]";
+    }
+
+    const keys = Object.keys(next);
+    if (keys.length === 0) return "{}";
+    const old = node && node.type === "object" ? node : null;
+    const ordered = old
+      ? [...[...old.children.keys()].filter((key) => Object.hasOwn(next, key)), ...keys.filter((key) => !old.children.has(key))]
+      : keys;
+    const spread = old ? multiline(old) : true;
+    const entries = ordered.map((key) => JSON.stringify(key) + ": " + write(old?.children.get(key), next[key], spread ? inner : indent));
+    if (!spread) return "{ " + entries.join(", ") + " }";
+
+    return "{\n" + entries.map((entry) => inner + entry).join(",\n") + "\n" + indent + "}";
+  };
+
+  return write(root, value, "");
+}

package/scripts/json-format.test.mjs

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+import { formatLike, parseWithRanges } from "./json-format.mjs";
+
+const manifest = `{
+  "$schema": "./schema/portolan.schema.json",
+  "sources": ["portolan/*.json", "examples/*/portolan/*.json"],
+  "projects": [
+    {
+      "id": "auth",
+      "root": "examples/auth"
+    }
+  ],
+  "verify": [
+    {
+      "plugin": "otel",
+      "in": "examples/auth",
+      "options": {
+        "traces": [
+          "telemetry/traces.jsonl"
+        ],
+        "out": "observed.json"
+      }
+    }
+  ],
+  "empty": [],
+  "number": 1e3
+}`;
+
+function lines(a, b) {
+  const x = a.split("\n");
+  const y = b.split("\n");
+  return y.filter((line) => !x.includes(line));
+}
+
+describe("writing a value the way the file already writes it", () => {
+  it("copies the text back byte for byte when nothing changed", () => {
+    expect(formatLike(manifest, JSON.parse(manifest))).toBe(manifest);
+  });
+
+  it("changes only the line that changed, in the style the array had", () => {
+    const next = JSON.parse(manifest);
+    next.verify[0].options.traces.push("telemetry/recordings/*.jsonl");
+    next.sources.push("data/*.json");
+    const out = formatLike(manifest, next);
+
+    expect(JSON.parse(out)).toEqual(next);
+    expect(lines(manifest, out)).toEqual([
+      '  "sources": ["portolan/*.json", "examples/*/portolan/*.json", "data/*.json"],',
+      '          "telemetry/traces.jsonl",',
+      '          "telemetry/recordings/*.jsonl"',
+    ]);
+  });
+
+  it("keeps the old key order and appends a new key after it", () => {
+    const next = { ...JSON.parse(manifest), added: { a: 1 } };
+    delete next.empty;
+    const out = formatLike(manifest, next);
+
+    expect(out.indexOf('"$schema"')).toBeLessThan(out.indexOf('"sources"'));
+    expect(out).not.toContain('"empty"');
+    expect(out.endsWith('  "number": 1e3,\n  "added": {\n    "a": 1\n  }\n}')).toBe(true);
+  });
+
+  it("writes something with no old self the default way: scalars inline, objects spread", () => {
+    const next = JSON.parse(manifest);
+    next.verify.push({ plugin: "codeowners", in: ".github", out: "data", options: { files: ["CODEOWNERS"], nested: [{ a: 1 }] } });
+    const out = formatLike(manifest, next);
+
+    expect(JSON.parse(out)).toEqual(next);
+    expect(out).toContain('    {\n      "plugin": "codeowners",\n      "in": ".github",\n      "out": "data",\n      "options": {\n        "files": ["CODEOWNERS"],\n        "nested": [\n          {\n            "a": 1\n          }\n        ]\n      }\n    }\n  ],');
+  });
+
+  it("keeps a spread array spread even when an element is replaced", () => {
+    const next = JSON.parse(manifest);
+    next.verify[0].options.traces = ["telemetry/other.jsonl"];
+    const out = formatLike(manifest, next);
+    expect(out).toContain('"traces": [\n          "telemetry/other.jsonl"\n        ],');
+  });
+
+  it("falls back to plain JSON when the old text is not JSON", () => {
+    expect(formatLike("not json", { a: [1, 2] })).toBe('{\n  "a": [\n    1,\n    2\n  ]\n}');
+  });
+
+  it("reads the repository's own manifest back unchanged", () => {
+    const text = readFileSync(new URL("../portolan.json", import.meta.url), "utf8").replace(/\n$/, "");
+    expect(parseWithRanges(text).value).toEqual(JSON.parse(text));
+    expect(formatLike(text, JSON.parse(text))).toBe(text);
+  });
+
+  it("parses strings with escapes and rejects what JSON.parse rejects", () => {
+    expect(parseWithRanges('{"a": "x\\"y", "b": [true, null, -1.5e2]}').value).toEqual({ a: 'x"y', b: [true, null, -150] });
+    expect(() => parseWithRanges('{"a": 1,}')).toThrow();
+    expect(() => parseWithRanges("[1] 2")).toThrow();
+  });
+});