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절
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"snapshotDigest": "16f727424579279e0ef810620f672a8a9d74de6b71e3e9ce37ab07a82f645588",
|
||||
"snapshotDigest": "96e048bf63f739ba7acb9238e77b4b36abaf9c1fc3e40ea2f2f4a4862e0127b9",
|
||||
"owner": "DongHyeonka",
|
||||
"reason": "2026-11-03 사용자 승인('둘 다 지워'): V2 API 행 제거. FE-REG-API 행은 V3 descriptor에서 뽑은 projection(operationId·featureId·method·path·authProfileId·retrySemantics·requestBody·responseBody·responseEnvelope·request/response/problemSchema)이다. V3 descriptor가 쓰지 않는 참조 기능 NoRequest 스키마 행 제거",
|
||||
"approvedAt": "2026-11-03T12:22:21.004Z"
|
||||
"reason": "1103/07-01 FE-REG-API rows carry descriptor wire values (statuses, limits, deadline, retry budget, traffic, command data, validation skip); problemSchema and unvalidated are breaking fields",
|
||||
"approvedAt": "2026-11-04T11:23:02.382Z"
|
||||
}
|
||||
|
||||
@@ -341,7 +341,17 @@
|
||||
"responseEnvelope",
|
||||
"requestSchema",
|
||||
"responseSchema",
|
||||
"problemSchema"
|
||||
"problemSchema",
|
||||
"acceptedStatuses",
|
||||
"emptyBodyStatuses",
|
||||
"unvalidated",
|
||||
"requestByteLimit",
|
||||
"responseByteLimit",
|
||||
"totalDeadlineMs",
|
||||
"retryBudget",
|
||||
"traffic",
|
||||
"commandEffect",
|
||||
"commandRecovery"
|
||||
],
|
||||
"fieldTypes": {
|
||||
"operationId": "string",
|
||||
@@ -355,7 +365,17 @@
|
||||
"responseEnvelope": "string",
|
||||
"requestSchema": "string",
|
||||
"responseSchema": "string",
|
||||
"problemSchema": "string"
|
||||
"problemSchema": "string",
|
||||
"acceptedStatuses": "array",
|
||||
"emptyBodyStatuses": "array",
|
||||
"unvalidated": "array",
|
||||
"requestByteLimit": "integer",
|
||||
"responseByteLimit": "integer",
|
||||
"totalDeadlineMs": "integer",
|
||||
"retryBudget": "integer",
|
||||
"traffic": "object|null",
|
||||
"commandEffect": "object|null",
|
||||
"commandRecovery": "object|null"
|
||||
},
|
||||
"uniqueFields": [
|
||||
"operationId"
|
||||
@@ -412,51 +432,110 @@
|
||||
"responseBody",
|
||||
"responseEnvelope",
|
||||
"requestSchema",
|
||||
"responseSchema"
|
||||
"responseSchema",
|
||||
"problemSchema",
|
||||
"unvalidated"
|
||||
]
|
||||
},
|
||||
"rows": {
|
||||
"CREATE_REFERENCE_RESOURCE": {
|
||||
"acceptedStatuses": [
|
||||
200,
|
||||
201
|
||||
],
|
||||
"authProfileId": "EXTERNAL_BEARER",
|
||||
"commandEffect": {
|
||||
"classifiesStatus": true
|
||||
},
|
||||
"commandRecovery": {
|
||||
"mode": "IDEMPOTENCY_REPLAY",
|
||||
"operationIdentityField": "idempotencyKey"
|
||||
},
|
||||
"emptyBodyStatuses": [],
|
||||
"featureId": "reference-feature",
|
||||
"method": "POST",
|
||||
"operationId": "CREATE_REFERENCE_RESOURCE",
|
||||
"path": "/api/reference-resources",
|
||||
"problemSchema": "ReferenceProblem",
|
||||
"requestBody": "JSON",
|
||||
"requestByteLimit": 32768,
|
||||
"requestSchema": "CreateReferenceResourceCommand",
|
||||
"responseBody": "REQUIRED_JSON",
|
||||
"responseByteLimit": 32768,
|
||||
"responseEnvelope": "NONE",
|
||||
"responseSchema": "ReferenceResourcePayload",
|
||||
"retrySemantics": "KEYED"
|
||||
"retryBudget": 0,
|
||||
"retrySemantics": "KEYED",
|
||||
"totalDeadlineMs": 10000,
|
||||
"traffic": {
|
||||
"maxConcurrentRequests": 1,
|
||||
"maxPhysicalRequests": 1,
|
||||
"maxQueuedRequests": 0,
|
||||
"maxRetries": 0
|
||||
},
|
||||
"unvalidated": []
|
||||
},
|
||||
"GET_REFERENCE_RESOURCE": {
|
||||
"acceptedStatuses": [
|
||||
200
|
||||
],
|
||||
"authProfileId": "EXTERNAL_BEARER",
|
||||
"commandEffect": null,
|
||||
"commandRecovery": null,
|
||||
"emptyBodyStatuses": [],
|
||||
"featureId": "reference-feature",
|
||||
"method": "GET",
|
||||
"operationId": "GET_REFERENCE_RESOURCE",
|
||||
"path": "/api/reference-resources/{resourceId}",
|
||||
"problemSchema": "ReferenceProblem",
|
||||
"requestBody": "NONE",
|
||||
"requestByteLimit": 0,
|
||||
"requestSchema": "ReferenceResourceParams",
|
||||
"responseBody": "REQUIRED_JSON",
|
||||
"responseByteLimit": 32768,
|
||||
"responseEnvelope": "NONE",
|
||||
"responseSchema": "ReferenceResourcePayload",
|
||||
"retrySemantics": "SAFE"
|
||||
"retryBudget": 2,
|
||||
"retrySemantics": "SAFE",
|
||||
"totalDeadlineMs": 10000,
|
||||
"traffic": {
|
||||
"maxConcurrentRequests": 1,
|
||||
"maxPhysicalRequests": 3,
|
||||
"maxQueuedRequests": 0,
|
||||
"maxRetries": 2
|
||||
},
|
||||
"unvalidated": []
|
||||
},
|
||||
"LIST_REFERENCE_RESOURCES": {
|
||||
"acceptedStatuses": [
|
||||
200
|
||||
],
|
||||
"authProfileId": "EXTERNAL_BEARER",
|
||||
"commandEffect": null,
|
||||
"commandRecovery": null,
|
||||
"emptyBodyStatuses": [],
|
||||
"featureId": "reference-feature",
|
||||
"method": "GET",
|
||||
"operationId": "LIST_REFERENCE_RESOURCES",
|
||||
"path": "/api/reference-resources",
|
||||
"problemSchema": "ReferenceProblem",
|
||||
"requestBody": "NONE",
|
||||
"requestByteLimit": 0,
|
||||
"requestSchema": "ReferenceResourceListQuery",
|
||||
"responseBody": "REQUIRED_JSON",
|
||||
"responseByteLimit": 262144,
|
||||
"responseEnvelope": "NONE",
|
||||
"responseSchema": "ReferenceResourceListPayload",
|
||||
"retrySemantics": "SAFE"
|
||||
"retryBudget": 2,
|
||||
"retrySemantics": "SAFE",
|
||||
"totalDeadlineMs": 10000,
|
||||
"traffic": {
|
||||
"maxConcurrentRequests": 1,
|
||||
"maxPhysicalRequests": 3,
|
||||
"maxQueuedRequests": 0,
|
||||
"maxRetries": 2
|
||||
},
|
||||
"unvalidated": []
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -565,7 +644,7 @@
|
||||
"registryId": "FE-REG-ENV",
|
||||
"owner": "feature-frontend-env-runtime-config-contract",
|
||||
"source": "src/contracts/env.ts",
|
||||
"rowCount": 16,
|
||||
"rowCount": 18,
|
||||
"contract": {
|
||||
"requiredFields": [
|
||||
"phase",
|
||||
@@ -619,6 +698,12 @@
|
||||
"phase": "runtime",
|
||||
"required": true
|
||||
},
|
||||
"BUILD_ID": {
|
||||
"classification": "public-metadata",
|
||||
"defaultValue": null,
|
||||
"phase": "runtime",
|
||||
"required": false
|
||||
},
|
||||
"CAPABILITY_OVERRIDES": {
|
||||
"classification": "public",
|
||||
"defaultValue": null,
|
||||
@@ -643,6 +728,12 @@
|
||||
"phase": "runtime",
|
||||
"required": false
|
||||
},
|
||||
"RELEASE_ID": {
|
||||
"classification": "public-metadata",
|
||||
"defaultValue": null,
|
||||
"phase": "runtime",
|
||||
"required": false
|
||||
},
|
||||
"RELEASE_MANIFEST_URL": {
|
||||
"classification": "public",
|
||||
"defaultValue": "/release-manifest.json",
|
||||
|
||||
@@ -149,7 +149,17 @@
|
||||
"responseEnvelope",
|
||||
"requestSchema",
|
||||
"responseSchema",
|
||||
"problemSchema"
|
||||
"problemSchema",
|
||||
"acceptedStatuses",
|
||||
"emptyBodyStatuses",
|
||||
"unvalidated",
|
||||
"requestByteLimit",
|
||||
"responseByteLimit",
|
||||
"totalDeadlineMs",
|
||||
"retryBudget",
|
||||
"traffic",
|
||||
"commandEffect",
|
||||
"commandRecovery"
|
||||
],
|
||||
"fieldTypes": {
|
||||
"operationId": "string",
|
||||
@@ -163,7 +173,17 @@
|
||||
"responseEnvelope": "string",
|
||||
"requestSchema": "string",
|
||||
"responseSchema": "string",
|
||||
"problemSchema": "string"
|
||||
"problemSchema": "string",
|
||||
"acceptedStatuses": "array",
|
||||
"emptyBodyStatuses": "array",
|
||||
"unvalidated": "array",
|
||||
"requestByteLimit": "integer",
|
||||
"responseByteLimit": "integer",
|
||||
"totalDeadlineMs": "integer",
|
||||
"retryBudget": "integer",
|
||||
"traffic": "object|null",
|
||||
"commandEffect": "object|null",
|
||||
"commandRecovery": "object|null"
|
||||
},
|
||||
"uniqueFields": [
|
||||
"operationId"
|
||||
@@ -224,7 +244,9 @@
|
||||
"responseBody",
|
||||
"responseEnvelope",
|
||||
"requestSchema",
|
||||
"responseSchema"
|
||||
"responseSchema",
|
||||
"problemSchema",
|
||||
"unvalidated"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
@@ -497,7 +497,10 @@ projectRequest: (input) => Object.freeze({
|
||||
② **기준**
|
||||
|
||||
- 라우트, operation, 스키마, 무효화 topic·namespace·edge를 **더하기만** 하면 기준선은 바뀌지 않는다.
|
||||
- 행을 **빼거나 바꾸면** breaking 변경이다. 둘 중 하나를 한다.
|
||||
- 행을 **빼거나** breaking 칸을 **바꾸면** breaking 변경이다. breaking 칸은 `config/contracts/registry-governance.json`의 `breakingFields`다. 배열 칸에서 값을 빼는 것도 breaking이다.
|
||||
- FE-REG-API 예: 생성 API의 `acceptedStatuses`를 `[200, 201]`에서 `[201]`로 줄이거나, `problemSchema`를 바꾸거나, 검증기를 `unvalidatedPayload`로 바꾸면(`unvalidated` 칸) breaking이다.
|
||||
- status를 더하는 것, 바이트 상한·마감·`retryBudget`·`traffic`·`commandEffect`·`commandRecovery`를 바꾸는 것은 behavior-change다. 통과하지만 스냅샷 diff(`artifacts/quality/registries.json`의 `compatibility.changes`)에 남는다. PR에서 본다.
|
||||
- breaking 변경이면 둘 중 하나를 한다.
|
||||
- `REGISTRY_BASELINE_OWNER`, `REGISTRY_BASELINE_REASON`을 주고 `corepack pnpm update:registry-baseline`을 돌린다.
|
||||
- 또는 `config/contracts/registry-change-evidence.json`에 항목을 더한다. 칸 설명은 `docs/operations/ci-quality-gates.md`에 있다.
|
||||
- a11y 기록은 생성 명령이 pending으로 만든다. 서명은 릴리스 전에 사람이 한다([03 문서](03-outside-feature-folder.md)).
|
||||
@@ -510,6 +513,7 @@ projectRequest: (input) => Object.freeze({
|
||||
- 메시지: `breaking change missing evidence: <changeId>`
|
||||
- 지금 diff와 맞지 않는 증거 행이 남으면 `stale breaking evidence <changeId>: ...`로 실패한다.
|
||||
- **못 잡음**: 사람이 서명하지 않은 a11y 기록은 merge 게이트를 통과한다. 릴리스 게이트 FE-GATE-028이 막는다.
|
||||
- **못 잡음**: descriptor의 함수는 행에 없다. `classifyProblem`·`classifyStatus`가 무엇을 `NOT_APPLIED`로 보는지, `projectRequest`가 무엇을 보내는지는 PR에서 본다.
|
||||
|
||||
④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration`
|
||||
|
||||
|
||||
@@ -1,16 +1,40 @@
|
||||
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;
|
||||
@@ -25,6 +49,17 @@ export type ApiOperationRow = Readonly<{
|
||||
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;
|
||||
}>;
|
||||
|
||||
/**
|
||||
@@ -50,8 +85,60 @@ export function projectApiOperationRows(
|
||||
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)) }
|
||||
: {}),
|
||||
});
|
||||
}
|
||||
|
||||
@@ -1,13 +1,22 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
canonicalizeRegistryValue,
|
||||
diffRegistrySnapshots,
|
||||
} from "../../scripts/lib/registry-compatibility.ts";
|
||||
import { projectApiOperationRows } from "../../src/contracts/api-operations.ts";
|
||||
import { composeContractContributions } from "../../src/contracts/external-contract-runtime.ts";
|
||||
import { unvalidatedPayload } from "../../src/contracts/unvalidated-payload.ts";
|
||||
import {
|
||||
API_OPERATIONS,
|
||||
COMPOSED_CONTRACT_CONTRIBUTIONS,
|
||||
} from "../../src/features/loaded-feature-runtimes.ts";
|
||||
import {
|
||||
TEST_CLASSIFIED_CREATE_HTTP_CONTRACT,
|
||||
TEST_CONTRACT_CONTRIBUTION,
|
||||
TEST_CREATE_HTTP_CONTRACT,
|
||||
TEST_LIST_HTTP_CONTRACT,
|
||||
} from "../helpers/external-contract-fixture.ts";
|
||||
|
||||
@@ -40,11 +49,80 @@ describe("FE-REG-API rows projected from HTTP descriptors", () => {
|
||||
requestSchema: "TestEntityListQuery",
|
||||
responseSchema: "TestEntityListPayload",
|
||||
problemSchema: "TestProblem",
|
||||
acceptedStatuses: [200],
|
||||
emptyBodyStatuses: [],
|
||||
unvalidated: [],
|
||||
requestByteLimit: 0,
|
||||
responseByteLimit: 32_768,
|
||||
totalDeadlineMs: 10_000,
|
||||
retryBudget: 2,
|
||||
traffic: null,
|
||||
commandEffect: null,
|
||||
commandRecovery: null,
|
||||
});
|
||||
expect(rows.TEST_CREATE_ENTITY).toMatchObject({
|
||||
method: "POST",
|
||||
retrySemantics: "KEYED",
|
||||
requestBody: "JSON",
|
||||
acceptedStatuses: [201],
|
||||
retryBudget: 0,
|
||||
commandEffect: { classifiesStatus: false },
|
||||
commandRecovery: {
|
||||
mode: "IDEMPOTENCY_REPLAY",
|
||||
operationIdentityField: "idempotencyKey",
|
||||
},
|
||||
});
|
||||
expect(rows.TEST_CREATE_ENTITY?.commandEffect).not.toHaveProperty(
|
||||
"refusedBeforeWrite",
|
||||
);
|
||||
});
|
||||
|
||||
it("carries the command effect data and the validator slots that skip validation", () => {
|
||||
const traffic = Object.freeze({
|
||||
maxPhysicalRequests: 2,
|
||||
maxRetries: 1,
|
||||
maxConcurrentRequests: 1,
|
||||
maxQueuedRequests: 0,
|
||||
});
|
||||
const rows = projectApiOperationRows(
|
||||
composeContractContributions([
|
||||
{
|
||||
...TEST_CONTRACT_CONTRIBUTION,
|
||||
http: [
|
||||
{
|
||||
...TEST_LIST_HTTP_CONTRACT,
|
||||
contract: {
|
||||
...TEST_LIST_HTTP_CONTRACT.contract,
|
||||
outputValidator: unvalidatedPayload(
|
||||
"TestEntityListPayload",
|
||||
"typed by the package",
|
||||
),
|
||||
},
|
||||
frontend: { ...TEST_LIST_HTTP_CONTRACT.frontend, traffic },
|
||||
},
|
||||
{
|
||||
...TEST_CLASSIFIED_CREATE_HTTP_CONTRACT,
|
||||
contract: {
|
||||
...TEST_CLASSIFIED_CREATE_HTTP_CONTRACT.contract,
|
||||
// A descriptor that names the codes refused before any write.
|
||||
commandEffect: {
|
||||
...TEST_CLASSIFIED_CREATE_HTTP_CONTRACT.contract.commandEffect,
|
||||
refusedBeforeWrite: ["VALIDATION_FAILED", "CONFLICT"],
|
||||
},
|
||||
},
|
||||
},
|
||||
] as never,
|
||||
},
|
||||
]).contributions,
|
||||
);
|
||||
|
||||
expect(rows.TEST_LIST_ENTITIES).toMatchObject({
|
||||
unvalidated: ["output"],
|
||||
traffic,
|
||||
});
|
||||
expect(rows.TEST_CREATE_ENTITY?.commandEffect).toEqual({
|
||||
classifiesStatus: true,
|
||||
refusedBeforeWrite: ["VALIDATION_FAILED", "CONFLICT"],
|
||||
});
|
||||
});
|
||||
|
||||
@@ -78,3 +156,148 @@ describe("FE-REG-API rows projected from HTTP descriptors", () => {
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* 1103/07-01. The wire values of a descriptor are graded by the governance
|
||||
* the repository ships, not only recorded: narrowing what the frontend
|
||||
* accepts, or changing how it validates, needs baseline evidence.
|
||||
*/
|
||||
describe("FE-REG-API compatibility of descriptor wire values", () => {
|
||||
async function snapshotOf(
|
||||
rows: Readonly<Record<string, unknown>>,
|
||||
): Promise<Readonly<Record<string, unknown>>> {
|
||||
const governance = JSON.parse(
|
||||
await readFile("config/contracts/registry-governance.json", "utf8"),
|
||||
) as {
|
||||
registries: Array<{
|
||||
registryId: string;
|
||||
breakingFields: string[];
|
||||
fieldTypes: Record<string, string>;
|
||||
}>;
|
||||
};
|
||||
const api = governance.registries.find(
|
||||
(registry) => registry.registryId === "FE-REG-API",
|
||||
)!;
|
||||
return {
|
||||
registries: [
|
||||
{
|
||||
registryId: "FE-REG-API",
|
||||
contract: {
|
||||
breakingFields: api.breakingFields,
|
||||
fieldTypes: api.fieldTypes,
|
||||
},
|
||||
rows: canonicalizeRegistryValue(rows),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
const rowsWith = (
|
||||
contract: Partial<typeof TEST_CREATE_HTTP_CONTRACT.contract> = {},
|
||||
frontend: Partial<typeof TEST_CREATE_HTTP_CONTRACT.frontend> = {},
|
||||
) =>
|
||||
projectApiOperationRows(
|
||||
composeContractContributions([
|
||||
{
|
||||
...TEST_CONTRACT_CONTRIBUTION,
|
||||
http: [
|
||||
{
|
||||
contract: {
|
||||
...TEST_CREATE_HTTP_CONTRACT.contract,
|
||||
acceptedStatuses: [200, 201],
|
||||
emptyBodyStatuses: [201],
|
||||
...contract,
|
||||
},
|
||||
frontend: { ...TEST_CREATE_HTTP_CONTRACT.frontend, ...frontend },
|
||||
},
|
||||
] as never,
|
||||
},
|
||||
]).contributions,
|
||||
);
|
||||
async function changesFor(after: Readonly<Record<string, unknown>>) {
|
||||
const diff = diffRegistrySnapshots(
|
||||
await snapshotOf(rowsWith()),
|
||||
await snapshotOf(after),
|
||||
);
|
||||
return diff.changes.map(({ changeId, impact }) => `${changeId} ${impact}`);
|
||||
}
|
||||
|
||||
it.each([
|
||||
[
|
||||
"a narrowed status list",
|
||||
{ acceptedStatuses: [201] },
|
||||
{},
|
||||
[
|
||||
"FE-REG-API:TEST_CREATE_ENTITY:acceptedStatuses:allowed-value-removed breaking",
|
||||
],
|
||||
],
|
||||
[
|
||||
"a narrowed empty-body list",
|
||||
{ emptyBodyStatuses: [] },
|
||||
{},
|
||||
[
|
||||
"FE-REG-API:TEST_CREATE_ENTITY:emptyBodyStatuses:allowed-value-removed breaking",
|
||||
],
|
||||
],
|
||||
[
|
||||
"another problem schema",
|
||||
{
|
||||
problemValidator: {
|
||||
...TEST_CREATE_HTTP_CONTRACT.contract.problemValidator,
|
||||
schemaId: "OtherProblem",
|
||||
},
|
||||
},
|
||||
{},
|
||||
["FE-REG-API:TEST_CREATE_ENTITY:problemSchema:field-changed breaking"],
|
||||
],
|
||||
[
|
||||
"an output whose validation is skipped",
|
||||
{ outputValidator: unvalidatedPayload("TestEntityPayload", "trusted") },
|
||||
{},
|
||||
["FE-REG-API:TEST_CREATE_ENTITY:unvalidated:field-changed breaking"],
|
||||
],
|
||||
[
|
||||
"a widened status list",
|
||||
{ acceptedStatuses: [200, 201, 202] },
|
||||
{},
|
||||
[
|
||||
"FE-REG-API:TEST_CREATE_ENTITY:acceptedStatuses:field-changed behavior-change",
|
||||
],
|
||||
],
|
||||
[
|
||||
"a larger response limit and a longer deadline",
|
||||
{},
|
||||
{ responseByteLimit: 8_388_608, totalDeadlineMs: 60_000 },
|
||||
[
|
||||
"FE-REG-API:TEST_CREATE_ENTITY:responseByteLimit:field-changed behavior-change",
|
||||
"FE-REG-API:TEST_CREATE_ENTITY:totalDeadlineMs:field-changed behavior-change",
|
||||
],
|
||||
],
|
||||
[
|
||||
"a traffic policy",
|
||||
{},
|
||||
{
|
||||
traffic: {
|
||||
maxPhysicalRequests: 1,
|
||||
maxRetries: 0,
|
||||
maxConcurrentRequests: 1,
|
||||
maxQueuedRequests: 0,
|
||||
},
|
||||
},
|
||||
["FE-REG-API:TEST_CREATE_ENTITY:traffic:field-changed behavior-change"],
|
||||
],
|
||||
[
|
||||
"a status classifier",
|
||||
{
|
||||
commandEffect: TEST_CLASSIFIED_CREATE_HTTP_CONTRACT.contract.commandEffect,
|
||||
},
|
||||
{},
|
||||
[
|
||||
"FE-REG-API:TEST_CREATE_ENTITY:commandEffect:field-changed behavior-change",
|
||||
],
|
||||
],
|
||||
] as const)("grades %s", async (_name, contract, frontend, expected) => {
|
||||
expect(await changesFor(rowsWith(contract as never, frontend as never))).toEqual(
|
||||
expected,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -115,6 +115,16 @@ const snapshotOperation: ApiOperationRow = Object.freeze({
|
||||
requestSchema: "NoRequest",
|
||||
responseSchema: "ReferenceRealtimeCheckpoint",
|
||||
problemSchema: "ReferenceRealtimeProblem",
|
||||
acceptedStatuses: [200],
|
||||
emptyBodyStatuses: [],
|
||||
unvalidated: [],
|
||||
requestByteLimit: 0,
|
||||
responseByteLimit: 32_768,
|
||||
totalDeadlineMs: 10_000,
|
||||
retryBudget: 2,
|
||||
traffic: null,
|
||||
commandEffect: null,
|
||||
commandRecovery: null,
|
||||
});
|
||||
|
||||
export const TEST_API_OPERATIONS = Object.freeze({
|
||||
|
||||
Reference in New Issue
Block a user