From 84effd0cd8e762cad77c3c723c4884dfee7aa4d0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:49:50 +0900 Subject: [PATCH] docs(http): compare KEYED retry, Retry-After and timeout rules per transport (03-06) V3, the V2 client and Browser RPC give the same policy names different behaviour. One table in the backend contract doc now states each rule with its code location, and the V2 timeoutMs option says it is not a ceiling. Also notes that an exposed X-Correlation-ID becomes AppFailure.requestId. Co-Authored-By: Claude Opus 5.5 --- .../backend-api-and-server-state-contract.md | 19 ++++++++++++++++++- src/adapters/http/client.ts | 5 +++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 95d45cac..c209ef03 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -253,7 +253,9 @@ Cross-origin bearer provider 최소 CORS: - exact allow-origin 목록과 bounded preflight cache - `Authorization`, `Content-Type`, `Idempotency-Key`, `X-Correlation-ID`, 향후 `If-None-Match`, `If-Match` 허용 -- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose +- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose. + `X-Correlation-ID`를 expose하면 V3 실패의 `AppFailure.requestId`가 된다 + (`src/adapters/http/feature-http-binding.ts`) - redirect login page, HTML error body와 wildcard credential 금지 ## 6. Command와 idempotency @@ -593,6 +595,21 @@ query invalidate hint로만 쓸지 operation별 reducer contract가 필요하다 - rate limit key는 principal/tenant/operation과 abuse policy에 binding하며 raw credential/IP를 metric label에 넣지 않는다. +### 16.1 전송별 재시도·타임아웃 규칙 (2026-09-25 코드 기준) + +같은 이름의 정책이라도 전송마다 동작이 다르다. operation을 다른 전송으로 옮기면 +이 표로 동작 변화를 확인한다. + +| 규칙 | V3 contract executor (기본 경로) | V2 client (기본 조합에 없음) | Browser RPC | +|---|---|---|---| +| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | 네트워크·타임아웃·429·408/425/502/503/504 뒤 같은 키로 다시 보낸다. 전송 여부를 보지 않는다 (`src/adapters/http/retry-policy.ts` `shouldRetry`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) | +| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | `MAX_RETRY_ATTEMPTS`, 기본 2 (`client.ts` `maxRetryAttempts`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) | +| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | 30초를 넘으면 재시도하지 않는다. 이하면 max(backoff, hint)만큼 기다린다 (`retry-policy.ts`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) | +| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 기본값이다. operation `timeoutMs`가 있으면 그 값을 쓰고, 더 길 수도 있다 (`client.ts` `defaultTimeoutMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 | + +결과 불명 뒤 사용자 재전송은 전송과 무관하게 같은 intent·같은 키를 쓴다 +(`src/presentation/adapters/query/application-query.ts` `resendUnknownEffect`). + ## 17. Observability와 privacy 허용되는 공통 dimension: diff --git a/src/adapters/http/client.ts b/src/adapters/http/client.ts index 8f9a9225..f002ca4c 100644 --- a/src/adapters/http/client.ts +++ b/src/adapters/http/client.ts @@ -106,6 +106,11 @@ export type HttpClientDependencies = Readonly<{ payload: unknown, ) => MappingResult; idempotencyKeyFactory?: () => string; + /** + * Default total deadline for an operation without its own `timeoutMs`. Not a + * ceiling: an operation may set a longer one. V3 treats `REQUEST_TIMEOUT_MS` + * as a ceiling instead (03-06). + */ timeoutMs?: number; maxRetryAttempts?: number; scheduler?: Scheduler;