diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index 681e34b4..4179a062 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -256,10 +256,14 @@ 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`). - 다시 보낸 요청이 쓰기 전에 거절되거나(429, 503 `RATE_LIMIT_*`, 401) 보내지 못하면 - (`NOT_STARTED`) 그 시도만 적용되지 않은 것이다. 결과 불명과 key는 그대로다. 폼은 - "잠시 뒤 같은 요청으로 다시 보내 주세요"를 보이고 저장을 받지 않는다. 401은 다시 - 로그인 안내가 먼저다(1106/03-01, `use-app-form.ts` `resendUnknown`). + 다시 보낸 요청이 쓰기 전에 거절되거나(429, 401, 403, 503 `RATE_LIMIT_*`, 422 + `IDEMPOTENT_REQUEST_MISMATCH`, 기능이 선언한 code) 보내지 못하면(`NOT_STARTED`) 그 + 시도만 적용되지 않은 것이다. 결과 불명과 key는 그대로다. 폼은 "잠시 뒤 같은 요청으로 + 다시 보내 주세요"와 결과 불명 화면(확인, 다시 보내기)을 보이고 저장을 받지 않는다. + 401은 다시 로그인 안내가 먼저다. 예외는 같은 요청이 매번 받는 거절이다. 입력 검증 + (`VALIDATION_REJECTED`, 400 `VALIDATION_FAILED`)과 400 `IDEMPOTENCY_KEY_INVALID`는 첫 + 요청도 거절됐다는 뜻이라 결과 불명을 풀고, 폼은 필드 오류를 보이고 저장을 다시 + 받는다(1106/03-01, `src/contracts/errors.ts` `isRefusedOnEveryAttempt`). 키가 없는 command(`NEVER`)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을 그리지 않는다(`canResendUnknownEffect`, 0929/03-03). 같은 canonical input의 재저장도 보내지 않는다. 훅의 `submit`이 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index 8e8b08af..9290d49f 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -242,6 +242,41 @@ export function withFailureEffect( }); } +/** + * 1106/03-01 (D10 supplement). The paired backend's pre-write refusals that + * every attempt of one request gets, code and status: binding and + * validation of the request (400 VALIDATION_FAILED, whatever its details) + * and a key its rule rejects (400 IDEMPOTENCY_KEY_INVALID). Both are rows of + * the refusal table in `src/adapters/http/backend-envelope.ts` + * (tests/unit/backend-envelope.test.ts holds them to it). Its other rows are + * not: 422 IDEMPOTENT_REQUEST_MISMATCH comes only once the key reached the + * server, and the 503 RATE_LIMIT_* answers come before the idempotency + * check and change over time. + */ +export const REFUSALS_OF_EVERY_ATTEMPT: Readonly> = + Object.freeze({ + VALIDATION_FAILED: 400, + IDEMPOTENCY_KEY_INVALID: 400, + }); + +/** + * 1106/03-01 (D10 supplement). A `NOT_APPLIED` refusal the same request gets + * on every attempt: input validation (`VALIDATION_REJECTED`) or a row above. + * A resend of an unknown request that meets one shows the first attempt was + * refused too, so the request is settled. Not one: a refusal before the + * idempotency check or one that changes over time (429, 401, 403, 503 + * RATE_LIMIT_*), a code a feature declared refused before its write (it may + * be a rule on changing state), any other code, and `NOT_STARTED`. + */ +export function isRefusedOnEveryAttempt(failure: AppFailure): boolean { + if (failure.effect !== "NOT_APPLIED") return false; + if (failure.kind === "VALIDATION_REJECTED") return true; + return ( + Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, failure.code) && + REFUSALS_OF_EVERY_ATTEMPT[failure.code] === failure.httpStatus + ); +} + /** * Projects an untrusted validation details payload into the only validation * metadata allowed to cross the HTTP boundary. Backend copy and additional diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index 797785e0..03bdca14 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -20,6 +20,7 @@ import { import type { Result } from "../../../contracts/result.ts"; import { createFailure, + isRefusedOnEveryAttempt, normalizeUnknownFailure, withFailureEffect, type AppFailure, @@ -268,8 +269,8 @@ type ApplicationMutationController = Readonly<{ * new request, so it could apply twice. An IDEMPOTENT command * (`resendSafe`) is sent without one (1106/03-03). 1106/03-01. A resend * that ends `NOT_APPLIED` or `NOT_STARTED` resolves to that failure and - * leaves the request unknown with its key; only success or - * `APPLIED_CONFIRMED` settles it. + * leaves the request unknown with its key. Success, `APPLIED_CONFIRMED` + * and a refusal every attempt gets (`isRefusedOnEveryAttempt`) settle it. */ resendUnknownEffect(): Promise | null>; /** @@ -634,9 +635,15 @@ export function useApplicationMutation( // the write (429, the edge's 503 RATE_LIMIT_*) or never sent shows only // that this attempt did not apply; the first may have. The request // stays unknown with its intent, so the next save or resend carries - // the same key, never a new one (backend http-contract.md §2). - const resendLeavesUnknown = (): boolean => - replayed !== undefined && (!scope || scope.isCurrent()); + // the same key, never a new one (backend http-contract.md §2). A + // refusal every attempt of the request gets (input validation, a key + // the server's rule rejects) shows the first was refused too, so the + // request is settled and the form can take a corrected save + // (isRefusedOnEveryAttempt, D10 supplement). + const resendLeavesUnknown = (failure: AppFailure): boolean => + replayed !== undefined && + (!scope || scope.isCurrent()) && + !isRefusedOnEveryAttempt(failure); let runtimeExecution: RuntimeMutationExecution | undefined; const pending = (async (): Promise> => { @@ -700,7 +707,7 @@ export function useApplicationMutation( switch (failure.effect) { case "NOT_STARTED": case "NOT_APPLIED": - if (resendLeavesUnknown()) { + if (resendLeavesUnknown(failure)) { optimisticLayer?.markUncertain(); holdUnknown(failure.retryAfterMs); break; @@ -755,7 +762,7 @@ export function useApplicationMutation( }), "NOT_STARTED", ); - if (resendLeavesUnknown()) { + if (resendLeavesUnknown(failure)) { admission.optimisticLayer?.markUncertain(); holdUnknown(undefined); return { ok: false as const, error: failure }; diff --git a/src/presentation/forms/use-app-form.ts b/src/presentation/forms/use-app-form.ts index c0351fd5..9f859164 100644 --- a/src/presentation/forms/use-app-form.ts +++ b/src/presentation/forms/use-app-form.ts @@ -10,7 +10,10 @@ import { } from "react"; import { flushSync } from "react-dom"; import type { ZodIssue, ZodType } from "../../contracts/zod.ts"; -import type { AppFailure } from "../../contracts/errors.ts"; +import { + isRefusedOnEveryAttempt, + type AppFailure, +} from "../../contracts/errors.ts"; import { useLocale, type ParameterlessMessageKey, @@ -508,14 +511,18 @@ function refusalFor( /** * 1106/03-01. The resend did not reach the write: the request it repeats is * still unknown, and the mutation coordinator keeps its key. Signing in again - * still comes first (D-2). + * still comes first (D-2). A refusal every attempt gets + * (`isRefusedOnEveryAttempt`, the coordinator's own test) settles the request + * instead, and the form shows it as for a first save (field errors, a save + * it takes again). */ function resendLeftUnknown(outcome: FormResult): boolean { return ( !outcome.ok && (outcome.error.effect === "NOT_APPLIED" || outcome.error.effect === "NOT_STARTED") && - outcome.error.action !== "reauth" + outcome.error.action !== "reauth" && + !isRefusedOnEveryAttempt(outcome.error) ); } diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx index 437e1fef..a07c961b 100644 --- a/tests/component/application-mutation-admission.test.tsx +++ b/tests/component/application-mutation-admission.test.tsx @@ -725,6 +725,40 @@ describe("application mutation intent admission", () => { effect: "NOT_STARTED", }), ], + // D10 supplement: these come before the idempotency check, change + // over time, or need the key to have reached the server already. + [ + "refused with 401", + createFailure("AUTH_REQUIRED", "CREATE_REPLAYED", 0, { + httpStatus: 401, + effect: "NOT_APPLIED", + }), + ], + [ + "refused with 403", + createFailure("FORBIDDEN", "CREATE_REPLAYED", 0, { + httpStatus: 403, + effect: "NOT_APPLIED", + }), + ], + [ + "refused with 422 IDEMPOTENT_REQUEST_MISMATCH", + createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, { + code: "IDEMPOTENT_REQUEST_MISMATCH", + httpStatus: 422, + effect: "NOT_APPLIED", + }), + ], + // A code the feature declared refused before its write may be a rule + // on changing state (a name already taken). + [ + "refused with a code the feature declared", + createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, { + code: "WORKLOG_INVALID", + httpStatus: 400, + effect: "NOT_APPLIED", + }), + ], ])("keeps the request unknown with its key when the resend is %s", async (_label, refusal) => { const { hook, intents } = renderKeyedCreate([ unknown, @@ -755,6 +789,100 @@ describe("application mutation intent admission", () => { ]); }); + // 1106/03-01 (D10 supplement). A refusal every attempt of the request + // gets shows the first attempt was refused too: input validation, or a + // key the server's rule rejects. The request is settled, so the form can + // take a corrected save, which goes out as a new request. + it.each([ + [ + "400 VALIDATION_FAILED with its field list", + createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, { + code: "VALIDATION_FAILED", + httpStatus: 400, + effect: "NOT_APPLIED", + }), + ], + [ + "400 VALIDATION_FAILED whose body did not parse", + createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, { + code: "VALIDATION_FAILED", + httpStatus: 400, + effect: "NOT_APPLIED", + }), + ], + [ + "400 IDEMPOTENCY_KEY_INVALID", + createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, { + code: "IDEMPOTENCY_KEY_INVALID", + httpStatus: 400, + effect: "NOT_APPLIED", + }), + ], + ])("settles the request when the resend is refused with %s", async (_label, refusal) => { + const { hook, intents } = renderKeyedCreate([ + unknown, + { ok: false, error: refusal }, + ]); + await act(() => hook.result.current.submit("same-input")); + + let resent: ApplicationResult | null | undefined; + await act(async () => { + resent = await hook.result.current.resendUnknownEffect(); + }); + + expect(resent).toMatchObject({ + ok: false, + error: { code: refusal.code, effect: "NOT_APPLIED" }, + }); + expect(hook.result.current.state.indicator).toBeNull(); + expect(hook.result.current.canResendUnknownEffect).toBe(false); + + await act(() => hook.result.current.submit("corrected-input")); + + expect(intents.map((intent) => intent.idempotencyKey)).toEqual([ + "key-1", + "key-1", + "key-2", + ]); + }); + + // 1106/03-01 (D10 supplement) on the IDEMPOTENT path (1106/03-03). A 404 + // the operation reads as not applied is a common answer once the first + // attempt applied, so the request stays unknown; input validation + // settles it. + it.each([ + [ + "refused with 404", + createFailure("NOT_FOUND", "CREATE_REPLAYED", 0, { + httpStatus: 404, + effect: "NOT_APPLIED", + }), + "mutation-effect-unknown", + ], + [ + "refused with 400 VALIDATION_FAILED", + createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, { + code: "VALIDATION_FAILED", + httpStatus: 400, + effect: "NOT_APPLIED", + }), + null, + ], + ] as const)("decides an unknown IDEMPOTENT request by its resend %s", async (_label, refusal, indicator) => { + const { hook, execute } = renderKeyedCreate( + [unknown, { ok: false, error: refusal }], + { keyed: false, resendSafe: true }, + ); + await act(() => hook.result.current.submit("idempotent-input")); + + await act(async () => { + await hook.result.current.resendUnknownEffect(); + }); + + expect(execute).toHaveBeenCalledTimes(2); + expect(hook.result.current.state.indicator).toBe(indicator); + }); + // 1106/03-01. The same when the resend fails in the coordinator itself // before anything is sent (here the page's optimistic update throws). it("keeps the request unknown with its key when the resend fails before sending", async () => { diff --git a/tests/component/form-foundation.test.tsx b/tests/component/form-foundation.test.tsx index c97136f3..0b9d18b6 100644 --- a/tests/component/form-foundation.test.tsx +++ b/tests/component/form-foundation.test.tsx @@ -1213,4 +1213,63 @@ describe("correcting a field after a server validation refusal", () => { ); expect(sentKeys(fetcher)).toEqual(["key-1", "key-1", "key-1"]); }); + + // 1106/03-01 (D10 supplement). The same-key resend meets the backend's 400 + // VALIDATION_FAILED, which every attempt of that request gets: the first + // was refused too. The form is not held: it shows the field error, and the + // corrected value goes out as a new request. Before, the save stayed off + // and the only ways out were a false "confirm applied" or a reload. + it("takes a corrected save after a resend refused with 400 VALIDATION_FAILED", async () => { + const user = userEvent.setup(); + const fetcher = vi + .fn() + .mockRejectedValueOnce(new TypeError("Failed to fetch")) + .mockResolvedValueOnce( + Response.json( + { + success: false, + error: { + code: "VALIDATION_FAILED", + details: [{ field: "name", code: "NOT_BLANK", message: "필수 값이 없습니다." }], + }, + meta, + }, + { status: 400 }, + ), + ) + .mockImplementation(async () => + Response.json({ + success: true, + data: { id: "entity-1", name: "Fixed" }, + meta, + }), + ); + render(, { + wrapper: wrapper(queryClient()), + }); + const name = screen.getByRole("textbox", { name: /Name/ }); + + await user.type(name, "Rejected"); + await user.click(screen.getByRole("button", { name: "Submit" })); + await waitFor(() => + expect(screen.getByTestId("result")).toHaveTextContent("effect-unknown"), + ); + await user.click(screen.getByRole("button", { name: "Resend" })); + + await waitFor(() => + expect(screen.getByTestId("result")).toHaveTextContent("validation-error"), + ); + expect(name).toHaveAttribute("aria-invalid", "true"); + expect(screen.getByTestId("indicator")).toHaveTextContent("none"); + expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled(); + + await user.clear(name); + await user.type(name, "Fixed"); + await user.click(screen.getByRole("button", { name: "Submit" })); + + await waitFor(() => + expect(screen.getByTestId("result")).toHaveTextContent("success"), + ); + expect(sentKeys(fetcher)).toEqual(["key-1", "key-1", "key-2"]); + }); }); diff --git a/tests/features/reference-feature/reference-page.test.tsx b/tests/features/reference-feature/reference-page.test.tsx index 37e51dd2..be84b7e0 100644 --- a/tests/features/reference-feature/reference-page.test.tsx +++ b/tests/features/reference-feature/reference-page.test.tsx @@ -412,6 +412,87 @@ describe("reference feature page states", () => { expect(name).toHaveValue(""); }); + /** + * 1106/03-01 (D10 supplement). The form is never held for good after a + * same-key resend. A refusal that may change (429) keeps the result + * unknown and the confirm and resend actions on screen. A field error the + * request gets on every attempt settles it: the field shows the error and + * the save is on again. + */ + async function resendAnUnknownCreate(resendAnswer: ReferenceResult) { + const user = userEvent.setup(); + const createResource = vi + .fn() + .mockResolvedValueOnce({ + ok: false, + error: createFailure("SERVER_FAILURE", "CREATE_REFERENCE_RESOURCE", 0, { + effect: "MAYBE_APPLIED", + }), + }) + .mockResolvedValueOnce(resendAnswer) + .mockResolvedValue({ + ok: true, + value: { resourceId: "created", title: "Resent", createdAt: null }, + }); + renderReference( + inputWith({ createResource }), + "/examples/reference-resources/new", + ); + const name = await screen.findByRole("textbox", { name: /새 항목 이름/ }); + await user.type(name, "Resent"); + await user.click(screen.getByRole("button", { name: "저장" })); + await user.click( + await screen.findByRole("button", { name: "같은 요청으로 다시 보내기" }), + ); + await waitFor(() => expect(createResource).toHaveBeenCalledTimes(2)); + return { user, name, createResource }; + } + + it("keeps the confirm on screen when the resend is refused for now", async () => { + const { user } = await resendAnUnknownCreate({ + ok: false, + error: createFailure("RATE_LIMITED", "CREATE_REFERENCE_RESOURCE", 0, { + effect: "NOT_APPLIED", + httpStatus: 429, + }), + }); + + expect( + await screen.findByText(KO_MESSAGES["form.resendLater"]), + ).toBeVisible(); + expect(screen.getByText("변경 결과를 확인할 수 없습니다.")).toBeVisible(); + expect(screen.getByRole("button", { name: "같은 요청으로 다시 보내기" })).toBeVisible(); + await user.click(screen.getByRole("button", { name: "변경됨으로 확인" })); + + expect(await screen.findByText("저장했습니다.")).toBeVisible(); + }); + + it("shows the field error and saves again when the resend is refused on its input", async () => { + const { user, name, createResource } = await resendAnUnknownCreate({ + ok: false, + error: createFailure("VALIDATION_REJECTED", "CREATE_REFERENCE_RESOURCE", 0, { + effect: "NOT_APPLIED", + httpStatus: 422, + validationIssues: [{ path: "name", code: "REQUIRED" }], + }), + }); + + await waitFor(() => expect(name).toHaveAttribute("aria-invalid", "true")); + expect(screen.queryByText("변경 결과를 확인할 수 없습니다.")).not.toBeInTheDocument(); + expect(screen.getByRole("button", { name: "저장" })).toBeEnabled(); + await user.clear(name); + await user.type(name, "Corrected"); + await user.click(screen.getByRole("button", { name: "저장" })); + + expect(await screen.findByText("저장했습니다.")).toBeVisible(); + const keys = createResource.mock.calls.map(([, context]) => context?.intent?.idempotencyKey); + expect(keys).toEqual([ + "reference-page-key-1", + "reference-page-key-1", + "reference-page-key-2", + ]); + }); + it.each([ ["AUTH_REQUIRED", "계속하려면 로그인이 필요합니다.", "로그인"], ["FORBIDDEN", "이 작업을 수행할 권한이 없습니다.", "안전한 화면으로 이동"], diff --git a/tests/unit/backend-envelope.test.ts b/tests/unit/backend-envelope.test.ts index 742c24af..0ccfa487 100644 --- a/tests/unit/backend-envelope.test.ts +++ b/tests/unit/backend-envelope.test.ts @@ -5,7 +5,13 @@ import { envelopeFailureReading, idempotencyRefusalReason, invitesKeyedResend, + refusedBeforeWriteRows, } from "../../src/adapters/http/backend-envelope.ts"; +import { + createFailure, + isRefusedOnEveryAttempt, + REFUSALS_OF_EVERY_ATTEMPT, +} from "../../src/contracts/errors.ts"; /** * 1103/10-02. The backend's refusal table, read status by status. The @@ -175,3 +181,52 @@ describe("backend Envelope failure table", () => { }, ); }); + +/** + * 1106/03-01 (D10 supplement). The refusals every attempt of one request + * gets (`REFUSALS_OF_EVERY_ATTEMPT`, which the mutation coordinator and the + * form read) are rows of this table. Every other row is sorted to the other + * side here, so a new row fails this test until someone decides it. + */ +describe("refusals every attempt of a request gets", () => { + it("are rows of the refusal table, code and status", () => { + for (const [code, status] of Object.entries(REFUSALS_OF_EVERY_ATTEMPT)) { + expect(refusedBeforeWriteRows()).toContainEqual({ code, status }); + } + }); + + it("leave the table's other rows to keep a resent request unknown", () => { + expect( + refusedBeforeWriteRows() + .filter(({ code }) => !Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, code)) + .map(({ code }) => code), + ).toEqual([ + "IDEMPOTENT_REQUEST_MISMATCH", + "RATE_LIMIT_UNAVAILABLE", + "RATE_LIMIT_INCOMPATIBLE", + ]); + }); + + // The failure the binding builds from each answer: kind from + // envelopeFailureReading, effect from envelopeFailureEffect. + it.each([ + ["400 VALIDATION_FAILED with a field list", 400, "VALIDATION_FAILED", [{ field: "name", code: "NOT_BLANK" }], undefined, true], + ["400 VALIDATION_FAILED whose body did not parse", 400, "VALIDATION_FAILED", { cause: "JsonParseException" }, undefined, true], + ["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", undefined, undefined, true], + ["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", undefined, undefined, false], + ["503 RATE_LIMIT_UNAVAILABLE", 503, "RATE_LIMIT_UNAVAILABLE", undefined, undefined, false], + ["a code the operation declared", 400, "WORKLOG_INVALID", undefined, ["WORKLOG_INVALID"], false], + ] as const)("decides whether %s is refused on every attempt", (_label, status, code, details, declared, expected) => { + const error = { code, ...(details === undefined ? {} : { details }) }; + const effect = envelopeFailureEffect(status, error, declared); + expect(effect).toBe("NOT_APPLIED"); + const failure = createFailure( + envelopeFailureReading(status, error).kind, + "ENVELOPE_OPERATION", + 0, + { code, httpStatus: status, effect: "NOT_APPLIED" }, + ); + + expect(isRefusedOnEveryAttempt(failure)).toBe(expected); + }); +});