refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다

문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.

고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
  resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
  스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
  parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
  parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
  지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
  legacy-http-credential-authority, bounded-json-compatibility,
  request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
  지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
  boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
  계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
  422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
  비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
  보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
  1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
  risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
  경로를 V3 파일로 바꿨다.

버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
  곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.

위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
  CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
  자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
  재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
  커밋에서 지우지 않았다. 다음 커밋이 지운다.

검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
  check:adapter-inventory(140 files), check:diagnostics, check:registries,
  check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).

BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
This commit is contained in:
DongHyeonka
2026-11-03 21:12:34 +09:00
parent bf86fe5cd0
commit 048f490ada
44 changed files with 466 additions and 4121 deletions
+1 -69
View File
@@ -7,7 +7,6 @@ import {
import { createDiagnosticsAdapter } from "../adapters/diagnostics/index.ts";
import {
createContractHttpExecutor,
createHttpClient,
type HttpExecutionObservation,
type InstalledHttpOperationExecutor,
} from "../adapters/http/index.ts";
@@ -35,13 +34,8 @@ import {
createTelemetryAdapter,
createTelemetryCollector,
} from "../adapters/telemetry/index.ts";
import type { AuthSessionPort } from "../application/ports/auth-session-port.ts";
import type { ReleaseInfo } from "../application/ports/release-info-port.ts";
import {
createRestProviderProfile,
INSTALLED_REST_AUTH_PROFILES,
} from "../contracts/rest-profiles.ts";
import type { ClockPort } from "../application/ports/clock-port.ts";
import { INSTALLED_REST_AUTH_PROFILES } from "../contracts/rest-profiles.ts";
import { createInstalledFeatureLoaders } from "../features/installed-feature-adapters.ts";
import {
INVALIDATION_REGISTRY,
@@ -72,41 +66,6 @@ import {
indexInvalidationTopicVersions,
} from "../contracts/query-invalidation.ts";
type HttpClientDependencies = Parameters<typeof createHttpClient>[0];
/**
* 제품이 V2 전송을 쓰려면 채워야 하는 슬롯 네 개.
*
* 이 템플릿은 넷 다 비워서 출하한다. 기본값인
* `contracts/api-operations.ts`의 `API_OPERATIONS`는 빈 객체이고
* `adapters/http/resource-mapper.ts`의 `mapOperationPayload`는 항상
* `MAPPING_INVARIANT_REJECTED`를 반환한다. 그래서 **이 레포 상태 그대로는
* V2로 어떤 오퍼레이션도 실행되지 않는다** — 그건 결함이 아니라 제품이
* 채우는 자리다.
*
* V2는 V3를 그대로 되돌리는 롤백 경로가 아니다. 두 경로는 wire 형식이
* 다르다. V2는 `{ success, data, meta }` 봉투를 검증하고
* (`adapters/http/schema-registry.ts`), V3는 봉투 없는 DTO 자체를 검증한다.
* 그래서 네 슬롯을 모두 주입해도 같은 백엔드로 V2로 되돌리면 모든 응답이
* `ENVELOPE_MISMATCH`다. V2로 되돌리려면 슬롯 주입과 함께 서버도 V2 봉투로
* 응답해야 한다.
* V3(`createContractHttpExecutor`)는 설치된 feature 계약에서 오퍼레이션을
* 받으므로 이 슬롯과 무관하게 동작한다.
*/
export type RuntimeHttpContract = Pick<
HttpClientDependencies,
"getOperation" | "validatePayload" | "validateRequest" | "mapPayload"
>;
type RuntimeHttpContext = Readonly<{
runtime: RuntimeConfigLoadResult;
authSession: AuthSessionPort;
fetcher?: typeof fetch;
clock?: ClockPort;
scheduler?: HttpClientDependencies["scheduler"];
diagnostics?: HttpClientDependencies["diagnostics"];
telemetry?: HttpClientDependencies["telemetry"];
}>;
export type RuntimeAdaptersContext = Readonly<{
runtime: RuntimeConfigLoadResult;
release: Readonly<ReleaseManifest>;
@@ -211,33 +170,6 @@ function storageOrUndefined(value: unknown): Storage | undefined {
}
}
/**
* Runtime-aware transport factory. Feature gateway composition calls this
* factory when a registered API capability is installed.
*/
export function createRuntimeHttpClient(
context: RuntimeHttpContext,
contract: RuntimeHttpContract = {},
) {
return createHttpClient({
baseUrl: context.runtime.config.API_BASE_URL,
timeoutMs: context.runtime.config.REQUEST_TIMEOUT_MS,
maxRetryAttempts: context.runtime.config.MAX_RETRY_ATTEMPTS,
authSession: context.authSession,
providerProfile: createRestProviderProfile(
"PRIMARY_API",
context.runtime.config.API_BASE_URL,
["omit"],
),
fetcher: context.fetcher,
clock: context.clock,
scheduler: context.scheduler,
diagnostics: context.diagnostics,
telemetry: context.telemetry,
...contract,
});
}
/**
* VD-07. Exactly one diagnostic per logical V3 execution and exactly one
* `api.request.failed` telemetry event per terminal non-abort failure.