fix(http): 결과 불명 쓰기에 보낸 요청 id를 지원 참조로 싣는다 (0929/03-04)

문제: 바인딩은 서버가 돌려준 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
This commit is contained in:
DongHyeonka
2026-11-03 00:53:16 +09:00
parent c5f87aaef5
commit 849d000342
5 changed files with 66 additions and 7 deletions
@@ -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
@@ -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
+4 -2
View File
@@ -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<WireOutput, Problem, Value>(
operationId: string,
@@ -309,9 +311,9 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
): Result<Value, AppFailure> {
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({
+15 -3
View File
@@ -143,7 +143,7 @@ export type HttpTransportFailure = Readonly<{
retryable: boolean;
}>;
export type HttpExecutionOutcome<Value, Problem> =
export type HttpExecutionOutcome<Value, Problem> = (
| Readonly<{
kind: "SUCCESS";
value: Value;
@@ -199,7 +199,17 @@ export type HttpExecutionOutcome<Value, Problem> =
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 });
};
/**
@@ -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<void>((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(<RuntimeApplication composition={composition} />);
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)[] = [];