diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 139c0935..8b1a3f64 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -125,6 +125,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 └─ MAYBE_APPLIED → 결과 불명 화면 ├─ 확인 (onReconcileUnknownEffect) └─ 같은 키로 다시 보내기 (onResendUnknownEffect) + 키가 있는 요청만. 키 없는 쓰기(NEVER)는 버튼이 없다 ``` | | `NOT_APPLIED` | `MAYBE_APPLIED` | diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index 98c3391f..c4576711 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -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한다. 화면은 근거 없는 diff --git a/src/application/view-models/async-state.ts b/src/application/view-models/async-state.ts index 3d573d7d..ecf72aa8 100644 --- a/src/application/view-models/async-state.ts +++ b/src/application/view-models/async-state.ts @@ -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 } + : {}), }); } diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index 081f240b..2f6daace 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -255,9 +255,17 @@ type ApplicationMutationController = 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 | 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 = @@ -791,18 +799,15 @@ export function useApplicationMutation( 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( 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": diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx index 61d5d42a..b6028b5f 100644 --- a/src/presentation/components/async-surface.tsx +++ b/src/presentation/components/async-surface.tsx @@ -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({ ) : null} {state.indicator === "mutation-effect-unknown" && - onResendUnknownEffect ? ( + onResendUnknownEffect && + state.unknownEffectResendable !== false ? ( diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx index 380c6e7e..f52334af 100644 --- a/tests/component/application-mutation-admission.test.tsx +++ b/tests/component/application-mutation-admission.test.tsx @@ -406,7 +406,7 @@ describe("application mutation intent admission", () => { function renderKeyedCreate( outcomes: ApplicationResult[], - 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({ 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 | 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 () => { diff --git a/tests/component/async-surface.test.tsx b/tests/component/async-surface.test.tsx index d13434b5..6b3ab630 100644 --- a/tests/component/async-surface.test.tsx +++ b/tests/component/async-surface.test.tsx @@ -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( + , + ); + + 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(