@intentius/chant-lexicon-gcp 0.124.31 → 0.124.32

package/dist/deep-observe-hooks.js

@@ -0,0 +1,152 @@
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { GCP_RESOURCE_OWNERSHIP_KEYS } from "./ownership.js";
+import { resolveGVK } from "./serializer.js";
+/**
+ * Fields GCP populates on essentially anything, wherever they appear.
+ *
+ * Pruned on BOTH sides and regardless of whether source declared them: these
+ * are server-assigned identity and bookkeeping, and a user who writes one is
+ * writing something the API will overwrite anyway.
+ */
+export const GCP_READ_ONLY_NAMES = new Set([
+    "etag",
+    "selfLink",
+    "id",
+    "projectId",
+    "projectNumber",
+    "timeCreated",
+    "updated",
+    "createTime",
+    "updateTime",
+    "generation",
+    "metageneration",
+    "uid",
+    "uniqueId",
+    "email",
+    "state",
+    "reconciling",
+    "observedGeneration",
+    // Cloud Run's server-computed service surface (v2 GetService).
+    "uri",
+    "urls",
+    "conditions",
+    "terminalCondition",
+    "latestReadyRevision",
+    "latestCreatedRevision",
+]);
+/**
+ * Per-kind values GCP fills in when the request omits them, keyed by the
+ * index-erased pattern from the tree root (the declared-props shape
+ * `./deep-observe.ts` reshapes the live payload into — spec fields at the
+ * root, so `storageClass`, not `spec.storageClass`).
+ *
+ * Unlike {@link GCP_READ_ONLY_NAMES} these are only noise where **source never
+ * declared the property** — a default somebody explicitly wrote is a fact worth
+ * diffing, and pruning it would hide a real change away from it. The
+ * `counterpart === "absent"` gate below is what enforces that, and it is the
+ * same rule the AWS and Azure hooks apply.
+ */
+export const GCP_SERVICE_DEFAULTS = {
+    StorageBucket: {
+        storageClass: "STANDARD",
+        locationType: "multi-region",
+        publicAccessPrevention: "inherited",
+        uniformBucketLevelAccess: false,
+        "softDeletePolicy.retentionDurationSeconds": "604800",
+    },
+    PubSubTopic: {
+        "messageStoragePolicy.enforceInTransit": false,
+    },
+    PubSubSubscription: {
+        ackDeadlineSeconds: 10,
+        "expirationPolicy.ttl": "2678400s",
+        enableMessageOrdering: false,
+        enableExactlyOnceDelivery: false,
+        retainAckedMessages: false,
+        detached: false,
+        "retryPolicy.minimumBackoff": "10s",
+    },
+    RunService: {
+        ingress: "INGRESS_TRAFFIC_ALL",
+        launchStage: "GA",
+    },
+    IAMServiceAccount: {
+        disabled: false,
+    },
+};
+/**
+ * chant's own ownership marker, in both vocabularies it is written in: the
+ * serializer stamps k8s-style label keys on the CNRM object
+ * (`app.kubernetes.io/managed-by`), while `gcpApply` stamps the GCP-legal
+ * equivalents on the live resource (`managed-by` — GCP label keys allow no `/`
+ * or `.`). See `./ownership.ts` for why the two surfaces differ. A declared
+ * tree carries the first family, a live payload can carry either (the applier
+ * forwards the manifest's labels where a kind accepts labels at all), and
+ * neither is drift: it is chant showing its own signature to itself — the same
+ * correction #1301 made for AWS.
+ */
+const CHANT_OWNERSHIP_LABEL_PATTERNS = new Set([LABEL_OWNERSHIP_KEYS, GCP_RESOURCE_OWNERSHIP_KEYS].flatMap((keys) => [
+    `metadata.labels.${keys.managedBy}`,
+    `metadata.labels.${keys.stack}`,
+    `metadata.labels.${keys.env}`,
+]));
+/** Declared-side CNRM machinery a REST payload never echoes (see module doc). */
+const CNRM_ENVELOPE_PATTERNS = new Set(["projectRef", "resourceID"]);
+const CNRM_ANNOTATION_PREFIX = "metadata.annotations.cnrm.cloud.google.com/";
+/** Last dotted segment of a path pattern — `spec.foo.etag` -> `etag`. */
+function lastSegment(pattern) {
+    const i = pattern.lastIndexOf(".");
+    return i === -1 ? pattern : pattern.slice(i + 1);
+}
+/** A `{}` with nothing pruned out of it, as GCP returns for an unset message. */
+function isEmptyObject(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0);
+}
+/**
+ * GCP's static deep-observation noise rules, applied by core to the declared
+ * tree and the live tree alike so the two are compared in the same shape.
+ */
+export const gcpDeepNormalizationHooks = {
+    prune(node) {
+        // Server-assigned, wherever it appears, on either side.
+        if (GCP_READ_ONLY_NAMES.has(lastSegment(node.pattern)))
+            return true;
+        // chant's own ownership marker is not drift (see the set's doc).
+        if (CHANT_OWNERSHIP_LABEL_PATTERNS.has(node.pattern))
+            return true;
+        // CNRM machinery on the declared side: instructions to the controller, not
+        // resource state, and no REST payload ever carries them.
+        if (CNRM_ENVELOPE_PATTERNS.has(node.pattern))
+            return true;
+        if (node.pattern.startsWith(CNRM_ANNOTATION_PREFIX))
+            return true;
+        // Everything below subtracts provider-populated values from the live tree,
+        // and only where source never declared the property. `counterpart` is a
+        // tri-state; only `absent` licenses it.
+        if (node.side !== "live" || node.counterpart !== "absent")
+            return false;
+        // An undeclared `null` or `{}` is GCP's spelling of "unset" — a field the
+        // API includes in the payload without there being any configuration in it
+        // (a service account's `description: null`, Cloud Run's
+        // `binaryAuthorization: {}`).
+        if (node.value === null || isEmptyObject(node.value))
+            return true;
+        const kindDefaults = GCP_SERVICE_DEFAULTS[shortKind(node.entityType)];
+        if (!kindDefaults)
+            return false;
+        return Object.prototype.hasOwnProperty.call(kindDefaults, node.pattern) && kindDefaults[node.pattern] === node.value;
+    },
+};
+/**
+ * `GCP::Pubsub::Topic` -> `PubSubTopic`, the key `GCP_SERVICE_DEFAULTS` uses —
+ * the CNRM kind, resolved through the serializer's GVK map because the naive
+ * `${service}${shortKind}` concatenation miscases 4 of the 6 appliable kinds
+ * (`PubsubTopic`, `IamServiceAccount`, …) and silently matches no defaults.
+ */
+function shortKind(entityType) {
+    const resolved = resolveGVK(entityType);
+    if (resolved)
+        return resolved.kind;
+    const parts = entityType.split("::");
+    return parts.length === 3 ? `${parts[1]}${parts[2]}` : entityType;
+}

package/dist/deep-observe.js

@@ -0,0 +1,273 @@
+/**
+ * GCP deep observation (#1087, re-landed on direct REST by #1209/#1210) — the
+ * GCP row of the deep-observe contract (#1014).
+ *
+ * ## The reader is the applier's transport, pointed at reads
+ *
+ * chant applies GCP cluster-free over direct REST (#706), and since #1209 it
+ * observes the same way: every GET here is built by the same
+ * `ResourceMapper.plan().getUrl` the applier writes through (see
+ * ./api/read-client.ts), so reader and applier cannot disagree about where a
+ * resource lives. `GCP_ENDPOINT_URL` redirects the whole reader at a local
+ * floci-gcp; unset means real GCP, exactly as it does for the applier.
+ * Coverage is the applier's own dispatch table — a kind with no mapper cannot
+ * be applied either, and reports NOT-OBSERVED with `unsupported-kind` (#1089)
+ * rather than being dropped.
+ *
+ * ## Two shapes, one diff
+ *
+ * The declared side is a CNRM spec as a declarable authors it (`{ metadata:
+ * { name }, location, storageClass }`); the REST APIs return their own shapes
+ * (`name` is usually the full resource path, a bucket's `iamConfiguration`
+ * nests what CNRM flattens, a subscription's `topic` is a path where CNRM
+ * writes `topicRef`). Diffed raw, every such field drifts twice: once as
+ * `declared -> <absent>` and once as `<undeclared> -> live`.
+ * {@link restToCnrmShape} plus the per-kind {@link CNRM_REFINERS} put the live
+ * payload into the declared vocabulary before the diff runs — the same move
+ * the AWS row makes with its per-type `toModel` (#1207/#1269), and it lives
+ * next to the read for the same reason: translation is the price of the
+ * richer read, and it does not belong inside the diff.
+ *
+ * ## Noise is a static table, not an ownership walk
+ *
+ * The kubectl-era reader pruned by CNRM `metadata.managedFields`. A REST
+ * payload never says who wrote a field, so the noise rules are static
+ * (./deep-observe-hooks.ts): server-assigned names, chant's own ownership
+ * labels, CNRM-only declared fields, and per-kind provider defaults gated on
+ * "source never declared it". Core applies the same hooks to both trees.
+ *
+ * Since #2160 part of that table has a substrate-independent answer behind it:
+ * core derives a claimed-field set from the declaration's own props, and a
+ * live value on a path outside it is reported as unclaimed rather than as
+ * drift. The table is not obsolete — `prune` is still the right tool for a
+ * field GCP populates on every object of a kind, and for putting the two trees
+ * in the same vocabulary — but the entries that exist only to say "nobody
+ * declared this" now have a general mechanism underneath them.
+ *
+ * ## The build-path boundary
+ *
+ * `gcpPlugin.ts` reaches this file only via `await import("./deep-observe.js")`
+ * inside `observeResourcesDeep` — never statically — so `chant build` never
+ * resolves the live transport just to synthesize a template.
+ * `deepNormalizationHooks` is plain data (./deep-observe-hooks.ts) and is
+ * imported statically from `plugin.ts`, because core normalizes the
+ * *declared* tree with it whether or not a live read ever happens.
+ */
+import { deepObservation, normalizeDeepProperties } from "@intentius/chant/deep-observation";
+import { hasOwnershipMarker } from "@intentius/chant/ownership";
+import { deriveGVK, manifestProjectAnnotations, resolveReadProject } from "./describe-resources.js";
+import { getResource, mapperForKind, GcpReadError, isNotFound } from "./api/read-client.js";
+import { gcpDeepNormalizationHooks } from "./deep-observe-hooks.js";
+/** The labels the applier stamps — see describe-resources.ts. */
+const GCP_OWNERSHIP_LABEL_KEYS = {
+    managedBy: "managed-by",
+    stack: "chant-stack",
+    env: "chant-env",
+};
+// Re-exported so a dynamic importer of this module (plugin.ts's
+// `observeResourcesDeep`, a test) can get the reader and its hooks from one
+// place. `plugin.ts`'s own `deepNormalizationHooks` field imports the hooks
+// separately, directly from `./deep-observe-hooks` — see the module doc.
+export { gcpDeepNormalizationHooks };
+/**
+ * Reshape a GCP REST body into the shape the declared props are written in:
+ * identity and labels under `metadata`, everything else at the root — a CNRM
+ * spec as a chant declarable authors it (`new StorageBucket({ metadata,
+ * location, storageClass })`). Kind-specific vocabulary differences on top of
+ * it are {@link CNRM_REFINERS}' job. Verified against floci-gcp: diffed raw, a
+ * bucket that matched its declaration exactly reported every field as drift
+ * twice, once per shape.
+ */
+export function restToCnrmShape(body) {
+    const metadata = {};
+    const rest = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (key === "name" || key === "labels" || key === "annotations")
+            metadata[key] = value;
+        else
+            rest[key] = value;
+    }
+    return {
+        ...(Object.keys(metadata).length ? { metadata } : {}),
+        ...rest,
+    };
+}
+/** The live payload minus the fields that live outside `properties` on
+ * {@link DeepResourceObservation}. A REST body has no `apiVersion`, but `kind`
+ * shows up on some (GCS returns `storage#bucket`), so both are dropped. */
+function propertiesTreeOf(obj) {
+    const { apiVersion: _apiVersion, kind: _kind, ...rest } = obj;
+    return rest;
+}
+/**
+ * Per-kind REST -> CNRM vocabulary mapping, applied after the generic
+ * {@link restToCnrmShape}. Each entry translates exactly the fields where the
+ * REST API and the CNRM schema disagree about names or nesting — kept next to
+ * the kind, like the applier's forward mapping in gcp-apply.ts, so adding a
+ * field means touching one kind in one file per direction.
+ */
+const CNRM_REFINERS = {
+    StorageBucket(tree) {
+        // CNRM flattens GCS's `iamConfiguration` envelope.
+        const iam = tree.iamConfiguration;
+        if (iam) {
+            if (iam.uniformBucketLevelAccess?.enabled !== undefined) {
+                tree.uniformBucketLevelAccess = iam.uniformBucketLevelAccess.enabled;
+            }
+            if (iam.publicAccessPrevention !== undefined)
+                tree.publicAccessPrevention = iam.publicAccessPrevention;
+            delete tree.iamConfiguration;
+        }
+        // `lifecycle.rule` -> `lifecycleRule`, the inverse of bucketInsertBody.
+        const lifecycle = tree.lifecycle;
+        if (lifecycle) {
+            if (lifecycle.rule !== undefined)
+                tree.lifecycleRule = lifecycle.rule;
+            delete tree.lifecycle;
+        }
+    },
+    PubSubSubscription(tree, ctx) {
+        const topic = tree.topic;
+        if (typeof topic !== "string")
+            return;
+        // The declared side writes a `topicRef`; a same-project path maps to the
+        // `name` form the manifest overwhelmingly uses, anything else to `external`.
+        const prefix = `projects/${ctx.project}/topics/`;
+        tree.topicRef = topic.startsWith(prefix) ? { name: topic.slice(prefix.length) } : { external: topic };
+        delete tree.topic;
+    },
+    SecretManagerSecret(tree) {
+        // CNRM spells automatic replication as a boolean; the REST API as `{}`.
+        const replication = tree.replication;
+        if (replication && typeof replication.automatic === "object" && replication.automatic !== null) {
+            replication.automatic = true;
+        }
+    },
+    IAMServiceAccount(tree, ctx) {
+        // The REST identity is the derived email; the declared name is the account
+        // id it was derived from (see gcpServiceAccountMapper).
+        const name = tree.metadata?.name;
+        if (typeof name === "string" && name.endsWith(`@${ctx.project}.iam.gserviceaccount.com`)) {
+            tree.metadata.name = name.slice(0, name.indexOf("@"));
+        }
+    },
+    RunService(tree, ctx) {
+        // The v2 payload carries no `location` field — it lives in the resource
+        // name. The declared side writes it as `location`.
+        const m = ctx.restName ? /\/locations\/([^/]+)\//.exec(ctx.restName) : null;
+        if (m)
+            tree.location = m[1];
+    },
+};
+/**
+ * A REST payload as a CNRM-shaped property tree, in the declared side's
+ * vocabulary. The generic reshape runs first, then the full resource path is
+ * shortened to the declared `metadata.name` (`projects/p/topics/t` -> `t`),
+ * then the kind's own refiner translates what the two schemas name
+ * differently.
+ */
+export function toCnrmTree(kind, body, ctx) {
+    const tree = restToCnrmShape(propertiesTreeOf(body));
+    const restName = typeof body.name === "string" ? body.name : undefined;
+    const name = tree.metadata?.name;
+    if (typeof name === "string" && name.includes("/")) {
+        tree.metadata.name = name.slice(name.lastIndexOf("/") + 1);
+    }
+    CNRM_REFINERS[kind]?.(tree, { ...ctx, restName });
+    return tree;
+}
+/**
+ * Read the live property tree for each declared entity over the applier's
+ * REST transport, normalized into the declared CNRM shape (see the module
+ * doc). A connect failure becomes NOT-OBSERVED for every declared entity
+ * rather than an empty result, and a 404 is a real absence the thin read
+ * already reports.
+ */
+export async function observeResourcesDeepGcp(options) {
+    const resources = {};
+    const unobserved = {};
+    const endpoint = process.env.GCP_ENDPOINT_URL;
+    const manifestProjects = manifestProjectAnnotations(options.buildOutput);
+    const reads = [...options.entities].map(async ([entityName, { entityType, props }]) => {
+        const gvk = deriveGVK(entityType);
+        if (!gvk || !mapperForKind(gvk.kind)) {
+            unobserved[entityName] = {
+                type: entityType,
+                reason: "unsupported-kind",
+                detail: gvk
+                    ? `no REST mapper for ${gvk.kind} — chant cannot apply this kind either`
+                    : `cannot derive a GCP kind from ${entityType}`,
+            };
+            return;
+        }
+        const metadata = props.metadata;
+        const name = metadata?.name;
+        if (!name) {
+            unobserved[entityName] = {
+                type: entityType,
+                reason: "read-failed",
+                detail: "declared entity has no metadata.name to query by",
+            };
+            return;
+        }
+        let client;
+        try {
+            client = {
+                project: resolveReadProject(gvk.kind, name, metadata, manifestProjects),
+                ...(endpoint ? { endpoint } : {}),
+            };
+        }
+        catch (err) {
+            unobserved[entityName] = {
+                type: entityType,
+                reason: "no-binding",
+                detail: err instanceof Error ? err.message : String(err),
+            };
+            return;
+        }
+        try {
+            const obj = await getResource(client, gvk.kind, name, props);
+            const labels = obj.labels;
+            // owned filter: withhold what does not carry chant's marker. Withheld is
+            // not absent (#1089). Where the payload has no labels at all there is
+            // nothing to filter on, so the resource passes through — the same
+            // detect-only degradation the thin path takes.
+            if (options.owned && labels != null && !hasOwnershipMarker(labels, GCP_OWNERSHIP_LABEL_KEYS)) {
+                unobserved[entityName] = {
+                    type: entityType,
+                    reason: "filtered",
+                    detail: "live resource carries no chant ownership marker and --owned was requested",
+                };
+                return;
+            }
+            resources[entityName] = {
+                type: entityType,
+                physicalId: obj.id ?? obj.selfLink ?? obj.name,
+                properties: normalizeDeepProperties(toCnrmTree(gvk.kind, obj, { project: client.project }), {
+                    entityType,
+                    side: "live",
+                    // The static table is the whole prune here — there is no per-resource
+                    // ownership pass, because a REST payload carries no field ownership
+                    // to drive one (see ./deep-observe-hooks.ts). What the payload cannot
+                    // say, the declaration does: core classifies against the claimed-field
+                    // set above this reader (#2160).
+                    hooks: gcpDeepNormalizationHooks,
+                }),
+            };
+        }
+        catch (err) {
+            // A 404 is a real absence, same as the thin read — recorded there, not
+            // restated here. Anything else proves nothing and is a hole (#1089).
+            if (isNotFound(err))
+                return;
+            const status = err instanceof GcpReadError ? err.status : undefined;
+            unobserved[entityName] = {
+                type: entityType,
+                reason: status === 401 || status === 403 ? "no-credentials" : "read-failed",
+                detail: err instanceof Error ? err.message : String(err),
+            };
+        }
+    });
+    await Promise.all(reads);
+    return deepObservation(resources, unobserved);
+}

package/dist/default-labels.js

@@ -0,0 +1,67 @@
+/**
+ * Default Labels & Annotations — declares project-wide labels/annotations
+ * for all GCP Config Connector resources.
+ *
+ * When a project exports a `defaultLabels(...)` or `defaultAnnotations(...)`
+ * declaration, the serializer automatically injects them into every resource's
+ * metadata at synthesis time. Explicit labels/annotations on individual
+ * resources take precedence.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+export const DEFAULT_LABELS_MARKER = Symbol.for("chant.gcp.defaultLabels");
+export const DEFAULT_ANNOTATIONS_MARKER = Symbol.for("chant.gcp.defaultAnnotations");
+export function isDefaultLabels(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        DEFAULT_LABELS_MARKER in value &&
+        value[DEFAULT_LABELS_MARKER] === true);
+}
+export function isDefaultAnnotations(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        DEFAULT_ANNOTATIONS_MARKER in value &&
+        value[DEFAULT_ANNOTATIONS_MARKER] === true);
+}
+/**
+ * Declare project-wide default labels for all GCP Config Connector resources.
+ *
+ * @example
+ * ```ts
+ * import { defaultLabels } from "@intentius/chant-lexicon-gcp";
+ *
+ * export const labels = defaultLabels({
+ *   "app.kubernetes.io/managed-by": "chant",
+ *   "env": "production",
+ * });
+ * ```
+ */
+export function defaultLabels(labels) {
+    return {
+        [DEFAULT_LABELS_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon: "gcp",
+        entityType: "chant:gcp:defaultLabels",
+        labels,
+    };
+}
+/**
+ * Declare project-wide default annotations for all GCP Config Connector resources.
+ *
+ * @example
+ * ```ts
+ * import { defaultAnnotations, GCP } from "@intentius/chant-lexicon-gcp";
+ *
+ * export const annotations = defaultAnnotations({
+ *   "cnrm.cloud.google.com/project-id": GCP.ProjectId,
+ * });
+ * ```
+ */
+export function defaultAnnotations(annotations) {
+    return {
+        [DEFAULT_ANNOTATIONS_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon: "gcp",
+        entityType: "chant:gcp:defaultAnnotations",
+        annotations,
+    };
+}