fix(http): KEYED 명령이 백엔드의 실행 전 거절에 같은 키로 다시 보낸다

문제
V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로
끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본
(2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response
status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는
network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과
어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝
백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로
나중에 다시 보낸다"로 정한다(http-contract.md §2).

고른 방법
- backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE.
- Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면
  AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget·
  MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을
  다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고
  키를 지킨다.

버린 대안
- V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이
  응답 없는 실패 뒤 재시도를 금지한다.
- 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자
  재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시
  보내지 않았다.

위험·한계
- retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다.
- Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다.

검증
- RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on
  the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고
  PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과.
- GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다.
- check:types, lint, check:architecture, test:unit 2,568, test:integration 117,
  test:component 245, tests/features 99 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
This commit is contained in:
DongHyeonka
2026-11-03 22:22:35 +09:00
parent 365d8c3c02
commit c05f41a63e
5 changed files with 105 additions and 9 deletions
+13
View File
@@ -173,6 +173,19 @@ export function envelopeFailureEffect(
: undefined;
}
/**
* §2. The one answer after which the backend asks for the same request again
* with the same key: 503 IDEMPOTENCY_UNAVAILABLE, refused before the command
* ran. A KEYED command may be resent on it automatically (runtime design
* §8.3: only on a known answer that says resending is safe).
*/
export function invitesKeyedResend(
status: number,
error: EnvelopeError,
): boolean {
return status === 503 && error.code === "IDEMPOTENCY_UNAVAILABLE";
}
/**
* Q-6.3-3b. A gateway 5xx/408/425 is a server outage, not a contract breach:
* it keeps the SERVER_FAILURE retry rule.
+21 -7
View File
@@ -48,6 +48,7 @@ import { parseRetryAfterDelay } from "../platform/retry-after.ts";
import {
envelopeFailureEffect,
idempotencyRefusalReason,
invitesKeyedResend,
readFailureEnvelope,
readSuccessEnvelope,
type IdempotencyRefusalReason,
@@ -1097,13 +1098,14 @@ export function createContractHttpExecutor(
return terminalOutcomeFor("ADMISSION");
}
if (
outcome.retryHint &&
// Q-6.3-7. An answer that says the command may already be applied
// is not replayed; reconciliation owns it from here.
outcome.certainty !== "MAYBE_APPLIED" &&
outcome.certainty !== "APPLIED_CONFIRMED" &&
retryIndex < retryCeiling &&
isRetryableSemantics(contract.retrySemantics)
(outcome.keyedResend === true ||
(outcome.retryHint &&
// Q-6.3-7. An answer that says the command may already be
// applied is not replayed; reconciliation owns it from here.
outcome.certainty !== "MAYBE_APPLIED" &&
outcome.certainty !== "APPLIED_CONFIRMED" &&
isRetryableSemantics(contract.retrySemantics))) &&
retryIndex < retryCeiling
) {
const delay = retryDelayFor(outcome.retryAfterMs, retryIndex, random);
if (delay !== null && delay < remaining() && admitRetry()) {
@@ -1214,6 +1216,12 @@ type AdmissionOutcome<Value, Problem> = Readonly<{
retryHint: boolean;
retryAfterMs: number | null;
diagnosticReason?: HttpDiagnosticReason;
/**
* §8.3. The server refused this KEYED command before it ran and asked for
* the same request with the same key. The certainty stays MAYBE_APPLIED so
* an exhausted resend still keeps the key.
*/
keyedResend?: true;
}>;
/**
@@ -1678,6 +1686,7 @@ async function admitProblem<Input, WireOutput, Problem>(
let validated: ValidatorInvocation<Problem>;
let backendEffect: "NOT_APPLIED" | "MAYBE_APPLIED" | undefined;
let refusalReason: IdempotencyRefusalReason | undefined;
let keyedResend = false;
if (enveloped) {
const framed = readFailureEnvelope(decoded.value);
validated = framed.ok
@@ -1686,6 +1695,10 @@ async function admitProblem<Input, WireOutput, Problem>(
if (framed.ok) {
backendEffect = envelopeFailureEffect(status, framed.value);
refusalReason = idempotencyRefusalReason(framed.value.code, status);
keyedResend =
isCommand &&
contract.retrySemantics === "KEYED" &&
invitesKeyedResend(status, framed.value);
}
} else {
validated = invokeValidator(contract.problemValidator, decoded.value);
@@ -1737,6 +1750,7 @@ async function admitProblem<Input, WireOutput, Problem>(
: refusalReason === undefined
? {}
: { diagnosticReason: refusalReason }),
...(keyedResend ? { keyedResend: true as const } : {}),
});
}