diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 2d3a0391..5cf0ca2a 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -191,8 +191,9 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 바뀐 파일마다 다시 볼 프론트 위치를 말하며 1로 끝난다(1105/16-02). - 프론트에서 Envelope를 읽는 곳: `src/adapters/http/backend-envelope.ts`(스키마와 해석). V3 실행기는 descriptor가 `responseEnvelope: "ENVELOPE_V1"`일 때 쓴다. - `create:feature`가 만든 기능은 이 값을 선언한다. 참조 기능은 선언하지 않고 - DTO와 problem details를 검증한다. + `create:feature`가 만든 기능은 이 값을 선언한다. 참조 기능은 `"NONE"`을 + 선언하고 DTO와 problem details를 검증한다. 이 칸은 descriptor 타입의 필수 + 칸이라 빠뜨리면 `check:types`가 실패한다(1103/16-01). - 실패 Envelope의 `error.code`가 "적용 안 됨"인지는 6.1절이 정한다. - 페이지 목록의 `meta.page`(`number`·`size`·`total`·`sort`)는 기능의 `mapSuccess(value, { page })` 두 번째 인자로 간다(`FeatureHttpSuccessContext`). diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 347975f5..a1e86d12 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -211,9 +211,10 @@ FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-ope - 성공: `{ "success": true, "data": ..., "meta": ... }` - 실패: `{ "success": false, "error": { "code", ... }, "meta": ... }` - 이 모양을 읽게 하는 것은 V3 descriptor(`-contract-contribution.ts`)의 한 줄 `responseEnvelope: "ENVELOPE_V1"`이다. 생성된 operation에는 모두 들어 있다. - - operation을 손으로 더할 때마다 이 줄을 적는다. 이 값은 operation마다 따로다. - - 한 계약 기여 안에서 이 값이 다른 operation이 있으면 계약 조립이 거부한다(`/: responseEnvelope NONE, but in the same contribution reads ENVELOPE_V1; ...`). 기여 하나는 백엔드 하나의 패키지라서다. 그래서 줄을 빠뜨리면 앱을 조립하는 테스트와 `check:registries`가 실패한다. - - **못 잡음**: 기여 안의 operation 모두에서 이 줄을 빼는 것. 그때는 아래 MSW 줄의 손글씨 gateway 테스트만 잡는다. + - operation을 손으로 더할 때마다 이 줄을 적는다. 이 값은 operation마다 따로다. 감싸지 않는 백엔드면 `"NONE"`을 적는다. 줄은 빼지 않는다. + - 줄을 빠뜨리면 `check:types`가 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 실패한다(`Property 'responseEnvelope' is missing ...`, 1103/16-01). 기여 안의 operation 모두에서 빼도 같다. + - 한 계약 기여 안에서 이 값이 다른 operation이 있으면 계약 조립이 거부한다(`/: responseEnvelope NONE, but in the same contribution reads ENVELOPE_V1; ...`). 기여 하나는 백엔드 하나의 패키지라서다. 그래서 값을 잘못 적으면 앱을 조립하는 테스트와 `check:registries`가 실패한다. + - **못 잡음**: 기여 안의 operation 모두에 같은 틀린 값을 적는 것(짝 백엔드인데 모두 `"NONE"`). 그때는 아래 MSW 줄의 손글씨 gateway 테스트만 잡는다. ```text 성공 status → Envelope 확인 → data를 outputValidator로 검증 → mapSuccess @@ -236,7 +237,7 @@ FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-ope DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 백엔드에 붙일 때: -1. descriptor에서 `responseEnvelope` 줄을 지운다. +1. 모든 descriptor의 `responseEnvelope`를 `"NONE" as const`로 바꾼다. 줄을 지우면 `check:types`가 실패한다. 2. problem 스키마를 problem details 모양으로 바꾼다. 3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다. diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index d1b3ed55..2ac31436 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -104,7 +104,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `/: is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>` | 읽기에 `KEYED`나 `NEVER`를 적었다 | V3 `retrySemantics`. 재시도를 막으려면 `frontend.retryBudget: 0` | | `/: command operations require a command effect descriptor` | 쓰기에 `commandEffect`가 없다 | V3 `commandEffect` | | `/: read operations carry no command descriptors` | GET에 `commandEffect`·`commandRecovery`를 적었다 | 둘 다 `null` | -| `/: responseEnvelope NONE, but in the same contribution reads ENVELOPE_V1; ...` | 한 계약 기여 안에서 operation 하나만 응답 모양이 다르다. 손으로 더한 operation에 `responseEnvelope` 줄을 빠뜨린 경우다 | 그 operation에 `responseEnvelope: "ENVELOPE_V1" as const`를 적는다. 정말 다른 백엔드면 기여를 나눈다 | +| `/: responseEnvelope NONE, but in the same contribution reads ENVELOPE_V1; ...` | 한 계약 기여 안에서 operation 하나만 응답 모양이 다르다. 손으로 더한 operation에 `"NONE"`을 적었거나, TypeScript 밖에서 만든 descriptor가 줄을 뺐다 | 그 operation에 `responseEnvelope: "ENVELOPE_V1" as const`를 적는다. 정말 다른 백엔드면 기여를 나눈다 | +| `check:types`: `Property 'responseEnvelope' is missing in type ...` (descriptor의 `satisfies InstalledHttpContract<...>`) | descriptor에 응답 모양 줄이 없다. 1103/16-01부터 필수 칸이다 | 짝 백엔드면 `responseEnvelope: "ENVELOPE_V1" as const`, 감싸지 않는 백엔드면 `"NONE" as const` | | `: package version must be exact SemVer` | 버전 범위(`^1.2.0`)나 형식 오류 | `_CONTRACT_PACKAGE.version` | ### 라우트·context diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index 3e2e5463..9654aaa6 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -794,8 +794,9 @@ export const ${operationId}_CONTRACT = Object.freeze({ responseBody: "REQUIRED_JSON" as const, // The paired backend wraps every JSON body (http-contract.md §1). Every // operation of this contribution says so (1103/16-01: composition refuses - // one that does not). Drop the line from all of them for a backend that - // sends the DTO and problem details bare. + // one that does not, and check:types one without the line). Write + // "NONE" on all of them for a backend that sends the DTO and problem + // details bare. responseEnvelope: "ENVELOPE_V1" as const, commandRecovery: null, commandEffect: null, diff --git a/scripts/drill-runbook.ts b/scripts/drill-runbook.ts index c1c8c987..1607a8fd 100644 --- a/scripts/drill-runbook.ts +++ b/scripts/drill-runbook.ts @@ -287,6 +287,7 @@ async function physicalAttempts( retrySemantics, requestBody: read ? ("NONE" as const) : ("JSON" as const), responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: null, commandEffect: read ? null diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index f89f2e18..62065c47 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -214,8 +214,8 @@ export interface InstalledHttpContract { requestBody: "NONE" | "JSON"; responseBody: "REQUIRED_JSON" | "OPTIONAL_JSON" | "NONE"; /** - * 1101 README 14.3. How the server frames a JSON body. Absent or `"NONE"`: - * the body is the DTO, and a failure body is the problem. `"ENVELOPE_V1"`: + * 1101 README 14.3. How the server frames a JSON body. `"NONE"`: the body + * is the DTO, and a failure body is the problem. `"ENVELOPE_V1"`: * the paired backend's `{ success, data | error, meta }` * (clean-architecture-backend-template docs/web/http-contract.md §1). * `outputValidator` then sees `data` (`null` when the key is absent) and @@ -224,8 +224,16 @@ export interface InstalledHttpContract { * (`src/adapters/http/backend-envelope.ts`, the frontend contract's 6.1), * not from `commandEffect.classifyProblem`, which decides every other * status. A body that is empty by `emptyBodyStatuses` has no Envelope. + * + * 1103/16-01. Required: an operation added by hand without the line read + * the real backend's Envelope as a DTO, and assembly cannot tell a + * forgotten line from a bare backend when every operation of a + * contribution forgot it (a read-only contribution, or a write without + * `refusedBeforeWrite`). `check:types` now fails on the descriptor. A + * descriptor typed outside TypeScript that leaves it out still composes + * and reads as `"NONE"`. */ - responseEnvelope?: ResponseEnvelope; + responseEnvelope: ResponseEnvelope; commandRecovery: CommandRecoveryDescriptor | null; commandEffect: CommandEffectDescriptor | null; /** diff --git a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts index b01ee5ba..08ada1ca 100644 --- a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts +++ b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts @@ -88,6 +88,7 @@ export const LIST_REFERENCE_RESOURCES_CONTRACT = Object.freeze({ retrySemantics: "SAFE" as const, requestBody: "NONE" as const, responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: null, commandEffect: null, projectRequest(input: z.output) { @@ -142,6 +143,7 @@ export const GET_REFERENCE_RESOURCE_CONTRACT = Object.freeze({ retrySemantics: "SAFE" as const, requestBody: "NONE" as const, responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: null, commandEffect: null, projectRequest(input: z.output) { @@ -192,6 +194,7 @@ export const CREATE_REFERENCE_RESOURCE_CONTRACT = Object.freeze({ retrySemantics: "KEYED" as const, requestBody: "JSON" as const, responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: Object.freeze({ mode: "IDEMPOTENCY_REPLAY" as const, operationIdentityField: "idempotencyKey", diff --git a/tests/contract/reusable-capability/feature-http-binding.test.ts b/tests/contract/reusable-capability/feature-http-binding.test.ts index 22bbf86c..b96600b5 100644 --- a/tests/contract/reusable-capability/feature-http-binding.test.ts +++ b/tests/contract/reusable-capability/feature-http-binding.test.ts @@ -44,6 +44,7 @@ const LOAD_RESOURCE_CONTRACT = Object.freeze({ retrySemantics: "SAFE" as const, requestBody: "NONE" as const, responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: null, commandEffect: null, projectRequest(input: ResourceInput) { diff --git a/tests/helpers/external-contract-fixture.ts b/tests/helpers/external-contract-fixture.ts index a65e5f74..dc67cd01 100644 --- a/tests/helpers/external-contract-fixture.ts +++ b/tests/helpers/external-contract-fixture.ts @@ -64,6 +64,7 @@ export const TEST_LIST_HTTP_CONTRACT: InstalledHttpContract< retrySemantics: "SAFE" as const, requestBody: "NONE" as const, responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: null, commandEffect: null, projectRequest(input: Readonly<{ limit: number }>) { @@ -99,6 +100,7 @@ export const TEST_DETAIL_HTTP_CONTRACT: InstalledHttpContract< retrySemantics: "SAFE" as const, requestBody: "NONE" as const, responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: null, commandEffect: null, projectRequest(input: Readonly<{ entityId: string }>) { @@ -145,6 +147,7 @@ export const TEST_CREATE_HTTP_CONTRACT: InstalledHttpContract< retrySemantics: "KEYED" as const, requestBody: "JSON" as const, responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "NONE" as const, commandRecovery: Object.freeze({ mode: "IDEMPOTENCY_REPLAY" as const, operationIdentityField: "idempotencyKey", diff --git a/tests/unit/external-contract-runtime.test.ts b/tests/unit/external-contract-runtime.test.ts index 564be7e6..109f5801 100644 --- a/tests/unit/external-contract-runtime.test.ts +++ b/tests/unit/external-contract-runtime.test.ts @@ -370,6 +370,26 @@ describe("one wire frame per contribution (1103/16-01)", () => { expect(composed.contributions.map(({ http }) => http.length)).toEqual([1, 2]); }); + + /** + * 1103/16-01 (rest). Assembly cannot tell a forgotten line from a bare + * backend when every operation of a contribution forgot it: a read-only + * contribution, or a write without `refusedBeforeWrite`. The line is + * required by the descriptor type, so `check:types` fails on such a + * descriptor (the directive below fails it when the type stops requiring + * the line). A descriptor typed outside TypeScript still composes as NONE. + */ + it("requires the line on every descriptor at compile time", () => { + const { responseEnvelope: _dropped, ...withoutLine } = listRow.contract; + // @ts-expect-error 1103/16-01: responseEnvelope is required on a descriptor. + const descriptor: InstalledContractContribution["http"][number] = { ...listRow, contract: withoutLine }; + + const composed = composeContractContributions([contribution("read-only", [descriptor])]); + + expect( + composed.httpByOperationId.get("TEST_LIST_ENTITIES")?.contract.responseEnvelope ?? "NONE", + ).toBe("NONE"); + }); }); // The sample feature's own cases (its fixture composes, a second one does not)