문제 fix/r1103-contracts는 fix/r1103-http가 아직 없을 때 CommandEffectDescriptor에 없는 refusedBeforeWrite를 구조 캐스트로 읽었다. 두 브랜치를 합치자 그 칸이 타입에 생겼다. 또 행 투영 테스트가 Envelope가 아닌 operation에 refusedBeforeWrite를 적는데, http 쪽 조립 검사(1103/03-01)는 그것을 거절해 테스트가 ContractContributionError로 실패한다. 고른 방법 - api-operations.ts는 effect.refusedBeforeWrite를 타입으로 읽는다. - 테스트의 create descriptor에 responseEnvelope ENVELOPE_V1을 주고, code를 업무 거절 모양(TEST_ENTITY_INVALID 등)으로 바꾼다. 위험·한계 - 행 모양은 그대로다. 기준선 영향 없음. 검증 - tests/unit/api-operation-rows.test.ts 12건, test:unit 2,790건, check:types, lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
144 lines
5.5 KiB
TypeScript
144 lines
5.5 KiB
TypeScript
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<unknown, unknown, unknown>["contract"]["requestBody"];
|
|
responseBody: InstalledHttpContract<unknown, unknown, unknown>["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<Record<string, ApiOperationRow>> {
|
|
const rows: Record<string, ApiOperationRow> = {};
|
|
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<Record<ApiUnvalidatedSlot, RuntimeValidator<unknown>>>,
|
|
): readonly ApiUnvalidatedSlot[] {
|
|
return Object.freeze(
|
|
(Object.keys(validators) as ApiUnvalidatedSlot[]).filter(
|
|
(slot) => validators[slot].validation !== undefined,
|
|
),
|
|
);
|
|
}
|
|
|
|
function commandEffectRow(
|
|
effect: CommandEffectDescriptor<unknown> | 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]) }),
|
|
});
|
|
}
|