refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제 기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행 (defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고, contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게 http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가 없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을 위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석 (resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만 남기고, 레지스트리 기준선 재승인을 승인했다. 고른 방법 - src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다. 조립된 contribution의 descriptor마다 operationId, featureId, method, path, authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope, request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는 같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다. requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다. - FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다. installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고 FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다. - realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과 retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics· replayPolicy 대신). - rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립 때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다. - 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로 바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를 지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다. - create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를 만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다. - 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다 (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음). - 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다. 버린 대안 - V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은 실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다. - 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary· unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를 쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다. 위험·한계 - BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes 의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다. 옮기는 법은 CHANGELOG에 적는다. - V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF 모드)가 사라졌다. V3 descriptor에는 그 칸이 없다. - BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2 필드를 갖지만 자체 계약이라 바꾸지 않았다. 검증 - check:types, lint, check:architecture, check:registries(11 registries PASS, compatibility=none), check:ci, check:diagnostics, check:adapter-inventory, verify:documentation 통과. - test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함), test:integration 114, test:component 245, test:contract 23, test:runtime-schema 56, tests/features 99 통과. - tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두 번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다. - check:bundle 통과. 초기 JS 201,598 → 200,911 B. - test:feature-scaffold 16개, test:sample-removal 23개 검사 통과. BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다. defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations, validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS, createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles, validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile, loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은 operation을 contract contribution에만 적고, schemas 행을 feature-runtime에 넘긴다.
This commit is contained in:
@@ -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"
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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"
|
||||
]
|
||||
|
||||
@@ -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`).
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -158,12 +158,12 @@ corepack pnpm create:feature invoice-feature
|
||||
생성된 파일:
|
||||
|
||||
- `contracts/<base>-feature-contract.ts`: 선언 쪽. 라우트, 무효화, 계약 패키지 신원(`contractPackages`).
|
||||
- `contracts/<base>-api-contract.ts`: V2 행. `check:registries`가 검사하는 선언이다.
|
||||
- `contracts/<base>-contract-contribution.ts`: V3 descriptor. 실제로 실행되는 HTTP 계약이다.
|
||||
- `contracts/<base>-contract-contribution.ts`: HTTP 계약(descriptor). operation을 적는 곳은 여기 하나다. 이것이 실행되고, `check:registries`의 FE-REG-API 행도 여기서 뽑는다.
|
||||
- `contracts/<base>-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행). 스키마 ID마다 쓰이는 자리(`boundary`)와 소유자를 적는다.
|
||||
- `contracts/<base>-schemas.ts`: zod 스키마와 검증기.
|
||||
- `contracts/<base>-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 스키마(`<base>-schemas.ts`의 `<base>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/<id>/<base>-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`이면 기능의 빈 입력 스키마(`<Base>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: <operationId>`
|
||||
- `pathSchema`가 비었거나 `maxEncodedSearchBytes`가 범위 밖: `Invalid REST operation contract: <operationId>`
|
||||
- `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마: `Unresolved API schema binding: <operationId>`
|
||||
- 인증 프로필 이름이 틀리면 operation을 적재하는 모든 게이트가 실패한다.
|
||||
- 메시지: `REST security profiles are incoherent for <operationId>: unknown authProfileId <id>.`
|
||||
- 스키마·mapper·operation ID가 겹치면 모듈 로드 때 그 ID를 말하며 실패한다.
|
||||
- 예: `Invalid or duplicate schema definition: <schemaId>`
|
||||
- descriptor의 입력·응답 스키마 ID가 스키마 메타데이터에 없으면 `check:registries`가 실패한다.
|
||||
- 메시지: `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` (`responseSchema`도 같다)
|
||||
- 인증 프로필 이름이 틀리면 계약 조립이 거부해 operation을 적재하는 모든 게이트가 실패한다.
|
||||
- 오류의 `reason`: `<featureId>/<operationId>: unknown authProfileId <id>`
|
||||
- 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다.
|
||||
- 예: `Invalid or duplicate schema definition: <schemaId>`, 계약 조립 `duplicate operation: <operationId>`
|
||||
- `TEMPLATE_FIXTURE` 출처를 참조 기능 밖에서 쓰면 계약 조립이 거부한다.
|
||||
- 오류의 `reason`: `<id>: 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 <id> needs <capability>, 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.<operationId> has no executable consumer for operationId=<operationId>`
|
||||
- **못 잡음**: `routeId`가 실제로 요청을 보내는 화면과 다른 것. 타입은 기능의 route ID인지만 본다.
|
||||
- **못 잡음**: 기능 `contracts/`나 다섯 폴더 밖에 새로 만든 폴더(예: `hooks/`)를 거쳐 `src/adapters`에 닿는 import. `.dependency-cruiser.json`에 그 경로를 막는 규칙이 없다. 기능 안에는 `domain/`, `application/`, `contracts/`, `adapters/`, `presentation/` 다섯 폴더만 둔다.
|
||||
|
||||
@@ -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/<base>-contract-contribution.ts`의 `retrySemantics`, `commandRecovery`, `frontend.retryBudget`. 같은 의미를 `contracts/<base>-api-contract.ts`의 `replayPolicy`, `idempotency`, `idempotencyKeyPolicy`에도 적는다.
|
||||
**어디에 적나**: `contracts/<base>-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`.
|
||||
|
||||
**틀리면**
|
||||
|
||||
|
||||
@@ -43,9 +43,9 @@ corepack pnpm create:feature <id> [--context <context id>] [--package @scope/nam
|
||||
- `context-routes.ts`: context가 적재하는 라우트
|
||||
- `contracts/<base>-feature-contract.ts`: 라우트, 무효화, 계약 패키지 신원
|
||||
- `contracts/<base>-schemas.ts`: zod 스키마와 `zodValidator` 검증기
|
||||
- `contracts/<base>-mapper.ts`: 와이어 값 → 화면 값, 레지스트리 mapper
|
||||
- `contracts/<base>-api-contract.ts`: V2 행
|
||||
- `contracts/<base>-contract-contribution.ts`: V3 descriptor와 계약 기여
|
||||
- `contracts/<base>-mapper.ts`: 와이어 값 → 화면 값
|
||||
- `contracts/<base>-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행)
|
||||
- `contracts/<base>-contract-contribution.ts`: HTTP descriptor와 계약 기여. FE-REG-API 행은 여기서 뽑는다
|
||||
- `contracts/<base>-message-catalog.ts`: ko-KR·en-US 문구
|
||||
- `application/<base>-feature-api.ts`: input, gateway port, `ApplicationFeatureInputs` 보강
|
||||
- `adapters/<base>-http-gateway.ts`: HTTP gateway
|
||||
|
||||
@@ -71,23 +71,16 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
|
||||
| 메시지 | 원인 | 고칠 곳 |
|
||||
|---|---|---|
|
||||
| `REST security profiles are incoherent for <operationId>: unknown authProfileId <id>.` | 없는 인증 프로필 | `contracts/<base>-api-contract.ts`의 `authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` |
|
||||
| `REST security profiles are incoherent for <operationId>: unknown csrfProfileId <id>.` | 없는 CSRF 프로필. 템플릿에는 `NO_CSRF_BEARER`뿐 | `contracts/<base>-api-contract.ts`의 `csrfProfileId` |
|
||||
| `REST security profiles are incoherent for <operationId>: auth "none" needs an ANONYMOUS profile, <id> is <transport>.` | V2 `auth: "none"`인데 인증 프로필을 썼다 | V2 `auth` 또는 `authProfileId` |
|
||||
| `REST security profiles are incoherent for <operationId>: auth "external-session" cannot use the ANONYMOUS profile <id>.` | 로그인 API에 `ANONYMOUS` | V2 `auth` 또는 `authProfileId` |
|
||||
| `<featureId>/<operationId>: unknown authProfileId <id>` (계약 조립 오류의 `reason`) | 없는 인증 프로필 | `contracts/<base>-contract-contribution.ts`의 `frontend.authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` |
|
||||
| `Product REST auth profile <id> reuses a template profile id.` | 제품 프로필 ID가 템플릿 것과 같다 | `src/contracts/product-contracts.ts` |
|
||||
|
||||
### 계약·스키마·mapper
|
||||
|
||||
| 메시지 | 원인 | 고칠 곳 |
|
||||
|---|---|---|
|
||||
| `Invalid or duplicate schema definition: <schemaId>` | 스키마 ID 중복 또는 메타 형식 | `contracts/<base>-api-contract.ts`의 `schemas`. 접두어를 붙인다 |
|
||||
| `Invalid or duplicate runtime schema codec: <schemaId>` | 런타임 codec ID 중복 | `contracts/<base>-schemas.ts` |
|
||||
| `Invalid or duplicate boundary mapper: <mapperId>` | mapper ID 중복 또는 형식 | `contracts/<base>-mapper.ts` |
|
||||
| `Duplicate API operation: <operationId>` | V2 operation ID 중복 | `contracts/<base>-api-contract.ts` |
|
||||
| `REST path codec does not match its template: <operationId>` | V2 `pathParameterNames`가 `path`의 `{이름}`과 다르다 | `contracts/<base>-api-contract.ts` ([01 문서 3단계](../01-add-a-feature.md#3단계-api-계약) "V2 행의 입력 칸") |
|
||||
| `Invalid REST operation contract: <operationId>` | V2 행 형식. 예: 빈 `pathSchema`, `maxEncodedSearchBytes`가 0~32,768 밖 | 같은 곳 |
|
||||
| `Unresolved API schema binding: <operationId>` | V2 `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마 | 같은 파일의 `schemas`, `contracts/<base>-schemas.ts`의 codec |
|
||||
| `Invalid or duplicate schema definition: <schemaId>` | 스키마 ID 중복 또는 메타 형식 | `contracts/<base>-schema-metadata.ts`. 접두어를 붙인다 |
|
||||
| `duplicate operation: <operationId>` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/<base>-contract-contribution.ts`. 접두어를 붙인다 |
|
||||
| `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`도 같은 꼴) | `contracts/<base>-schema-metadata.ts` |
|
||||
| `Unregistered route codec: <codecId>` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/<base>-routes.ts` |
|
||||
| `contract package <packageId> is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/<base>-contract-contribution.ts`의 `source` |
|
||||
| `<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `<BASE>_CONTRACT_PACKAGE` 하나를 쓰게 한다 |
|
||||
@@ -149,7 +142,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
| `FE-REG-ROUTE.<ROUTE_ID>.loadingSurface value <value> does not match <pattern>` | 로딩 화면 이름이 케밥 표기가 아니다 | 계약 `routes.*.loadingSurface` |
|
||||
| `FE-REG-ROUTE.<ROUTE_ID>.<field> has unknown value <value>` | `access`·`errorSurface`가 정해진 값이 아니다 | 계약 `routes` |
|
||||
| `FE-REG-ROUTE.<ROUTE_ID>.paramsSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | 라우트 스키마 ID를 기능이 등록하지 않았다 (`searchSchema`도 같은 꼴) | 계약 스키마 메타 |
|
||||
| `FE-REG-API.<operationId> has no executable consumer for operationId=<operationId>` | V2 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 V2 행을 지운다 |
|
||||
| `FE-REG-API.<operationId> has no executable consumer for operationId=<operationId>` | 계약의 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 descriptor를 지운다 |
|
||||
| `breaking change missing evidence: <changeId>` | 행을 빼거나 바꿨는데 승인이 없다 | `update:registry-baseline` 또는 `config/contracts/registry-change-evidence.json` |
|
||||
| `stale breaking evidence <changeId>: no breaking change in the current diff has this changeId. ...` | 지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 |
|
||||
| `registry baseline approval digest mismatch: approved=<digest> actual=<digest>` | 기준선 파일을 손으로 고쳤다 | `update:registry-baseline`으로 다시 찍는다 |
|
||||
|
||||
@@ -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)에 있다.
|
||||
|
||||
@@ -77,12 +77,12 @@ const search = (q: string) =>
|
||||
|
||||
| 패턴 | 정의 | 예제 | 검사 |
|
||||
|---|---|---|---|
|
||||
| V2 operation 행 | `src/contracts/api-operations.ts`의 `defineRestOperation` | 생성 뼈대 `contracts/<base>-api-contract.ts` | `check:registries` (FE-REG-API) |
|
||||
| V3 HTTP 계약(실행) | `src/contracts/external-contract-runtime.ts` | 생성 뼈대 `contracts/<base>-contract-contribution.ts` | 계약 조립, V2/V3 일치 테스트 |
|
||||
| HTTP 계약 | `src/contracts/external-contract-runtime.ts` | 생성 뼈대 `contracts/<base>-contract-contribution.ts` | 계약 조립, `check:registries` (FE-REG-API 행은 `src/contracts/api-operations.ts`의 `projectApiOperationRows`가 뽑는다) |
|
||||
| 스키마 메타데이터 | `src/contracts/schema-registry.ts`의 `SchemaDefinition` | 생성 뼈대 `contracts/<base>-schema-metadata.ts` | `check:registries` (FE-REG-SCHEMA) |
|
||||
| 배포된 계약 패키지 출처 | 같은 파일의 `EXTERNAL_PACKAGE` | 생성 뼈대(자리표시자 또는 `--package` 신원). 실제 `@org-contracts/*` 패키지를 import하는 예제는 없음 | 계약 조립(신원 형식), 릴리스 승인(자리표시자) |
|
||||
| 런타임 검증기 | `src/contracts/zod-validator.ts`의 `zodValidator` | 생성 뼈대 `contracts/<base>-schemas.ts` | 스키마 ID 중복 |
|
||||
| 검증 생략 | `src/contracts/unvalidated-payload.ts`의 `unvalidatedPayload` | 없음 (기능 예제) | 이유가 비면 throw, `listUnvalidatedPayloads`가 목록을 보임 |
|
||||
| DTO → 화면 값 mapper | `src/contracts/boundary-mapper.ts` | 생성 뼈대 `contracts/<base>-mapper.ts` | mapper ID 중복 |
|
||||
| DTO → 화면 값 mapper | `src/contracts/boundary-mapper.ts`의 `BoundaryMappingResult` | 생성 뼈대 `contracts/<base>-mapper.ts` | 타입 검사 |
|
||||
| gateway port + HTTP 어댑터 | `src/adapters/http/index.ts`의 `createFeatureHttpBinding`, `defineFeatureHttpOperationForRoutes` | 생성 뼈대 `adapters/<base>-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/<base>-feature-api.ts` | `FailureKind` 닫힌 어휘(타입) |
|
||||
|
||||
@@ -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 직접 호출)를 먼저 의심한다.
|
||||
|
||||
점검:
|
||||
|
||||
|
||||
+34
-112
@@ -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<Record<string, InstalledBoundaryMapper>>);
|
||||
`;
|
||||
}
|
||||
|
||||
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" });
|
||||
});
|
||||
});
|
||||
`;
|
||||
}
|
||||
|
||||
|
||||
@@ -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([]),
|
||||
}),
|
||||
|
||||
+46
-215
@@ -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<unknown, unknown, unknown>["contract"]["requestBody"];
|
||||
responseBody: InstalledHttpContract<unknown, unknown, unknown>["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<Record<string, ApiOperation>>[],
|
||||
): Readonly<Record<string, ApiOperation>> {
|
||||
const result: Record<string, ApiOperation> = Object.create(null);
|
||||
export function projectApiOperationRows(
|
||||
contributions: readonly InstalledContractContribution[],
|
||||
): Readonly<Record<string, ApiOperationRow>> {
|
||||
const rows: Record<string, ApiOperationRow> = {};
|
||||
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<Record<string, ApiOperation>>,
|
||||
schemaMetadata: Readonly<Record<string, Readonly<{ schemaId: string }>>>,
|
||||
schemaCodecs: Readonly<Record<string, Readonly<{ schemaId: string }>>>,
|
||||
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<Record<string, ApiOperation>> =
|
||||
Object.freeze({});
|
||||
|
||||
export function getApiOperation(
|
||||
operationId: string,
|
||||
operations: Readonly<Record<string, ApiOperation>> = 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);
|
||||
}
|
||||
|
||||
@@ -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<Record<string, RuntimeSchemaCodec>>;
|
||||
mappers: Readonly<Record<string, InstalledBoundaryMapper>>;
|
||||
apiOperations: Readonly<Record<string, ApiOperation>>;
|
||||
apiOperations: Readonly<Record<string, ApiOperationRow>>;
|
||||
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")
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -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<object>();
|
||||
|
||||
/**
|
||||
* 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<Record<string, RestAuthProfile>>;
|
||||
|
||||
/**
|
||||
* 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<Record<string, RestAuthProfile>>,
|
||||
);
|
||||
return createReadOnlyRegistry(installed);
|
||||
}
|
||||
|
||||
function withProductProfiles(): Readonly<Record<string, RestAuthProfile>> {
|
||||
@@ -263,141 +220,3 @@ function withProductProfiles(): Readonly<Record<string, RestAuthProfile>> {
|
||||
*/
|
||||
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<Record<string, RestCsrfProfile>>);
|
||||
|
||||
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<Record<string, RestCsrfProfile>> = 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<string, readonly FetchCredentialsMode[]>
|
||||
>,
|
||||
authProfiles: RestAuthProfileSource = INSTALLED_REST_AUTH_PROFILES,
|
||||
csrfProfiles: Readonly<Record<string, RestCsrfProfile>> = 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;
|
||||
}
|
||||
|
||||
@@ -42,13 +42,6 @@ type EmptyFeatureMessageCatalogs = Readonly<
|
||||
Record<string, Readonly<Record<never, never>>>
|
||||
>;
|
||||
|
||||
/** 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[];
|
||||
}>;
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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에 실어
|
||||
|
||||
@@ -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);
|
||||
@@ -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,
|
||||
|
||||
@@ -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<string, unknown>;
|
||||
return (
|
||||
typeof dto.id === "string" &&
|
||||
typeof dto.name === "string" &&
|
||||
(dto.createdAt === undefined || typeof dto.createdAt === "string")
|
||||
);
|
||||
}
|
||||
|
||||
function mapUnknownReferenceResourcePayload(
|
||||
value: unknown,
|
||||
): BoundaryMappingResult<ReferenceResource> {
|
||||
return isReferenceResourceDto(value)
|
||||
? mapReferenceResourcePayload(value)
|
||||
: mappingFailure("MAPPING_INVARIANT_REJECTED");
|
||||
}
|
||||
|
||||
function mapUnknownReferenceResourceListPayload(
|
||||
value: unknown,
|
||||
): BoundaryMappingResult<readonly ReferenceResource[]> {
|
||||
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<ReferenceResource | readonly ReferenceResource[]> {
|
||||
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<Record<string, InstalledBoundaryMapper>>);
|
||||
|
||||
export function toReferenceView(
|
||||
resource: ReferenceResource,
|
||||
): ReferenceResourceView {
|
||||
|
||||
@@ -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",
|
||||
}),
|
||||
});
|
||||
@@ -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<string, z.ZodType>;
|
||||
|
||||
const requestSchemas = {
|
||||
ReferenceResourceParams: referenceResourceParamsSchema,
|
||||
ReferenceResourceListQuery: referenceResourceListQuerySchema,
|
||||
NoRequest: z.object({}).strict(),
|
||||
CreateReferenceResourceCommand: createReferenceResourceCommandSchema,
|
||||
} satisfies Record<string, z.ZodType>;
|
||||
|
||||
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<Record<string, z.ZodType>>,
|
||||
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);
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -22,7 +22,7 @@ function feature(id: string, paths: Readonly<Record<string, string>>) {
|
||||
messages: {},
|
||||
loadRuntime: async () => ({
|
||||
featureId: id,
|
||||
apiContract: {},
|
||||
schemas: {},
|
||||
adapters: [],
|
||||
contractContributions: [],
|
||||
}),
|
||||
|
||||
@@ -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];
|
||||
|
||||
@@ -16,7 +16,7 @@ function fakeFeature(id: string) {
|
||||
messages: {},
|
||||
loadRuntime: async () => ({
|
||||
featureId: id,
|
||||
apiContract: {},
|
||||
schemas: {},
|
||||
adapters: [],
|
||||
contractContributions: [],
|
||||
}),
|
||||
|
||||
@@ -6,7 +6,7 @@ import {
|
||||
|
||||
const runtimeOf = async (featureId: string) => ({
|
||||
featureId,
|
||||
apiContract: {},
|
||||
schemas: {},
|
||||
adapters: [],
|
||||
contractContributions: [],
|
||||
});
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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" }],
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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([]),
|
||||
}),
|
||||
|
||||
@@ -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([]),
|
||||
}),
|
||||
|
||||
@@ -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(),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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<string, unknown>]>([
|
||||
["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();
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -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(
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -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({
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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<unknown, unknown, unknown>[],
|
||||
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);
|
||||
`;
|
||||
|
||||
|
||||
@@ -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: [],
|
||||
}),
|
||||
|
||||
Reference in New Issue
Block a user