import type { CommandEffectDescriptor, CommandRecoveryDescriptor, HttpMethod, InstalledContractContribution, InstalledHttpContract, ResponseEnvelope, RetrySemantics, RuntimeValidator, } from "./external-contract-runtime.ts"; import type { TrafficBudget } from "../platform/traffic/traffic-budget.ts"; /** * 1103/07-01. The data of a command effect descriptor. Its classifiers are * behaviour and stay out of the row; what the row keeps is whether the * descriptor answers 401, 403 and 429 itself, and the problem codes it names * as refused before any write when it names them. */ export type ApiCommandEffectRow = Readonly<{ classifiesStatus: boolean; refusedBeforeWrite?: readonly string[]; }>; /** A validator slot whose validation is skipped (`unvalidatedPayload`). */ export type ApiUnvalidatedSlot = "input" | "output" | "problem"; /** * FE-REG-API. The governed row of one installed HTTP operation, projected * from its V3 descriptor (`InstalledHttpContract`). A feature writes the * operation once, in its contract contribution; `check:registries` compares * these rows with the approved baseline. * * 1103/07-01. The row carries every wire-facing value of the descriptor: * what is sent and accepted, the bounds, and the retry and command data. The * governance grades a change (`config/contracts/registry-governance.json`). * Only functions stay out (`projectRequest`, the validators' parsing, the * command effect classifiers), with the policy and diagnostics names. */ export type ApiOperationRow = Readonly<{ operationId: string; featureId: string; method: HttpMethod; path: string; authProfileId: string; retrySemantics: RetrySemantics; requestBody: InstalledHttpContract["contract"]["requestBody"]; responseBody: InstalledHttpContract["contract"]["responseBody"]; responseEnvelope: ResponseEnvelope; requestSchema: string; responseSchema: string; problemSchema: string; acceptedStatuses: readonly number[]; emptyBodyStatuses: readonly number[]; /** Validator slots that skip validation by name; `[]` when all validate. */ unvalidated: readonly ApiUnvalidatedSlot[]; requestByteLimit: number; responseByteLimit: number; totalDeadlineMs: number; retryBudget: 0 | 1 | 2; traffic: TrafficBudget | null; commandEffect: ApiCommandEffectRow | null; commandRecovery: CommandRecoveryDescriptor | null; }>; /** * Pass composed contributions (`composeContractContributions`): composition * already refused duplicate operation ids and snapshotted every row. */ export function projectApiOperationRows( contributions: readonly InstalledContractContribution[], ): Readonly> { const rows: Record = {}; for (const contribution of contributions) { for (const { contract, frontend } of contribution.http) { rows[contract.operationId] = Object.freeze({ operationId: contract.operationId, featureId: contribution.featureId, method: contract.method, path: contract.pathTemplate, authProfileId: frontend.authProfileId, retrySemantics: contract.retrySemantics, requestBody: contract.requestBody, responseBody: contract.responseBody, responseEnvelope: contract.responseEnvelope ?? "NONE", requestSchema: contract.inputValidator.schemaId, responseSchema: contract.outputValidator.schemaId, problemSchema: contract.problemValidator.schemaId, acceptedStatuses: Object.freeze([...contract.acceptedStatuses]), emptyBodyStatuses: Object.freeze([...contract.emptyBodyStatuses]), unvalidated: unvalidatedSlots({ input: contract.inputValidator, output: contract.outputValidator, problem: contract.problemValidator, }), requestByteLimit: frontend.requestByteLimit, responseByteLimit: frontend.responseByteLimit, totalDeadlineMs: frontend.totalDeadlineMs, retryBudget: frontend.retryBudget, traffic: frontend.traffic === undefined ? null : Object.freeze({ maxPhysicalRequests: frontend.traffic.maxPhysicalRequests, maxRetries: frontend.traffic.maxRetries, maxConcurrentRequests: frontend.traffic.maxConcurrentRequests, maxQueuedRequests: frontend.traffic.maxQueuedRequests, }), commandEffect: commandEffectRow(contract.commandEffect), commandRecovery: contract.commandRecovery === null ? null : Object.freeze({ ...contract.commandRecovery }), }); } } return Object.freeze(rows); } /** The same marker rule as `listUnvalidatedPayloads`: any marker counts. */ function unvalidatedSlots( validators: Readonly>>, ): readonly ApiUnvalidatedSlot[] { return Object.freeze( (Object.keys(validators) as ApiUnvalidatedSlot[]).filter( (slot) => validators[slot].validation !== undefined, ), ); } function commandEffectRow( effect: CommandEffectDescriptor | null, ): ApiCommandEffectRow | null { if (effect === null) return null; // A descriptor that does not name refused codes has no such list, and the // row then has no such field. const refused = effect.refusedBeforeWrite; return Object.freeze({ classifiesStatus: typeof effect.classifyStatus === "function", ...(refused === undefined ? {} : { refusedBeforeWrite: Object.freeze([...refused]) }), }); }