@intentius/chant-lexicon-gcp 0.124.34 → 0.124.36

package/dist/op/activities/gcp-apply.js

@@ -3,6 +3,8 @@ import { parseYAML } from "@intentius/chant/yaml";
 import { sleep } from "@intentius/chant/op";
 import { hasOwnershipMarker, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
 import { GCP_RESOURCE_OWNERSHIP_KEYS } from "../../ownership.js";
+import { iamPolicyMemberMapper } from "./gcp-iam.js";
+import { backendServiceMapper, computeAddressMapper, forwardingRuleMapper, networkMapper, subnetworkMapper, regionNetworkEndpointGroupMapper, targetHttpProxyMapper, urlMapMapper, } from "./gcp-compute.js";
 import { applyResult, } from "@intentius/chant/apply";
 const PROJECT_ID_ANNOTATION = "cnrm.cloud.google.com/project-id";
 /**
@@ -143,14 +145,71 @@ export const pubSubTopicMapper = {
         items: (body) => (body?.topics ?? []).map((t) => ({ name: t.name.split("/").pop() ?? t.name, labels: t.labels })),
     },
 };
-/** Map a CNRM RunService to a Cloud Run v2 Service body. Pure. */
-export function cloudRunServiceBody(resource) {
+/**
+ * Map a CNRM RunService to a Cloud Run v2 Service body. Pure. CNRM names the
+ * service account with `template.serviceAccountRef`; v2 takes
+ * `template.serviceAccount` as an email (#4240).
+ */
+export function cloudRunServiceBody(resource, project) {
     const spec = (resource.spec ?? {});
     const body = {};
-    if (spec.template)
-        body.template = spec.template;
+    if (!spec.template)
+        return body;
+    const { serviceAccountRef, ...template } = spec.template;
+    const email = serviceAccountEmail(serviceAccountRef, project);
+    const out = email ? { ...template, serviceAccount: email } : { ...template };
+    const vpcAccess = out.vpcAccess;
+    if (vpcAccess && Array.isArray(vpcAccess.networkInterfaces)) {
+        const region = (resource.spec ?? {}).location ?? "us-central1";
+        out.vpcAccess = { ...vpcAccess, networkInterfaces: vpcAccess.networkInterfaces.map((i) => networkInterface(i, project, region)) };
+    }
+    body.template = out;
     return body;
 }
+/**
+ * A CNRM Direct VPC egress interface as Cloud Run v2 takes it (#4249):
+ * `networkRef` and `subnetworkRef` become `network` and `subnetwork` paths,
+ * `name` in the project (the subnetwork in the service's region) and
+ * `external` as given. `tags` and anything else pass through. Pure.
+ */
+export function networkInterface(iface, project, region) {
+    if (!iface || typeof iface !== "object")
+        return iface;
+    const { networkRef, subnetworkRef, ...rest } = iface;
+    const path = (ref, scoped, key) => {
+        if (!ref)
+            return undefined;
+        if (ref.external)
+            return ref.external;
+        if (!ref.name)
+            return undefined;
+        if (!project)
+            throw new Error(`${key} { name: "${ref.name}" } needs a project to form its path`);
+        return scoped(project, ref.name);
+    };
+    const network = path(networkRef, (p, n) => `projects/${p}/global/networks/${n}`, "networkRef");
+    const subnetwork = path(subnetworkRef, (p, n) => `projects/${p}/regions/${region}/subnetworks/${n}`, "subnetworkRef");
+    return { ...rest, ...(network ? { network } : {}), ...(subnetwork ? { subnetwork } : {}) };
+}
+/**
+ * The email a CNRM `serviceAccountRef` names: `external` as given (an email,
+ * or a `projects/<p>/serviceAccounts/<email>` path), `name` as an account id
+ * in the project.
+ */
+export function serviceAccountEmail(ref, project) {
+    if (!ref)
+        return undefined;
+    if (ref.external)
+        return ref.external.split("/").pop();
+    if (ref.name) {
+        if (ref.name.includes("@"))
+            return ref.name;
+        if (!project)
+            throw new Error(`serviceAccountRef { name: "${ref.name}" } needs a project to form the account's email`);
+        return `${ref.name}@${project}.iam.gserviceaccount.com`;
+    }
+    return undefined;
+}
 export const cloudRunServiceMapper = {
     kind: "RunService",
     defaultHost: "https://run.googleapis.com",
@@ -168,11 +227,11 @@ export const cloudRunServiceMapper = {
             create: {
                 method: "POST",
                 url: `${services}?serviceId=${encodeURIComponent(name)}`,
-                body: cloudRunServiceBody(resource),
+                body: cloudRunServiceBody(resource, project),
             },
             // Cloud Run reconciles with a PATCH of the service; like create it returns
             // a long-running operation, polled via the mapper's `operation`.
-            update: { method: "PATCH", url, body: cloudRunServiceBody(resource) },
+            update: { method: "PATCH", url, body: cloudRunServiceBody(resource, project) },
         };
     },
 };
@@ -259,6 +318,16 @@ export const MAPPERS = {
     SecretManagerSecret: secretManagerSecretMapper,
     IAMServiceAccount: gcpServiceAccountMapper,
     RunService: cloudRunServiceMapper,
+    // #4233: a binding member, and the Cloud Run load balancer.
+    IAMPolicyMember: iamPolicyMemberMapper,
+    ComputeAddress: computeAddressMapper,
+    ComputeRegionNetworkEndpointGroup: regionNetworkEndpointGroupMapper,
+    ComputeBackendService: backendServiceMapper,
+    ComputeURLMap: urlMapMapper,
+    ComputeTargetHTTPProxy: targetHttpProxyMapper,
+    ComputeForwardingRule: forwardingRuleMapper,
+    ComputeNetwork: networkMapper,
+    ComputeSubnetwork: subnetworkMapper,
 };
 /**
  * Collect the local resource names this resource references via CNRM `*Ref`
@@ -266,7 +335,29 @@ export const MAPPERS = {
  * refs point outside the manifest and are ignored for ordering. Pure.
  */
 export function referencedNames(resource) {
-    const names = [];
+    return [...new Set(referencedResources(resource).map((r) => r.name))];
+}
+/**
+ * The CNRM kind a `*Ref` key points at, where the key alone says. A ref that
+ * carries its own `kind` (`resourceRef`) uses that. Two resources of different
+ * kinds may share a name (a RunService `web` and its NEG `web`), so ordering
+ * matches on kind when it can.
+ */
+const REF_KINDS = {
+    topicRef: "PubSubTopic",
+    serviceRef: "RunService",
+    serviceAccountRef: "IAMServiceAccount",
+    addressRef: "ComputeAddress",
+    networkEndpointGroupRef: "ComputeRegionNetworkEndpointGroup",
+    backendServiceRef: "ComputeBackendService",
+    urlMapRef: "ComputeURLMap",
+    targetHTTPProxyRef: "ComputeTargetHTTPProxy",
+    networkRef: "ComputeNetwork",
+    subnetworkRef: "ComputeSubnetwork",
+};
+/** The local resources this resource references via `*Ref` fields, each with its kind when known. Pure. */
+export function referencedResources(resource) {
+    const refs = [];
     const visit = (v, key) => {
         if (Array.isArray(v)) {
             for (const x of v)
@@ -276,14 +367,15 @@ export function referencedNames(resource) {
         if (v && typeof v === "object") {
             const obj = v;
             if (key && /Refs?$/.test(key) && typeof obj.name === "string") {
-                names.push(obj.name);
+                const kind = typeof obj.kind === "string" ? obj.kind : REF_KINDS[key];
+                refs.push(kind ? { name: obj.name, kind } : { name: obj.name });
             }
             for (const [k, val] of Object.entries(obj))
                 visit(val, k);
         }
     };
     visit(resource.spec);
-    return [...new Set(names)];
+    return refs;
 }
 /**
  * Topologically order resources so a referenced resource comes before the
@@ -296,7 +388,7 @@ export function orderByReferences(resources) {
     for (const r of resources) {
         const n = r.metadata?.name;
         if (n)
-            byName.set(n, r);
+            byName.set(n, [...(byName.get(n) ?? []), r]);
     }
     const ordered = [];
     const done = new Set();
@@ -307,9 +399,10 @@ export function orderByReferences(resources) {
         if (active.has(r))
             throw new Error(`reference cycle involving ${r.metadata?.name ?? "?"}`);
         active.add(r);
-        for (const ref of referencedNames(r)) {
-            const dep = byName.get(ref);
-            if (dep && dep !== r)
+        for (const ref of referencedResources(r)) {
+            const named = (byName.get(ref.name) ?? []).filter((d) => d !== r);
+            const deps = ref.kind ? named.filter((d) => d.kind === ref.kind) : named;
+            for (const dep of deps)
                 visit(dep);
         }
         active.delete(r);
@@ -379,8 +472,12 @@ const defaultHttp = async (method, url, body, signal) => {
  * completion. `http` is injectable for tests.
  */
 export async function applyResource(mapper, resource, ctx, http = defaultHttp, signal) {
-    const plan = mapper.plan(resource, ctx);
     const name = resource.metadata?.name ?? "?";
+    if (mapper.custom) {
+        const result = await mapper.custom.apply(resource, ctx, http, signal);
+        return { kind: mapper.kind, name, ...result };
+    }
+    const plan = mapper.plan(resource, ctx);
     const get = await http("GET", plan.getUrl, undefined, signal);
     if (get.status === 200) {
         // Exists. Reconcile to desired if the mapper supports it; otherwise leave it.
@@ -566,6 +663,7 @@ export async function gcpApply(args, signal, http = defaultHttp) {
     const resolve = (mapper, resource) => ({
         base: (endpoint ?? mapper.defaultHost).replace(/\/$/, ""),
         project: args.project ?? (resource ? resolveGcpProject(resource) : ""),
+        manifest: resources,
     });
     const applied = [];
     const notAttempted = [];
@@ -578,6 +676,11 @@ export async function gcpApply(args, signal, http = defaultHttp) {
             continue;
         }
         const ctx = resolve(mapper, r);
+        if (mapper.accepts && !mapper.accepts(r, ctx)) {
+            console.log(`skip: ${r.kind}/${r.metadata?.name ?? "?"} has nothing chant can apply it to`);
+            notAttempted.push({ kind: r.kind, name: r.metadata?.name ?? "?", reason: "unsupported-kind" });
+            continue;
+        }
         const result = await applyResource(mapper, r, ctx, http, signal);
         const verb = result.created ? "created" : result.updated ? "updated" : "unchanged";
         console.log(`${verb}: ${result.kind}/${result.name} (${ctx.base})`);
@@ -594,8 +697,11 @@ export async function gcpApply(args, signal, http = defaultHttp) {
  * that is polled to completion. `http` is injectable for tests.
  */
 export async function deleteResource(mapper, resource, ctx, http = defaultHttp, signal) {
-    const plan = mapper.plan(resource, ctx);
     const name = resource.metadata?.name ?? "?";
+    if (mapper.custom) {
+        return { kind: mapper.kind, name, deleted: await mapper.custom.delete(resource, ctx, http, signal) };
+    }
+    const plan = mapper.plan(resource, ctx);
     const res = await http("DELETE", plan.getUrl, undefined, signal);
     if (res.status === 404) {
         return { kind: mapper.kind, name, deleted: false };
@@ -633,7 +739,13 @@ export async function gcpDelete(args, signal, http = defaultHttp) {
         }
         const base = (resolveGcpEndpoint(args) ?? mapper.defaultHost).replace(/\/$/, "");
         const project = args.project ?? resolveGcpProject(r);
-        const result = await deleteResource(mapper, r, { base, project }, http, signal);
+        const ctx = { base, project, manifest: resources };
+        if (mapper.accepts && !mapper.accepts(r, ctx)) {
+            console.log(`skip: ${r.kind}/${r.metadata?.name ?? "?"} has nothing chant can delete it from`);
+            notAttempted.push({ kind: r.kind, name: r.metadata?.name ?? "?", reason: "unsupported-kind" });
+            continue;
+        }
+        const result = await deleteResource(mapper, r, ctx, http, signal);
         console.log(`${result.deleted ? "deleted" : "absent"}: ${result.kind}/${result.name} (${base})`);
         deleted.push(result);
     }

package/dist/op/activities/gcp-compute.d.ts

@@ -0,0 +1,66 @@
+import type { GcpResource, OperationSpec, ResourceMapper } from "./gcp-apply.js";
+export declare const COMPUTE_HOST = "https://compute.googleapis.com";
+type Ref = {
+    name?: string;
+    external?: string;
+    kind?: string;
+};
+type Obj = Record<string, unknown>;
+export interface ComputeCtx {
+    base: string;
+    project: string;
+    manifest?: readonly GcpResource[];
+}
+/** The region or `"global"` a CNRM compute spec declares. A NEG names `region`; the rest `location`. */
+export declare function scopeOf(spec: Obj | undefined, env?: NodeJS.ProcessEnv): string;
+/** The compute name: CNRM's `resourceID` when set, else `metadata.name`. */
+export declare function computeName(resource: GcpResource): string;
+/**
+ * The partial URL a `*Ref` resolves to. `external` is used as given when it is
+ * a path or URL; a bare name (or `name`) is scoped by the referenced resource's
+ * own spec when the manifest holds it, else by `fallbackScope`. Pure.
+ */
+export declare function refUrl(key: string, ref: Ref, ctx: ComputeCtx, fallbackScope: string): string;
+/**
+ * The resource's labels GCP accepts, plus the ownership marker. Composites put
+ * Kubernetes-style keys (`app.kubernetes.io/component`) in `metadata.labels`,
+ * which a compute label key can't hold, so those are left out.
+ */
+export declare function computeLabels(labels: Record<string, string> | undefined): Record<string, string>;
+/** ComputeAddress → addresses.insert body. Pure. */
+export declare function addressBody(resource: GcpResource, ctx: ComputeCtx): Obj;
+/** ComputeRegionNetworkEndpointGroup → regionNetworkEndpointGroups.insert body (serverless NEGs). Pure. */
+export declare function negBody(resource: GcpResource, ctx: ComputeCtx): Obj;
+/**
+ * ComputeNetwork → networks.insert body. A network is global. CNRM's
+ * `autoCreateSubnetworks` defaults to false, where compute's default is true,
+ * so it is always sent. Pure.
+ */
+export declare function networkBody(resource: GcpResource): Obj;
+/** ComputeSubnetwork → subnetworks.insert body. CNRM's `secondaryIpRange` and `logConfig` become compute's `secondaryIpRanges` and an enabled `logConfig`. Pure. */
+export declare function subnetworkBody(resource: GcpResource, ctx: ComputeCtx): Obj;
+/** ComputeBackendService → backendServices.insert body. Pure. */
+export declare function backendServiceBody(resource: GcpResource, ctx: ComputeCtx): Obj;
+/** ComputeURLMap → urlMaps.insert body. Pure. */
+export declare function urlMapBody(resource: GcpResource, ctx: ComputeCtx): Obj;
+/** ComputeTargetHTTPProxy → targetHttpProxies.insert body. Pure. */
+export declare function targetHttpProxyBody(resource: GcpResource, ctx: ComputeCtx): Obj;
+/** ComputeForwardingRule → forwardingRules.insert body. Pure. */
+export declare function forwardingRuleBody(resource: GcpResource, ctx: ComputeCtx): Obj;
+/**
+ * A compute `Operation`: the insert or delete returns one with a `selfLink`,
+ * polled until `status: "DONE"`. The link is rebased onto `base`, so an
+ * endpoint override (floci-gcp) is polled too. A create that returned the
+ * resource itself has nothing to poll.
+ */
+export declare const computeOperation: OperationSpec;
+export declare const computeAddressMapper: ResourceMapper;
+export declare const regionNetworkEndpointGroupMapper: ResourceMapper;
+export declare const backendServiceMapper: ResourceMapper;
+export declare const urlMapMapper: ResourceMapper;
+export declare const targetHttpProxyMapper: ResourceMapper;
+export declare const forwardingRuleMapper: ResourceMapper;
+export declare const networkMapper: ResourceMapper;
+export declare const subnetworkMapper: ResourceMapper;
+export {};
+//# sourceMappingURL=gcp-compute.d.ts.map

package/dist/op/activities/gcp-compute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp-compute.d.ts","sourceRoot":"","sources":["../../../src/op/activities/gcp-compute.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9E,eAAO,MAAM,YAAY,mCAAmC,CAAC;AAI7D,KAAK,GAAG,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/D,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAqBnC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CACnC;AAED,wGAAwG;AACxG,wBAAgB,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,SAAS,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG3F;AAMD,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAKzD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAmB5F;AAkBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMhG;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,GAAG,CAWvE;AAED,2GAA2G;AAC3G,wBAAgB,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,GAAG,CA0BnE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,GAAG,CAStD;AAED,oKAAoK;AACpK,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,GAAG,CAW1E;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,GAAG,CAoC9E;AAED,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,GAAG,CA4BtE;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,GAAG,CAK/E;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,GAAG,CAoB9E;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAe9B,CAAC;AAsBF,eAAO,MAAM,oBAAoB,gBAA4D,CAAC;AAC9F,eAAO,MAAM,gCAAgC,gBAAuF,CAAC;AACrI,eAAO,MAAM,oBAAoB,gBAAgF,CAAC;AAClH,eAAO,MAAM,YAAY,gBAAwD,CAAC;AAClF,eAAO,MAAM,qBAAqB,gBAAoF,CAAC;AACvH,eAAO,MAAM,oBAAoB,gBAAgF,CAAC;AAClH,eAAO,MAAM,aAAa,gBAAuF,CAAC;AAClH,eAAO,MAAM,gBAAgB,gBAAoE,CAAC"}

package/dist/op/activities/gcp-compute.js

@@ -0,0 +1,349 @@
+/**
+ * Compute Engine mappers for the Cloud Run load balancer (#4233): ComputeAddress,
+ * ComputeRegionNetworkEndpointGroup (serverless NEGs), ComputeBackendService,
+ * ComputeURLMap, ComputeTargetHTTPProxy and ComputeForwardingRule; and for a
+ * declared network (#4248): ComputeNetwork (always global) and
+ * ComputeSubnetwork (regional, by its CNRM `region`).
+ *
+ * Each maps a CNRM spec onto the compute v1 insert body. A resource is global
+ * or regional by its CNRM `location` (`"global"` or a region; a NEG has
+ * `region`), and that picks `projects/<p>/global/<collection>` or
+ * `projects/<p>/regions/<r>/<collection>`. `*Ref` fields become the referenced
+ * resource's partial URL, which compute accepts; a ref to a resource in the
+ * same manifest takes its scope from that resource's own spec, so a global
+ * backend service can point at a regional NEG.
+ *
+ * Inserts return a compute `Operation`, polled at its `selfLink` (rebased onto
+ * the endpoint override, so floci-gcp answers). These kinds reconcile by
+ * existence only: an existing resource is left as it is, since compute updates
+ * need the live `fingerprint` and most of these fields are immutable.
+ */
+import { GCP_RESOURCE_OWNERSHIP_KEYS } from "../../ownership.js";
+import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+export const COMPUTE_HOST = "https://compute.googleapis.com";
+const enc = encodeURIComponent;
+function isObj(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** What a `*Ref` key points at: the CNRM kind (for a manifest lookup), the collection, and whether it is global only. */
+const REF_TARGETS = {
+    addressRef: { kind: "ComputeAddress", collection: "addresses", scope: "either" },
+    networkEndpointGroupRef: { kind: "ComputeRegionNetworkEndpointGroup", collection: "networkEndpointGroups", scope: "regional" },
+    backendServiceRef: { kind: "ComputeBackendService", collection: "backendServices", scope: "either" },
+    backendBucketRef: { kind: "ComputeBackendBucket", collection: "backendBuckets", scope: "global" },
+    urlMapRef: { kind: "ComputeURLMap", collection: "urlMaps", scope: "either" },
+    targetHTTPProxyRef: { kind: "ComputeTargetHTTPProxy", collection: "targetHttpProxies", scope: "either" },
+    targetHTTPSProxyRef: { kind: "ComputeTargetHTTPSProxy", collection: "targetHttpsProxies", scope: "either" },
+    healthCheckRef: { kind: "ComputeHealthCheck", collection: "healthChecks", scope: "either" },
+    securityPolicyRef: { kind: "ComputeSecurityPolicy", collection: "securityPolicies", scope: "global" },
+    networkRef: { kind: "ComputeNetwork", collection: "networks", scope: "global" },
+    subnetworkRef: { kind: "ComputeSubnetwork", collection: "subnetworks", scope: "regional" },
+};
+/** The region or `"global"` a CNRM compute spec declares. A NEG names `region`; the rest `location`. */
+export function scopeOf(spec, env = process.env) {
+    const loc = spec?.location ?? spec?.region;
+    return typeof loc === "string" && loc !== "" ? loc : (env.GCP_REGION || "us-central1");
+}
+function scopePath(project, scope) {
+    return scope === "global" ? `projects/${enc(project)}/global` : `projects/${enc(project)}/regions/${enc(scope)}`;
+}
+/** The compute name: CNRM's `resourceID` when set, else `metadata.name`. */
+export function computeName(resource) {
+    const id = resource.spec?.resourceID;
+    const name = typeof id === "string" && id !== "" ? id : resource.metadata?.name;
+    if (!name)
+        throw new Error(`${resource.kind ?? "compute resource"} has no metadata.name`);
+    return name;
+}
+/**
+ * The partial URL a `*Ref` resolves to. `external` is used as given when it is
+ * a path or URL; a bare name (or `name`) is scoped by the referenced resource's
+ * own spec when the manifest holds it, else by `fallbackScope`. Pure.
+ */
+export function refUrl(key, ref, ctx, fallbackScope) {
+    const target = REF_TARGETS[key];
+    if (!target)
+        throw new Error(`no compute collection for ${key}`);
+    if (typeof ref.external === "string" && ref.external !== "") {
+        if (ref.external.startsWith("projects/") || ref.external.startsWith("https://"))
+            return ref.external;
+    }
+    const name = ref.name ?? ref.external;
+    if (!name)
+        throw new Error(`${key} has no name or external`);
+    const declared = ctx.manifest?.find((r) => r.kind === target.kind && (r.metadata?.name === name || r.spec?.resourceID === name));
+    const scope = target.scope === "global"
+        ? "global"
+        : declared
+            ? scopeOf(declared.spec)
+            : target.scope === "regional" && fallbackScope === "global"
+                ? scopeOf(undefined)
+                : fallbackScope;
+    const resolvedName = declared ? computeName(declared) : name;
+    return `${scopePath(ctx.project, scope)}/${target.collection}/${resolvedName}`;
+}
+/** Resolve the one `*Ref` key an object holds (`{ backendServiceRef: {...} }` → URL), or undefined. */
+function oneRef(value, ctx, scope) {
+    if (!isObj(value))
+        return undefined;
+    for (const [k, v] of Object.entries(value)) {
+        if (REF_TARGETS[k] && isObj(v))
+            return refUrl(k, v, ctx, scope);
+    }
+    return undefined;
+}
+/** Copy the listed fields that are set. */
+function pick(spec, keys) {
+    const out = {};
+    for (const k of keys)
+        if (spec[k] !== undefined)
+            out[k] = spec[k];
+    return out;
+}
+/**
+ * The resource's labels GCP accepts, plus the ownership marker. Composites put
+ * Kubernetes-style keys (`app.kubernetes.io/component`) in `metadata.labels`,
+ * which a compute label key can't hold, so those are left out.
+ */
+export function computeLabels(labels) {
+    const out = {};
+    for (const [k, v] of Object.entries(labels ?? {})) {
+        if (/^[a-z][a-z0-9_-]{0,62}$/.test(k) && typeof v === "string" && /^[a-z0-9_-]{0,63}$/.test(v))
+            out[k] = v;
+    }
+    return { ...out, [GCP_RESOURCE_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE };
+}
+/** ComputeAddress → addresses.insert body. Pure. */
+export function addressBody(resource, ctx) {
+    const spec = (resource.spec ?? {});
+    const scope = scopeOf(spec);
+    const body = {
+        name: computeName(resource),
+        ...pick(spec, ["address", "addressType", "description", "ipVersion", "ipv6EndpointType", "networkTier", "prefixLength", "purpose"]),
+        labels: computeLabels(resource.metadata?.labels),
+    };
+    if (isObj(spec.networkRef))
+        body.network = refUrl("networkRef", spec.networkRef, ctx, scope);
+    if (isObj(spec.subnetworkRef))
+        body.subnetwork = refUrl("subnetworkRef", spec.subnetworkRef, ctx, scope);
+    return body;
+}
+/** ComputeRegionNetworkEndpointGroup → regionNetworkEndpointGroups.insert body (serverless NEGs). Pure. */
+export function negBody(resource, ctx) {
+    const spec = (resource.spec ?? {});
+    const scope = scopeOf(spec);
+    const body = {
+        name: computeName(resource),
+        networkEndpointType: spec.networkEndpointType ?? "SERVERLESS",
+        ...pick(spec, ["description", "pscTargetService"]),
+    };
+    const serviceName = (ref) => {
+        if (!isObj(ref))
+            return undefined;
+        const r = ref;
+        // A serverless NEG names the service, not its path.
+        return (r.external ?? r.name)?.split("/").pop();
+    };
+    if (isObj(spec.cloudRun)) {
+        const c = spec.cloudRun;
+        body.cloudRun = { ...pick(c, ["tag", "urlMask"]), ...(serviceName(c.serviceRef) ? { service: serviceName(c.serviceRef) } : {}) };
+    }
+    if (isObj(spec.cloudFunction)) {
+        const c = spec.cloudFunction;
+        body.cloudFunction = { ...pick(c, ["urlMask"]), ...(serviceName(c.functionRef) ? { function: serviceName(c.functionRef) } : {}) };
+    }
+    if (isObj(spec.appEngine))
+        body.appEngine = spec.appEngine;
+    if (isObj(spec.networkRef))
+        body.network = refUrl("networkRef", spec.networkRef, ctx, scope);
+    if (isObj(spec.subnetworkRef))
+        body.subnetwork = refUrl("subnetworkRef", spec.subnetworkRef, ctx, scope);
+    return body;
+}
+/**
+ * ComputeNetwork → networks.insert body. A network is global. CNRM's
+ * `autoCreateSubnetworks` defaults to false, where compute's default is true,
+ * so it is always sent. Pure.
+ */
+export function networkBody(resource) {
+    const spec = (resource.spec ?? {});
+    const body = {
+        name: computeName(resource),
+        autoCreateSubnetworks: spec.autoCreateSubnetworks === true,
+        ...pick(spec, ["description", "mtu", "networkFirewallPolicyEnforcementOrder"]),
+    };
+    if (typeof spec.routingMode === "string")
+        body.routingConfig = { routingMode: spec.routingMode };
+    return body;
+}
+/** ComputeSubnetwork → subnetworks.insert body. CNRM's `secondaryIpRange` and `logConfig` become compute's `secondaryIpRanges` and an enabled `logConfig`. Pure. */
+export function subnetworkBody(resource, ctx) {
+    const spec = (resource.spec ?? {});
+    const scope = scopeOf(spec);
+    const body = {
+        name: computeName(resource),
+        ...pick(spec, ["ipCidrRange", "description", "privateIpGoogleAccess", "purpose", "role", "stackType"]),
+    };
+    if (isObj(spec.networkRef))
+        body.network = refUrl("networkRef", spec.networkRef, ctx, scope);
+    if (Array.isArray(spec.secondaryIpRange))
+        body.secondaryIpRanges = spec.secondaryIpRange;
+    if (isObj(spec.logConfig))
+        body.logConfig = { enable: true, ...spec.logConfig };
+    return body;
+}
+/** ComputeBackendService → backendServices.insert body. Pure. */
+export function backendServiceBody(resource, ctx) {
+    const spec = (resource.spec ?? {});
+    const scope = scopeOf(spec);
+    const body = {
+        name: computeName(resource),
+        ...pick(spec, [
+            "affinityCookieTtlSec",
+            "cdnPolicy",
+            "compressionMode",
+            "customRequestHeaders",
+            "customResponseHeaders",
+            "description",
+            "loadBalancingScheme",
+            "localityLbPolicy",
+            "logConfig",
+            "portName",
+            "protocol",
+            "sessionAffinity",
+            "timeoutSec",
+        ]),
+    };
+    if (spec.enableCdn !== undefined)
+        body.enableCDN = spec.enableCdn;
+    if (spec.connectionDrainingTimeoutSec !== undefined)
+        body.connectionDraining = { drainingTimeoutSec: spec.connectionDrainingTimeoutSec };
+    if (Array.isArray(spec.backend)) {
+        body.backends = spec.backend.map((b) => {
+            const { group, ...rest } = b;
+            const groupUrl = isObj(group) ? oneRef(group, ctx, scope) ?? group.instanceGroupRef?.external : undefined;
+            return { ...rest, ...(groupUrl ? { group: groupUrl } : {}) };
+        });
+    }
+    if (Array.isArray(spec.healthChecks)) {
+        body.healthChecks = spec.healthChecks.map((h) => oneRef(h, ctx, scope)).filter((u) => !!u);
+    }
+    if (isObj(spec.securityPolicyRef))
+        body.securityPolicy = refUrl("securityPolicyRef", spec.securityPolicyRef, ctx, scope);
+    else if (typeof spec.securityPolicy === "string")
+        body.securityPolicy = spec.securityPolicy;
+    return body;
+}
+/** ComputeURLMap → urlMaps.insert body. Pure. */
+export function urlMapBody(resource, ctx) {
+    const spec = (resource.spec ?? {});
+    const scope = scopeOf(spec);
+    const service = (v) => oneRef(v, ctx, scope);
+    const body = {
+        name: computeName(resource),
+        ...pick(spec, ["description", "defaultUrlRedirect", "headerAction"]),
+    };
+    const def = service(spec.defaultService);
+    if (def)
+        body.defaultService = def;
+    if (Array.isArray(spec.hostRule))
+        body.hostRules = spec.hostRule;
+    if (Array.isArray(spec.pathMatcher)) {
+        body.pathMatchers = spec.pathMatcher.map((m) => {
+            const { defaultService, pathRule, ...rest } = m;
+            const out = { ...rest };
+            const d = service(defaultService);
+            if (d)
+                out.defaultService = d;
+            if (Array.isArray(pathRule)) {
+                out.pathRules = pathRule.map((r) => {
+                    const { service: s, ...rr } = r;
+                    const u = service(s);
+                    return { ...rr, ...(u ? { service: u } : {}) };
+                });
+            }
+            return out;
+        });
+    }
+    return body;
+}
+/** ComputeTargetHTTPProxy → targetHttpProxies.insert body. Pure. */
+export function targetHttpProxyBody(resource, ctx) {
+    const spec = (resource.spec ?? {});
+    const body = { name: computeName(resource), ...pick(spec, ["description", "proxyBind", "httpKeepAliveTimeoutSec"]) };
+    if (isObj(spec.urlMapRef))
+        body.urlMap = refUrl("urlMapRef", spec.urlMapRef, ctx, scopeOf(spec));
+    return body;
+}
+/** ComputeForwardingRule → forwardingRules.insert body. Pure. */
+export function forwardingRuleBody(resource, ctx) {
+    const spec = (resource.spec ?? {});
+    const scope = scopeOf(spec);
+    const body = {
+        name: computeName(resource),
+        ...pick(spec, ["allowGlobalAccess", "description", "ipVersion", "isMirroringCollector", "loadBalancingScheme", "networkTier", "portRange", "ports", "allPorts"]),
+        labels: computeLabels(resource.metadata?.labels),
+    };
+    if (spec.ipProtocol !== undefined)
+        body.IPProtocol = spec.ipProtocol;
+    if (isObj(spec.ipAddress)) {
+        const ip = spec.ipAddress;
+        const addr = isObj(ip.addressRef) ? refUrl("addressRef", ip.addressRef, ctx, scope) : ip.ip;
+        if (addr)
+            body.IPAddress = addr;
+    }
+    const target = oneRef(spec.target, ctx, scope);
+    if (target)
+        body.target = target;
+    if (isObj(spec.backendServiceRef))
+        body.backendService = refUrl("backendServiceRef", spec.backendServiceRef, ctx, scope);
+    if (isObj(spec.networkRef))
+        body.network = refUrl("networkRef", spec.networkRef, ctx, scope);
+    if (isObj(spec.subnetworkRef))
+        body.subnetwork = refUrl("subnetworkRef", spec.subnetworkRef, ctx, scope);
+    return body;
+}
+/**
+ * A compute `Operation`: the insert or delete returns one with a `selfLink`,
+ * polled until `status: "DONE"`. The link is rebased onto `base`, so an
+ * endpoint override (floci-gcp) is polled too. A create that returned the
+ * resource itself has nothing to poll.
+ */
+export const computeOperation = {
+    pollUrl(body, { base }) {
+        const op = body;
+        const link = op?.selfLink;
+        if (!link || !link.includes("/operations/"))
+            return undefined;
+        const at = link.indexOf("/compute/v1/");
+        return at >= 0 ? `${base}${link.slice(at)}` : link;
+    },
+    isDone(body) {
+        return body?.status === "DONE";
+    },
+    error(body) {
+        const errors = body?.error?.errors;
+        return errors?.length ? errors.map((e) => e.message ?? e.code ?? "error").join("; ") : undefined;
+    },
+};
+function computeMapper(kind, collection, build, regionalCollection = collection, scopeFor = (spec) => scopeOf(spec)) {
+    return {
+        kind,
+        defaultHost: COMPUTE_HOST,
+        operation: computeOperation,
+        plan(resource, ctx) {
+            const scope = scopeFor(resource.spec);
+            const coll = `${ctx.base}/compute/v1/${scopePath(ctx.project, scope)}/${scope === "global" ? collection : regionalCollection}`;
+            const name = computeName(resource);
+            return { getUrl: `${coll}/${enc(name)}`, create: { method: "POST", url: coll, body: build(resource, ctx) } };
+        },
+    };
+}
+export const computeAddressMapper = computeMapper("ComputeAddress", "addresses", addressBody);
+export const regionNetworkEndpointGroupMapper = computeMapper("ComputeRegionNetworkEndpointGroup", "networkEndpointGroups", negBody);
+export const backendServiceMapper = computeMapper("ComputeBackendService", "backendServices", backendServiceBody);
+export const urlMapMapper = computeMapper("ComputeURLMap", "urlMaps", urlMapBody);
+export const targetHttpProxyMapper = computeMapper("ComputeTargetHTTPProxy", "targetHttpProxies", targetHttpProxyBody);
+export const forwardingRuleMapper = computeMapper("ComputeForwardingRule", "forwardingRules", forwardingRuleBody);
+export const networkMapper = computeMapper("ComputeNetwork", "networks", networkBody, "networks", () => "global");
+export const subnetworkMapper = computeMapper("ComputeSubnetwork", "subnetworks", subnetworkBody);