Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
8.3 KB
Raw Blame
import { createHash } from 'node:crypto'
import { PRE_DEPLOY_ANNOTATION } from '@clerum/network-policy-core'

/**
 * Annotation that records a hash of the recipe-derived manifest WRC last applied
 * to a managed object. On the next reconcile the reconciler recomputes the hash
 * from the freshly-built manifest and compares it to this annotation; when they
 * match it skips the write entirely.
 *
 * Why this exists: WRC's apply path does an unconditional full PUT
 * (replaceNamespaced*) every reconcile. Because builders emit a partial spec, the
 * API server re-defaults server-managed fields (strategy, revisionHistoryLimit,
 * progressDeadlineSeconds, …) on every replace, bumping `metadata.generation`
 * with no real change. That perpetual churn drove a degraded↔active status flap
 * (observedGeneration always one behind) and a downstream HCC NetworkPolicy
 * no-op write storm. Hashing the *desired* manifest (never the server's defaulted
 * view) and gating the write makes reconciles idempotent.
 */
export const SPEC_HASH_ANNOTATION = 'clerum.io/spec-hash'

/**
 * Annotations that record cross-controller handshake state rather than the
 * recipe-derived desired spec, and therefore MUST be excluded from the hash.
 *
 * `clerum.io/pre-deploy` is the load-bearing case: WRC builds two desired
 * manifests for the SAME McpServer in a single reconcile pass — step 7b
 * (`preDeployMcpServers`) injects `pre-deploy: "true"` before `ensureMcpServer`,
 * while step 9a (`delegateTransportWorkloads`) builds the manifest via
 * `buildMcpServerManifest` WITHOUT it. If the hash counted this annotation the
 * two manifests would hash differently and the idempotency gate would fire a
 * `replace` twice every pass forever (never converging, because the replace
 * carries `pre-deploy` over via the annotation merge). Excluding it lets both
 * paths hash identically so the gate holds (zero PUTs in steady state).
 *
 * The annotation intentionally PERSISTS on the live object (the replace merge
 * keeps it): HCC's network-ready re-ack guard keys off `pre-deploy === "true"`
 * (host-context-controller/src/reconciler.ts), so it must not be stripped from
 * the object — only from the hash. The key comes from the shared
 * `@clerum/network-policy-core` constant (the same one WRC and HCC use), so it
 * cannot drift; specHash.test.ts still pins the exclusion-list membership.
 */
export const HASH_EXCLUDED_ANNOTATIONS = [PRE_DEPLOY_ANNOTATION] as const

// Loose, class-compatible shape: K8s client model classes (V1Deployment, …) have
// `metadata?: V1ObjectMeta` with `annotations?: { [k]: string }`, so they satisfy
// this without needing an index signature.
type AnnotatableManifest = { metadata?: { annotations?: { [key: string]: string } } }

// Metadata that is not recipe-derived. The hash is only ever computed from a
// manifest WRC built, never from an object read back: the gate compares the live
// object's annotation string with the desired hash. The builders never set the
// server-assigned fields, so excluding them keeps the hash a function of the
// recipe even if a caller hashes a manifest that already carries, say, a
// resourceVersion. ownerReferences carry the apiserver-assigned recipe uid and are
// dropped for a cross-namespace object; the gate compares the controller owner uid
// on its own (controllerOwnerUidMatches).
// `annotations[SPEC_HASH_ANNOTATION]` is stripped to avoid self-reference.
const VOLATILE_METADATA_FIELDS = [
  'resourceVersion',
  'uid',
  'generation',
  'creationTimestamp',
  'deletionTimestamp',
  'managedFields',
  'selfLink',
  'ownerReferences',
]

function stableStringify(value: unknown): string {
  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
  const entries = Object.entries(value as Record<string, unknown>)
    .filter(([, v]) => v !== undefined)
    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
    .map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child)}`)
  return `{${entries.join(',')}}`
}

/**
 * Hash the recipe-derived shape of a manifest: its spec and the metadata we
 * author (name/namespace/labels/annotations), excluding server-managed/volatile
 * fields, `status`, and the spec-hash annotation itself.
 */
export function computeSpecHash(manifest: object): string {
  const clone = JSON.parse(JSON.stringify(manifest ?? {})) as {
    status?: unknown
    metadata?: { annotations?: { [key: string]: string } } & Record<string, unknown>
  }
  delete clone.status
  if (clone.metadata && typeof clone.metadata === 'object') {
    for (const field of VOLATILE_METADATA_FIELDS) {
      delete (clone.metadata as Record<string, unknown>)[field]
    }
    if (clone.metadata.annotations && typeof clone.metadata.annotations === 'object') {
      delete clone.metadata.annotations[SPEC_HASH_ANNOTATION]
      // Handshake-state annotations (e.g. pre-deploy) are cross-controller signals,
      // not desired spec: excluding them lets WRC's 7b (with pre-deploy) and 9a
      // (without) manifests hash identically so the idempotency gate converges.
      for (const key of HASH_EXCLUDED_ANNOTATIONS) {
        delete clone.metadata.annotations[key]
      }
      // An empty annotations object must hash identically to an absent one, so that
      // a freshly-built (unstamped) manifest and the same manifest after stamping
      // produce the same hash (the gate's idempotency guarantee).
      if (Object.keys(clone.metadata.annotations).length === 0) {
        delete (clone.metadata as Record<string, unknown>).annotations
      }
    }
  }
  return createHash('sha256').update(stableStringify(clone)).digest('hex').slice(0, 32)
}

/**
 * Compute the spec hash and write it into `metadata.annotations`. Mutates and
 * returns the hash. Idempotent: re-stamping the same manifest yields the same hash
 * because the prior hash annotation is excluded from the computation.
 */
export function stampSpecHash(manifest: AnnotatableManifest): string {
  const hash = computeSpecHash(manifest)
  const meta = (manifest.metadata ?? {}) as { annotations?: { [key: string]: string } }
  meta.annotations = meta.annotations ?? {}
  meta.annotations[SPEC_HASH_ANNOTATION] = hash
  ;(manifest as { metadata?: unknown }).metadata = meta
  return hash
}

/**
 * True when `existing` already carries the same spec-hash annotation that
 * `desired` was (or would be) stamped with — i.e. the apply would be a no-op.
 * Returns false when either side lacks the annotation (e.g. an object created
 * before this gate existed), forcing one reconciling write that stamps it.
 */
export function specHashUnchanged(
  desired: AnnotatableManifest,
  existing: { metadata?: { annotations?: { [key: string]: string } } } | null | undefined
): boolean {
  const desiredHash =
    desired.metadata?.annotations?.[SPEC_HASH_ANNOTATION] ?? computeSpecHash(desired)
  const existingHash = existing?.metadata?.annotations?.[SPEC_HASH_ANNOTATION]
  return Boolean(existingHash && desiredHash === existingHash)
}

type ControllerOwnedManifest = {
  metadata?: { ownerReferences?: Array<{ controller?: boolean; uid?: string }> }
}

/**
 * The metadata a read-first apply gate reads: the spec hash, the controller
 * owner, and the labels an ownership check inspects.
 */
export type GatedManifest = {
  metadata?: {
    annotations?: { [key: string]: string }
    labels?: { [key: string]: string }
    ownerReferences?: Array<{ controller?: boolean; uid?: string }>
  }
}

/**
 * True when `desired` and `existing` name the same controller owner uid, or
 * neither has a controller owner. ownerReferences stay out of the spec hash
 * (the apiserver assigns the uid, and a cross-namespace manifest drops them),
 * so a recipe deleted and recreated under the same name leaves the hash equal
 * while the live object still points at the old uid. Garbage collection would
 * then delete that object once the old owner is gone; comparing the uid makes
 * the gate write the new ownerReference instead. Same criterion as the
 * Secret comparison in the reconciler.
 */
export function controllerOwnerUidMatches(
  desired: ControllerOwnedManifest,
  existing: ControllerOwnedManifest | null | undefined
): boolean {
  const controllerUid = (manifest: ControllerOwnedManifest | null | undefined) =>
    manifest?.metadata?.ownerReferences?.find(ref => ref.controller)?.uid
  return controllerUid(desired) === controllerUid(existing)
}