@intentius/chant-k8s-client 0.31.0 → 0.32.0

package/src/conflict.ts

@@ -0,0 +1,257 @@
+/**
+ * The server-side-apply conflict surface — chant #1075.
+ *
+ * When an apply touches a field another manager owns, the API server refuses
+ * with a 409 and — unlike almost every other Kubernetes failure — tells you
+ * precisely what went wrong: which fields, and who owns each one. It arrives as
+ * a `Status` whose `details.causes` is a list of `FieldManagerConflict` entries:
+ *
+ * ```json
+ * { "reason": "Conflict", "code": 409,
+ *   "message": "Apply failed with 2 conflicts: conflicts with \"kubectl\" ...",
+ *   "details": { "causes": [
+ *     { "type": "FieldManagerConflict", "message": "conflict with \"kubectl\"",
+ *       "field": ".spec.replicas" } ] } }
+ * ```
+ *
+ * chant #1074 already carried that through as a typed `K8sApiError` with
+ * `conflict === true`. What was missing is the presentation: a 409 whose
+ * message is one run-on line is not something an operator can act on, and the
+ * thing they must not do — force it because the error suggested nothing else —
+ * is exactly what a bad message invites.
+ *
+ * So this error names the competing manager, lists the contested paths under
+ * it, says what forcing would mean, and stops there. **chant never forces a
+ * conflict on its own.** Taking a field from another manager is a decision
+ * about who owns production, and a tool that makes it silently is the reason
+ * "it works on my cluster" happens. The opt-in exists (`force`), it is never
+ * the default, and nothing in chant turns it on for you.
+ */
+
+import { K8sApiError, type K8sStatus } from "./errors";
+
+/** One contested field: a path, and the manager that owns it. */
+export interface FieldConflict {
+  /** The manager that currently owns the field, e.g. `kubectl`, `helm`. */
+  manager: string;
+  /**
+   * The field path, in the same syntax `./managed-fields.ts` renders — e.g.
+   * `.spec.replicas`, `.spec.template.spec.containers[name="web"].image`.
+   */
+  field: string;
+  /** The apiVersion the owning entry was recorded at, when the server said. */
+  apiVersion?: string;
+}
+
+/**
+ * A server-side apply was refused because another field manager owns fields
+ * this apply would set.
+ *
+ * Extends {@link K8sApiError} so every existing `instanceof K8sApiError` check
+ * (and the `conflict` predicate) keeps working — this is a presentation of the
+ * 409, not a replacement for it.
+ */
+export class FieldManagerConflictError extends K8sApiError {
+  /** Every contested field, in the order the server reported them. */
+  public readonly conflicts: FieldConflict[];
+  /** The field manager chant applied as, and which was refused. */
+  public readonly fieldManager: string;
+
+  constructor(
+    statusCode: number,
+    apiMessage: string,
+    conflicts: FieldConflict[],
+    fieldManager: string,
+    target?: string,
+    status?: K8sStatus,
+  ) {
+    super(statusCode, status?.reason ?? "Conflict", apiMessage, target, status);
+    this.name = "FieldManagerConflictError";
+    this.conflicts = conflicts;
+    this.fieldManager = fieldManager;
+    // Message is assembled after the fields exist, since it renders them.
+    this.message = renderConflictReport({ conflicts, fieldManager, target, apiMessage });
+  }
+
+  /** Contested paths grouped by the manager that owns them, managers sorted. */
+  get byManager(): Record<string, string[]> {
+    const grouped: Record<string, string[]> = {};
+    for (const conflict of this.conflicts) {
+      (grouped[conflict.manager] ??= []).push(conflict.field);
+    }
+    return Object.fromEntries(
+      Object.entries(grouped)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([manager, fields]) => [manager, [...fields].sort()]),
+    );
+  }
+
+  /** The competing managers, sorted. */
+  get managers(): string[] {
+    return Object.keys(this.byManager);
+  }
+
+  /** The contested paths, sorted and deduplicated. */
+  get fields(): string[] {
+    return [...new Set(this.conflicts.map((c) => c.field))].sort();
+  }
+}
+
+/** Inputs {@link renderConflictReport} needs; broken out so tests can render directly. */
+export interface ConflictReport {
+  conflicts: FieldConflict[];
+  fieldManager: string;
+  target?: string;
+  /** The server's own message, used verbatim when nothing could be parsed. */
+  apiMessage?: string;
+}
+
+/**
+ * The operator-facing rendering. Three things, in this order: what is
+ * contested and who holds it, what chant applied as, and what the two ways out
+ * actually mean. No recommendation between them — that is the point.
+ */
+export function renderConflictReport(report: ConflictReport): string {
+  const { conflicts, fieldManager, target } = report;
+  const subject = target ? `${target}` : "this object";
+
+  if (conflicts.length === 0) {
+    return (
+      `k8s: server-side apply of ${subject} was refused with a field-ownership conflict, but the ` +
+      `API server reported no field causes${report.apiMessage ? ` — it said: ${report.apiMessage}` : ""}. ` +
+      `chant applied as field manager "${fieldManager}".`
+    );
+  }
+
+  const grouped = new Map<string, string[]>();
+  for (const conflict of conflicts) {
+    const list = grouped.get(conflict.manager) ?? [];
+    if (!list.includes(conflict.field)) list.push(conflict.field);
+    grouped.set(conflict.manager, list);
+  }
+
+  const count = new Set(conflicts.map((c) => c.field)).size;
+  const lines = [
+    `k8s: server-side apply of ${subject} was refused — ` +
+      `${count} ${count === 1 ? "field is" : "fields are"} owned by another field manager.`,
+    "",
+  ];
+  for (const [manager, fields] of [...grouped].sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`  "${manager}" owns:`);
+    for (const field of [...fields].sort()) lines.push(`    ${field}`);
+  }
+  lines.push(
+    "",
+    `chant applied as field manager "${fieldManager}". Taking these fields means the managers above`,
+    `stop owning them, and will contest them again on their next apply.`,
+    "",
+    "chant does not force this for you. Either:",
+    "  - remove the contested fields from your chant source, leaving them to their current owner; or",
+    "  - re-run this apply with force-conflicts on, deliberately (the `force: true` activity argument,",
+    "    or `forceConflicts: true` on ApplyOp), which transfers ownership to chant.",
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Pull the field causes out of a 409 `Status`.
+ *
+ * `details.causes` is the machine-readable form and is preferred. Not every
+ * server fills it in — an aggregated API server or an older release puts the
+ * same information only in the prose `message` — so the message is parsed as a
+ * fallback rather than the list being reported as empty.
+ */
+export function parseFieldConflicts(status: K8sStatus | undefined, message?: string): FieldConflict[] {
+  const fromCauses = causesOf(status);
+  if (fromCauses.length > 0) return fromCauses;
+  return parseConflictMessage(message ?? status?.message ?? "");
+}
+
+interface StatusCause {
+  type?: string;
+  message?: string;
+  field?: string;
+}
+
+function causesOf(status: K8sStatus | undefined): FieldConflict[] {
+  const details = status?.details;
+  if (!details || typeof details !== "object") return [];
+  const causes = (details as { causes?: unknown }).causes;
+  if (!Array.isArray(causes)) return [];
+  const out: FieldConflict[] = [];
+  for (const raw of causes as StatusCause[]) {
+    if (!raw || typeof raw !== "object") continue;
+    if (raw.type !== undefined && raw.type !== "FieldManagerConflict") continue;
+    const field = typeof raw.field === "string" ? raw.field : undefined;
+    if (!field) continue;
+    const { manager, apiVersion } = parseCauseMessage(raw.message ?? "");
+    out.push({
+      manager: manager ?? "an unnamed manager",
+      field,
+      ...(apiVersion ? { apiVersion } : {}),
+    });
+  }
+  return out;
+}
+
+/** `conflict with "kubectl" using apps/v1` → manager + apiVersion. */
+function parseCauseMessage(message: string): { manager?: string; apiVersion?: string } {
+  const manager = /conflicts? with "([^"]+)"/.exec(message)?.[1];
+  const apiVersion = /\busing ([^\s:]+)\b/.exec(message)?.[1];
+  return { ...(manager ? { manager } : {}), ...(apiVersion ? { apiVersion } : {}) };
+}
+
+/**
+ * Parse the prose form, which the server builds as one `conflicts with "x"`
+ * clause per manager followed by that manager's fields as a `-` list:
+ *
+ * ```
+ * Apply failed with 2 conflicts: conflicts with "kubectl" using apps/v1:
+ * - .spec.replicas
+ * - .spec.template.spec.containers[name="web"].image
+ * ```
+ */
+export function parseConflictMessage(message: string): FieldConflict[] {
+  if (!message) return [];
+  const out: FieldConflict[] = [];
+  let manager: string | undefined;
+  let apiVersion: string | undefined;
+
+  for (const rawLine of message.split("\n")) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+
+    const header = /conflicts? with "([^"]+)"(?: using ([^\s:]+))?/.exec(line);
+    if (header) {
+      manager = header[1];
+      apiVersion = header[2];
+      // Single-conflict messages inline the field: `... with "kubectl": .spec.replicas`
+      const inline = /:\s*(\.[^\s]+)$/.exec(line);
+      if (inline) out.push({ manager, field: inline[1], ...(apiVersion ? { apiVersion } : {}) });
+      continue;
+    }
+
+    const bullet = /^-\s*(\S.*)$/.exec(line);
+    if (bullet && manager) {
+      out.push({ manager, field: bullet[1].trim(), ...(apiVersion ? { apiVersion } : {}) });
+    }
+  }
+  return out;
+}
+
+/**
+ * Turn a 409 from an apply into the presented error. Any other failure is
+ * returned unchanged — this is a narrowing, not a catch-all.
+ */
+export function asFieldManagerConflict(error: unknown, fieldManager: string): unknown {
+  if (!(error instanceof K8sApiError) || !error.conflict) return error;
+  if (error instanceof FieldManagerConflictError) return error;
+  return new FieldManagerConflictError(
+    error.statusCode,
+    error.apiMessage,
+    parseFieldConflicts(error.status, error.apiMessage),
+    fieldManager,
+    error.target,
+    error.status,
+  );
+}

package/src/errors.ts

@@ -56,7 +56,11 @@ export class K8sApiError extends Error {
     return this.statusCode === 401 || this.reason === "Unauthorized";
   }
 
-  /** Server-side-apply field-ownership conflict (chant #1075 surfaces these properly). */
+  /**
+   * Server-side-apply field-ownership conflict. `./conflict.ts`'s
+   * {@link import("./conflict").FieldManagerConflictError} is the presented
+   * form (chant #1075); this predicate still answers for both.
+   */
   get conflict(): boolean {
     return this.statusCode === 409 || this.reason === "Conflict";
   }
@@ -138,6 +142,19 @@ export class ExecCredentialNotAllowedError extends Error {
   }
 }
 
+/**
+ * chant's own field-manager identity is unusable (chant #1075) — almost always
+ * because `ownership.stack` is too long or carries whitespace. Raised where the
+ * name is derived, before any request, so the config key can be named instead
+ * of the failure arriving as a 400 from a cluster.
+ */
+export class FieldManagerError extends Error {
+  constructor(message: string) {
+    super(`k8s: ${message}`);
+    this.name = "FieldManagerError";
+  }
+}
+
 /** The kubeconfig could not be read, or names no usable cluster/context. */
 export class KubeConfigError extends Error {
   constructor(message: string) {

package/src/field-manager.test.ts

@@ -0,0 +1,110 @@
+/**
+ * chant's field-manager identity (chant #1075).
+ *
+ * The scheme is small enough to state in one line — `chant`, or `chant:<stack>`
+ * — so what is worth testing is the edges: that it is derived from the same
+ * `ownership.stack` the label marker uses, that it round-trips, and that an
+ * identity the API server would reject fails here, where the config key
+ * responsible can be named.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  CHANT_FIELD_MANAGER,
+  FIELD_MANAGER_MAX_LENGTH,
+  assertValidFieldManager,
+  chantStackOf,
+  fieldManagerFor,
+  isChantFieldManager,
+} from "./field-manager";
+import { FieldManagerError } from "./errors";
+
+describe("fieldManagerFor", () => {
+  test("no ownership stack yields the bare chant", () => {
+    expect(fieldManagerFor()).toBe("chant");
+    expect(fieldManagerFor({})).toBe("chant");
+    expect(fieldManagerFor({ stack: "" })).toBe("chant");
+    expect(fieldManagerFor({ stack: "   " })).toBe("chant");
+  });
+
+  test("a stack qualifies it — the identity the ownership label already carries", () => {
+    expect(fieldManagerFor({ stack: "web" })).toBe("chant:web");
+    expect(fieldManagerFor({ stack: "platform-prod" })).toBe("chant:platform-prod");
+  });
+
+  test("two stacks on one cluster are two managers, which is the point", () => {
+    expect(fieldManagerFor({ stack: "a" })).not.toBe(fieldManagerFor({ stack: "b" }));
+  });
+
+  test("it is stable — the same stack derives the same manager every time", () => {
+    expect(fieldManagerFor({ stack: "web" })).toBe(fieldManagerFor({ stack: "web" }));
+  });
+
+  test("surrounding whitespace is trimmed rather than baked into the identity", () => {
+    expect(fieldManagerFor({ stack: "  web  " })).toBe("chant:web");
+  });
+});
+
+describe("recognising chant's own managers", () => {
+  test("qualified and unqualified are both chant's", () => {
+    expect(isChantFieldManager("chant")).toBe(true);
+    expect(isChantFieldManager("chant:web")).toBe(true);
+  });
+
+  test("another tool's manager is not, and neither is a lookalike prefix", () => {
+    for (const other of ["kubectl", "helm", "argo-controller", "chanted", "chant-ish", "", undefined]) {
+      expect(isChantFieldManager(other)).toBe(false);
+    }
+  });
+
+  test("the stack round-trips out of the manager", () => {
+    expect(chantStackOf(fieldManagerFor({ stack: "web" }))).toBe("web");
+    expect(chantStackOf("chant")).toBeUndefined();
+    expect(chantStackOf("kubectl")).toBeUndefined();
+    expect(chantStackOf(undefined)).toBeUndefined();
+  });
+
+  test("a stack containing the separator still round-trips whole", () => {
+    const manager = fieldManagerFor({ stack: "team:web" });
+    expect(manager).toBe("chant:team:web");
+    expect(chantStackOf(manager)).toBe("team:web");
+  });
+});
+
+describe("identities the API server would reject fail here instead", () => {
+  test("over the length ceiling, naming the config key", () => {
+    const stack = "s".repeat(FIELD_MANAGER_MAX_LENGTH);
+    const err = (() => {
+      try {
+        fieldManagerFor({ stack });
+        return undefined;
+      } catch (e) {
+        return e;
+      }
+    })();
+    expect(err).toBeInstanceOf(FieldManagerError);
+    expect(String(err)).toContain("ownership.stack");
+    expect(String(err)).toContain(String(FIELD_MANAGER_MAX_LENGTH));
+  });
+
+  test("an interior space, which would otherwise arrive as a 400 from a cluster", () => {
+    expect(() => fieldManagerFor({ stack: "web prod" })).toThrow(FieldManagerError);
+  });
+
+  test("a control character", () => {
+    expect(() => fieldManagerFor({ stack: `web${String.fromCharCode(9)}prod` })).toThrow(FieldManagerError);
+  });
+
+  test("an explicitly supplied manager is checked the same way", () => {
+    expect(() => assertValidFieldManager("")).toThrow(FieldManagerError);
+    expect(() => assertValidFieldManager("a".repeat(FIELD_MANAGER_MAX_LENGTH + 1))).toThrow(FieldManagerError);
+    expect(() => assertValidFieldManager(CHANT_FIELD_MANAGER)).not.toThrow();
+    // Someone else's manager is a legal value — this validates syntax, not ownership.
+    expect(() => assertValidFieldManager("kubectl-client-side-apply")).not.toThrow();
+  });
+
+  test("a stack exactly at the ceiling is allowed", () => {
+    const stack = "s".repeat(FIELD_MANAGER_MAX_LENGTH - "chant:".length);
+    expect(fieldManagerFor({ stack })).toHaveLength(FIELD_MANAGER_MAX_LENGTH);
+  });
+});

package/src/field-manager.ts

@@ -0,0 +1,111 @@
+/**
+ * chant's field-manager identity — chant #1075.
+ *
+ * Server-side apply records, per field, the name of the manager that last
+ * wrote it. That name is chant's identity in the cluster, so it has to be
+ * *stable* (the same stack applying twice must be the same manager, or the
+ * second apply conflicts with the first) and *distinguishing* (two chant
+ * stacks sharing a cluster must not silently co-own each other's fields).
+ *
+ * The scheme is `chant` alone, or `chant:<stack>` when the project sets
+ * `ownership.stack` — the same identity the label-based ownership marker
+ * already carries (`packages/core/src/ownership.ts`). Ownership-by-label
+ * answers a binary whole-object question; the field manager is the sub-object
+ * version of the same fact, supplied by the API server rather than stamped by
+ * chant. One identity, two granularities.
+ *
+ * **`ownership.env` is deliberately not part of it.** Two environments of one
+ * stack only ever touch the same object if they share a namespace and a name,
+ * and at that point they are fighting over it. An env-qualified manager would
+ * let them each own a different half of that object without either noticing;
+ * a stack-qualified one makes the second apply conflict, which is the correct
+ * outcome and the whole point of the conflict surface.
+ *
+ * This module is plain string logic with no dependency on chant core, so the
+ * lexicon (which reads `ownership` from project config) and the client (which
+ * writes the query parameter) agree on one derivation rather than two.
+ */
+
+import { FieldManagerError } from "./errors";
+
+/** The unqualified manager, used when a project sets no ownership stack. */
+export const CHANT_FIELD_MANAGER = "chant";
+
+/** Separator between the `chant` prefix and the stack identity. */
+export const FIELD_MANAGER_SEPARATOR = ":";
+
+/**
+ * The API server's own ceiling on `fieldManager`
+ * (`k8s.io/apiserver/pkg/endpoints/handlers/fieldmanager`). Exceeding it is a
+ * 400 on every apply, so it is checked here — where the name is derived and
+ * the offending config key can be named — rather than discovered in a cluster.
+ */
+export const FIELD_MANAGER_MAX_LENGTH = 128;
+
+/** The stack identity a field manager is derived from. */
+export interface FieldManagerIdentity {
+  /** `ownership.stack` from project config, when set. */
+  stack?: string;
+}
+
+/**
+ * Derive the field manager for a stack. `undefined`/no stack yields the bare
+ * `chant`; a stack yields `chant:<stack>`.
+ */
+export function fieldManagerFor(identity?: FieldManagerIdentity): string {
+  const stack = identity?.stack?.trim();
+  if (!stack) return CHANT_FIELD_MANAGER;
+  const manager = `${CHANT_FIELD_MANAGER}${FIELD_MANAGER_SEPARATOR}${stack}`;
+  assertValidFieldManager(manager, stack);
+  return manager;
+}
+
+/**
+ * Reject a field manager the API server would reject, naming the config key
+ * responsible. A silent truncation would be worse than a failure: it would
+ * merge two stacks' identities into one and make their applies fight.
+ */
+export function assertValidFieldManager(manager: string, stack?: string): void {
+  const source = stack === undefined ? `field manager "${manager}"` : `ownership.stack "${stack}"`;
+  if (manager.length === 0) {
+    throw new FieldManagerError(`${source} produces an empty field manager, which the API server rejects`);
+  }
+  if (manager.length > FIELD_MANAGER_MAX_LENGTH) {
+    throw new FieldManagerError(
+      `${source} produces the field manager "${manager}" (${manager.length} characters), ` +
+        `over the API server's ${FIELD_MANAGER_MAX_LENGTH}-character limit`,
+    );
+  }
+  // Space (0x20), every C0 control, and DEL. A code-point scan rather than a
+  // regexp, so no literal control character ever appears in this source.
+  const badIndex = [...manager].findIndex((ch) => {
+    const code = ch.codePointAt(0) ?? 0;
+    return code <= 0x20 || code === 0x7f;
+  });
+  if (badIndex !== -1) {
+    throw new FieldManagerError(
+      `${source} produces the field manager "${manager}", which contains whitespace or a control ` +
+        `character at position ${badIndex}. A field manager is an identity recorded on every object ` +
+        `chant applies; keep it to printable, space-free text.`,
+    );
+  }
+}
+
+/** True when `manager` is a chant field manager, qualified or not. */
+export function isChantFieldManager(manager: string | undefined): boolean {
+  if (!manager) return false;
+  return (
+    manager === CHANT_FIELD_MANAGER ||
+    manager.startsWith(`${CHANT_FIELD_MANAGER}${FIELD_MANAGER_SEPARATOR}`)
+  );
+}
+
+/**
+ * The stack a chant field manager names, or undefined for the unqualified
+ * `chant` and for any manager that is not chant's at all.
+ */
+export function chantStackOf(manager: string | undefined): string | undefined {
+  if (!manager || !isChantFieldManager(manager)) return undefined;
+  const stack = manager.slice(CHANT_FIELD_MANAGER.length + FIELD_MANAGER_SEPARATOR.length);
+  return stack.length > 0 ? stack : undefined;
+}

package/src/index.ts

@@ -22,18 +22,53 @@ export {
   selectorText,
   refText,
 } from "./client";
-export type { K8sClient, ReadOptions, ApplyOptions } from "./client";
+export type { K8sClient, ReadOptions, ApplyOptions, DeleteOptions, ListOptions, ReadLogOptions } from "./client";
 
 export {
   K8sApiError,
   K8sTransportError,
   K8sClientUnavailableError,
   ExecCredentialNotAllowedError,
+  FieldManagerError,
   KubeConfigError,
   UnknownResourceError,
 } from "./errors";
 export type { K8sStatus } from "./errors";
 
+// chant's field-manager identity and the conflict surface — chant #1075.
+export {
+  CHANT_FIELD_MANAGER,
+  FIELD_MANAGER_SEPARATOR,
+  FIELD_MANAGER_MAX_LENGTH,
+  fieldManagerFor,
+  assertValidFieldManager,
+  isChantFieldManager,
+  chantStackOf,
+} from "./field-manager";
+export type { FieldManagerIdentity } from "./field-manager";
+
+export {
+  FieldManagerConflictError,
+  asFieldManagerConflict,
+  parseFieldConflicts,
+  parseConflictMessage,
+  renderConflictReport,
+} from "./conflict";
+export type { FieldConflict, ConflictReport } from "./conflict";
+
+// managedFields primitives — the material chant #1076's deep observation reads.
+export {
+  managedFieldsOf,
+  fieldSetsOf,
+  managersOf,
+  fieldsOwnedBy,
+  chantOwnedFields,
+  fieldOwners,
+  fieldPathsOf,
+  renderSegment,
+} from "./managed-fields";
+export type { ManagedFieldsEntry, ManagerFieldSet } from "./managed-fields";
+
 export {
   DEFAULT_EXEC_ALLOWLIST,
   assertExecCredentialAllowed,