@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/fleet-vm-readiness.js

@@ -0,0 +1,104 @@
+'use strict';
+// Pure readiness derivation for the Fleet Dashboard's per-VM card
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the merged
+// poll state `v` and the derived `ctx` the card builder already computes,
+// collapse the VM into a single readiness label the card renders. No I/O —
+// server.js owns the polling (including the slow-cadence LB backend-health
+// probe that fills `v.backendHealth`).
+//
+// The bug this fixes: a VM card rendered as idle with a CLICKABLE editor URL the
+// moment the VM was rostered + SSH-tunnel-reachable, even when its public LB URL
+// (vm-<N>.editor.<domain>) would return Envoy "no healthy upstream" (503). The
+// card reflected only SSH-tunnel reachability to :14199, never whether the load
+// balancer actually routes to a HEALTHY backend. Two situations cause the 503,
+// and the card had zero visibility into either:
+//
+//   transient half-wire — the editor is serving but the LB health check hasn't
+//                         marked the backend HEALTHY yet during cold start. It
+//                         resolves on its own; the card should say 'starting'.
+//   permanent half-wire — the per-VM LB backend service was never created (e.g.
+//                         the Add ran under a service account lacking
+//                         compute.backendServices.create), so the URL 503s
+//                         forever until re-wired. The card should say
+//                         'half-wired', visibly distinct from 'starting'.
+//
+// SSH reachability (v.reachable from probeVM over the tunnel) is necessary but
+// not sufficient: the tunnel is up in BOTH 503 cases. Only the LB backend health
+// (gcloud compute backend-services get-health, gathered into v.backendHealth)
+// distinguishes ready / starting / half-wired. The editor's own /healthz can't
+// see the half-wire, so it is not enough on its own.
+//
+//   'provisioning' — an Add/recover job is in flight; the VM is still being
+//                    built, so judging its public-URL readiness is premature.
+//   'unreachable'  — the editor did not answer over the tunnel. Nothing
+//                    downstream (broker, LB health) is meaningful; the link is
+//                    gated exactly as today.
+//   'half-wired'   — LB mode, the editor backend service is ABSENT (never
+//                    created). The permanent 503 case — the public URL will fail
+//                    until re-wired. The state that had NO signal before.
+//   'starting'     — LB mode, the editor backend exists but is UNHEALTHY (LB has
+//                    not yet marked it HEALTHY). The transient 503 case; flips to
+//                    'ready' on its own once the health check passes.
+//   'broker-down'  — reachable + LB-healthy (or legacy mode), but the broker
+//                    daemon is down, so the VM cannot start an agent session.
+//   'ready'        — reachable, broker up, and (LB mode) the editor backend is
+//                    HEALTHY. The only state whose editor link is live + green.
+//
+// Legacy mode (FLEET_DOMAIN unset ⇒ ctx.lbMode falsey, or no backendHealth
+// supplied): there is no LB to health-check, so the backend-health branch is
+// skipped and readiness degrades to today's reachability/broker behavior — no
+// regression, no gcloud calls.
+const READINESS_STATES = [
+  'provisioning',
+  'unreachable',
+  'half-wired',
+  'starting',
+  'broker-down',
+  'ready',
+];
+
+// A VM mid-provision: an Add (incl. its recovering re-run) that is queued
+// (number reserved, cloud:up not started) or running. Its public URL has no
+// meaningful readiness yet, so this takes precedence over every other signal —
+// a freshly-reserved VM must not flash 'half-wired' before its backend exists.
+function isProvisioning(job) {
+  if (!job) return false;
+  if (job.action === 'add' && (job.state === 'running' || job.state === 'queued')) return true;
+  if (job.recovering && job.state === 'running') return true;
+  return false;
+}
+
+// `v` is the merged poll state (state.vms[n]); `ctx` carries the derived values
+// the card builder already has on hand:
+//   ctx.job          — the active job (or null), for the provisioning check.
+//   ctx.brokerStatus — the debounced broker tri-state ('down'|'idle'|
+//                      'agent-live'|'unknown') the card already derives.
+//   ctx.lbMode       — true when FLEET_DOMAIN is set (the LB fronts the URLs).
+//                      When false, the backend-health branch is skipped.
+function deriveVmReadiness(v, ctx) {
+  const c = ctx || {};
+  // 1. Still being built — don't judge a half-built VM as ready or half-wired.
+  if (isProvisioning(c.job)) return 'provisioning';
+  // 2. Editor unreachable over the tunnel: we polled nothing, so broker / LB
+  //    health are unknowable. Link gated, exactly as the pre-readiness card did.
+  if (!v || !v.reachable) return 'unreachable';
+  // 3. LB mode only: the public URL's fate is the editor backend's LB health.
+  //    Skipped entirely in legacy mode (no LB) or before the first probe lands
+  //    (no backendHealth) — both fall through to the reachability/broker path.
+  const bh = v.backendHealth;
+  if (c.lbMode && bh) {
+    // Backend service never created ⇒ permanent 503 until re-wired.
+    if (bh.editor === 'absent') return 'half-wired';
+    // Backend exists but not yet HEALTHY ⇒ transient 503 during cold start.
+    if (bh.editor === 'unhealthy') return 'starting';
+    // 'healthy' falls through to ready; 'unknown' (get-health errored) is
+    // absence-of-evidence — never rendered as a problem, falls through too.
+  }
+  // 4. Reachable but the broker daemon is down: the VM can't start a session.
+  if (c.brokerStatus === 'down') return 'broker-down';
+  // 5. Reachable, broker up, and (LB mode) the editor backend is HEALTHY —
+  //    genuinely ready: green, clickable, public URL actually routes.
+  return 'ready';
+}
+
+module.exports = { deriveVmReadiness, READINESS_STATES, isProvisioning };

package/npm/fleet-vm-slugs.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// npm/fleet-vm-slugs.js — the per-VM custom-slug sidecar
+// (`.codeyam/logs/fleet-vm-slugs.json`). A slug is an optional human-readable
+// override for a VM's leftmost hostname label, so its public URLs become
+// `<slug>.editor.<domain>` instead of the number-derived `vm-<N>.editor.<domain>`.
+//
+// Why a sidecar and not the roster: the roster (`npm/fleet-roster.js`) is a flat
+// integer array with a hard "sorted, de-duped set of integers" invariant that
+// bash consumers (`vm-urls.sh`, the watchdog) depend on. Rather than break that
+// shape, slugs live in a SEPARATE map `{ "<N>": "<slug>" }`, fronted by a
+// read+write seam modeled exactly on fleet-roster.js (atomic temp-file + rename,
+// tolerant of a missing/malformed file).
+//
+// The slug is purely a public-hostname override — internal GCP resource names
+// (NEG / backend service / path matcher) stay keyed off the VM number, so a VM
+// added without a slug keeps its `vm-<N>` URLs unchanged.
+//
+// Env override: `VM_SLUGS_FILE` relocates the file (mirrors fleet-roster.js's
+// `VMS_STATE_FILE`); resolved once at module load.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+const { normalizeVmNumber, normalizeVmSlug } = require('./vm-urls');
+
+const VM_SLUGS_FILE = process.env.VM_SLUGS_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-vm-slugs.json');
+
+// Read the slug sidecar, returning a `{ [vmNumber]: slug }` object, or null if
+// the file is missing or malformed (treated as "no slugs"). Keys are kept as the
+// string form JSON emits; callers look them up by `String(n)`.
+function readSlugs() {
+  try {
+    const data = JSON.parse(fs.readFileSync(VM_SLUGS_FILE, 'utf8'));
+    if (data && typeof data === 'object' && !Array.isArray(data)) return data;
+  } catch { /* missing or malformed */ }
+  return null;
+}
+
+// Persist `map` as the sidecar, atomically: write a temp file then `rename` it
+// over the target so a concurrent reader never observes a half-written file. The
+// temp name carries the pid so two processes writing at once don't clobber each
+// other's temp file before their renames land. Returns the written map.
+function writeSlugs(map) {
+  const next = map && typeof map === 'object' && !Array.isArray(map) ? map : {};
+  fs.mkdirSync(path.dirname(VM_SLUGS_FILE), { recursive: true });
+  const tmp = `${VM_SLUGS_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, VM_SLUGS_FILE); // atomic replace
+  return next;
+}
+
+/** The slug mapped to VM `n`, or null when it has none (or the file is absent).
+ *  This is the resolver every hostname derivation funnels through:
+ *  `slugFor(n) || ('vm-' + n)`. */
+function slugFor(n) {
+  const num = normalizeVmNumber(n);
+  const map = readSlugs();
+  const slug = map && map[String(num)];
+  return typeof slug === 'string' && slug.length > 0 ? slug : null;
+}
+
+/** The VM number currently mapped to `slug`, or null when no VM owns it. Used to
+ *  reject a duplicate slug BEFORE it is assigned (a slug must be unique across
+ *  the fleet, else two VMs would claim the same hostname). `slug` is normalized
+ *  first so the comparison is case-insensitive. */
+function vmForSlug(slug) {
+  const want = normalizeVmSlug(slug);
+  const map = readSlugs() || {};
+  for (const [k, v] of Object.entries(map)) {
+    if (typeof v === 'string' && v.toLowerCase() === want) {
+      const num = Number(k);
+      if (Number.isInteger(num) && num > 0) return num;
+    }
+  }
+  return null;
+}
+
+/** Assign `slug` to VM `n`, validating the slug (via `normalizeVmSlug`) and
+ *  rejecting a slug already mapped to a DIFFERENT VM. Returns the written map.
+ *  Re-assigning a VM its own existing slug is an idempotent no-op-shaped write. */
+function setSlug(n, slug) {
+  const num = normalizeVmNumber(n);
+  const norm = normalizeVmSlug(slug);
+  const owner = vmForSlug(norm);
+  if (owner != null && owner !== num) {
+    throw new Error(
+      `VM slug "${norm}" is already assigned to VM-${owner} — pick another name`,
+    );
+  }
+  const map = { ...(readSlugs() || {}) };
+  map[String(num)] = norm;
+  return writeSlugs(map);
+}
+
+/** Remove VM `n`'s slug mapping, returning the new map. Removing an absent entry
+ *  is a no-op. Called on Destroy so a number freed and later re-used doesn't
+ *  inherit a stale slug. */
+function removeSlug(n) {
+  const num = normalizeVmNumber(n);
+  const map = { ...(readSlugs() || {}) };
+  delete map[String(num)];
+  return writeSlugs(map);
+}
+
+module.exports = {
+  VM_SLUGS_FILE,
+  readSlugs,
+  writeSlugs,
+  slugFor,
+  vmForSlug,
+  setSlug,
+  removeSlug,
+};

package/npm/google-ingress.js

@@ -0,0 +1,211 @@
+'use strict';
+// Deterministic Google Cloud HTTPS-LB resource-name derivation for the fleet.
+//
+// The fleet's public browser ingress moves from cloudflared named tunnels to a
+// single Google external HTTPS Load Balancer (one URL map, host-based routing).
+// Reaching a specific port on a specific VM needs a zonal NEG + backend service
+// per (VM, surface); the URL map then routes each `vm-<N>.<surface>.<domain>`
+// host to that backend. This module is the single source of truth for those
+// Google resource NAMES so the bash provisioners (scripts/gcp/google-ingress.sh,
+// scripts/gcp/vm-ingress.sh) and any node caller derive identical strings and a
+// unit test guards them against drift — exactly the contract npm/vm-urls.js and
+// npm/launch-config.js follow.
+//
+// Pure logic only — no I/O, no env reads beyond the explicit `env` argument a
+// caller passes in, so it stays unit-testable in isolation
+// (npm/google-ingress.test.js). The HOSTNAMES it routes to are reused verbatim
+// from npm/vm-urls.js (vmHostnames / dashboardHostname): the Google migration is
+// a serving-layer swap, not a URL-scheme change, so hostnames must never drift
+// from the cert/DNS that vm-urls.js already defines.
+//
+// Stack note: this is fleet-operator infrastructure (the cloud GCE fleet that
+// runs codeyam-editor itself), not a per-app-stack assumption. A project that
+// never joins a Google fleet never sets FLEET_DOMAIN / FLEET_INGRESS=google and
+// never derives a name here; the legacy cloudflared path stays the fallback.
+
+const {
+  normalizeVmNumber,
+  vmHostnames,
+  dashboardHostname,
+} = require('./vm-urls');
+
+// The two per-VM ingress surfaces. `editor` fronts the in-VM editor control API
+// (a fixed port); `preview` fronts the VM's dev server (a per-project port).
+// Keep this list as the single definition both name derivation and the host-rule
+// builder iterate, so a third surface is one edit, not three.
+const SURFACES = Object.freeze(['editor', 'preview']);
+
+// The in-VM editor control API port. Fixed across the fleet (matches
+// named-tunnel-config.sh's EDITOR_PORT default and cloud.js's `-L …:14199`), so
+// the editor backend NEG always targets this port regardless of project.
+const EDITOR_PORT = 14199;
+
+/** The fixed in-VM editor control-API port the editor backend NEG targets. A
+ *  function (not a bare constant export) so callers read it the same way they
+ *  read the per-VM appPort — a uniform "resolve the port for this surface" shape. */
+function editorPort() {
+  return EDITOR_PORT;
+}
+
+/** Validate an ingress surface against SURFACES. The NEG / backend-service /
+ *  host-rule derivations all key off it, so a typo'd surface would mint a
+ *  resource that nothing routes to — reject it loudly at the boundary, mirroring
+ *  how vm-urls.js rejects a bad VM number or domain. Returns the surface. */
+function normalizeSurface(surface) {
+  if (!SURFACES.includes(surface)) {
+    throw new Error(
+      `surface must be one of ${SURFACES.join('|')}, got: ${surface}`,
+    );
+  }
+  return surface;
+}
+
+/** The zonal NEG name for a (VM, surface): `vm-<N>-<surface>-neg`. One network
+ *  endpoint group per surface points at the VM's internal IP + that surface's
+ *  port — the Google-native analog of a cloudflared ingress rule's local origin. */
+function negName(n, surface) {
+  const num = normalizeVmNumber(n);
+  return `vm-${num}-${normalizeSurface(surface)}-neg`;
+}
+
+/** The backend-service name for a (VM, surface): `vm-<N>-<surface>-bes`. One
+ *  backend service per host rule wraps the matching NEG (with IAP + a health
+ *  check); the URL map's host rule points at this name. */
+function backendServiceName(n, surface) {
+  const num = normalizeVmNumber(n);
+  return `vm-${num}-${normalizeSurface(surface)}-bes`;
+}
+
+/** The URL-map host rules for a VM: one `{ host, surface, backendService }` per
+ *  surface, where `host` is the EXACT hostname vm-urls.js derives (so the LB
+ *  routes the same hostnames the cert covers and DNS resolves) and
+ *  `backendService` is this module's name for that surface. Reusing
+ *  `vmHostnames` rather than re-deriving keeps the hostname scheme single-sourced.
+ *  Returns the surfaces in SURFACES order so the provisioner's output is stable.
+ *
+ *  An optional `slug` overrides the routed `host` with the VM's custom hostname
+ *  (`<slug>.<surface>.<domain>`) while the NEG / `backendService` names stay
+ *  keyed off the VM NUMBER — the slug changes only what the URL map matches, not
+ *  the internal GCP resource names. */
+function urlMapHostRules(n, domain, slug) {
+  const hosts = vmHostnames(n, domain, slug); // also validates n, domain, slug
+  return SURFACES.map((surface) => ({
+    host: hosts[surface],
+    surface,
+    backendService: backendServiceName(n, surface),
+  }));
+}
+
+/** Decide which gcloud URL-map operation reconciles a single `(host,
+ *  pathMatcher)` against the map's CURRENT state, given `hostRules` — the
+ *  flattened `[{ host, pathMatcher }]` projection of the URL map's host rules
+ *  (one entry per host, since one host rule can list several hosts). Returns
+ *  `{ op }`, one of:
+ *    - `skip`            — `host` already routes to `pathMatcher`; nothing to do.
+ *    - `add-host-rule`   — `pathMatcher` already exists (some other host points
+ *                          at it, e.g. the numeric `vmN.<surface>` host) but
+ *                          `host` is not attached: attach it. Fixes the
+ *                          `Duplicate path matcher` failure on a reused slug.
+ *    - `repoint`         — `host` exists but aims at a DIFFERENT matcher (a stale
+ *                          rule left by a destroyed VM): remove it, then attach
+ *                          `host` to the correct matcher. Fixes a reused slug
+ *                          silently skipped as "already configured" while it
+ *                          still routed to a dead backend.
+ *    - `add-path-matcher`— neither `host` nor `pathMatcher` is present: create
+ *                          the matcher and attach the host (the original path).
+ *
+ *  Pure and side-effect-free — no gcloud, no I/O — so vm-ingress.sh can read the
+ *  URL-map state in bash, ask this helper for the op, and run the matching
+ *  gcloud command, keeping the four-way decision unit-testable (the same
+ *  bash↔node contract the name derivations above follow). Tolerates a
+ *  missing/empty `hostRules`. */
+function hostRuleOperation({ hostRules, host, pathMatcher } = {}) {
+  if (!host) throw new Error('hostRuleOperation requires a host');
+  if (!pathMatcher) throw new Error('hostRuleOperation requires a pathMatcher');
+  const rules = Array.isArray(hostRules) ? hostRules : [];
+  const existing = rules.find((r) => r && r.host === host);
+  if (existing) {
+    return { op: existing.pathMatcher === pathMatcher ? 'skip' : 'repoint' };
+  }
+  const matcherExists = rules.some((r) => r && r.pathMatcher === pathMatcher);
+  return { op: matcherExists ? 'add-host-rule' : 'add-path-matcher' };
+}
+
+/** Decide whether a NEG must be attached as a backend to its backend service,
+ *  given `backends` — the BES's CURRENT `backends[].group` self-links (what
+ *  `gcloud compute backend-services describe --format='value(backends[].group)'`
+ *  emits) — and `neg`, the bare NEG name this surface expects. Returns `{ op }`:
+ *    - `skip`   — some current backend already resolves to `neg`; nothing to do.
+ *    - `attach` — `neg` is not yet a backend (an empty BES, or one wired to a
+ *                 different group): `add-backend` it.
+ *
+ *  `backends[].group` is a full self-link
+ *  (`.../networkEndpointGroups/vm-3-editor-neg`), so the match compares by
+ *  basename — the bare NEG name — not the whole URL. Pure and side-effect-free
+ *  (no gcloud, no I/O), so vm-ingress.sh reads the BES's backends in bash, asks
+ *  this helper for the op, and `add-backend`s only when it returns `attach`: the
+ *  same bash↔node contract `hostRuleOperation` follows. This is what makes `up`
+ *  *converge* a BES that pre-exists with zero backends (the permanent-503 empty-
+ *  backend bug) instead of skipping the attach as "already configured". Throws on
+ *  a missing `neg` (mirrors `hostRuleOperation`'s guard); tolerates a
+ *  missing/empty `backends`. */
+function backendNegAttachOperation({ backends, neg } = {}) {
+  if (!neg) throw new Error('backendNegAttachOperation requires a neg');
+  const groups = Array.isArray(backends) ? backends : [];
+  const basename = (g) => String(g).split('/').pop();
+  const attached = groups.some((g) => g && basename(g) === neg);
+  return { op: attached ? 'skip' : 'attach' };
+}
+
+/** The dashboard's backend-service name: `dashboard-bes`. The dashboard is a
+ *  single fleet-wide surface (not per-VM), so its name carries no VM number. The
+ *  backend itself is only fully wired once the dashboard moves onto GCE
+ *  (vm-dashboard-on-gce), but the name is defined here so the shared provisioner
+ *  and that dependent plan agree. */
+function dashboardBackendServiceName() {
+  return 'dashboard-bes';
+}
+
+/** The dashboard's zonal NEG name: `dashboard-neg`. One network endpoint group
+ *  points at the operator host's internal IP + the dashboard port (8787) — the
+ *  Google-native analog of the dashboard's old ngrok upstream. Single fleet-wide
+ *  surface, so (like the backend-service name) it carries no VM number. Wired by
+ *  scripts/gcp/dashboard-ingress.sh once the dashboard moves onto GCE. */
+function dashboardNegName() {
+  return 'dashboard-neg';
+}
+
+/** The dashboard's dedicated health-check name: `dashboard-hc`. The per-VM
+ *  surfaces share `fleet-ingress-hc` (port 14199), but the dashboard backend
+ *  health-checks its own port (8787, path /healthz), so it needs its own check
+ *  rather than reusing the editor-port one. */
+function dashboardHealthCheckName() {
+  return 'dashboard-hc';
+}
+
+/** The dashboard's single URL-map host rule: `{ host, backendService }`, where
+ *  `host` is `dashboard.<domain>` from vm-urls.js. Separate from
+ *  `urlMapHostRules` because the dashboard is fleet-wide, not keyed off a VM
+ *  number. */
+function dashboardHostRule(domain) {
+  return {
+    host: dashboardHostname(domain), // validates domain
+    backendService: dashboardBackendServiceName(),
+  };
+}
+
+module.exports = {
+  SURFACES,
+  EDITOR_PORT,
+  editorPort,
+  normalizeSurface,
+  negName,
+  backendServiceName,
+  urlMapHostRules,
+  hostRuleOperation,
+  backendNegAttachOperation,
+  dashboardBackendServiceName,
+  dashboardNegName,
+  dashboardHealthCheckName,
+  dashboardHostRule,
+};