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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:49:50 +09:00
co-authored by Claude Opus 5.5
parent e7f376ac83
commit 84effd0cd8
2 changed files with 23 additions and 1 deletions
@@ -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:
+5
View File
@@ -106,6 +106,11 @@ export type HttpClientDependencies = Readonly<{
payload: unknown,
) => MappingResult<unknown>;
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;