문제
참조 기능의 생성 분류기가 모든 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
169 lines
5.3 KiB
TypeScript
169 lines
5.3 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
|
|
import {
|
|
createFeatureHttpBinding,
|
|
type InstalledHttpOperationExecutor,
|
|
} from "../../../src/adapters/http/index.ts";
|
|
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>>,
|
|
): InstalledHttpOperationExecutor {
|
|
const execute = (async () => outcome) as unknown as
|
|
InstalledHttpOperationExecutor["execute"];
|
|
return Object.freeze({ execute });
|
|
}
|
|
|
|
describe("reference HTTP business problem mapping", () => {
|
|
it("maps a typed 409 reference problem to the feature-owned business code", async () => {
|
|
const executor = executorReturning(
|
|
Object.freeze({
|
|
kind: "PROBLEM",
|
|
problem: Object.freeze({
|
|
type: "https://example.test/problems/reference-conflict",
|
|
title: "Reference conflict",
|
|
status: 409,
|
|
code: "REFERENCE_NAME_ALREADY_EXISTS",
|
|
}),
|
|
metadata: Object.freeze({ status: 409 }),
|
|
effect: "NOT_APPLIED",
|
|
}),
|
|
);
|
|
const gateway = createReferenceHttpGateway(
|
|
createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS),
|
|
);
|
|
|
|
await expect(
|
|
gateway.create({ name: "duplicate" }),
|
|
).resolves.toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "CONFLICT",
|
|
code: "REFERENCE_NAME_ALREADY_EXISTS",
|
|
httpStatus: 409,
|
|
},
|
|
});
|
|
});
|
|
|
|
it.each([
|
|
{
|
|
status: 409,
|
|
code: undefined,
|
|
expectedKind: "CONFLICT",
|
|
expectedCode: "REFERENCE_RESOURCE_CONFLICT",
|
|
},
|
|
{
|
|
status: 422,
|
|
code: "REFERENCE_NAME_REJECTED",
|
|
expectedKind: "VALIDATION_REJECTED",
|
|
expectedCode: "REFERENCE_NAME_REJECTED",
|
|
},
|
|
{
|
|
status: 422,
|
|
code: undefined,
|
|
expectedKind: "VALIDATION_REJECTED",
|
|
expectedCode: "REFERENCE_RESOURCE_REJECTED",
|
|
},
|
|
{
|
|
status: 400,
|
|
code: "REFERENCE_BAD_REQUEST",
|
|
expectedKind: "UNKNOWN_CLIENT_FAILURE",
|
|
expectedCode: "CONTRACT_PROBLEM",
|
|
},
|
|
] as const)(
|
|
"projects create problem status $status through the feature-owned mapper/fallback",
|
|
async ({ status, code, expectedKind, expectedCode }) => {
|
|
const executor = executorReturning(
|
|
Object.freeze({
|
|
kind: "PROBLEM",
|
|
problem: Object.freeze({
|
|
type: "https://example.test/problems/reference-" + status,
|
|
title: "Reference request rejected",
|
|
status,
|
|
...(code === undefined ? {} : { code }),
|
|
}),
|
|
metadata: Object.freeze({ status }),
|
|
effect: "NOT_APPLIED",
|
|
}),
|
|
);
|
|
const gateway = createReferenceHttpGateway(
|
|
createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS),
|
|
);
|
|
|
|
await expect(
|
|
gateway.create({ name: "rejected" }),
|
|
).resolves.toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: expectedKind,
|
|
code: expectedCode,
|
|
httpStatus: status,
|
|
},
|
|
});
|
|
},
|
|
);
|
|
|
|
it("keeps the platform status fallback when the operation has no problem mapper", async () => {
|
|
const executor = executorReturning(
|
|
Object.freeze({
|
|
kind: "PROBLEM",
|
|
problem: Object.freeze({
|
|
type: "https://example.test/problems/not-found",
|
|
title: "Not found",
|
|
status: 404,
|
|
}),
|
|
metadata: Object.freeze({ status: 404 }),
|
|
effect: "NOT_APPLIED",
|
|
}),
|
|
);
|
|
const gateway = createReferenceHttpGateway(
|
|
createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS),
|
|
);
|
|
|
|
await expect(gateway.get("missing")).resolves.toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "NOT_FOUND",
|
|
code: "CONTRACT_PROBLEM",
|
|
httpStatus: 404,
|
|
},
|
|
});
|
|
});
|
|
});
|
|
|
|
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);
|
|
},
|
|
);
|
|
});
|