@celilo/cli 1.12.0 → 1.13.0

package/src/console/closure.test.ts

@@ -0,0 +1,246 @@
+/**
+ * The six graph shapes the plan names, five of which the live fleet produced.
+ *
+ * They are here rather than in an e2e suite because every one of them is a
+ * property of the walk, and a walk is testable without a fleet.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../manifest/schema';
+import type { ProviderRow, ProviderState } from '../services/consumer-cleanup';
+import { DEFAULT_CLOSURE_DEPTH, UNBOUNDED_CLOSURE_DEPTH, computeClosure } from './closure';
+
+/** Only the two capability lists matter here; the rest of a manifest does not. */
+function manifest(spec: { requires?: string[]; optional?: string[] }): ModuleManifest {
+  return {
+    requires: { capabilities: (spec.requires ?? []).map((name) => ({ name })) },
+    optional: { capabilities: (spec.optional ?? []).map((name) => ({ name })) },
+  } as unknown as ModuleManifest;
+}
+
+function deployed(...moduleIds: string[]): ProviderState[] {
+  return moduleIds.map((moduleId) => ({ moduleId, state: 'VERIFIED' }));
+}
+
+describe('computeClosure', () => {
+  test('follows an optional-only edge, and marks it optional', () => {
+    // The live case: a module reaches the internal resolver ONLY optionally.
+    // Following `requires` alone drops the resolver while looking complete.
+    const rows: ProviderRow[] = [{ moduleId: 'technitium', capabilityName: 'dns_internal' }];
+    const result = computeClosure({
+      rootModuleId: 'wireguard-manager',
+      manifests: new Map([['wireguard-manager', manifest({ optional: ['dns_internal'] })]]),
+      providerRows: rows,
+      providerStates: deployed('technitium'),
+    });
+
+    expect(result.nodes).toHaveLength(1);
+    expect(result.nodes[0]?.moduleId).toBe('technitium');
+    expect(result.nodes[0]?.optional).toBe(true);
+  });
+
+  test('a module reached both ways is not optional', () => {
+    const rows: ProviderRow[] = [
+      { moduleId: 'caddy', capabilityName: 'private_web' },
+      { moduleId: 'caddy', capabilityName: 'public_web' },
+    ];
+    const result = computeClosure({
+      rootModuleId: 'app',
+      manifests: new Map([
+        ['app', manifest({ requires: ['private_web'], optional: ['public_web'] })],
+      ]),
+      providerRows: rows,
+      providerStates: deployed('caddy'),
+    });
+
+    expect(result.nodes[0]?.optional).toBe(false);
+    expect(result.nodes[0]?.via).toEqual(['private_web', 'public_web']);
+  });
+
+  test('the default depth excludes a three-hop dependency', () => {
+    const rows: ProviderRow[] = [
+      { moduleId: 'b', capabilityName: 'cap_b' },
+      { moduleId: 'c', capabilityName: 'cap_c' },
+      { moduleId: 'd', capabilityName: 'cap_d' },
+    ];
+    const manifests = new Map([
+      ['a', manifest({ requires: ['cap_b'] })],
+      ['b', manifest({ requires: ['cap_c'] })],
+      ['c', manifest({ requires: ['cap_d'] })],
+      ['d', manifest({})],
+    ]);
+    const result = computeClosure({
+      rootModuleId: 'a',
+      manifests,
+      providerRows: rows,
+      providerStates: deployed('b', 'c', 'd'),
+    });
+
+    expect(result.depth).toBe(DEFAULT_CLOSURE_DEPTH);
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['b', 'c']);
+    expect(result.truncated).toBe(true);
+  });
+
+  test('an unbounded walk terminates on a cycle, listing each module once', () => {
+    // caddy requires authentik, authentik requires caddy. The real graph.
+    const rows: ProviderRow[] = [
+      { moduleId: 'authentik', capabilityName: 'idp' },
+      { moduleId: 'caddy', capabilityName: 'private_web' },
+    ];
+    const manifests = new Map([
+      ['caddy', manifest({ requires: ['idp'] })],
+      ['authentik', manifest({ requires: ['private_web'] })],
+    ]);
+    const result = computeClosure({
+      rootModuleId: 'caddy',
+      manifests,
+      providerRows: rows,
+      providerStates: deployed('caddy', 'authentik'),
+      depth: UNBOUNDED_CLOSURE_DEPTH,
+    });
+
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['authentik']);
+    expect(result.truncated).toBe(false);
+  });
+
+  test('a capability with several providers highlights every one', () => {
+    // firewall is deliberately multi-provider: an edge provider plus inner layers.
+    const rows: ProviderRow[] = [
+      { moduleId: 'iptables', capabilityName: 'firewall' },
+      { moduleId: 'opnsense', capabilityName: 'firewall' },
+    ];
+    const result = computeClosure({
+      rootModuleId: 'app',
+      manifests: new Map([['app', manifest({ requires: ['firewall'] })]]),
+      providerRows: rows,
+      providerStates: deployed('iptables', 'opnsense'),
+    });
+
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['iptables', 'opnsense']);
+  });
+
+  test('a module that depends on nothing returns an empty closure, not a failure', () => {
+    const result = computeClosure({
+      rootModuleId: 'standalone',
+      manifests: new Map([['standalone', manifest({})]]),
+      providerRows: [],
+      providerStates: [],
+    });
+
+    expect(result.nodes).toEqual([]);
+    expect(result.truncated).toBe(false);
+  });
+
+  test('a module that provides what it consumes is not its own dependency', () => {
+    const rows: ProviderRow[] = [
+      { moduleId: 'caddy', capabilityName: 'private_web' },
+      { moduleId: 'other', capabilityName: 'private_web' },
+    ];
+    const result = computeClosure({
+      rootModuleId: 'caddy',
+      manifests: new Map([['caddy', manifest({ requires: ['private_web'] })]]),
+      providerRows: rows,
+      providerStates: deployed('caddy', 'other'),
+    });
+
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['other']);
+  });
+
+  test('the shortest hop wins when a module is reachable two ways', () => {
+    const rows: ProviderRow[] = [
+      { moduleId: 'b', capabilityName: 'cap_b' },
+      { moduleId: 'shared', capabilityName: 'cap_shared' },
+      { moduleId: 'shared', capabilityName: 'cap_deep' },
+    ];
+    const manifests = new Map([
+      ['a', manifest({ requires: ['cap_b', 'cap_shared'] })],
+      ['b', manifest({ requires: ['cap_deep'] })],
+      ['shared', manifest({})],
+    ]);
+    const result = computeClosure({
+      rootModuleId: 'a',
+      manifests,
+      providerRows: rows,
+      providerStates: deployed('b', 'shared'),
+    });
+
+    const shared = result.nodes.find((n) => n.moduleId === 'shared');
+    expect(shared?.hop).toBe(1);
+  });
+});
+
+describe('the walk follows real bindings, not declarations', () => {
+  const rows: ProviderRow[] = [
+    { moduleId: 'cpanel', capabilityName: 'external_web' },
+    { moduleId: 'caddy', capabilityName: 'public_web' },
+    { moduleId: 'forgejo', capabilityName: 'source_forge' },
+  ];
+  const manifests = new Map([
+    ['site', manifest({ optional: ['external_web', 'public_web', 'source_forge'] })],
+    ['cpanel', manifest({})],
+    ['caddy', manifest({})],
+    ['forgejo', manifest({})],
+  ]);
+
+  test('a declared capability the module never called into is NOT a dependency', () => {
+    // The tango-nexus case, which is what celilo#1072 was filed for: four
+    // optional declarations, one actual binding. Following the declarations
+    // claims the module is standing on three things it has never touched.
+    const result = computeClosure({
+      rootModuleId: 'site',
+      manifests,
+      providerRows: rows,
+      providerStates: deployed('cpanel', 'caddy', 'forgejo'),
+      bindings: new Map([['site', new Map([['external_web', 'cpanel']])]]),
+    });
+
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['cpanel']);
+  });
+
+  test('without bindings the walk falls back to declarations, and says more', () => {
+    // Not a silent fallback: the caller decides. A walk with no binding data
+    // answers "what could this reach", which is a different and still useful
+    // question, and it must not be mistaken for the other one.
+    const result = computeClosure({
+      rootModuleId: 'site',
+      manifests,
+      providerRows: rows,
+      providerStates: deployed('cpanel', 'caddy', 'forgejo'),
+    });
+
+    expect(result.nodes.map((n) => n.moduleId).sort()).toEqual(['caddy', 'cpanel', 'forgejo']);
+  });
+
+  test('a binding to a DIFFERENT provider of the same capability is not followed', () => {
+    // firewall has several live providers. A consumer bound to one of them is
+    // not thereby standing on the others.
+    const multi: ProviderRow[] = [
+      { moduleId: 'iptables', capabilityName: 'firewall' },
+      { moduleId: 'axon', capabilityName: 'firewall' },
+    ];
+    const result = computeClosure({
+      rootModuleId: 'app',
+      manifests: new Map([
+        ['app', manifest({ requires: ['firewall'] })],
+        ['iptables', manifest({})],
+        ['axon', manifest({})],
+      ]),
+      providerRows: multi,
+      providerStates: deployed('iptables', 'axon'),
+      bindings: new Map([['app', new Map([['firewall', 'iptables']])]]),
+    });
+
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['iptables']);
+  });
+
+  test('a module with no bindings at all depends on nothing', () => {
+    const result = computeClosure({
+      rootModuleId: 'site',
+      manifests,
+      providerRows: rows,
+      providerStates: deployed('cpanel', 'caddy', 'forgejo'),
+      bindings: new Map([['site', new Map()]]),
+    });
+
+    expect(result.nodes).toEqual([]);
+  });
+});

package/src/console/closure.ts

@@ -0,0 +1,208 @@
+/**
+ * The bounded capability closure: which modules a selected module stands on.
+ *
+ * Pure, so the console's central question is answerable without a database and
+ * the awkward graph shapes below are testable directly.
+ *
+ * The edge is `planConsumerCleanup()`'s edge, called rather than copied. That
+ * function already answers "which providers does this module reach", already
+ * counts `requires` AND `optional` as dependency edges, and already handles the
+ * two cases a fresh implementation gets wrong: a capability with several
+ * providers (firewall has an edge provider plus inner layers, all of them real)
+ * and a module that both provides and consumes a capability, which must not
+ * become its own dependency. A second walk would drift from it.
+ *
+ * What this adds is the part a one-hop cleanup plan has no use for: distance,
+ * optionality, and termination.
+ */
+
+import {
+  type ConsumedCapabilities,
+  type ProviderRow,
+  type ProviderState,
+  planConsumerCleanup,
+} from '../services/consumer-cleanup';
+
+/**
+ * Hops to walk when the caller does not say.
+ *
+ * Two, because the fleet's useful answer is "what this stands on, and what that
+ * stands on". Deliberately a default and not a law: `depth: UNBOUNDED` walks the
+ * whole graph, and the walk terminates on cycles either way.
+ */
+export const DEFAULT_CLOSURE_DEPTH = 2;
+
+/** Walk until the graph runs out rather than until a hop count does. */
+export const UNBOUNDED_CLOSURE_DEPTH = 0;
+
+export interface ClosureRequest {
+  rootModuleId: string;
+  /**
+   * Each module's consumed capabilities, by module id. A module with no entry
+   * ends that branch of the walk rather than failing the whole thing: a manifest
+   * celilo cannot parse is a real state, and one bad row must not blank the
+   * picture.
+   */
+  manifests: ReadonlyMap<string, ConsumedCapabilities>;
+  providerRows: readonly ProviderRow[];
+  providerStates: readonly ProviderState[];
+  depth?: number;
+  /**
+   * Which providers each module has actually called into, keyed by module id
+   * then capability name.
+   *
+   * When supplied, the walk follows only real bindings. Without it the walk
+   * follows every declared capability, which answers "what could this reach"
+   * rather than "what is this standing on". Optional so the walk stays testable
+   * without a database, not so the distinction is optional.
+   */
+  bindings?: ReadonlyMap<string, ReadonlyMap<string, string>>;
+}
+
+export interface ClosureNode {
+  moduleId: string;
+  /** 1 is a direct dependency of the root. */
+  hop: number;
+  /**
+   * True when every edge that reaches this module is an `optional.capabilities`
+   * edge.
+   *
+   * Load-bearing rather than cosmetic: on a real fleet the internal DNS resolver
+   * is reached only optionally, so a walk that followed `requires` alone drops
+   * the resolver out of the picture entirely while looking complete.
+   */
+  optional: boolean;
+  /** Capability names by which the walk reached this module, sorted. */
+  via: string[];
+}
+
+export interface ClosureResult {
+  nodes: ClosureNode[];
+  /** Hops actually walked. Echoes the request so the console can say what it bounded. */
+  depth: number;
+  /**
+   * True when the walk stopped because it hit the bound and the graph continued.
+   * Distinct from an exhausted graph, which is a complete answer.
+   */
+  truncated: boolean;
+}
+
+interface Edge {
+  to: string;
+  hop: number;
+  capability: string;
+  optional: boolean;
+}
+
+/**
+ * Which of a module's consumed capabilities it declared as optional.
+ *
+ * A name in both sets counts as required: `requires` is the stronger claim, and
+ * a module that declares a capability both ways still fails without it.
+ */
+function optionalCapabilityNames(manifest: ConsumedCapabilities): Set<string> {
+  const required = new Set((manifest.requires?.capabilities ?? []).map((c) => c.name));
+  return new Set(
+    (manifest.optional?.capabilities ?? []).map((c) => c.name).filter((n) => !required.has(n)),
+  );
+}
+
+export function computeClosure(request: ClosureRequest): ClosureResult {
+  const depth = request.depth ?? DEFAULT_CLOSURE_DEPTH;
+  const providerRows = [...request.providerRows];
+  const providerStates = [...request.providerStates];
+
+  const edges: Edge[] = [];
+  // The root counts as visited from the start, so a cycle back to it terminates
+  // rather than re-entering, and the selection never lists itself.
+  const visited = new Set([request.rootModuleId]);
+  let frontier = [request.rootModuleId];
+  let hop = 0;
+  let truncated = false;
+
+  while (frontier.length > 0) {
+    hop += 1;
+    if (depth !== UNBOUNDED_CLOSURE_DEPTH && hop > depth) {
+      // Something was still reachable when the bound stopped us. That is a
+      // different answer from an exhausted graph and the console says so.
+      truncated = true;
+      break;
+    }
+
+    const next: string[] = [];
+    for (const moduleId of frontier) {
+      const manifest = request.manifests.get(moduleId);
+      if (!manifest) continue;
+
+      const optionalNames = optionalCapabilityNames(manifest);
+      const bound = request.bindings?.get(moduleId);
+
+      for (const target of planConsumerCleanup(moduleId, manifest, providerRows, providerStates)) {
+        // A cycle walks back to the selection. Terminating the WALK there is not
+        // enough: the edge is still real, and recording it would list the
+        // selected module as one of its own dependencies. caddy requires
+        // authentik and authentik requires caddy, so this is the ordinary case
+        // on a real fleet rather than a pathological one.
+        if (target.providerId === request.rootModuleId) continue;
+
+        for (const capability of target.capabilityNames) {
+          // A capability the consumer declared and never called into is not a
+          // dependency. Following it would put a provider inside the closure on
+          // the strength of a manifest line, which is a claim that the module is
+          // standing on something it has never touched.
+          if (bound && bound.get(capability) !== target.providerId) continue;
+
+          edges.push({
+            to: target.providerId,
+            hop,
+            capability,
+            optional: optionalNames.has(capability),
+          });
+        }
+        if (!visited.has(target.providerId)) {
+          visited.add(target.providerId);
+          next.push(target.providerId);
+        }
+      }
+    }
+    frontier = next;
+  }
+
+  return { nodes: collectNodes(edges), depth, truncated };
+}
+
+/**
+ * Fold the edge list into one node per module.
+ *
+ * A module is recorded at the SHORTEST hop that reached it, and is optional only
+ * if no edge anywhere in the walk reached it by a required capability. Deciding
+ * either from the first edge seen would make the answer depend on iteration
+ * order.
+ */
+function collectNodes(edges: readonly Edge[]): ClosureNode[] {
+  const byModule = new Map<string, { hop: number; via: Set<string>; anyRequired: boolean }>();
+
+  for (const edge of edges) {
+    const existing = byModule.get(edge.to);
+    if (!existing) {
+      byModule.set(edge.to, {
+        hop: edge.hop,
+        via: new Set([edge.capability]),
+        anyRequired: !edge.optional,
+      });
+      continue;
+    }
+    existing.hop = Math.min(existing.hop, edge.hop);
+    existing.via.add(edge.capability);
+    existing.anyRequired = existing.anyRequired || !edge.optional;
+  }
+
+  return [...byModule.entries()]
+    .map(([moduleId, v]) => ({
+      moduleId,
+      hop: v.hop,
+      optional: !v.anyRequired,
+      via: [...v.via].sort(),
+    }))
+    .sort((a, b) => a.hop - b.hop || a.moduleId.localeCompare(b.moduleId));
+}

package/src/console/control-plane-boundary.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The console must not be reachable from the data plane.
+ *
+ * This is asserted here, cheaply, on every pull request. The e2e suite asserts
+ * the same thing for real by failing to reach the console from a data-plane
+ * zone, but that suite is slow, needs Docker, and does not run on every change.
+ * The way this boundary actually erodes is a one-line manifest edit that adds
+ * `private_web` because someone wanted to reach the console from a laptop
+ * without bringing up the VPN, and a gate that only fires in e2e would not catch
+ * that until much later.
+ *
+ * The history is why this is a test and not a comment. The change's second draft
+ * DID publish the console through caddy-internal, the operator refused it, and
+ * the final verification step still said "the route resolves through
+ * caddy-internal" for a further round after that. Prose did not hold this.
+ */
+import { describe, expect, test } from 'bun:test';
+import { parse } from 'yaml';
+
+const MANIFEST_PATH = new URL(
+  '../../../../modules/celilo-web-console/manifest.yml',
+  import.meta.url,
+).pathname;
+
+/**
+ * Capabilities that give something a way in from the data plane.
+ *
+ * `private_web` and `public_web` publish a route through a reverse proxy.
+ * `firewall` is how a module asks for a port forward or an ingress address.
+ * Any of the three would put a data-plane client on a path to the control
+ * plane.
+ */
+const INGRESS_CAPABILITIES = ['private_web', 'public_web', 'firewall'];
+
+interface CapabilityRef {
+  name: string;
+}
+interface Manifest {
+  id: string;
+  requires?: { capabilities?: CapabilityRef[]; system?: { zone?: string } };
+  optional?: { capabilities?: CapabilityRef[] };
+  provides?: { capabilities?: CapabilityRef[] };
+}
+
+async function loadManifest(): Promise<Manifest> {
+  return parse(await Bun.file(MANIFEST_PATH).text()) as Manifest;
+}
+
+describe('celilo-web-console stays in the control plane', () => {
+  test('lands in secure-mgmt and nowhere else', async () => {
+    const manifest = await loadManifest();
+    expect(manifest.requires?.system?.zone).toBe('secure-mgmt');
+  });
+
+  test('requires no capability that could give it data-plane ingress', async () => {
+    const manifest = await loadManifest();
+    const required = (manifest.requires?.capabilities ?? []).map((c) => c.name);
+    const found = required.filter((name) => INGRESS_CAPABILITIES.includes(name));
+    expect(found).toEqual([]);
+  });
+
+  test('does not pick up ingress through an OPTIONAL capability either', async () => {
+    // Optional is the likelier hole. It reads as harmless, and the closure walk
+    // in this same directory exists because optional edges are real edges.
+    const manifest = await loadManifest();
+    const optional = (manifest.optional?.capabilities ?? []).map((c) => c.name);
+    const found = optional.filter((name) => INGRESS_CAPABILITIES.includes(name));
+    expect(found).toEqual([]);
+  });
+
+  test('provides nothing, so nothing can bind to it as a dependency', async () => {
+    const manifest = await loadManifest();
+    expect(manifest.provides?.capabilities ?? []).toEqual([]);
+  });
+});