Skip to content

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

TypeScript
3.9 KB
Raw Blame
import { ReporterTerminalError, type ReporterTerminalResult } from './boundedOffPathReporter'
import { hccLogger } from './logger'

const log = hccLogger.child({ module: 'reporter-http-failure' })

/**
 * control-api answers these (status, code) pairs deterministically: resending
 * the same event gets the same answer, because what they refuse is the request
 * itself and not the state of anything around it. `invalid_tracing_input`
 * covers both a malformed request and a well-formed one the server cannot bind
 * — a `hostLookupReference` without a uid, or carrying a key the server does
 * not read (#693) — and neither becomes acceptable on a retry, so it is as
 * final as `unsafe_tracing_input`. Every other failure (403 binding not yet
 * visible, 5xx, a 4xx without a code, a body that is not JSON) stays retryable.
 *
 * `administrative_intent_generation_drift` (#329) is deterministic for a
 * different reason than the others: the request is well formed and the server
 * state is real, but the Host carries an intent annotation pinned to a
 * generation it has already passed, and nothing ever retires that annotation.
 * Generations only grow — but on its own that would not settle it, because a
 * generation the annotation could still catch up to is not a superseded one.
 * The second fact is what closes it: nothing ever RAISES the annotation.
 * control-api's only correction lowers a prediction to the generation its write
 * actually produced, and the reporter always reads the live object, so the
 * answer cannot change. The plain 403 next door is NOT deterministic — it also
 * covers a binding that is merely not visible yet, which is what lets a
 * control-api/HCC deploy overlap heal itself — so only the coded 409 is listed
 * here. Two entries now share status 409, which makes the `find` on `code`
 * below load-bearing rather than incidental.
 */
const TERMINAL_RESPONSES: ReadonlyArray<{
  status: number
  code: string
  result: ReporterTerminalResult
}> = [
  { status: 409, code: 'tracing_idempotency_conflict', result: 'conflict' },
  { status: 409, code: 'administrative_intent_generation_drift', result: 'rejected' },
  { status: 400, code: 'unsafe_tracing_input', result: 'rejected' },
  { status: 400, code: 'invalid_tracing_input', result: 'rejected' },
]

function unreadableBodyReason(error: unknown): 'not_json' | 'aborted' | 'read_failed' {
  if (error instanceof Error && error.name === 'SyntaxError') return 'not_json'
  if (error instanceof Error && error.name === 'AbortError') return 'aborted'
  return 'read_failed'
}

async function responseCode(response: Response, label: string): Promise<string | undefined> {
  let body: unknown
  try {
    body = await response.json()
  } catch (error) {
    // No code can be read, so the caller treats the response as retryable.
    // Only the status and the failure kind are logged, never the body.
    log.warn('reporter could not read the response code', {
      label,
      status: response.status,
      reason: unreadableBodyReason(error),
    })
    return undefined
  }
  if (typeof body !== 'object' || body === null) return undefined
  const code = (body as { code?: unknown }).code
  return typeof code === 'string' ? code : undefined
}

/**
 * Throws for a non-2xx submit response. Only the `code` field of the body is
 * read; the body is never logged or attached to the error.
 */
export async function throwForFailedSubmit(response: Response, label: string): Promise<void> {
  if (response.ok) return
  const candidates = TERMINAL_RESPONSES.filter(entry => entry.status === response.status)
  if (candidates.length > 0) {
    const code = await responseCode(response, label)
    const terminal = candidates.find(entry => entry.code === code)
    if (terminal) {
      throw new ReporterTerminalError(
        terminal.result,
        `${label} submit rejected with ${response.status} ${terminal.code}`
      )
    }
  }
  throw new Error(`${label} submit failed with ${response.status}`)
}