fix(query): 키 없는 결과 불명 요청에는 재전송을 주지 않는다

문제
resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만
본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의
결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고,
서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험
X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가
NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의
기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도
이 버튼을 숨기는 장치가 없다.

고른 방법
- application-query.ts canResend: head가 UNKNOWN이고 intent에
  idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는
  거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다.
- AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고,
  훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면
  onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존
  페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다.
- KEYED는 지금처럼 같은 키로 재전송한다.

버린 대안
- 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존
  배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다).
- AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다.

위험·한계
- 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다.
  "적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정).
- 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은
  결과 불명 동안 제출을 막는다.
- hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다.

검증
- RED: application-mutation-admission 2건(NEVER: canResend false·resend null·
  execute 1회, KEYED: canResend true), async-surface 2건 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
  3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출.
- check:types, lint, check:architecture, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03
Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
This commit is contained in:
DongHyeonka
2026-11-04 20:43:06 +09:00
parent 1e8b3d049f
commit 2017ef76ff
7 changed files with 124 additions and 16 deletions
+1
View File
@@ -125,6 +125,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
└─ MAYBE_APPLIED → 결과 불명 화면
├─ 확인 (onReconcileUnknownEffect)
└─ 같은 키로 다시 보내기 (onResendUnknownEffect)
키가 있는 요청만. 키 없는 쓰기(NEVER)는 버튼이 없다
```
| | `NOT_APPLIED` | `MAYBE_APPLIED` |
@@ -27,7 +27,7 @@ HTTP 경로는 V3 하나다.
| bounded response decoder | 구현됨. 선언 길이 → 스트림 바이트 → JSON 구조 → 스키마 순 | `src/adapters/http/bounded-body-reader.ts`, `bounded-json.ts`, `http-execution-v3.ts` `admitResponse` |
| typed schema/mapper | 구현됨. 계약별 input/output/problem validator와 feature mapper | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/feature-http-binding.ts` |
| strict query/mutation definition과 concurrency coordinator | 구현됨 | `src/contracts/server-state.ts` `bindQuery`·`BoundMutation`, `src/presentation/adapters/query/application-query.ts` |
| 결과 불명 command의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다 | `application-query.ts` `resendUnknownEffect` (6.3) |
| 결과 불명 command의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다. 키 없는 command(`NEVER`)에는 재전송을 주지 않는다 | `application-query.ts` `resendUnknownEffect` (6.3) |
| cursor pagination | runtime만 있다. 설치된 operation이 쓰지 않는다 | `src/adapters/query-cache/cursor-pagination-runtime.ts` |
| conditional request | validator store만 조합됐다. V3는 `If-None-Match`/`If-Match`를 보내지 않는다 | `src/adapters/query-cache/conditional-validator-store.ts` |
| GraphQL reference adapter | 구현 안 됨 | 없음 |
@@ -256,6 +256,8 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그
다시 보내기"는 그 intent와 같은 `Idempotency-Key`로 보낸다. 입력이 바뀌면 새
key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts`
`submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`).
키가 없는 command(`NEVER`)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을
그리지 않는다(`canResendUnknownEffect`, 0929/03-03).
5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. 화면의
"변경됨으로 확인"이 이 경로다.
6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는
@@ -69,6 +69,11 @@ export type AsyncSignals = Readonly<{
isDegraded?: boolean;
isMutationPending?: boolean;
hasMutationEffectUnknown?: boolean;
/**
* 0929/03-03. Whether the unknown-effect request can be sent again as the
* same request: it carries an idempotency key.
*/
isUnknownEffectResendable?: boolean;
hasMutationConflict?: boolean;
}>;
@@ -78,6 +83,12 @@ export type AsyncState = Readonly<{
failure?: AppFailure;
overlay: AsyncOverlay;
indicator: (typeof ASYNC_OVERLAYS)[number] | null;
/**
* 0929/03-03. Only with `indicator: "mutation-effect-unknown"`, when the
* coordinator said: `false` means the request has no idempotency key, so
* sending it again is a second, unprotected request and no resend is drawn.
*/
unknownEffectResendable?: boolean;
}>;
export function deriveAsyncState(signals: AsyncSignals): AsyncState {
@@ -121,6 +132,10 @@ export function deriveAsyncState(signals: AsyncSignals): AsyncState {
failure: base === "terminal-error" ? signals.failure : undefined,
overlay,
indicator,
...(indicator === "mutation-effect-unknown" &&
signals.isUnknownEffectResendable !== undefined
? { unknownEffectResendable: signals.isUnknownEffectResendable }
: {}),
});
}
@@ -255,9 +255,17 @@ type ApplicationMutationController<Input, Value> = Readonly<{
/**
* D-1. Sends the oldest unknown-effect request again with its original
* intent, so a keyed command carries the same `Idempotency-Key`. Resolves
* to `null` when nothing is waiting to be resent.
* to `null` when nothing is waiting to be resent, and (0929/03-03) when
* that request has no key: the server could not tell a second one from a
* new request, so it could apply twice.
*/
resendUnknownEffect(): Promise<ApplicationResult<Value> | null>;
/**
* 0929/03-03. `resendUnknownEffect` would send: the oldest request is
* unknown, carries an idempotency key and is not being reconciled.
* `state.unknownEffectResendable` carries the same answer to `AsyncSurface`.
*/
canResendUnknownEffect: boolean;
}>;
type MutationExecution<Input> =
@@ -791,18 +799,15 @@ export function useApplicationMutation<Input, Value>(
const resendUnknownEffect = useCallback(async () => {
const head = unknownEffectChannel?.admissions[0];
if (
!head ||
head.state !== "UNKNOWN" ||
!head.intent ||
unknownEffectChannel?.reconciliationInFlight
) {
return null;
}
if (!head || !canResend(unknownEffectChannel, head)) return null;
return submit(head.input as Input);
}, [submit, unknownEffectChannel]);
const unknownEffectHead = unknownEffectChannel?.admissions[0];
const canResendUnknownEffect =
unknownEffectChannel !== null &&
unknownEffectHead !== undefined &&
canResend(unknownEffectChannel, unknownEffectHead);
return Object.freeze({
state: deriveAsyncState({
@@ -812,15 +817,33 @@ export function useApplicationMutation<Input, Value>(
unknownEffectHead?.state === "ACTIVE" ||
unknownEffectHead?.state === "RECONCILING",
hasMutationEffectUnknown: unknownEffectHead?.state === "UNKNOWN",
isUnknownEffectResendable: canResendUnknownEffect,
hasMutationConflict: conflict !== null,
}),
submit,
resolveConflict,
reconcileUnknownEffect,
resendUnknownEffect,
canResendUnknownEffect,
});
}
/**
* D-1 / 0929/03-03. A resend repeats the unknown request with its original
* intent. Without an idempotency key (a `NEVER` command) nothing lets the
* server recognise the repeat, so it is not offered.
*/
function canResend(
channel: UnknownEffectChannel,
head: MutationAdmission,
): boolean {
return (
head.state === "UNKNOWN" &&
head.intent?.idempotencyKey !== undefined &&
!channel.reconciliationInFlight
);
}
function mutationFailureWithEffect(failure: AppFailure): AppFailure {
switch (failure.effect) {
case "NOT_STARTED":
@@ -126,7 +126,11 @@ export type AsyncSurfaceProps = Readonly<{
onResolveConflict?: () => void;
/** Only `APPLIED` is offered: "not applied" needs evidence the UI lacks. */
onReconcileUnknownEffect?: (resolution: "APPLIED") => void;
/** D-1. Resends the unknown request with its original intent and key. */
/**
* D-1. Resends the unknown request with its original intent and key.
* 0929/03-03. Not drawn when `state.unknownEffectResendable` is `false`:
* a request without a key would go out as a second, unprotected one.
*/
onResendUnknownEffect?: () => void;
/** 08-05. Title level of the empty and failure surfaces it renders. */
headingLevel?: HeadingLevel | undefined;
@@ -219,7 +223,8 @@ export function AsyncSurface({
</Button>
) : null}
{state.indicator === "mutation-effect-unknown" &&
onResendUnknownEffect ? (
onResendUnknownEffect &&
state.unknownEffectResendable !== false ? (
<Button onClick={onResendUnknownEffect}>
{message("action.resendMutation")}
</Button>
@@ -406,7 +406,7 @@ describe("application mutation intent admission", () => {
function renderKeyedCreate(
outcomes: ApplicationResult<string>[],
maxIdentities?: number,
options: Readonly<{ maxIdentities?: number; keyed?: boolean }> = {},
) {
const client = queryClient();
const intents: MutationIntent[] = [];
@@ -421,14 +421,14 @@ describe("application mutation intent admission", () => {
return outcomes.shift() ?? { ok: true, value: input };
},
);
const scope = replayScope(maxIdentities);
const scope = replayScope(options.maxIdentities);
const hook = renderHook(
() =>
useApplicationMutation<string, string>({
definitionId: "replay-intent-v1",
definitionVersion: 1,
operationId: "CREATE_REPLAYED",
requiresIdempotencyKey: true,
requiresIdempotencyKey: options.keyed ?? true,
owner: "platform-test",
duplicatePolicy: "REJECT_WHILE_ACTIVE",
scope,
@@ -484,7 +484,7 @@ describe("application mutation intent admission", () => {
// identity registry evicts other inputs first and the same input saved
// later still finds the unknown request and its key.
it("keeps the unknown input's identity when the identity registry is full", async () => {
const { hook, intents } = renderKeyedCreate([unknown], 2);
const { hook, intents } = renderKeyedCreate([unknown], { maxIdentities: 2 });
await act(() => hook.result.current.submit("same-input"));
// A two-entry registry: the third input evicts the oldest unleased one.
await act(() => hook.result.current.submit("second-input"));
@@ -536,6 +536,34 @@ describe("application mutation intent admission", () => {
expect(execute).toHaveBeenCalledTimes(3);
});
// 0929/03-03. A command without a key has nothing the server can match a
// second request to: resending it after a lost answer can apply it twice.
it("offers no resend for an unknown request that carries no key", async () => {
const { hook, execute } = renderKeyedCreate([unknown], { keyed: false });
await act(() => hook.result.current.submit("keyless-input"));
expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown");
expect(hook.result.current.canResendUnknownEffect).toBe(false);
expect(hook.result.current.state.unknownEffectResendable).toBe(false);
let resent: ApplicationResult<string> | null | undefined;
await act(async () => {
resent = await hook.result.current.resendUnknownEffect();
});
expect(resent).toBeNull();
expect(execute).toHaveBeenCalledOnce();
expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown");
});
it("offers the same-key resend for an unknown keyed request", async () => {
const { hook } = renderKeyedCreate([unknown]);
expect(hook.result.current.canResendUnknownEffect).toBe(false);
await act(() => hook.result.current.submit("keyed-input"));
expect(hook.result.current.canResendUnknownEffect).toBe(true);
expect(hook.result.current.state.unknownEffectResendable).toBe(true);
});
// 백엔드 1101/02-01. The paired backend answers a same-key request while
// the first still runs with 409 IDEMPOTENT_IN_FLIGHT and Retry-After.
it("holds a resend until the Retry-After of the unknown answer", async () => {
+34
View File
@@ -102,6 +102,40 @@ describe("async UI state matrix", () => {
expect(retry).not.toHaveBeenCalled();
});
// 0929/03-03. The coordinator says when the unknown request has no key;
// the surface then draws no resend, whatever callback the page passes.
it("draws no resend for an unknown request that cannot be resent", () => {
render(
<AsyncSurface
state={deriveAsyncState({
data: ["value"],
hasMutationEffectUnknown: true,
isUnknownEffectResendable: false,
})}
onReconcileUnknownEffect={vi.fn()}
onResendUnknownEffect={vi.fn()}
/>,
);
expect(
screen.queryByRole("button", { name: "같은 요청으로 다시 보내기" }),
).not.toBeInTheDocument();
expect(screen.getByRole("button", { name: "변경됨으로 확인" })).toBeInTheDocument();
});
it("keeps the resend state to an unknown mutation only", () => {
expect(
deriveAsyncState({ data: ["value"], isUnknownEffectResendable: false }),
).not.toHaveProperty("unknownEffectResendable");
expect(
deriveAsyncState({
data: ["value"],
hasMutationEffectUnknown: true,
isUnknownEffectResendable: true,
}).unknownEffectResendable,
).toBe(true);
});
// 0929/08-04. The unknown result is the case a user most wants to report.
it("shows the support reference of a save whose effect is unknown", () => {
render(