From 08ed0a088d023656f40c670aa7c4740a718bec59 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:24:41 +0900 Subject: [PATCH] =?UTF-8?q?fix(contracts)!:=20FE-REG-API=20=ED=96=89?= =?UTF-8?q?=EC=97=90=20status=20=EB=AA=A9=EB=A1=9D=C2=B7=EC=83=81=ED=95=9C?= =?UTF-8?q?=C2=B7=EC=9E=AC=EC=8B=9C=EB=8F=84=20=EC=98=88=EC=82=B0=C2=B7?= =?UTF-8?q?=EA=B2=80=EC=A6=9D=20=EC=83=9D=EB=9E=B5=EC=9D=84=20=EB=8B=B4?= =?UTF-8?q?=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 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절 --- .../contracts/registry-baseline.approval.json | 6 +- config/contracts/registry-baseline.json | 105 ++++++++- config/contracts/registry-governance.json | 28 ++- docs/manual/01-add-a-feature.md | 6 +- src/contracts/api-operations.ts | 87 +++++++ tests/unit/api-operation-rows.test.ts | 223 ++++++++++++++++++ tests/unit/realtime/fixture.ts | 10 + 7 files changed, 451 insertions(+), 14 deletions(-) diff --git a/config/contracts/registry-baseline.approval.json b/config/contracts/registry-baseline.approval.json index 7f1f1b88..fad51b0f 100644 --- a/config/contracts/registry-baseline.approval.json +++ b/config/contracts/registry-baseline.approval.json @@ -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" } diff --git a/config/contracts/registry-baseline.json b/config/contracts/registry-baseline.json index f01ec895..01e176d5 100644 --- a/config/contracts/registry-baseline.json +++ b/config/contracts/registry-baseline.json @@ -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", diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index 23aa7522..71add621 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.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" ] }, { diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 8382286d..f9a74029 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -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: ` - 지금 diff와 맞지 않는 증거 행이 남으면 `stale breaking evidence : ...`로 실패한다. - **못 잡음**: 사람이 서명하지 않은 a11y 기록은 merge 게이트를 통과한다. 릴리스 게이트 FE-GATE-028이 막는다. +- **못 잡음**: descriptor의 함수는 행에 없다. `classifyProblem`·`classifyStatus`가 무엇을 `NOT_APPLIED`로 보는지, `projectRequest`가 무엇을 보내는지는 PR에서 본다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` diff --git a/src/contracts/api-operations.ts b/src/contracts/api-operations.ts index 4d7b496c..ae9bc4c3 100644 --- a/src/contracts/api-operations.ts +++ b/src/contracts/api-operations.ts @@ -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>>, +): 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; + // 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)) } + : {}), + }); +} diff --git a/tests/unit/api-operation-rows.test.ts b/tests/unit/api-operation-rows.test.ts index fac6639b..fc597cd5 100644 --- a/tests/unit/api-operation-rows.test.ts +++ b/tests/unit/api-operation-rows.test.ts @@ -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>, + ): Promise>> { + const governance = JSON.parse( + await readFile("config/contracts/registry-governance.json", "utf8"), + ) as { + registries: Array<{ + registryId: string; + breakingFields: string[]; + fieldTypes: Record; + }>; + }; + 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 = {}, + frontend: Partial = {}, + ) => + 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>) { + 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, + ); + }); +}); diff --git a/tests/unit/realtime/fixture.ts b/tests/unit/realtime/fixture.ts index 372db896..fe64d75c 100644 --- a/tests/unit/realtime/fixture.ts +++ b/tests/unit/realtime/fixture.ts @@ -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({