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
+2 -2
View File
@@ -30,7 +30,7 @@ async function filesBelow(directory: string): Promise<string[]> {
const telemetryProducerFiles: Readonly<Record<string, string>> = {
"app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
"api.request.failed": "src/adapters/http/client.ts",
"api.request.failed": "src/bootstrap/runtime-adapters.ts",
"ui.render.failed": "src/application/create-application.ts",
"release.mismatch.detected": "src/application/create-application.ts",
"service-worker.start.failed": "src/bootstrap/optional-runtime-host.ts",
@@ -39,7 +39,7 @@ const telemetryProducerFiles: Readonly<Record<string, string>> = {
};
const diagnosticProducerFiles: Readonly<Record<string, string>> = {
"app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
"http.request.completed": "src/adapters/http/client.ts",
"http.request.completed": "src/bootstrap/runtime-adapters.ts",
"cache.operation.failed":
"src/adapters/query-cache/tanstack-query-cache.ts",
"storage.operation.failed":
+93 -13
View File
@@ -2,13 +2,18 @@ import { access, mkdir, readFile } from "node:fs/promises";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { shouldRetry } from "../src/adapters/http/retry-policy.ts";
import { createContractHttpExecutor } from "../src/adapters/http/index.ts";
import { createTelemetryAdapter } from "../src/adapters/telemetry/best-effort-telemetry.ts";
import { verifyCompatibilityTuple } from "../src/contracts/compatibility.ts";
import type { StoragePort } from "../src/application/ports/storage-port.ts";
import { decideChunkRecovery } from "../src/application/use-cases/decide-chunk-recovery.ts";
import { validateRuntimeConfig } from "../src/bootstrap/runtime-config-schema.ts";
import type { InstalledContractPackageIdentity } from "../src/contracts/external-contract-runtime.ts";
import type {
InstalledContractPackageIdentity,
RetrySemantics,
} from "../src/contracts/external-contract-runtime.ts";
import { z } from "../src/contracts/zod.ts";
import { zodValidator } from "../src/contracts/zod-validator.ts";
import {
parseReleaseArtifact,
parseRuntimeConfigArtifact,
@@ -241,17 +246,92 @@ async function drillChunkMismatch(context: DrillContext): Promise<DrillResult> {
};
}
/**
* One operation through the V3 executor against a fixed answer. Returns how
* many requests it sent, which is what retry amplification is measured in.
*/
async function physicalAttempts(
retrySemantics: Extract<RetrySemantics, "SAFE" | "NEVER">,
answer: () => Response,
): Promise<number> {
const read = retrySemantics === "SAFE";
let sent = 0;
const executor = createContractHttpExecutor({
baseUrl: "https://api.invalid",
maxRetryAttempts: 2,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
fetcher: (async () => {
sent += 1;
return answer();
}) as typeof fetch,
sleep: async () => {},
random: () => 0,
});
await executor.execute(
Object.freeze({
contract: Object.freeze({
operationId: "DRILL_API_DEGRADATION",
method: read ? ("GET" as const) : ("POST" as const),
pathTemplate: "/api/drill",
inputValidator: zodValidator("DrillInput", z.object({}).strict()),
outputValidator: zodValidator(
"DrillOutput",
z.object({ id: z.string() }).strict(),
),
problemValidator: zodValidator(
"DrillProblem",
z.object({ code: z.string() }).strip(),
),
acceptedStatuses: Object.freeze([200]),
emptyBodyStatuses: Object.freeze([]),
retrySemantics,
requestBody: read ? ("NONE" as const) : ("JSON" as const),
responseBody: "REQUIRED_JSON" as const,
commandRecovery: null,
commandEffect: read
? null
: Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem: () => "MAYBE_APPLIED" as const,
}),
projectRequest: () =>
Object.freeze({
pathValues: Object.freeze({}),
queryEntries: Object.freeze([]),
body: read ? null : Object.freeze({}),
}),
}),
frontend: Object.freeze({
policyId: "DRILL_API_V1",
requestByteLimit: read ? 0 : 1_024,
responseByteLimit: 4_096,
totalDeadlineMs: 5_000,
retryBudget: read ? (2 as const) : (0 as const),
authProfileId: "ANONYMOUS",
diagnosticsOperation: "drill.api",
}),
}),
Object.freeze({}),
{
routeId: "DRILL_ROUTE",
scope: Object.freeze({
generation: 1,
fingerprint: "drill-scope",
identities: Object.freeze({}) as never,
signal: new AbortController().signal,
isCurrent: () => true,
}),
},
);
return sent;
}
async function drillApiDegradation(): Promise<DrillResult> {
const unkeyedRetry = shouldRetry(
{ idempotency: "none" },
{ kind: "SERVER_FAILURE", httpStatus: 503 },
0,
);
const safeRetry = shouldRetry(
{ idempotency: "safe" },
{ kind: "SERVER_FAILURE", httpStatus: 503 },
0,
);
const unavailable = () => Response.json({ code: "TEMPORARY" }, { status: 503 });
const unkeyedRetry = (await physicalAttempts("NEVER", unavailable)) > 1;
const safeRetry = (await physicalAttempts("SAFE", unavailable)) > 1;
const schemaRetry =
(await physicalAttempts("SAFE", () => Response.json({ unexpected: true }))) > 1;
return {
// The trigger is a failure rate over live traffic.
triggerAsserted: "UNVERIFIED",
@@ -263,7 +343,7 @@ async function drillApiDegradation(): Promise<DrillResult> {
assertion(
"schema fixtures",
"schema mismatch is not retryable",
verdict(!shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
verdict(!schemaRetry),
),
],
negativeFixtureFailedAsExpected: verdict(!unkeyedRetry),
-2
View File
@@ -21,9 +21,7 @@ const maximumWaiverDurationMs = 90 * 24 * 60 * 60 * 1_000;
export const REQUIRED_HIGH_RISK_PATHS = Object.freeze([
"src/adapters/http/http-execution-v3.ts",
"src/adapters/http/request-builder.ts",
"src/adapters/http/bounded-body-reader.ts",
"src/adapters/http/bounded-json.ts",
"src/bootstrap/read-bounded-boot-json.ts",
"src/adapters/service-worker/service-worker-lifecycle.ts",
"src/adapters/query-cache/server-state-scope-runtime.ts",