@celilo/console-server 0.5.1 → 0.6.1

package/spa/index.html

@@ -4,7 +4,15 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>celilo</title>
-    <script type="module" crossorigin src="/assets/index-C31pEQ-J.js"></script>
+    <!-- Inline so there is no file to ship and no second request. The glyph is
+         drawn by the VIEWER's emoji font, so it will not look identical across
+         platforms, and a system without the woman-technologist ZWJ sequence
+         falls back to two glyphs side by side rather than one. -->
+    <link
+      rel="icon"
+      href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>👩‍💻</text></svg>"
+    />
+    <script type="module" crossorigin src="/assets/index-bR5M5myY.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-eLF_dgP-.css">
   </head>
   <body>

package/src/main.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { startFromEnv } from './main';
+
+/**
+ * The console used to fall back to the bare destination `celilo-api@celilo-mgr`
+ * when CELILO_API_DEST was unset. That name resolves only on celilo-mgr itself,
+ * so on the console's own box every /api read 502'd while `celilo module health`
+ * reported VERIFIED — it drives an OIDC login and never touches the upstream.
+ * celilo#1453.
+ *
+ * A silent fallback to an unreachable default is worse than no default: it turns
+ * a missing value into a runtime symptom three layers from its cause. So the
+ * behaviour under test is the REFUSAL, not the presence of a constant.
+ */
+const OIDC_ENV = {
+  OIDC_ISSUER: 'https://auth.example.test/application/o/console/',
+  OIDC_CLIENT_ID: 'console-web',
+  OIDC_CLIENT_SECRET: 'not-a-real-secret',
+};
+
+describe('startFromEnv — the upstream destination', () => {
+  test('refuses to start when CELILO_API_DEST is unset', () => {
+    expect(() => startFromEnv({ ...OIDC_ENV })).toThrow(/CELILO_API_DEST is not set/);
+  });
+
+  test('refuses to start when CELILO_API_DEST is empty', () => {
+    expect(() => startFromEnv({ ...OIDC_ENV, CELILO_API_DEST: '' })).toThrow(
+      /CELILO_API_DEST is not set/,
+    );
+  });
+
+  test('says what a usable destination looks like, so the message is actionable', () => {
+    // An error naming only the variable sends the reader to grep. This one has to
+    // carry the shape of the answer, because the shape IS the bug: a bare
+    // hostname looks correct and resolves nowhere.
+    expect(() => startFromEnv({ ...OIDC_ENV })).toThrow(/\.infra\.<domain>/);
+  });
+});

package/src/main.ts

@@ -23,8 +23,18 @@ import { type AuthGate, type AuthSubject, serve } from './serve';
  */
 const DEFAULT_IDENTITY_FILE = '/etc/celilo-web-console/id_ed25519';
 
-/** Matches `wellspring`'s `DEFAULT_ENDPOINT`, which is the fleet's convention. */
-const DEFAULT_DEST = 'celilo-api@celilo-mgr';
+// There is deliberately no DEFAULT_DEST. It used to be `celilo-api@celilo-mgr`,
+// borrowed from wellspring's DEFAULT_ENDPOINT — a bare name that resolves only on
+// celilo-mgr itself, via its own /etc/hosts. No system in the fleet carries a DNS
+// search domain, so on the console's own box it resolved nowhere, and the server
+// fell back to it silently whenever CELILO_API_DEST was unset. The result was
+// `ssh: Could not resolve hostname celilo-mgr` twice a second and a 502 on every
+// /api read, while `celilo module health` still reported VERIFIED because it
+// drives a login and never touches the upstream. celilo#1453.
+//
+// A missing destination is a misconfiguration, so it fails loudly. The fleet's
+// real name for a system is `<hostname>.infra.<domain>`, which technitium
+// registers for every system (on-system-event.ts:120).
 
 export interface OidcGateOptions {
   /** The `iss` claim exactly — for authentik, `https://auth.<domain>/application/o/<slug>/`. */
@@ -95,12 +105,17 @@ export function oidcGate(options: OidcGateOptions): AuthGate {
 }
 
 /** Read one required value, or say which one is missing and who writes it. */
-function required(env: Record<string, string | undefined>, name: string): string {
+const OIDC_UNSET =
+  "The console refuses to serve without an identity provider — see /etc/celilo-web-console-discovered.env, which the module's install hook writes once the OIDC client exists.";
+
+function required(
+  env: Record<string, string | undefined>,
+  name: string,
+  why: string = OIDC_UNSET,
+): string {
   const value = env[name];
   if (value === undefined || value === '') {
-    throw new Error(
-      `${name} is not set. The console refuses to serve without an identity provider — see /etc/celilo-web-console-discovered.env, which the module's install hook writes once the OIDC client exists.`,
-    );
+    throw new Error(`${name} is not set. ${why}`);
   }
   return value;
 }
@@ -126,7 +141,11 @@ export function startFromEnv(env: Record<string, string | undefined> = process.e
   );
   const server = serve({
     port: Number(env.PORT ?? 8443),
-    dest: env.CELILO_API_DEST ?? DEFAULT_DEST,
+    dest: required(
+      env,
+      'CELILO_API_DEST',
+      'The console has no celilo to read through. The module writes it into /etc/celilo-web-console.env from its `api_dest` config; it must be a resolvable destination such as celilo-api@celilo-mgr.infra.<domain>, never a bare hostname.',
+    ),
     identityFile: env.CELILO_IDENTITY_FILE ?? DEFAULT_IDENTITY_FILE,
     ...(env.CONSOLE_SPA_DIR ? { spaDir: env.CONSOLE_SPA_DIR } : {}),
     authenticate: login.authenticate,

package/src/upstream.ts

@@ -66,8 +66,15 @@ export interface UpstreamOptions {
 const EXIT_DENIED = 126;
 
 interface CacheEntry {
+  /** When the value SETTLED. Meaningless while `pending`. */
   at: number;
-  value: unknown;
+  /**
+   * The promise, not the resolved value — so concurrent callers for the same
+   * argv join one request instead of each starting their own.
+   */
+  value: Promise<unknown>;
+  /** In flight. A pending entry is joined regardless of the TTL. */
+  pending: boolean;
 }
 
 export class Upstream {
@@ -90,10 +97,41 @@ export class Upstream {
   async read<T>(argv: readonly string[]): Promise<T> {
     const key = argv.join(' ');
     const hit = this.cache.get(key);
-    if (hit && this.now() - hit.at < this.ttl) return hit.value as T;
+    // A PENDING entry is joined whatever the TTL says. This cache used to store
+    // the resolved value and `await` before setting it, so every caller that
+    // arrived while a read was in flight missed and started its own. The console
+    // polls every 5s and mounts several panels at once, and each panel opens its
+    // OWN ssh connection because ControlMaster is deliberately off (celilo#921),
+    // so identical argv went to celilo three or four times per cycle. Measured
+    // on the live console 2026-09-27: 28 `console:status` ops against 18
+    // `alerts:list` + 10 `backup:list`, with panels at 12-14s against a 15s
+    // client timeout.
+    //
+    // Joining only on a fresh TTL would not fix it: a read takes ~4s here and
+    // the TTL is 2s, so the entry expires WHILE IN FLIGHT and the next caller
+    // duplicates it anyway. With reads slower than the TTL that is the common
+    // case, not an edge one — hence `pending`.
+    if (hit && (hit.pending || this.now() - hit.at < this.ttl)) return hit.value as Promise<T>;
+
+    const value = this.runJson<T>(argv);
+    const entry: CacheEntry = { at: this.now(), value, pending: true };
+    this.cache.set(key, entry);
+
+    value.then(
+      () => {
+        // The TTL runs from when the value SETTLED, not when the request
+        // started; otherwise a read slower than the TTL is stale on arrival.
+        entry.at = this.now();
+        entry.pending = false;
+      },
+      () => {
+        // A failed read must not be served for the rest of the window, and must
+        // not leave a permanently-pending entry that every later caller joins.
+        // Retry it; do not remember it.
+        if (this.cache.get(key) === entry) this.cache.delete(key);
+      },
+    );
 
-    const value = await this.runJson<T>(argv);
-    this.cache.set(key, { at: this.now(), value });
     return value;
   }
 

package/src/verbs.ts

@@ -81,7 +81,23 @@ interface CliClosure {
   truncated: boolean;
 }
 
-/** `celilo alerts --json`, verbatim. */
+/**
+ * `celilo alerts list --json`, verbatim — which is NOT the protocol's shape.
+ *
+ * Every timestamp is `unknown` deliberately. celilo stores them as Drizzle
+ * `mode: 'timestamp'` columns, so its rows hold `Date` objects and `--json`
+ * prints ISO STRINGS, while the protocol declares epoch ms (also deliberate:
+ * ages are computed against the server's `asOf`, so a skewed browser clock
+ * cannot answer "how long has this been firing" wrongly).
+ *
+ * Typing them `number` here declared a shape nobody checked. `upstream.read<T>`
+ * is a type ASSERTION, so the strings passed through onto the wire, the
+ * browser's own protocol validation rejected the payload, and the dock rendered
+ * one word — "unavailable" — for a fleet with six firing alerts (celilo#1455).
+ * `unknown` forces every one of them through `epochMs` below, which converts and
+ * VALIDATES at the ingest boundary, so an upstream shape change fails here
+ * naming the field instead of three layers away as a single word.
+ */
 interface CliAlert {
   id: string;
   key: string;
@@ -90,18 +106,45 @@ interface CliAlert {
   monitor: string | null;
   escalationPolicy: string | null;
   escalationStep: number;
-  nextEscalationAt: number | null;
-  firstFiredAt: number;
-  lastSeenAt: number;
+  nextEscalationAt: unknown;
+  firstFiredAt: unknown;
+  lastSeenAt: unknown;
   suppressedByAlertId: string | null;
   suppressedByWindowId: string | null;
   awaitingConfirmation: boolean;
   ackedBy: string | null;
-  ackedAt: number | null;
-  silencedUntil: number | null;
+  ackedAt: unknown;
+  silencedUntil: unknown;
   message: string;
 }
 
+const ALERTS_ARGV = ['alerts', 'list', '--json'] as const;
+
+/**
+ * An upstream timestamp as epoch ms, or a `malformed` failure naming the field.
+ *
+ * Accepts both forms on purpose: epoch ms is what the protocol wants and what an
+ * older or future celilo may print directly, and an ISO string is what today's
+ * Drizzle-serialised rows carry.
+ */
+function epochMs(value: unknown, field: string): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    if (!Number.isNaN(parsed)) return parsed;
+  }
+  throw new UpstreamUnavailable(
+    'malformed',
+    ALERTS_ARGV,
+    `\`celilo alerts list --json\` returned ${field}=${JSON.stringify(value)}; expected epoch ms or an ISO timestamp.`,
+  );
+}
+
+/** As `epochMs`, for a field celilo legitimately leaves unset. */
+function epochMsOrNull(value: unknown, field: string): number | null {
+  return value === null || value === undefined ? null : epochMs(value, field);
+}
+
 /** `celilo person list --json`, verbatim. */
 interface CliPerson {
   name: string;
@@ -278,17 +321,17 @@ export async function readAlerts(upstream: Upstream, moduleId?: string): Promise
         state: alertState(row.state),
         severity: severity(row.severity),
         policy: row.escalationPolicy,
-        firstFiredAt: row.firstFiredAt,
-        lastSeenAt: row.lastSeenAt,
+        firstFiredAt: epochMs(row.firstFiredAt, 'firstFiredAt'),
+        lastSeenAt: epochMs(row.lastSeenAt, 'lastSeenAt'),
         suppressedByAlertId: row.suppressedByAlertId,
         suppressedByWindowId: row.suppressedByWindowId,
-        silencedUntil: row.silencedUntil,
+        silencedUntil: epochMsOrNull(row.silencedUntil, 'silencedUntil'),
         // `alerts --json` resolves the person to a name. There is no id on the
         // wire, so the name serves as both — which is what the console shows.
         ackedBy: row.ackedBy ? { id: row.ackedBy, name: row.ackedBy } : null,
-        ackedAt: row.ackedAt,
+        ackedAt: epochMsOrNull(row.ackedAt, 'ackedAt'),
         escalationStep: row.escalationStep,
-        nextEscalationAt: row.nextEscalationAt,
+        nextEscalationAt: epochMsOrNull(row.nextEscalationAt, 'nextEscalationAt'),
       }),
     ),
   };
@@ -467,5 +510,5 @@ export async function ackAlert(
     );
   }
 
-  return { ackedAt: acked.ackedAt, ackedByName: acked.ackedBy ?? person };
+  return { ackedAt: epochMs(acked.ackedAt, 'ackedAt'), ackedByName: acked.ackedBy ?? person };
 }