@caelo-cms/provisioning 0.10.47 → 0.10.49

package/src/caddy.ts

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P14 — Caddyfile generator.
+ *
+ * Reads the `domains` table + the deploy targets and emits a
+ * deterministic Caddyfile string. The CLI's `regenerate-caddy`
+ * sub-command writes this to `/etc/caddy/Caddyfile` and runs
+ * `caddy reload`.
+ *
+ * Per-vhost shape:
+ *   <hostname> {
+ *     # admin   → reverse_proxy localhost:5173
+ *     # public  → root + try_files (static), with /api/* → gateway
+ *     tls <ownerEmail>
+ *   }
+ *
+ * Staging vhosts force `X-Robots-Tag: noindex`.
+ *
+ * Public vhosts mark content-hashed build outputs (fonts, plugin
+ * bundles — `CONTENT_HASHED_PATH_PATTERN` in @caelo-cms/shared)
+ * `immutable` for a year. Everything else keeps Caddy's file_server
+ * default (no Cache-Control; ETag + Last-Modified for revalidation),
+ * so pages and slug-addressed media are never pinned in caches. The
+ * matcher also requires the file to exist (`file`), so a 404 for a
+ * hashed URL (an old page requesting an asset the new build dropped)
+ * is never cached for a year.
+ *
+ * `.ico` files (theme favicons) are served as `image/x-icon`, the one
+ * icon MIME the media library stores and `<link rel="icon" type>`
+ * declares. file_server only fills Content-Type when no earlier handler
+ * set it, so the `header` line wins over the host's mime.types name.
+ */
+
+import { CONTENT_HASHED_PATH_PATTERN, IMMUTABLE_CACHE_CONTROL } from "@caelo-cms/shared";
+
+export interface CaddyDomainSpec {
+  readonly hostname: string;
+  readonly kind: "admin" | "public";
+  readonly env: "production" | "staging";
+}
+
+export interface CaddyfileSpec {
+  readonly ownerEmail: string;
+  readonly publicSiteRoot: string; // absolute path on disk
+  readonly stagingSiteRoot: string;
+  readonly adminPort: number;
+  readonly gatewayPort: number;
+  readonly domains: ReadonlyArray<CaddyDomainSpec>;
+}
+
+export function generateCaddyfile(spec: CaddyfileSpec): string {
+  const blocks: string[] = [];
+
+  // Global options.
+  blocks.push(`{
+  email ${spec.ownerEmail}
+}
+`);
+
+  for (const d of spec.domains) {
+    blocks.push(vhost(d, spec));
+  }
+
+  // Localhost dev fallback when no domains are configured (so a fresh
+  // `cms-provision` produces a working Caddyfile even pre-DNS).
+  if (spec.domains.length === 0) {
+    blocks.push(`# No domains configured yet — cms-provision regenerate-caddy
+# will overwrite this file when you add one at /settings/domains.
+:8081 {
+  reverse_proxy localhost:${spec.adminPort}
+}
+`);
+  }
+
+  return blocks.join("\n");
+}
+
+function vhost(d: CaddyDomainSpec, spec: CaddyfileSpec): string {
+  const noindex = d.env === "staging" ? `\n  header X-Robots-Tag "noindex"` : "";
+  if (d.kind === "admin") {
+    return `${d.hostname} {${noindex}
+  reverse_proxy localhost:${spec.adminPort}
+}
+`;
+  }
+  // public — API routes go to the gateway,
+  // the rest serves static files. Locale variants serve from a
+  const root = d.env === "staging" ? spec.stagingSiteRoot : spec.publicSiteRoot;
+  return `${d.hostname} {${noindex}
+  root * ${root}
+  @content_hashed {
+    path_regexp content_hashed ${CONTENT_HASHED_PATH_PATTERN}
+    file
+  }
+  header @content_hashed Cache-Control "${IMMUTABLE_CACHE_CONTROL}"
+  @ico path *.ico
+  header @ico Content-Type "image/x-icon"
+  handle /api/* {
+    reverse_proxy localhost:${spec.gatewayPort}
+  }
+  handle /admin/* {
+    reverse_proxy localhost:${spec.adminPort}
+  }
+  handle {
+    file_server {
+      try_files {path} {path}/index.html /index.html
+    }
+  }
+}
+`;
+}

package/src/cdn-copy.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P15 — per-provider CDN-copy adapter contract.
+ *
+ * P7 ships the `media_assets.usage_count` threshold + the `media.set_cdn`
+ * op that flips a per-asset boolean. P15 wires the actual edge-pin
+ * operation per provider:
+ *   - AWS  → CloudFront cache invalidation + warmer request.
+ *   - GCP  → set Cache-Control metadata on the GCS object so Cloud CDN
+ *           respects the long TTL.
+ *   - Azure → Front Door purge + warm endpoint.
+ *
+ * The redeploy-orchestrator's `cdnCopyTick()` (currently a no-op for
+ * cloud installs) drains the per-asset CDN-pin queue using the adapter
+ * registered for the active provider.
+ *
+ * Each provider's stack publishes a `CdnCopyAdapter` instance via its
+ * Pulumi outputs (the actual implementation is dynamically imported by
+ * the orchestrator at runtime so `@caelo-cms/provisioning` doesn't pull in
+ * `@aws-sdk/...`/`@google-cloud/...`/`@azure/...` as static deps). The
+ * interface defined here is the only thing both sides agree on.
+ */
+
+export interface CdnCopyAdapter {
+  /**
+   * Mark the asset at `assetKey` (object key in primary storage) as
+   * CDN-cached. Returns the public CDN URL — admin uses this as the
+   * canonical URL for the asset thereafter.
+   */
+  pin(assetKey: string): Promise<string>;
+  /** Reverse — drop from CDN edge cache. */
+  unpin(assetKey: string): Promise<void>;
+}
+
+/**
+ * No-op adapter for self-hosted installs (Caddy serves directly from
+ * disk; no separate CDN tier). Returns the input asset key as a relative
+ * URL so callers don't have to special-case the no-CDN case.
+ */
+export const selfHostedCdnCopy: CdnCopyAdapter = {
+  async pin(assetKey) {
+    return `/media/${assetKey}`;
+  },
+  async unpin() {
+    // no-op
+  },
+};
+
+/**
+ * Resolves the right adapter per `process.env.CAELO_PROVIDER`. Lazy
+ * dynamic-imports the per-provider implementation so a self-hosted
+ * install never loads the cloud SDKs.
+ *
+ * Returns `selfHostedCdnCopy` ONLY for `provider==='self-hosted'` or an
+ * unset env (treated as self-hosted). For `gcp`/`aws`/`azure`, the
+ * matching `cdn-copy-<gcs|aws|azure>.ts` file MUST exist in this
+ * directory — those land with the per-provider PRs. Per CLAUDE.md §2
+ * "no fallbacks pre-1.0" we deliberately do NOT silently degrade to
+ * the self-hosted no-op when the file is missing: a missing module is
+ * a deploy bug + the orchestrator tick should crash loudly so the
+ * operator notices instead of silently dropping CDN-pin requests.
+ */
+export async function loadCdnCopyAdapter(provider?: string): Promise<CdnCopyAdapter> {
+  switch (provider) {
+    case "gcp":
+      // biome-ignore lint/suspicious/noExplicitAny: opt-in dynamic import
+      return ((await import("./cdn-copy-gcs.js" as string)) as any).gcsCloudCdnPin;
+    case "gcp-firebase":
+      // v0.3.0 — Firebase Hosting manages CDN caching natively (each
+      // deploy creates an immutable version + the CDN's freshness is
+      // dictated by Firebase Hosting headers). There's no per-asset
+      // "pin to edge" API; this adapter is effectively a no-op that
+      // returns the same shape as self-hosted.
+      return selfHostedCdnCopy;
+    case "aws":
+      // biome-ignore lint/suspicious/noExplicitAny: opt-in dynamic import
+      return ((await import("./cdn-copy-aws.js" as string)) as any).s3CloudfrontPrewarm;
+    case "azure":
+      // biome-ignore lint/suspicious/noExplicitAny: opt-in dynamic import
+      return ((await import("./cdn-copy-azure.js" as string)) as any).azureBlobCdnPrefetch;
+    case undefined:
+    case "":
+    case "self-hosted":
+      return selfHostedCdnCopy;
+    default:
+      throw new Error(
+        `loadCdnCopyAdapter: unknown CAELO_PROVIDER='${provider}'. Expected one of: self-hosted | gcp | gcp-firebase | aws | azure.`,
+      );
+  }
+}

package/src/cert-wait.test.ts

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { type CertProbe, domainMappingProbe, lbCertProbe, waitForCert } from "./cert-wait.js";
+import type { GcloudResult } from "./gcloud.js";
+
+const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitCode: 0 });
+const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
+
+/** A fake clock the injected sleep advances. */
+function clock() {
+  let t = 0;
+  return {
+    now: () => t,
+    sleep: async (ms: number) => {
+      t += ms;
+    },
+    elapsed: () => t,
+  };
+}
+
+function probes(...seq: CertProbe[]) {
+  let i = 0;
+  return async () => seq[Math.min(i++, seq.length - 1)] as CertProbe;
+}
+
+describe("waitForCert", () => {
+  it("returns once the probe reports ready, reporting each new detail once", async () => {
+    const c = clock();
+    const updates: string[] = [];
+    const r = await waitForCert({
+      probe: probes(
+        { state: "pending", detail: "waiting for DNS" },
+        { state: "pending", detail: "waiting for DNS" },
+        { state: "pending", detail: "issuing" },
+        { state: "ready" },
+      ),
+      timeoutMs: 60_000,
+      intervalMs: 10_000,
+      onUpdate: (d) => updates.push(d),
+      ...c,
+    });
+    expect(r).toEqual({ ok: true });
+    expect(updates).toEqual(["waiting for DNS", "issuing"]);
+    expect(c.elapsed()).toBe(30_000);
+  });
+
+  it("times out with the last detail instead of waiting forever", async () => {
+    const c = clock();
+    const r = await waitForCert({
+      probe: probes({ state: "pending", detail: "CertificateProvisioned: DNS not set" }),
+      timeoutMs: 25_000,
+      intervalMs: 10_000,
+      ...c,
+    });
+    expect(r).toEqual({
+      ok: false,
+      reason: "timeout",
+      lastDetail: "CertificateProvisioned: DNS not set",
+    });
+    // Probed at 0, 10s, 20s, 25s (the deadline) — never slept past it.
+    expect(c.elapsed()).toBe(25_000);
+  });
+
+  it("stops at once when gcloud fails, since waiting cannot fix that", async () => {
+    const c = clock();
+    const r = await waitForCert({
+      probe: probes({ state: "error", error: "PERMISSION_DENIED" }),
+      timeoutMs: 60_000,
+      intervalMs: 10_000,
+      ...c,
+    });
+    expect(r).toEqual({ ok: false, reason: "error", error: "PERMISSION_DENIED" });
+    expect(c.elapsed()).toBe(0);
+  });
+});
+
+const target = { hostname: "admin.example.com", region: "europe-west1", projectId: "p" };
+
+describe("domainMappingProbe", () => {
+  it("is ready when the mapping's Ready condition is True", async () => {
+    const calls: string[][] = [];
+    const run = async (args: string[]) => {
+      calls.push(args);
+      return ok(JSON.stringify({ status: { conditions: [{ type: "Ready", status: "True" }] } }));
+    };
+    expect(await domainMappingProbe(run, target)).toEqual({ state: "ready" });
+    expect(calls[0]).toEqual([
+      "beta",
+      "run",
+      "domain-mappings",
+      "describe",
+      "--domain=admin.example.com",
+      "--region=europe-west1",
+      "--project=p",
+      "--format=json",
+    ]);
+  });
+
+  it("reports the certificate condition's message while pending", async () => {
+    const run = async () =>
+      ok(
+        JSON.stringify({
+          status: {
+            conditions: [
+              { type: "Ready", status: "Unknown", message: "not ready" },
+              {
+                type: "CertificateProvisioned",
+                status: "Unknown",
+                message: "Certificate issuance pending. Add the DNS record.",
+              },
+              { type: "DomainRoutable", status: "True" },
+            ],
+          },
+        }),
+      );
+    expect(await domainMappingProbe(run, target)).toEqual({
+      state: "pending",
+      detail: "CertificateProvisioned: Certificate issuance pending. Add the DNS record.",
+    });
+  });
+
+  it("is pending (not ready) before Google reports any condition", async () => {
+    const run = async () => ok(JSON.stringify({ status: {} }));
+    expect((await domainMappingProbe(run, target)).state).toBe("pending");
+  });
+
+  it("surfaces a gcloud failure as an error", async () => {
+    const run = async () => fail("ERROR: (gcloud) You do not currently have an active account");
+    const r = await domainMappingProbe(run, target);
+    expect(r.state).toBe("error");
+  });
+});
+
+describe("lbCertProbe", () => {
+  const list = (certs: unknown[]) => async () => ok(JSON.stringify(certs));
+  const lb = { projectId: "p", hostname: "admin.example.com" };
+
+  it("is ready when the admin's own certificate is ACTIVE although the main domain's is not", async () => {
+    const r = await lbCertProbe(
+      list([
+        {
+          name: "combined",
+          managed: {
+            status: "PROVISIONING",
+            domainStatus: { "example.com": "FAILED_NOT_VISIBLE", "admin.example.com": "ACTIVE" },
+          },
+        },
+        {
+          name: "admin-only",
+          managed: { status: "ACTIVE", domainStatus: { "admin.example.com": "ACTIVE" } },
+        },
+      ]),
+      lb,
+    );
+    expect(r).toEqual({ state: "ready" });
+  });
+
+  it("does not count a domain that is ACTIVE on a certificate that is not served yet", async () => {
+    const r = await lbCertProbe(
+      list([
+        {
+          name: "combined",
+          managed: {
+            status: "PROVISIONING",
+            domainStatus: { "example.com": "FAILED_NOT_VISIBLE", "admin.example.com": "ACTIVE" },
+          },
+        },
+      ]),
+      lb,
+    );
+    expect(r).toEqual({ state: "pending", detail: "combined: admin.example.com ACTIVE" });
+  });
+
+  it("is ready for installs that only have the combined certificate, once it is ACTIVE", async () => {
+    const r = await lbCertProbe(
+      list([
+        {
+          name: "combined",
+          managed: {
+            status: "ACTIVE",
+            domainStatus: { "example.com": "ACTIVE", "admin.example.com": "ACTIVE" },
+          },
+        },
+      ]),
+      lb,
+    );
+    expect(r).toEqual({ state: "ready" });
+  });
+
+  it("is pending when no certificate lists the host", async () => {
+    expect((await lbCertProbe(list([]), lb)).state).toBe("pending");
+  });
+});

package/src/cert-wait.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Waiting for a Google-managed TLS certificate (§11.C: the CLI polls certs
+ * itself instead of telling the operator to check back later).
+ *
+ * Two certificate sources, one wait loop:
+ *   - the `gcp` load balancer's managed SSL certificates
+ *     ({@link lbCertProbe}) — the installer waits for the admin host;
+ *   - a Cloud Run domain mapping's certificate ({@link domainMappingProbe})
+ *     — `admin-domain enable` / `staging-domain enable` on gcp-firebase.
+ *
+ * {@link waitForCert} is pure apart from its injected clock, sleep and
+ * probe, so the timeout and progress behaviour is unit-tested without
+ * gcloud or real time.
+ */
+
+import type { GcloudResult } from "./gcloud.js";
+
+type Run = (args: string[]) => Promise<GcloudResult>;
+
+/** One look at a certificate. */
+export type CertProbe =
+  | { readonly state: "ready" }
+  | { readonly state: "pending"; readonly detail: string }
+  /** gcloud itself failed (auth, permissions) — waiting will not fix it. */
+  | { readonly state: "error"; readonly error: string };
+
+export type CertWaitResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: "timeout"; readonly lastDetail: string }
+  | { readonly ok: false; readonly reason: "error"; readonly error: string };
+
+export interface CertWaitOpts {
+  readonly probe: () => Promise<CertProbe>;
+  readonly timeoutMs: number;
+  readonly intervalMs: number;
+  /** Called whenever the probe's detail text changes (spinner message). */
+  readonly onUpdate?: (detail: string) => void;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly now?: () => number;
+}
+
+/**
+ * Poll `probe` until the certificate is ready, gcloud fails, or `timeoutMs`
+ * passes. The probe runs once more at the deadline so a certificate that
+ * flips during the last interval is not reported as a timeout.
+ */
+export async function waitForCert(opts: CertWaitOpts): Promise<CertWaitResult> {
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const deadline = now() + opts.timeoutMs;
+  let lastDetail = "";
+  for (;;) {
+    const p = await opts.probe();
+    if (p.state === "ready") return { ok: true };
+    if (p.state === "error") return { ok: false, reason: "error", error: p.error };
+    if (p.detail !== lastDetail) {
+      lastDetail = p.detail;
+      opts.onUpdate?.(p.detail);
+    }
+    const remaining = deadline - now();
+    if (remaining <= 0) return { ok: false, reason: "timeout", lastDetail };
+    await sleep(Math.min(opts.intervalMs, remaining));
+  }
+}
+
+interface MappingCondition {
+  type?: string;
+  status?: string;
+  message?: string;
+  reason?: string;
+}
+
+/**
+ * The certificate state of the Cloud Run domain mapping for `hostname`.
+ * Ready once the mapping's `Ready` condition is True (Google sets it after
+ * `CertificateProvisioned` and `DomainRoutable`); until then the detail is
+ * the first non-True condition's message, which says what Google waits for
+ * (usually the DNS record).
+ */
+export async function domainMappingProbe(
+  run: Run,
+  target: { readonly hostname: string; readonly region: string; readonly projectId: string },
+): Promise<CertProbe> {
+  const r = await run([
+    "beta",
+    "run",
+    "domain-mappings",
+    "describe",
+    `--domain=${target.hostname}`,
+    `--region=${target.region}`,
+    `--project=${target.projectId}`,
+    "--format=json",
+  ]);
+  if (!r.ok) return { state: "error", error: `describe the domain mapping: ${r.stderr.trim()}` };
+  const conditions =
+    (JSON.parse(r.stdout) as { status?: { conditions?: MappingCondition[] } }).status?.conditions ??
+    [];
+  const ready = conditions.find((c) => c.type === "Ready");
+  if (ready?.status === "True") return { state: "ready" };
+  const blocking =
+    conditions.find((c) => c.type === "CertificateProvisioned" && c.status !== "True") ??
+    conditions.find((c) => c.status !== "True");
+  const detail = blocking
+    ? `${blocking.type}: ${blocking.message || blocking.reason || blocking.status || "pending"}`
+    : "Google has not reported the mapping's status yet";
+  return { state: "pending", detail };
+}
+
+interface SslCertificateJson {
+  name?: string;
+  managed?: { status?: string; domainStatus?: Record<string, string> };
+}
+
+/**
+ * Whether the `gcp` load balancer has an ACTIVE managed certificate that
+ * covers `hostname`. Any such certificate counts: installs from before the
+ * admin got its own certificate serve the admin from the combined one.
+ * A certificate is only served once its overall status is ACTIVE, so a
+ * combined certificate whose other domain still fails does not count.
+ */
+export async function lbCertProbe(
+  run: Run,
+  target: { readonly projectId: string; readonly hostname: string },
+): Promise<CertProbe> {
+  const r = await run([
+    "compute",
+    "ssl-certificates",
+    "list",
+    "--global",
+    `--project=${target.projectId}`,
+    "--format=json",
+  ]);
+  if (!r.ok) return { state: "error", error: `list SSL certificates: ${r.stderr.trim()}` };
+  const covering = (JSON.parse(r.stdout) as SslCertificateJson[]).filter(
+    (c) => c.managed?.domainStatus?.[target.hostname] !== undefined,
+  );
+  if (
+    covering.some(
+      (c) =>
+        c.managed?.status === "ACTIVE" && c.managed.domainStatus?.[target.hostname] === "ACTIVE",
+    )
+  ) {
+    return { state: "ready" };
+  }
+  if (covering.length === 0) {
+    return { state: "pending", detail: `no managed certificate lists ${target.hostname} yet` };
+  }
+  const detail = covering
+    .map(
+      (c) =>
+        `${c.name ?? "certificate"}: ${target.hostname} ${c.managed?.domainStatus?.[target.hostname]}`,
+    )
+    .join("; ");
+  return { state: "pending", detail };
+}
+
+/**
+ * How long the CLI waits for a certificate before handing the operator the
+ * status command. Google documents up to 60 min after DNS resolves.
+ */
+export const CERT_WAIT_TIMEOUT_MS = 60 * 60 * 1000;