@specific.dev/spectest 0.38.0 → 0.41.0

package/src/ingress.ts

@@ -0,0 +1,305 @@
+// Low-level ingress primitives — the first-class building blocks the
+// daemon's networking is expressed in terms of. The friendly
+// `services.<name>.tls` / `services.<name>.hostnames` fields and
+// `defineFake(...)` are all *sugar* that lower onto these three:
+//
+//   certificate(hostnames)      — mint a leaf cert from the in-VM root CA
+//   dnsName(hostname, target)   — register a name → a container or the daemon
+//   proxy(hostname, upstream)   — reverse-proxy a hostname to a service:port
+//
+// The daemon consumes only the lowered result (see `lowerIngress`), so it
+// never special-cases tls/hostnames/fakes — it just executes a generic set
+// of certs, proxy routes, DNS registrations, and aliases. A user-authored
+// component emits the same primitives by attaching them with `provides(...)`,
+// so it can do anything the built-ins do without any daemon change.
+//
+// None of this is part of the wire `EnvironmentConfig` the control plane
+// deserialises: the decls live on the `Project` (daemon-side only) and,
+// when attached to a service, ride on a Symbol key that `JSON.stringify`
+// drops — so Rust's `deny_unknown_fields` never sees them.
+
+import type { FakeDefinition, Project, ServiceConfig } from "./index.js";
+
+/** Where a DNS name points. `ingress` = the harness's listener on the
+ *  bridge gateway (fakes, TLS-terminated proxies); `service` = a container's
+ *  live IP on spectest-net (a plain peer alias, no daemon hop). */
+export type DnsTarget = { ingress: true } | { service: string };
+
+export interface CertificateDecl {
+  kind: "certificate";
+  /** Hostnames the leaf cert's SANs cover. One cert is minted per decl. */
+  hostnames: string[];
+}
+
+export interface DnsDecl {
+  kind: "dns";
+  hostname: string;
+  target: DnsTarget;
+}
+
+export interface ProxyDecl {
+  kind: "proxy";
+  hostname: string;
+  upstream: { service: string; port: number };
+}
+
+export type IngressDecl = CertificateDecl | DnsDecl | ProxyDecl;
+
+/** Token a component can use in a decl where it can't know its own
+ *  services-map key yet — resolved to that key during `lowerIngress`.
+ *  Mirrors the `{{SPECTEST_SERVICE}}` token honoured in `files`. */
+export const SELF_SERVICE_TOKEN = "{{SPECTEST_SERVICE}}";
+
+// Multi-label hostname: at least one dot, each label 1–63 chars of
+// [a-z0-9-], no leading/trailing hyphen. Kept in lockstep with index.ts.
+const HOSTNAME_RE =
+  /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+
+function assertHostname(h: string, ctx: string): void {
+  const lower = h.toLowerCase();
+  if (!HOSTNAME_RE.test(lower)) {
+    throw new Error(
+      `${ctx}: invalid hostname ${JSON.stringify(h)} — must be a multi-label DNS name (e.g. "api.stripe.com")`,
+    );
+  }
+  if (lower === "internal" || lower.endsWith(".internal")) {
+    throw new Error(
+      `${ctx}: hostname ${JSON.stringify(h)} ends in the reserved ".internal" TLD`,
+    );
+  }
+}
+
+/** A wildcard is `*.` + a normal multi-label hostname (e.g.
+ *  `*.example.com`). It matches any name ending in that suffix. */
+export function isWildcard(hostname: string): boolean {
+  return hostname.startsWith("*.");
+}
+
+/** Validate an exact hostname OR a `*.suffix` wildcard. */
+function assertNameOrWildcard(h: string, ctx: string): void {
+  if (isWildcard(h)) {
+    // The bit after `*.` must itself be a valid multi-label hostname, so
+    // `*.example.com` is fine but `*.com` (too broad) and `*` are not.
+    assertHostname(h.slice(2), `${ctx} wildcard`);
+    return;
+  }
+  assertHostname(h, ctx);
+}
+
+/**
+ * Request a leaf certificate (signed by the in-VM root CA) covering
+ * `hostnames`. The daemon binds it on the HTTPS ingress (:443, SNI per
+ * hostname). Pairs with a `proxy(...)` (TLS-terminated reverse proxy) or a
+ * fake handler; on its own it just makes those hostnames serve HTTPS.
+ *
+ * A `*.suffix` wildcard is allowed and becomes a wildcard SAN, so one cert
+ * covers a whole domain (`*.us-east-1.amazonaws.com`). As in any TLS
+ * client, a wildcard SAN covers exactly **one** label — `*.example.com`
+ * matches `api.example.com`, not `a.b.example.com`.
+ */
+export function certificate(hostnames: string[]): CertificateDecl {
+  if (!Array.isArray(hostnames) || hostnames.length === 0) {
+    throw new Error("certificate(): at least one hostname is required");
+  }
+  for (const h of hostnames) assertNameOrWildcard(h, "certificate()");
+  return { kind: "certificate", hostnames: hostnames.map((h) => h.toLowerCase()) };
+}
+
+/**
+ * Register `hostname` in spectest's DNS. `{ ingress: true }` points it at
+ * the daemon (for fakes / TLS proxies — resolved to the bridge gateway and
+ * injected as `--add-host` into every container); `{ service }` makes it an
+ * extra peer alias for that container (resolved live to its IP). The
+ * `SELF_SERVICE_TOKEN` may be used for `service` when a component can't yet
+ * know its own key.
+ */
+export function dnsName(hostname: string, target: DnsTarget): DnsDecl {
+  assertNameOrWildcard(hostname, "dnsName()");
+  if (!("ingress" in target) && !("service" in target)) {
+    throw new Error(
+      `dnsName(${JSON.stringify(hostname)}): target must be { ingress: true } or { service }`,
+    );
+  }
+  return { kind: "dns", hostname: hostname.toLowerCase(), target };
+}
+
+/**
+ * Reverse-proxy `hostname` to `http://<service>:<port>` on spectest-net.
+ * Implies the hostname resolves to the daemon ingress, so containers reach
+ * it without any extra `dnsName(...)`. Add a `certificate([hostname])` to
+ * serve it over HTTPS as well as HTTP.
+ *
+ * `hostname` may be a `*.suffix` wildcard, which sends every name under
+ * that domain to the same upstream — one route for a whole API surface
+ * (`*.us-east-1.amazonaws.com` → a LocalStack container). Exact routes
+ * always win over wildcards, and the longest wildcard suffix wins among
+ * wildcards.
+ */
+export function proxy(
+  hostname: string,
+  upstream: { service: string; port: number },
+): ProxyDecl {
+  assertNameOrWildcard(hostname, "proxy()");
+  if (!upstream || typeof upstream.service !== "string" || typeof upstream.port !== "number") {
+    throw new Error(
+      `proxy(${JSON.stringify(hostname)}): upstream must be { service: string, port: number }`,
+    );
+  }
+  return { kind: "proxy", hostname: hostname.toLowerCase(), upstream };
+}
+
+/** Symbol key under which `provides(...)` stashes a component's ingress
+ *  decls on its service object. A Symbol so `JSON.stringify(environment)`
+ *  (the wire config shipped to the Rust control plane) drops it — symbol
+ *  keys are never serialised, regardless of enumerability. Kept
+ *  *enumerable* so it survives the common `{ ...component() }` spread (object
+ *  spread copies enumerable symbol props but skips non-enumerable ones). */
+const INGRESS_DECLS: unique symbol = Symbol.for("spectest.ingress.decls");
+
+/**
+ * Attach low-level ingress decls to a service definition a component
+ * returns. The decls are read by `lowerIngress` at load time and never
+ * serialised into the wire config.
+ *
+ * ```ts
+ * return provides({ image, command }, [
+ *   certificate(["app.test"]),
+ *   dnsName("app.test", { ingress: true }),
+ *   proxy("app.test", { service: SELF_SERVICE_TOKEN, port: 3000 }),
+ * ]);
+ * ```
+ */
+export function provides<T extends ServiceConfig>(
+  service: T,
+  decls: IngressDecl[],
+): T {
+  // Merge with any decls already attached (e.g. a component built via
+  // provides() that the caller then wraps again) so neither layer is lost.
+  const prior = readProvided(service);
+  Object.defineProperty(service, INGRESS_DECLS, {
+    value: [...prior, ...decls],
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+  return service;
+}
+
+function readProvided(service: ServiceConfig): IngressDecl[] {
+  const decls = (service as unknown as Record<symbol, unknown>)[INGRESS_DECLS];
+  return Array.isArray(decls) ? (decls as IngressDecl[]) : [];
+}
+
+/** Everything the daemon needs to stand up ingress, derived once per
+ *  /load. The daemon executes this generically — it reads neither
+ *  `svc.tls` nor `svc.hostnames` directly. */
+export interface LoweredIngress {
+  /** One leaf cert per group; SANs = the group's hostnames. */
+  certificates: { hostnames: string[] }[];
+  /** Reverse-proxy routes: hostname → upstream service:port. */
+  proxies: { hostname: string; service: string; port: number }[];
+  /** Hostnames that resolve to the daemon ingress gateway (DNS registry
+   *  + `--add-host` on every container). Covers fakes, TLS proxies, and
+   *  any `dnsName(h, { ingress: true })`. */
+  ingressHosts: string[];
+  /** service key → extra `--network-alias`es (from `hostnames` /
+   *  `dnsName(h, { service })`). */
+  aliasesByService: Record<string, string[]>;
+  /** Wildcard suffixes (`*.example.com` → `.example.com`) and where they
+   *  point. Resolved to a concrete IP in the daemon (service → that
+   *  container's IP, ingress → the bridge gateway) and written to the
+   *  resolver's wildcard table. Only the resolver answers these — they
+   *  can't be expressed as `--network-alias`/`--add-host`. */
+  wildcards: { pattern: string; target: DnsTarget }[];
+}
+
+function resolveSelf(service: string, selfKey: string): string {
+  return service === SELF_SERVICE_TOKEN ? selfKey : service;
+}
+
+/**
+ * Lower a project's friendly surface (`services.*.tls`,
+ * `services.*.hostnames`, component `provides(...)`, and `fakes`) into the
+ * generic `LoweredIngress` the daemon executes. This is the framework
+ * abstraction the user asked for: the special-casing lives here, in one
+ * pure function, instead of being scattered through the daemon.
+ */
+export function lowerIngress(project: Project): LoweredIngress {
+  const certificates: { hostnames: string[] }[] = [];
+  const proxies: { hostname: string; service: string; port: number }[] = [];
+  const ingressSet = new Set<string>();
+  const aliasesByService: Record<string, string[]> = {};
+  const wildcards: { pattern: string; target: DnsTarget }[] = [];
+
+  const addAlias = (service: string, host: string): void => {
+    (aliasesByService[service] ??= []).push(host.toLowerCase());
+  };
+  const applyDecl = (decl: IngressDecl, selfKey: string): void => {
+    switch (decl.kind) {
+      case "certificate":
+        certificates.push({ hostnames: decl.hostnames });
+        break;
+      case "proxy": {
+        const service = resolveSelf(decl.upstream.service, selfKey);
+        proxies.push({ hostname: decl.hostname, service, port: decl.upstream.port });
+        // A proxied hostname must route to the daemon. A wildcard one can
+        // only be answered by the resolver (there is no `--add-host` for a
+        // pattern), so it goes in the wildcard table pointed at the ingress.
+        if (isWildcard(decl.hostname)) {
+          wildcards.push({ pattern: decl.hostname, target: { ingress: true } });
+        } else {
+          ingressSet.add(decl.hostname);
+        }
+        break;
+      }
+      case "dns": {
+        // A wildcard can only be answered by the resolver (no
+        // --network-alias / --add-host equivalent), so route either kind
+        // of target through the wildcard table; the daemon resolves the IP.
+        if (isWildcard(decl.hostname)) {
+          const target =
+            "service" in decl.target
+              ? { service: resolveSelf(decl.target.service, selfKey) }
+              : decl.target;
+          wildcards.push({ pattern: decl.hostname, target });
+        } else if ("ingress" in decl.target) {
+          ingressSet.add(decl.hostname);
+        } else {
+          addAlias(resolveSelf(decl.target.service, selfKey), decl.hostname);
+        }
+        break;
+      }
+    }
+  };
+
+  for (const [name, svc] of Object.entries(project.environment.services)) {
+    // Component-provided explicit decls.
+    for (const decl of readProvided(svc)) applyDecl(decl, name);
+    // `tls: [{ hostname, port }]` → cert + TLS-terminated reverse proxy.
+    for (const entry of (svc as ServiceConfig).tls ?? []) {
+      applyDecl(certificate([entry.hostname]), name);
+      applyDecl(proxy(entry.hostname, { service: name, port: entry.port }), name);
+    }
+    // `hostnames: [h]` → plain peer alias (no daemon hop).
+    for (const h of (svc as ServiceConfig).hostnames ?? []) {
+      applyDecl(dnsName(h, { service: name }), name);
+    }
+  }
+
+  // Fakes: in-daemon handlers. The handler routing stays keyed by hostname
+  // in the daemon's FAKES map; here we only contribute their networking
+  // (a leaf cert for HTTPS + ingress DNS).
+  for (const fake of Object.values(project.fakes ?? {}) as FakeDefinition[]) {
+    const hostnames = fake.hostnames.map((h) => h.toLowerCase());
+    certificates.push({ hostnames });
+    for (const h of hostnames) ingressSet.add(h);
+  }
+
+  return {
+    certificates,
+    proxies,
+    ingressHosts: [...ingressSet],
+    aliasesByService,
+    wildcards,
+  };
+}