docs: 사라진 V2 동작 셋의 판정과 되살린 것을 기록한다
문제 14.7은 V2 삭제로 "401 뒤 세션 복구 재전송"과 "보낸 KEYED 요청 자동 재시도"가 사라졌다고만 적었다. 사용자가 없어져도 되는지 물었고, V2 보안 프로필 일관성 검사도 같이 사라졌다. 고른 방법 14.7에 세 동작의 판정 표를 적었다. 기준은 설계 정본(2026-07-30 closed deep design) 8절이다. - 401 재전송: 없어져도 된다(8.4 FRT-D016 hidden replay 금지). VD-23의 낡은 문장은 리뷰 대상으로 남긴다. - KEYED 자동 재시도: 정본 8.3이 허용하는 부분(재시도를 허락하는 알려진 응답)만 되살렸다(c05f41a). - 보안 프로필 검사: 쿠키 인증 쓰기의 CSRF 요구만 보안 불변식이라 되살렸다 (365d8c3). CHANGELOG에 [보안] 행과 [계약] 행을 더했다. 검증 - verify:documentation PASS_SCOPED, tests/unit/changelog-review-ids.test.ts 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
This commit is contained in:
@@ -75,6 +75,8 @@
|
||||
| [계약] | V2: 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`가 `effect: "NOT_APPLIED"`와 진단 reason을 싣는다. 409의 `Retry-After`는 `retryAfterMs`로 실린다(V3 PROBLEM 실패도 같다). 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다. 응답 code의 정본은 백엔드 템플릿 `docs/web/http-contract.md` §2다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/adapters/http/feature-http-binding.ts`, `src/presentation/adapters/query/application-query.ts` | `93782b0`, `47fec5c` |
|
||||
| [계약] | V2 클라이언트가 짝 백엔드의 400 `VALIDATION_FAILED`(필드 목록 `details: [{field, code, message}]`)를 422와 같은 `VALIDATION_REJECTED`·`validationIssues`로 읽는다. 필드 검증 거절(422와 이 400)은 `effect: "NOT_APPLIED"`다. 전에는 결과 불명으로 붙들어 폼에서 값을 고쳐도 다시 저장할 수 없었다. 그 밖의 400·409는 그대로 결과 불명이다. 적용 여부는 다음 행이 다시 정했다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/contracts/errors.ts` | `02e35d2`, `64e98ee` |
|
||||
| [계약] | 거절의 적용 여부를 계약 문서 6.1절 표(백엔드 `5786126c` 코드 기준)로 정한다. V2와 V3 Envelope operation이 같은 표(`src/adapters/http/backend-envelope.ts`)를 쓴다. 적용 안 됨은 400 `VALIDATION_FAILED`(details 모양과 상관없음)·400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`뿐이고, 그 밖의 400·409·422는 결과 불명이다. V2에서 `IDEMPOTENT_REQUEST_MISMATCH`가 아닌 422는 이제 결과 불명이라 폼에서 값을 고쳐도 다시 저장할 수 없다. 필드 검증을 422로 보내는 백엔드를 쓰는 프로젝트는 영향을 받는다. 필드 목록 없는 400 `VALIDATION_FAILED`는 바로 다시 저장할 수 있다. V3 Envelope operation의 400·409·422는 `classifyProblem` 대신 이 표가 정한다 (1101/14.4) | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/client.ts`, `src/adapters/http/http-execution-v3.ts` | `3261208` |
|
||||
| [보안] [계약] | 쿠키 인증 프로필(`SAME_ORIGIN_COOKIE`)로 쓰기(GET·HEAD 밖)를 하는 operation은 그 프로필이 `x-csrf-token`이나 `x-xsrf-token`을 `requiredCredentialHeaders`로 요구해야 한다. 아니면 계약 조립이 거절한다. V2 클라이언트가 지키던 검사를 V3 조립으로 옮겼다 | `src/contracts/external-contract-runtime.ts` | `365d8c3` |
|
||||
| [계약] | KEYED Envelope operation이 503 `IDEMPOTENCY_UNAVAILABLE`(백엔드가 실행 전에 거절)을 받으면 `retryBudget` 안에서 같은 키로 자동으로 다시 보낸다. 다 쓰면 결과 불명(`MAYBE_APPLIED`)이고 키를 지킨다. 응답 없는 실패 뒤에는 여전히 다시 보내지 않는다 | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/http-execution-v3.ts` | `c05f41a` |
|
||||
| [계약] **BREAKING** | 기능마다 적던 V2 API 행을 지웠다. HTTP operation은 contract contribution의 descriptor에 한 번만 적는다. FE-REG-API 행은 그 descriptor에서 뽑는다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`: operationId·featureId·method·path·authProfileId·retrySemantics·requestBody·responseBody·responseEnvelope·requestSchema·responseSchema·problemSchema). `FeatureRuntime`은 `apiContract` 대신 `schemas`(FE-REG-SCHEMA 행)를 받는다. 지운 이름: `defineRestOperation`, `ApiOperation`, `RestOperationV2`, `composeApiOperations`, `validateApiRuntimeBindings`, `getApiOperation`, contracts의 `API_OPERATIONS`; `rest-profiles.ts`의 `createRestProviderProfile`, `RestProviderProfile`, `resolveRestSecurityProfiles`, `validateRestProfileBindings`, `REST_CSRF_PROFILES`, `RestCsrfProfile`; `loaded-feature-runtimes.ts`의 `RUNTIME_SCHEMA_CODECS`, `MAPPER_REGISTRY`, `REST_PROFILE_BINDINGS_VALID`, `API_RUNTIME_BINDINGS_VALID`. realtime `apiOperations` 바인딩은 `ApiOperationRow`를 받고, snapshot operation을 `method: "GET"`과 `retrySemantics` `SAFE`·`IDEMPOTENT`로 본다. 레지스트리 기준선을 다시 승인했다. 옮기는 법: `<base>-api-contract.ts`의 `schemas`를 `<base>-schema-metadata.ts`로 옮겨 `defineFeatureRuntime({ schemas })`에 넘기고, `apiOperations`·`runtimeSchemas`·`mappers`와 mapper 레지스트리 행을 지운다. 스키마 메타데이터에 descriptor 입력·응답 검증기의 schemaId가 있어야 한다. memento-frontend의 `memento-web`이 해당한다 | `src/contracts/api-operations.ts`, `src/features/feature-module.ts`, `src/features/installed-feature-runtime-registries.ts`, `config/contracts/`, `scripts/create-feature.ts` | `12f3bb7` |
|
||||
| [계약] **BREAKING** | V2 HTTP 클라이언트를 지웠다. HTTP 경로는 V3 실행기 하나다. 배럴(`src/adapters/http/index.ts`)에서 `createHttpClient`, `HttpClient`, `HttpClientDependencies`, `HttpFailure`, `HttpResult`, `LegacyHttpInput`, `Scheduler`, `OperationRequestInput`가, `src/bootstrap/runtime-adapters.ts`에서 `createRuntimeHttpClient`, `RuntimeHttpContract`가 없어졌다. 지운 파일: `client.ts`, `bounded-json.ts`, `request-builder.ts`, `resource-mapper.ts`, `retry-policy.ts`, `schema-registry.ts`(`src/adapters/http/`). Envelope 스키마는 `backend-envelope.ts`로 옮겼다. 템플릿과 tech-log·memento 모두 앱 안에서 V2 클라이언트를 부르는 곳이 없었다. 부르는 코드가 있으면 그 operation의 V3 descriptor를 만들어 `createFeatureHttpBinding`으로 실행한다. 초기 JS 203,354 → 201,598 B | `src/adapters/http/`, `src/bootstrap/runtime-adapters.ts`, `scripts/drill-runbook.ts` | `048f490` |
|
||||
| [계약] | V3 descriptor에 선택 필드 `responseEnvelope`가 생겼다. `"ENVELOPE_V1"`이면 V3 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 적용 여부는 실행기가 V2와 같은 표로 정하고(아래 6.1 표 행), `mapProblem`이 답하지 않으면 V2와 같은 kind·code·필드 오류로 읽는다. 성공 status의 Envelope 아닌 본문은 새 위반 `ENVELOPE_MISMATCH`다(`HttpContractViolationKind`에 추가만, exhaustive switch는 분기를 더한다). Envelope operation의 진단은 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`에 V2와 같은 `reason`을 싣는다(`HttpDiagnosticReason`에 두 값 추가). `create:feature`가 만든 기능은 이 값을 선언하고 problem 스키마가 Envelope `error`다. 값이 없는 descriptor(참조 기능 포함)는 그대로다. 이전에 만든 기능을 짝 백엔드에 붙이려면 contribution에 `responseEnvelope: "ENVELOPE_V1" as const`를 더하고 problem 스키마를 `error` 모양(`code` 필수)으로 바꾼다 (1101 README 14.3) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/`, `scripts/create-feature.ts`, `tests/mocks/handlers/http-scenarios.ts` | `7db32e1`, `bd83b49` |
|
||||
|
||||
@@ -616,6 +616,12 @@ Envelope operation에서는 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 ef
|
||||
| `12f3bb7` | V2 API 행(`defineRestOperation` 등), 기능의 `runtimeSchemas`·`mappers`, V2 보안 프로필 해석(`resolveRestSecurityProfiles` 등), V2/V3 일치 테스트 | FE-REG-API 행을 descriptor에서 뽑는다(`projectApiOperationRows`). `FeatureRuntime`은 `schemas`만 받는다. realtime snapshot 검사는 뽑은 행을 읽는다. 레지스트리 기준선 재승인(digest `16f72742…`, 승인자 `DongHyeonka`) |
|
||||
|
||||
- 초기 JS: 203,354 → 201,598 B(`048f490`) → 200,911 B. 14.6 시작(202,770 B)보다 1,859 B 작다.
|
||||
- 사라진 V2 전용 동작: 401 뒤 세션 복구 후 한 번 재전송, 보낸 KEYED 요청의 503 자동 재시도. 14.6의 "V2와 남은 차이"는 비교할 대상이 없어졌다.
|
||||
- 사라진 V2 전용 동작은 하나씩 판정했다(사용자 질문 "없어지면 안 되는 것 아닌가"). 기준은 현재 설계 정본 `docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md` 8절이다.
|
||||
|
||||
| V2 동작 | 판정 | 근거 | 처리 |
|
||||
|---|---|---|---|
|
||||
| 401 뒤 세션 복구 후 한 번 재전송 | 없어져도 된다 | 정본 8.4(FRT-D016): "401 response 뒤 hidden refresh-and-replay를 하지 않는다". 자격증명 owner가 보내기 전에 토큰을 준비하고, 401은 끝이며, 다시 로그인한 뒤 사용자가 다시 실행한다. V3는 401에서 `onUnauthenticated`를 부르고 세션 화면의 "recover" 동작이 이어 준다 | 코드 변경 없음. VD-23의 "401 recovery는 한 번 수행" 문장은 정본과 어긋난 낡은 문장이다(리뷰 대상) |
|
||||
| 보낸 KEYED 요청의 자동 재시도 | 일부는 있어야 한다 | 정본 8.3: KEYED는 "known response status가 retry 가능하다고 package가 명시한 경우만" 자동 재시도하고, 응답 없는 network·timeout 뒤에는 금지한다. V2는 network·timeout 뒤에도 재시도해 정본과 어긋났다. 반대로 V3는 응답이 재시도를 허락해도 재시도하지 않아 정본보다 좁았다 | 고쳤다(`c05f41a`). Envelope operation이 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거절, 백엔드 §2가 같은 키 재전송을 요구)을 받으면 `retryBudget` 안에서 같은 키로 다시 보낸다. 다 쓰면 결과 불명이고 키를 지킨다 |
|
||||
| 보안 프로필 일관성 검사(`resolveRestSecurityProfiles`) | 하나는 있어야 한다 | `auth`·`authProfileId`·`csrfProfileId` 사이의 어긋남 검사는 V3 descriptor에 칸이 하나(`authProfileId`)뿐이라 대상이 없다. 그러나 "쿠키 인증 쓰기는 CSRF 헤더를 요구한다"는 보안 불변식이고, V3 프로필 설치 규칙에는 없었다 | 고쳤다(`365d8c3`). 계약 조립이 쿠키 프로필로 쓰기(GET·HEAD 밖)를 하면서 `x-csrf-token`·`x-xsrf-token`을 요구하지 않는 operation을 거절한다 |
|
||||
- 남긴 것: `src/application/policies/bounded-polling.ts`의 `BoundedPollOperationContract`는 `contractVersion: 2` 필드를 갖지만 realtime polling recipe의 자체 계약이고 V2 HTTP 경로가 아니다. 고치지 않았다.
|
||||
- 다운스트림: tech-log·memento 모두 V2 클라이언트를 부르지 않는다. memento-frontend의 `memento-web` 기능은 V2 API 행을 쓰므로 동기화 때 CHANGELOG의 옮기는 법을 따른다.
|
||||
|
||||
Reference in New Issue
Block a user