Files
clean-architecture-frontend…/src/contracts/api-operations.ts
T
DongHyeonka 08ed0a088d fix(contracts)!: FE-REG-API 행에 status 목록·상한·재시도 예산·검증 생략을 담는다
문제
V2 행과 V2/V3 parity 테스트를 지운 뒤 FE-REG-API 행은 descriptor에서
12칸만 뽑는다. acceptedStatuses, emptyBodyStatuses, 바이트 상한, 마감,
retryBudget, traffic, commandEffect, commandRecovery, 검증 생략 표시는 행에
없다. 그래서 생성 API의 acceptedStatuses를 [200, 201]에서 [201]로 줄여도
check:registries가 통과한다(실험 X2). 이전 커밋 d99301b에서는 같은 변경이
breaking 증거 누락으로 실패했다. 응답 상한·마감 변경은 기록에서 사라졌고
(X3·X6), problemSchema는 breaking 칸이 아니어서 problem 검증기 id를 바꿔도
behavior-change로 통과했다(X4). 짝 백엔드는 생성에 201, 본문 없는 응답에
204를 쓴다. 이 status를 빼면 배포 뒤 그 API가 모두 실패한다.

고른 방법
- projectApiOperationRows가 함수 밖의 descriptor 값을 모두 뽑는다:
  acceptedStatuses, emptyBodyStatuses, unvalidated(검증을 건너뛰는 검증기
  칸 이름: input·output·problem), requestByteLimit, responseByteLimit,
  totalDeadlineMs, retryBudget, traffic, commandEffect, commandRecovery.
- commandEffect는 함수를 빼고 데이터만 남긴다: classifyStatus가 있는지
  (classifiesStatus)와, descriptor가 이름을 붙였을 때만 refusedBeforeWrite
  목록. refusedBeforeWrite는 다른 작업에서 더해지는 선택 칸이라 구조로
  읽고, 없으면 행에도 없다.
- governance: problemSchema와 unvalidated를 breakingFields에 넣는다.
  status 배열은 breakingFields에 넣지 않는다. 분류기가 배열에서 값이
  빠지면 이미 allowed-value-removed breaking으로 본다. breakingFields에
  넣으면 status를 더하는 것(전에 받던 응답을 모두 계속 받는 변경)까지
  증거를 요구한다. 숫자 칸·traffic·command 칸은 behavior-change로 기록한다.
- 매뉴얼 01 9단계에 무엇이 breaking이고 무엇이 behavior-change인지,
  descriptor 함수는 행에 없다는 것을 적었다.

버린 대안
- descriptor 전체(함수 제외)를 투영: policyId·diagnosticsOperation까지
  기준선이 흔들려 리뷰 잡음만 는다. 둘은 wire 값이 아니다.
- V2/V3 parity 테스트 부활: 사본이 다시 둘이 된다.
- 숫자 칸 감소를 breaking으로: 분류기에 방향 규칙이 없고, 상한·마감
  조정은 자주 하는 운영 값이다. 기록만 하고 PR에서 본다.

위험·한계
- governance 계약(requiredFields·fieldTypes·breakingFields)이 바뀌어
  기준선을 다시 승인했다. 다운스트림은 동기화 때 재승인 1회가 필요하다.
- FE-REG-SCHEMA에 problem 스키마 행이 없어 problemSchema는 참조 검사
  대상이 아니다. breaking 칸으로만 잠근다.
- classifyProblem이 무엇을 NOT_APPLIED로 보는지는 함수라 기록되지 않는다.

검증
- 기준선 재승인 뒤 실험 재실행(check:registries):
  X2 [200,201]->[201] 실패(acceptedStatuses:allowed-value-removed 증거 누락),
  X4 problem 검증기 id 변경 실패(problemSchema:field-changed 3건),
  X5 GET 출력 검증기 생략 실패(unvalidated:field-changed),
  X3 응답 상한·X6 마감 변경은 behavior-change로 통과하고 스냅샷에 남는다.
- tests/unit/api-operation-rows.test.ts: 새 칸 고정, refusedBeforeWrite
  있음·없음, governance JSON으로 분류한 8가지 변경.
- run-vitest related(api-operations.ts, governance) 21파일 156건,
  registry 테스트 4파일 63건, check:registries:compatibility-fixtures,
  check:types, eslint, verify:documentation 통과.

BREAKING CHANGE: FE-REG-API governance 계약이 바뀌어 다운스트림의
check:registries가 FE-REG-API:$contract:* contract-field-changed로
실패한다. 동기화 뒤 REGISTRY_BASELINE_OWNER·REGISTRY_BASELINE_REASON을
주고 update:registry-baseline을 한 번 돌린다.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
Refs: docs/reviews/2026-11-03-maturity-review/README.md 3절
2026-11-04 20:24:41 +09:00

145 lines
5.6 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;
// Read structurally: a descriptor that does not name refused codes has no
// such list, and the row then has no such field.
const refused: unknown = (effect as Readonly<{ refusedBeforeWrite?: unknown }>)
.refusedBeforeWrite;
return Object.freeze({
classifiesStatus: typeof effect.classifyStatus === "function",
...(Array.isArray(refused)
? { refusedBeforeWrite: Object.freeze(refused.map(String)) }
: {}),
});
}