Skip to content

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

TypeScript
6.7 KB
Raw Blame
/**
 * Host↔LlmHook referential-integrity helpers (spec §8.2).
 *
 * A hook is referenced from `Host.spec.guardrails.hooks[phase]` as `{ id, digest }`.
 * These keep those references consistent with the hook's lifecycle so mcp-host
 * never sees an inconsistent state:
 *   - uninstall  → strip the ref from every referencing Host (no dangling ref,
 *     which mcp-host can't fail-closed on — N11).
 *   - upgrade    → move the CR image bump and the admin-pinned Host-ref digests
 *     together (an uncoordinated bump trips the digest pin and quarantines the
 *     hook).
 */
import { K8sGateway } from '../k8s.js'

type HookRef = { id: string; digest?: string }
type HostGuardrails = { hooks?: Record<string, HookRef[]>; [k: string]: unknown }
interface HostResource {
  metadata?: { name?: string }
  spec?: { guardrails?: HostGuardrails; [k: string]: unknown }
}

function referencesHook(host: HostResource, hookId: string): boolean {
  const hooks = host.spec?.guardrails?.hooks
  return (
    !!hooks &&
    Object.values(hooks).some(arr => Array.isArray(arr) && arr.some(r => r?.id === hookId))
  )
}

/** Hosts (in `hostsNamespace`) whose `guardrails.hooks` reference the LlmHook id. */
export async function listHostsReferencingHook(
  gateway: K8sGateway,
  hookId: string,
  hostsNamespace: string
): Promise<HostResource[]> {
  const items = (await gateway.listResource('hosts', hostsNamespace)) as HostResource[]
  return (items ?? []).filter(h => referencesHook(h, hookId))
}

/**
 * Atomic read→derive→write of one Host's `guardrails.hooks` map.
 *
 * `mutateResource` re-reads the Host, runs `derive` against THAT read, and uses
 * its `resourceVersion` as the replace precondition (re-deriving on a 409).
 * Deriving INSIDE the callback is the whole point: the Hosts here come from a
 * single list read, so a map computed out here would be replayed against a Host
 * that a concurrent install/uninstall has since changed — a full-spec replace
 * with no precondition, i.e. a silent lost update. That leaves an LlmHook CR
 * installed but unreferenced, which reads as an active guardrail that never
 * runs (fail-OPEN).
 */
async function mutateHostHooks(
  gateway: K8sGateway,
  name: string,
  hostsNamespace: string,
  derive: (hooks: Record<string, HookRef[]>) => Record<string, HookRef[]>
): Promise<void> {
  await gateway.mutateResource(
    'hosts',
    name,
    current => {
      const spec = (current.spec ?? {}) as NonNullable<HostResource['spec']>
      const guardrails: HostGuardrails = { ...(spec.guardrails ?? {}) }
      guardrails.hooks = derive(guardrails.hooks ?? {})
      return { spec: { ...spec, guardrails } }
    },
    hostsNamespace
  )
}

/** Drop `hookId` from every phase (removing now-empty phases). */
function withoutHook(hooks: Record<string, HookRef[]>, hookId: string): Record<string, HookRef[]> {
  const next: Record<string, HookRef[]> = { ...hooks }
  for (const phase of Object.keys(next)) {
    const filtered = next[phase].filter(r => r.id !== hookId)
    if (filtered.length > 0) next[phase] = filtered
    else delete next[phase]
  }
  return next
}

/**
 * Referential integrity on install: reference `hookId` from every phase in
 * `lifecyclePoints` on ONE Host. Idempotent per phase (an existing ref is left
 * alone), and atomic — refs another operation added after this request started
 * are preserved rather than clobbered (see mutateHostHooks).
 */
export async function addHookRefToHost(
  gateway: K8sGateway,
  hostName: string,
  hookId: string,
  lifecyclePoints: string[],
  digest: string | undefined,
  hostsNamespace: string
): Promise<void> {
  await mutateHostHooks(gateway, hostName, hostsNamespace, current => {
    const hooks: Record<string, HookRef[]> = { ...current }
    for (const phase of lifecyclePoints) {
      const arr = hooks[phase] ? [...hooks[phase]] : []
      if (!arr.some(r => r.id === hookId)) {
        arr.push({ id: hookId, ...(digest ? { digest } : {}) })
      }
      hooks[phase] = arr
    }
    return hooks
  })
}

/**
 * Referential integrity on uninstall: remove every `{ id: hookId }` reference
 * from all referencing Hosts. Call this BEFORE deleting the LlmHook CR so a
 * dangling ref never exists. Returns the Host names touched.
 */
export async function stripHookRefFromHosts(
  gateway: K8sGateway,
  hookId: string,
  hostsNamespace: string
): Promise<string[]> {
  const hosts = await listHostsReferencingHook(gateway, hookId, hostsNamespace)
  const touched: string[] = []
  for (const host of hosts) {
    const name = host.metadata?.name
    if (!name) continue
    await mutateHostHooks(gateway, name, hostsNamespace, hooks => withoutHook(hooks, hookId))
    touched.push(name)
  }
  return touched
}

/** Phases (Host keys) under which `hooks` currently references `hookId`. */
function phasesReferencing(hooks: Record<string, HookRef[]>, hookId: string): string[] {
  return Object.keys(hooks).filter(
    phase => Array.isArray(hooks[phase]) && hooks[phase].some(r => r?.id === hookId)
  )
}

/**
 * Coordinated upgrade: move the admin-pinned Host-ref digests together with the
 * CR image bump, PRESERVING each Host's per-phase placement. mcp-host runs a
 * hook only at the Host phases it is referenced under, so an admin's "Remove
 * from <phase>" must survive an upgrade:
 *   - phases the Host references the hook under AND the upgraded hook still
 *     declares are kept, with the new `digest`;
 *   - phases the upgraded hook no longer declares are dropped;
 *   - phases the Host does not reference (e.g. removed by the admin, or newly
 *     declared by the upgrade) are NOT added.
 * If none of the Host's phases survive the upgrade, the hook is re-referenced at
 * the upgraded `lifecyclePoints` rather than silently left unreferenced (an
 * installed guardrail that never runs). Returns the Host names touched.
 */
export async function syncHookRefsInHosts(
  gateway: K8sGateway,
  hookId: string,
  lifecyclePoints: string[],
  digest: string | undefined,
  hostsNamespace: string
): Promise<string[]> {
  const hosts = await listHostsReferencingHook(gateway, hookId, hostsNamespace)
  const touched: string[] = []
  for (const host of hosts) {
    const name = host.metadata?.name
    if (!name) continue
    await mutateHostHooks(gateway, name, hostsNamespace, current => {
      const declared = new Set(lifecyclePoints)
      const kept = phasesReferencing(current, hookId).filter(phase => declared.has(phase))
      const phases = kept.length > 0 ? kept : lifecyclePoints
      const hooks = withoutHook(current, hookId)
      for (const phase of phases) {
        const arr = hooks[phase] ? [...hooks[phase]] : []
        arr.push({ id: hookId, ...(digest ? { digest } : {}) })
        hooks[phase] = arr
      }
      return hooks
    })
    touched.push(name)
  }
  return touched
}