Files
clean-architecture-frontend…/src/contracts/api-operations.ts
T
DongHyeonka 3fba68bebc refactor(contracts): FE-REG-API 행이 refusedBeforeWrite를 타입으로 읽는다
문제
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
2026-11-04 22:34:35 +09:00

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]) }),
});
}