fix(inbound)!: Retry-After를 레지스트리대로 붙이고 GraphQL 인자 거부를 맞춘다

문제(r8-f1 보고의 범위 밖 1·2, 소유자 답 2026-11-07 "권하는 안대로"):
- web RetryAfterAdvisor 표가 레지스트리 retry_after_seconds 칸의 미러인데
  7개가 빠졌다(DB_UNAVAILABLE 5, DB_SERIALIZATION_FAILURE 1, DB_DEADLOCK
  1, DB_IDLE_IN_TX_TIMEOUT 2, OUTBOX_PUBLISH_FAILED 30,
  JOB_EXECUTOR_REJECTED 5, JOB_TIMEOUT 10). 그래서 DB 일시 실패 응답에
  Retry-After가 없다. 대조하는 테스트가 없었다: advisor 단위 테스트는
  값을 코드마다 손으로 옮겼고, enum·레지스트리 대조 테스트는 category·
  status·retryable만 봤다.
- GraphQL @Argument 값이 파라미터 타입으로 바뀌지 않으면 Spring 인자
  binder가 BindException을 던지는데, 매퍼가 모르는 타입이라
  INTERNAL_ERROR로 가리고 예외째 ERROR로 남긴다. 그 메시지에
  rejected value [...]가 실린다.

고친 것:
- RetryAfterAdvisor 표를 Map.ofEntries로 바꾸고 7개를 채웠다(Map.of는
  10쌍이 상한). OperationalErrorRegistryContractTest(document-contract)에
  OperationalError마다 RetryAfterAdvisor.retryAfterSeconds와 레지스트리
  값이 같은지 보는 테스트를 더했다. 버린 안: advisor가 레지스트리를
  런타임에 읽는 것 — web leaf가 저장소 파일을 읽게 되고 jar에 실리지
  않는다.
- GraphQlWireErrorMapper가 BindException을 IllegalArgumentException과
  같은 "거부된 인자"로 본다: 등록된 매핑이 없으면 BAD_PARAMETER(REQUEST),
  로그는 ServerFailureLog.refused의 WARN 한 줄(타입만). web이 바뀌지 않는
  경로 변수에 답하는 것과 같다.
- 결정 색인 2.3절에 두 결정과 STOMP 필수 header 누락을 ERROR로 두는
  기본값(이유 포함)을 적었다. 업그레이드 안내 B-47·B-48.

위험·한계:
- 응답이 바뀐다: DB 일시 실패 넷에 Retry-After가 생기고, GraphQL 인자
  변환 실패가 INTERNAL_ERROR → BAD_PARAMETER.
- 대조 테스트는 OperationalError 코드만 본다. 다른 leaf의 코드는
  RetryAfterHint로 자기 값을 말한다(대조 대상 아님).
- BindException은 binder가 인자 변환을 모아 던질 때만 온다. @Valid
  검증(ConstraintViolationException)은 이 leaf에 Bean Validation이 없어
  다루지 않았다.

검증(desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f1-logs/round2/):
- RED(5f6a86d7 + 테스트만): 11건 실패. advisor 7개 코드 empty, 레지스트리
  대조 1건, GraphQL 3건(INTERNAL_ERROR, ERROR "graphql failure masked" +
  BindException "rejected value [alice@example.com]"). round2/red.log
- 이 트리(ca44d3fc): :ci :verifyDependencyLocks --warning-mode=fail rc=0
  (web test 341, graphql test 404, app-bootstrap test 225 skip 4 이전부터,
  architectureTest, verifyGraphQlApiSurface 포함)
- :sample-portfolio:check :sample-portfolio:qualityCheck rc=0
- :verifyStrictLaneStages --dry-run 두 빌드 rc=0, -p optional-platforms ci rc=0
- web·graphql systemTest, :conditionalTransportQualification rc=0
- :app-bootstrap:documentContractTest rc=0(67)
- web·graphql·app-bootstrap testQualityCheck rc=0
- scripts/verify-compose-profile-contracts.sh rc=0, scripts/check-work-docs.py rc=0

BREAKING CHANGE: DB_UNAVAILABLE(5초)·DB_SERIALIZATION_FAILURE(1초)·
DB_DEADLOCK(1초)·DB_IDLE_IN_TX_TIMEOUT(2초) 응답에 Retry-After가 붙고,
GraphQL @Argument 변환 실패는 INTERNAL_ERROR 대신 BAD_PARAMETER로 답한다.
업그레이드 안내 B-47·B-48.
Refs: docs/work/reference/decisions.md 2.3절, docs/upgrade/2026-11-maturity-review.md B-47, B-48
This commit is contained in:
DongHyeonka
2026-11-07 01:38:36 +09:00
parent 5f6a86d7b7
commit ef8ef170e8
13 changed files with 277 additions and 38 deletions
+4 -2
View File
@@ -526,8 +526,10 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
(web-advanced `ADMISSION_REFUSED` = 1초).
- `IDEMPOTENT_IN_FLIGHT` 는 2초: 기본 processing lease(30s)보다 짧아 첫 시도가 끝날 수 있는 동안
같은 키로 다시 묻게 한다. 근거와 클라이언트 행동은 `docs/web/http-contract.md` §2.
- `LOCK_ACQUISITION_TIMEOUT` 은 1초(레지스트리 값). 표가 `Map.of` 의 상한인 10쌍을 채웠다. 더 넣으려면
`Map.ofEntries` 로 바꾼다.
- 표는 레지스트리의 `retry_after_seconds` 가 있는 행마다 한 줄이다(`LOCK_ACQUISITION_TIMEOUT` 1초, DB·outbox·job
코드 포함). `OperationalErrorRegistryContractTest`(app-bootstrap document-contract)가 `OperationalError` 마다 표와
레지스트리를 대조한다. 전에는 대조가 없어 7개가 빠진 채였다(advisor 단위 테스트는 값을 코드마다 손으로 옮겨
적었고, enum·레지스트리 대조 테스트는 category·status·retryable 만 봤다).
---
@@ -11,31 +11,36 @@ import java.util.OptionalInt;
*/
public final class RetryAfterAdvisor {
/** Per-code {@code Retry-After} values (seconds). */
/**
* Per-code {@code Retry-After} values (seconds): the registry's {@code retry_after_seconds}
* column, every row that has one. {@code OperationalErrorRegistryContractTest} (app-bootstrap,
* document-contract) fails when a code here and its registry row differ.
*/
private static final Map<String, Integer> RETRY_AFTER_SECONDS =
Map.of(
"RATE_LIMIT_EXCEEDED",
1,
Map.ofEntries(
Map.entry("RATE_LIMIT_EXCEEDED", 1),
// The application's value, which the processing-lease check also reads: the resend
// arrives while the first attempt can still finish. docs/web/http-contract.md §2.
"IDEMPOTENT_IN_FLIGHT",
Math.toIntExact(IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER.toSeconds()),
"AUTH_KID_UNKNOWN",
5,
"AUTH_JWKS_UNAVAILABLE",
30,
"DEPENDENCY_TIMEOUT",
2,
"DEPENDENCY_CONNECT_FAILED",
2,
"DEPENDENCY_DNS_FAILED",
5,
"DEPENDENCY_5XX_SERVER",
2,
"DEPENDENCY_CIRCUIT_OPEN",
10,
"LOCK_ACQUISITION_TIMEOUT",
1);
Map.entry(
"IDEMPOTENT_IN_FLIGHT",
Math.toIntExact(IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER.toSeconds())),
Map.entry("AUTH_KID_UNKNOWN", 5),
Map.entry("AUTH_JWKS_UNAVAILABLE", 30),
Map.entry("DEPENDENCY_TIMEOUT", 2),
Map.entry("DEPENDENCY_CONNECT_FAILED", 2),
Map.entry("DEPENDENCY_DNS_FAILED", 5),
Map.entry("DEPENDENCY_5XX_SERVER", 2),
Map.entry("DEPENDENCY_CIRCUIT_OPEN", 10),
Map.entry("LOCK_ACQUISITION_TIMEOUT", 1),
Map.entry("DB_UNAVAILABLE", 5),
Map.entry("DB_SERIALIZATION_FAILURE", 1),
Map.entry("DB_DEADLOCK", 1),
Map.entry("DB_IDLE_IN_TX_TIMEOUT", 2),
// Never on an HTTP response today (an async failure's 500 is a placeholder), kept so the
// table and the registry stay one-to-one.
Map.entry("OUTBOX_PUBLISH_FAILED", 30),
Map.entry("JOB_EXECUTOR_REJECTED", 5),
Map.entry("JOB_TIMEOUT", 10));
private RetryAfterAdvisor() {}
@@ -5,6 +5,8 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.shared.error.OperationalError;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
class RetryAfterAdvisorTest {
@@ -103,4 +105,21 @@ class RetryAfterAdvisorTest {
assertThat(RetryAfterAdvisor.retryAfterSeconds(OperationalError.LOCK_ACQUISITION_TIMEOUT))
.hasValue(1);
}
// docs/registries/error-codes.yaml retry_after_seconds of the database, outbox and job rows.
// RetryAfterAdvisor's table once left these out; the registry contract test (app-bootstrap
// OperationalErrorRegistryContractTest) now compares every code.
@ParameterizedTest
@CsvSource({
"DB_UNAVAILABLE, 5",
"DB_SERIALIZATION_FAILURE, 1",
"DB_DEADLOCK, 1",
"DB_IDLE_IN_TX_TIMEOUT, 2",
"OUTBOX_PUBLISH_FAILED, 30",
"JOB_EXECUTOR_REJECTED, 5",
"JOB_TIMEOUT, 10"
})
void aRetryableCodeWithARegisteredDelayHasThatRetryAfter(OperationalError code, int seconds) {
assertThat(RetryAfterAdvisor.retryAfterSeconds(code)).hasValue(seconds);
}
}