typekro 0.26.0 → 0.27.1

package/dist/core/deployment/kro-namespace-teardown.d.ts

@@ -0,0 +1,248 @@
+import type * as k8s from '@kubernetes/client-node';
+import type { TypeKroLogger } from '../logging/types.js';
+/**
+ * Annotation stamped on a hoisted workload Namespace at CREATE time, recording
+ * the RGD that created it — the durable ownership RECORD used by teardown. A
+ * Namespace is a deletion candidate ONLY if it carries this annotation set to
+ * THIS composition's RGD name (i.e. typekro created it for this composition);
+ * an adopted/pre-existing Namespace never carries it and is never deleted.
+ */
+export declare const NAMESPACE_OWNER_ANNOTATION = "typekro.io/created-by-rgd";
+/**
+ * Annotation stamped on the instance CR at DEPLOY time recording the CONCRETE names
+ * of every Namespace this instance hoisted out of the RGD graph (finding #4). Value is
+ * a JSON array of names (e.g. `["team-a","team-a-monitoring"]`). Teardown + the pre-hoist
+ * guard read it back EXACTLY so a hoisted name derived from an ARBITRARY spec field (e.g.
+ * `spec.targetNamespace`) round-trips without re-deriving it from `metadata.namespace` /
+ * `spec.namespace` (which can be wrong for non-1:1 hoists).
+ */
+export declare const HOISTED_NAMESPACES_ANNOTATION = "typekro.io/hoisted-namespaces";
+/**
+ * Parse the {@link HOISTED_NAMESPACES_ANNOTATION} value back into a list of namespace
+ * names. Tolerant: a missing/blank value yields `[]`; a malformed value yields `[]`
+ * (callers decide the fallback). Only string entries are returned.
+ */
+export declare function parseHoistedNamespacesAnnotation(value: string | undefined): string[];
+/**
+ * A richer read of {@link HOISTED_NAMESPACES_ANNOTATION} that DISTINGUISHES three cases the
+ * pre-hoist guard must treat differently:
+ *  - `present` — a valid JSON array, INCLUDING an explicit empty `[]` (the instance hoists zero
+ *    namespaces). This is per-instance PROOF and is SAFE — the guard must NOT fail closed on it.
+ *  - `missing` — no annotation at all: a genuinely-legacy CR predating the record → FAIL CLOSED.
+ *  - `malformed` — present but not a JSON array → FAIL CLOSED.
+ * (Teardown uses {@link parseHoistedNamespacesAnnotation}, where any non-list just means "nothing
+ * to clean" — the missing-vs-empty distinction only matters for the fail-closed guard.)
+ */
+export type HoistedNamespacesRecord = {
+    readonly status: 'present';
+    readonly names: string[];
+} | {
+    readonly status: 'missing';
+} | {
+    readonly status: 'malformed';
+};
+export declare function readHoistedNamespacesRecord(value: string | undefined): HoistedNamespacesRecord;
+/**
+ * The minimal LIST surface used by {@link listNamespacesOwnedByRgd}. {@link
+ * k8s.KubernetesObjectApi} satisfies it; tests inject a mock.
+ */
+export interface NamespaceListApi {
+    list(apiVersion: string, kind: string, namespace?: string, pretty?: string, exact?: boolean, exportt?: boolean, fieldSelector?: string, labelSelector?: string, limit?: number, continueToken?: string): Promise<unknown>;
+}
+/**
+ * List the NAMES of every Namespace carrying {@link NAMESPACE_OWNER_ANNOTATION} == `rgdName`
+ * — the DURABLE, cluster-side record of every workload Namespace typekro created for this RGD.
+ *
+ * Unlike the CR's {@link HOISTED_NAMESPACES_ANNOTATION} (which dies WITH the instance CR), this
+ * record survives the CR, so:
+ *   - a teardown RETRY after the CR is already gone can still FIND + clean the owned
+ *     namespace(s) (and gate the RGD/CRD delete on their cleanup), and
+ *   - the pre-hoist guard can resolve an existing instance's namespaces EXACTLY without
+ *     approximating from `metadata.namespace` / `spec.namespace`.
+ *
+ * Lists cluster-wide (small N in practice) and filters client-side by the ownership
+ * annotation, FOLLOWING the list continuation token so an owned namespace beyond the first
+ * page is never hidden by a silent cap. A list error PROPAGATES (callers fail closed /
+ * preserve): an unreadable list is not proof that no owned namespace exists.
+ */
+export declare function listNamespacesOwnedByRgd(kubeConfig: k8s.KubeConfig, rgdName: string, options?: {
+    k8sApi?: NamespaceListApi;
+    logger?: TypeKroLogger;
+}): Promise<string[]>;
+/**
+ * A namespaced RESOURCE TYPE discovered from the cluster's API surface. `apiVersion`
+ * is the group/version (`v1`, `apps/v1`, `kro.run/v1alpha1`); `kind` is the object
+ * kind used to LIST instances of the type in a namespace.
+ */
+export interface NamespacedResourceType {
+    readonly apiVersion: string;
+    readonly kind: string;
+}
+/**
+ * Discovery + listing surface for the emptiness check, injected so the
+ * classification LOGIC is unit-testable OFFLINE (the maintainer validates real
+ * cluster discovery on OrbStack). The default cluster implementation is
+ * {@link createClusterNamespaceInventory}.
+ */
+export interface NamespaceInventory {
+    /** All NAMESPACED, LISTABLE resource types the cluster currently serves. */
+    discoverNamespacedTypes(): Promise<NamespacedResourceType[]>;
+    /** The names of every object of `type` present in `namespace`. */
+    listObjectNames(type: NamespacedResourceType, namespace: string): Promise<string[]>;
+}
+/**
+ * The verdict of the emptiness gate. `empty: false` ALWAYS carries a human `reason`
+ * — either a real occupant, or an uncertainty (discovery/list error) that fails the
+ * gate toward RETAIN.
+ */
+export type NamespaceEmptinessVerdict = {
+    readonly empty: true;
+} | {
+    readonly empty: false;
+    readonly reason: string;
+};
+/**
+ * Whether an object found in a namespace is a k8s AUTO-PROVISIONED default that does
+ * NOT count as "occupied" — every namespace has these regardless of what a
+ * user/stack put in it:
+ *   - the `default` ServiceAccount,
+ *   - the `kube-root-ca.crt` ConfigMap (the injected cluster CA bundle),
+ *   - `default-token-*` Secrets (older k8s auto-mounted the SA token this way).
+ *
+ * `Event` objects are handled at DISCOVERY time ({@link isEventType}) — they are
+ * transient, controller-generated bookkeeping (a just-drained namespace still holds
+ * deletion Events for up to the event TTL), never a resource a user/stack owns, so
+ * they must not pin an otherwise-empty namespace open. Treating them as occupants
+ * would make the gate almost never fire. This is a deliberate, documented extension
+ * of the brief's three-item default list.
+ *
+ * Keyed by GROUP + kind + name (finding #5): the built-in defaults all live in the
+ * CORE group (`""`). Keying by kind/name alone would wrongly exempt an unrelated CRD
+ * whose kind happened to be `ServiceAccount` / `ConfigMap` / `Secret` in some OTHER
+ * group — a real occupant — from the emptiness gate.
+ */
+export declare function isAutoProvisionedDefault(group: string, kind: string, name: string): boolean;
+/**
+ * Event types — transient, never counted as occupants. Keyed by GROUP + kind (finding
+ * #5): only the CORE-group (`""`) `Event` and the `events.k8s.io` `Event` are exempted,
+ * so an unrelated CRD named `Event` in some OTHER group is still treated as an occupant.
+ */
+export declare function isEventType(group: string, kind: string): boolean;
+/**
+ * Classify whether `namespace` is EMPTY (safe to delete) by enumerating every
+ * namespaced resource type via discovery and listing each in the namespace. Returns
+ * `empty: true` ONLY when nothing but k8s auto-provisioned defaults is present.
+ *
+ * FAIL SAFE (finding #3 + #4): on ANY uncertainty — discovery error, a per-type list
+ * error, or an unexpected occupant — the verdict is `empty: false` (RETAIN). Deleting
+ * an occupied namespace is high harm; retaining an empty one is low harm, so every
+ * ambiguity resolves toward RETAIN.
+ */
+export declare function classifyNamespaceEmptiness(inventory: NamespaceInventory, namespace: string, logger?: TypeKroLogger): Promise<NamespaceEmptinessVerdict>;
+/**
+ * The OWNERSHIP-gated + EMPTY-gated delete (findings #3 + #4), shared by BOTH the
+ * imperative `deleteInstance` path and the Alchemy teardown handler.
+ *
+ * ORDER: this runs AFTER the instance CR is gone (KRO has graph-deleted every child)
+ * but BEFORE the RGD/CRD teardown — the current teardown order is CR → namespace →
+ * RGD → CRD (the generated CRD is torn down LAST). Deleting the namespace while the
+ * RGD + CRD are still HEALTHY/Active is deliberate: the namespace controller confirms
+ * emptiness instantly and can never terminate against a *Terminating* CRD (upstream
+ * kro #1171). Never scans-and-deletes arbitrary namespaces: the caller passes exactly
+ * the namespace THIS instance declared/hoisted.
+ *
+ * TWO GATES, ownership PRIMARY: with `ownedByRgd` set (both callers pass it), the
+ * namespace is deleted ONLY if it carries {@link NAMESPACE_OWNER_ANNOTATION} equal to
+ * this RGD (typekro CREATED it) AND is empty. An ADOPTED/undeclared namespace (no
+ * matching stamp) is RETAINED — never deleted — as is one another stack/user still
+ * OCCUPIES (non-empty) or one that cannot be read (fail-safe retain).
+ *
+ * GATED (not best-effort): a pre-delete 404 is benign (already gone), but the delete
+ * itself polls to a real 404 and THROWS {@link DeploymentTimeoutError} on timeout — a
+ * stuck namespace finalizer surfaces as an error, never a silently-abandoned
+ * Terminating namespace. (The generated-CRD delete, a LATER step in `deleteInstance`,
+ * is the only best-effort deletion — see {@link KroResourceFactoryImpl.deleteInstance}.)
+ */
+export declare function deleteNamespaceIfEmpty(kubeConfig: k8s.KubeConfig, namespace: string, options?: {
+    logger?: TypeKroLogger;
+    inventory?: NamespaceInventory;
+    k8sApi?: Pick<k8s.KubernetesObjectApi, 'read' | 'delete'>;
+    context?: Record<string, unknown>;
+    /**
+     * When set, delete ONLY if the live Namespace carries
+     * {@link NAMESPACE_OWNER_ANNOTATION} equal to this value (typekro created it
+     * for this composition's RGD). An adopted/undeclared Namespace — no matching
+     * ownership annotation — is RETAINED. This is the PRIMARY ownership guard;
+     * emptiness below is the secondary safety net.
+     */
+    ownedByRgd?: string;
+    /** Bound for the gated delete (poll to a real 404, throw on timeout). */
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * The create-first API surface: an atomic CREATE (POST) plus a READ used only to
+ * classify a pre-existing namespace on conflict. {@link k8s.KubernetesObjectApi}
+ * satisfies this; tests inject a mock.
+ */
+export interface NamespaceCreateFirstApi {
+    create(resource: k8s.KubernetesObject, pretty?: string, dryRun?: string, fieldManager?: string): Promise<unknown>;
+    read(resource: {
+        apiVersion: string;
+        kind: string;
+        metadata: {
+            name: string;
+        };
+    }): Promise<unknown>;
+}
+/** Verdict of {@link decideNamespaceOwnershipCreateFirst}. */
+export interface NamespaceOwnershipDecision {
+    /** True IFF our CREATE returned 201 — i.e. WE created the namespace this call. */
+    readonly created: boolean;
+    /**
+     * True IFF typekro (this RGD) owns the namespace: it either created it now (`created`)
+     * or a PRIOR create by this RGD stamped it (matching {@link NAMESPACE_OWNER_ANNOTATION}).
+     * A namespace merely ADOPTED (created by someone else) is `owned: false`.
+     */
+    readonly owned: boolean;
+}
+/**
+ * ATOMIC ownership decision via CREATE-FIRST (finding #3), shared by the imperative and
+ * alchemy deploy paths. The old GET→(if 404)→SSA-patch-with-owner-stamp was raceable:
+ * another actor creating the namespace between the GET and the patch let typekro ADOPT
+ * it yet stamp it owned — and later DELETE it. Instead:
+ *
+ *   1. Attempt to CREATE the namespace (POST) WITH the ownership stamp. A 201 is proof
+ *      WE created it → we own it (ownership is atomic: owned IFF we created it).
+ *   2. On 409 (already exists) it is NOT ours to claim by this call. READ it and treat
+ *      it as owned ONLY if it already carries THIS RGD's stamp (a prior create by us);
+ *      otherwise it is ADOPTED (`owned: false`). This 409-read is race-free for the
+ *      ownership decision because ownership was fixed at the original 201-create.
+ *   3. Any OTHER create error is rethrown for the caller to handle (fail loud).
+ *
+ * `manifestWithStamp` MUST already carry {@link NAMESPACE_OWNER_ANNOTATION} = `ownerRgd`
+ * plus the complete declared namespace config, so a 201 lands the full config atomically.
+ */
+export declare function decideNamespaceOwnershipCreateFirst(api: NamespaceCreateFirstApi, manifestWithStamp: k8s.KubernetesObject, ownerRgd: string, fieldManager?: string): Promise<NamespaceOwnershipDecision>;
+/**
+ * Default {@link NamespaceInventory} backed by the live cluster. Discovery enumerates
+ * EVERY served API group DYNAMICALLY — the core group via `CoreV1Api.getAPIResources()`
+ * and every other served group via `CustomObjectsApi.getAPIResources(group, version)`
+ * (the generic per-group discovery endpoint, `GET /apis/{group}/{version}`) — all
+ * through the Bun-compatible client wrappers (no raw HTTP; identical under Bun and Node).
+ * This covers built-in AND custom (CRD) namespaced kinds uniformly, since a CRD's group
+ * appears in the served-group list. Listing uses `KubernetesObjectApi.list(apiVersion,
+ * kind, namespace)` and FOLLOWS the list continuation token so a namespace with more
+ * objects than one page never hides an occupant behind a silent cap (finding #5b).
+ *
+ * COVERAGE / UNCERTAINTY (finding #5a): the emptiness gate is a SECONDARY backstop
+ * (ownership is the PRIMARY teardown guard), so it must never misclassify occupied as
+ * empty. If the cluster serves a namespaced group this inventory CANNOT enumerate — for
+ * ANY reason: a native group whose discovery call fails, or an aggregated APIService
+ * whose external backend is unreachable — discovery THROWS an uncertainty error, which
+ * {@link classifyNamespaceEmptiness} turns into a fail-safe RETAIN. The ONLY groups
+ * deliberately skipped are the ephemeral metrics aggregation groups (their samples are
+ * never persistent occupants). There is no native-vs-aggregated distinction: anything we
+ * can't enumerate is uncertainty.
+ */
+export declare function createClusterNamespaceInventory(kubeConfig: k8s.KubeConfig): NamespaceInventory;
+//# sourceMappingURL=kro-namespace-teardown.d.ts.map

package/dist/core/deployment/kro-namespace-teardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kro-namespace-teardown.d.ts","sourceRoot":"","sources":["../../../src/core/deployment/kro-namespace-teardown.ts"],"names":[],"mappings":"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"}