@intentius/chant-lexicon-cpln 0.53.0

package/src/composites/public-domain.ts

@@ -0,0 +1,144 @@
+/**
+ * PublicDomain — a custom domain routed to workloads in one GVC.
+ *
+ * Domains carry several rules that are easy to violate by picking the
+ * combination that reads best rather than the one that works:
+ *
+ * - An **apex domain must use `cname` mode**. NS mode does not support apex,
+ *   and there is no partial-credit failure — the domain simply will not
+ *   validate.
+ * - **NS mode requires the `dns01` certificate challenge**; `http01` is
+ *   rejected outright.
+ * - `gvcLink`, `workloadLink` and `ports[].routes` are **mutually exclusive**
+ *   ways of saying where traffic goes; exactly one may be set.
+ * - Every route in a domain must target workloads in the **same GVC**.
+ *
+ * This composite takes a GVC and a route table, derives the mode when it can,
+ * and refuses the combinations above at build time.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Domain } from "../generated";
+
+export interface DomainRoute {
+  /** Path prefix to match (e.g. `/api`). One of `prefix` or `regex`. */
+  prefix?: string;
+  /** RE2 path regex to match. One of `prefix` or `regex`. */
+  regex?: string;
+  /** Name of the workload in `gvc` to route to. */
+  workload: string;
+  /** Port on the workload (default 8080). */
+  port?: number;
+  /** Rewrite the matched prefix to this before forwarding. */
+  replacePrefix?: string;
+}
+
+export interface PublicDomainProps {
+  /** The domain name, e.g. `api.example.com` or the apex `example.com`. */
+  name: string;
+  /** The GVC every route targets. */
+  gvc: string;
+  /**
+   * Routes for the domain. Omit to send all traffic to the GVC's default
+   * routing (a `gvcLink` domain) instead.
+   */
+  routes?: DomainRoute[];
+  /**
+   * DNS mode. Defaults to `cname`, which is also the only mode valid for an
+   * apex domain.
+   */
+  dnsMode?: "cname" | "ns";
+  /**
+   * Certificate challenge type. Defaults to `dns01` under `ns` (the only
+   * option there) and `http01` under `cname`.
+   */
+  certChallengeType?: "dns01" | "http01";
+  /** Public port (default 443). */
+  port?: number;
+  /** Protocol (default `http2`). `tcp` requires a dedicated load balancer. */
+  protocol?: "http" | "http2" | "tcp";
+  /** Tags applied to the domain. */
+  tags?: Record<string, string>;
+  /** Per-member defaults for customizing the underlying resource. */
+  defaults?: {
+    domain?: Partial<ConstructorParameters<typeof Domain>[0]>;
+  };
+}
+
+/** An apex domain has exactly one dot: `example.com`, not `api.example.com`. */
+export function isApexDomain(name: string): boolean {
+  return name.split(".").filter(Boolean).length === 2;
+}
+
+export const PublicDomain = Composite((props: PublicDomainProps) => {
+  const {
+    name,
+    gvc,
+    routes,
+    dnsMode = "cname",
+    certChallengeType = dnsMode === "ns" ? "dns01" : "http01",
+    port = 443,
+    protocol = "http2",
+    tags,
+    defaults: defs,
+  } = props;
+
+  if (dnsMode === "ns" && isApexDomain(name)) {
+    throw new Error(
+      `PublicDomain "${name}": an apex domain must use dnsMode "cname". NS mode does not support apex domains.`,
+    );
+  }
+
+  if (dnsMode === "ns" && certChallengeType !== "dns01") {
+    throw new Error(
+      `PublicDomain "${name}": dnsMode "ns" requires certChallengeType "dns01"; "${certChallengeType}" is rejected.`,
+    );
+  }
+
+  for (const route of routes ?? []) {
+    if (!route.prefix && !route.regex) {
+      throw new Error(`PublicDomain "${name}": every route needs a \`prefix\` or a \`regex\`.`);
+    }
+    if (route.prefix && route.regex) {
+      throw new Error(
+        `PublicDomain "${name}": route for workload "${route.workload}" sets both \`prefix\` and \`regex\`; ` +
+          `only one may be provided.`,
+      );
+    }
+  }
+
+  const domain = new Domain(
+    mergeDefaults(
+      {
+        name,
+        ...(tags && { tags }),
+        spec: {
+          dnsMode,
+          certChallengeType,
+          // `gvcLink` and `ports[].routes` are mutually exclusive: a domain
+          // with explicit routes must not also carry a GVC link.
+          ...(routes && routes.length > 0
+            ? {
+                ports: [
+                  {
+                    number: port,
+                    protocol,
+                    routes: routes.map((route) => ({
+                      ...(route.prefix && { prefix: route.prefix }),
+                      ...(route.regex && { regex: route.regex }),
+                      ...(route.replacePrefix && { replacePrefix: route.replacePrefix }),
+                      port: route.port ?? 8080,
+                      workloadLink: `//gvc/${gvc}/workload/${route.workload}`,
+                    })),
+                  },
+                ],
+              }
+            : { gvcLink: `//gvc/${gvc}` }),
+        },
+      } as Record<string, unknown>,
+      defs?.domain,
+    ),
+  );
+
+  return { domain };
+}, "PublicDomain");

package/src/composites/secret-access.ts

@@ -0,0 +1,136 @@
+/**
+ * SecretAccess — the identity and policy a workload needs to read a secret.
+ *
+ * Control Plane's own documentation calls a partial version of this its number
+ * one support issue: reading a secret at runtime takes three separate steps,
+ * and **missing any one of them fails silently at runtime** rather than at
+ * apply time.
+ *
+ *   1. An identity exists, and the workload's `spec.identityLink` points at it.
+ *   2. A policy grants that identity `reveal` on the secret, with the identity
+ *      named as a principal in a binding.
+ *   3. The workload references the secret in the field-qualified form —
+ *      `cpln://secret/NAME.payload`, not `cpln://secret/NAME`.
+ *
+ * This composite owns steps 1 and 2, and {@link secretRef} exists for step 3 so
+ * the field qualifier is hard to forget.
+ *
+ * The principal link is the part most worth automating. A binding written
+ * against `//identity/NAME` — which reads perfectly naturally, and is what
+ * you would guess — is accepted by the API and then **silently ignored**. Only
+ * the GVC-qualified `//gvc/GVC/identity/NAME` form works. This composite only
+ * emits the qualified form.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Identity, Policy } from "../generated";
+
+export interface SecretAccessProps {
+  /** Identity name. The policy is named `<name>-secret-access` unless overridden. */
+  name: string;
+  /** GVC the identity lives in. Identities cannot be shared across GVCs. */
+  gvc: string;
+  /**
+   * Names of the org-scoped secrets this identity may read. Each becomes a
+   * `//secret/NAME` target link on the policy.
+   */
+  secrets: string[];
+  /** Policy name (default `<name>-secret-access`). */
+  policyName?: string;
+  /**
+   * Permissions granted on the target secrets (default `["reveal"]`).
+   * Control Plane requires the list to be sorted and unique, which this does.
+   */
+  permissions?: string[];
+  /** Tags applied to both resources. */
+  tags?: Record<string, string>;
+  /** Per-member defaults for customizing individual resources. */
+  defaults?: {
+    identity?: Partial<ConstructorParameters<typeof Identity>[0]>;
+    policy?: Partial<ConstructorParameters<typeof Policy>[0]>;
+  };
+}
+
+export const SecretAccess = Composite((props: SecretAccessProps) => {
+  const {
+    name,
+    gvc,
+    secrets,
+    policyName = `${name}-secret-access`,
+    permissions = ["reveal"],
+    tags,
+    defaults: defs,
+  } = props;
+
+  if (secrets.length === 0) {
+    throw new Error(
+      `SecretAccess "${name}": no secrets listed. A policy with no target links grants nothing, ` +
+        `and the workload would fail to read its secrets at runtime with no apply-time error.`,
+    );
+  }
+
+  const identity = new Identity(
+    mergeDefaults(
+      {
+        name,
+        gvc,
+        ...(tags && { tags }),
+      } as Record<string, unknown>,
+      defs?.identity,
+    ),
+  );
+
+  const policy = new Policy(
+    mergeDefaults(
+      {
+        name: policyName,
+        ...(tags && { tags }),
+        targetKind: "secret",
+        targetLinks: [...secrets].sort().map((secret) => `//secret/${secret}`),
+        bindings: [
+          {
+            // Sorted and deduplicated: Control Plane requires permissions in a
+            // binding to be both.
+            permissions: [...new Set(permissions)].sort(),
+            // The GVC-qualified form. The bare `//identity/NAME` is silently
+            // ignored — see the module comment.
+            principalLinks: [identityLink(gvc, name)],
+          },
+        ],
+      } as Record<string, unknown>,
+      defs?.policy,
+    ),
+  );
+
+  return { identity, policy };
+}, "SecretAccess");
+
+/**
+ * The GVC-qualified principal link for an identity.
+ *
+ * Exported because this is the form policies must use, and the unqualified one
+ * fails silently.
+ */
+export function identityLink(gvc: string, name: string): string {
+  return `//gvc/${gvc}/identity/${name}`;
+}
+
+/**
+ * A field-qualified secret reference for use in a container's env or volumes.
+ *
+ * The field name is required. `cpln://secret/db.password` resolves; the
+ * unqualified `cpln://secret/db` does not, except for `gcp` secrets mounted as
+ * a file. The field differs by secret type:
+ *
+ * | Type | Field |
+ * |---|---|
+ * | `opaque` | `payload` |
+ * | `dictionary` | any key |
+ * | `userpass` | `username`, `password` |
+ * | `tls` | `cert`, `key` |
+ * | `keypair` | `publicKey`, `privateKey` |
+ * | `aws` | `accessKey`, `secretKey`, `roleArn` |
+ */
+export function secretRef(name: string, field: string): string {
+  return `cpln://secret/${name}.${field}`;
+}

package/src/composites/serverless-service.ts

@@ -0,0 +1,143 @@
+/**
+ * ServerlessService — a serverless workload with the port, probe and firewall
+ * settings a public HTTP service actually needs.
+ *
+ * Serverless is the Control Plane workload type with the most rules attached to
+ * it, and most of them are easy to get wrong by omission rather than by writing
+ * something incorrect:
+ *
+ * - It must expose *exactly one* HTTP port. Zero or two is rejected.
+ * - The external firewall's inbound is closed by default, so a workload that
+ *   looks completely correct serves nothing until a CIDR is added.
+ * - `concurrency` and `rps` are the only strategies that scale to zero, and
+ *   only on this workload type.
+ *
+ * The defaults here are Control Plane's own, restated so they are visible at
+ * the call site rather than implied.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Workload } from "../generated";
+
+export interface ServerlessServiceProps {
+  /** Workload name. Max 49 characters, and cannot end with `-headless`. */
+  name: string;
+  /** GVC this workload is deployed into. */
+  gvc: string;
+  /** Container image. Use `//image/NAME:TAG` for the org's own registry. */
+  image: string;
+  /**
+   * The port the container listens on. Serverless exposes exactly one HTTP
+   * port, and it must match what the process actually binds or health checks
+   * fail.
+   */
+  port?: number;
+  /** Protocol for the exposed port (default `http`). */
+  protocol?: "http" | "http2";
+  /** Container name (default `main`). */
+  containerName?: string;
+  /** CPU in millicores (default `50m`). Minimum 25m. */
+  cpu?: string;
+  /** Memory (default `128Mi`). Minimum 32Mi, and memory(MiB)/cpu(m) must be ≤ 8. */
+  memory?: string;
+  /** Environment variables, as a plain map. */
+  env?: Record<string, string>;
+  /**
+   * CIDRs allowed to reach the workload from the internet. Defaults to closed;
+   * pass `["0.0.0.0/0"]` for a public service.
+   */
+  inboundAllowCidr?: string[];
+  /** Hostnames or CIDRs the workload may call out to. Defaults to closed. */
+  outboundAllowCidr?: string[];
+  /** Minimum replicas (default 1). `0` scales to zero. */
+  minScale?: number;
+  /** Maximum replicas (default 5). */
+  maxScale?: number;
+  /**
+   * Autoscaling strategy (default `concurrency`). Only `concurrency` and `rps`
+   * scale a serverless workload to zero; `cpu`/`memory` cannot, and `latency`
+   * and multi-metric are not available on serverless at all.
+   */
+  autoscalingMetric?: "concurrency" | "rps" | "cpu" | "memory" | "disabled";
+  /** Scaling target (default 95). Capped at 100 for cpu/memory. */
+  autoscalingTarget?: number;
+  /**
+   * Identity to run as, as a link (`//gvc/GVC/identity/NAME`). Leave unset
+   * unless the workload needs secret access, credential-free cloud access or
+   * private networking — an unnecessary identity assignment complicates audit
+   * traces.
+   */
+  identityLink?: string;
+  /** Tags applied to the workload. */
+  tags?: Record<string, string>;
+  /** Per-member defaults for customizing the underlying resource. */
+  defaults?: {
+    workload?: Partial<ConstructorParameters<typeof Workload>[0]>;
+  };
+}
+
+export const ServerlessService = Composite((props: ServerlessServiceProps) => {
+  const {
+    name,
+    gvc,
+    image,
+    port = 8080,
+    protocol = "http",
+    containerName = "main",
+    cpu = "50m",
+    memory = "128Mi",
+    env,
+    inboundAllowCidr = [],
+    outboundAllowCidr = [],
+    minScale = 1,
+    maxScale = 5,
+    autoscalingMetric = "concurrency",
+    autoscalingTarget = 95,
+    identityLink,
+    tags,
+    defaults: defs,
+  } = props;
+
+  const workload = new Workload(
+    mergeDefaults(
+      {
+        name,
+        gvc,
+        ...(tags && { tags }),
+        spec: {
+          type: "serverless",
+          ...(identityLink && { identityLink }),
+          containers: [
+            {
+              name: containerName,
+              image,
+              cpu,
+              memory,
+              ports: [{ number: port, protocol }],
+              ...(env && {
+                env: Object.entries(env).map(([envName, value]) => ({ name: envName, value })),
+              }),
+            },
+          ],
+          firewallConfig: {
+            external: {
+              inboundAllowCIDR: inboundAllowCidr,
+              outboundAllowCIDR: outboundAllowCidr,
+            },
+          },
+          defaultOptions: {
+            autoscaling: {
+              metric: autoscalingMetric,
+              target: autoscalingTarget,
+              minScale,
+              maxScale,
+            },
+          },
+        },
+      } as Record<string, unknown>,
+      defs?.workload,
+    ),
+  );
+
+  return { workload };
+}, "ServerlessService");

package/src/composites/stateful-service.ts

@@ -0,0 +1,179 @@
+/**
+ * StatefulService — a stateful workload with its volume set, mounted.
+ *
+ * Persistent storage on Control Plane is two resources that have to agree, and
+ * the ways they can disagree are all expensive:
+ *
+ * - `ext4` and `xfs` volume sets bind to exactly one *stateful* workload.
+ *   Mounting one from a serverless or standard workload is not a degraded
+ *   mode, it is rejected.
+ * - `fileSystemType` and `performanceClass` are both immutable. Changing
+ *   either later means delete and recreate, which means data loss.
+ * - `high-throughput-ssd` has a 200 GB floor, not the 10 GB floor the other
+ *   classes have, so an initial capacity that is fine for one class is invalid
+ *   for another.
+ * - A volume set is GVC-scoped and only mountable from its own GVC.
+ *
+ * This composite pairs them so the mount URI, the GVC and the workload type
+ * cannot drift apart, and validates the capacity floor at build time rather
+ * than at apply time.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Workload, VolumeSet } from "../generated";
+
+/** Minimum initial capacity in GB, by performance class. */
+const MIN_CAPACITY_GB: Record<string, number> = {
+  "general-purpose-ssd": 10,
+  "high-throughput-ssd": 200,
+  shared: 10,
+};
+
+export interface StatefulServiceProps {
+  /** Workload name. The volume set is named `<name>-data` unless overridden. */
+  name: string;
+  /** GVC for both the workload and the volume set. */
+  gvc: string;
+  /** Container image. */
+  image: string;
+  /** Mount path inside the container. */
+  mountPath: string;
+  /** Initial volume capacity in GB. Must clear the performance class floor. */
+  capacityGb: number;
+  /** Volume set name (default `<name>-data`). */
+  volumeSetName?: string;
+  /** Filesystem (default `ext4`). Immutable after creation. */
+  fileSystemType?: "ext4" | "xfs" | "shared";
+  /** Performance class (default `general-purpose-ssd`). Immutable after creation. */
+  performanceClass?: "general-purpose-ssd" | "high-throughput-ssd" | "shared";
+  /**
+   * What happens to the volume when the workload releases it (default
+   * `retain`). `recycle` discards the data.
+   */
+  recoveryPolicy?: "retain" | "recycle";
+  /** Ports the container exposes. */
+  ports?: Array<{ number: number; protocol?: "http" | "http2" | "grpc" | "tcp" }>;
+  /** Container name (default `main`). */
+  containerName?: string;
+  /** CPU in millicores (default `50m`). */
+  cpu?: string;
+  /** Memory (default `128Mi`). */
+  memory?: string;
+  /** Environment variables, as a plain map. */
+  env?: Record<string, string>;
+  /** CIDRs allowed to reach the workload from the internet. Defaults to closed. */
+  inboundAllowCidr?: string[];
+  /** Hostnames or CIDRs the workload may call out to. Defaults to closed. */
+  outboundAllowCidr?: string[];
+  /** Minimum replicas (default 1). Stateful cannot scale to zero without KEDA. */
+  minScale?: number;
+  /** Maximum replicas (default 1). */
+  maxScale?: number;
+  /** Identity to run as, as a link (`//gvc/GVC/identity/NAME`). */
+  identityLink?: string;
+  /** Tags applied to both resources. */
+  tags?: Record<string, string>;
+  /** Per-member defaults for customizing individual resources. */
+  defaults?: {
+    workload?: Partial<ConstructorParameters<typeof Workload>[0]>;
+    volumeSet?: Partial<ConstructorParameters<typeof VolumeSet>[0]>;
+  };
+}
+
+export const StatefulService = Composite((props: StatefulServiceProps) => {
+  const {
+    name,
+    gvc,
+    image,
+    mountPath,
+    capacityGb,
+    volumeSetName = `${name}-data`,
+    fileSystemType = "ext4",
+    performanceClass = "general-purpose-ssd",
+    recoveryPolicy = "retain",
+    ports = [],
+    containerName = "main",
+    cpu = "50m",
+    memory = "128Mi",
+    env,
+    inboundAllowCidr = [],
+    outboundAllowCidr = [],
+    minScale = 1,
+    maxScale = 1,
+    identityLink,
+    tags,
+    defaults: defs,
+  } = props;
+
+  const floor = MIN_CAPACITY_GB[performanceClass];
+  if (floor !== undefined && capacityGb < floor) {
+    throw new Error(
+      `StatefulService "${name}": capacityGb ${capacityGb} is below the ${floor} GB minimum for ` +
+        `performanceClass "${performanceClass}". Both fileSystemType and performanceClass are immutable ` +
+        `after creation, so this is worth getting right before the first apply.`,
+    );
+  }
+
+  const volumeSet = new VolumeSet(
+    mergeDefaults(
+      {
+        name: volumeSetName,
+        gvc,
+        ...(tags && { tags }),
+        spec: {
+          initialCapacity: capacityGb,
+          fileSystemType,
+          // Control Plane forces `shared` for a shared filesystem; setting it
+          // explicitly keeps the emitted manifest equal to what comes back.
+          performanceClass: fileSystemType === "shared" ? "shared" : performanceClass,
+          snapshots: { createFinalSnapshot: true },
+        },
+      } as Record<string, unknown>,
+      defs?.volumeSet,
+    ),
+  );
+
+  const workload = new Workload(
+    mergeDefaults(
+      {
+        name,
+        gvc,
+        ...(tags && { tags }),
+        spec: {
+          type: "stateful",
+          ...(identityLink && { identityLink }),
+          containers: [
+            {
+              name: containerName,
+              image,
+              cpu,
+              memory,
+              ...(ports.length > 0 && {
+                ports: ports.map((p) => ({ number: p.number, protocol: p.protocol ?? "http" })),
+              }),
+              ...(env && {
+                env: Object.entries(env).map(([envName, value]) => ({ name: envName, value })),
+              }),
+              volumes: [
+                {
+                  uri: `cpln://volumeset/${volumeSetName}`,
+                  path: mountPath,
+                  recoveryPolicy,
+                },
+              ],
+            },
+          ],
+          firewallConfig: {
+            external: { inboundAllowCIDR: inboundAllowCidr, outboundAllowCIDR: outboundAllowCidr },
+          },
+          defaultOptions: {
+            autoscaling: { minScale, maxScale },
+          },
+        },
+      } as Record<string, unknown>,
+      defs?.workload,
+    ),
+  );
+
+  return { workload, volumeSet };
+}, "StatefulService");