fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).
고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.
버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.
위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
(CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
(reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
"처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.
검증
- RED(수정 전): reference-production-vertical "keeps the key when the
resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
(IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
check:ci 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
This commit is contained in:
@@ -88,7 +88,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
|
||||
| logging/diagnostics | 준비됨 | 별도 `DiagnosticsPort`, 8-event registry, allowlist, bounded/no-op adapter와 production producer | 실제 프로젝트의 remote sink는 port 뒤에서 선택 |
|
||||
| telemetry | 준비됨/프로젝트 선택 | 5-event registry, bounded queue, redaction/value policy, boot·HTTP·render·release·drop producer | analytics/RUM/error vendor와 consent는 프로젝트에서 선택 |
|
||||
| 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 |
|
||||
| 단위·통합·E2E | 준비됨 | source/test strict typecheck, shared MSW 19개 scenario, 실제 bootstrap, built-dist 3엔진·compact E2E | 제품별 critical flow를 같은 catalog/gate에 추가 |
|
||||
| 단위·통합·E2E | 준비됨 | source/test strict typecheck, shared MSW 20개 scenario, 실제 bootstrap, built-dist 3엔진·compact E2E | 제품별 critical flow를 같은 catalog/gate에 추가 |
|
||||
| UI 회귀 검증 | 준비됨 | dev-only Storybook interaction/axe와 pinned Chromium visual baseline 4종 | cloud review와 다중 OS/device는 프로젝트 선택 |
|
||||
| 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 9단계 검증 | 새 contribution도 같은 제거 gate에 포함 |
|
||||
| registry·compatibility 집행 | 준비됨 | 10개 registry type/reference/consumer/orphan, 승인 digest와 actual semantic diff, breaking evidence | public 계약 변경 시 baseline review 유지 |
|
||||
|
||||
@@ -852,7 +852,7 @@ owner와 만료 시한이 있는 quarantine만 허용한다.
|
||||
`behavior-change`, 제거/type/path/contract 변경은 `breaking`으로 계산한다.
|
||||
breaking에는 version, migration, compatibility window, rollback과 owner를
|
||||
요구하며 digest 변조와 누락 fixture가 실제로 실패한다.
|
||||
- API operation별 19개 shared MSW scenario catalog와 strict unhandled-request
|
||||
- API operation별 20개 shared MSW scenario catalog와 strict unhandled-request
|
||||
server를 제공하고 reference vertical integration이 공통 envelope/handler를
|
||||
사용한다.
|
||||
- 기본 Playwright는 `build` + `preview`의 실제 `dist`를 Chromium, Firefox,
|
||||
|
||||
@@ -141,7 +141,7 @@ rasterization과 실제 device farm은 프로젝트가 요구할 때 연결한
|
||||
#### Shared MSW와 결정성
|
||||
|
||||
operation별 success/empty/slow/network/timeout/content/envelope/schema/auth/
|
||||
403/404/409/422/429/retry/terminal을 포함한 19개 scenario catalog와 strict
|
||||
403/404/409(충돌·처리 중)/422/429/retry/terminal을 포함한 20개 scenario catalog와 strict
|
||||
unhandled-request server(`tests/mocks/server.ts`의
|
||||
`onUnhandledRequest: "error"`)를 공유한다. browser test는 공용 fixture
|
||||
(`tests/support/browser/strict-browser-test.ts`)가 console error/warning,
|
||||
@@ -746,7 +746,8 @@ tests/factories/
|
||||
| `unauthenticated-401` | 401. 명령은 적용되지 않음(`NOT_APPLIED`) |
|
||||
| `forbidden-403` | 권한 없음 |
|
||||
| `not-found-404` | 리소스 없음 |
|
||||
| `conflict-409` | mutation conflict |
|
||||
| `conflict-409` | mutation conflict. 계약에 적힌 충돌 code라 명령은 적용되지 않음(`NOT_APPLIED`) |
|
||||
| `in-flight-409` | 같은 멱등 키의 앞선 요청이 아직 처리 중(`IDEMPOTENT_IN_FLIGHT`). 명령은 결과 불명(`MAYBE_APPLIED`)이라 다음 전송도 같은 키 |
|
||||
| `validation-422` | 승인된 field/global error |
|
||||
| `rate-limited-429` | Retry-After 포함 |
|
||||
| `server-retry-success` | bounded retry 뒤 성공 |
|
||||
|
||||
@@ -45,7 +45,7 @@ if (
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
"HTTP scenario evidence: PASS (stale receipt removed, 54 executed, missing-ID fixture rejected)\n",
|
||||
"HTTP scenario evidence: PASS (stale receipt removed, 57 executed, missing-ID fixture rejected)\n",
|
||||
);
|
||||
|
||||
function run(script: string) {
|
||||
|
||||
+19
-1
@@ -30,6 +30,18 @@ const PROBLEM_VALIDATOR = zodValidator(
|
||||
referenceProblemSchema,
|
||||
);
|
||||
|
||||
/**
|
||||
* 0929/03-01. A 409 does not by itself mean "refused": a resend with the same
|
||||
* key can meet the first attempt still running (the paired backend answers
|
||||
* `409 IDEMPOTENT_IN_FLIGHT`). Only the conflict codes this fixture declares
|
||||
* are `NOT_APPLIED`; any other 409 stays `MAYBE_APPLIED`, so the coordinator
|
||||
* keeps the intent and the next send reuses the key. Answering `NOT_APPLIED`
|
||||
* there would let the next save mint a new key and create the resource twice.
|
||||
*/
|
||||
const CREATE_NOT_APPLIED_CONFLICT_CODES: ReadonlySet<string> = new Set([
|
||||
"CONFLICT",
|
||||
]);
|
||||
|
||||
/**
|
||||
* Fixture-side classifier standing in for the package-provided pure bounded
|
||||
* classifier. A status the fixture does not describe stays `MAYBE_APPLIED`.
|
||||
@@ -38,8 +50,14 @@ const CREATE_EFFECT: CommandEffectDescriptor<ReferenceProblem> = Object.freeze({
|
||||
successEffect: "APPLIED_CONFIRMED" as const,
|
||||
classifyProblem({
|
||||
status,
|
||||
problem,
|
||||
}: Readonly<{ status: number; problem: ReferenceProblem }>) {
|
||||
if (status === 400 || status === 409 || status === 422) {
|
||||
if (status === 400 || status === 422) return "NOT_APPLIED";
|
||||
if (
|
||||
status === 409 &&
|
||||
problem.code !== undefined &&
|
||||
CREATE_NOT_APPLIED_CONFLICT_CODES.has(problem.code)
|
||||
) {
|
||||
return "NOT_APPLIED";
|
||||
}
|
||||
return "MAYBE_APPLIED";
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
createReferenceHttpGateway,
|
||||
REFERENCE_HTTP_OPERATIONS,
|
||||
} from "../../../src/features/reference-feature/adapters/reference-http-gateway.ts";
|
||||
import { CREATE_REFERENCE_RESOURCE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
|
||||
|
||||
function executorReturning(
|
||||
outcome: Readonly<Record<string, unknown>>,
|
||||
@@ -133,3 +134,35 @@ describe("reference HTTP business problem mapping", () => {
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("reference create problem effect classification (0929/03-01)", () => {
|
||||
const classify = (status: number, code?: string) =>
|
||||
CREATE_REFERENCE_RESOURCE_CONTRACT.contract.commandEffect.classifyProblem({
|
||||
status,
|
||||
problem: Object.freeze({
|
||||
type: "https://api.test/problems/reference",
|
||||
title: "Reference problem",
|
||||
status,
|
||||
...(code === undefined ? {} : { code }),
|
||||
}),
|
||||
});
|
||||
|
||||
it.each([
|
||||
// The first attempt with this key still runs: the key must stay bound.
|
||||
{ status: 409, code: "IDEMPOTENT_IN_FLIGHT", effect: "MAYBE_APPLIED" },
|
||||
// An undeclared 409 may hide a running attempt: safe side.
|
||||
{ status: 409, code: "SOMETHING_NEW", effect: "MAYBE_APPLIED" },
|
||||
{ status: 409, code: undefined, effect: "MAYBE_APPLIED" },
|
||||
// The fixture's declared semantic conflict is the only refused 409.
|
||||
{ status: 409, code: "CONFLICT", effect: "NOT_APPLIED" },
|
||||
{ status: 400, code: undefined, effect: "NOT_APPLIED" },
|
||||
{ status: 422, code: "VALIDATION_REJECTED", effect: "NOT_APPLIED" },
|
||||
{ status: 404, code: "NOT_FOUND", effect: "MAYBE_APPLIED" },
|
||||
{ status: 503, code: "SERVER_FAILURE", effect: "MAYBE_APPLIED" },
|
||||
] as const)(
|
||||
"classifies status $status code $code as $effect",
|
||||
({ status, code, effect }) => {
|
||||
expect(classify(status, code)).toBe(effect);
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { render, screen } from "@testing-library/react";
|
||||
import { render, screen, waitFor } from "@testing-library/react";
|
||||
import userEvent from "@testing-library/user-event";
|
||||
import { http, HttpResponse } from "msw";
|
||||
import {
|
||||
@@ -166,6 +166,93 @@ describe("reference feature production vertical path", () => {
|
||||
expect(idempotencyKeys[1]).toBe(idempotencyKeys[0]);
|
||||
});
|
||||
|
||||
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)[] = [];
|
||||
// A server that deduplicates by key: one receipt per created resource.
|
||||
const receipts = new Map<string, Record<string, string>>();
|
||||
let firstAttemptRunning = true;
|
||||
mockApi.server.use(
|
||||
http.post("https://api.test/api/reference-resources", async ({ request }) => {
|
||||
const key = request.headers.get("idempotency-key") ?? "";
|
||||
idempotencyKeys.push(key);
|
||||
const receipt = receipts.get(key);
|
||||
if (receipt) {
|
||||
if (firstAttemptRunning) {
|
||||
// The paired backend answers a same-key request while the first
|
||||
// attempt still runs with 409 IDEMPOTENT_IN_FLIGHT.
|
||||
firstAttemptRunning = false;
|
||||
return HttpResponse.json(
|
||||
{
|
||||
type: "https://api.test/problems/idempotent_in_flight",
|
||||
title: "IDEMPOTENT_IN_FLIGHT",
|
||||
status: 409,
|
||||
code: "IDEMPOTENT_IN_FLIGHT",
|
||||
},
|
||||
{
|
||||
status: 409,
|
||||
headers: { "content-type": "application/problem+json" },
|
||||
},
|
||||
);
|
||||
}
|
||||
return HttpResponse.json(receipt, { status: 201 });
|
||||
}
|
||||
const body = (await request.json()) as { name: string };
|
||||
const resource = {
|
||||
id: `reference-created-${receipts.size + 1}`,
|
||||
name: body.name,
|
||||
createdAt: "2026-07-26T00:00:00.000Z",
|
||||
};
|
||||
receipts.set(key, resource);
|
||||
// The first attempt reaches the server; only its response is lost.
|
||||
if (receipts.size === 1) return new HttpResponse(null, { status: 504 });
|
||||
return HttpResponse.json(resource, { status: 201 });
|
||||
}),
|
||||
);
|
||||
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: /새 항목 이름/ }),
|
||||
"Slow write",
|
||||
);
|
||||
await user.click(screen.getByRole("button", { name: "저장" }));
|
||||
await user.click(
|
||||
await screen.findByRole("button", { name: "같은 요청으로 다시 보내기" }),
|
||||
);
|
||||
await waitFor(() => expect(idempotencyKeys).toHaveLength(2));
|
||||
|
||||
// After the 409 the user takes the next step the screen offers.
|
||||
const next = await waitFor(() => {
|
||||
const resend = screen.queryByRole("button", {
|
||||
name: "같은 요청으로 다시 보내기",
|
||||
});
|
||||
if (resend) return resend;
|
||||
const save = screen.getByRole("button", { name: "저장" });
|
||||
expect(save).toBeEnabled();
|
||||
return save;
|
||||
});
|
||||
const shownAfterInFlight = {
|
||||
unknown: screen.queryByText("변경 결과를 확인할 수 없습니다.") !== null,
|
||||
conflict: screen.queryAllByText(/충돌/).length > 0,
|
||||
};
|
||||
await user.click(next);
|
||||
await waitFor(() => expect(idempotencyKeys).toHaveLength(3));
|
||||
|
||||
const [first] = idempotencyKeys;
|
||||
expect(idempotencyKeys).toEqual([first, first, first]);
|
||||
expect(receipts.size).toBe(1);
|
||||
expect(shownAfterInFlight).toEqual({ unknown: true, conflict: false });
|
||||
expect(await screen.findByText("저장했습니다.")).toBeVisible();
|
||||
});
|
||||
|
||||
it.each([
|
||||
// The demo session treats a server 401 as signed out; the route guard
|
||||
// then asks for sign-in and the form is gone.
|
||||
|
||||
@@ -361,17 +361,17 @@ async function executeScenario(
|
||||
}
|
||||
|
||||
describe("HTTP scenario catalog execution evidence", () => {
|
||||
it("declares exactly the 54 behaviorally distinct operation scenarios", () => {
|
||||
it("declares exactly the 57 behaviorally distinct operation scenarios", () => {
|
||||
const executionIds = Object.entries(OPERATION_SCENARIO_CATALOG).flatMap(
|
||||
([operationId, scenarioIds]) =>
|
||||
scenarioIds.map((scenarioId) => `${operationId}::${scenarioId}`),
|
||||
);
|
||||
|
||||
expect(OPERATION_SCENARIO_CATALOG.LIST_REFERENCE_RESOURCES).toHaveLength(19);
|
||||
expect(OPERATION_SCENARIO_CATALOG.GET_REFERENCE_RESOURCE).toHaveLength(18);
|
||||
expect(OPERATION_SCENARIO_CATALOG.CREATE_REFERENCE_RESOURCE).toHaveLength(17);
|
||||
expect(executionIds).toHaveLength(54);
|
||||
expect(new Set(executionIds)).toHaveLength(54);
|
||||
expect(OPERATION_SCENARIO_CATALOG.LIST_REFERENCE_RESOURCES).toHaveLength(20);
|
||||
expect(OPERATION_SCENARIO_CATALOG.GET_REFERENCE_RESOURCE).toHaveLength(19);
|
||||
expect(OPERATION_SCENARIO_CATALOG.CREATE_REFERENCE_RESOURCE).toHaveLength(18);
|
||||
expect(executionIds).toHaveLength(57);
|
||||
expect(new Set(executionIds)).toHaveLength(57);
|
||||
expect(executionIds).toEqual(HTTP_SCENARIO_EXECUTION_IDS);
|
||||
});
|
||||
|
||||
@@ -410,7 +410,7 @@ describe("HTTP scenario catalog execution evidence", () => {
|
||||
HTTP_SCENARIO_RECEIPT_SCHEMA_VERSION,
|
||||
HTTP_SCENARIO_EXPECTATIONS,
|
||||
),
|
||||
catalogTotal: 54,
|
||||
catalogTotal: 57,
|
||||
executedIds: sortedRows.map((row) => row.executionId),
|
||||
rows: sortedRows,
|
||||
},
|
||||
|
||||
@@ -81,6 +81,11 @@ async function scenarioResponse(
|
||||
if (scenario === "conflict-409") {
|
||||
return HttpResponse.json(problem(409, "CONFLICT"), { status: 409 });
|
||||
}
|
||||
if (scenario === "in-flight-409") {
|
||||
return HttpResponse.json(problem(409, "IDEMPOTENT_IN_FLIGHT"), {
|
||||
status: 409,
|
||||
});
|
||||
}
|
||||
if (scenario === "validation-422") {
|
||||
return HttpResponse.json(
|
||||
problem(422, "VALIDATION_REJECTED"),
|
||||
|
||||
@@ -30,6 +30,7 @@ export const HTTP_SCENARIO_IDS = Object.freeze([
|
||||
"forbidden-403",
|
||||
"not-found-404",
|
||||
"conflict-409",
|
||||
"in-flight-409",
|
||||
"validation-422",
|
||||
"rate-limited-429",
|
||||
"server-retry-success",
|
||||
@@ -271,6 +272,21 @@ function expectationFor(
|
||||
),
|
||||
];
|
||||
break;
|
||||
case "in-flight-409":
|
||||
// 0929/03-01. The same key is still running: the command stays unknown.
|
||||
statuses = [409];
|
||||
kind = "PROBLEM";
|
||||
detail = "409";
|
||||
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLIED";
|
||||
observer = command ? "MAYBE_APPLIED" : "NOT_STARTED";
|
||||
bodies = [
|
||||
attemptBody(
|
||||
"FULLY_READ_WITHIN_BOUND",
|
||||
jsonBytes(problem(409, "IDEMPOTENT_IN_FLIGHT")),
|
||||
65_536,
|
||||
),
|
||||
];
|
||||
break;
|
||||
case "validation-422":
|
||||
statuses = [422];
|
||||
kind = "PROBLEM";
|
||||
|
||||
Reference in New Issue
Block a user