diff --git a/config/contracts/registry-baseline.approval.json b/config/contracts/registry-baseline.approval.json index ea584524..7f1f1b88 100644 --- a/config/contracts/registry-baseline.approval.json +++ b/config/contracts/registry-baseline.approval.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, - "snapshotDigest": "3c3702b55ad8849f399833206ea4515808eda6ab6d1fd5c49e90f8579e644170", + "snapshotDigest": "16f727424579279e0ef810620f672a8a9d74de6b71e3e9ce37ab07a82f645588", "owner": "DongHyeonka", - "reason": "2026-11-03 사용자가 결정을 위임함: 0929/07-03, 1101/16-03, 15-01 source 경로. 승인 뒤 쌓인 0925/08-13·1101/05-01(증거로 유지), VITE_BUILD_ID 기본값·service-worker.start.failed 행(증거 불필요)도 함께 흡수", - "approvedAt": "2026-11-02T15:53:54.852Z" + "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" } diff --git a/config/contracts/registry-baseline.json b/config/contracts/registry-baseline.json index 4294d79f..f01ec895 100644 --- a/config/contracts/registry-baseline.json +++ b/config/contracts/registry-baseline.json @@ -330,30 +330,32 @@ "rowCount": 3, "contract": { "requiredFields": [ + "operationId", + "featureId", "method", "path", - "operationId", - "auth", - "timeoutMs", - "idempotency", - "retry", - "requestSource", + "authProfileId", + "retrySemantics", + "requestBody", + "responseBody", + "responseEnvelope", "requestSchema", "responseSchema", - "owner" + "problemSchema" ], "fieldTypes": { + "operationId": "string", + "featureId": "string", "method": "string", "path": "string", - "operationId": "string", - "auth": "string", - "timeoutMs": "integer|null", - "idempotency": "string", - "retry": "string", - "requestSource": "string", + "authProfileId": "string", + "retrySemantics": "string", + "requestBody": "string", + "responseBody": "string", + "responseEnvelope": "string", "requestSchema": "string", "responseSchema": "string", - "owner": "string" + "problemSchema": "string" }, "uniqueFields": [ "operationId" @@ -361,28 +363,30 @@ "allowedValues": { "method": [ "GET", + "HEAD", "POST", "PUT", "PATCH", "DELETE" ], - "auth": [ - "none", - "external-session" + "retrySemantics": [ + "SAFE", + "IDEMPOTENT", + "KEYED", + "NEVER" ], - "idempotency": [ - "safe", - "keyed", - "none" + "requestBody": [ + "NONE", + "JSON" ], - "retry": [ - "runtime", - "never" + "responseBody": [ + "REQUIRED_JSON", + "OPTIONAL_JSON", + "NONE" ], - "requestSource": [ - "none", - "search", - "body" + "responseEnvelope": [ + "NONE", + "ENVELOPE_V1" ] }, "references": [ @@ -399,115 +403,60 @@ ], "keyField": "operationId", "breakingFields": [ + "operationId", "method", "path", - "operationId", - "auth", - "idempotency", - "requestSource", + "authProfileId", + "retrySemantics", + "requestBody", + "responseBody", + "responseEnvelope", "requestSchema", "responseSchema" ] }, "rows": { "CREATE_REFERENCE_RESOURCE": { - "auth": "external-session", "authProfileId": "EXTERNAL_BEARER", - "contractVersion": 2, - "csrfProfileId": "NO_CSRF_BEARER", - "idempotency": "keyed", - "idempotencyKeyPolicy": "REQUIRED", - "mapperId": "ReferenceResourceMapper", - "maxEncodedSearchBytes": 0, - "maxResponseBytes": 32768, + "featureId": "reference-feature", "method": "POST", "operationId": "CREATE_REFERENCE_RESOURCE", - "owner": "feature-frontend-reference-feature-vertical-slice", "path": "/api/reference-resources", - "pathParameterNames": [], - "pathSchema": "NoRequest", - "protocol": "REST", - "providerId": "PRIMARY_API", - "replayPolicy": "KEYED_COMMAND", + "problemSchema": "ReferenceProblem", + "requestBody": "JSON", "requestSchema": "CreateReferenceResourceCommand", - "requestSource": "body", - "responseMediaTypes": [ - "application/json" - ], + "responseBody": "REQUIRED_JSON", + "responseEnvelope": "NONE", "responseSchema": "ReferenceResourcePayload", - "retry": "runtime", - "semantics": "COMMAND", - "successStatuses": [ - 200, - 201 - ], - "timeoutMs": null + "retrySemantics": "KEYED" }, "GET_REFERENCE_RESOURCE": { - "auth": "external-session", "authProfileId": "EXTERNAL_BEARER", - "contractVersion": 2, - "csrfProfileId": "NO_CSRF_BEARER", - "idempotency": "safe", - "idempotencyKeyPolicy": "NONE", - "mapperId": "ReferenceResourceMapper", - "maxEncodedSearchBytes": 0, - "maxResponseBytes": 32768, + "featureId": "reference-feature", "method": "GET", "operationId": "GET_REFERENCE_RESOURCE", - "owner": "feature-frontend-reference-feature-vertical-slice", "path": "/api/reference-resources/{resourceId}", - "pathParameterNames": [ - "resourceId" - ], - "pathSchema": "ReferenceResourceParams", - "protocol": "REST", - "providerId": "PRIMARY_API", - "replayPolicy": "SAFE", - "requestSchema": "NoRequest", - "requestSource": "none", - "responseMediaTypes": [ - "application/json" - ], + "problemSchema": "ReferenceProblem", + "requestBody": "NONE", + "requestSchema": "ReferenceResourceParams", + "responseBody": "REQUIRED_JSON", + "responseEnvelope": "NONE", "responseSchema": "ReferenceResourcePayload", - "retry": "runtime", - "semantics": "QUERY", - "successStatuses": [ - 200 - ], - "timeoutMs": null + "retrySemantics": "SAFE" }, "LIST_REFERENCE_RESOURCES": { - "auth": "external-session", "authProfileId": "EXTERNAL_BEARER", - "contractVersion": 2, - "csrfProfileId": "NO_CSRF_BEARER", - "idempotency": "safe", - "idempotencyKeyPolicy": "NONE", - "mapperId": "ReferenceResourceListMapper", - "maxEncodedSearchBytes": 4096, - "maxResponseBytes": 262144, + "featureId": "reference-feature", "method": "GET", "operationId": "LIST_REFERENCE_RESOURCES", - "owner": "feature-frontend-reference-feature-vertical-slice", "path": "/api/reference-resources", - "pathParameterNames": [], - "pathSchema": "NoRequest", - "protocol": "REST", - "providerId": "PRIMARY_API", - "replayPolicy": "SAFE", + "problemSchema": "ReferenceProblem", + "requestBody": "NONE", "requestSchema": "ReferenceResourceListQuery", - "requestSource": "search", - "responseMediaTypes": [ - "application/json" - ], + "responseBody": "REQUIRED_JSON", + "responseEnvelope": "NONE", "responseSchema": "ReferenceResourceListPayload", - "retry": "runtime", - "semantics": "QUERY", - "successStatuses": [ - 200 - ], - "timeoutMs": null + "retrySemantics": "SAFE" } } }, @@ -515,7 +464,7 @@ "registryId": "FE-REG-SCHEMA", "owner": "feature-frontend-contract-schema-registry", "source": "src/features/loaded-feature-runtimes.ts", - "rowCount": 8, + "rowCount": 7, "contract": { "requiredFields": [ "schemaId", @@ -568,15 +517,6 @@ "runtime": "zod", "schemaId": "none" }, - "NoRequest": { - "boundary": "api-request", - "direction": "REQUEST", - "owner": "feature-frontend-reference-feature-vertical-slice", - "runtime": "zod", - "schemaId": "NoRequest", - "schemaVersion": 1, - "unknownFieldPolicy": "REJECT_UNKNOWN" - }, "NotFoundSplat": { "boundary": "route-params", "owner": "feature-frontend-routing-release-recovery-runtime", diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index c4a71cf5..23aa7522 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.json @@ -138,38 +138,64 @@ "owner": "feature-frontend-api-client-response-envelope-contract", "keyField": "operationId", "requiredFields": [ + "operationId", + "featureId", "method", "path", - "operationId", - "auth", - "timeoutMs", - "idempotency", - "retry", - "requestSource", + "authProfileId", + "retrySemantics", + "requestBody", + "responseBody", + "responseEnvelope", "requestSchema", "responseSchema", - "owner" + "problemSchema" ], "fieldTypes": { + "operationId": "string", + "featureId": "string", "method": "string", "path": "string", - "operationId": "string", - "auth": "string", - "timeoutMs": "integer|null", - "idempotency": "string", - "retry": "string", - "requestSource": "string", + "authProfileId": "string", + "retrySemantics": "string", + "requestBody": "string", + "responseBody": "string", + "responseEnvelope": "string", "requestSchema": "string", "responseSchema": "string", - "owner": "string" + "problemSchema": "string" }, - "uniqueFields": ["operationId"], + "uniqueFields": [ + "operationId" + ], "allowedValues": { - "method": ["GET", "POST", "PUT", "PATCH", "DELETE"], - "auth": ["none", "external-session"], - "idempotency": ["safe", "keyed", "none"], - "retry": ["runtime", "never"], - "requestSource": ["none", "search", "body"] + "method": [ + "GET", + "HEAD", + "POST", + "PUT", + "PATCH", + "DELETE" + ], + "retrySemantics": [ + "SAFE", + "IDEMPOTENT", + "KEYED", + "NEVER" + ], + "requestBody": [ + "NONE", + "JSON" + ], + "responseBody": [ + "REQUIRED_JSON", + "OPTIONAL_JSON", + "NONE" + ], + "responseEnvelope": [ + "NONE", + "ENVELOPE_V1" + ] }, "references": [ { @@ -189,12 +215,14 @@ "src/features/*/application" ], "breakingFields": [ + "operationId", "method", "path", - "operationId", - "auth", - "idempotency", - "requestSource", + "authProfileId", + "retrySemantics", + "requestBody", + "responseBody", + "responseEnvelope", "requestSchema", "responseSchema" ] diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 772be5ca..b3ddcad8 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -546,12 +546,12 @@ query invalidate hint로만 쓸지 operation별 reducer contract가 필요하다 같은 이름의 정책이라도 전송마다 동작이 다르다. operation을 다른 전송으로 옮기면 이 표로 동작 변화를 확인한다. -| 규칙 | V3 contract executor (기본 경로) | V2 client (기본 조합에 없음) | Browser RPC | -|---|---|---|---| -| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | 네트워크·타임아웃·429·408/425/502/503/504 뒤 같은 키로 다시 보낸다. 전송 여부를 보지 않는다 (`src/adapters/http/retry-policy.ts` `shouldRetry`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) | -| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | `MAX_RETRY_ATTEMPTS`, 기본 2 (`client.ts` `maxRetryAttempts`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) | -| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | 30초를 넘으면 재시도하지 않는다. 이하면 max(backoff, hint)만큼 기다린다 (`retry-policy.ts`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) | -| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 기본값이다. operation `timeoutMs`가 있으면 그 값을 쓰고, 더 길 수도 있다 (`client.ts` `defaultTimeoutMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 | +| 규칙 | V3 contract executor | Browser RPC | +|---|---|---| +| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) | +| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) | +| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) | +| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 | 결과 불명 뒤 사용자 재전송은 전송과 무관하게 같은 intent·같은 키를 쓴다 (`src/presentation/adapters/query/application-query.ts` `resendUnknownEffect`). diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 620edd09..054d2342 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -141,10 +141,9 @@ selected app. Every build and check script runs it first; run it yourself with entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip (`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB). - An HTTP API is written twice: its API contract operation (V2) is what - `check:registries` governs, and its contract contribution descriptor (V3) - is what executes. `tests/unit/http-operation-v2-v3-parity.test.ts` fails - when one exists without the other or when they disagree. + An HTTP API is written once, as its contract contribution descriptor: it + executes, and `check:registries` governs the FE-REG-API row projected from + it (`projectApiOperationRows` in `src/contracts/api-operations.ts`). A product feature's contract contribution uses an `EXTERNAL_PACKAGE` source. `TEMPLATE_FIXTURE` belongs to `reference-feature` only and never joins the release contract set; the composer rejects it anywhere else. diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 2a6c6858..8382286d 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -158,12 +158,12 @@ corepack pnpm create:feature invoice-feature 생성된 파일: - `contracts/-feature-contract.ts`: 선언 쪽. 라우트, 무효화, 계약 패키지 신원(`contractPackages`). -- `contracts/-api-contract.ts`: V2 행. `check:registries`가 검사하는 선언이다. -- `contracts/-contract-contribution.ts`: V3 descriptor. 실제로 실행되는 HTTP 계약이다. +- `contracts/-contract-contribution.ts`: HTTP 계약(descriptor). operation을 적는 곳은 여기 하나다. 이것이 실행되고, `check:registries`의 FE-REG-API 행도 여기서 뽑는다. +- `contracts/-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행). 스키마 ID마다 쓰이는 자리(`boundary`)와 소유자를 적는다. - `contracts/-schemas.ts`: zod 스키마와 검증기. - `contracts/-mapper.ts`: 와이어 값 → 화면 값. -같은 API를 V2와 V3로 두 번 쓴다. V2는 레지스트리 검사용 선언이고, V3는 실행용이다. +FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`). 같은 API를 다른 파일에 다시 적지 않는다. ① **정할 것** @@ -172,8 +172,8 @@ corepack pnpm create:feature invoice-feature - 재시도 의미(`retrySemantics`). [02 결정표 3절](02-decision-tables.md#3-재시도-의미) - 쓰기의 실패 분류(`commandEffect`). [02 결정표 4절](02-decision-tables.md#4-결과-불명) - 인증 프로필(`authProfileId`). [02 결정표 5절](02-decision-tables.md#5-인증) - - 바이트 한도·마감: V3 `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`. V2 `maxResponseBytes`는 V3 `responseByteLimit`와 같은 값이다. - - 스키마 ID, mapper ID, operation ID. 모두 기능 접두어를 붙인다([reference/global-ids.md](reference/global-ids.md)). + - 바이트 한도·마감: `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`. + - 스키마 ID, operation ID. 모두 기능 접두어를 붙인다([reference/global-ids.md](reference/global-ids.md)). ② **기준** @@ -203,8 +203,8 @@ corepack pnpm create:feature invoice-feature - 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다. - problem 스키마(`-schemas.ts`의 `ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다. - 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`가 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. -- `mapProblem`이 없거나 `undefined`를 돌려주면 V2 클라이언트와 같은 kind·code·필드 오류로 읽는다(`src/adapters/http/backend-envelope.ts`). -- 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. V2 `maxResponseBytes`와 같은 값이다. +- `mapProblem`이 없거나 `undefined`를 돌려주면 백엔드 code·필드 오류·status별 kind로 읽는다(`src/adapters/http/backend-envelope.ts`). +- 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. - MSW: `createHttpScenarioHandler`는 descriptor의 `responseEnvelope`를 보고 Envelope로 답한다(`tests/mocks/handlers/http-scenarios.ts`). 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 검사한다. - `http-contract.md`는 status·`code`의 **뜻**(예: 409 `IDEMPOTENT_IN_FLIGHT`)의 정본이다. 기능 코드에서 그 code는 problem의 `code`로 읽는다. @@ -218,69 +218,56 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 참조 기능(`src/features/reference-feature/`)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. -**V2 행의 입력 칸** +**입력과 스키마 메타데이터** -V2 행은 입력을 두 칸으로 나눠 적는다. 경로 파라미터는 `pathSchema`, 검색값·본문은 `requestSchema`다. V3는 입력 전체를 `inputValidator` 하나로 검증한다. +`inputValidator` 하나가 operation 입력 전체를 검증한다. 입력이 요청의 어디로 가는지는 `projectRequest`가 정한다. -정본: 칸 정의는 `src/contracts/api-operations.ts`(`RestOperationV2`, `validateRestOperation`), 스키마 칸은 `src/contracts/schema-registry.ts`(`SchemaDefinition`). 아래는 자주 바꾸고 자주 막히는 칸만 적는다. +- 경로 파라미터: `pathValues`. 키는 `pathTemplate`의 `{이름}`과 같다. +- 검색값: `queryEntries`. 인코딩한 쿼리는 8,192바이트까지다(`HTTP_EXECUTION_CEILINGS.encodedQueryBytes`). +- 본문: `body`. `requestBody: "JSON"`일 때만 쓴다. 아니면 `null`이다. -| 칸 | 뜻 | 값 고르는 법 | V3 짝 | -|---|---|---|---| -| `requestSource` | 입력이 요청의 어디로 가나 | `none`(입력 없음, 또는 경로 파라미터만), `search`(쿼리 문자열), `body`(JSON 본문) | `body`면 `requestBody: "JSON"`, 아니면 `"NONE"` | -| `requestSchema` | 검색값·본문 스키마 ID | `requestSource`가 `none`이면 기능의 빈 입력 스키마(`NoRequest`) | `requestSource`가 `none`이 아니면 `inputValidator`의 스키마 ID와 같다 | -| `pathSchema` | 경로 파라미터 스키마 ID. 비울 수 없다 | 경로 파라미터가 없으면 빈 입력 스키마 | 파라미터가 있으면 `inputValidator`의 스키마 ID와 같다 | -| `pathParameterNames` | `path`의 `{이름}` 목록 | `path`에 적은 이름과 정확히 같게. 없으면 `[]` | `projectRequest`가 돌려주는 `pathValues`의 키 | -| `maxEncodedSearchBytes` | 인코딩한 쿼리 문자열의 바이트 상한(0~32,768). V2 실행기만 읽는다 | 검색값이 없으면 0. 있으면 값의 최대 길이로 정한다(참조 기능 4,096) | 없음. V3는 고정 상한 8,192바이트(`HTTP_EXECUTION_CEILINGS.encodedQueryBytes`)를 쓴다 | -| 스키마 `boundary` | 그 스키마가 쓰이는 자리 | 아래 목록 | 없음 | +경로 파라미터와 본문을 함께 받는 operation(예: `PUT /items/{id}` + 본문)은 입력 스키마 하나에 둘을 담고 `projectRequest`가 나눈다. + +정본: descriptor 칸은 `src/contracts/external-contract-runtime.ts`(`InstalledHttpContract`), 스키마 메타데이터 칸은 `src/contracts/schema-registry.ts`(`SchemaDefinition`). 스키마 `boundary` 값: -- `route-params`: 라우트 경로 파라미터(`paramsSchema`). 같은 스키마를 GET의 `pathSchema`로도 쓴다. +- `route-params`: 라우트 경로 파라미터(`paramsSchema`). 같은 스키마를 경로 파라미터 GET의 `inputValidator`로도 쓴다. - `route-search`: 라우트 검색값에만 쓴다. - `route-search-api-request`: 라우트 검색값이면서 GET 쿼리다. 목록 검색이 이 경우다. -- `api-request`: 요청 본문, 그리고 빈 입력 스키마. +- `api-request`: 요청 입력. - `api-response`: 응답 DTO. -예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력 칸만 적었다. 나머지 칸은 생성된 행과 같다. +예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸만 적었다. ```ts -// GET /api/notices?q=... → V3 inputValidator: NoticeListQuery, projectRequest는 queryEntries를 채운다 -NOTICE_LIST_ITEMS: defineRestOperation({ - method: "GET", - path: "/api/notices", - requestSource: "search", - requestSchema: "NoticeListQuery", // boundary: "route-search-api-request" - pathSchema: "NoticeNoRequest", // boundary: "api-request" - pathParameterNames: [], - maxEncodedSearchBytes: 4_096, +// GET /api/notices?q=... inputValidator 스키마 NoticeListQuery (boundary: "route-search-api-request") +pathTemplate: "/api/notices", +inputValidator: zodValidator("NoticeListQuery", noticeListQuerySchema), +projectRequest: (input) => Object.freeze({ + pathValues: Object.freeze({}), + queryEntries: Object.freeze(input.q === undefined ? [] : [Object.freeze(["q", input.q] as const)]), + body: null, }), -// GET /api/notices/{noticeId} → V3 inputValidator: NoticeParams, projectRequest는 pathValues를 채운다 -NOTICE_GET_ITEM: defineRestOperation({ - method: "GET", - path: "/api/notices/{noticeId}", - requestSource: "none", - requestSchema: "NoticeNoRequest", - pathSchema: "NoticeParams", // boundary: "route-params" - pathParameterNames: ["noticeId"], - maxEncodedSearchBytes: 0, + +// GET /api/notices/{noticeId} inputValidator 스키마 NoticeParams (boundary: "route-params") +pathTemplate: "/api/notices/{noticeId}", +inputValidator: zodValidator("NoticeParams", noticeParamsSchema), +projectRequest: (input) => Object.freeze({ + pathValues: Object.freeze({ noticeId: input.noticeId }), + queryEntries: Object.freeze([]), + body: null, }), ``` -경로 파라미터와 검색값·본문을 함께 받는 operation(예: `PUT /items/{id}` + 본문)은 아직 규칙이 없다. V2/V3 일치 테스트가 `V2 declares both a path and a request schema; decide which V3 input schema matches them`로 실패한다. - ③ **잡는 검사 / 못 잡는 것** -- V2와 V3가 다르면 `tests/unit/http-operation-v2-v3-parity.test.ts`(`test:unit`, FE-GATE-005)가 실패한다. - - 비교하는 것: operation 목록, method, path, 성공 상태, 응답 한도, 인증 프로필, 재시도 의미, 쓰기 의미, 요청 본문, 스키마 ID. - - 마감 시간은 비교하지 않는다. V2 `timeoutMs`는 `null`이다. -- V2 입력 칸이 틀리면 모듈 로드 때 operation ID를 말하며 실패한다. - - `pathParameterNames`가 `path`의 이름과 다름: `REST path codec does not match its template: ` - - `pathSchema`가 비었거나 `maxEncodedSearchBytes`가 범위 밖: `Invalid REST operation contract: ` - - `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마: `Unresolved API schema binding: ` -- 인증 프로필 이름이 틀리면 operation을 적재하는 모든 게이트가 실패한다. - - 메시지: `REST security profiles are incoherent for : unknown authProfileId .` -- 스키마·mapper·operation ID가 겹치면 모듈 로드 때 그 ID를 말하며 실패한다. - - 예: `Invalid or duplicate schema definition: ` +- descriptor의 입력·응답 스키마 ID가 스키마 메타데이터에 없으면 `check:registries`가 실패한다. + - 메시지: `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` (`responseSchema`도 같다) +- 인증 프로필 이름이 틀리면 계약 조립이 거부해 operation을 적재하는 모든 게이트가 실패한다. + - 오류의 `reason`: `/: unknown authProfileId ` +- 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다. + - 예: `Invalid or duplicate schema definition: `, 계약 조립 `duplicate operation: ` - `TEMPLATE_FIXTURE` 출처를 참조 기능 밖에서 쓰면 계약 조립이 거부한다. - 오류의 `reason`: `: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE` - zod를 직접 import하면 `check:architecture`가 `zod-is-reached-through-contracts-zod`로 막는다. @@ -364,7 +351,7 @@ NOTICE_GET_ITEM: defineRestOperation({ - operation ID·route ID·입력 타입을 틀리면 `check:types`가 막는다. 음성 fixture: `check:types:fixture:http-operation-id`, `check:types:fixture:http-route-id`, `check:types:fixture:http-operation-input`. - 호스트가 주지 않는 capability를 `needs`에 적으면 조립이 실패한다. - 메시지: `feature needs , which the host did not provide` -- V2 operation을 선언하고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다. +- operation을 계약에 두고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다. - 메시지: `FE-REG-API. has no executable consumer for operationId=` - **못 잡음**: `routeId`가 실제로 요청을 보내는 화면과 다른 것. 타입은 기능의 route ID인지만 본다. - **못 잡음**: 기능 `contracts/`나 다섯 폴더 밖에 새로 만든 폴더(예: `hooks/`)를 거쳐 `src/adapters`에 닿는 import. `.dependency-cruiser.json`에 그 경로를 막는 규칙이 없다. 기능 안에는 `domain/`, `application/`, `contracts/`, `adapters/`, `presentation/` 다섯 폴더만 둔다. diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 61ceb487..352a80b4 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -88,8 +88,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 |---|---|---|---| | 서버 보장 | 멱등 키(`Idempotency-Key` 헤더)로 같은 요청의 중복 적용을 막는다 | 같은 요청을 여러 번 적용해도 결과가 같다 (키 없이) | 중복을 막지 못한다 | | 자동 재시도 | 실제로 보내기 전까지만. 보낸 뒤 결과를 모르면 결과 불명(4절)으로 넘긴다 | 된다 | 하지 않는다 | -| V3 | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 참조 기능은 `retryBudget: 0` | — | `retryBudget: 0` 필수 | -| V2 `replayPolicy` | `KEYED_COMMAND` | `IDEMPOTENT` | `NON_REPLAYABLE` | +| descriptor | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 참조 기능은 `retryBudget: 0` | — | `retryBudget: 0` 필수 | | 뮤테이션 정책 | `requiresIdempotencyKey: true` | — | — | - 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다. @@ -99,13 +98,12 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 **정본**: 백엔드가 멱등 키 요청에 어떻게 답하는지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2(멱등성 응답)다. 여기에 표를 옮기지 않는다. -**어디에 적나**: `contracts/-contract-contribution.ts`의 `retrySemantics`, `commandRecovery`, `frontend.retryBudget`. 같은 의미를 `contracts/-api-contract.ts`의 `replayPolicy`, `idempotency`, `idempotencyKeyPolicy`에도 적는다. +**어디에 적나**: `contracts/-contract-contribution.ts`의 `retrySemantics`, `commandRecovery`, `frontend.retryBudget`. 다른 파일에 다시 적지 않는다. **틀리면** - `NEVER`에 `retryBudget`을 0보다 크게 주면 계약 조립이 `retry budget contradicts NEVER retry semantics`로 거부한다. - `KEYED`에 `commandRecovery`가 없으면 `KEYED commands require a recovery descriptor`로 거부한다. -- V2와 V3의 재시도 의미가 다르면 `tests/unit/http-operation-v2-v3-parity.test.ts`가 실패한다. - 서버 보장과 다른 의미를 고른 것은 검사가 잡지 못한다. 근거: `scale-architecture.md` §13(재시도 모델). @@ -141,7 +139,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 같은 status라도 code로 나뉠 수 있다. 예: 409 중 "처리 중"은 `MAYBE_APPLIED`여야 한다. `NOT_APPLIED`로 보면 다음 저장이 새 키를 만들어 같은 작업이 두 번 적용된다. - 401·403·429는 문제 응답 본문을 읽기 전에 status로 나뉜다. 서버가 상태를 안 바꾼다고 보장하면 `classifyStatus`로 `NOT_APPLIED`를 돌려준다. 없으면 `MAYBE_APPLIED`다. - 문제 응답 본문이 기능의 problem 스키마를 통과하지 못하면 `classifyProblem`을 부르지 않는다. 쓰기는 `MAYBE_APPLIED`가 된다(`src/adapters/http/http-execution-v3.ts`). -- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다. V2 클라이언트도 같은 표를 쓴다. +- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다. - `NOT_APPLIED`(쓰기 전 거절): 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH` - `MAYBE_APPLIED`: 그 밖의 400·409·422. 409 `IDEMPOTENT_IN_FLIGHT`, `BAD_PARAMETER`, 도메인 code, fileserver의 422가 여기 든다. 그리고 503 `IDEMPOTENCY_UNAVAILABLE` - 짝 백엔드가 쓰기 전에 거절하는 code를 새로 만들면 계약 문서 6.1절과 이 표를 함께 고친다. 표에 없으면 `MAYBE_APPLIED`다 @@ -161,7 +159,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 → 결과 불명 화면 → "같은 요청으로 다시 보내기"가 같은 키로 보낸다 ``` -- V2 클라이언트(레거시)도 같다. V2와 V3 Envelope 경로가 같은 표(`src/adapters/http/backend-envelope.ts`)를 읽는다. V2는 `NOT_APPLIED`만 싣고 503은 effect 없이 돌아온다. 뮤테이션 조정자가 그것을 `MAYBE_APPLIED`로 본다(`src/presentation/adapters/query/application-query.ts`의 `mutationFailureWithEffect`). +- 뮤테이션 조정자는 effect가 없는 실패도 `MAYBE_APPLIED`로 본다(`src/presentation/adapters/query/application-query.ts`의 `mutationFailureWithEffect`). - 판정: 맞는다. 지금 동작은 `MAYBE_APPLIED`이고 재전송은 같은 키다. 백엔드가 요구하는 행동과 같다. - 다른 점은 화면뿐이다. 서버는 "실행 안 함"이라고 답했지만 화면은 "결과를 모른다"로 보여 준다. - `NOT_APPLIED`로 바꾸면 다음 저장이 새 키를 만든다. 키를 다시 쓰는 것은 결과 불명으로 남은 요청뿐이다(같은 파일). 백엔드가 말한 "같은 키"와 어긋난다. @@ -188,16 +186,15 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 | 언제 | 로그인 없이 부르는 API | 세션 토큰을 `authorization` 헤더로 보내는 API. 생성된 뼈대가 이것이다 | 위 둘로 안 되는 경우(쿠키 세션, 별도 토큰 등) | | 정의 | `src/contracts/rest-profiles.ts` (템플릿 소유) | 같은 파일 | `src/contracts/product-contracts.ts`의 `PRODUCT_REST_AUTH_PROFILES` (제품 소유) | | 자격 증명 | 없음 | 템플릿 세션 | `src/bootstrap/product-composition.ts`의 `credentialProviders` | -| V2 `auth` | `none` | `external-session` | 프로필에 맞게 | | 라우트 `access` | 보통 `public` | 보통 `session-required` | 프로필에 맞게 | - `REFERENCE_EXTERNAL_BEARER`는 `EXTERNAL_BEARER`의 옛 이름이다. `@deprecated`이고 한 릴리스 뒤 지운다. 새 코드는 쓰지 않는다. - 제품 프로필 ID는 템플릿 프로필 ID와 겹치면 안 된다. -- CSRF 프로필은 템플릿 상수(`REST_CSRF_PROFILES`)뿐이다. 제품이 더할 자리는 없다. 쿠키 인증은 인증 프로필의 헤더 집합으로 표현한다. 예제: `tests/unit/product-composition-fixture.test.ts`. +- 쿠키 인증과 CSRF 헤더는 인증 프로필의 헤더 집합으로 표현한다. 예제: `tests/unit/product-composition-fixture.test.ts`. **기준**: 백엔드가 그 API에 요구하는 인증을 따른다. 새 프로필은 템플릿 파일이 아니라 제품 소유 파일 두 곳에만 더한다. -**어디에 적나**: V3 `frontend.authProfileId`와 V2 `authProfileId`(같은 값), V2 `auth`, 라우트 `access`. +**어디에 적나**: descriptor의 `frontend.authProfileId`, 라우트 `access`. **틀리면** diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md index d8e37316..5e26a4bb 100644 --- a/docs/manual/reference/create-feature.md +++ b/docs/manual/reference/create-feature.md @@ -43,9 +43,9 @@ corepack pnpm create:feature [--context ] [--package @scope/nam - `context-routes.ts`: context가 적재하는 라우트 - `contracts/-feature-contract.ts`: 라우트, 무효화, 계약 패키지 신원 - `contracts/-schemas.ts`: zod 스키마와 `zodValidator` 검증기 -- `contracts/-mapper.ts`: 와이어 값 → 화면 값, 레지스트리 mapper -- `contracts/-api-contract.ts`: V2 행 -- `contracts/-contract-contribution.ts`: V3 descriptor와 계약 기여 +- `contracts/-mapper.ts`: 와이어 값 → 화면 값 +- `contracts/-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행) +- `contracts/-contract-contribution.ts`: HTTP descriptor와 계약 기여. FE-REG-API 행은 여기서 뽑는다 - `contracts/-message-catalog.ts`: ko-KR·en-US 문구 - `application/-feature-api.ts`: input, gateway port, `ApplicationFeatureInputs` 보강 - `adapters/-http-gateway.ts`: HTTP gateway diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 6cd11943..c22a5b87 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -71,23 +71,16 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | 메시지 | 원인 | 고칠 곳 | |---|---|---| -| `REST security profiles are incoherent for : unknown authProfileId .` | 없는 인증 프로필 | `contracts/-api-contract.ts`의 `authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` | -| `REST security profiles are incoherent for : unknown csrfProfileId .` | 없는 CSRF 프로필. 템플릿에는 `NO_CSRF_BEARER`뿐 | `contracts/-api-contract.ts`의 `csrfProfileId` | -| `REST security profiles are incoherent for : auth "none" needs an ANONYMOUS profile, is .` | V2 `auth: "none"`인데 인증 프로필을 썼다 | V2 `auth` 또는 `authProfileId` | -| `REST security profiles are incoherent for : auth "external-session" cannot use the ANONYMOUS profile .` | 로그인 API에 `ANONYMOUS` | V2 `auth` 또는 `authProfileId` | +| `/: unknown authProfileId ` (계약 조립 오류의 `reason`) | 없는 인증 프로필 | `contracts/-contract-contribution.ts`의 `frontend.authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` | | `Product REST auth profile reuses a template profile id.` | 제품 프로필 ID가 템플릿 것과 같다 | `src/contracts/product-contracts.ts` | ### 계약·스키마·mapper | 메시지 | 원인 | 고칠 곳 | |---|---|---| -| `Invalid or duplicate schema definition: ` | 스키마 ID 중복 또는 메타 형식 | `contracts/-api-contract.ts`의 `schemas`. 접두어를 붙인다 | -| `Invalid or duplicate runtime schema codec: ` | 런타임 codec ID 중복 | `contracts/-schemas.ts` | -| `Invalid or duplicate boundary mapper: ` | mapper ID 중복 또는 형식 | `contracts/-mapper.ts` | -| `Duplicate API operation: ` | V2 operation ID 중복 | `contracts/-api-contract.ts` | -| `REST path codec does not match its template: ` | V2 `pathParameterNames`가 `path`의 `{이름}`과 다르다 | `contracts/-api-contract.ts` ([01 문서 3단계](../01-add-a-feature.md#3단계-api-계약) "V2 행의 입력 칸") | -| `Invalid REST operation contract: ` | V2 행 형식. 예: 빈 `pathSchema`, `maxEncodedSearchBytes`가 0~32,768 밖 | 같은 곳 | -| `Unresolved API schema binding: ` | V2 `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마 | 같은 파일의 `schemas`, `contracts/-schemas.ts`의 codec | +| `Invalid or duplicate schema definition: ` | 스키마 ID 중복 또는 메타 형식 | `contracts/-schema-metadata.ts`. 접두어를 붙인다 | +| `duplicate operation: ` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/-contract-contribution.ts`. 접두어를 붙인다 | +| `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`도 같은 꼴) | `contracts/-schema-metadata.ts` | | `Unregistered route codec: ` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/-routes.ts` | | `contract package is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/-contract-contribution.ts`의 `source` | | ` contributes contract package , which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `_CONTRACT_PACKAGE` 하나를 쓰게 한다 | @@ -149,7 +142,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `FE-REG-ROUTE..loadingSurface value does not match ` | 로딩 화면 이름이 케밥 표기가 아니다 | 계약 `routes.*.loadingSurface` | | `FE-REG-ROUTE.. has unknown value ` | `access`·`errorSurface`가 정해진 값이 아니다 | 계약 `routes` | | `FE-REG-ROUTE..paramsSchema references unknown FE-REG-SCHEMA.schemaId=` | 라우트 스키마 ID를 기능이 등록하지 않았다 (`searchSchema`도 같은 꼴) | 계약 스키마 메타 | -| `FE-REG-API. has no executable consumer for operationId=` | V2 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 V2 행을 지운다 | +| `FE-REG-API. has no executable consumer for operationId=` | 계약의 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 descriptor를 지운다 | | `breaking change missing evidence: ` | 행을 빼거나 바꿨는데 승인이 없다 | `update:registry-baseline` 또는 `config/contracts/registry-change-evidence.json` | | `stale breaking evidence : no breaking change in the current diff has this changeId. ...` | 지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 | | `registry baseline approval digest mismatch: approved= actual=` | 기준선 파일을 손으로 고쳤다 | `update:registry-baseline`으로 다시 찍는다 | diff --git a/docs/manual/reference/global-ids.md b/docs/manual/reference/global-ids.md index 0be8a5c3..cb4ca833 100644 --- a/docs/manual/reference/global-ids.md +++ b/docs/manual/reference/global-ids.md @@ -24,20 +24,19 @@ | `chunkId` | 계약 `routes` | `route-invoice-list` | `check:registries` (`duplicates chunkId=`) | | `moduleId` | `routeRuntimeContracts`, 지연 페이지 표 | `invoice-list-page` | `check:registries` (FE-REG-ROUTE-RUNTIME) | | `loadingSurface` | 계약 `routes` | `invoice-list` | 검사 없음 (형식만 본다) | -| operation ID | V2 행, V3 descriptor, gateway | `INVOICE_LIST_ITEMS` | 모듈 로드 (`Duplicate API operation`), 계약 조립 (`duplicate operation`) | -| API 경로 | V2 `path`, V3 `pathTemplate` | `/api/invoice-items` | 검사 없음. 백엔드 계약을 따른다 | -| 스키마 ID | V2 스키마 메타, zod 검증기, codec | `InvoiceNoRequest`, `InvoiceItemListPayload`, `InvoiceProblem` | 모듈 로드 (`Invalid or duplicate schema definition`) | -| mapper ID | V2 `mapperId`, 레지스트리 mapper | `InvoiceItemListMapper` | 모듈 로드 (`Invalid or duplicate boundary mapper`) | +| operation ID | descriptor, gateway | `INVOICE_LIST_ITEMS` | 계약 조립 (`duplicate operation`) | +| API 경로 | descriptor `pathTemplate` | `/api/invoice-items` | 검사 없음. 백엔드 계약을 따른다 | +| 스키마 ID | 스키마 메타데이터, zod 검증기 | `InvoiceNoRequest`, `InvoiceItemListPayload`, `InvoiceProblem` | 모듈 로드 (`Invalid or duplicate schema definition`) | | `contributionId` | 계약 기여 | `invoice-feature-http-v1` | 계약 조립 (`duplicate contributionId`) | -| `policyId` | V3 `frontend` | `INVOICE_LIST_V1` | 검사 없음 | -| `diagnosticsOperation` | V3 `frontend` | `invoice.list` | 검사 없음 | +| `policyId` | descriptor `frontend` | `INVOICE_LIST_V1` | 검사 없음 | +| `diagnosticsOperation` | descriptor `frontend` | `invoice.list` | 검사 없음 | | 쿼리 namespace | 계약 `invalidation.namespaces`, 쿼리 바인딩 | `invoice-item` (버전 1) | 조립 (`Duplicate invalidation namespace`) | | 무효화 topic | 계약 `invalidation.topics`, 뮤테이션 `invalidate` | `qinv.` + 무작위 26자 | 생성 명령이 설치된 topic과 비교, 조립 (`Duplicate invalidation topic`) | | 쿼리·뮤테이션 `definitionId` | 쿼리 바인딩 | `invoice-item-list-v1` | 검사 없음 | | 문구 키 | 기능 문구 catalog | `route.INVOICE_LIST.title`, `invoice.list.title` 등 | 생성 명령, 조립 (`Duplicate ko-KR message key`) | | telemetry `kind` | application input | `invoice.list.failed` | 검사 없음 | -| `owner` | V2 행, 스키마 메타, mapper | `feature-frontend-invoice-feature` | 검사 없음 | -| 인증 프로필 ID | V2·V3 `authProfileId` | `EXTERNAL_BEARER` (템플릿 것을 씀) | 제품 프로필이 템플릿 ID를 쓰면 모듈 로드 (`reuses a template profile id`) | +| `owner` | 스키마 메타데이터 | `feature-frontend-invoice-feature` | 검사 없음 | +| 인증 프로필 ID | descriptor `frontend.authProfileId` | `EXTERNAL_BEARER` (템플릿 것을 씀) | 제품 프로필이 템플릿 ID를 쓰면 모듈 로드 (`reuses a template profile id`) | | `navigationOrder` | 계약 `routes` | 설치된 최댓값 + 10 | 검사 없음. 같은 숫자가 둘이어도 통과 | 메시지 전체와 고칠 파일은 [errors.md](errors.md)에 있다. diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index 80171943..c8e49e09 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -77,12 +77,12 @@ const search = (q: string) => | 패턴 | 정의 | 예제 | 검사 | |---|---|---|---| -| V2 operation 행 | `src/contracts/api-operations.ts`의 `defineRestOperation` | 생성 뼈대 `contracts/-api-contract.ts` | `check:registries` (FE-REG-API) | -| V3 HTTP 계약(실행) | `src/contracts/external-contract-runtime.ts` | 생성 뼈대 `contracts/-contract-contribution.ts` | 계약 조립, V2/V3 일치 테스트 | +| HTTP 계약 | `src/contracts/external-contract-runtime.ts` | 생성 뼈대 `contracts/-contract-contribution.ts` | 계약 조립, `check:registries` (FE-REG-API 행은 `src/contracts/api-operations.ts`의 `projectApiOperationRows`가 뽑는다) | +| 스키마 메타데이터 | `src/contracts/schema-registry.ts`의 `SchemaDefinition` | 생성 뼈대 `contracts/-schema-metadata.ts` | `check:registries` (FE-REG-SCHEMA) | | 배포된 계약 패키지 출처 | 같은 파일의 `EXTERNAL_PACKAGE` | 생성 뼈대(자리표시자 또는 `--package` 신원). 실제 `@org-contracts/*` 패키지를 import하는 예제는 없음 | 계약 조립(신원 형식), 릴리스 승인(자리표시자) | | 런타임 검증기 | `src/contracts/zod-validator.ts`의 `zodValidator` | 생성 뼈대 `contracts/-schemas.ts` | 스키마 ID 중복 | | 검증 생략 | `src/contracts/unvalidated-payload.ts`의 `unvalidatedPayload` | 없음 (기능 예제) | 이유가 비면 throw, `listUnvalidatedPayloads`가 목록을 보임 | -| DTO → 화면 값 mapper | `src/contracts/boundary-mapper.ts` | 생성 뼈대 `contracts/-mapper.ts` | mapper ID 중복 | +| DTO → 화면 값 mapper | `src/contracts/boundary-mapper.ts`의 `BoundaryMappingResult` | 생성 뼈대 `contracts/-mapper.ts` | 타입 검사 | | gateway port + HTTP 어댑터 | `src/adapters/http/index.ts`의 `createFeatureHttpBinding`, `defineFeatureHttpOperationForRoutes` | 생성 뼈대 `adapters/-http-gateway.ts` | 음성 타입 fixture (operation ID, route ID, 입력) | | 문제 응답 → 업무 실패 | `mapProblem` (HTTP 바인딩) | 참조 기능 `adapters/reference-http-gateway.ts` (409, 422) | 기능 테스트 | | 결과와 실패 | `src/contracts/result.ts`, `src/contracts/errors.ts` | 생성 뼈대 `application/-feature-api.ts` | `FailureKind` 닫힌 어휘(타입) | diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index 57bc2fc2..98c3391f 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -157,7 +157,7 @@ V3는 자격증명이 없거나(`UNAUTHENTICATED`), auth owner가 장애거나 fetch 없이 끝난다(`src/bootstrap/runtime-adapters.ts` `attachCredentials`, `src/adapters/http/http-execution-v3.ts` credential patch 처리). 전송 0회 미인증은 diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그래도 무자격 -전송이 보이면 V3가 아닌 경로(V2 client 직접 조합, 외부 SDK)를 먼저 의심한다. +전송이 보이면 V3가 아닌 경로(외부 SDK 직접 호출)를 먼저 의심한다. 점검: diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index 1be82543..b035bbf1 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -277,7 +277,7 @@ export function planFeature( [`${feature}/contracts/${base}-feature-contract.ts`, renderFeatureContract(shape)], [`${feature}/contracts/${base}-schemas.ts`, renderSchemas(shape)], [`${feature}/contracts/${base}-mapper.ts`, renderMapper(shape)], - [`${feature}/contracts/${base}-api-contract.ts`, renderApiContract(shape)], + [`${feature}/contracts/${base}-schema-metadata.ts`, renderSchemaMetadata(shape)], [ `${feature}/contracts/${base}-contract-contribution.ts`, renderContractContribution(shape), @@ -369,9 +369,9 @@ function renderFeatureRuntime({ names }: Shape): string { const { base, upper } = names; return `import { defineFeatureRuntime } from "../feature-module.ts"; import { ${upper}_FEATURE_ADAPTER_CONTRIBUTION } from "./adapters/create-${base}-feature-input.ts"; -import { ${upper}_API_CONTRACT } from "./contracts/${base}-api-contract.ts"; import { ${upper}_CONTRACT_CONTRIBUTION } from "./contracts/${base}-contract-contribution.ts"; import { ${upper}_FEATURE_ID } from "./contracts/${base}-feature-contract.ts"; +import { ${upper}_SCHEMA_METADATA } from "./contracts/${base}-schema-metadata.ts"; /** * The executable half. \`feature-module.ts\` imports this file dynamically, so @@ -379,7 +379,7 @@ import { ${upper}_FEATURE_ID } from "./contracts/${base}-feature-contract.ts"; */ export const FEATURE_RUNTIME = defineFeatureRuntime({ featureId: ${upper}_FEATURE_ID, - apiContract: ${upper}_API_CONTRACT, + schemas: ${upper}_SCHEMA_METADATA, adapters: [${upper}_FEATURE_ADAPTER_CONTRIBUTION], contractContributions: [${upper}_CONTRACT_CONTRIBUTION], } as const); @@ -522,8 +522,7 @@ export const ${upper}_FEATURE_CONTRACT = Object.freeze({ function renderSchemas({ names }: Shape): string { const { camel, pascal, upper } = names; - return `import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts"; -import { z } from "../../../contracts/zod.ts"; + return `import { z } from "../../../contracts/zod.ts"; import { zodValidator } from "../../../contracts/zod-validator.ts"; /** The GET takes no input. Schema ids are global, so this one is prefixed too. */ @@ -564,28 +563,16 @@ export const ${upper}_VALIDATORS = Object.freeze({ ), ${pascal}Problem: zodValidator("${pascal}Problem", ${camel}ProblemSchema), }); - -export const ${upper}_RUNTIME_SCHEMA_CODECS = Object.freeze({ - ${pascal}NoRequest: runtimeSchemaCodecFromValidator(${upper}_VALIDATORS.${pascal}NoRequest), - ${pascal}ItemListPayload: runtimeSchemaCodecFromValidator( - ${upper}_VALIDATORS.${pascal}ItemListPayload, - ), -}); `; } -function renderMapper({ names, owner }: Shape): string { - const { base, camel, pascal, upper } = names; +function renderMapper({ names }: Shape): string { + const { base, pascal } = names; return `import { - mappingFailure, mappingSuccess, type BoundaryMappingResult, - type InstalledBoundaryMapper, } from "../../../contracts/boundary-mapper.ts"; -import { - ${camel}ItemListPayloadSchema, - type ${pascal}ItemDto, -} from "./${base}-schemas.ts"; +import type { ${pascal}ItemDto } from "./${base}-schemas.ts"; /** What the page shows. A wire field never reaches presentation by its wire name. */ export type ${pascal}ItemView = Readonly<{ itemId: string; name: string }>; @@ -604,93 +591,37 @@ export function map${pascal}ItemList( ), ); } - -/** The registry row (FE-REG-API). The registry is untyped, so it checks the shape. */ -export const ${upper}_BOUNDARY_MAPPERS = Object.freeze({ - ${pascal}ItemListMapper: Object.freeze({ - mapperId: "${pascal}ItemListMapper", - mapperVersion: 1, - inputSchemaId: "${pascal}ItemListPayload", - outputContractId: "${pascal}ItemList", - owner: "${owner}", - maxOutputItems: 100, - map(value: unknown) { - const parsed = ${camel}ItemListPayloadSchema.safeParse(value); - return parsed.success - ? map${pascal}ItemList(parsed.data) - : mappingFailure("MAPPING_INVARIANT_REJECTED"); - }, - }), -} satisfies Readonly>); `; } -function renderApiContract({ names, operationId, apiPath, owner }: Shape): string { - const { base, pascal, upper } = names; - return `import { defineRestOperation } from "../../../contracts/api-operations.ts"; -import { ${upper}_BOUNDARY_MAPPERS } from "./${base}-mapper.ts"; -import { ${upper}_RUNTIME_SCHEMA_CODECS } from "./${base}-schemas.ts"; - -const OWNER = "${owner}"; +function renderSchemaMetadata({ names, owner }: Shape): string { + const { pascal, upper } = names; + return `const OWNER = "${owner}"; /** - * The V2 API contract \`check:registries\` governs (FE-REG-API). The executable - * descriptor of the same operation is in \`${base}-contract-contribution.ts\`; - * tests/unit/http-operation-v2-v3-parity.test.ts fails when they disagree. - * Runtime half only: \`feature-runtime.ts\` loads it. + * FE-REG-SCHEMA rows of the feature's schemas (\`check:registries\`). The HTTP + * operation is written once, in \`${names.base}-contract-contribution.ts\`; + * FE-REG-API rows are projected from it. Runtime half only: + * \`feature-runtime.ts\` loads it. */ -export const ${upper}_API_CONTRACT = Object.freeze({ - runtimeSchemas: ${upper}_RUNTIME_SCHEMA_CODECS, - mappers: ${upper}_BOUNDARY_MAPPERS, - schemas: Object.freeze({ - ${pascal}NoRequest: Object.freeze({ - schemaId: "${pascal}NoRequest", - boundary: "api-request", - owner: OWNER, - runtime: "zod", - schemaVersion: 1, - direction: "REQUEST", - unknownFieldPolicy: "REJECT_UNKNOWN", - }), - ${pascal}ItemListPayload: Object.freeze({ - schemaId: "${pascal}ItemListPayload", - boundary: "api-response", - owner: OWNER, - runtime: "zod", - schemaVersion: 1, - direction: "RESPONSE", - unknownFieldPolicy: "STRIP_UNKNOWN", - }), +export const ${upper}_SCHEMA_METADATA = Object.freeze({ + ${pascal}NoRequest: Object.freeze({ + schemaId: "${pascal}NoRequest", + boundary: "api-request", + owner: OWNER, + runtime: "zod", + schemaVersion: 1, + direction: "REQUEST", + unknownFieldPolicy: "REJECT_UNKNOWN", }), - apiOperations: Object.freeze({ - ${operationId}: defineRestOperation({ - method: "GET", - path: "${apiPath}", - operationId: "${operationId}", - auth: "external-session", - timeoutMs: null, - idempotency: "safe", - retry: "runtime", - requestSource: "none", - requestSchema: "${pascal}NoRequest", - responseSchema: "${pascal}ItemListPayload", - owner: OWNER, - contractVersion: 2, - protocol: "REST", - semantics: "QUERY", - replayPolicy: "SAFE", - idempotencyKeyPolicy: "NONE", - mapperId: "${pascal}ItemListMapper", - successStatuses: [200], - responseMediaTypes: ["application/json"], - maxResponseBytes: 262_144, - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_BEARER", - csrfProfileId: "NO_CSRF_BEARER", - pathSchema: "${pascal}NoRequest", - pathParameterNames: [], - maxEncodedSearchBytes: 0, - }), + ${pascal}ItemListPayload: Object.freeze({ + schemaId: "${pascal}ItemListPayload", + boundary: "api-response", + owner: OWNER, + runtime: "zod", + schemaVersion: 1, + direction: "RESPONSE", + unknownFieldPolicy: "STRIP_UNKNOWN", }), } as const); `; @@ -713,7 +644,8 @@ import { } from "./${base}-schemas.ts"; /** - * The executable (V3) descriptor of ${operationId}. It belongs to the contract + * The HTTP descriptor of ${operationId}, the one place the operation is + * written: it executes, and FE-REG-API reads it. It belongs to the contract * package pinned in \`${base}-feature-contract.ts\`: import \`@org-contracts/*\` * only in this file (external-contract-package-single-import-path) and take * the package's descriptor instead of this local one. @@ -1038,12 +970,11 @@ export default function ${pascal}ListPage() { } function renderInputTest({ names, operationId }: Shape): string { - const { base, pascal, upper } = names; + const { base, pascal } = names; return `import { describe, expect, it, vi } from "vitest"; import { createFailure } from "../../../src/contracts/errors.ts"; import { create${pascal}FeatureInput } from "../../../src/features/${names.id}/application/${base}-feature-api.ts"; -import { ${upper}_BOUNDARY_MAPPERS } from "../../../src/features/${names.id}/contracts/${base}-mapper.ts"; import type { TelemetryPort } from "../../../src/platform/telemetry/telemetry-port.ts"; const ITEMS = Object.freeze([Object.freeze({ itemId: "item-1", name: "First item" })]); @@ -1086,15 +1017,6 @@ describe("${names.id} application input", () => { await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure }); }); }); - -describe("${names.id} registry mapper", () => { - it("maps a list payload and rejects any other shape", () => { - const { map } = ${upper}_BOUNDARY_MAPPERS.${pascal}ItemListMapper; - - expect(map([{ id: "item-1", name: "First item" }])).toEqual({ ok: true, value: ITEMS }); - expect(map({ items: [] })).toEqual({ ok: false, code: "MAPPING_INVARIANT_REJECTED" }); - }); -}); `; } diff --git a/scripts/scale/composition-workloads.ts b/scripts/scale/composition-workloads.ts index adeb8646..24d44e15 100644 --- a/scripts/scale/composition-workloads.ts +++ b/scripts/scale/composition-workloads.ts @@ -76,7 +76,7 @@ export const COMPOSITION_WORKLOADS: readonly CompositionWorkload[] = Object.free loadRuntime: async () => Object.freeze({ featureId: id, - apiContract: Object.freeze({}), + schemas: Object.freeze({}), adapters: Object.freeze([]), contractContributions: Object.freeze([]), }), diff --git a/src/contracts/api-operations.ts b/src/contracts/api-operations.ts index c333f26b..4d7b496c 100644 --- a/src/contracts/api-operations.ts +++ b/src/contracts/api-operations.ts @@ -1,226 +1,57 @@ -export type ApiOperation = Readonly<{ - method: string; - path: string; +import type { + HttpMethod, + InstalledContractContribution, + InstalledHttpContract, + ResponseEnvelope, + RetrySemantics, +} from "./external-contract-runtime.ts"; + +/** + * 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. + */ +export type ApiOperationRow = Readonly<{ operationId: string; - auth: "none" | "external-session"; - timeoutMs: number | null; - idempotency: "safe" | "keyed" | "none"; - retry: "runtime" | "never"; - requestSource: "search" | "body" | "none"; + featureId: string; + method: HttpMethod; + path: string; + authProfileId: string; + retrySemantics: RetrySemantics; + requestBody: InstalledHttpContract["contract"]["requestBody"]; + responseBody: InstalledHttpContract["contract"]["responseBody"]; + responseEnvelope: ResponseEnvelope; requestSchema: string; responseSchema: string; - owner: string; - contractVersion?: 2; - protocol?: "REST"; - semantics?: "QUERY" | "COMMAND"; - replayPolicy?: "SAFE" | "IDEMPOTENT" | "KEYED_COMMAND" | "NON_REPLAYABLE"; - idempotencyKeyPolicy?: "NONE" | "REQUIRED"; - mapperId?: string; - successStatuses?: readonly number[]; - responseMediaTypes?: readonly string[]; - maxResponseBytes?: number; - providerId?: string; - authProfileId?: string; - csrfProfileId?: string; - pathSchema?: string; - pathParameterNames?: readonly string[]; - maxEncodedSearchBytes?: number; + problemSchema: string; }>; /** - * 07-02. A V2 row is the declaration `check:registries` (FE-REG-API) governs; - * it is not what executes. The executed copy of the same HTTP API is the V3 - * descriptor (`InstalledHttpContract`) in the feature's contract contribution. - * A feature writes both, and `tests/unit/http-operation-v2-v3-parity.test.ts` - * checks they name the same operations, method, path, statuses, limits, auth - * profile, replay and write semantics, request body and schema ids. The - * deadline is not compared: V2 `timeoutMs` is `null` while V3 always has one. + * Pass composed contributions (`composeContractContributions`): composition + * already refused duplicate operation ids and snapshotted every row. */ -export type RestOperationV2 = ApiOperation & - Readonly<{ - contractVersion: 2; - protocol: "REST"; - semantics: "QUERY" | "COMMAND"; - replayPolicy: - | "SAFE" - | "IDEMPOTENT" - | "KEYED_COMMAND" - | "NON_REPLAYABLE"; - idempotencyKeyPolicy: "NONE" | "REQUIRED"; - mapperId: string; - successStatuses: readonly number[]; - responseMediaTypes: readonly string[]; - maxResponseBytes: number; - providerId: string; - authProfileId: string; - csrfProfileId: string; - pathSchema: string; - pathParameterNames: readonly string[]; - maxEncodedSearchBytes: number; - }>; - -const MAX_RESPONSE_BYTES = 8 * 1024 * 1024; -const OPERATION_ID = /^[A-Z][A-Z0-9_]{2,79}$/; -const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/; - -export function defineRestOperation( - operation: RestOperationV2, -): RestOperationV2 { - validateRestOperation(operation); - return Object.freeze({ - ...operation, - successStatuses: Object.freeze([...operation.successStatuses]), - responseMediaTypes: Object.freeze([...operation.responseMediaTypes]), - pathParameterNames: Object.freeze([...operation.pathParameterNames]), - }); -} - -export function composeApiOperations( - contributions: readonly Readonly>[], -): Readonly> { - const result: Record = Object.create(null); +export function projectApiOperationRows( + contributions: readonly InstalledContractContribution[], +): Readonly> { + const rows: Record = {}; for (const contribution of contributions) { - for (const [registryId, operation] of Object.entries(contribution)) { - if (registryId !== operation.operationId) { - throw new TypeError("API operation registry key does not match operationId."); - } - if (Object.hasOwn(result, registryId)) { - throw new TypeError(`Duplicate API operation: ${registryId}`); - } - if (operation.contractVersion === 2) { - validateRestOperation(operation as RestOperationV2); - } - result[registryId] = operation; + 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, + }); } } - return Object.freeze(result); -} - -export function validateApiRuntimeBindings( - operations: Readonly>, - schemaMetadata: Readonly>>, - schemaCodecs: Readonly>>, - mappers: Readonly< - Record< - string, - Readonly<{ mapperId: string; inputSchemaId: string; maxOutputItems: number }> - > - >, -): true { - for (const operation of Object.values(operations)) { - if (operation.contractVersion !== 2) continue; - for (const schemaId of [ - operation.pathSchema, - operation.requestSchema, - operation.responseSchema, - ]) { - if ( - !schemaId || - schemaMetadata[schemaId]?.schemaId !== schemaId || - schemaCodecs[schemaId]?.schemaId !== schemaId - ) { - throw new TypeError( - `Unresolved API schema binding: ${operation.operationId}`, - ); - } - } - const mapper = mappers[operation.mapperId ?? ""]; - if ( - !mapper || - mapper.mapperId !== operation.mapperId || - mapper.inputSchemaId !== operation.responseSchema || - mapper.maxOutputItems < 1 - ) { - throw new TypeError( - `Unresolved API mapper binding: ${operation.operationId}`, - ); - } - } - return true; -} - -function validateRestOperation(operation: RestOperationV2): void { - if ( - operation.protocol !== "REST" || - !OPERATION_ID.test(operation.operationId) || - !operation.owner || - !operation.mapperId || - !operation.providerId || - !operation.authProfileId || - !operation.csrfProfileId || - !operation.pathSchema || - !operation.path.startsWith("/") || - operation.path.startsWith("//") || - operation.path.includes("?") || - operation.path.includes("#") || - !Number.isSafeInteger(operation.maxResponseBytes) || - operation.maxResponseBytes < 1 || - operation.maxResponseBytes > MAX_RESPONSE_BYTES || - !Number.isSafeInteger(operation.maxEncodedSearchBytes) || - operation.maxEncodedSearchBytes < 0 || - operation.maxEncodedSearchBytes > 32_768 || - operation.successStatuses.length === 0 || - operation.successStatuses.some( - (status) => !Number.isInteger(status) || status < 200 || status > 299, - ) || - new Set(operation.successStatuses).size !== operation.successStatuses.length || - operation.responseMediaTypes.length === 0 || - operation.responseMediaTypes.some( - (value) => !MEDIA_TYPE.test(value) || value !== value.toLowerCase(), - ) - ) { - throw new TypeError(`Invalid REST operation contract: ${operation.operationId}`); - } - const placeholders = [ - ...operation.path.matchAll( - /:([A-Za-z][A-Za-z0-9_]*)|\{([A-Za-z][A-Za-z0-9_]*)\}/g, - ), - ] - .map((match) => match[1] ?? match[2] ?? "") - .sort(); - const codecKeys = [...operation.pathParameterNames].sort(); - if ( - new Set(codecKeys).size !== codecKeys.length || - placeholders.length !== codecKeys.length || - placeholders.some((name, index) => name !== codecKeys[index]) - ) { - throw new TypeError( - `REST path codec does not match its template: ${operation.operationId}`, - ); - } - const isQuery = operation.semantics === "QUERY"; - // R-7.4. CSRF need is decided from the method (rest-profiles), so a COMMAND - // must use an unsafe method. Same binding as browser-rpc and the V3 runtime. - if ( - !["QUERY", "COMMAND"].includes(operation.semantics) || - !["SAFE", "IDEMPOTENT", "KEYED_COMMAND", "NON_REPLAYABLE"].includes( - operation.replayPolicy, - ) || - (!isQuery && !["POST", "PUT", "PATCH", "DELETE"].includes(operation.method)) || - (isQuery && !["GET", "HEAD"].includes(operation.method)) || - (isQuery && !["SAFE", "IDEMPOTENT"].includes(operation.replayPolicy)) || - (operation.replayPolicy === "KEYED_COMMAND" && - (operation.idempotencyKeyPolicy !== "REQUIRED" || - operation.idempotency !== "keyed")) || - (operation.replayPolicy === "NON_REPLAYABLE" && - (operation.retry !== "never" || operation.idempotency !== "none")) - ) { - throw new TypeError(`Incoherent REST replay contract: ${operation.operationId}`); - } -} - -export const API_OPERATIONS: Readonly> = - Object.freeze({}); - -export function getApiOperation( - operationId: string, - operations: Readonly> = API_OPERATIONS, -): ApiOperation { - const selected = Object.hasOwn(operations, operationId) - ? operations[operationId] - : undefined; - if (!selected) { - throw new Error(`Unregistered API operation: ${operationId}`); - } - return selected; + return Object.freeze(rows); } diff --git a/src/contracts/realtime-streams.ts b/src/contracts/realtime-streams.ts index d920640e..b99a8470 100644 --- a/src/contracts/realtime-streams.ts +++ b/src/contracts/realtime-streams.ts @@ -1,4 +1,4 @@ -import type { ApiOperation } from "./api-operations.ts"; +import type { ApiOperationRow } from "./api-operations.ts"; import type { InstalledBoundaryMapper } from "./boundary-mapper.ts"; import type { RuntimeSchemaCodec } from "./schema-registry.ts"; import { @@ -105,7 +105,7 @@ export type RealtimeEventTypeRegistration = Readonly<{ export type RealtimePolicyRegistryBindings = Readonly<{ schemaCodecs: Readonly>; mappers: Readonly>; - apiOperations: Readonly>; + apiOperations: Readonly>; endpointIds: readonly RealtimeEndpointId[]; effectProfileIds: readonly ExternalEventEffectProfileId[]; killSwitchIds: readonly KillSwitchId[]; @@ -467,11 +467,9 @@ function validSnapshotBindings( OWNED_ID.test(input.checkpointCodecId) && bindings.schemaCodecs[input.checkpointCodecId]?.schemaId === input.checkpointCodecId && - operation?.contractVersion === 2 && - operation.protocol === "REST" && - operation.semantics === "QUERY" && - (operation.replayPolicy === "SAFE" || - operation.replayPolicy === "IDEMPOTENT") + operation?.method === "GET" && + (operation.retrySemantics === "SAFE" || + operation.retrySemantics === "IDEMPOTENT") ); } diff --git a/src/contracts/rest-profiles.ts b/src/contracts/rest-profiles.ts index ea7e9af1..349c3957 100644 --- a/src/contracts/rest-profiles.ts +++ b/src/contracts/rest-profiles.ts @@ -3,19 +3,10 @@ import { type ReadOnlyRegistry, } from "./read-only-registry.ts"; import { snapshotExactArray, snapshotExactObject } from "./exact-snapshot.ts"; -import { isLoopbackHostname } from "./deployment-admission.ts"; import { PRODUCT_REST_AUTH_PROFILES } from "./product-contracts.ts"; export type FetchCredentialsMode = "omit" | "same-origin" | "include"; -export type RestProviderProfile = Readonly<{ - providerId: string; - baseUrl: string; - allowedCredentialsModes: readonly FetchCredentialsMode[]; - redirect: "error"; - referrerPolicy: "no-referrer"; -}>; - /** * VD-23. The complete closed set of headers a credential owner may contribute. * Transport-owned headers (`accept`, `content-type`, `idempotency-key`) and @@ -57,12 +48,6 @@ export type InstalledRestAuthProfiles = ReadOnlyRegistry< RestAuthProfile >; -export type RestCsrfProfile = Readonly<{ - csrfProfileId: string; - mode: "NONE" | "HEADER"; - headerName: "x-csrf-token" | null; -}>; - const EXTERNAL_BEARER = Object.freeze({ authProfileId: "EXTERNAL_BEARER", transport: "BEARER_HEADER", @@ -213,35 +198,7 @@ export function installRestAuthProfileRegistry( if (installed.size === 0) { throw new TypeError("REST auth profile registry cannot be empty."); } - const registry = createReadOnlyRegistry(installed); - INSTALLED_REGISTRIES.add(registry); - return registry; -} - -/** Registries this module installed, as opposed to look-alike objects. */ -const INSTALLED_REGISTRIES = new WeakSet(); - -/** - * REST auth profiles as accepted by resolve: the installed registry, or a raw - * record that is installed (validated) before any lookup. - */ -export type RestAuthProfileSource = - | InstalledRestAuthProfiles - | Readonly>; - -/** - * Q-6.7-9. Composition, the V3 executor and V2 resolve answer from one - * validated registry. A raw record never reaches a lookup unvalidated, so a - * profile installation would refuse cannot be resolved either. - */ -function installedAuthProfiles( - profiles: RestAuthProfileSource, -): InstalledRestAuthProfiles { - return INSTALLED_REGISTRIES.has(profiles) - ? (profiles as InstalledRestAuthProfiles) - : installRestAuthProfileRegistry( - profiles as Readonly>, - ); + return createReadOnlyRegistry(installed); } function withProductProfiles(): Readonly> { @@ -263,141 +220,3 @@ function withProductProfiles(): Readonly> { */ export const INSTALLED_REST_AUTH_PROFILES: InstalledRestAuthProfiles = installRestAuthProfileRegistry(withProductProfiles()); - -export const REST_CSRF_PROFILES = Object.freeze({ - NO_CSRF_BEARER: Object.freeze({ - csrfProfileId: "NO_CSRF_BEARER", - mode: "NONE", - headerName: null, - }), -} satisfies Readonly>); - -export function createRestProviderProfile( - providerId: string, - baseUrl: string, - allowedCredentialsModes: readonly FetchCredentialsMode[] = ["omit"], -): RestProviderProfile { - const parsed = new URL(baseUrl); - const localHttp = - parsed.protocol === "http:" && - isLoopbackHostname(parsed.hostname); - if ( - !providerId || - (parsed.protocol !== "https:" && !localHttp) || - parsed.username || - parsed.password || - parsed.search || - parsed.hash || - allowedCredentialsModes.length === 0 || - new Set(allowedCredentialsModes).size !== allowedCredentialsModes.length - ) { - throw new TypeError("Invalid REST provider profile."); - } - return Object.freeze({ - providerId, - baseUrl: parsed.href, - allowedCredentialsModes: Object.freeze([...allowedCredentialsModes]), - redirect: "error", - referrerPolicy: "no-referrer", - }); -} - -export function resolveRestSecurityProfiles( - operation: Readonly<{ - operationId?: string; - method: string; - auth: "none" | "external-session"; - authProfileId?: string; - csrfProfileId?: string; - }>, - provider: RestProviderProfile, - authProfiles: RestAuthProfileSource = INSTALLED_REST_AUTH_PROFILES, - csrfProfiles: Readonly> = REST_CSRF_PROFILES, -): Readonly<{ auth: RestAuthProfile; csrf: RestCsrfProfile }> { - const authProfileId = operation.authProfileId ?? ""; - const auth = installedAuthProfiles(authProfiles).get(authProfileId); - const csrfProfileId = operation.csrfProfileId ?? ""; - const csrf = Object.hasOwn(csrfProfiles, csrfProfileId) - ? csrfProfiles[csrfProfileId] - : undefined; - const unsafe = !["GET", "HEAD", "OPTIONS"].includes(operation.method); - // 16-03. Every broken condition is named, with the operation and profile - // ids, so a renamed or missing profile does not have to be found by - // comparing each rule by hand. - const broken = [ - !auth && `unknown authProfileId ${authProfileId || "(none)"}`, - !csrf && `unknown csrfProfileId ${csrfProfileId || "(none)"}`, - auth && - !provider.allowedCredentialsModes.includes(auth.credentials) && - `provider ${provider.providerId} does not allow credentials "${auth.credentials}" of ${authProfileId}`, - auth && - operation.auth === "none" && - auth.transport !== "ANONYMOUS" && - `auth "none" needs an ANONYMOUS profile, ${authProfileId} is ${auth.transport}`, - auth && - operation.auth === "external-session" && - auth.transport === "ANONYMOUS" && - `auth "external-session" cannot use the ANONYMOUS profile ${authProfileId}`, - auth?.transport === "BEARER_HEADER" && - csrf && - csrf.mode !== "NONE" && - `bearer profile ${authProfileId} cannot use CSRF mode ${csrf.mode} of ${csrfProfileId}`, - unsafe && - auth?.transport === "SAME_ORIGIN_COOKIE" && - csrf && - csrf.mode !== "HEADER" && - `${operation.method} with cookie profile ${authProfileId} needs a HEADER CSRF profile, ${csrfProfileId} is ${csrf.mode}`, - ].filter((condition): condition is string => typeof condition === "string"); - if (!auth || !csrf || broken.length > 0) { - throw new TypeError( - `REST security profiles are incoherent for ${operation.operationId ?? "an operation"}: ${broken.join("; ")}.`, - ); - } - return Object.freeze({ auth, csrf }); -} - -export function validateRestProfileBindings( - operations: Readonly< - Record< - string, - Readonly<{ - contractVersion?: number; - operationId: string; - method: string; - auth: "none" | "external-session"; - providerId?: string; - authProfileId?: string; - csrfProfileId?: string; - }> - > - >, - providerCredentialModes: Readonly< - Record - >, - authProfiles: RestAuthProfileSource = INSTALLED_REST_AUTH_PROFILES, - csrfProfiles: Readonly> = REST_CSRF_PROFILES, -): true { - const installed = installedAuthProfiles(authProfiles); - for (const operation of Object.values(operations)) { - if (operation.contractVersion !== 2) continue; - const allowed = providerCredentialModes[operation.providerId ?? ""]; - if (!allowed) { - throw new TypeError( - `Unregistered REST provider binding: ${operation.operationId}`, - ); - } - resolveRestSecurityProfiles( - operation, - Object.freeze({ - providerId: operation.providerId ?? "", - baseUrl: "https://contract.invalid/", - allowedCredentialsModes: allowed, - redirect: "error", - referrerPolicy: "no-referrer", - }), - installed, - csrfProfiles, - ); - } - return true; -} diff --git a/src/features/feature-module.ts b/src/features/feature-module.ts index d72f4d27..f9defeff 100644 --- a/src/features/feature-module.ts +++ b/src/features/feature-module.ts @@ -42,13 +42,6 @@ type EmptyFeatureMessageCatalogs = Readonly< Record>> >; -/** The V2 API contract: operations, schema metadata, runtime codecs, mappers. */ -export type EmptyFeatureApiContract = Readonly<{ - apiOperations: EmptyRecord; - schemas: EmptyRecord; - runtimeSchemas: EmptyRecord; - mappers: EmptyRecord; -}>; /** * The executable half. `featureId` must equal the declaring module's id; the @@ -56,12 +49,17 @@ export type EmptyFeatureApiContract = Readonly<{ * it belongs to that feature. */ export type FeatureRuntime< - ApiContract = EmptyFeatureApiContract, + Schemas = EmptyRecord, Adapter = never, ContractContribution = never, > = Readonly<{ featureId: string; - apiContract: ApiContract; + /** + * FE-REG-SCHEMA rows (`SchemaDefinition`) for the feature's route and API + * schemas. The HTTP operations themselves are the V3 descriptors in + * `contractContributions`; FE-REG-API rows are projected from them. + */ + schemas: Schemas; adapters: readonly Adapter[]; contractContributions: readonly ContractContribution[]; }>; diff --git a/src/features/installed-feature-runtime-registries.ts b/src/features/installed-feature-runtime-registries.ts index 1b86be28..1404c147 100644 --- a/src/features/installed-feature-runtime-registries.ts +++ b/src/features/installed-feature-runtime-registries.ts @@ -1,15 +1,9 @@ -import { - composeApiOperations, - validateApiRuntimeBindings, -} from "../contracts/api-operations.ts"; -import { composeBoundaryMapperRegistry } from "../contracts/boundary-mapper.ts"; +import { projectApiOperationRows } from "../contracts/api-operations.ts"; import { composeContractContributions, type InstalledContractContribution, } from "../contracts/external-contract-runtime.ts"; -import { validateRestProfileBindings } from "../contracts/rest-profiles.ts"; import { - composeRuntimeSchemaCodecs, composeSchemaRegistry, PLATFORM_SCHEMA_REGISTRY, } from "../contracts/schema-registry.ts"; @@ -22,9 +16,9 @@ import { INSTALLED_PRODUCT_FEATURE_MODULES } from "./installed-product-manifest. /** * 15-01. Loads every installed feature's runtime half and composes the - * registries that need all of them: the V2 API registries and the contract - * contributions. Duplicates across features throw here, as they did at boot - * before 15-01. + * registries that need all of them: the schema registry, the contract + * contributions, and the FE-REG-API rows projected from those contributions. + * Duplicates across features throw here, as they did at boot before 15-01. * * The app boot never calls this: at runtime the composition root loads one * feature at a time when its routes are entered (`installed-feature-adapters.ts`). @@ -35,34 +29,10 @@ export async function loadInstalledFeatureRuntimeRegistries() { const runtimes = Object.freeze( await Promise.all(INSTALLED_PRODUCT_FEATURE_MODULES.map(loadFeatureRuntime)), ); - type LoadedApiContract = (typeof runtimes)[number]["apiContract"]; - const apiContracts: readonly LoadedApiContract[] = runtimes.map( - (runtime) => runtime.apiContract, - ); - - const apiOperations = composeApiOperations( - apiContracts.map((contract) => contract.apiOperations), - ); - const restProfileBindingsValid = validateRestProfileBindings( - apiOperations, - Object.freeze({ PRIMARY_API: Object.freeze(["omit"] as const) }), - ); const schemaRegistry = composeSchemaRegistry([ PLATFORM_SCHEMA_REGISTRY, - ...apiContracts.map((contract) => contract.schemas), + ...runtimes.map((runtime) => runtime.schemas), ]); - const runtimeSchemaCodecs = composeRuntimeSchemaCodecs( - apiContracts.map((contract) => contract.runtimeSchemas), - ); - const mapperRegistry = composeBoundaryMapperRegistry( - apiContracts.map((contract) => contract.mappers), - ); - const apiRuntimeBindingsValid = validateApiRuntimeBindings( - apiOperations, - schemaRegistry, - runtimeSchemaCodecs, - mapperRegistry, - ); const contractContributions: readonly InstalledContractContribution[] = Object.freeze( @@ -94,12 +64,10 @@ export async function loadInstalledFeatureRuntimeRegistries() { return Object.freeze({ runtimes, - apiOperations, - restProfileBindingsValid, + apiOperations: projectApiOperationRows( + composedContractContributions.contributions, + ), schemaRegistry, - runtimeSchemaCodecs, - mapperRegistry, - apiRuntimeBindingsValid, contractContributions, composedContractContributions, }); diff --git a/src/features/loaded-feature-runtimes.ts b/src/features/loaded-feature-runtimes.ts index d97ba99f..80e02470 100644 --- a/src/features/loaded-feature-runtimes.ts +++ b/src/features/loaded-feature-runtimes.ts @@ -17,11 +17,7 @@ const registries = await loadInstalledFeatureRuntimeRegistries(); export const LOADED_FEATURE_RUNTIMES = registries.runtimes; export const API_OPERATIONS = registries.apiOperations; -export const REST_PROFILE_BINDINGS_VALID = registries.restProfileBindingsValid; export const SCHEMA_REGISTRY = registries.schemaRegistry; -export const RUNTIME_SCHEMA_CODECS = registries.runtimeSchemaCodecs; -export const MAPPER_REGISTRY = registries.mapperRegistry; -export const API_RUNTIME_BINDINGS_VALID = registries.apiRuntimeBindingsValid; export const INSTALLED_CONTRACT_CONTRIBUTIONS = registries.contractContributions; export const COMPOSED_CONTRACT_CONTRIBUTIONS = registries.composedContractContributions; diff --git a/src/features/reference-feature/README.md b/src/features/reference-feature/README.md index 392fffea..a966ba79 100644 --- a/src/features/reference-feature/README.md +++ b/src/features/reference-feature/README.md @@ -57,8 +57,8 @@ feature가 실제 contribution을 소유한다. - 선언(초기 청크, `feature-module.ts`): route 표와 invalidation은 `reference-feature-contract.ts`, 문구는 `reference-message-catalog.ts` -- 실행부(`feature-runtime.ts`, reference route에 들어갈 때 적재): API 계약 - `reference-api-contract.ts`, bootstrap input +- 실행부(`feature-runtime.ts`, reference route에 들어갈 때 적재): 스키마 메타데이터 + `reference-schema-metadata.ts`, bootstrap input `REFERENCE_FEATURE_ADAPTER_CONTRIBUTION`, HTTP contract contribution - route codec과 page component: `REFERENCE_FEATURE_ROUTE_CODECS`, `REFERENCE_FEATURE_ROUTE_RUNTIME` (`context-routes.ts`가 route handle에 실어 diff --git a/src/features/reference-feature/contracts/reference-api-contract.ts b/src/features/reference-feature/contracts/reference-api-contract.ts deleted file mode 100644 index 55e6afb1..00000000 --- a/src/features/reference-feature/contracts/reference-api-contract.ts +++ /dev/null @@ -1,155 +0,0 @@ -import { defineRestOperation } from "../../../contracts/api-operations.ts"; -import { REFERENCE_RUNTIME_SCHEMA_CODECS } from "./reference-schemas.ts"; -import { REFERENCE_BOUNDARY_MAPPERS } from "./reference-mapper.ts"; - -/** - * 15-01. The V2 API contract of the reference feature: operations, schema - * metadata, runtime schema codecs and boundary mappers. Runtime half only - * (`feature-runtime.ts`); the app boot never imports it. - */ -export const REFERENCE_API_CONTRACT = Object.freeze({ - runtimeSchemas: REFERENCE_RUNTIME_SCHEMA_CODECS, - mappers: REFERENCE_BOUNDARY_MAPPERS, - schemas: Object.freeze({ - ReferenceResourceParams: Object.freeze({ - schemaId: "ReferenceResourceParams", - boundary: "route-params", - owner: "feature-frontend-reference-feature-vertical-slice", - runtime: "zod", - schemaVersion: 1, - direction: "REQUEST", - unknownFieldPolicy: "REJECT_UNKNOWN", - }), - ReferenceResourceListQuery: Object.freeze({ - schemaId: "ReferenceResourceListQuery", - boundary: "route-search-api-request", - owner: "feature-frontend-reference-feature-vertical-slice", - runtime: "zod", - schemaVersion: 1, - direction: "REQUEST", - unknownFieldPolicy: "REJECT_UNKNOWN", - }), - CreateReferenceResourceCommand: Object.freeze({ - schemaId: "CreateReferenceResourceCommand", - boundary: "api-request", - owner: "feature-frontend-reference-feature-vertical-slice", - runtime: "zod", - schemaVersion: 1, - direction: "REQUEST", - unknownFieldPolicy: "REJECT_UNKNOWN", - }), - NoRequest: Object.freeze({ - schemaId: "NoRequest", - boundary: "api-request", - owner: "feature-frontend-reference-feature-vertical-slice", - runtime: "zod", - schemaVersion: 1, - direction: "REQUEST", - unknownFieldPolicy: "REJECT_UNKNOWN", - }), - ReferenceResourceListPayload: Object.freeze({ - schemaId: "ReferenceResourceListPayload", - boundary: "api-response", - owner: "feature-frontend-reference-feature-vertical-slice", - runtime: "zod", - schemaVersion: 1, - direction: "RESPONSE", - unknownFieldPolicy: "STRIP_UNKNOWN", - }), - ReferenceResourcePayload: Object.freeze({ - schemaId: "ReferenceResourcePayload", - boundary: "api-response", - owner: "feature-frontend-reference-feature-vertical-slice", - runtime: "zod", - schemaVersion: 1, - direction: "RESPONSE", - unknownFieldPolicy: "STRIP_UNKNOWN", - }), - }), - apiOperations: Object.freeze({ - LIST_REFERENCE_RESOURCES: defineRestOperation({ - method: "GET", - path: "/api/reference-resources", - operationId: "LIST_REFERENCE_RESOURCES", - auth: "external-session", - timeoutMs: null, - idempotency: "safe", - retry: "runtime", - requestSource: "search", - requestSchema: "ReferenceResourceListQuery", - responseSchema: "ReferenceResourceListPayload", - owner: "feature-frontend-reference-feature-vertical-slice", - contractVersion: 2, - protocol: "REST", - semantics: "QUERY", - replayPolicy: "SAFE", - idempotencyKeyPolicy: "NONE", - mapperId: "ReferenceResourceListMapper", - successStatuses: [200], - responseMediaTypes: ["application/json"], - maxResponseBytes: 262_144, - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_BEARER", - csrfProfileId: "NO_CSRF_BEARER", - pathSchema: "NoRequest", - pathParameterNames: [], - maxEncodedSearchBytes: 4_096, - }), - CREATE_REFERENCE_RESOURCE: defineRestOperation({ - method: "POST", - path: "/api/reference-resources", - operationId: "CREATE_REFERENCE_RESOURCE", - auth: "external-session", - timeoutMs: null, - idempotency: "keyed", - retry: "runtime", - requestSource: "body", - requestSchema: "CreateReferenceResourceCommand", - responseSchema: "ReferenceResourcePayload", - owner: "feature-frontend-reference-feature-vertical-slice", - contractVersion: 2, - protocol: "REST", - semantics: "COMMAND", - replayPolicy: "KEYED_COMMAND", - idempotencyKeyPolicy: "REQUIRED", - mapperId: "ReferenceResourceMapper", - successStatuses: [200, 201], - responseMediaTypes: ["application/json"], - maxResponseBytes: 32_768, - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_BEARER", - csrfProfileId: "NO_CSRF_BEARER", - pathSchema: "NoRequest", - pathParameterNames: [], - maxEncodedSearchBytes: 0, - }), - GET_REFERENCE_RESOURCE: defineRestOperation({ - method: "GET", - path: "/api/reference-resources/{resourceId}", - operationId: "GET_REFERENCE_RESOURCE", - auth: "external-session", - timeoutMs: null, - idempotency: "safe", - retry: "runtime", - requestSource: "none", - requestSchema: "NoRequest", - responseSchema: "ReferenceResourcePayload", - owner: "feature-frontend-reference-feature-vertical-slice", - contractVersion: 2, - protocol: "REST", - semantics: "QUERY", - replayPolicy: "SAFE", - idempotencyKeyPolicy: "NONE", - mapperId: "ReferenceResourceMapper", - successStatuses: [200], - responseMediaTypes: ["application/json"], - maxResponseBytes: 32_768, - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_BEARER", - csrfProfileId: "NO_CSRF_BEARER", - pathSchema: "ReferenceResourceParams", - pathParameterNames: ["resourceId"], - maxEncodedSearchBytes: 0, - }), - }), -} as const); diff --git a/src/features/reference-feature/contracts/reference-feature-contract.ts b/src/features/reference-feature/contracts/reference-feature-contract.ts index cfff3eb9..c9d91d45 100644 --- a/src/features/reference-feature/contracts/reference-feature-contract.ts +++ b/src/features/reference-feature/contracts/reference-feature-contract.ts @@ -11,9 +11,10 @@ export const REFERENCE_RESOURCE_INVALIDATION_TOPIC = /** * 15-01. The declaration half: what the shell reads before a reference route - * is entered. It is in the initial chunk, so it holds data only. The API - * contract with its runtime schemas and mappers is - * `reference-api-contract.ts`, loaded with `feature-runtime.ts`. + * is entered. It is in the initial chunk, so it holds data only. The schema + * metadata is `reference-schema-metadata.ts` and the HTTP operations are + * `reference-feature-contract-contribution.ts`, both loaded with + * `feature-runtime.ts`. */ export const REFERENCE_FEATURE_CONTRACT = Object.freeze({ featureId: REFERENCE_FEATURE_ID, diff --git a/src/features/reference-feature/contracts/reference-mapper.ts b/src/features/reference-feature/contracts/reference-mapper.ts index 3f607954..2527468c 100644 --- a/src/features/reference-feature/contracts/reference-mapper.ts +++ b/src/features/reference-feature/contracts/reference-mapper.ts @@ -5,7 +5,6 @@ import { import { mappingFailure, mappingSuccess, - type InstalledBoundaryMapper, type BoundaryMappingResult, } from "../../../contracts/boundary-mapper.ts"; import type { ReferenceResourceDto } from "./reference-schemas.ts"; @@ -49,83 +48,6 @@ export function mapReferenceResourceListPayload( return mappingSuccess(Object.freeze(output)); } -function isReferenceResourceDto(value: unknown): value is ReferenceResourceDto { - if (!value || typeof value !== "object" || Array.isArray(value)) return false; - const dto = value as Record; - return ( - typeof dto.id === "string" && - typeof dto.name === "string" && - (dto.createdAt === undefined || typeof dto.createdAt === "string") - ); -} - -function mapUnknownReferenceResourcePayload( - value: unknown, -): BoundaryMappingResult { - return isReferenceResourceDto(value) - ? mapReferenceResourcePayload(value) - : mappingFailure("MAPPING_INVARIANT_REJECTED"); -} - -function mapUnknownReferenceResourceListPayload( - value: unknown, -): BoundaryMappingResult { - if ( - !Array.isArray(value) || - value.length > 100 || - !value.every(isReferenceResourceDto) - ) { - return mappingFailure( - Array.isArray(value) && value.length > 100 - ? "OUTPUT_LIMIT_EXCEEDED" - : "MAPPING_INVARIANT_REJECTED", - ); - } - return mapReferenceResourceListPayload(value); -} - -/** - * Registry-facing compatibility projection. The registry is intentionally - * untyped, so its adapter performs the defensive shape check. Feature HTTP - * bindings use the typed operation-specific mappers above. - */ -export function mapReferenceOperation( - operationId: string, - payload: unknown, -): BoundaryMappingResult { - if (operationId === "LIST_REFERENCE_RESOURCES") { - return mapUnknownReferenceResourceListPayload(payload); - } - if ( - operationId === "CREATE_REFERENCE_RESOURCE" || - operationId === "GET_REFERENCE_RESOURCE" - ) { - return mapUnknownReferenceResourcePayload(payload); - } - return mappingFailure("MAPPING_INVARIANT_REJECTED"); -} - -export const REFERENCE_BOUNDARY_MAPPERS = Object.freeze({ - ReferenceResourceListMapper: Object.freeze({ - mapperId: "ReferenceResourceListMapper", - mapperVersion: 1, - inputSchemaId: "ReferenceResourceListPayload", - outputContractId: "ReferenceResourceList", - owner: "feature-frontend-reference-feature-vertical-slice", - maxOutputItems: 100, - map: mapUnknownReferenceResourceListPayload, - }), - ReferenceResourceMapper: Object.freeze({ - mapperId: "ReferenceResourceMapper", - mapperVersion: 1, - inputSchemaId: "ReferenceResourcePayload", - outputContractId: "ReferenceResource", - owner: "feature-frontend-reference-feature-vertical-slice", - maxOutputItems: 1, - map: mapUnknownReferenceResourcePayload, - }), -} satisfies Readonly>); - export function toReferenceView( resource: ReferenceResource, ): ReferenceResourceView { diff --git a/src/features/reference-feature/contracts/reference-schema-metadata.ts b/src/features/reference-feature/contracts/reference-schema-metadata.ts new file mode 100644 index 00000000..6975658f --- /dev/null +++ b/src/features/reference-feature/contracts/reference-schema-metadata.ts @@ -0,0 +1,53 @@ +/** + * FE-REG-SCHEMA rows of the reference feature's route and API schemas. + * Runtime half only (`feature-runtime.ts`); the app boot never imports it. + * The HTTP operations are the V3 descriptors in + * `reference-feature-contract-contribution.ts`; FE-REG-API reads them. + */ +export const REFERENCE_SCHEMA_METADATA = Object.freeze({ + ReferenceResourceParams: Object.freeze({ + schemaId: "ReferenceResourceParams", + boundary: "route-params", + owner: "feature-frontend-reference-feature-vertical-slice", + runtime: "zod", + schemaVersion: 1, + direction: "REQUEST", + unknownFieldPolicy: "REJECT_UNKNOWN", + }), + ReferenceResourceListQuery: Object.freeze({ + schemaId: "ReferenceResourceListQuery", + boundary: "route-search-api-request", + owner: "feature-frontend-reference-feature-vertical-slice", + runtime: "zod", + schemaVersion: 1, + direction: "REQUEST", + unknownFieldPolicy: "REJECT_UNKNOWN", + }), + CreateReferenceResourceCommand: Object.freeze({ + schemaId: "CreateReferenceResourceCommand", + boundary: "api-request", + owner: "feature-frontend-reference-feature-vertical-slice", + runtime: "zod", + schemaVersion: 1, + direction: "REQUEST", + unknownFieldPolicy: "REJECT_UNKNOWN", + }), + ReferenceResourceListPayload: Object.freeze({ + schemaId: "ReferenceResourceListPayload", + boundary: "api-response", + owner: "feature-frontend-reference-feature-vertical-slice", + runtime: "zod", + schemaVersion: 1, + direction: "RESPONSE", + unknownFieldPolicy: "STRIP_UNKNOWN", + }), + ReferenceResourcePayload: Object.freeze({ + schemaId: "ReferenceResourcePayload", + boundary: "api-response", + owner: "feature-frontend-reference-feature-vertical-slice", + runtime: "zod", + schemaVersion: 1, + direction: "RESPONSE", + unknownFieldPolicy: "STRIP_UNKNOWN", + }), +}); diff --git a/src/features/reference-feature/contracts/reference-schemas.ts b/src/features/reference-feature/contracts/reference-schemas.ts index 619cd866..ebe4a491 100644 --- a/src/features/reference-feature/contracts/reference-schemas.ts +++ b/src/features/reference-feature/contracts/reference-schemas.ts @@ -1,6 +1,4 @@ import { z } from "../../../contracts/zod.ts"; -import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts"; -import { zodValidator } from "../../../contracts/zod-validator.ts"; export const referenceResourceListQuerySchema = z .object({ @@ -67,69 +65,3 @@ export const createReferenceResourceCommandSchema = z note: z.string().trim().max(500).optional(), }) .strict(); - -const payloadSchemas = { - ReferenceResourceListPayload: z.array(referenceResourceDtoSchema).max(100), - ReferenceResourcePayload: referenceResourceDtoSchema, -} satisfies Record; - -const requestSchemas = { - ReferenceResourceParams: referenceResourceParamsSchema, - ReferenceResourceListQuery: referenceResourceListQuerySchema, - NoRequest: z.object({}).strict(), - CreateReferenceResourceCommand: createReferenceResourceCommandSchema, -} satisfies Record; - -const codec = (schemaId: string, schema: z.ZodType) => - runtimeSchemaCodecFromValidator(zodValidator(schemaId, schema)); - -export const REFERENCE_RUNTIME_SCHEMA_CODECS = Object.freeze({ - ReferenceResourceParams: codec( - "ReferenceResourceParams", - referenceResourceParamsSchema, - ), - ReferenceResourceListQuery: codec( - "ReferenceResourceListQuery", - referenceResourceListQuerySchema, - ), - NoRequest: codec("NoRequest", requestSchemas.NoRequest), - CreateReferenceResourceCommand: codec( - "CreateReferenceResourceCommand", - requestSchemas.CreateReferenceResourceCommand, - ), - ReferenceResourceListPayload: codec( - "ReferenceResourceListPayload", - payloadSchemas.ReferenceResourceListPayload, - ), - ReferenceResourcePayload: codec( - "ReferenceResourcePayload", - payloadSchemas.ReferenceResourcePayload, - ), -}); - -const NOT_REGISTERED = Object.freeze({ - success: false as const, - issues: Object.freeze([ - Object.freeze({ path: "", code: "SCHEMA_NOT_REGISTERED" }), - ]), -}); - -function validateOwned( - owned: Readonly>, - schemaId: string, - value: unknown, -) { - return Object.hasOwn(owned, schemaId) - ? REFERENCE_RUNTIME_SCHEMA_CODECS[ - schemaId as keyof typeof REFERENCE_RUNTIME_SCHEMA_CODECS - ].parse(value) - : NOT_REGISTERED; -} - -export function validateReferencePayload(schemaId: string, value: unknown) { - return validateOwned(payloadSchemas, schemaId, value); -} - -export function validateReferenceRequest(schemaId: string, value: unknown) { - return validateOwned(requestSchemas, schemaId, value); -} diff --git a/src/features/reference-feature/feature-runtime.ts b/src/features/reference-feature/feature-runtime.ts index f36b0a04..9953e987 100644 --- a/src/features/reference-feature/feature-runtime.ts +++ b/src/features/reference-feature/feature-runtime.ts @@ -1,8 +1,8 @@ import { defineFeatureRuntime } from "../feature-module.ts"; import { REFERENCE_FEATURE_ADAPTER_CONTRIBUTION } from "./adapters/create-reference-feature-input.ts"; -import { REFERENCE_API_CONTRACT } from "./contracts/reference-api-contract.ts"; import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "./contracts/reference-feature-contract-contribution.ts"; import { REFERENCE_FEATURE_ID } from "./contracts/reference-feature-contract.ts"; +import { REFERENCE_SCHEMA_METADATA } from "./contracts/reference-schema-metadata.ts"; /** * 15-01. The executable half of the reference feature. `feature-module.ts` @@ -12,7 +12,7 @@ import { REFERENCE_FEATURE_ID } from "./contracts/reference-feature-contract.ts" */ export const FEATURE_RUNTIME = defineFeatureRuntime({ featureId: REFERENCE_FEATURE_ID, - apiContract: REFERENCE_API_CONTRACT, + schemas: REFERENCE_SCHEMA_METADATA, adapters: [REFERENCE_FEATURE_ADAPTER_CONTRIBUTION], contractContributions: [REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION], } as const); diff --git a/tests/architecture/context-route-roots.test.ts b/tests/architecture/context-route-roots.test.ts index b74ebc32..b0ba7a55 100644 --- a/tests/architecture/context-route-roots.test.ts +++ b/tests/architecture/context-route-roots.test.ts @@ -22,7 +22,7 @@ function feature(id: string, paths: Readonly>) { messages: {}, loadRuntime: async () => ({ featureId: id, - apiContract: {}, + schemas: {}, adapters: [], contractContributions: [], }), diff --git a/tests/architecture/module-hierarchy.test.ts b/tests/architecture/module-hierarchy.test.ts index 3ac2f803..df268dfb 100644 --- a/tests/architecture/module-hierarchy.test.ts +++ b/tests/architecture/module-hierarchy.test.ts @@ -3,7 +3,7 @@ import { defineFeatureModule } from "../../src/features/feature-module.ts"; import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts"; import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts"; -const feature = defineFeatureModule({ id:"f", contracts:{featureId:"f"}, routes:{}, messages:{}, loadRuntime: async () => ({ featureId: "f", apiContract: {}, adapters: [], contractContributions: [] }) }); +const feature = defineFeatureModule({ id:"f", contracts:{featureId:"f"}, routes:{}, messages:{}, loadRuntime: async () => ({ featureId: "f", schemas: {}, adapters: [], contractContributions: [] }) }); describe("module hierarchy", () => { it("exposes only direct children and freezes copied arrays", () => { const features = [feature]; diff --git a/tests/architecture/topology-cardinality.test.ts b/tests/architecture/topology-cardinality.test.ts index ab611263..547f22db 100644 --- a/tests/architecture/topology-cardinality.test.ts +++ b/tests/architecture/topology-cardinality.test.ts @@ -16,7 +16,7 @@ function fakeFeature(id: string) { messages: {}, loadRuntime: async () => ({ featureId: id, - apiContract: {}, + schemas: {}, adapters: [], contractContributions: [], }), diff --git a/tests/features/feature-module.test.ts b/tests/features/feature-module.test.ts index d30848a6..13bc9db5 100644 --- a/tests/features/feature-module.test.ts +++ b/tests/features/feature-module.test.ts @@ -6,7 +6,7 @@ import { const runtimeOf = async (featureId: string) => ({ featureId, - apiContract: {}, + schemas: {}, adapters: [], contractContributions: [], }); diff --git a/tests/features/reference-feature/feature-module.test.ts b/tests/features/reference-feature/feature-module.test.ts index eff771a5..f77b1a01 100644 --- a/tests/features/reference-feature/feature-module.test.ts +++ b/tests/features/reference-feature/feature-module.test.ts @@ -14,7 +14,7 @@ describe("REFERENCE_FEATURE_MODULE", () => { expect(runtime.featureId).toBe("reference-feature"); expect(runtime.adapters.length).toBeGreaterThan(0); expect(runtime.contractContributions.length).toBeGreaterThan(0); - expect(Object.keys(runtime.apiContract.apiOperations).length).toBeGreaterThan(0); + expect(Object.keys(runtime.schemas).length).toBeGreaterThan(0); }); it("types a feature message's parameters from its catalog placeholders", () => { diff --git a/tests/features/reference-feature/reference-contract.test.ts b/tests/features/reference-feature/reference-contract.test.ts index eb2febb1..4f632f12 100644 --- a/tests/features/reference-feature/reference-contract.test.ts +++ b/tests/features/reference-feature/reference-contract.test.ts @@ -5,19 +5,20 @@ import { parseRouteInput, } from "../../../src/presentation/routes/route-codecs.ts"; import { - mapReferenceOperation, + mapReferenceResourcePayload, toReferenceView, } from "../../../src/features/reference-feature/contracts/reference-mapper.ts"; import { - validateReferencePayload, - validateReferenceRequest, -} from "../../../src/features/reference-feature/contracts/reference-schemas.ts"; + CREATE_REFERENCE_RESOURCE_CONTRACT, + GET_REFERENCE_RESOURCE_CONTRACT, + LIST_REFERENCE_RESOURCES_CONTRACT, + REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, +} from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts"; import { REFERENCE_FEATURE_CONTRACT, REFERENCE_FEATURE_ID, REFERENCE_RESOURCE_INVALIDATION_TOPIC, } from "../../../src/features/reference-feature/contracts/reference-feature-contract.ts"; -import { REFERENCE_API_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-api-contract.ts"; import { REFERENCE_FEATURE_ROUTE_CODECS } from "../../../src/features/reference-feature/presentation/reference-route-codecs.ts"; import type { ReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.ts"; import { createTestApplication } from "../../helpers/create-test-application.ts"; @@ -85,31 +86,24 @@ describe("reference feature boundary contracts", () => { ), ).toEqual({ success: false, code: "ROUTE_SEARCH_INVALID" }); expect( - validateReferencePayload("ReferenceResourceListPayload", [ + LIST_REFERENCE_RESOURCES_CONTRACT.contract.outputValidator.safeParse([ { id: "unsafe", name: 42 }, ]), ).toMatchObject({ success: false }); - expect( - mapReferenceOperation("LIST_REFERENCE_RESOURCES", [ - { id: "unsafe", name: 42 }, - ]), - ).toMatchObject({ ok: false }); }); it("normalizes request input and maps only owned domain fields", () => { expect( - validateReferenceRequest("CreateReferenceResourceCommand", { + CREATE_REFERENCE_RESOURCE_CONTRACT.contract.inputValidator.safeParse({ name: " Example ", }), ).toMatchObject({ success: true, data: { name: "Example" } }); - const model = mapReferenceOperation("CREATE_REFERENCE_RESOURCE", { + const model = mapReferenceResourcePayload({ id: "reference-1", name: "Example", createdAt: "2026-07-26T00:00:00.000Z", }); - if (!model.ok || !("id" in model.value)) { - throw new Error("expected one model"); - } + if (!model.ok) throw new Error("expected one model"); expect(toReferenceView(model.value)).toEqual({ resourceId: "reference-1", title: "Example", @@ -124,20 +118,24 @@ describe("reference feature boundary contracts", () => { "REFERENCE_RESOURCE_FORM", "REFERENCE_RESOURCE_STATUS", ]); - expect(Object.keys(REFERENCE_API_CONTRACT.apiOperations)).toEqual([ - "LIST_REFERENCE_RESOURCES", - "CREATE_REFERENCE_RESOURCE", - "GET_REFERENCE_RESOURCE", - ]); expect( - REFERENCE_API_CONTRACT.apiOperations.GET_REFERENCE_RESOURCE, - ).toMatchObject({ - pathSchema: "ReferenceResourceParams", - pathParameterNames: ["resourceId"], - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_BEARER", - csrfProfileId: "NO_CSRF_BEARER", + REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION.http.map( + ({ contract }) => contract.operationId, + ), + ).toEqual([ + "LIST_REFERENCE_RESOURCES", + "GET_REFERENCE_RESOURCE", + "CREATE_REFERENCE_RESOURCE", + ]); + expect(GET_REFERENCE_RESOURCE_CONTRACT.contract).toMatchObject({ + pathTemplate: "/api/reference-resources/{resourceId}", }); + expect(GET_REFERENCE_RESOURCE_CONTRACT.contract.inputValidator.schemaId).toBe( + "ReferenceResourceParams", + ); + expect(GET_REFERENCE_RESOURCE_CONTRACT.frontend.authProfileId).toBe( + "EXTERNAL_BEARER", + ); }); it("contributes an identity-based invalidation graph and an explicit wire version", () => { diff --git a/tests/features/reference-feature/reference-validator-protocol.test.ts b/tests/features/reference-feature/reference-validator-protocol.test.ts index ed04cc2b..91f70658 100644 --- a/tests/features/reference-feature/reference-validator-protocol.test.ts +++ b/tests/features/reference-feature/reference-validator-protocol.test.ts @@ -4,17 +4,10 @@ import { CREATE_REFERENCE_RESOURCE_CONTRACT, LIST_REFERENCE_RESOURCES_CONTRACT, } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts"; -import { - REFERENCE_RUNTIME_SCHEMA_CODECS, - validateReferencePayload, - validateReferenceRequest, -} from "../../../src/features/reference-feature/contracts/reference-schemas.ts"; /** - * Q-6.7-8 characterization. The reference feature exposes one schema through - * two protocols: the canonical `RuntimeValidator` (array paths) for the HTTP - * contract and the registry-facing `RuntimeSchemaCodec` (dotted paths). Both - * must keep answering exactly this after they share one zod wrapper. + * Q-6.7-8 characterization. The reference feature's schemas answer through the + * canonical `RuntimeValidator` protocol (array paths) of its HTTP contract. */ describe("reference validator protocols", () => { const badList = [{ id: "unsafe", name: 42 }]; @@ -34,55 +27,4 @@ describe("reference validator protocols", () => { }), ).toEqual({ success: true, data: { name: "Example" } }); }); - - it("answers the schema codec with dotted paths", () => { - const codecs = REFERENCE_RUNTIME_SCHEMA_CODECS; - expect(codecs.ReferenceResourceListPayload.parse(badList)).toEqual({ - success: false, - issues: [{ path: "0.name", code: "invalid_type" }], - }); - expect( - codecs.CreateReferenceResourceCommand.parse({ name: "a", extra: 1 }), - ).toEqual({ - success: false, - issues: [{ path: "", code: "unrecognized_keys" }], - }); - expect( - codecs.ReferenceResourceListQuery.parse({ limit: "5", tags: "open" }), - ).toEqual({ success: true, data: { limit: 5, tags: ["open"] } }); - expect(Object.keys(codecs)).toEqual([ - "ReferenceResourceParams", - "ReferenceResourceListQuery", - "NoRequest", - "CreateReferenceResourceCommand", - "ReferenceResourceListPayload", - "ReferenceResourcePayload", - ]); - for (const [schemaId, codec] of Object.entries(codecs)) { - expect(codec.schemaId).toBe(schemaId); - } - }); - - it("keeps the payload and request lookups apart", () => { - expect(validateReferencePayload("ReferenceResourceListPayload", badList)) - .toEqual({ - success: false, - issues: [{ path: "0.name", code: "invalid_type" }], - }); - expect(validateReferencePayload("NoRequest", {})).toEqual({ - success: false, - issues: [{ path: "", code: "SCHEMA_NOT_REGISTERED" }], - }); - expect( - validateReferenceRequest("CreateReferenceResourceCommand", { - name: " Example ", - }), - ).toEqual({ success: true, data: { name: "Example" } }); - expect( - validateReferenceRequest("ReferenceResourcePayload", {}), - ).toEqual({ - success: false, - issues: [{ path: "", code: "SCHEMA_NOT_REGISTERED" }], - }); - }); }); diff --git a/tests/helpers/fixture-feature.tsx b/tests/helpers/fixture-feature.tsx index 2ff08cfa..b1f875fd 100644 --- a/tests/helpers/fixture-feature.tsx +++ b/tests/helpers/fixture-feature.tsx @@ -123,12 +123,7 @@ export const FIXTURE_FEATURE_MODULE = defineFeatureModule({ loadRuntime: async () => Object.freeze({ featureId: FIXTURE_FEATURE_ID, - apiContract: Object.freeze({ - apiOperations: Object.freeze({}), - schemas: Object.freeze({}), - runtimeSchemas: Object.freeze({}), - mappers: Object.freeze({}), - }), + schemas: Object.freeze({}), adapters: Object.freeze([]), contractContributions: Object.freeze([]), }), diff --git a/tests/helpers/fixture-layout-product.tsx b/tests/helpers/fixture-layout-product.tsx index 0d8d15b8..3d6e0bb2 100644 --- a/tests/helpers/fixture-layout-product.tsx +++ b/tests/helpers/fixture-layout-product.tsx @@ -83,12 +83,7 @@ function layoutFeature(featureId: string, specs: readonly RouteSpec[]) { loadRuntime: async () => Object.freeze({ featureId, - apiContract: Object.freeze({ - apiOperations: Object.freeze({}), - schemas: Object.freeze({}), - runtimeSchemas: Object.freeze({}), - mappers: Object.freeze({}), - }), + schemas: Object.freeze({}), adapters: Object.freeze([]), contractContributions: Object.freeze([]), }), diff --git a/tests/unit/api-operation-rows.test.ts b/tests/unit/api-operation-rows.test.ts new file mode 100644 index 00000000..fac6639b --- /dev/null +++ b/tests/unit/api-operation-rows.test.ts @@ -0,0 +1,80 @@ +import { describe, expect, it } from "vitest"; + +import { projectApiOperationRows } from "../../src/contracts/api-operations.ts"; +import { composeContractContributions } from "../../src/contracts/external-contract-runtime.ts"; +import { + API_OPERATIONS, + COMPOSED_CONTRACT_CONTRIBUTIONS, +} from "../../src/features/loaded-feature-runtimes.ts"; +import { + TEST_CONTRACT_CONTRIBUTION, + TEST_LIST_HTTP_CONTRACT, +} from "../helpers/external-contract-fixture.ts"; + +/** + * FE-REG-API rows are projected from the installed HTTP descriptors, so an + * operation is written once and the governed row cannot disagree with what + * executes. + */ +describe("FE-REG-API rows projected from HTTP descriptors", () => { + it("projects each descriptor with its feature, wire and schema identities", () => { + const rows = projectApiOperationRows( + composeContractContributions([TEST_CONTRACT_CONTRIBUTION]).contributions, + ); + + expect(Object.keys(rows)).toEqual([ + "TEST_LIST_ENTITIES", + "TEST_GET_ENTITY", + "TEST_CREATE_ENTITY", + ]); + expect(rows.TEST_LIST_ENTITIES).toEqual({ + operationId: "TEST_LIST_ENTITIES", + featureId: "test-feature", + method: "GET", + path: "/api/test-entities", + authProfileId: "ANONYMOUS", + retrySemantics: "SAFE", + requestBody: "NONE", + responseBody: "REQUIRED_JSON", + responseEnvelope: "NONE", + requestSchema: "TestEntityListQuery", + responseSchema: "TestEntityListPayload", + problemSchema: "TestProblem", + }); + expect(rows.TEST_CREATE_ENTITY).toMatchObject({ + method: "POST", + retrySemantics: "KEYED", + requestBody: "JSON", + }); + }); + + it("carries an Envelope declaration", () => { + const rows = projectApiOperationRows( + composeContractContributions([ + { + ...TEST_CONTRACT_CONTRIBUTION, + http: [ + { + ...TEST_LIST_HTTP_CONTRACT, + contract: { + ...TEST_LIST_HTTP_CONTRACT.contract, + responseEnvelope: "ENVELOPE_V1" as const, + }, + }, + ] as never, + }, + ]).contributions, + ); + + expect(rows.TEST_LIST_ENTITIES?.responseEnvelope).toBe("ENVELOPE_V1"); + }); + + it("is what the registry governance reads for the installed features", () => { + expect(API_OPERATIONS).toEqual( + projectApiOperationRows(COMPOSED_CONTRACT_CONTRIBUTIONS.contributions), + ); + expect(Object.keys(API_OPERATIONS).sort()).toEqual( + [...COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.keys()].sort(), + ); + }); +}); diff --git a/tests/unit/api-operation-v2.test.ts b/tests/unit/api-operation-v2.test.ts deleted file mode 100644 index 3e04d094..00000000 --- a/tests/unit/api-operation-v2.test.ts +++ /dev/null @@ -1,122 +0,0 @@ -import { describe, expect, it } from "vitest"; - -import { - composeApiOperations, - defineRestOperation, - type RestOperationV2, -} from "../../src/contracts/api-operations.ts"; -import { API_OPERATIONS } from "../../src/features/loaded-feature-runtimes.ts"; - -function operation(operationId = "GET_RESOURCE") { - return defineRestOperation({ - contractVersion: 2, - protocol: "REST", - semantics: "QUERY", - method: "GET", - path: "/resources/{resourceId}", - operationId, - auth: "external-session", - timeoutMs: 5_000, - idempotency: "safe", - retry: "runtime", - replayPolicy: "SAFE", - idempotencyKeyPolicy: "NONE", - requestSource: "none", - requestSchema: "NoRequest", - responseSchema: "ResourcePayload", - mapperId: "ResourceMapper", - successStatuses: [200], - responseMediaTypes: ["application/json"], - maxResponseBytes: 32_768, - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_BEARER", - csrfProfileId: "NO_CSRF_BEARER", - pathSchema: "ResourceParams", - pathParameterNames: ["resourceId"], - maxEncodedSearchBytes: 0, - owner: "test", - }); -} - -describe("REST operation v2 registry", () => { - it("rejects duplicate contributions before an object spread can overwrite them", () => { - const selected = operation(); - expect(() => - composeApiOperations([ - { GET_RESOURCE: selected }, - { GET_RESOURCE: selected }, - ]), - ).toThrow("Duplicate API operation"); - }); - - it("rejects an unsafe query/replay policy combination", () => { - expect(() => - defineRestOperation({ - ...operation(), - method: "POST", - }), - ).toThrow("Incoherent REST replay contract"); - }); - - // 07-06 (MX5). A KEYED command without a required idempotency key would be - // resent with no key to bind the retry to. - it("rejects a KEYED_COMMAND whose idempotency key is not required", () => { - expect(() => - defineRestOperation({ ...command(), idempotencyKeyPolicy: "NONE" }), - ).toThrow("Incoherent REST replay contract: CREATE_RESOURCE"); - expect(defineRestOperation(command()).idempotencyKeyPolicy).toBe("REQUIRED"); - }); -}); - -function command(): RestOperationV2 { - return { - ...operation(), - semantics: "COMMAND", - method: "POST", - path: "/resources", - operationId: "CREATE_RESOURCE", - idempotency: "keyed", - replayPolicy: "KEYED_COMMAND", - idempotencyKeyPolicy: "REQUIRED", - requestSource: "body", - pathSchema: "NoRequest", - pathParameterNames: [], - }; -} - -/** - * R-7.4. CSRF protection is chosen from the HTTP method, so a COMMAND sent - * as GET/HEAD would skip it. browser-rpc and the V3 composition already bind - * commands to unsafe methods; REST V2 must too. - */ -describe("REST operation v2 command method and enum rules", () => { - it.each(["POST", "PUT", "PATCH", "DELETE"])("accepts a COMMAND sent as %s", (method) => { - expect(defineRestOperation({ ...command(), method }).method).toBe(method); - }); - - it.each(["GET", "HEAD", "OPTIONS", "post"])("rejects a COMMAND sent as %s", (method) => { - expect(() => defineRestOperation({ ...command(), method })).toThrow(TypeError); - expect(() => - composeApiOperations([{ CREATE_RESOURCE: { ...command(), method } }]), - ).toThrow(TypeError); - }); - - it.each<[string, Record]>([ - ["semantics", { semantics: "SUBSCRIBE" }], - ["replayPolicy", { replayPolicy: "ALWAYS" }], - ])("rejects an unknown %s value", (_field, patch) => { - void _field; - const candidate = { ...command(), ...patch } as unknown as RestOperationV2; - expect(() => defineRestOperation(candidate)).toThrow(TypeError); - }); - - it("keeps every installed REST v2 operation valid", () => { - for (const installed of Object.values(API_OPERATIONS)) { - if (installed.contractVersion !== 2) continue; - expect( - () => defineRestOperation(installed as RestOperationV2), - installed.operationId, - ).not.toThrow(); - } - }); -}); diff --git a/tests/unit/contract-registry-lookup.test.ts b/tests/unit/contract-registry-lookup.test.ts index 5762be27..e76f9a05 100644 --- a/tests/unit/contract-registry-lookup.test.ts +++ b/tests/unit/contract-registry-lookup.test.ts @@ -1,6 +1,5 @@ import { describe, expect, it } from "vitest"; -import { getApiOperation } from "../../src/contracts/api-operations.ts"; import { mapWithBoundaryRegistry } from "../../src/contracts/boundary-mapper.ts"; import { isAllowedOfflineTransition, @@ -17,12 +16,6 @@ import { getStorageDefinition } from "../../src/contracts/storage-keys.ts"; const INHERITED = ["constructor", "__proto__", "toString", "hasOwnProperty"]; describe("registry lookups ignore inherited keys", () => { - it("getApiOperation", () => { - for (const id of INHERITED) { - expect(() => getApiOperation(id), id).toThrow("Unregistered API operation"); - } - }); - it("getStorageDefinition", () => { for (const id of INHERITED) { expect(() => getStorageDefinition(id), id).toThrow( diff --git a/tests/unit/http-operation-v2-v3-parity.test.ts b/tests/unit/http-operation-v2-v3-parity.test.ts deleted file mode 100644 index 4ada352c..00000000 --- a/tests/unit/http-operation-v2-v3-parity.test.ts +++ /dev/null @@ -1,97 +0,0 @@ -import { describe, expect, it } from "vitest"; - -import type { - ApiOperation, - RestOperationV2, -} from "../../src/contracts/api-operations.ts"; -import { - API_OPERATIONS, - INSTALLED_CONTRACT_CONTRIBUTIONS, -} from "../../src/features/loaded-feature-runtimes.ts"; - -// 07-03 (D-7), 07-02. FE-REG-API governs the V2 rows while the V3 descriptors -// are what executes. Until V2 is generated from V3, both copies must agree. -const RETRY_SEMANTICS_FOR_REPLAY_POLICY = Object.freeze({ - SAFE: "SAFE", - IDEMPOTENT: "IDEMPOTENT", - KEYED_COMMAND: "KEYED", - NON_REPLAYABLE: "NEVER", -} as const); - -const v3ByOperationId = new Map( - INSTALLED_CONTRACT_CONTRIBUTIONS.flatMap((contribution) => - contribution.http.map( - (descriptor) => [descriptor.contract.operationId, descriptor] as const, - ), - ), -); -const v2Rows = (Object.values(API_OPERATIONS) as readonly ApiOperation[]).filter( - (operation): operation is RestOperationV2 => operation.contractVersion === 2, -); - -// V3 validates the whole canonical input with one schema; V2 splits it into a -// path schema and a request (search or body) schema. The row says which of -// the two carry input: path parameters, and a request source other than -// "none". The other one names the feature's empty-input schema, whatever the -// feature calls it (schema ids are global, so a second feature cannot reuse -// the sample's `NoRequest`). An operation that needs both has no rule yet and -// fails here until one is written down. -function v2InputSchema(row: RestOperationV2): string { - const declared = [ - ...(row.pathParameterNames.length > 0 ? [row.pathSchema] : []), - ...(row.requestSource !== "none" ? [row.requestSchema] : []), - ]; - expect( - declared.length, - `${row.operationId}: V2 declares both a path and a request schema; decide which V3 input schema matches them`, - ).toBeLessThanOrEqual(1); - return declared[0] ?? row.requestSchema; -} - -describe("HTTP operation V2 rows and V3 descriptors", () => { - // 07-02. Both directions: a V3-only operation executes outside the - // FE-REG-API gate, a V2-only one is governed but never executes. With the - // sample feature removed both sets are empty, which is why there is no - // "at least one row" assertion (test:sample-removal runs this file). - it("cover the same operations", () => { - expect([...v3ByOperationId.keys()].sort(), "V3 descriptors").toEqual( - v2Rows.map((row) => row.operationId).sort(), - ); - }); - - it("declare the same method, path, statuses, limit, auth profile, replay policy, write semantics, request body and schema ids", () => { - for (const row of v2Rows) { - const descriptor = v3ByOperationId.get(row.operationId); - expect(descriptor, `${row.operationId} has no V3 descriptor`).toBeDefined(); - if (!descriptor) continue; - expect( - { - method: descriptor.contract.method, - path: descriptor.contract.pathTemplate, - successStatuses: [...descriptor.contract.acceptedStatuses], - maxResponseBytes: descriptor.frontend.responseByteLimit, - authProfileId: descriptor.frontend.authProfileId, - retrySemantics: descriptor.contract.retrySemantics, - // The executor treats an operation as a write by its effect - // descriptor, not by its method. - semantics: descriptor.contract.commandEffect === null ? "QUERY" : "COMMAND", - requestBody: descriptor.contract.requestBody, - inputSchema: descriptor.contract.inputValidator.schemaId, - responseSchema: descriptor.contract.outputValidator.schemaId, - }, - row.operationId, - ).toEqual({ - method: row.method, - path: row.path, - successStatuses: [...row.successStatuses], - maxResponseBytes: row.maxResponseBytes, - authProfileId: row.authProfileId, - retrySemantics: RETRY_SEMANTICS_FOR_REPLAY_POLICY[row.replayPolicy], - semantics: row.semantics, - requestBody: row.requestSource === "body" ? "JSON" : "NONE", - inputSchema: v2InputSchema(row), - responseSchema: row.responseSchema, - }); - } - }); -}); diff --git a/tests/unit/realtime/fixture.ts b/tests/unit/realtime/fixture.ts index faac3734..372db896 100644 --- a/tests/unit/realtime/fixture.ts +++ b/tests/unit/realtime/fixture.ts @@ -2,7 +2,7 @@ import { mappingSuccess, type InstalledBoundaryMapper, } from "../../../src/contracts/boundary-mapper.ts"; -import type { ApiOperation } from "../../../src/contracts/api-operations.ts"; +import type { ApiOperationRow } from "../../../src/contracts/api-operations.ts"; import { createRealtimePolicyRegistry, defineEventTypeId, @@ -102,33 +102,19 @@ export const TEST_MAPPERS = Object.freeze({ ReferenceRealtimeMapper: TEST_MAPPER, }); -const snapshotOperation: ApiOperation = Object.freeze({ +const snapshotOperation: ApiOperationRow = Object.freeze({ + operationId: "GET_REFERENCE_REALTIME_SNAPSHOT", + featureId: "sample-feature", method: "GET", path: "/api/reference-snapshot", - operationId: "GET_REFERENCE_REALTIME_SNAPSHOT", - auth: "external-session", - timeoutMs: 10_000, - idempotency: "safe", - retry: "never", - requestSource: "none", + authProfileId: "EXTERNAL_BEARER", + retrySemantics: "SAFE", + requestBody: "NONE", + responseBody: "REQUIRED_JSON", + responseEnvelope: "NONE", requestSchema: "NoRequest", responseSchema: "ReferenceRealtimeCheckpoint", - owner: "sample-owner", - contractVersion: 2, - protocol: "REST", - semantics: "QUERY", - replayPolicy: "SAFE", - idempotencyKeyPolicy: "NONE", - mapperId: "ReferenceRealtimeSnapshotMapper", - successStatuses: [200], - responseMediaTypes: ["application/json"], - maxResponseBytes: 16_384, - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_SESSION", - csrfProfileId: "NONE", - pathSchema: "NoRequest", - pathParameterNames: [], - maxEncodedSearchBytes: 0, + problemSchema: "ReferenceRealtimeProblem", }); export const TEST_API_OPERATIONS = Object.freeze({ diff --git a/tests/unit/rest-profile-contract.test.ts b/tests/unit/rest-profile-contract.test.ts index d64627a5..09be86f6 100644 --- a/tests/unit/rest-profile-contract.test.ts +++ b/tests/unit/rest-profile-contract.test.ts @@ -3,177 +3,32 @@ import path from "node:path"; import { describe, expect, it } from "vitest"; -import { defineRestOperation } from "../../src/contracts/api-operations.ts"; import { composeContractContributions, ContractContributionError, } from "../../src/contracts/external-contract-runtime.ts"; import { - createRestProviderProfile, INSTALLED_REST_AUTH_PROFILES, installRestAuthProfileRegistry, - resolveRestSecurityProfiles, REST_AUTH_PROFILES, - validateRestProfileBindings, } from "../../src/contracts/rest-profiles.ts"; import { TEST_CONTRACT_CONTRIBUTION } from "../helpers/external-contract-fixture.ts"; -/** - * §24.12: the common REST profile contract must stay independently verifiable - * after the sample feature is removed, so this suite owns its own operation - * fixture instead of importing an installed feature contract. - */ -const SAMPLE_COMMAND = defineRestOperation({ - method: "POST", - path: "/api/sample-resources", - operationId: "CREATE_SAMPLE_RESOURCE", - auth: "external-session", - timeoutMs: null, - idempotency: "keyed", - retry: "runtime", - requestSource: "body", - requestSchema: "SampleCommand", - responseSchema: "SamplePayload", - owner: "platform-test-fixture", - contractVersion: 2, - protocol: "REST", - semantics: "COMMAND", - replayPolicy: "KEYED_COMMAND", - idempotencyKeyPolicy: "REQUIRED", - mapperId: "SampleMapper", - successStatuses: [200, 201], - responseMediaTypes: ["application/json"], - maxResponseBytes: 32_768, - providerId: "PRIMARY_API", - authProfileId: "EXTERNAL_BEARER", - csrfProfileId: "NO_CSRF_BEARER", - pathSchema: "NoRequest", - pathParameterNames: [], - maxEncodedSearchBytes: 0, -}); - -const SAMPLE_OPERATIONS = Object.freeze({ - CREATE_SAMPLE_RESOURCE: SAMPLE_COMMAND, -}); - -describe("REST provider/auth/CSRF profiles", () => { - it("preserves the provider prefix and rejects unsafe endpoint forms", () => { - expect( - createRestProviderProfile( - "PRIMARY_API", - "https://api.test/base/", - ["omit"], - ), - ).toMatchObject({ - providerId: "PRIMARY_API", - baseUrl: "https://api.test/base/", - redirect: "error", - referrerPolicy: "no-referrer", - }); - expect(() => - createRestProviderProfile( - "PRIMARY_API", - "https://user:password@api.test/base/", - ), - ).toThrow("Invalid REST provider profile"); - expect(() => - createRestProviderProfile("PRIMARY_API", "http://api.test/base/"), - ).toThrow("Invalid REST provider profile"); - }); - - it("resolves bearer auth to omit credentials and no CSRF", () => { - const resolved = resolveRestSecurityProfiles( - SAMPLE_COMMAND, - createRestProviderProfile("PRIMARY_API", "https://api.test", ["omit"]), - ); - expect(resolved).toMatchObject({ - auth: { - transport: "BEARER_HEADER", - credentials: "omit", - allowedCredentialHeaders: ["authorization"], - }, - csrf: { mode: "NONE" }, - }); - }); - - it("validates every installed profile binding as a set", () => { - expect( - validateRestProfileBindings(SAMPLE_OPERATIONS, { - PRIMARY_API: ["omit"], - }), - ).toBe(true); - expect(() => - validateRestProfileBindings(SAMPLE_OPERATIONS, {}), - ).toThrow("Unregistered REST provider binding"); - }); - - // 16-03. A copied feature that renamed the sample's profile id stopped every - // gate with one sentence that named neither the operation nor the profile. - it("names the operation, the profile and the broken condition", () => { - const renamed = Object.freeze({ - CREATE_SAMPLE_RESOURCE: { - ...SAMPLE_COMMAND, - authProfileId: "ORDER_EXTERNAL_BEARER", - }, - }); - expect(() => - validateRestProfileBindings(renamed, { PRIMARY_API: ["omit"] }), - ).toThrow( - /incoherent.*CREATE_SAMPLE_RESOURCE.*unknown authProfileId ORDER_EXTERNAL_BEARER/, - ); - - const publicWithBearer = Object.freeze({ - CREATE_SAMPLE_RESOURCE: { ...SAMPLE_COMMAND, auth: "none" as const }, - }); - expect(() => - validateRestProfileBindings(publicWithBearer, { PRIMARY_API: ["omit"] }), - ).toThrow( - /CREATE_SAMPLE_RESOURCE.*auth "none" needs an ANONYMOUS profile.*EXTERNAL_BEARER is BEARER_HEADER/, - ); - }); -}); - -/** - * Q-6.7-9. Composition, the V3 executor and the V2 resolve must all answer - * from one validated installed registry. A raw record handed to resolve used - * to skip installation, so a bearer profile with ambient credentials passed. - */ describe("one installed REST auth profile registry", () => { - const provider = createRestProviderProfile("PRIMARY_API", "https://api.test", [ - "omit", - "same-origin", - ]); - - it("rejects a raw profile record that installation would refuse", () => { - const incoherent = { - EXTERNAL_BEARER: { - ...REST_AUTH_PROFILES.EXTERNAL_BEARER, - credentials: "same-origin" as const, - }, - }; + it("refuses a raw profile record that is incoherent", () => { expect(() => - resolveRestSecurityProfiles(SAMPLE_COMMAND, provider, incoherent), + installRestAuthProfileRegistry({ + EXTERNAL_BEARER: { + ...REST_AUTH_PROFILES.EXTERNAL_BEARER, + credentials: "same-origin" as const, + }, + }), ).toThrow(TypeError); }); - it("resolves through the installed registry", () => { - expect( - resolveRestSecurityProfiles( - SAMPLE_COMMAND, - provider, - INSTALLED_REST_AUTH_PROFILES, - ).auth, - ).toBe(INSTALLED_REST_AUTH_PROFILES.get("EXTERNAL_BEARER")); - }); - - it("does not resolve an inherited profile id", () => { - expect(() => - resolveRestSecurityProfiles( - { ...SAMPLE_COMMAND, authProfileId: "toString" }, - provider, - REST_AUTH_PROFILES, - ), - ).toThrow("incoherent"); + it("does not answer for an inherited profile id", () => { + expect(INSTALLED_REST_AUTH_PROFILES.has("toString")).toBe(false); + expect(INSTALLED_REST_AUTH_PROFILES.get("toString")).toBeUndefined(); }); it("composes contributions against the registry it is given", () => { diff --git a/tests/unit/second-api-feature-registries.test.ts b/tests/unit/second-api-feature-registries.test.ts index 5765a9da..4e319787 100644 --- a/tests/unit/second-api-feature-registries.test.ts +++ b/tests/unit/second-api-feature-registries.test.ts @@ -23,13 +23,18 @@ const FEATURE_ID = "second-api-feature"; const CONTEXT_ID = "second-api-context"; const TOPIC_ID = "qinv.01kb3m8q2v6t4r9s1n5p7c0w"; -const FEATURE_CONTRACT = `import { defineRestOperation } from "../../../contracts/api-operations.ts"; -import type { InstalledBoundaryMapper } from "../../../contracts/boundary-mapper.ts"; -import { mappingFailure, mappingSuccess } from "../../../contracts/boundary-mapper.ts"; +const FEATURE_CONTRACT = `import { + PLACEHOLDER_CONTRACT_PACKAGE_DIGEST, + PLACEHOLDER_CONTRACT_PACKAGE_REVISION, + PLACEHOLDER_CONTRACT_PACKAGE_VERSION, +} from "../../../contracts/deployment-admission.ts"; +import type { + InstalledContractContribution, + InstalledHttpContract, +} from "../../../contracts/external-contract-runtime.ts"; import { unvalidatedPayload } from "../../../contracts/unvalidated-payload.ts"; import { defineQueryInvalidationTopic } from "../../../contracts/query-invalidation.ts"; import { defineQueryNamespaceIdentity } from "../../../contracts/query-keys.ts"; -import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts"; const OWNER = "feature-frontend-second-api-feature"; const SECOND_ITEM_TOPIC = defineQueryInvalidationTopic("${TOPIC_ID}"); @@ -38,10 +43,16 @@ const SECOND_ITEM_NAMESPACE = defineQueryNamespaceIdentity("second-item", 1); const schema = (schemaId: string, boundary: string, direction: string) => Object.freeze({ schemaId, boundary, owner: OWNER, runtime: "zod", schemaVersion: 1, direction }); -const codec = (schemaId: string) => - runtimeSchemaCodecFromValidator( - unvalidatedPayload(schemaId, "registry fixture: only check-registries reads it"), - ); +const unchecked = (schemaId: string) => + unvalidatedPayload(schemaId, "registry fixture: only check-registries reads it"); + +const SECOND_CONTRACT_PACKAGE = Object.freeze({ + packageId: "@org-contracts/second-api", + version: PLACEHOLDER_CONTRACT_PACKAGE_VERSION, + digest: PLACEHOLDER_CONTRACT_PACKAGE_DIGEST, + runtimeProtocolVersion: 1 as const, + sourceRevision: PLACEHOLDER_CONTRACT_PACKAGE_REVISION, +}); const ROUTES = Object.freeze({ SECOND_ITEM_LIST: Object.freeze({ @@ -81,66 +92,57 @@ export const SECOND_API_CONTRACT = Object.freeze({ topicVersions: Object.freeze([ Object.freeze({ topicId: SECOND_ITEM_TOPIC, topicVersion: 1 }), ]), - contractPackages: Object.freeze([]), + contractPackages: Object.freeze([SECOND_CONTRACT_PACKAGE]), } as const); -// Runtime half: the V2 API contract, loaded with feature-runtime.ts. -export const SECOND_API_V2_CONTRACT = Object.freeze({ - apiOperations: Object.freeze({ - GET_SECOND_ITEM: defineRestOperation({ - method: "GET", - path: "/api/second-items/{itemId}", - operationId: "GET_SECOND_ITEM", - auth: "none", - timeoutMs: null, - idempotency: "safe", - retry: "runtime", - requestSource: "none", - requestSchema: "SecondItemRequest", - responseSchema: "SecondItemPayload", - owner: OWNER, - contractVersion: 2, - protocol: "REST", - semantics: "QUERY", - replayPolicy: "SAFE", - idempotencyKeyPolicy: "NONE", - mapperId: "SecondItemMapper", - successStatuses: [200], - responseMediaTypes: ["application/json"], - maxResponseBytes: 16_384, - providerId: "PRIMARY_API", - authProfileId: "ANONYMOUS", - csrfProfileId: "NO_CSRF_BEARER", - pathSchema: "SecondItemParams", - pathParameterNames: ["itemId"], - maxEncodedSearchBytes: 0, - }), - }), - schemas: Object.freeze({ - SecondItemListQuery: schema("SecondItemListQuery", "route-search", "REQUEST"), - SecondItemParams: schema("SecondItemParams", "api-request", "REQUEST"), - SecondItemRequest: schema("SecondItemRequest", "api-request", "REQUEST"), - SecondItemPayload: schema("SecondItemPayload", "api-response", "RESPONSE"), - }), - runtimeSchemas: Object.freeze({ - SecondItemListQuery: codec("SecondItemListQuery"), - SecondItemParams: codec("SecondItemParams"), - SecondItemRequest: codec("SecondItemRequest"), - SecondItemPayload: codec("SecondItemPayload"), - }), - mappers: Object.freeze({ - SecondItemMapper: Object.freeze({ - mapperId: "SecondItemMapper", - mapperVersion: 1, - inputSchemaId: "SecondItemPayload", - outputContractId: "SecondItem", - owner: OWNER, - maxOutputItems: 1, - map: (value: unknown) => - value && typeof value === "object" ? mappingSuccess(value) : mappingFailure("MAPPING_INVARIANT_REJECTED"), - } satisfies InstalledBoundaryMapper), - }), +// Runtime half, loaded with feature-runtime.ts. +export const SECOND_API_SCHEMAS = Object.freeze({ + SecondItemListQuery: schema("SecondItemListQuery", "route-search", "REQUEST"), + SecondItemParams: schema("SecondItemParams", "api-request", "REQUEST"), + SecondItemPayload: schema("SecondItemPayload", "api-response", "RESPONSE"), } as const); + +export const SECOND_API_CONTRIBUTION: InstalledContractContribution = Object.freeze({ + contributionId: "second-api-feature-http-v1", + featureId: "${FEATURE_ID}", + source: Object.freeze({ kind: "EXTERNAL_PACKAGE" as const, package: SECOND_CONTRACT_PACKAGE }), + http: Object.freeze([ + Object.freeze({ + contract: Object.freeze({ + operationId: "GET_SECOND_ITEM", + method: "GET" as const, + pathTemplate: "/api/second-items/{itemId}", + inputValidator: unchecked("SecondItemParams"), + outputValidator: unchecked("SecondItemPayload"), + problemValidator: unchecked("SecondItemProblem"), + acceptedStatuses: Object.freeze([200]), + emptyBodyStatuses: Object.freeze([]), + retrySemantics: "SAFE" as const, + requestBody: "NONE" as const, + responseBody: "REQUIRED_JSON" as const, + responseEnvelope: "ENVELOPE_V1" as const, + commandRecovery: null, + commandEffect: null, + projectRequest: (input: unknown) => + Object.freeze({ + pathValues: Object.freeze({ itemId: String((input as { itemId: string }).itemId) }), + queryEntries: Object.freeze([]), + body: null, + }), + }), + frontend: Object.freeze({ + policyId: "SECOND_ITEM_V1", + requestByteLimit: 0, + responseByteLimit: 16_384, + totalDeadlineMs: 10_000, + retryBudget: 0 as const, + authProfileId: "ANONYMOUS", + diagnosticsOperation: "second.item", + }), + }), + ]) as readonly InstalledHttpContract[], + events: Object.freeze([]), +}); `; const FEATURE_MODULE = `import { defineFeatureModule } from "../feature-module.ts"; @@ -159,13 +161,16 @@ export const FEATURE_MODULE = defineFeatureModule({ `; const FEATURE_RUNTIME = `import { defineFeatureRuntime } from "../feature-module.ts"; -import { SECOND_API_V2_CONTRACT } from "./contracts/second-api-contract.ts"; +import { + SECOND_API_CONTRIBUTION, + SECOND_API_SCHEMAS, +} from "./contracts/second-api-contract.ts"; export const FEATURE_RUNTIME = defineFeatureRuntime({ featureId: "${FEATURE_ID}", - apiContract: SECOND_API_V2_CONTRACT, + schemas: SECOND_API_SCHEMAS, adapters: [], - contractContributions: [], + contractContributions: [SECOND_API_CONTRIBUTION], } as const); `; diff --git a/tests/unit/two-feature-install-typecheck.test.ts b/tests/unit/two-feature-install-typecheck.test.ts index 71b80c28..b19df20a 100644 --- a/tests/unit/two-feature-install-typecheck.test.ts +++ b/tests/unit/two-feature-install-typecheck.test.ts @@ -58,7 +58,7 @@ declare module "../../application/ports/in/application-api.ts" { export const FEATURE_RUNTIME = defineFeatureRuntime({ featureId: "second-feature", - apiContract: { apiOperations: {}, schemas: {}, runtimeSchemas: {}, mappers: {} }, + schemas: {}, adapters: [ defineFeatureAdapterContribution({ featureId: "second-feature", @@ -126,7 +126,7 @@ export const FEATURE_MODULE = defineFeatureModule({ messages: { "ko-KR": MESSAGES, "en-US": MESSAGES }, loadRuntime: async () => ({ featureId: FEATURE_MODULE_ID, - apiContract: { apiOperations: {}, schemas: {}, runtimeSchemas: {}, mappers: {} }, + schemas: {}, adapters: [], contractContributions: [], }),