From 849d000342f0d3395623360a020ddfd6261c4997 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 00:36:44 +0900 Subject: [PATCH] =?UTF-8?q?fix(http):=20=EA=B2=B0=EA=B3=BC=20=EB=B6=88?= =?UTF-8?q?=EB=AA=85=20=EC=93=B0=EA=B8=B0=EC=97=90=20=EB=B3=B4=EB=82=B8=20?= =?UTF-8?q?=EC=9A=94=EC=B2=AD=20id=EB=A5=BC=20=EC=A7=80=EC=9B=90=20?= =?UTF-8?q?=EC=B0=B8=EC=A1=B0=EB=A1=9C=20=EC=8B=A3=EB=8A=94=EB=8B=A4=20(09?= =?UTF-8?q?29/03-04)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 바인딩은 서버가 돌려준 x-correlation-id만 AppFailure.requestId로 싣는다. 마감 초과·연결 끊김(TRANSPORT_FAILURE)과 취소에는 응답이 없고, 헤더를 노출하지 않는 서버·게이트웨이의 504에도 반사값이 없다. 실행기는 보낸 id를 알지만 observation(기본 sink 없는 메모리 diagnostics)에만 넣었다. 그래서 e54fbf2(0929/08-04)가 결과 불명 화면에 더한 "지원 참조" 줄이 가장 흔한 결과 불명 경우(마감 초과)에 비어 있었다. 요청은 id를 싣고 서버 로그에 남는데도 지원 담당은 시각·사용자로 찾아야 했다. 고른 방법: 리뷰의 최소 개선 방향 ①을 한다. ②(화면)는 e54fbf2가 이미 했다. - V3 실행 결과(HttpExecutionOutcome)의 모든 가지에 선택 필드 sentRequestId를 더한다. finish()가 요청에 넣은 x-correlation-id를 싣는다. observation의 correlationId와 같은 값이다. - 바인딩은 반사값이 없으면 sentRequestId를 requestId로 쓴다. - 런북 5.2-6과 백엔드 계약 5절에 "반사값이 없으면 보낸 값" 한 줄씩. 버린 대안: metadata 없는 가지에만 필드 두기 — 반사 헤더 없는 504는 metadata가 있어 빠진다. 바인딩이 id를 만들어 실행기에 넘기기 — 실행기가 이미 id를 만들고 재시도에 공유하므로 생성 지점이 둘이 된다. 위험·한계: 공개 결과 타입에 선택 필드 하나가 붙는다(추가만). 요청을 조립하기 전에 끝난 실패(자격 증명 없음, 입력 거절)와 id 생성 실패(보안 컨텍스트 아님)에는 값이 없다. 서버가 id를 바꿔 쓰면 반사값을 우선하므로 두 값이 다를 수 있다. telemetry에는 넣지 않는다(VD-07). 초기 JS gzip은 이 커밋 단독으로 재지 않았다(두 커밋 뒤 함께 잼). 검증: - RED: reference-production-vertical에 새 테스트. REQUEST_TIMEOUT_MS 200, MSW가 abort까지 응답하지 않는다. 수정 전 "변경 결과를 확인할 수 없습니다."는 보이지만 "Unable to find an element with the text: 지원 참조: 29d7f444-…"로 실패. - GREEN: 같은 테스트 통과(화면 식별자 = 요청 헤더 x-correlation-id). tests/features·unit·integration·component 242 files 2975 tests, tests/contract·runtime-schema·architecture 13 files 109 tests 통과. tsc app·test, eslint(바꾼 파일), verify-documentation-readiness, check-adapter-inventory, check-registries 통과. Refs: docs/reviews/2026-09-29-maturity-review/03-adapters-http-state.md 03-04 --- .../backend-api-and-server-state-contract.md | 3 +- .../api-contract-and-server-state-recovery.md | 4 +- src/adapters/http/feature-http-binding.ts | 6 ++- src/adapters/http/http-execution-v3.ts | 18 ++++++-- .../reference-production-vertical.test.tsx | 42 +++++++++++++++++++ 5 files changed, 66 insertions(+), 7 deletions(-) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index c209ef03..5fad9e6a 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -255,7 +255,8 @@ Cross-origin bearer provider 최소 CORS: `X-Correlation-ID`, 향후 `If-None-Match`, `If-Match` 허용 - 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose. `X-Correlation-ID`를 expose하면 V3 실패의 `AppFailure.requestId`가 된다 - (`src/adapters/http/feature-http-binding.ts`) + (`src/adapters/http/feature-http-binding.ts`). expose하지 않거나 응답이 없으면 + 클라이언트가 보낸 값이 된다 - redirect login page, HTML error body와 wildcard credential 금지 ## 6. Command와 idempotency diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index dfc7fba4..6991a90f 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -188,7 +188,9 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그 `correlation_id`로 쓰려면 `Access-Control-Expose-Headers`에도 넣는다 (`src/adapters/http/feature-http-binding.ts` `projectExecutionOutcome`, `src/bootstrap/runtime-adapters.ts` `createHttpObservationProjector`). telemetry에는 - 넣지 않는다. + 넣지 않는다. 반사값이 없으면(마감 초과, 연결 끊김, 헤더를 노출하지 않는 서버나 + 게이트웨이) `requestId`는 요청에 보낸 값이다(V3 결과의 `sentRequestId`). 결과 + 불명 쓰기 화면은 이 값을 "지원 참조"로 보인다(0929/03-04). ## 6. REST incident diff --git a/src/adapters/http/feature-http-binding.ts b/src/adapters/http/feature-http-binding.ts index ca1c483e..f91b10e7 100644 --- a/src/adapters/http/feature-http-binding.ts +++ b/src/adapters/http/feature-http-binding.ts @@ -295,6 +295,8 @@ export function createFeatureHttpBinding< /** * 03-03. A failure carries the server's echoed correlation id as `requestId`, * so the support reference a user reports points at one server log entry. + * 0929/03-04. Without an echo (timeout, lost connection, a gateway that drops + * the header) it is the id the request carried. */ function projectExecutionOutcome( operationId: string, @@ -309,9 +311,9 @@ function projectExecutionOutcome( ): Result { const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome); const requestId = - "metadata" in outcome + ("metadata" in outcome ? outcome.metadata?.correlationReference - : undefined; + : undefined) ?? outcome.sentRequestId; return projected.ok || requestId === undefined ? projected : Object.freeze({ diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 5db17aa3..6d4c8b40 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -143,7 +143,7 @@ export type HttpTransportFailure = Readonly<{ retryable: boolean; }>; -export type HttpExecutionOutcome = +export type HttpExecutionOutcome = ( | Readonly<{ kind: "SUCCESS"; value: Value; @@ -199,7 +199,17 @@ export type HttpExecutionOutcome = kind: "AUTH_INTEGRATION_FAILURE"; reason: AuthIntegrationFailureReason; effect: "NOT_APPLICABLE" | "NOT_STARTED"; - }>; + }> +) & + Readonly<{ + /** + * 0929/03-04. The `x-correlation-id` this execution put on its request, + * on every variant: a timeout or lost connection has no response to echo + * one. Absent when the request was never assembled or no id could be made. + * Diagnostics and support references only; never telemetry. + */ + sentRequestId?: string; + }>; /** * §7.7 / VD-23. A configuration or collaborator contract breach, never a user @@ -664,7 +674,9 @@ export function createContractHttpExecutor( } catch { // Observation is outside the execution authority. } - return outcome; + return sentRequestId === undefined + ? outcome + : Object.freeze({ ...outcome, sentRequestId }); }; /** diff --git a/tests/features/reference-feature/reference-production-vertical.test.tsx b/tests/features/reference-feature/reference-production-vertical.test.tsx index 05ec65d4..a8b7c98f 100644 --- a/tests/features/reference-feature/reference-production-vertical.test.tsx +++ b/tests/features/reference-feature/reference-production-vertical.test.tsx @@ -166,6 +166,48 @@ describe("reference feature production vertical path", () => { expect(idempotencyKeys[1]).toBe(idempotencyKeys[0]); }); + // 0929/03-04. A write past its deadline has no server answer to echo an + // id, so the screen shows the id the request itself carried. + it("shows the sent x-correlation-id for a create past its deadline", async () => { + const user = userEvent.setup(); + const sentIds: (string | null)[] = []; + mockApi.server.use( + http.get("http://app.test/config.json", () => + HttpResponse.json({ ...runtimeConfig, REQUEST_TIMEOUT_MS: 200 }), + ), + http.post("https://api.test/api/reference-resources", async ({ request }) => { + sentIds.push(request.headers.get("x-correlation-id")); + // The server is still working when the client deadline ends. + await new Promise((resolve) => { + request.signal.addEventListener("abort", () => resolve(), { once: true }); + }); + return new HttpResponse(null, { status: 504 }); + }), + ); + const composition = await createRuntimeComposition({ + fetcher: absoluteFetch, + host: {}, + }); + window.history.pushState({}, "", "/examples/reference-resources/new"); + render(); + + await user.click( + await screen.findByRole("button", { name: "로그인 시작" }), + ); + await user.type( + await screen.findByRole("textbox", { name: /새 항목 이름/ }), + "Past the deadline", + ); + await user.click(screen.getByRole("button", { name: "저장" })); + + expect( + await screen.findByText("변경 결과를 확인할 수 없습니다."), + ).toBeVisible(); + expect(sentIds).toHaveLength(1); + expect(sentIds[0]).toMatch(/^[A-Za-z0-9._:-]{1,128}$/u); + expect(screen.getByText(`지원 참조: ${sentIds[0]}`)).toBeVisible(); + }); + it("keeps the key when the resend meets the first attempt still in flight (0929/03-01)", async () => { const user = userEvent.setup(); const idempotencyKeys: (string | null)[] = [];