@intentius/chant 0.33.0 → 0.34.0

package/src/observation.test.ts

@@ -5,14 +5,19 @@
 import { describe, test, expect } from "vitest";
 import {
   UNOBSERVED_REASONS,
+  boundedConcurrently,
   formatUnobserved,
   isObservationResult,
   isUnobservedReason,
   mergeObservations,
   normalizeObservation,
   observation,
+  observeEntities,
   unobservedAll,
   unobservedReasonText,
+  type DeclaredEntity,
+  type EntityObservation,
+  type ObserverAdapter,
 } from "./observation";
 import type { ResourceMetadata } from "./lexicon";
 
@@ -94,3 +99,133 @@ describe("reason totality", () => {
     ).toBe("widget (K8s::X::Widget) — no reader for this resource kind: no mapping");
   });
 });
+
+describe("boundedConcurrently", () => {
+  test("processes every item", async () => {
+    const seen: number[] = [];
+    await boundedConcurrently([1, 2, 3, 4, 5], async (n) => {
+      seen.push(n);
+    }, 2);
+    expect([...seen].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  test("never exceeds the limit in flight", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    await boundedConcurrently(Array.from({ length: 20 }, (_, i) => i), async () => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      await new Promise((r) => setTimeout(r, 1));
+      inFlight -= 1;
+    }, 4);
+    expect(peak).toBeLessThanOrEqual(4);
+    expect(peak).toBeGreaterThan(1); // it did run concurrently, not serially
+  });
+
+  test("an empty list is a no-op", async () => {
+    await expect(boundedConcurrently([], async () => {})).resolves.toBeUndefined();
+  });
+});
+
+describe("observeEntities harness (#1201)", () => {
+  const entity = (name: string, type = "Fake::Resource"): DeclaredEntity => ({ name, type, props: {} });
+
+  /** A fake adapter whose `read` is table-driven by entity name. */
+  const adapterOf = (
+    reads: Record<string, EntityObservation | (() => Promise<EntityObservation>)>,
+    over: Partial<ObserverAdapter<{ ok: true }>> = {},
+  ): ObserverAdapter<{ ok: true }> => ({
+    bind: async () => ({ ok: true }),
+    classifyBindFailure: () => ({ reason: "read-failed" }),
+    read: async (_client, e) => {
+      const r = reads[e.name];
+      if (typeof r === "function") return r();
+      if (!r) throw new Error(`no fake read for ${e.name}`);
+      return r;
+    },
+    ...over,
+  });
+
+  test("routes the tri-state: present -> resources, absent -> neither, unobserved -> unobserved", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b"), entity("c", "Fake::Odd")],
+      adapterOf({
+        a: { present: meta({ physicalId: "id-a" }) },
+        b: { absent: true },
+        c: { unobserved: { reason: "unsupported-kind", detail: "no reader" } },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["a"]);
+    expect(result.resources.a.physicalId).toBe("id-a");
+    // absent 'b' is in neither map
+    expect(result.unobserved).toEqual({
+      c: { type: "Fake::Odd", reason: "unsupported-kind", detail: "no reader" },
+    });
+  });
+
+  test("a bind failure marks every entity NOT-OBSERVED with the typed reason and declared type", async () => {
+    const result = await observeEntities(
+      [entity("a", "AWS::S3::Bucket"), entity("b", "AWS::S3::Bucket")],
+      adapterOf(
+        {},
+        {
+          bind: async () => {
+            throw new Error("no creds");
+          },
+          classifyBindFailure: () => ({ reason: "no-credentials", detail: "token expired" }),
+        },
+      ),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved).toEqual({
+      a: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+      b: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+    });
+  });
+
+  test("a loud refusal rethrows instead of degrading to a hole", async () => {
+    await expect(
+      observeEntities(
+        [entity("a")],
+        adapterOf(
+          {},
+          {
+            bind: async () => {
+              throw new Error("context mismatch");
+            },
+            classifyBindFailure: () => "rethrow",
+          },
+        ),
+      ),
+    ).rejects.toThrow("context mismatch");
+  });
+
+  test("a per-entity read throw degrades to read-failed for that one entity, not an absence", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b")],
+      adapterOf({
+        a: () => Promise.reject(new Error("boom")),
+        b: { present: meta() },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["b"]);
+    expect(result.unobserved?.a).toEqual({ type: "Fake::Resource", reason: "read-failed", detail: "boom" });
+  });
+
+  test("uses the adapter's own concurrency pool when it supplies one", async () => {
+    let usedPool = false;
+    await observeEntities(
+      [entity("a")],
+      adapterOf(
+        { a: { present: meta() } },
+        {
+          concurrently: async (items, fn) => {
+            usedPool = true;
+            for (const it of items) await fn(it);
+          },
+        },
+      ),
+    );
+    expect(usedPool).toBe(true);
+  });
+});

package/src/observation.ts

@@ -211,3 +211,154 @@ export function formatUnobserved(name: string, entry: UnobservedEntity): string
   const base = `${name}${entry.type ? ` (${entry.type})` : ""} — ${unobservedReasonText(entry.reason)}`;
   return entry.detail ? `${base}: ${entry.detail}` : base;
 }
+
+/* ------------------------------------------------------------------------- *
+ * The observer harness (#1201).
+ *
+ * Every native observer runs the same control flow: bind to the provider on
+ * the applier's own transport, read the declared entities concurrently, and
+ * turn each read into one of the tri-state outcomes above. The k8s observer
+ * (#1074) and Fly (#767) already embody it. Rather than have aws/gcp/azure each
+ * re-derive it — and re-derive it inconsistently, which is how the shell-out
+ * observers drifted apart — a lexicon supplies an {@link ObserverAdapter} and
+ * the harness owns the shape: bind-or-not-observe-all with a typed reason,
+ * bounded concurrency, per-entity tri-state routing, and a per-entity throw
+ * degrading to `read-failed` rather than a silent absence.
+ *
+ * The adapter owns transport and endpoint resolution (an emulator override is
+ * resolved inside `bind()` via the shared live-endpoint helper), so the
+ * emulator override behaves identically across lexicons by construction — the
+ * harness never touches an endpoint itself.
+ * ------------------------------------------------------------------------- */
+
+/** One declared entity handed to the harness. */
+export interface DeclaredEntity {
+  /** chant entity name — the key every outcome is filed under. */
+  name: string;
+  /** Declared entity type (e.g. `AWS::EC2::VPC`). */
+  type: string;
+  /** Declared properties, for the adapter to derive a physical address from. */
+  props: Record<string, unknown>;
+}
+
+/**
+ * The outcome of reading one entity, mapped onto the tri-state:
+ * - `present` — a key in `resources`.
+ * - `absent` — in neither map (the provider was asked and reported it missing).
+ * - `unobserved` — a typed NOT-OBSERVED (unsupported kind, filtered, read error).
+ */
+export type EntityObservation =
+  | { present: ResourceMetadata }
+  | { absent: true }
+  | { unobserved: { reason: UnobservedReason; detail?: string } };
+
+/** What a lexicon supplies to drive the harness. `Client` is its transport handle. */
+export interface ObserverAdapter<Client> {
+  /**
+   * Reach the provider on the applier's transport. Throw for a whole-lexicon
+   * failure; {@link classifyBindFailure} decides what the throw means.
+   */
+  bind(): Promise<Client>;
+  /**
+   * Map a `bind()` throw to a typed whole-lexicon reason (every entity becomes
+   * NOT-OBSERVED with it), or `"rethrow"` for a loud refusal that must not be
+   * swallowed — a context/subscription mismatch, which core turns into an
+   * honest hole per entity at a higher layer.
+   */
+  classifyBindFailure(err: unknown): { reason: UnobservedReason; detail?: string } | "rethrow";
+  /** Read one declared entity. A throw here is caught and recorded `read-failed`. */
+  read(client: Client, entity: DeclaredEntity): Promise<EntityObservation>;
+  /**
+   * Run `fn` over `items` concurrently. Supply the transport's own bounded pool
+   * (the k8s client's `concurrently`, say); when omitted the harness uses
+   * {@link boundedConcurrently}, so "N entities is not N serial spawns" holds
+   * for every lexicon whether or not its transport ships a pool.
+   */
+  concurrently?<T>(items: readonly T[], fn: (item: T) => Promise<void>): Promise<void>;
+}
+
+/** Default concurrency for {@link boundedConcurrently} when a transport ships no pool. */
+export const DEFAULT_OBSERVE_CONCURRENCY = 16;
+
+/**
+ * Run `fn` over `items` with at most `limit` in flight. A rejected `fn` rejects
+ * the whole run (the harness wraps per-entity reads so this stays for genuinely
+ * unexpected faults).
+ */
+export async function boundedConcurrently<T>(
+  items: readonly T[],
+  fn: (item: T) => Promise<void>,
+  limit: number = DEFAULT_OBSERVE_CONCURRENCY,
+): Promise<void> {
+  const queue = [...items];
+  const size = Math.max(1, Math.min(limit, queue.length || 1));
+  const workers = Array.from({ length: size }, async () => {
+    for (;;) {
+      const next = queue.shift();
+      if (next === undefined) return;
+      await fn(next);
+    }
+  });
+  await Promise.all(workers);
+}
+
+/**
+ * The shared observer control flow (#1201). Binds via the adapter, reads every
+ * declared entity concurrently, and assembles the tri-state {@link ObservationResult}.
+ *
+ * A `bind()` throw becomes NOT-OBSERVED for every entity (typed by
+ * {@link ObserverAdapter.classifyBindFailure}) unless the adapter asks to
+ * rethrow. A per-entity `read()` throw the adapter did not itself map becomes
+ * `read-failed` for that one entity — never a silent absence, which would
+ * classify as a spurious `create`.
+ */
+export async function observeEntities<Client>(
+  declared: readonly DeclaredEntity[],
+  adapter: ObserverAdapter<Client>,
+): Promise<ObservationResult> {
+  const typesByName: Record<string, string> = {};
+  for (const d of declared) typesByName[d.name] = d.type;
+
+  let client: Client;
+  try {
+    client = await adapter.bind();
+  } catch (err) {
+    const verdict = adapter.classifyBindFailure(err);
+    if (verdict === "rethrow") throw err;
+    return observation(
+      {},
+      unobservedAll(
+        declared.map((d) => d.name),
+        verdict.reason,
+        verdict.detail,
+        typesByName,
+      ),
+    );
+  }
+
+  const resources: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  const run = adapter.concurrently ?? ((items, fn) => boundedConcurrently(items, fn));
+
+  await run(declared, async (entity) => {
+    let result: EntityObservation;
+    try {
+      result = await adapter.read(client, entity);
+    } catch (err) {
+      result = {
+        unobserved: {
+          reason: "read-failed",
+          detail: err instanceof Error ? err.message : String(err),
+        },
+      };
+    }
+    if ("present" in result) {
+      resources[entity.name] = result.present;
+    } else if ("unobserved" in result) {
+      unobserved[entity.name] = { type: entity.type, ...result.unobserved };
+    }
+    // `absent`: record nothing — in neither map is how the contract spells absence.
+  });
+
+  return observation(resources, unobserved);
+}