@intentius/chant-lexicon-cpln 0.124.30 → 0.124.32

package/dist/composites/catalog.js

@@ -0,0 +1,556 @@
+export const compositeCatalog = [
+    {
+        "name": "CronJob",
+        "lexicon": "cpln",
+        "description": "CronJob — a scheduled workload, with the constraints cron carries.",
+        "bundles": [
+            "Workload"
+        ],
+        "params": [
+            {
+                "name": "name",
+                "type": "string",
+                "required": true,
+                "description": "Workload name."
+            },
+            {
+                "name": "gvc",
+                "type": "string",
+                "required": true,
+                "description": "GVC this job is deployed into."
+            },
+            {
+                "name": "image",
+                "type": "string",
+                "required": true,
+                "description": "Container image."
+            },
+            {
+                "name": "schedule",
+                "type": "string",
+                "required": true,
+                "description": "Cron schedule, standard five-field syntax (e.g. `\"0 * * * *\"`)."
+            },
+            {
+                "name": "containerName",
+                "type": "string",
+                "required": false,
+                "description": "Container name (default `main`)."
+            },
+            {
+                "name": "command",
+                "type": "string",
+                "required": false,
+                "description": "Entrypoint override."
+            },
+            {
+                "name": "args",
+                "type": "string[]",
+                "required": false,
+                "description": "Arguments passed to the entrypoint."
+            },
+            {
+                "name": "cpu",
+                "type": "string",
+                "required": false,
+                "description": "CPU in millicores (default `50m`)."
+            },
+            {
+                "name": "memory",
+                "type": "string",
+                "required": false,
+                "description": "Memory (default `128Mi`)."
+            },
+            {
+                "name": "env",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Environment variables, as a plain map."
+            },
+            {
+                "name": "concurrencyPolicy",
+                "type": "\"Allow\" | \"Forbid\" | \"Replace\"",
+                "required": false,
+                "description": "What to do when a run is still going at the next scheduled time (default `Forbid` — skip the new run rather than overlap)."
+            },
+            {
+                "name": "restartPolicy",
+                "type": "\"Never\" | \"OnFailure\"",
+                "required": false,
+                "description": "Restart behaviour for a failed run (default `Never`)."
+            },
+            {
+                "name": "activeDeadlineSeconds",
+                "type": "number",
+                "required": false,
+                "description": "Seconds a run may take before it is killed."
+            },
+            {
+                "name": "historyLimit",
+                "type": "number",
+                "required": false,
+                "description": "How many finished runs to retain."
+            },
+            {
+                "name": "outboundAllowCidr",
+                "type": "string[]",
+                "required": false,
+                "description": "Hostnames or CIDRs the job may call out to."
+            },
+            {
+                "name": "identityLink",
+                "type": "string",
+                "required": false,
+                "description": "Identity to run as, as a link (`//gvc/GVC/identity/NAME`)."
+            },
+            {
+                "name": "tags",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Tags applied to the workload."
+            },
+            {
+                "name": "defaults",
+                "type": "{ workload?: Partial<ConstructorParameters<typeof Workload>[0]>; }",
+                "required": false,
+                "description": "Per-member defaults for customizing the underlying resource."
+            }
+        ]
+    },
+    {
+        "name": "GvcEnvironment",
+        "lexicon": "cpln",
+        "description": "GvcEnvironment — a GVC placed in named locations, with its pull secrets.",
+        "bundles": [
+            "Gvc"
+        ],
+        "params": [
+            {
+                "name": "name",
+                "type": "string",
+                "required": true,
+                "description": "GVC name."
+            },
+            {
+                "name": "org",
+                "type": "string",
+                "required": true,
+                "description": "Org the GVC belongs to."
+            },
+            {
+                "name": "locations",
+                "type": "string[]",
+                "required": true,
+                "description": "Location ids to place workloads in, e.g. `[\"aws-us-east-1\"]`."
+            },
+            {
+                "name": "pullSecrets",
+                "type": "string[]",
+                "required": false,
+                "description": "Names of secrets used to pull private images."
+            },
+            {
+                "name": "endpointNamingFormat",
+                "type": "\"default\" | \"legacy\" | \"org\"",
+                "required": false,
+                "description": "Public endpoint naming scheme (default `org`, the default for new GVCs): `{workload}-{gvcAlias}.{orgPrefix}.cpln.app`."
+            },
+            {
+                "name": "env",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Environment variables inherited by every workload in the GVC."
+            },
+            {
+                "name": "keda",
+                "type": "boolean",
+                "required": false,
+                "description": "Enable KEDA autoscaling for standard and stateful workloads in this GVC."
+            },
+            {
+                "name": "tags",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Tags applied to the GVC."
+            },
+            {
+                "name": "defaults",
+                "type": "{ gvc?: Partial<ConstructorParameters<typeof Gvc>[0]>; }",
+                "required": false,
+                "description": "Per-member defaults for customizing the underlying resource."
+            }
+        ]
+    },
+    {
+        "name": "PublicDomain",
+        "lexicon": "cpln",
+        "description": "PublicDomain — a custom domain routed to workloads in one GVC.",
+        "bundles": [
+            "Domain"
+        ],
+        "params": [
+            {
+                "name": "name",
+                "type": "string",
+                "required": true,
+                "description": "The domain name, e.g. `api.example.com` or the apex `example.com`."
+            },
+            {
+                "name": "gvc",
+                "type": "string",
+                "required": true,
+                "description": "The GVC every route targets."
+            },
+            {
+                "name": "routes",
+                "type": "DomainRoute[]",
+                "required": false,
+                "description": "Routes for the domain."
+            },
+            {
+                "name": "dnsMode",
+                "type": "\"cname\" | \"ns\"",
+                "required": false,
+                "description": "DNS mode."
+            },
+            {
+                "name": "certChallengeType",
+                "type": "\"dns01\" | \"http01\"",
+                "required": false,
+                "description": "Certificate challenge type."
+            },
+            {
+                "name": "port",
+                "type": "number",
+                "required": false,
+                "description": "Public port (default 443)."
+            },
+            {
+                "name": "protocol",
+                "type": "\"http\" | \"http2\" | \"tcp\"",
+                "required": false,
+                "description": "Protocol (default `http2`)."
+            },
+            {
+                "name": "tags",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Tags applied to the domain."
+            },
+            {
+                "name": "defaults",
+                "type": "{ domain?: Partial<ConstructorParameters<typeof Domain>[0]>; }",
+                "required": false,
+                "description": "Per-member defaults for customizing the underlying resource."
+            }
+        ]
+    },
+    {
+        "name": "SecretAccess",
+        "lexicon": "cpln",
+        "description": "SecretAccess — the identity and policy a workload needs to read a secret.",
+        "bundles": [
+            "Identity",
+            "Policy"
+        ],
+        "params": [
+            {
+                "name": "name",
+                "type": "string",
+                "required": true,
+                "description": "Identity name."
+            },
+            {
+                "name": "gvc",
+                "type": "string",
+                "required": true,
+                "description": "GVC the identity lives in."
+            },
+            {
+                "name": "secrets",
+                "type": "string[]",
+                "required": true,
+                "description": "Names of the org-scoped secrets this identity may read."
+            },
+            {
+                "name": "policyName",
+                "type": "string",
+                "required": false,
+                "description": "Policy name (default `<name>-secret-access`)."
+            },
+            {
+                "name": "permissions",
+                "type": "string[]",
+                "required": false,
+                "description": "Permissions granted on the target secrets (default `[\"reveal\"]`)."
+            },
+            {
+                "name": "tags",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Tags applied to both resources."
+            },
+            {
+                "name": "defaults",
+                "type": "{ identity?: Partial<ConstructorParameters<typeof Identity>[0]>; policy?: Partial<ConstructorParameters<typeof Policy...",
+                "required": false,
+                "description": "Per-member defaults for customizing individual resources."
+            }
+        ]
+    },
+    {
+        "name": "ServerlessService",
+        "lexicon": "cpln",
+        "description": "ServerlessService — a serverless workload with the port, probe and firewall settings a public HTTP service actually needs.",
+        "bundles": [
+            "Workload"
+        ],
+        "params": [
+            {
+                "name": "name",
+                "type": "string",
+                "required": true,
+                "description": "Workload name."
+            },
+            {
+                "name": "gvc",
+                "type": "string",
+                "required": true,
+                "description": "GVC this workload is deployed into."
+            },
+            {
+                "name": "image",
+                "type": "string",
+                "required": true,
+                "description": "Container image."
+            },
+            {
+                "name": "port",
+                "type": "number",
+                "required": false,
+                "description": "The port the container listens on."
+            },
+            {
+                "name": "protocol",
+                "type": "\"http\" | \"http2\"",
+                "required": false,
+                "description": "Protocol for the exposed port (default `http`)."
+            },
+            {
+                "name": "containerName",
+                "type": "string",
+                "required": false,
+                "description": "Container name (default `main`)."
+            },
+            {
+                "name": "cpu",
+                "type": "string",
+                "required": false,
+                "description": "CPU in millicores (default `50m`)."
+            },
+            {
+                "name": "memory",
+                "type": "string",
+                "required": false,
+                "description": "Memory (default `128Mi`)."
+            },
+            {
+                "name": "env",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Environment variables, as a plain map."
+            },
+            {
+                "name": "inboundAllowCidr",
+                "type": "string[]",
+                "required": false,
+                "description": "CIDRs allowed to reach the workload from the internet."
+            },
+            {
+                "name": "outboundAllowCidr",
+                "type": "string[]",
+                "required": false,
+                "description": "Hostnames or CIDRs the workload may call out to."
+            },
+            {
+                "name": "minScale",
+                "type": "number",
+                "required": false,
+                "description": "Minimum replicas (default 1)."
+            },
+            {
+                "name": "maxScale",
+                "type": "number",
+                "required": false,
+                "description": "Maximum replicas (default 5)."
+            },
+            {
+                "name": "autoscalingMetric",
+                "type": "\"concurrency\" | \"rps\" | \"cpu\" | \"memory\" | \"disabled\"",
+                "required": false,
+                "description": "Autoscaling strategy (default `concurrency`)."
+            },
+            {
+                "name": "autoscalingTarget",
+                "type": "number",
+                "required": false,
+                "description": "Scaling target (default 95)."
+            },
+            {
+                "name": "identityLink",
+                "type": "string",
+                "required": false,
+                "description": "Identity to run as, as a link (`//gvc/GVC/identity/NAME`)."
+            },
+            {
+                "name": "tags",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Tags applied to the workload."
+            },
+            {
+                "name": "defaults",
+                "type": "{ workload?: Partial<ConstructorParameters<typeof Workload>[0]>; }",
+                "required": false,
+                "description": "Per-member defaults for customizing the underlying resource."
+            }
+        ]
+    },
+    {
+        "name": "StatefulService",
+        "lexicon": "cpln",
+        "description": "StatefulService — a stateful workload with its volume set, mounted.",
+        "bundles": [
+            "VolumeSet",
+            "Workload"
+        ],
+        "params": [
+            {
+                "name": "name",
+                "type": "string",
+                "required": true,
+                "description": "Workload name."
+            },
+            {
+                "name": "gvc",
+                "type": "string",
+                "required": true,
+                "description": "GVC for both the workload and the volume set."
+            },
+            {
+                "name": "image",
+                "type": "string",
+                "required": true,
+                "description": "Container image."
+            },
+            {
+                "name": "mountPath",
+                "type": "string",
+                "required": true,
+                "description": "Mount path inside the container."
+            },
+            {
+                "name": "capacityGb",
+                "type": "number",
+                "required": true,
+                "description": "Initial volume capacity in GB."
+            },
+            {
+                "name": "volumeSetName",
+                "type": "string",
+                "required": false,
+                "description": "Volume set name (default `<name>-data`)."
+            },
+            {
+                "name": "fileSystemType",
+                "type": "\"ext4\" | \"xfs\" | \"shared\"",
+                "required": false,
+                "description": "Filesystem (default `ext4`)."
+            },
+            {
+                "name": "performanceClass",
+                "type": "\"general-purpose-ssd\" | \"high-throughput-ssd\" | \"shared\"",
+                "required": false,
+                "description": "Performance class (default `general-purpose-ssd`)."
+            },
+            {
+                "name": "recoveryPolicy",
+                "type": "\"retain\" | \"recycle\"",
+                "required": false,
+                "description": "What happens to the volume when the workload releases it (default `retain`)."
+            },
+            {
+                "name": "ports",
+                "type": "Array<{ number: number; protocol?: \"http\" | \"http2\" | \"grpc\" | \"tcp\" }>",
+                "required": false,
+                "description": "Ports the container exposes."
+            },
+            {
+                "name": "containerName",
+                "type": "string",
+                "required": false,
+                "description": "Container name (default `main`)."
+            },
+            {
+                "name": "cpu",
+                "type": "string",
+                "required": false,
+                "description": "CPU in millicores (default `50m`)."
+            },
+            {
+                "name": "memory",
+                "type": "string",
+                "required": false,
+                "description": "Memory (default `128Mi`)."
+            },
+            {
+                "name": "env",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Environment variables, as a plain map."
+            },
+            {
+                "name": "inboundAllowCidr",
+                "type": "string[]",
+                "required": false,
+                "description": "CIDRs allowed to reach the workload from the internet."
+            },
+            {
+                "name": "outboundAllowCidr",
+                "type": "string[]",
+                "required": false,
+                "description": "Hostnames or CIDRs the workload may call out to."
+            },
+            {
+                "name": "minScale",
+                "type": "number",
+                "required": false,
+                "description": "Minimum replicas (default 1)."
+            },
+            {
+                "name": "maxScale",
+                "type": "number",
+                "required": false,
+                "description": "Maximum replicas (default 1)."
+            },
+            {
+                "name": "identityLink",
+                "type": "string",
+                "required": false,
+                "description": "Identity to run as, as a link (`//gvc/GVC/identity/NAME`)."
+            },
+            {
+                "name": "tags",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "Tags applied to both resources."
+            },
+            {
+                "name": "defaults",
+                "type": "{ workload?: Partial<ConstructorParameters<typeof Workload>[0]>; volumeSet?: Partial<ConstructorParameters<typeof Vol...",
+                "required": false,
+                "description": "Per-member defaults for customizing individual resources."
+            }
+        ]
+    }
+];

package/dist/composites/cron-job.js

@@ -0,0 +1,52 @@
+/**
+ * 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/index.js";
+export const CronJob = Composite((props) => {
+    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 },
+            },
+        },
+    }, defs?.workload));
+    return { workload };
+}, "CronJob");

package/dist/composites/gvc-environment.js

@@ -0,0 +1,49 @@
+/**
+ * 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/index.js";
+/** Location ids look like `aws-us-east-1`, `gcp-us-central1`, `azure-eastus`. */
+const LOCATION_ID = /^(aws|gcp|azure)-[a-z0-9-]+$/;
+export const GvcEnvironment = Composite((props) => {
+    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 } }),
+        },
+    }, defs?.gvc));
+    return { gvc };
+}, "GvcEnvironment");

package/dist/composites/index.js

@@ -0,0 +1,6 @@
+export { GvcEnvironment } from "./gvc-environment.js";
+export { ServerlessService } from "./serverless-service.js";
+export { CronJob } from "./cron-job.js";
+export { StatefulService } from "./stateful-service.js";
+export { SecretAccess, identityLink, secretRef } from "./secret-access.js";
+export { PublicDomain, isApexDomain } from "./public-domain.js";