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;