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(