fix(contracts)!: HTTP descriptor의 responseEnvelope를 필수 칸으로 둔다
문제: responseEnvelope는 descriptor의 선택 칸이고 없으면 "NONE"이다.
1103/16-01 수정은 계약 조립이 한 기여 안에서 값이 섞이면 거부하고,
refusedBeforeWrite가 있는 쓰기에 Envelope를 요구하게 했다. 그러나 읽기만
있는 기여(기본 생성 판)나 refusedBeforeWrite 없는 쓰기에서 줄을 모두 빼면
조립은 통과하고(모두 같은 NONE), 짝 백엔드의 Envelope를 DTO로 읽어
SCHEMA_MISMATCH로 깨지는 것은 손글씨 gateway 테스트만 잡는다. 지난 완료
기준("줄을 지우면 check:types가 실패한다")을 채우지 못했다.
고른 방법(1103 대안 (b)): InstalledHttpContract의 contract.responseEnvelope를
필수로 바꾼다. 생성 기능·참조 기능·예제의 descriptor는 모두
`satisfies InstalledHttpContract<...>`라 줄을 지우면 tsc가 그 자리에서
실패한다. 줄이 없던 descriptor에 "NONE" as const를 적었다: 참조 기능 셋,
tests/helpers/external-contract-fixture.ts 셋,
tests/contract/reusable-capability/feature-http-binding.test.ts,
scripts/drill-runbook.ts. 값은 전과 같아 FE-REG-API 행과 레지스트리 기준선은
바뀌지 않는다. 조립(external-contract-runtime.ts)은 그대로 빠진 값을 NONE으로
읽는다: TypeScript 밖에서 만든 descriptor를 런타임에 거부하지 않는다.
생성기 주석의 "줄을 지운다" 안내를 "NONE을 적는다"로, 매뉴얼 01(3단계,
짝 백엔드가 아닌 백엔드), errors.md, 계약 문서 4.1절을 같은 뜻으로 고쳤다.
테스트: external-contract-runtime.test.ts에 줄을 뺀 descriptor 선언 위
@ts-expect-error를 두었다. 타입이 다시 선택 칸이 되면 그 지시문이 쓰이지
않아 check:types:test가 실패한다. 같은 테스트가 런타임 조립은 NONE으로
읽는지도 본다.
버린 대안: (c) 기여 단위 기본값 — 규칙이 하나 는다. (d)만으로 두기 — 모두
빠진 경우를 못 막는다. 조립에서 빠진 키를 거부 — JS로 만든 계약 패키지가
런타임에 깨지고, 빠진 값을 일부러 다루는 테스트를 모두 바꿔야 한다.
위험·한계: descriptor를 직접 쓰는 다운스트림 코드는 줄을 더할 때까지
check:types가 실패한다. 모든 operation에 같은 틀린 값을 적는 것(짝 백엔드인데
모두 "NONE")은 여전히 타입도 조립도 통과한다(매뉴얼 "못 잡음"). 이 노트북에서
tsc를 돌리지 못해, 놓친 descriptor가 있으면 desktop check:types가 알려 준다.
검증: desktop batch에서 확인.
corepack pnpm check:types
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/features/reference-feature tests/unit/api-operation-rows.test.ts
corepack pnpm check:registries (compatibility 변화 없음 기대)
BREAKING CHANGE: src/contracts/external-contract-runtime.ts의
InstalledHttpContract에서 contract.responseEnvelope가 필수다. 이 줄이 없는
descriptor는 check:types에서 실패한다. 감싸지 않는 백엔드는
responseEnvelope: "NONE" as const, 짝 백엔드(Envelope)는 "ENVELOPE_V1" as const를
operation마다 적는다. 런타임 동작은 같다.
Refs: 1103/16-01
This commit is contained in:
@@ -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`).
|
||||
|
||||
@@ -211,9 +211,10 @@ FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-ope
|
||||
- 성공: `{ "success": true, "data": ..., "meta": ... }`
|
||||
- 실패: `{ "success": false, "error": { "code", ... }, "meta": ... }`
|
||||
- 이 모양을 읽게 하는 것은 V3 descriptor(`<base>-contract-contribution.ts`)의 한 줄 `responseEnvelope: "ENVELOPE_V1"`이다. 생성된 operation에는 모두 들어 있다.
|
||||
- operation을 손으로 더할 때마다 이 줄을 적는다. 이 값은 operation마다 따로다.
|
||||
- 한 계약 기여 안에서 이 값이 다른 operation이 있으면 계약 조립이 거부한다(`<id>/<operationId>: responseEnvelope NONE, but <other> 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이 있으면 계약 조립이 거부한다(`<id>/<operationId>: responseEnvelope NONE, but <other> 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`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다.
|
||||
|
||||
|
||||
@@ -104,7 +104,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
| `<id>/<operationId>: <GET·HEAD> is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>` | 읽기에 `KEYED`나 `NEVER`를 적었다 | V3 `retrySemantics`. 재시도를 막으려면 `frontend.retryBudget: 0` |
|
||||
| `<id>/<operationId>: command operations require a command effect descriptor` | 쓰기에 `commandEffect`가 없다 | V3 `commandEffect` |
|
||||
| `<id>/<operationId>: read operations carry no command descriptors` | GET에 `commandEffect`·`commandRecovery`를 적었다 | 둘 다 `null` |
|
||||
| `<id>/<operationId>: responseEnvelope NONE, but <other> in the same contribution reads ENVELOPE_V1; ...` | 한 계약 기여 안에서 operation 하나만 응답 모양이 다르다. 손으로 더한 operation에 `responseEnvelope` 줄을 빠뜨린 경우다 | 그 operation에 `responseEnvelope: "ENVELOPE_V1" as const`를 적는다. 정말 다른 백엔드면 기여를 나눈다 |
|
||||
| `<id>/<operationId>: responseEnvelope NONE, but <other> 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` |
|
||||
| `<id>: package version must be exact SemVer` | 버전 범위(`^1.2.0`)나 형식 오류 | `<BASE>_CONTRACT_PACKAGE.version` |
|
||||
|
||||
### 라우트·context
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -214,8 +214,8 @@ export interface InstalledHttpContract<Input, WireOutput, Problem> {
|
||||
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<Input, WireOutput, Problem> {
|
||||
* (`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<Problem> | null;
|
||||
/**
|
||||
|
||||
@@ -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<typeof referenceResourceListQuerySchema>) {
|
||||
@@ -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<typeof referenceResourceParamsSchema>) {
|
||||
@@ -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",
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user