@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/google-ingress.js

@@ -0,0 +1,226 @@
+'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(),
+  };
+}
+
+/** Extract the VM number from an LB-ingress resource name this module mints
+ *  (`vm-<N>-<surface>-neg` or `vm-<N>-<surface>-bes`, surface ∈ SURFACES).
+ *  Returns the number, or null for any name that isn't a per-VM ingress resource
+ *  (the shared `codeyam-dashboard-*` backend, a foreign resource, junk). The
+ *  inverse of negName / backendServiceName — the orphan sweep uses it to map the
+ *  live LB backends back to the VM numbers that own them. The surface alternation
+ *  is built from SURFACES so it stays in lockstep with the name derivations.
+ *  Pure. */
+function vmNumberFromResourceName(name) {
+  const re = new RegExp(`^vm-(\\d+)-(?:${SURFACES.join('|')})-(?:neg|bes)$`);
+  const m = re.exec(String(name == null ? '' : name).trim());
+  return m ? Number(m[1]) : null;
+}
+
+module.exports = {
+  SURFACES,
+  EDITOR_PORT,
+  editorPort,
+  normalizeSurface,
+  negName,
+  backendServiceName,
+  vmNumberFromResourceName,
+  urlMapHostRules,
+  hostRuleOperation,
+  backendNegAttachOperation,
+  dashboardBackendServiceName,
+  dashboardNegName,
+  dashboardHealthCheckName,
+  dashboardHostRule,
+};