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)[] = [];