Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import type { InfrastructureTelemetrySubmitterPrincipalV1 } from '../../middleware/tracingSubmitterAuth.js'
import type {
InfrastructureTelemetryEventInputV1,
InfrastructureTelemetryServerBindingV1,
} from './contracts.js'
import { canonicalTracingClusterName, canonicalTracingEnvironment } from './environment.js'
import {
type InfrastructureWorkloadBindingResolver,
InvalidTracingInputError,
} from './routeSubmissionService.js'
export const HCC_HEALTH_TRANSITION_BINDING_BLOCKER =
'hcc_telemetry_requires_server_verifiable_host_reference'
const HCC_HOST_TELEMETRY_TYPES = [
'health_transition',
'lifecycle_transition',
'reconcile_outcome',
'controller_error',
] as const
export interface AuthoritativeHostLookup {
getResource(plural: 'hosts', name: string, namespace: string): Promise<unknown>
}
type AuthoritativeHost = {
apiVersion?: string
kind?: string
metadata?: { name?: string; namespace?: string; uid?: string; generation?: number }
}
/**
* HCC's InternalControl credential authenticates the controller, while the
* authoritative Host read below binds each accepted report to a real resource
* and exact observed generation. Capacity and usage remain fail-closed because
* they require a separate inventory or metrics authority.
*/
export class HccHealthTransitionBindingUnavailableError extends Error {
readonly code = HCC_HEALTH_TRANSITION_BINDING_BLOCKER
readonly status = 403
readonly statusCode = 403
constructor() {
super('HCC telemetry rejected: no server-verifiable Host reference exists.')
this.name = 'HccHealthTransitionBindingUnavailableError'
}
}
export class HccHealthTransitionBindingResolver implements InfrastructureWorkloadBindingResolver {
constructor(
private readonly hostLookup: AuthoritativeHostLookup,
private readonly environment = canonicalTracingEnvironment(),
private readonly clusterName = canonicalTracingClusterName()
) {}
async resolve(
principal: InfrastructureTelemetrySubmitterPrincipalV1,
event: InfrastructureTelemetryEventInputV1
): Promise<InfrastructureTelemetryServerBindingV1 | null> {
if (
principal.kind !== 'hcc_internal_control' ||
!HCC_HOST_TELEMETRY_TYPES.includes(
event.telemetryType as (typeof HCC_HOST_TELEMETRY_TYPES)[number]
)
) {
return null
}
const reference = event.hostLookupReference
if (
!reference ||
!isDnsLabel(reference.name) ||
!isDnsLabel(reference.namespace) ||
(reference.generation !== undefined &&
(!Number.isSafeInteger(reference.generation) || reference.generation < 1))
) {
throw new HccHealthTransitionBindingUnavailableError()
}
if (reference.uid === undefined) {
// A Host deleted and recreated under the same name restarts at
// generation 1, so a reference without the uid does not name one object:
// an event observed on the old Host would bind to its successor. There
// is no spelling of this request that names the right object, which is
// why it is a 400 the caller must fix rather than the 403 above, which
// says the binding is not visible yet and invites a retry (#693).
throw new InvalidTracingInputError(
'hostLookupReference.uid is required for host-context-controller telemetry'
)
}
let host: AuthoritativeHost
try {
host = (await this.hostLookup.getResource(
'hosts',
reference.name,
reference.namespace
)) as AuthoritativeHost
} catch {
return null
}
const metadata = host.metadata
if (
host.apiVersion !== 'clerum.io/v1alpha1' ||
host.kind !== 'Host' ||
metadata?.name !== reference.name ||
metadata.namespace !== reference.namespace ||
// The generation stays optional where the uid is required: it narrows
// which revision of an object was observed, and an event that omits it
// still names one object. The uid is what names the object at all, so
// its absence has no safe reading (#693).
(reference.generation !== undefined && metadata.generation !== reference.generation) ||
// A Host deleted and recreated under the same name restarts at generation 1;
// only the uid tells the objects apart, so an event observed on the old
// object must not bind to its successor (#691).
metadata.uid !== reference.uid
) {
return null
}
const outcome = hccOutcome(event)
if (outcome === null) return null
return {
triggerKind: 'controller_reconcile',
outcome,
reasonCode: event.payload?.reason_code ?? null,
environment: this.environment,
clusterName: this.clusterName,
namespace: metadata.namespace,
workloadKind: 'Host',
workloadRef: `${metadata.namespace}/${metadata.name}`,
kubernetesKind: 'Host',
kubernetesName: metadata.name,
kubernetesUid: metadata.uid ?? null,
metadataGeneration: metadata.generation ?? null,
relatedOperationId: null,
relatedRunId: null,
}
}
}
function hccOutcome(event: InfrastructureTelemetryEventInputV1): string | null {
const reportedStatus = event.payload?.status
if (event.telemetryType === 'controller_error') {
return reportedStatus === undefined || reportedStatus === 'failed' ? 'failed' : null
}
if (event.telemetryType === 'reconcile_outcome') {
return reportedStatus === 'succeeded' || reportedStatus === 'failed' ? reportedStatus : null
}
return 'unknown'
}
function isDnsLabel(value: string): boolean {
return /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(value) && value.length <= 63
}