@intentius/chant-lexicon-cpln 0.53.0

package/src/codegen/naming.ts

@@ -0,0 +1,61 @@
+/**
+ * cpln naming strategy.
+ *
+ * Every generated type is `Cpln::Core::{Name}` with a `{Name}` the parser has
+ * already made unique — `$ref`'d schemas take their upstream name and inline
+ * shapes take their path — so the core strategy's collision phases never fire
+ * and `resolve` returns the last segment unchanged. The value of going through
+ * the core strategy anyway is phase 1a: once this lexicon publishes a surface
+ * snapshot, a name that has shipped stays attached to the type that shipped it
+ * even if an upstream reshuffle would otherwise hand it to a newcomer.
+ */
+
+import {
+  NamingStrategy as CoreNamingStrategy,
+  reservedNamesFromSnapshot,
+  type NamingConfig,
+  type NamingInput,
+} from "@intentius/chant/codegen/naming";
+import { cplnShortName, cplnServiceName, KINDS, SERVICE } from "../kinds";
+import type { CplnParseResult } from "../spec/parse";
+
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+
+/**
+ * The eight kinds are pinned by hand. They are the names users type, and they
+ * should not move because a property type elsewhere in the spec started or
+ * stopped existing.
+ */
+const priorityNames: Record<string, string> = Object.fromEntries(
+  KINDS.map((k) => [k.typeName, k.className]),
+);
+
+const cplnNamingConfig: NamingConfig = {
+  priorityNames,
+  priorityAliases: {},
+  priorityPropertyAliases: {},
+  serviceAbbreviations: { [SERVICE]: SERVICE },
+  shortName: cplnShortName,
+  serviceName: cplnServiceName,
+};
+
+export interface CplnNamingOptions {
+  /** A committed `surface.snapshot.json`, when one exists. */
+  snapshot?: { entries?: Record<string, { kind?: string; resourceType?: string }> };
+}
+
+/**
+ * cpln-specific naming strategy.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+  constructor(results: CplnParseResult[], options: CplnNamingOptions = {}) {
+    const inputs: NamingInput[] = results.map((r) => ({
+      typeName: r.resource.typeName,
+      propertyTypes: r.propertyTypes,
+    }));
+    super(inputs, {
+      ...cplnNamingConfig,
+      reservedNames: reservedNamesFromSnapshot(options.snapshot),
+    });
+  }
+}

package/src/codegen/package.ts

@@ -0,0 +1,35 @@
+/**
+ * Package the cpln lexicon into the distributable bundle under `dist/`.
+ */
+
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { cplnPlugin } from "../plugin";
+
+export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
+  // This file is `src/codegen/package.ts`; rules and skills are collected
+  // relative to `src/`, so srcDir is the parent of this directory. Pointing it
+  // at `src/codegen` globs a directory that does not exist and silently ships
+  // a bundle with zero rules and zero skills.
+  const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+
+  const { spec, stats } = await packagePipeline({
+    generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+    buildManifest: () => ({
+      name: "cpln",
+      version: pkgJson.version ?? "0.0.0",
+      chantVersion: ">=0.1.0",
+      namespace: "Cpln",
+    }),
+    srcDir,
+    collectSkills: () => collectSkills(cplnPlugin.skills?.() ?? []),
+  });
+
+  // Both callers (the plugin's `package()` and `package-cli`) print their own
+  // summary — don't double-report here.
+  return { spec, stats };
+}

package/src/composites/composites.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "vitest";
+import { isCompositeInstance } from "@intentius/chant";
+import { GvcEnvironment, ServerlessService, CronJob, StatefulService, SecretAccess, PublicDomain } from "./index";
+import { identityLink, secretRef } from "./secret-access";
+import { isApexDomain } from "./public-domain";
+import { propsOf, readString, readArray, readNumber, readPath } from "../entity-props";
+
+describe("GvcEnvironment", () => {
+  it("builds location links from the org and location ids", () => {
+    const { gvc } = GvcEnvironment({ name: "prod", org: "acme", locations: ["aws-us-east-1"] });
+
+    expect(isCompositeInstance({ gvc })).toBe(false);
+    expect(readString(gvc, "name")).toBe("prod");
+    expect(readArray(gvc, "spec", "staticPlacement", "locationLinks")).toEqual([
+      "/org/acme/location/aws-us-east-1",
+    ]);
+  });
+
+  it("sorts locations and pull secrets so output is stable", () => {
+    const { gvc } = GvcEnvironment({
+      name: "prod",
+      org: "acme",
+      locations: ["gcp-us-central1", "aws-us-east-1"],
+      pullSecrets: ["z-creds", "a-creds"],
+    });
+
+    expect(readArray(gvc, "spec", "staticPlacement", "locationLinks")).toEqual([
+      "/org/acme/location/aws-us-east-1",
+      "/org/acme/location/gcp-us-central1",
+    ]);
+    expect(readArray(gvc, "spec", "pullSecretLinks")).toEqual(["//secret/a-creds", "//secret/z-creds"]);
+  });
+
+  it("refuses a GVC with no locations", () => {
+    expect(() => GvcEnvironment({ name: "prod", org: "acme", locations: [] })).toThrow(/runs them nowhere/);
+  });
+
+  it("refuses a location id that is not one", () => {
+    expect(() => GvcEnvironment({ name: "prod", org: "acme", locations: ["us-east-1"] })).toThrow(
+      /not a location id/,
+    );
+  });
+});
+
+describe("ServerlessService", () => {
+  it("emits exactly one HTTP port", () => {
+    const { workload } = ServerlessService({ name: "web", gvc: "prod", image: "nginx:1.27" });
+    const containers = readArray(workload, "spec", "containers");
+
+    expect(readString(workload, "spec", "type")).toBe("serverless");
+    expect(containers).toHaveLength(1);
+    const ports = readArray(containers[0], "ports");
+    expect(ports).toHaveLength(1);
+    expect(readNumber(ports[0], "number")).toBe(8080);
+  });
+
+  it("leaves the firewall closed by default in both directions", () => {
+    const { workload } = ServerlessService({ name: "web", gvc: "prod", image: "nginx:1.27" });
+    expect(readArray(workload, "spec", "firewallConfig", "external", "inboundAllowCIDR")).toEqual([]);
+    expect(readArray(workload, "spec", "firewallConfig", "external", "outboundAllowCIDR")).toEqual([]);
+  });
+
+  it("maps env to Control Plane's name/value pairs", () => {
+    const { workload } = ServerlessService({
+      name: "web",
+      gvc: "prod",
+      image: "nginx:1.27",
+      env: { LOG_LEVEL: "info" },
+    });
+    const env = readArray(readArray(workload, "spec", "containers")[0], "env");
+    expect(env).toEqual([{ name: "LOG_LEVEL", value: "info" }]);
+  });
+
+  it("honours per-member defaults", () => {
+    const { workload } = ServerlessService({
+      name: "web",
+      gvc: "prod",
+      image: "nginx:1.27",
+      defaults: { workload: { description: "the web tier" } },
+    });
+    expect(readString(workload, "description")).toBe("the web tier");
+  });
+});
+
+describe("CronJob", () => {
+  it("sets the schedule and exposes no ports", () => {
+    const { workload } = CronJob({ name: "nightly", gvc: "prod", image: "busybox:1.36", schedule: "0 3 * * *" });
+
+    expect(readString(workload, "spec", "type")).toBe("cron");
+    expect(readString(workload, "spec", "job", "schedule")).toBe("0 3 * * *");
+    expect(readArray(readArray(workload, "spec", "containers")[0], "ports")).toEqual([]);
+    expect(readArray(workload, "spec", "firewallConfig", "external", "inboundAllowCIDR")).toEqual([]);
+  });
+
+  it("defaults to Forbid so runs do not overlap", () => {
+    const { workload } = CronJob({ name: "nightly", gvc: "prod", image: "busybox:1.36", schedule: "0 3 * * *" });
+    expect(readString(workload, "spec", "job", "concurrencyPolicy")).toBe("Forbid");
+  });
+});
+
+describe("StatefulService", () => {
+  it("pairs the workload and volume set on the same mount", () => {
+    const { workload, volumeSet } = StatefulService({
+      name: "db",
+      gvc: "prod",
+      image: "postgres:17",
+      mountPath: "/var/lib/postgresql/data",
+      capacityGb: 20,
+    });
+
+    expect(readString(volumeSet, "name")).toBe("db-data");
+    expect(readString(volumeSet, "gvc")).toBe("prod");
+    expect(readString(workload, "spec", "type")).toBe("stateful");
+
+    const volumes = readArray(readArray(workload, "spec", "containers")[0], "volumes");
+    expect(readString(volumes[0], "uri")).toBe("cpln://volumeset/db-data");
+    expect(readString(volumes[0], "path")).toBe("/var/lib/postgresql/data");
+  });
+
+  it("refuses a capacity below the performance class floor", () => {
+    expect(() =>
+      StatefulService({
+        name: "db",
+        gvc: "prod",
+        image: "postgres:17",
+        mountPath: "/data",
+        capacityGb: 50,
+        performanceClass: "high-throughput-ssd",
+      }),
+    ).toThrow(/200 GB minimum/);
+  });
+
+  it("forces performanceClass shared for a shared filesystem", () => {
+    // Control Plane forces it server-side; declaring it too keeps the manifest
+    // equal to what comes back, so it does not read as drift on every plan.
+    const { volumeSet } = StatefulService({
+      name: "files",
+      gvc: "prod",
+      image: "nginx:1.27",
+      mountPath: "/files",
+      capacityGb: 10,
+      fileSystemType: "shared",
+    });
+    expect(readString(volumeSet, "spec", "performanceClass")).toBe("shared");
+  });
+
+  it("keeps createFinalSnapshot on and defaults to ext4", () => {
+    // `createFinalSnapshot` auto-snapshots before any volume deletion. It
+    // defaults on upstream; declaring it means a later edit that turns it off
+    // is a visible diff rather than an inherited default nobody chose.
+    const { volumeSet } = StatefulService({
+      name: "db",
+      gvc: "prod",
+      image: "postgres:17",
+      mountPath: "/data",
+      capacityGb: 20,
+    });
+    expect(readString(volumeSet, "spec", "fileSystemType")).toBe("ext4");
+    expect(propsOf(readPath(volumeSet, "spec", "snapshots")).createFinalSnapshot).toBe(true);
+  });
+});
+
+describe("SecretAccess", () => {
+  it("emits a GVC-qualified principal link", () => {
+    const { identity, policy } = SecretAccess({ name: "api", gvc: "prod", secrets: ["db-password"] });
+
+    expect(readString(identity, "name")).toBe("api");
+    expect(readString(policy, "targetKind")).toBe("secret");
+    expect(readArray(policy, "targetLinks")).toEqual(["//secret/db-password"]);
+
+    const bindings = readArray(policy, "bindings");
+    expect(readArray(bindings[0], "principalLinks")).toEqual(["//gvc/prod/identity/api"]);
+    // The bare form is accepted by Control Plane and silently ignored.
+    expect(JSON.stringify(bindings)).not.toContain('"//identity/api"');
+  });
+
+  it("sorts and deduplicates permissions", () => {
+    const { policy } = SecretAccess({
+      name: "api",
+      gvc: "prod",
+      secrets: ["db"],
+      permissions: ["reveal", "edit", "reveal"],
+    });
+    expect(readArray(readArray(policy, "bindings")[0], "permissions")).toEqual(["edit", "reveal"]);
+  });
+
+  it("refuses an empty secret list", () => {
+    expect(() => SecretAccess({ name: "api", gvc: "prod", secrets: [] })).toThrow(/grants nothing/);
+  });
+});
+
+describe("PublicDomain", () => {
+  it("routes to the GVC when no routes are given", () => {
+    const { domain } = PublicDomain({ name: "api.example.com", gvc: "prod" });
+    expect(readString(domain, "spec", "gvcLink")).toBe("//gvc/prod");
+    expect(readArray(domain, "spec", "ports")).toEqual([]);
+  });
+
+  it("emits per-port routes and no gvcLink when routes are given", () => {
+    const { domain } = PublicDomain({
+      name: "api.example.com",
+      gvc: "prod",
+      routes: [{ prefix: "/v1", workload: "api", port: 8080 }],
+    });
+
+    expect(readString(domain, "spec", "gvcLink")).toBeUndefined();
+    const routes = readArray(readArray(domain, "spec", "ports")[0], "routes");
+    expect(readString(routes[0], "workloadLink")).toBe("//gvc/prod/workload/api");
+  });
+
+  it("defaults the challenge type to the one the DNS mode allows", () => {
+    expect(readString(PublicDomain({ name: "api.example.com", gvc: "prod" }).domain, "spec", "certChallengeType")).toBe(
+      "http01",
+    );
+    expect(
+      readString(
+        PublicDomain({ name: "api.example.com", gvc: "prod", dnsMode: "ns" }).domain,
+        "spec",
+        "certChallengeType",
+      ),
+    ).toBe("dns01");
+  });
+
+  it("refuses an apex domain in ns mode", () => {
+    expect(() => PublicDomain({ name: "example.com", gvc: "prod", dnsMode: "ns" })).toThrow(/apex/);
+  });
+
+  it("refuses a route with both prefix and regex", () => {
+    expect(() =>
+      PublicDomain({
+        name: "api.example.com",
+        gvc: "prod",
+        routes: [{ prefix: "/v1", regex: "^/v1", workload: "api" }],
+      }),
+    ).toThrow(/only one may be provided/);
+  });
+});
+
+describe("helpers", () => {
+  it("qualifies an identity link", () => {
+    expect(identityLink("prod", "api")).toBe("//gvc/prod/identity/api");
+  });
+
+  it("qualifies a secret reference with its field", () => {
+    expect(secretRef("db", "payload")).toBe("cpln://secret/db.payload");
+  });
+
+  it("recognises apex domains", () => {
+    expect(isApexDomain("example.com")).toBe(true);
+    expect(isApexDomain("api.example.com")).toBe(false);
+  });
+});

package/src/composites/cron-job.ts

@@ -0,0 +1,124 @@
+/**
+ * CronJob — a scheduled workload, with the constraints cron carries.
+ *
+ * Cron is the workload type with the most *silent* rules: it must not expose
+ * any port, its container has to exit on completion, and probes, autoscaling,
+ * `timeoutSeconds` and `debug` are all accepted and then ignored. Rather than
+ * let a caller set those and wonder why nothing happens, this composite has no
+ * knobs for them.
+ *
+ * A cron workload also deploys to every location in its GVC with no
+ * per-location override, so placement is a property of the GVC, not of this.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Workload } from "../generated";
+
+export interface CronJobProps {
+  /** Workload name. Max 49 characters. */
+  name: string;
+  /** GVC this job is deployed into. */
+  gvc: string;
+  /** Container image. */
+  image: string;
+  /** Cron schedule, standard five-field syntax (e.g. `"0 * * * *"`). */
+  schedule: string;
+  /** Container name (default `main`). */
+  containerName?: string;
+  /** Entrypoint override. */
+  command?: string;
+  /** Arguments passed to the entrypoint. */
+  args?: string[];
+  /** CPU in millicores (default `50m`). */
+  cpu?: string;
+  /** Memory (default `128Mi`). */
+  memory?: string;
+  /** Environment variables, as a plain map. */
+  env?: Record<string, string>;
+  /**
+   * What to do when a run is still going at the next scheduled time
+   * (default `Forbid` — skip the new run rather than overlap).
+   */
+  concurrencyPolicy?: "Allow" | "Forbid" | "Replace";
+  /** Restart behaviour for a failed run (default `Never`). */
+  restartPolicy?: "Never" | "OnFailure";
+  /** Seconds a run may take before it is killed. */
+  activeDeadlineSeconds?: number;
+  /** How many finished runs to retain. */
+  historyLimit?: number;
+  /** Hostnames or CIDRs the job may call out to. Defaults to closed. */
+  outboundAllowCidr?: string[];
+  /** Identity to run as, as a link (`//gvc/GVC/identity/NAME`). */
+  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 CronJob = Composite((props: CronJobProps) => {
+  const {
+    name,
+    gvc,
+    image,
+    schedule,
+    containerName = "main",
+    command,
+    args,
+    cpu = "50m",
+    memory = "128Mi",
+    env,
+    concurrencyPolicy = "Forbid",
+    restartPolicy = "Never",
+    activeDeadlineSeconds,
+    historyLimit,
+    outboundAllowCidr = [],
+    identityLink,
+    tags,
+    defaults: defs,
+  } = props;
+
+  const workload = new Workload(
+    mergeDefaults(
+      {
+        name,
+        gvc,
+        ...(tags && { tags }),
+        spec: {
+          type: "cron",
+          ...(identityLink && { identityLink }),
+          job: {
+            schedule,
+            concurrencyPolicy,
+            restartPolicy,
+            ...(activeDeadlineSeconds !== undefined && { activeDeadlineSeconds }),
+            ...(historyLimit !== undefined && { historyLimit }),
+          },
+          containers: [
+            {
+              name: containerName,
+              image,
+              cpu,
+              memory,
+              ...(command && { command }),
+              ...(args && { args }),
+              ...(env && {
+                env: Object.entries(env).map(([envName, value]) => ({ name: envName, value })),
+              }),
+            },
+          ],
+          firewallConfig: {
+            // A cron job serves nothing, so inbound stays closed. Outbound is
+            // the only direction worth opening.
+            external: { inboundAllowCIDR: [], outboundAllowCIDR: outboundAllowCidr },
+          },
+        },
+      } as Record<string, unknown>,
+      defs?.workload,
+    ),
+  );
+
+  return { workload };
+}, "CronJob");

package/src/composites/gvc-environment.ts

@@ -0,0 +1,104 @@
+/**
+ * GvcEnvironment — a GVC placed in named locations, with its pull secrets.
+ *
+ * Two things belong here rather than at the workload:
+ *
+ * - **Pull secrets are GVC-level** (`spec.pullSecretLinks`), not per-workload.
+ *   Looking for them on a workload is a common wrong turn, and only the
+ *   `docker`, `ecr` and `gcp` secret types are valid as pull secrets.
+ * - **Placement is GVC-level.** Location links use the full org-qualified path
+ *   (`/org/ORG/location/aws-us-east-1`), which is why this takes an `org`.
+ *
+ * The location id format is `<provider>-<region>`: `aws-us-east-1`,
+ * `gcp-us-central1`, `azure-eastus`.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Gvc } from "../generated";
+
+/** Location ids look like `aws-us-east-1`, `gcp-us-central1`, `azure-eastus`. */
+const LOCATION_ID = /^(aws|gcp|azure)-[a-z0-9-]+$/;
+
+export interface GvcEnvironmentProps {
+  /** GVC name. */
+  name: string;
+  /** Org the GVC belongs to. Needed to build location links. */
+  org: string;
+  /** Location ids to place workloads in, e.g. `["aws-us-east-1"]`. */
+  locations: string[];
+  /**
+   * Names of secrets used to pull private images. Only `docker`, `ecr` and
+   * `gcp` secret types are valid here.
+   */
+  pullSecrets?: string[];
+  /**
+   * Public endpoint naming scheme (default `org`, the default for new GVCs):
+   * `{workload}-{gvcAlias}.{orgPrefix}.cpln.app`.
+   */
+  endpointNamingFormat?: "default" | "legacy" | "org";
+  /** Environment variables inherited by every workload in the GVC. */
+  env?: Record<string, string>;
+  /** Enable KEDA autoscaling for standard and stateful workloads in this GVC. */
+  keda?: boolean;
+  /** Tags applied to the GVC. */
+  tags?: Record<string, string>;
+  /** Per-member defaults for customizing the underlying resource. */
+  defaults?: {
+    gvc?: Partial<ConstructorParameters<typeof Gvc>[0]>;
+  };
+}
+
+export const GvcEnvironment = Composite((props: GvcEnvironmentProps) => {
+  const {
+    name,
+    org,
+    locations,
+    pullSecrets,
+    endpointNamingFormat = "org",
+    env,
+    keda,
+    tags,
+    defaults: defs,
+  } = props;
+
+  if (locations.length === 0) {
+    throw new Error(
+      `GvcEnvironment "${name}": no locations. A GVC with no placement accepts workloads and runs them nowhere.`,
+    );
+  }
+
+  for (const location of locations) {
+    if (!LOCATION_ID.test(location)) {
+      throw new Error(
+        `GvcEnvironment "${name}": "${location}" is not a location id. Expected <provider>-<region>, ` +
+          `e.g. "aws-us-east-1", "gcp-us-central1", "azure-eastus".`,
+      );
+    }
+  }
+
+  const gvc = new Gvc(
+    mergeDefaults(
+      {
+        name,
+        ...(tags && { tags }),
+        spec: {
+          endpointNamingFormat,
+          staticPlacement: {
+            locationLinks: [...locations].sort().map((location) => `/org/${org}/location/${location}`),
+          },
+          ...(pullSecrets &&
+            pullSecrets.length > 0 && {
+              pullSecretLinks: [...pullSecrets].sort().map((secret) => `//secret/${secret}`),
+            }),
+          ...(env && {
+            env: Object.entries(env).map(([envName, value]) => ({ name: envName, value })),
+          }),
+          ...(keda !== undefined && { keda: { enabled: keda } }),
+        },
+      } as Record<string, unknown>,
+      defs?.gvc,
+    ),
+  );
+
+  return { gvc };
+}, "GvcEnvironment");

package/src/composites/index.ts

@@ -0,0 +1,17 @@
+export { GvcEnvironment } from "./gvc-environment";
+export type { GvcEnvironmentProps } from "./gvc-environment";
+
+export { ServerlessService } from "./serverless-service";
+export type { ServerlessServiceProps } from "./serverless-service";
+
+export { CronJob } from "./cron-job";
+export type { CronJobProps } from "./cron-job";
+
+export { StatefulService } from "./stateful-service";
+export type { StatefulServiceProps } from "./stateful-service";
+
+export { SecretAccess, identityLink, secretRef } from "./secret-access";
+export type { SecretAccessProps } from "./secret-access";
+
+export { PublicDomain, isApexDomain } from "./public-domain";
+export type { PublicDomainProps, DomainRoute } from "./public-domain";