Merge pull request 'docs(runbooks): runbook 신호를 지금 코드가 내는 응답·로그·지표로 고친다' (#30) from claude/r9-a-runbooks into main
main / build-logic (push) Successful in 2m3s
main / main (push) Successful in 26m51s
main / configuration-cache (push) Successful in 2m5s
main / links (push) Successful in 11s
main / vulnerabilities (push) Successful in 1m4s
main / http3-experimental (push) Successful in 57s
main / jpa-postgresql (16) (push) Skipped
main / jpa-postgresql (17) (push) Skipped
main / jpa-postgresql (18) (push) Skipped
main / httpclient-transport (push) Skipped
main / redis-topology (push) Skipped
main / fileserver-nfs-ambiguity (push) Skipped
main / notification-chaos (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / performance (push) Skipped
main / object-storage-aws (push) Skipped
main / compose-smoke (push) Skipped
main / done (push) Skipped

This commit was merged in pull request #30.
This commit is contained in:
2026-11-13 03:25:45 +00:00
35 changed files with 255 additions and 372 deletions
+2
View File
@@ -191,6 +191,8 @@ errors:
# ============================================================
# source: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL"
# 지금 이 코드는 JWT decoder를 만들지 못할 때(issuer discovery 4xx·issuer 불일치·jwks_uri 없음) 나온다. 공개 경로
# 설정 오류는 이 코드를 내지 않는다(runbook auth-public-path-misconfiguration.md).
- code: INTERNAL_AUTH_MISCONFIGURATION
category: INTERNAL
http_status: 500
+2 -2
View File
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_AUDIENCE_MISMATCH]
severity: P2
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -17,7 +17,7 @@ status: 초안
## 진단
- 토큰의 `aud` 클레임 값을 본다.
- 클라이언트가 어떤 audience로 token을 요청하는지 클라이언트 설정에서 본다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
- 설정된 `app.security.audience`(`APP_SECURITY_JWT_AUDIENCE`, 쉼표로 구분)와 비교한다. 토큰은 그중 하나 이상을
담아야 한다.
+8 -6
View File
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_ISSUER_MISMATCH]
severity: P2
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -13,22 +13,24 @@ status: 초안
## 증상
- HTTP 401, `error.code=AUTH_ISSUER_MISMATCH`.
- 토큰의 `iss` 클레임이 설정된 발급자와 다르다.
- WARN 로그 줄 `security failure: code=AUTH_ISSUER_MISMATCH category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`).
## 진단
- 토큰의 `iss`를 `spring.security.oauth2.resourceserver.jwt.issuer-uri`와 비교한다.
- IdP 환경이 바뀌었는지 확인한다.
- 검증기가 비교하는 값은 `app.security.issuer-uri`(env `APP_SECURITY_JWT_ISSUER`)다(`config/security.yml` → `JwtDecoderConfig`). 같은 env가 `spring.security.oauth2.resourceserver.jwt.issuer-uri`도 채우지만 decoder는 그 키를 읽지 않는다.
- 거부된 token의 `iss`를 클라이언트 쪽에서 디코딩해 `APP_SECURITY_JWT_ISSUER`와 견준다. 흔한 원인은 hostname(내부·외부 주소), realm 이름, 끝의 `/` 차이다. IdP discovery의 `issuer`와 설정값이 다르면 이 401이 아니라 decoder를 만들지 못한 500 `INTERNAL_AUTH_MISCONFIGURATION`이다(`docs/runbooks/auth-public-path-misconfiguration.md`).
- 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다.
## 조치
- IdP를 옮겼으면 issuer 설정을 고친다.
- 예상하지 않은 발급자의 토큰은 계속 거부한다.
- IdP를 옮겼으면 `APP_SECURITY_JWT_ISSUER`를 고친다.
- 예상하지 않은 발급자의 token은 계속 거부한다.
## 에스컬레이션
- 예상하지 않은 발급자를 찾으면 플랫폼 보안 팀에 넘긴다.
---
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+5 -4
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [AUTH_JWKS_UNAVAILABLE]
severity: P1
owner: oncall
last_updated: 2026-11-06
last_updated: 2026-11-13
status: 초안
---
@@ -15,16 +15,17 @@ status: 초안
- HTTP 503, `error.code=AUTH_JWKS_UNAVAILABLE`.
- ERROR 로그 줄 `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
(logger `AuthErrorResponseWriter`).
- 인증이 모두 실패하고, JWKS 새로 고침도 실패한다.
- token을 실은 요청이 모두 이 503으로 답하고, 응답에는 `Retry-After: 30`이 붙는다.
## 진단
- IdP의 JWKS 엔드포인트 상태를 본다: `curl -sf https://<idp-host>/.well-known/jwks.json`
- 앱이 읽는 JWKS 주소는 issuer discovery로 정해진다: `app.security.issuer-uri`(`APP_SECURITY_JWT_ISSUER`)의 `/.well-known/openid-configuration`에 있는 `jwks_uri`다. 앱이 도는 곳에서 그 두 주소를 `curl -sf`로 읽는다.
- 앱 pod에서 IdP까지 네트워크가 닿는지 확인한다.
## 조치
- 캐시된 JWKS로 버틸 수단이 있으면 쓴다.
- 첫 검증에 성공한 뒤에는 키를 라이브러리(Nimbus) 기본 캐시에 두므로, IdP가 잠깐 멈춰도 캐시가 살아 있는 동안은 검증이 된다. 앱에는 캐시 시간·새로 고침 손잡이가 없다.
- 첫 검증 전이거나 캐시가 지난 뒤 IdP에 닿지 않으면 이 503이 난다. decoder는 다음 요청에서 다시 시도하므로 IdP가 돌아오면 저절로 회복한다.
- IdP 팀과 복구를 맞춘다.
## 에스컬레이션
+8 -6
View File
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_KID_UNKNOWN]
severity: P2
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -12,23 +12,25 @@ status: 초안
## 증상
- HTTP 401, `error.code=AUTH_KID_UNKNOWN`, `retryable=true`.
- 토큰 헤더의 `kid`가 캐시된 JWKS에 없다.
- HTTP 401, `error.code=AUTH_KID_UNKNOWN`, `retryable=true`, `Retry-After: 5`.
- WARN 로그 줄 `security failure: code=AUTH_KID_UNKNOWN category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`).
- token 헤더의 `kid`가 앱이 읽은 JWKS에 없다.
## 진단
- 최근에 IdP 키 교체가 있었는지 확인한다.
- JWKS 캐시 TTL과 새로 고침 시점을 확인한다.
- JWKS는 issuer discovery의 `jwks_uri`에서 읽는다(`app.security.issuer-uri`, `APP_SECURITY_JWT_ISSUER`). 그 주소에 새 kid가 있는지 본다. 앱에는 JWKS 캐시 TTL·새로 고침 손잡이가 없다(라이브러리 기본 캐시).
## 조치
- JWKS 캐시를 강제로 새로 고친다.
- 새 키가 IdP JWKS 엔드포인트에 게시됐는지 확인한다.
- 새 키가 IdP JWKS에 게시됐는지 확인한다.
- 모르는 kid가 오면 decoder가 JWKS를 다시 받으므로, 새 키가 게시되면 재시작 없이 다음 요청부터 통과한다. 게시됐는데도 계속 이 401이면 앱이 읽는 `jwks_uri`가 IdP가 키를 게시한 곳과 같은지(앞단 캐시·다른 realm) 본다.
## 에스컬레이션
- 10분이 지나도 새 kid가 JWKS에 나타나지 않으면 IdP 팀에 넘긴다.
---
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
@@ -1,10 +1,10 @@
---
title: Runbook — INTERNAL_AUTH_MISCONFIGURATION (공개 경로 설정 오류)
title: Runbook — INTERNAL_AUTH_MISCONFIGURATION (JWT decoder 설정 오류)
category: INTERNAL
error_codes: [INTERNAL_AUTH_MISCONFIGURATION]
severity: P1
owner: oncall
last_updated: 2026-11-07
last_updated: 2026-11-13
status: 초안
---
@@ -15,22 +15,23 @@ status: 초안
- HTTP 500, `error.code=INTERNAL_AUTH_MISCONFIGURATION`.
- ERROR 로그 줄 `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
(logger `AuthErrorResponseWriter`).
- 실행 중에 보안 필터 설정 오류가 드러났다.
- 이 코드는 JWT decoder를 만들 수 없을 때 나온다: issuer metadata가 망가졌거나 네트워크 문제가 아닌 이유로 decoder 초기화가 실패했다(`JwtDecoderConfig` → `SecurityErrorClassifier`). decoder는 첫 token을 검증할 때 만들어지므로 기동은 성공하고, token을 실은 요청마다 이 500이 난다.
- 공개 경로 설정 오류는 이 코드를 내지 않는다. 잘못 연 공개 경로는 오류 없이 열리므로 스냅숏 검사(아래)로만 잡힌다.
## 진단
- CI의 `verifyPublicPathSnapshot` 결과를 본다.
- `SecurityConfig`와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근
변경을 본다.
- 먼저 issuer 설정을 본다. 앱이 도는 곳에서 `<APP_SECURITY_JWT_ISSUER>/.well-known/openid-configuration`을 받는다. 이 500은 discovery 후보 주소가 모두 4xx(없는 realm, 틀린 경로)이거나, 응답의 `issuer`가 `APP_SECURITY_JWT_ISSUER`와 글자까지 다르거나(끝의 `/` 포함), `jwks_uri`가 없을 때다.
- 연결 실패·5xx·JSON이 아닌 응답이면 이 코드가 아니라 503 `AUTH_JWKS_UNAVAILABLE`이다(`docs/runbooks/auth-jwks-unavailable.md`).
- 공개 경로를 의심하면 CI의 `verifyPublicPathSnapshot` 결과와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근 변경을 본다.
## 조치
- 잘못된 공개 경로 변경을 되돌린다.
- 저장소 루트에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
- `APP_SECURITY_JWT_ISSUER`를 IdP discovery의 `issuer`와 같게 고쳐 다시 배포한다. 설정은 기동 때 읽는다.
- 잘못된 공개 경로 변경을 되돌린다. 저장소 루트에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
## 에스컬레이션
- P1 즉시: 설정 오류로 인증을 건너뛸 수 있으면.
- P1 즉시: token을 싣는 모든 요청이 500이다. 공개 경로를 잘못 열어 인증을 건너뛸 수 있을 때도 P1이다.
---
+2 -2
View File
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_TOKEN_EXPIRED]
severity: P3
owner: oncall
last_updated: 2026-11-07
last_updated: 2026-11-13
status: 초안
---
@@ -17,7 +17,7 @@ status: 초안
## 진단
- `exp` 클레임과 서버 시계를 비교한다.
- 서버 시계와 token 발급 호스트의 시계를 비교한다. token의 `exp`는 클라이언트 쪽에서 재현해 본다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다.
- 토큰을 발급하는 호스트의 NTP 동기화를 확인한다.
## 조치
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_TOKEN_INVALID_SIGNATURE]
severity: P1
owner: oncall
last_updated: 2026-11-06
last_updated: 2026-11-13
status: 초안
---
@@ -24,7 +24,7 @@ status: 초안
## 조치
- JWKS의 키 ID가 토큰 헤더와 맞는지 확인한다.
- IdP가 서명에 쓰는 키가 JWKS(`jwks_uri`)에 게시됐는지 확인한다. token 헤더의 `kid`는 클라이언트 쪽에서 재현해 본다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다.
- 위조가 의심되면 보안 팀에 알린다.
## 에스컬레이션
+9 -8
View File
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_TOKEN_MALFORMED, INVALID_TOKEN]
severity: P3
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -12,22 +12,23 @@ status: 초안
## 증상
- HTTP 401 응답, `error.code=AUTH_TOKEN_MALFORMED`.
- 토큰은 있지만 JWT로 파싱되지 않는다(세 부분이 아님, base64가 아님 등).
- HTTP 401, `error.code=AUTH_TOKEN_MALFORMED`, `WWW-Authenticate: Bearer error="invalid_token"`.
- WARN 로그 줄 `security failure: code=AUTH_TOKEN_MALFORMED category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`).
- 분류기가 더 좁은 코드로 가르지 못한 token 실패도 이 코드다(`SecurityErrorClassifier`).
## 진단
- 로그에서 Authorization 헤더 원문을 본다.
- 토큰을 만드는 도구에 버그가 있는지 확인한다.
- 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
- 같은 `path=`·시각에 몰리는지 보고 어느 클라이언트인지 앞단 접근 로그로 찾는다.
## 조치
- 잘못된 토큰이 어디서 오는지 찾는다.
- 클라이언트의 토큰 생성을 고친다.
- 클라이언트의 token 생성·전달(접두어 `Bearer `, 잘린 값)을 고친다.
## 에스컬레이션
- 급증이 인프라 문제를 가리키면 넘긴다.
- 급증이 인프라 문제(프록시가 헤더를 바꿈 등)를 가리키면 넘긴다.
---
+5 -5
View File
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_TOKEN_MISSING, UNAUTHENTICATED]
severity: P3
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -12,13 +12,12 @@ status: 초안
## 증상
- HTTP 401 응답, `error.code=AUTH_TOKEN_MISSING`.
- 클라이언트가 Authorization 헤더나 Bearer 토큰을 보내지 않았다.
- HTTP 401, `error.code=AUTH_TOKEN_MISSING`, `WWW-Authenticate: Bearer`.
- WARN 로그 줄 `security failure: code=AUTH_TOKEN_MISSING category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`). 보안 chain이 거부한 요청은 요청 로그(`http_request …`)에는 없다.
## 진단
- 요청 로그에서 Authorization 헤더가 빠졌는지 본다.
- 클라이언트 SDK 설정을 확인한다.
- 헤더가 있었는지는 앱 로그에 없다. 앞단 프록시·gateway 설정과 클라이언트 SDK 설정을 본다.
## 조치
@@ -29,6 +28,7 @@ status: 초안
- 넓게 퍼졌거나 중요한 업무 흐름에 영향이 있으면 넘긴다.
---
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+15 -47
View File
@@ -4,65 +4,33 @@ category: AUTH
error_codes: [AUTH_TOKEN_EXPIRED, AUTH_KID_UNKNOWN, AUTH_JWKS_UNAVAILABLE, AUTH_TOKEN_INVALID_SIGNATURE]
severity: P1
owner: oncall
last_updated: 2026-05-22
last_updated: 2026-11-13
status: 초안
---
# Runbook: JWT key rotation 시 인증 실패 spike
## 1. Trigger
## 증상
이 runbook은 다음 alert가 울리면 쓴다.
- 401이 몰리고 코드가 `AUTH_KID_UNKNOWN`(retryable, `Retry-After: 5`)·`AUTH_TOKEN_INVALID_SIGNATURE`·`AUTH_TOKEN_EXPIRED`, 또는 503 `AUTH_JWKS_UNAVAILABLE`(`Retry-After: 30`)이다.
- WARN 로그 줄 `security failure: code=<CODE> category=<CATEGORY> method=… path=…`(logger `AuthErrorResponseWriter`). 4xx는 WARN, 5xx는 ERROR다. `code=`·`category=`는 메시지 글자이고 구조화 칸이 아니다. `AUTH_JWKS_UNAVAILABLE`의 category는 `TRANSIENT_DEPENDENCY`다.
- 이 템플릿은 경보 규칙·대시보드를 두지 않는다. 서비스가 위 `security failure` 줄의 `code=`·`path=`나 `http.server.requests`의 tag `status`로 만든다. 보안 chain이 거부한 요청은 handler가 없어 tag `uri`가 `UNKNOWN`이니 경로로 가르지 못한다. 이 경로의 로그에는 `dependency_name` 칸이 없다.
- alert name: `auth_401_error_rate_high` 또는 `jwks_refresh_failure_spike`
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `runbook_link`, `dependency_name`
- 임계: 401 error rate > 5% 5분 지속 OR JWKS refresh failure count > 10건/분
## 진단
## 2. First Response (5분 이내)
- JWKS 주소는 issuer discovery로 정해진다: `app.security.issuer-uri`(`APP_SECURITY_JWT_ISSUER`)의 `/.well-known/openid-configuration`에 있는 `jwks_uri`다(`JwtDecoderConfig`). 그 주소를 앱이 도는 곳에서 `curl -sf`로 읽어 새 kid가 있는지 본다.
- JWKS 캐시 TTL·강제 새로 고침 손잡이는 없다. decoder는 처음 쓸 때 discovery를 하고, 실패하면 다음 요청에서 다시 한다. 한 번 성공한 뒤에는 라이브러리 기본 캐시로 `jwks_uri`를 다시 읽는다.
- 시계 차이 허용은 60초다(`JwtDecoderConfig`). 만료가 몰리면 발급 호스트의 NTP를 본다.
- 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
### Step 1 — 확인
1. JWKS endpoint health check: `curl -sf https://<idp-host>/.well-known/jwks.json | jq '.keys | length'`
2. log query에서 `error.code` 분포 확인 — `AUTH_KID_UNKNOWN` 비중이 높으면 rotation 원인 강력 시사
3. IdP rotation schedule 확인 (직전 24h 내 rotation 이벤트가 있었는지)
## 조치
### Step 2 — 임시 격리
- JWKS cache TTL을 짧게(예: 60s) 강제하여 새 kid 전파 가속
- 새 kid가 JWKS에 publish되어 있는지 확인. 누락이면 IdP에 republish 요청
- IdP가 새 키를 게시하기 전에 그 키로 서명한 token을 냈으면 IdP 쪽에서 「게시 → 대기 → 전환」 순서를 지킨다. 앱 쪽 kid 허용 목록은 없다.
- 모르는 kid가 오면 decoder가 JWKS를 다시 받으므로 키 교체에 재시작은 필요 없다. 재시작이 필요한 경우는 IdP가 `jwks_uri`를 옮겼을 때뿐이다. discovery는 decoder를 처음 만들 때 한 번만 읽기 때문이다(`JwtDecoderConfig`).
## 3. Diagnosis
## 에스컬레이션
- log query (Loki/CloudWatch): `{service="auth"} | error.category="AUTH" | dependency_name="jwks-endpoint"`
- metric panel: `auth_jwks_cache_hit_ratio`, `auth_jwks_refresh_failure_total`, `auth_kid_unknown_total`
- trace: 실패한 request 1건에서 `traceId` 추출 → IdP outbound span 확인
- 가능한 원인:
- 새 kid가 JWKS에 publish되기 전 token 발급 → 24h overlap window 안에 있는지 확인
- JWKS endpoint 장애 (5xx, timeout) → IdP status page 확인
- 시계 skew로 인한 만료 오판 → NTP sync 상태 확인
## 4. Mitigation
- 단기: old kid를 임시 재허용 (rollback). overlap window를 48h로 일시 확장
- IdP에 새 JWKS publish 재시도 요청
- 장기: rotation 절차에 "publish → 24h 대기 → switch" 단계 강제. observability에 kid 분포 metric 추가
## 5. Escalation
- P2 → P1 격상 조건: 401 error rate > 20% 또는 다중 tenant에 동시 발생
- 다음 on-call로 page: 10분 내 회복 안 되면 IdP team 또는 platform-security team page
## 6. Recovery / Verification
- 회복 확인 metric: `auth_401_error_rate < 1%` 5분 지속, `AUTH_KID_UNKNOWN` 건수 0
- post-incident:
- rotation 절차 RCA 작성
- JWKS overlap window 정책 문서 업데이트
- kid 분포 dashboard 영구화
## 7. Related
- error-codes.yaml rows: `AUTH_TOKEN_EXPIRED`, `AUTH_KID_UNKNOWN`, `AUTH_JWKS_UNAVAILABLE`, `AUTH_TOKEN_INVALID_SIGNATURE`
- metrics.yaml: `auth_jwks_cache_hit_ratio`, `auth_jwks_refresh_failure_total`
- 관련 branch: [[feature-security-operational-baseline]]
- 10분 안에 회복하지 않으면 IdP 팀에 넘긴다.
---
+14 -50
View File
@@ -4,68 +4,32 @@ category: AUTHZ
error_codes: [AUTHZ_INSUFFICIENT_PERMISSION, AUTHZ_TENANT_MISMATCH]
severity: P2
owner: oncall
last_updated: 2026-05-22
last_updated: 2026-11-13
status: 초안
---
# Runbook: cross-tenant 접근 시도 감지
## 1. Trigger
## 증상
이 runbook은 다음 alert가 울리면 쓴다.
- `AUTHZ_TENANT_MISMATCH`는 enum 상수(`OperationalError`)와 registry 행이 있지만 내는 코드가 없다.
- 실제 동작: 남의 tenant·소유자의 객체는 없는 것과 같은 404다(예: durable operation `OPERATION_NOT_FOUND`, `DurableOperationAccessPolicy`). 파일 서버는 403 `ACCESS_DENIED`, GraphQL은 HTTP 200 본문의 오류 `RESOURCE_NOT_FOUND`(category AUTHORIZATION)다. tenant를 요청 입력으로 보낸 요청은 서비스가 요청 경로에서 web-advanced `WebSecurityContextBridge.resolve(authentication, requestInput)`(요청 입력을 받는 두 인자 판)을 부를 때만 403 `TENANT_INPUT_UNTRUSTED`가 된다. 한 인자 `resolve`와 기본 구성은 그 검사를 하지 않아 그런 header는 무시된다.
- 이 거부들에는 코드를 가진 전용 WARN 줄이 없다(4xx carrier, `ServerFailureLog`). web은 요청 로그 줄 `http_request … status=<404 또는 파일 서버 403>`(MDC `user_principal` 포함)과 `http.server.requests`의 `status`가 남지만 평범한 404·403과 구별되지 않는다. GraphQL 거부는 HTTP 200이라 status로도 보이지 않는다. 시도를 세려면 서비스가 판정하는 자리에서 WARN 한 줄과 지표를 더해야 한다.
- alert name: `authz_cross_tenant_violation` 또는 `authz_403_spike`
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `principal_id_pseudonymized`, `tenant_id`, `runbook_link`
- 임계:
- P2: 403 with `error.code=AUTHZ_TENANT_MISMATCH` > 10건/5분
- P1 격상: 동일 principal에서 3개 이상 tenant 시도 OR 5분 내 100건 초과
## 진단
## 2. First Response (5분 이내)
- 서비스가 그 신호를 더했다면 그 WARN 줄의 MDC `request_id`로 같은 요청의 `http_request` 줄을 찾고, 그 줄의 MDC `user_principal`(가명화한 사용자 식별자)로 같은 호출자를 묶는다. `user_principal`은 `RequestLoggingFilter`가 요청 로그 줄을 쓸 때만 MDC에 두므로 handler 안에서 남긴 줄에는 없다. 서비스 WARN 줄에 직접 실으려면 `UserPrincipalPseudonymizerPort`로 가명 값을 만든다. 원본 사용자 식별자·IP·토큰 claim은 로그에 없고 남기지 않는다.
- `trace_id`로 요청 흐름을 따라간다. tenant는 인증 정보에서만 오고 요청 값에서 오지 않으므로(`docs/manual/07-authorization.md` 「객체 단위 권한」), 비교할 「요청의 tenant」는 없다.
- 가능한 원인: 계정 탈취, 다른 tenant의 id를 쓰는 클라이언트 버그, 여러 tenant를 다뤄야 하는 관리 작업의 권한 누락.
### Step 1 — 확인
1. log query로 위반 principal 식별 (pseudonymized): `error.code=AUTHZ_TENANT_MISMATCH`
2. principal의 정상 tenant scope 확인 (IdP claim 또는 entitlement table)
3. `CROSS_TENANT_ADMIN` capability 보유 여부 확인 — 보유자라면 false positive 가능성
## 조치
### Step 2 — 임시 격리
- 명백한 위반 패턴이면 principal session 강제 만료 (token revocation list 추가)
- security incident channel 통보 (`#sec-incident`)
- 위반 request의 source IP / user-agent 기록
- 반복하는 호출자는 gateway·IdP에서 막는다. 이 템플릿에는 token 폐기 목록이 없다(JWT 모드는 상태가 없다. Redis 세션 모드는 세션을 지우면 끊긴다).
- 여러 tenant를 다루는 관리 작업이 거부되면 그 유스케이스의 권한 판정을 본다. 관리 경로는 관리 권한으로 따로 판정한다(예: 파일 서버 `ForceDeleteFileApplicationUseCase`의 `file:admin`과 `FileOperation.ADMIN_FORCE_DELETE`). `@UseCaseCapability(crossTenantAdmin = true)`는 ArchUnit·리뷰가 보는 선언이라 실행 시 접근을 열지 않는다(`docs/registries/capabilities.yaml`).
## 3. Diagnosis
## 에스컬레이션
- log query: `{service="api"} | error.category="AUTHZ" | principal_id_pseudonymized="<hash>"`
- metric panel: `authz_denied_total{reason="tenant_mismatch"}`, `authz_principal_tenant_distribution`
- trace: 위반 request의 `traceId`로 호출 chain 확인. token claim의 `tenant_id`와 요청 path의 `tenant_id` 비교
- 가능한 원인:
- account takeover (계정 탈취) → 즉시 session revoke + 비밀번호 reset 요구
- client bug (잘못된 tenant id 전송) → product team에 통보
- 정상 admin operation 누락된 capability → entitlement 보정
## 4. Mitigation
- 단기: principal session revoke, source IP rate-limit 강화
- 위반이 client bug면 client patch release 협조
- 장기: tenant boundary 검증 layer를 controller가 아닌 repository 진입점에서 강제 ([[feature-repository-access-permission-contract]])
## 5. Escalation
- 다음 on-call로 page: 보안 incident channel 즉시 page. 5분 내 security on-call 응답 없으면 CISO escalation
- legal/compliance 통보 필요 여부 판단 (개인정보 noted시)
## 6. Recovery / Verification
- 회복 확인 metric: `AUTHZ_TENANT_MISMATCH` 건수 정상 baseline 복귀
- post-incident:
- account takeover면 forensics 수행 + audit log 보존
- cross-tenant 검증 unit test 추가
- 위반 패턴 detection rule 영구화
## 7. Related
- error-codes.yaml rows: `AUTHZ_INSUFFICIENT_PERMISSION`, `AUTHZ_TENANT_MISMATCH`
- metrics.yaml: `authz_denied_total`, `authz_principal_tenant_distribution`
- 관련 branch: [[feature-tenant-context-policy]], [[feature-repository-access-permission-contract]]
- 계정 탈취가 의심되면 보안 incident로 넘긴다.
---
+8 -6
View File
@@ -4,7 +4,7 @@ category: AUTHZ
error_codes: [AUTHZ_TENANT_MISMATCH]
severity: P1
owner: oncall
last_updated: 2026-11-07
last_updated: 2026-11-13
status: 초안
---
@@ -12,14 +12,16 @@ status: 초안
## 증상
- HTTP 403, `error.code=AUTHZ_TENANT_MISMATCH`.
- 템플릿은 이 코드를 내지 않는다. 다른 테넌트 접근을 판단하는 서비스가 낸다. 403 carrier는 로그 줄 없이
응답하므로(`ServerFailureLog`), 이 runbook으로 시도를 찾으려면 그 서비스가 판단하는 자리에서
`code=AUTHZ_TENANT_MISMATCH`를 남겨야 한다.
- `AUTHZ_TENANT_MISMATCH`는 enum 상수와 registry 행이 있지만 템플릿 코드는 내지 않는다. 템플릿이 정한 규칙은 남의
tenant 객체를 없는 것처럼 404로 답하는 것이다(`docs/manual/07-authorization.md` 「객체 단위 권한」, 실제 신호는
`docs/runbooks/authz-cross-tenant-violation.md`).
- 서비스가 다른 tenant 접근을 403 `AUTHZ_TENANT_MISMATCH`로 따로 답하기로 했을 때만 이 runbook을 쓴다. 403 carrier는
로그 줄 없이 응답하므로(`ServerFailureLog`), 그 서비스가 판단하는 자리에서 `code=AUTHZ_TENANT_MISMATCH`를 남겨야
찾을 수 있다.
## 진단
- `traceId`를 뽑고, 요청의 테넌트 헤더(서비스가 정한 이름, 예: `X-Tenant-Id`)와 토큰의 테넌트 클레임을 비교한다.
- `trace_id`로 요청 흐름을 따라간다. tenant는 인증 정보에서만 온다. 요청이 tenant를 제안하면(`X-Tenant-Id` 등) 서비스가 web-advanced `WebSecurityContextBridge.resolve(authentication, requestInput)`을 부를 때 403 `TENANT_INPUT_UNTRUSTED`로 거부하고, 한 인자 `resolve`만 부르거나 부르지 않으면 무시한다. 그래서 비교할 「요청의 tenant」는 없다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
- 클라이언트 설정 오류인지 의도한 공격인지 가린다.
## 조치
+2 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DB_UNAVAILABLE]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -13,7 +13,7 @@ status: 초안
## 증상
- HTTP 503, `error.code=DB_UNAVAILABLE`.
- 로그에 SQLState 08* 연결 오류가 있다.
- ERROR 줄 `persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`(`ServerFailureLog`). 원인 사슬은 붙지 않아 SQLState·SQL은 로그에 없다. 연결 계열 SQLState(08*)와 PostgreSQL 종료 상태(57P01·57P02)가 이 코드로 분류된다(`PersistenceExceptionTranslator`, `PostgreSqlFailureClassifier`). 쓰기 트랜잭션의 commit 중에 같은 상태가 나면 적용됐는지 모르므로 이 코드가 아니라 `DB_COMPLETION_UNKNOWN`(재시도 금지)이다.
## 진단
+4 -2
View File
@@ -4,7 +4,7 @@ category: PERMANENT_DEPENDENCY
error_codes: [DEPENDENCY_4XX_CLIENT]
severity: P2
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -14,10 +14,12 @@ status: 초안
- HTTP 502, `error.code=DEPENDENCY_4XX_CLIENT`.
- 업스트림이 401·403·400을 돌려줬다. 자격 증명, scope, 요청 형식 문제다.
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
- ERROR 줄 `dependency failure classified as DEPENDENCY_4XX_CLIENT (category=PERMANENT_DEPENDENCY, retryable=false, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
## 진단
- 로그에서 업스트림 응답 본문의 오류 내용을 본다.
- 업스트림 응답 본문은 로그에 남지 않는다(본문은 비밀·개인 정보를 실을 수 있어 남기지 않는다). 그 줄의 `dependency=`와, httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`status`로 어느 업스트림이 어떤 4xx를 돌려줬는지 본다. 본문은 업스트림 쪽 로그나 재현으로 본다.
- API 자격 증명과 scope가 유효한지 확인한다.
## 조치
+4 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DEPENDENCY_5XX_SERVER]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -14,10 +14,12 @@ status: 초안
- HTTP 502, `error.code=DEPENDENCY_5XX_SERVER`.
- 업스트림이 5xx를 돌려줬다. 서버 쪽 일시 장애다.
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
- ERROR 줄 `dependency failure classified as DEPENDENCY_5XX_SERVER (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
## 진단
- `dependency_name` 태그로 어느 업스트림이 실패하는지 본다.
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`outcome`으로도 본다.
- 업스트림 서비스의 상태 페이지를 본다.
## 조치
+4 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DEPENDENCY_CIRCUIT_OPEN]
severity: P2
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -14,10 +14,12 @@ status: 초안
- HTTP 503, `error.code=DEPENDENCY_CIRCUIT_OPEN`.
- 어떤 의존성의 circuit breaker(Resilience4j)가 OPEN 상태다.
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
- ERROR 줄 `dependency failure classified as DEPENDENCY_CIRCUIT_OPEN (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
## 진단
- 그 의존성의 Resilience4j circuit breaker 메트릭을 본다.
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.circuit.state`(tag `clientName`, 1 = open)와 `http.client.circuit.state.rejected`(열려 거부한 호출)를 본다. Resilience4j 자체 지표(`resilience4j_*`)는 묶지 않았다.
- 업스트림 상태를 확인한다. 실패가 임계를 넘으면 circuit이 열린다.
## 조치
+4 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DEPENDENCY_CONNECT_FAILED]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -14,10 +14,12 @@ status: 초안
- HTTP 503, `error.code=DEPENDENCY_CONNECT_FAILED`.
- 업스트림으로 TCP 연결이 거부됐거나 네트워크에 닿지 않는다.
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
- ERROR 줄 `dependency failure classified as DEPENDENCY_CONNECT_FAILED (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
## 진단
- `dependency_name` 태그로 어느 업스트림에 닿지 않는지 본다.
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`outcome`으로도 본다.
- 네트워크 경로와 방화벽 규칙을 확인한다.
## 조치
+4 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DEPENDENCY_DNS_FAILED]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-13
status: 초안
---
@@ -14,10 +14,12 @@ status: 초안
- HTTP 503, `error.code=DEPENDENCY_DNS_FAILED`.
- 업스트림 호스트 이름의 DNS 조회가 실패했다.
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
- ERROR 줄 `dependency failure classified as DEPENDENCY_DNS_FAILED (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
## 진단
- 앱 pod에서 DNS 조회를 시험한다: `nslookup <upstream-host>`
- 그 줄의 `dependency=`로 어느 업스트림인지 본다. 앱 pod에서 DNS 조회를 시험한다: `nslookup <upstream-host>`
- 클러스터 DNS(CoreDNS) 상태를 확인한다.
## 조치
+4 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DEPENDENCY_TIMEOUT]
severity: P1
owner: oncall
last_updated: 2026-11-07
last_updated: 2026-11-13
status: 초안
---
@@ -15,10 +15,12 @@ status: 초안
- HTTP 504, `error.code=DEPENDENCY_TIMEOUT`.
- 업스트림 서비스가 설정된 시간 안에 답하지 않았다. 호출 전체의 상한은 HTTP 클라이언트 profile의
`timeout.total-call`이다(기본값은 `docs/httpclient/configuration-reference.md`).
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
- ERROR 줄 `dependency failure classified as DEPENDENCY_TIMEOUT (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
## 진단
- 로그의 `dependency_name`으로 어느 업스트림이 시간을 넘기는지 본다.
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`outcome`으로도 본다. 시간 초과만 따로 보려면 `http.client.timeout`을 본다.
- 업스트림 서비스의 지연 메트릭을 본다.
## 조치
+17 -60
View File
@@ -1,80 +1,37 @@
---
title: Runbook — 외부 의존성 unavailable
category: TRANSIENT_DEPENDENCY
error_codes: [DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAILED, DEPENDENCY_CIRCUIT_OPEN, DEPENDENCY_5XX_SERVER, CACHE_UNAVAILABLE, DB_UNAVAILABLE]
error_codes: [DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAILED, DEPENDENCY_CIRCUIT_OPEN, DEPENDENCY_5XX_SERVER, DB_UNAVAILABLE]
severity: P1
owner: oncall
last_updated: 2026-05-22
last_updated: 2026-11-13
status: 초안
---
# Runbook: 외부 의존성 unavailable
## 1. Trigger
## 증상
이 runbook은 다음 alert가 울리면 쓴다.
- DB: 503 `DB_UNAVAILABLE`과 ERROR 줄 `persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`(`ServerFailureLog`, 원인 사슬은 붙지 않는다).
- outbound HTTP: 지금 httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`와 ERROR 줄 `unhandled exception on …`이 된다. registry의 `DEPENDENCY_*` 코드는 `DependencyFailureException`을 던지는 서비스 코드에서만 나오고, ERROR 줄 `dependency failure classified as DEPENDENCY_… (category=TRANSIENT_DEPENDENCY, retryable=…, dependency=<이름>)`을 남긴다.
- Redis: `CACHE_UNAVAILABLE` 코드는 없다. cache 읽기가 실패하면 원천에서 읽고 HTTP 오류는 없다. WARN 줄 `Redis semantic operation degraded; capability=… operation=… failureType=…`(`RedisSemanticFailureLogger`)이 남는다. cache만이 아니라 idempotency·rate-limit·lease도 같은 줄을 낸다. 같은 capability·operation·failureType은 1분에 한 번만 WARN이고 나머지는 DEBUG라, 경보는 건수가 아니라 그 줄이 나왔는지로 건다.
- 이 템플릿은 경보 규칙·대시보드를 두지 않는다. 서비스가 위 줄의 고정 문구(`persistence failure classified as`, `dependency failure classified as`, `unhandled exception on`, `Redis semantic operation degraded`)와 `http.server.requests`(tag `status`, `uri`)로 만든다. 업스트림 이름은 `dependency=` 값뿐이다. 위 줄들에는 `dependency_name` 칸이 없다.
- alert name: `dependency_error_rate_critical` 또는 `circuit_breaker_open`
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `dependency_name`, `dependency_kind`(required|optional), `runbook_link`
- 임계:
- P1: required dependency의 error rate > 50% 1분 OR circuit_open state 활성
- P2: optional dependency degraded (fail-open으로 동작 중)
## 진단
## 2. First Response (5분 이내)
- outbound HTTP 지표(httpclient capability를 켠 서비스): `http.client.requests`(tag `clientName`, `outcome`=`success`|`failure`), `http.client.retry.count`, `http.client.retry.exhausted`, `http.client.circuit.state`(1=open), `http.client.circuit.state.rejected`(`docs/registries/metrics.yaml`). Resilience4j 자체 지표(`resilience4j_*`)는 묶지 않았다.
- DB 풀: `hikaricp.connections.active`·`hikaricp.connections.pending`·`hikaricp.connections.timeout`(persistence-jpa를 켠 서비스).
- readiness는 DB와 required Redis만 본다. outbound HTTP 의존은 readiness에 들지 않는다.
### Step 1 — 확인
1. `dependency_name` 별 status page 확인 (외부 SaaS면 vendor status, internal이면 해당 service dashboard)
2. log query로 실패 패턴 확인: timeout / connect / DNS / 5xx 중 어떤 모드인지
3. runtime-health Dependency Matrix에서 required vs optional 분류 확인
4. circuit breaker state 확인 (Resilience4j metric)
## 조치
### Step 2 — 임시 격리
- required dep이면 readiness probe로 traffic 차단 (회복 대기) — cascade failure 방지
- optional dep이면 fail-open with degraded mode 확인. degraded banner를 client에 노출
- DNS failure면 resolver/coredns 상태 확인. cache 강제 flush 검토
- DB·required Redis 장애면 readiness가 트래픽을 뺀다. 회복을 기다린다.
- outbound 의존 장애면 그 클라이언트의 timeout·retry·circuit 설정(`docs/httpclient/`)을 본다. circuit을 손으로 되돌리는 actuator는 없다(`circuitbreakerevents`는 노출하지 않는다).
- 풀이 고갈되면 풀 크기와 오래 쥔 트랜잭션을 본다.
## 3. Diagnosis
## 에스컬레이션
- log query: `{service="app"} | dependency_name="<name>" | stats count by error.code`
- metric panel:
- `resilience4j_circuitbreaker_state{name="<name>"}`
- `resilience4j_retry_calls_total{kind="failed_without_retry"}`
- `hikaricp_connections_active`, `hikaricp_connections_pending` (DB_UNAVAILABLE)
- `http_client_requests_seconds_count{outcome="SERVER_ERROR"}`
- trace: 실패 request의 outbound span에서 timeout/connect/DNS 분류, target endpoint 확인
- 가능한 원인:
- vendor outage → status page 확인, 회복 대기
- 네트워크 문제 (DNS, security group, NAT) → infra team 확인
- connection pool 고갈 (Hikari) → pool size/timeout 점검
- circuit breaker open 후 half-open 전환 실패 → 수동 reset 검토
- retry-storm으로 인한 self-DoS → retry budget 축소
## 4. Mitigation
- 단기: required면 회복 대기 + traffic 차단, optional이면 degraded mode로 유지
- pool 고갈이면 일시 pool size 상향 + leak detection 활성화
- circuit이 stuck이면 수동 reset (`actuator/circuitbreakerevents`)
- 장기: retry budget·timeout·circuit 임계 재조정, fallback path 보강, vendor SLA 재협상
## 5. Escalation
- 다음 on-call로 page: required dep 5분 내 회복 안 되면 외부 dep team 또는 vendor에 page
- 다중 dep 동시 장애면 incident commander 호출 (네트워크 전반 문제 의심)
## 6. Recovery / Verification
- 회복 확인 metric: dependency error rate < 1% 5분 지속, circuit_breaker_state = CLOSED, pool utilization 정상
- post-incident:
- vendor postmortem 요청 (외부 SaaS면)
- timeout/retry/circuit 설정 재검토
- degraded mode가 사용자 경험에 미친 영향 측정
- chaos test에 해당 시나리오 추가
## 7. Related
- error-codes.yaml rows: `DEPENDENCY_TIMEOUT`, `DEPENDENCY_CONNECT_FAILED`, `DEPENDENCY_DNS_FAILED`, `DEPENDENCY_CIRCUIT_OPEN`, `DEPENDENCY_5XX_SERVER`, `CACHE_UNAVAILABLE`, `DB_UNAVAILABLE`
- metrics.yaml: `resilience4j_circuitbreaker_state`, `hikaricp_connections_active`, `http_client_requests_seconds_count`
- 관련 branch: [[feature-outbound-http-client-baseline]], [[feature-persistence-failure-baseline]]
- required 의존이 5분 안에 돌아오지 않으면 그 의존의 담당이나 vendor에 넘긴다.
---
+2 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
severity: P2
owner: oncall
last_updated: 2026-11-07
last_updated: 2026-11-13
status: 운영
---
@@ -114,7 +114,7 @@ status: 운영
- Redis: 확인과 삭제를 한 단계로, 서비스에 등록된 스크립트가 도는 계정으로 한다
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, 비어 있으면 애플리케이션 계정). `HMGET`으로
확인하고 `DEL`을 보내면 명령이 둘이다. 그 사이에 만료되어 새 요청이 다시 claim한 기록은 그 요청이 도는
동안 지워지고, 그 키의 다음 요청이 일을 한 번 더 한다(2026-11-04 재확인 리뷰 RR4-03-02). 아래 프로그램은
동안 지워지고, 그 키의 다음 요청이 일을 한 번 더 한다. 아래 프로그램은
`state`가 `ABANDONED`일 때만 키를 지운다. 애플리케이션 계정은 `EVAL`이 막혀 있으므로
(`compose/redis/acl/README.md`), 서비스가 자기 스크립트를 돌리는 것처럼 불러 올리고 `SCRIPT LOAD`가 찍은
digest로 돌린다.
+9 -10
View File
@@ -4,7 +4,7 @@ category: INTERNAL
error_codes: [INTERNAL_ERROR, INTERNAL_AUTH_MISCONFIGURATION, JVM_OOM]
severity: P1
owner: oncall
last_updated: 2026-05-22
last_updated: 2026-11-13
status: 초안
---
@@ -12,10 +12,9 @@ status: 초안
## 1. Trigger
이 runbook은 다음 alert가 울리면 쓴다.
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
- alert name: `http_5xx_error_rate_critical`
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `request_id`, `traceId`, `runbook_link`
- 경보에 실을 만한 값: MDC `request_id`·`trace_id`, ERROR 줄의 고정 문구(`unhandled exception on <경로>`, `failure classified as <code> (category=…, retryable=…)`), `http.server.requests`의 `status`. 5xx 줄에는 `error.code`·`error.category` 구조화 칸이 없고 코드는 메시지 글자로만 남는다(`ServerFailureLog`)
- 임계: 5xx error rate > 5% 5분 지속 OR > 10% 1분
## 2. First Response (5분 이내)
@@ -23,8 +22,8 @@ status: 초안
### Step 1 — 확인
1. 가장 최근 deploy 시각 확인 (CI/CD dashboard, artifact registry digest)
2. JVM metric 확인: heap usage, GC pause, CPU, thread count
3. log에서 실패 request 1건 추출 → `request_id`, `traceId` 확보
4. error.code 분포 확인: `INTERNAL_ERROR` vs `JVM_OOM` vs `INTERNAL_AUTH_MISCONFIGURATION`
3. log에서 실패 request 1건 추출 → `request_id`, `trace_id` 확보
4. 실패 종류 가르기: ERROR 줄 고정 문구 `unhandled exception on`(분류 안 된 실패, `INTERNAL_ERROR`) vs `failure classified as <code>`(분류된 5xx) vs `security failure: code=INTERNAL_AUTH_MISCONFIGURATION`. OOM은 로그 코드가 아니라 `runtime-jvm-oom.md`의 신호로 본다
### Step 2 — 임시 격리
- 직전 deploy가 의심되면 즉시 rollback (artifact registry에서 직전 image digest pin)
@@ -33,14 +32,14 @@ status: 초안
## 3. Diagnosis
- log query: `{service="app"} | http.status>=500 | stats count by error.code`
- log query: ERROR 줄을 위 고정 문구별로 센다(예: `{service="app"} |= "unhandled exception on"`). 로그에는 `http.status`·`error.code` 칸이 없다
- metric panel: `jvm_memory_used_bytes{area="heap"}`, `jvm_gc_pause_seconds`, `process_cpu_seconds_total`, `http_server_requests_seconds_count{status=~"5.."}`
- trace: 실패 request의 `traceId`로 span chain 확인 → stack trace에서 root exception 추출
- trace: 실패 request의 `trace_id`로 span chain 확인 → stack trace에서 root exception 추출
- heap dump 위치: `/var/tmp/heap/java_pid<pid>.hprof`(`-XX:HeapDumpPath=/var/tmp/heap`). 그 경로에 디스크 볼륨을 붙인 배포에만 남는다. 읽는 법은 `docs/runbooks/runtime-jvm-oom.md` 「진단」
- 가능한 원인:
- 직전 deploy의 회귀 버그 → rollback
- JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석
- 외부 의존성 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → config secret 확인
- JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석(`runtime-jvm-oom.md`)
- JWT decoder 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → issuer 설정과 discovery(`auth-public-path-misconfiguration.md`)
- thread starvation (pool 고갈) → thread dump (`jstack <pid>`)
## 4. Mitigation
+8 -6
View File
@@ -4,7 +4,7 @@ category: INTERNAL
error_codes: [JOB_DEAD_LETTER]
severity: P1
owner: oncall
last_updated: 2026-06-13
last_updated: 2026-11-13
status: 초안
---
@@ -12,10 +12,12 @@ status: 초안
## 1. Trigger
이 runbook은 다음 alert가 울리면 쓴다.
`JOB_DEAD_LETTER`는 enum 상수와 registry 행이 있지만 템플릿 코드는 내지 않는다. 템플릿에는 job 재시도·DLQ 실행기가 없다.
`job.dlq.total`·`job.retry.total`도 서비스가 `BackgroundJobMetrics.recordDeadLetter`·`recordRetryOutcome`을 부를 때만
생긴다(meter는 처음 셀 때 등록된다). 그래서 이 runbook은 서비스가 job 재시도·DLQ를 붙이고 아래 줄과 지표를 낼 때만
쓴다. 그 전에는 이 신호로 만든 경보가 울리지 않는다. 이 템플릿은 경보 규칙을 두지 않는다.
- alert name: `job_dead_letter`
- alert payload 필수 field: `error.code=JOB_DEAD_LETTER`, `job_name`, `correlation_id`, `runbook_link`
- 서비스가 낼 때 경보에 실을 만한 값: `error.code=JOB_DEAD_LETTER`, `job_name`, `correlation_id`
- 임계: `job.dlq.total` > 0 for 5m (p1) — retry 소진 후 DLQ 진입은 자동 회복이 없으므로 점검 대상
## 2. First Response (5분 이내)
@@ -26,7 +28,7 @@ status: 초안
3. DLQ 적재 위치(향후 retry carrier 확정 시 DB 테이블/큐) 확인 — 현재 skeleton은 vocabulary 단계
### Step 2 — 임시 격리
- DLQ는 max attempts(3) 소진의 최종 상태 — 자동 재시도 없음, 수동 개입 필수
- DLQ는 서비스가 정한 최대 시도를 다 쓴 최종 상태 — 자동 재시도 없음, 수동 개입 필수
- 비즈니스 크리티컬 job이면 §4의 수동 처분(재처리 또는 폐기)을 우선 수행
## 3. Diagnosis
@@ -40,7 +42,7 @@ status: 초안
## 4. Mitigation (수동 처분 — 둘 중 하나)
- **재처리 (기본)**: 원인 해소 후 해당 job을 다시 enqueue. 소비자는 멱등(idempotencyKey dedupe) 의무가 있으므로 중복 처리 안전
- **재처리 (기본)**: 원인 해소 후 해당 job을 다시 enqueue. 다시 넣어도 안전한지는 그 job이 멱등한지(서비스가 정한 dedupe key)에 달렸다. 멱등이 아니면 먼저 부작용이 이미 났는지 확인한다
- **폐기 (영구)**: 작업이 더 이상 유효하지 않으면 DLQ에서 제거. ⚠ 비즈니스 오너 승인 후에만 수행하고 incident 기록에 남김
- 장기: poison input 재발 방지(입력 계약 테스트 보강), non-transient error는 retry 없이 즉시 DLQ로 분류
+3 -4
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [JOB_EXECUTOR_REJECTED]
severity: P1
owner: oncall
last_updated: 2026-06-13
last_updated: 2026-11-13
status: 초안
---
@@ -12,10 +12,9 @@ status: 초안
## 1. Trigger
이 runbook은 다음 alert가 울리면 쓴다.
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
- alert name: `executor_rejected`
- alert payload 필수 field: `error.code=JOB_EXECUTOR_REJECTED`, `executor_name`, `policy`, `runbook_link`
- 경보에 실을 만한 값: `error.code=JOB_EXECUTOR_REJECTED`, `executor_name`, `policy`
- 임계: `executor.rejected.total` > 0 for 1m (p1) — bounded pool이 saturation으로 task를 거부
- 보조 신호: `executor.saturation` gauge > queue capacity의 80% for 5m (p2)
+9 -6
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [JOB_TIMEOUT]
severity: P2
owner: oncall
last_updated: 2026-11-03
last_updated: 2026-11-13
status: 초안
---
@@ -12,12 +12,15 @@ status: 초안
## 1. Trigger
이 runbook은 다음 alert가 울리면 쓴다.
`JOB_TIMEOUT`은 enum 상수와 registry 행이 있지만 템플릿 코드는 내지 않는다. `job.retry.total`도 서비스가
`BackgroundJobMetrics.recordRetryOutcome`을 부를 때만 생긴다. 그래서 이 runbook의 코드·지표 신호는 서비스가 job
시간 상한·재시도를 붙여 낼 때만 있다. 이 템플릿은 경보 규칙을 두지 않는다.
- alert name: `job_timeout`
- alert payload 필수 field: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id`, `runbook_link`
- 임계: `job.retry.total{outcome=RETRY}` 급증 또는 graceful-shutdown 중 in-flight job interrupt 발생
- 연관: shutdown phase에서 19s await 초과로 interrupt된 job (D8)
- 템플릿이 내는 신호는 종료 때 하나다: async executor가 남은 작업을 19s 기다리고도 끝나지 않으면 Spring이 WARN 줄
`Timed out while waiting for executor '<bean 이름>' to terminate`를 남긴다
(`AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS`). 남은 작업은 JVM이 끝날 때 함께 끊긴다.
- 서비스가 낼 때 경보에 실을 만한 값: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id`
- 임계: `job.retry.total{outcome=RETRY}` 급증
## 2. First Response (10분 이내)
+10 -10
View File
@@ -4,7 +4,7 @@ category: AUTHZ
error_codes: [ACTUATOR_FORBIDDEN]
severity: P2
owner: oncall
last_updated: 2026-11-07
last_updated: 2026-11-13
status: 초안
---
@@ -12,24 +12,24 @@ status: 초안
## 증상
- HTTP 403, `error.code=ACTUATOR_FORBIDDEN`.
- 제한된 actuator 엔드포인트(env·configprops·heapdump·shutdown)에 접근하려 했다.
- `ACTUATOR_FORBIDDEN`은 enum 상수(`OperationalError`)와 registry 행(`docs/registries/error-codes.yaml`)이 있지만 내는 코드가 없다.
- 실제 신호: 노출한 actuator(`health`·`info`·`prometheus`) 밖의 경로(env·configprops·heapdump·threaddump·shutdown·loggers)는 actuator chain이 잡지 않아 메인 보안 chain으로 간다. token이 없으면 401 `AUTH_TOKEN_MISSING`(Envelope, `WWW-Authenticate: Bearer`)과 WARN 줄 `security failure: code=AUTH_TOKEN_MISSING category=AUTH method=… path=/actuator/…`(logger `AuthErrorResponseWriter`)이다. 인증된 호출자는 mapping이 없어 404다(`config/observability.yml`의 `management.endpoints.web.exposure`).
- 서비스가 노출 목록을 넓혀 `health`·`info`·`prometheus` 밖의 endpoint를 더하면, 그 endpoint는 actuator chain이 잡고 본문 없는 401로 답한다. 그 chain에는 인증 수단이 없다(`ManagementSecurityConfig`). 이 401과 인증된 호출자의 404는 보안 로그 줄을 남기지 않는다.
## 진단
- 어느 actuator 엔드포인트에 접근했는지 찾는다.
- 호출자가 누구인지(내부 도구인지 외부인지) 확인한다.
- 관리 포트 노출은 포트로 가른다. 클러스터 밖에서 `curl -s -o /dev/null -w '%{http_code}' http://<host>:9001/actuator/health`가 200이면 관리 포트(`MANAGEMENT_SERVER_PORT`, 기본 9001, bind 주소 `MANAGEMENT_SERVER_ADDRESS`, 기본 `127.0.0.1`)가 클러스터 밖에 노출된 것이다. kubelet·Prometheus가 pod IP로 읽도록 `0.0.0.0`에 묶은 배포에서 클러스터 안의 200은 정상이다. 401·404만으로는 가를 수 없다: actuator가 없는 메인 포트의 `/actuator/env`도 메인 chain이 같은 401·WARN 줄·404로 답한다.
- 앱 로그에서 `path=/actuator`가 든 `security failure` 줄을 찾는다(token 없는 시도). 그 줄에는 포트가 없다. 인증된 호출자의 404는 보안 로그 줄이 없다. 앞단 프록시·ingress 접근 로그로 어느 포트를 누가 불렀는지 찾는다.
## 조치
- management 포트가 밖으로 노출되지 않았는지 확인한다.
- heapdump·threaddump는 노출 목록에서 빠져 있다(`config/observability.yml`의
`management.endpoints.web.exposure.exclude`). 꼭 필요하면 운영 조직의 break-glass 절차를 따른다. 이 저장소에는
그 절차 문서가 없다.
- 관리 포트를 클러스터 밖으로 열지 않는다. kubelet 프로브와 Prometheus는 pod IP로 붙으므로 둘 중 하나를 고른다(`src/bootstrap/service-runtime/README.md` 「ManagementSecurityConfig」): `MANAGEMENT_SERVER_ADDRESS`를 `0.0.0.0`으로 두고 NetworkPolicy로 클러스터 안의 그 둘만 들이거나, 같은 pod의 sidecar가 loopback으로 읽는다. 기본값(loopback) 그대로면 liveness가 실패한다.
- heapdump·threaddump는 노출 목록에서 빠져 있다. 꼭 필요하면 운영 조직의 break-glass 절차를 따른다. 이 저장소에는 그 절차 문서가 없다.
## 에스컬레이션
- 금지된 actuator 접근이 외부 공격으로 보이면 P1.
- 관리 포트가 밖에 열려 있고(위 `curl`이 200) 외부에서 actuator를 두드린 흔적이 있으면 P1. 메인 포트의 `/actuator/…` 시도만 있으면 보통 스캐너다.
---
+11 -14
View File
@@ -4,7 +4,7 @@ category: INTERNAL
error_codes: [OUTBOX_DEAD_LETTER]
severity: P1
owner: oncall
last_updated: 2026-11-04
last_updated: 2026-11-13
status: 초안
---
@@ -12,14 +12,12 @@ status: 초안
## 1. Trigger
이 runbook은 다음 alert가 울리면 쓴다.
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
- alert name: `outbox_dead_letter`
- alert payload 필수 field: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`, `runbook_link`
- 경보에 실을 만한 값: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`
- 임계: `outbox.publisher.published.total{outcome=DEAD}` > 0 또는 `outbox.pending.size{status=DEAD}` > 0 (DEAD 전이는
자동 회복이 없으므로 단건도 점검 대상). 두 번째 조건이 필요한 이유: claim이 행을 DEAD로 옮기는 경우
(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다
(재리뷰 2026-11-03 2차 RR-02-12)
(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다.
## 2. First Response (5분 이내)
@@ -53,8 +51,7 @@ status: 초안
**재발행 (기본)**: 원인 해소 후 해당 row를 다시 claim 가능 상태로 되돌린다. 시도 횟수 두 개
(`attempt_count`, `deferred_attempt_count`)를 함께 0으로 되돌린다. `attempt_count`만 되돌리면 다음 claim에서
미룬 claim 수가 전체 claim 수보다 많아지고, claim은 그 행을 읽지 않고 다시 DEAD로 옮긴다(재리뷰 2026-11-03
RR-05-01).
미룬 claim 수가 전체 claim 수보다 많아지고, claim은 그 행을 읽지 않고 다시 DEAD로 옮긴다.
<!-- runbook-sql: dead-redrive-one -->
```sql
@@ -109,8 +106,8 @@ UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status
V21(`V21__outbox_aggregate_sequence.sql`)은 `outbox_event`의 순서 키
`(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)`에 유일 인덱스
`ux_outbox_event_aggregate_order`를 만든다. 같은 키를 가진 행이 이미 둘 이상 있으면 인덱스 생성이
실패하고 기동이 멈춘다(`MIGRATION_FAILED`, exit 70). 이 실패는 의도한 동작이다(리뷰 2026-11-01
README 15절 결정). 같은 키의 행들은 claim gate가 순서를 정하지 못한 행이다. 그냥 넘기면 순서 위반이
실패하고 기동이 멈춘다(`MIGRATION_FAILED`, exit 70). 이 실패는 의도한 동작이다(소유자
결정). 같은 키의 행들은 claim gate가 순서를 정하지 못한 행이다. 그냥 넘기면 순서 위반이
숨는다. V21은 transaction 하나로 적용되므로, 실패하면 V21 전체가 롤백되고 V20 상태로 남는다.
V21이 하는 일은 세 가지 더 있다.
@@ -118,14 +115,14 @@ V21이 하는 일은 세 가지 더 있다.
- **floor 기록.** `outbox_aggregate_sequence_floor`에 V21 적용 시각(epoch 마이크로초)을 한 번 쓴다. 새로
생기는 aggregate counter는 이 값과 남은 행의 최대 번호 중 큰 값 다음에서 시작한다. 그래서 reaper가
행을 지운 aggregate, tenant scope가 바뀐 aggregate도 소비자가 이미 받은 벽시계 번호(약 1.7×10¹⁵)보다
작은 번호를 받지 않는다(리뷰 RR-03-02). 벽시계 번호를 쓴 적 없는 서비스도 첫 번호가 floor + 1이다.
작은 번호를 받지 않는다. 벽시계 번호를 쓴 적 없는 서비스도 첫 번호가 floor + 1이다.
- **counter 미리 만들기.** 남은 행이 있는 aggregate의 counter를 그 최대 번호로 만든다.
- **잠금 대기 5초.** 유일 인덱스는 만드는 동안 `outbox_event`에 SHARE 잠금을 건다. 그동안 outbox를 쓰는
업무 쓰기가 모두 멈춘다. V21은 `lock_timeout = 5s`로 잠금을 기다린다. 열린 outbox 쓰기 트랜잭션 때문에
5초 안에 못 잡으면 V21이 실패하고 V20에 남는다(`MIGRATION_FAILED`). 덜 바쁜 시각에 다시 배포하거나
Step 0으로 인덱스를 먼저 만든다.
V20(`deferred_attempt_count`)과 V22(`last_failure_code`)도 같은 상한을 둔다(재리뷰 2026-11-03 2차 RR-02-09).
V20(`deferred_attempt_count`)과 V22(`last_failure_code`)도 같은 상한을 둔다.
둘 다 `ALTER TABLE outbox_event`라 가장 강한 잠금(ACCESS EXCLUSIVE)을 건다. 이 잠금은 읽기와도 충돌하므로,
`outbox_event`를 읽기만 한 트랜잭션 하나(운영자가 `BEGIN` 안에서 조회하고 둔 psql 세션 포함)가 열려 있어도
기다린다. 5초 안에 못 잡으면 그 마이그레이션이 실패·롤백되고 DB는 한 버전 아래(V19 또는 V21)에 남으며 새 버전은
@@ -147,8 +144,8 @@ rolling 배포 중 아직 옛 버전인 인스턴스가 벽시계 번호로 쓴
이 "그 행 뒤에"는 **같은 aggregate identity**의 행에만 성립한다. tenant scope를 바꾸는 배포에서는 옛 버전이
옛 scope로, 새 버전이 새 scope로 쓴다. 새 버전의 counter는 옛 scope 행을 보지 못하므로 floor + 1부터 시작하고,
rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽시계 번호)보다 **작은** 번호를 준다(재리뷰
2026-11-03 2차 RR-02-10, 실 PG 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한
rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽시계 번호)보다 **작은** 번호를 준다(실
PostgreSQL에서 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한
소비자는 그 사이 새 이벤트를 버린다. 그래서 **tenant scope를 바꾸는 배포는 rolling으로 하지 않는다**: 옛 버전
인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다.
+8 -9
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [OUTBOX_PUBLISH_FAILED]
severity: P2
owner: oncall
last_updated: 2026-11-04
last_updated: 2026-11-13
status: 초안
---
@@ -12,10 +12,9 @@ status: 초안
## 1. Trigger
이 runbook은 다음 alert가 울리면 쓴다.
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
- alert name: `outbox_publish_failed_rate`, `outbox_publisher_lag` 또는 `outbox_retry_long`
- alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`, `runbook_link`
- 경보에 실을 만한 값: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`
- 임계 (metrics.yaml verbatim):
- P2: `outbox.publisher.published.total{outcome=FAILED}` rate > 1% for 10m
- P2: `outbox.publisher.lag` > 60s for 10m / P1: > 300s for 5m
@@ -35,8 +34,8 @@ status: 초안
아니라 **선택자**다 — messaging을 끄는 것은 `APP_MESSAGING_ENABLED=false`이고, 이 값을 비운다고
messaging이 꺼지지는 않는다.
- relay 스케줄러는 발행 포트(`OutboxMessagePublishPort`, messaging bridge가 제공)가 있을 때만
생긴다. messaging을 고르지 않은 배포에서는 relay가 없고 PENDING row가 그대로 남는다(MSG-024의
"DEAD까지 소진"은 대역 publisher가 있던 때의 이야기다). messaging 모듈이 켜져 있는데
생긴다. messaging을 고르지 않은 배포에서는 relay가 없고 PENDING row가 그대로 남는다(DEAD로 가지
않는다). messaging 모듈이 켜져 있는데
`APP_MESSAGING_PRODUCER_ID`가 공백이면(messaging `MessagingConfig`) 또는 `APP_MESSAGING_BROKER`가
공백이면(messaging platform `MessagingProviderSelection`) 기동이 거부된다 — 값을 설정하거나
messaging을 끈다.
@@ -81,8 +80,8 @@ status: 초안
### 4.1 끝나지 않는 재시도 — 찾기, 보류(park), 재개(resume), 버리기(skip)
시도 예산을 쓰지 않는 실패(§2 Step 2)는 끝 상태가 없다. 리뷰 2026-11-01 README 15절 결정(재시도 유지)은 그대로 두고,
운영자가 그런 행을 보고 멈출 수 있게 한다(재리뷰 2026-11-03 RR-05-03 결정).
시도 예산을 쓰지 않는 실패(§2 Step 2)는 끝 상태가 없다. 그런 실패는 계속 재시도한다(소유자 결정). 대신 운영자가
그런 행을 보고 멈출 수 있게 한다.
**Step 1 — 찾기 (읽기 전용).** 미룬 claim(`deferred_attempt_count`)이 10번 이상인 FAILED 행이다. backoff 상한이
5분이라 10번은 적어도 약 35분 동안 계속 실패했다는 뜻이다. `outbox.retry.long.size`·`outbox.retry.long.age`가
@@ -117,7 +116,7 @@ UPDATE outbox_event SET status = 'PARKED' WHERE event_id = '<id>' AND status = '
**롤백 전에 보류를 푼다.** `PARKED`는 이 버전(`bbe944bd` 이후)에 생긴 상태다. 그보다 옛 버전은 이 이름을 몰라
상태별 집계 전체가 실패하고, `outbox.pending.size` 게이지가 PENDING까지 통째로 꺼진다 — `PENDING size growing`
경보의 입력이 사라진다(재리뷰 2026-11-03 2차 RR-02-11). 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
경보의 입력이 사라진다. 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을
말한다(`outbox_event holds rows in a status this version does not know`).
+15 -51
View File
@@ -4,69 +4,33 @@ category: RATE_LIMIT
error_codes: [RATE_LIMIT_EXCEEDED, IDEMPOTENT_IN_FLIGHT]
severity: P3
owner: oncall
last_updated: 2026-05-22
last_updated: 2026-11-13
status: 초안
---
# Runbook: Rate limit 초과 spike
## 1. Trigger
## 증상
이 runbook은 다음 alert가 울리면 쓴다.
- HTTP 429 `RATE_LIMIT_EXCEEDED`, `Retry-After`(초), `X-RateLimit-Limit`·`X-RateLimit-Remaining`·`X-RateLimit-Reset` 헤더(`RateLimitInterceptor`). 저장소에 닿지 못하면 503 `RATE_LIMIT_UNAVAILABLE`이다.
- 앱 안 limiter는 기본으로 꺼져 있다(`APP_RATE_LIMIT_ENABLED=false`, `docs/security/rate-limiting.md`). 켠 서비스에서만 이 증상이 난다.
- 429에는 전용 WARN 줄이 없다. 요청 로그 INFO 줄 `http_request method=… uri_template=… status=429 duration_ms=…`(`RequestLoggingFilter`, `APP_LOG_SAMPLING_RATE` 표본)과 `http.server.requests`의 `status=429`가 신호다. 이 템플릿은 경보 규칙·대시보드를 두지 않는다. 서비스가 그 둘로 만든다.
- `IDEMPOTENT_IN_FLIGHT`는 요청률 제한이 아니다. 같은 멱등 키의 요청이 아직 처리 중이라는 409(CONFLICT)다(`docs/web/runbook.md`).
- alert name: `rate_limit_429_high`
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `rate_limit_key_type`(ip|principal|tenant), `runbook_link`
- 임계:
- P3: 429 rate > 1% 10분 지속 (일상적 abuse 차단 효과 정상)
- P2 격상: 정상 client(known principal/tenant)에서 spike 또는 spike와 함께 5xx 동반
## 진단
## 2. First Response (5분 이내)
- limiter key는 「호출자 × 연산」이다(`RateLimitKeyResolver`). 호출자는 인증된 사용자, `service` 역할을 가진 principal(종류 이름 `API_KEY`, header의 API key가 아니다), 인증이 없으면 client IP(`getRemoteAddr()`)다. 연산은 method와 route template(`GET /v1/orders/{id}`)이다. tenant 단위는 없다. 호출자 값(사용자 id·IP)은 가명으로 바꿔 쓰고 로그·지표에 남기지 않는다.
- 정책 값(`APP_RATE_LIMIT_LIMIT`·`_WINDOW` 등)은 정책 id마다 하나이고 재시작해야 바뀐다. key 하나만 올리는 손잡이는 없다.
### Step 1 — 확인
1. rate-limit key 분포 확인: IP/principal/tenant 중 어디서 spike가 발생했는지
- log query: `error.code=RATE_LIMIT_EXCEEDED | stats count by rate_limit_key_type, rate_limit_key`
2. top-N offending key 추출 (상위 10건)
3. 정상 client 식별 — 알려진 partner/internal service면 P2 격상
## 조치
### Step 2 — 임시 격리
- abuse traffic 패턴이면 WAF/gateway에서 IP block (geo, ASN 단위)
- IDEMPOTENT_IN_FLIGHT 다발이면 client의 retry-storm 의심 → client에 retry-after 협조 요청
- 남용이면 앞단(WAF·gateway)에서 막는다.
- 정상 트래픽이 늘었으면 정책 값을 올리고 재배포한다.
- 클라이언트가 `Retry-After`를 지키지 않고 재시도하면 backoff를 요청한다.
## 3. Diagnosis
## 에스컬레이션
- log query: `{service="gateway"} | error.code="RATE_LIMIT_EXCEEDED" | stats count by rate_limit_key`
- metric panel: `gateway_rate_limit_dropped_total`, `gateway_rate_limit_bucket_utilization`
- trace: 429 응답의 `Retry-After` 헤더 값, `rate_limit_remaining` header 확인
- 가능한 원인:
- abuse / bot traffic → IP/ASN block
- 정상 client의 traffic 증가 (캠페인, 신규 feature) → limit 일시 상향
- retry-storm (client backoff 미적용) → client에 idempotency-key + exponential backoff 권고
- limit 설정 오류 (잘못된 정량 threshold) → config rollback
## 4. Mitigation
- 단기: abuse면 IP/ASN block, 정상 client면 해당 key의 limit 일시 상향(예: 2x, 1시간 TTL)
- IDEMPOTENT_IN_FLIGHT 다발: idempotency-key 정책 점검, client 협조 요청
- 장기: limit 정책을 tenant tier별 차등으로 재설계, abuse pattern detection 자동화
## 5. Escalation
- 다음 on-call로 page: 30분 내 정상 client 회복 안 되면 product team 통보
- 정상 client에 SLO 위반 가능성 있으면 CSM/계정담당 통보
## 6. Recovery / Verification
- 회복 확인 metric: 429 rate < 0.5% 10분 지속, 정상 client의 success rate 정상화
- post-incident:
- 일시 상향한 limit 원복 (TTL 만료 확인)
- abuse pattern을 detection rule에 영구 등록
- retry-storm이면 client SDK 가이드 보완
## 7. Related
- error-codes.yaml rows: `RATE_LIMIT_EXCEEDED`, `IDEMPOTENT_IN_FLIGHT`
- metrics.yaml: `gateway_rate_limit_dropped_total`, `gateway_rate_limit_bucket_utilization`
- 관련 branch: [[feature-rate-limit-idempotency-contract]]
- 정상 클라이언트가 30분 넘게 막히면 제품 팀에 알린다.
---
+3 -3
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: []
severity: P1
owner: oncall
last_updated: 2026-07-29
last_updated: 2026-11-13
status: 운영
---
@@ -36,11 +36,11 @@ Redis liveness 실패만으로 pod를 재시작하지 않는다. 재시작 폭
뜻이다. 이를 정상 attestation으로 해석하지 않는다.
- **지금 내보내는 Redis 지표는 connection lane 단위 `redis.lane.*`다**(`docs/registries/metrics.yaml`,
`lane` 태그). capability·operation 단위 지표(`redis.capability.*`)는 설계만 있고 아직 어떤 코드도
내보내지 않는다 — 대시보드에서 찾지 않는다(재리뷰 2026-11-03, `src/adapter/outbound/cache-redis/README.md`
내보내지 않는다 — 대시보드에서 찾지 않는다(`src/adapter/outbound/cache-redis/README.md`
「아직 내보내지 않는 지표」).
- lane 포화: `redis.lane.acquire.refused.total`(거절)과 `redis.lane.acquire.wait.seconds`(대기)를 lane별로
본다. `CACHE_SCRIPT`만 차 있으면 캐시 조건부 쓰기의 문제이고, 멱등성·lease가 쓰는 `SCRIPT` lane은
따로 본다(재리뷰 RR-04-02).
따로 본다.
- 연결 불안정: `redis.lane.connections.opened.total`·`redis.lane.connections.discarded.total`의 급증,
`redis.lane.connections.active`·`pending`.
- operation 결과(hit/miss/denied/conflict, `certainty=indeterminate`)는 지표가 아니라 각 capability의
+23 -17
View File
@@ -34,7 +34,10 @@ HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈
요구한다.
2. **client가 다른 본문을 보냈다.** `422 IDEMPOTENT_REQUEST_MISMATCH`로 답하고 절대 다시 보내지 않는다. 다시 보내면
호출자가 한 적 없는 요청의 영수증을 돌려주게 된다.
3. **기록이 만료됐다.** TTL은 연산마다 정하고 상한은 72h다. 만료 뒤의 재시도는 정의상 새 요청이다.
3. **기록이 만료됐다.** TTL은 전역 하나다: `APP_IDEMPOTENCY_TTL`(`app.capabilities.idempotency.replay-ttl`, 기본 24h,
상한 72h). 연산마다 정하는 손잡이는 없다. 이 값은 실패 기록 보존 `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길
수 없다. TTL만 48h로 올리면 기동이 실패하니 둘을 같이 올린다(`IdempotencySettings`). 만료 뒤의 재시도는 정의상 새
요청이다.
`409 IDEMPOTENT_IN_FLIGHT`(retryable=true, `Retry-After: 2`)는 실패가 아니다. 앞 시도가 아직 돌고 있고 그 결과를
모른다. 호출자는 `Retry-After` 뒤에 **같은** `Idempotency-Key`로 다시 보낸다. 새 key는 새 요청이고, 쓰기가 두 번
@@ -42,37 +45,40 @@ HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈
## rolling 배포가 인스턴스를 반쯤 비운 채 멈춘다
`shutDownGracefully`는 진행 중인 일을 기다리고, 열려 있지만 노는 keep-alive connection이 진행 중으로 셀 수 있다. 그
기다림 중에 `stop()`을 부르면 멈춘다.
graceful shutdown(`server.shutdown=graceful`)은 진행 중인 요청이 끝나기를 기다린다. 끝나지 않는 요청이 있으면 그
기다림이 길어진다.
- **증상:** 요청을 받지도 않고 끝나지도 않는 인스턴스. 로그에 오류가 없다.
- **원인:** 상한 없는 graceful 기다림. `GracefulShutdownProbe`는 정한 유예 시간으로 그것을 제한하고, 시간이 지나면
어쨌든 서버를 멈춘다. 배포도 같게 해야 한다.
- **설정:** `spring.lifecycle.timeout-per-shutdown-phase`. 상한이 없으면 배포는 영영 놀지 않을 수도 있는 connection을
기다린다.
- **증상:** 종료 중인 인스턴스가 새 요청을 받지 않은 채 오래 남는다. 종료 예산보다 유예가 짧으면 멈추는 대신
SIGKILL로 끝나고, 진행 중이던 요청·async 작업이 끊긴다. 로그에 오류가 없다.
- **원인:** 종료 단계는 차례로 더해진다. 웹 drain(`spring.lifecycle.timeout-per-shutdown-phase`,
`APP_SERVER_SHUTDOWN_TIMEOUT`, 기본 30s)이 끝난 뒤 async executor가 남은 작업을 19s 기다린다
(`AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS`). 합계 49s에 preStop(5s)과 여유를 더한 값보다 배포의 종료 유예
(Kubernetes `terminationGracePeriodSeconds` 등, 기본 30s)가 짧으면 async 대기 중에 죽는다. compose는 60s다
(`compose.yaml` `stop_grace_period`). 같은 예산을 `docs/runbooks/job-timeout.md` 「Escalation」이 적는다.
- `GracefulShutdownProbe`는 시험 도구다(web `testFixtures`, 성능 lane이 쓴다). 운영 코드에는 없다.
## metric이 오지 않거나 청구액이 뛰었다
거의 늘 가짓수가 많은 tag다. 흔히 *풀린* 경로를 담은 `routeTemplate`이고, 자원마다 시계열 하나가 된다.
거의 늘 가짓수가 많은 tag다. 흔히 *풀린* 경로를 담은 경로 tag이고, 자원마다 시계열 하나가 된다. 이 템플릿의
`http.server.requests`는 Spring Framework 기본 convention(`DefaultServerRequestObservationConvention`)의 tag `uri`를
쓴다(`docs/registries/metrics.yaml`). 맞는 route가 있으면 template(`/v1/orders/{id}`)이고, 없으면 그 convention이 정한
상수(`NOT_FOUND`, `REDIRECTION`, `UNKNOWN`, `root`)다.
- **확인:** metric 저장소에서 `routeTemplate`의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린
경로가 새어 나갔다.
- **확인:** metric 저장소에서 `uri`의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린 경로가 새어
나갔다(서비스가 자기 convention으로 tag를 바꿨을 때 생긴다).
- **절대 tag로 쓰지 않는 것:** URL, query string, 식별자, tenant, key, token, cookie, 본문. tag 값은 가려지지 않은 채
metric 저장소에 닿고, 보통 그와 함께 외부 SaaS에도 닿는다.
## 브라우저에서만 cross-origin 요청이 실패한다
API는 맞게 답하는데 브라우저가 응답을 거부한다. CORS는 `SecurityConfig`가 적용하는 `CorsSettings`(`app.cors.*`)다.
시작 단계는 두 설정을 거부한다.
시작 단계는 아래 설정을 거부한다.
- origin 없이 `APP_SECURITY_CORS_ENABLED=true`.
- `APP_SECURITY_CORS_ALLOW_CREDENTIALS=true`와 함께 `APP_SECURITY_CORS_ORIGINS`의 `*` — 어떤 브라우저도 받아들이지
않는다.
다음 둘은 시작은 되지만 브라우저에서 여전히 실패한다.
- origin 목록의 `https://*.example.com` — 글자 그대로 비교하므로 아무것에도 맞지 않는다.
- 경로가 있는 origin(`https://app.example.com/ui`) — origin은 scheme, host, port뿐이다.
- origin 목록의 `https://*.example.com` 같은 wildcard origin과 경로가 있는 origin(`https://app.example.com/ui`) — origin은
scheme, host, port뿐이다(`CorsSettings`).
응답은 오는데 브라우저 코드에서 헤더가 `null`로 읽힌다(`Retry-After`, `X-Request-Id`, `Location`, tus
`Upload-Offset`): 그 헤더가 `Access-Control-Expose-Headers`에 없다. 노출 목록은 `CorsExposedHeaders.PLATFORM`과 모듈마다의
+1 -1
View File
@@ -258,7 +258,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
| `LockAcquisitionTimeoutException` | `LOCK_ACQUISITION_TIMEOUT` | 409 (retryable=true, `Retry-After: 1`) | 분산 락을 `waitTime` 안에 못 잡음. 경합은 일시적이라 잠시 뒤 같은 요청을 다시 보낸다. carrier 분기(전에는 carrier 가 아니라 500 `INTERNAL_ERROR`, 재리뷰 RR7-01-04) |
| `IdempotencyRequestMismatchException` | `IDEMPOTENT_REQUEST_MISMATCH` | 422 (retryable=false) | D8: `Idempotency-Key` 를 다른 본문으로 재사용. 다시 보내지 않는다(`docs/web/http-contract.md` §2). fingerprint/scope 노출 금지 |
| `PersistenceFailureException` (JPA `JpaPersistenceException` 포함) | `ex.errorCode()` (사전분류 `DB_*`) | 코드 결정 | adapter-persistence translator 가 SQLState→`DB_*` 로 이미 분류, JPA 예외는 `FailureCategory`→`DB_*`. 클라이언트 메시지는 category 문구, **절대 `ex.getMessage()` 아님**(SQLState/제약명 담음, 서버 로그 전용) |
| `DependencyFailureException` | `ex.errorCode()` (사전분류 `DEPENDENCY_*`) | 코드 결정 | adapter-outbound `OutboundHttpErrorMapper` 가 upstream 실패를 분류. 클라이언트 메시지는 category 문구, **절대 `ex.getMessage()` 아님**. retryable + `retry_after_seconds` 있으면 `RetryAfterAdvisor` 로 `Retry-After` 부착 |
| `DependencyFailureException` | `ex.errorCode()` (사전분류 `DEPENDENCY_*`) | 코드 결정 | upstream 실패를 분류하는 서비스 코드가 던진다(템플릿 httpclient 는 만들지 않는다). 클라이언트 메시지는 category 문구, **절대 `ex.getMessage()` 아님**. retryable + `retry_after_seconds` 있으면 `RetryAfterAdvisor` 로 `Retry-After` 부착 |
| `HttpRequestMethodNotSupportedException` | `METHOD_NOT_ALLOWED` | 405 | D12: 405 는 지원 메서드를 나열한 `Allow` 헤더 필수 |
| `HttpMediaTypeNotSupportedException` | `UNSUPPORTED_MEDIA_TYPE` | 415 | D9: 요청 본문 형식 미지원 — 406 과 구별 |
| `MaxUploadSizeExceededException` | `PAYLOAD_TOO_LARGE` | 413 | D8: 과대 본문은 envelope 내 413, raw 500 금지. multipart와 JSON 본문 모두 이 코드다(multipart 전용 코드는 없다) |
+16 -14
View File
@@ -144,9 +144,10 @@ Spring/Lettuce 타입을 노출하지 않는다.
- `AUTH_KID_UNKNOWN` 은 `retryable=true`: 키 회전(key rotation) 중 알 수 없는 JWKS `kid` 는 키
세트가 새로고침되면 저절로 풀린다(레지스트리에서 `false→true` 로 바뀐 이력 있음, Retry-After 5s).
- `AUTH_JWKS_UNAVAILABLE` 은 JWKS 엔드포인트 장애 = 일시적 의존성 실패 → 503, retryable.
- `INTERNAL_AUTH_MISCONFIGURATION` 은 `retryable=false`: 보호돼야 할 엔드포인트가 public 으로
새어 나가는 것은 **배포 시점 설정 버그**이지 일시적 장애가 아니다. 같은 요청을 다시 보내도 (재배포
전까지) 절대 풀리지 않으므로 false 다(`INTERNAL` category 코드는 모두 `retryable=false`).
- `INTERNAL_AUTH_MISCONFIGURATION` 은 `retryable=false`: JWT decoder 를 만들 수 없는 것(issuer discovery 4xx,
discovery 의 `issuer` 불일치, `jwks_uri` 없음)은 **배포 시점 설정 버그**이지 일시적 장애가 아니다. 같은 요청을
다시 보내도 (설정을 고쳐 재배포하기 전까지) 풀리지 않으므로 false 다(`INTERNAL` category 코드는 모두
`retryable=false`). 공개 경로 설정 오류는 이 코드를 내지 않는다.
**rate-limit / idempotency**
- `RATE_LIMIT_EXCEEDED` 는 `retryable=true` 이며 Retry-After 헤더와 짝을 이룬다.
@@ -185,8 +186,9 @@ Spring/Lettuce 타입을 노출하지 않는다.
| `DB_QUERY_CANCELED` | 57014 | TRANSIENT_DEPENDENCY | 503 | ❌ | |
**outbound HTTP — upstream 실패 분류**
- `DEPENDENCY_*` 코드는 adapter-outbound 의 `OutboundHttpErrorMapper` 가 upstream HTTP/네트워크
실패를 분류한 뒤 방출한다. raw upstream 응답은 web 계층까지 도달하지 않는다.
- `DEPENDENCY_*` 코드는 서비스 코드가 upstream HTTP/네트워크 실패를 분류해 `DependencyFailureException` 으로 던질
때 나온다. 템플릿의 httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR` 다. raw upstream 응답은 web 계층까지
도달하지 않는다.
- **알려진 미해결 엣지:** 408(Request Timeout)·429(Too Many Requests)는 의미상 재시도 가능하지만,
레지스트리 SSOT 는 **모든 upstream 4xx 를 `PERMANENT_DEPENDENCY`(`retryable=false`)로 분류**한다.
이는 의도적 결정이며, 바꾸려면 레지스트리 갱신과 어댑터 변경을 함께 해야 한다.
@@ -226,12 +228,12 @@ Spring/Lettuce 타입을 노출하지 않는다.
(D6)이며, 정합성 자체는 이 코드가 아니라 DB 제약이 지킨다.
**기타 운영 코드**
- `JVM_OOM`: JVM OutOfMemoryError 분류. JVM 이 죽는
종료성 장애(`ExitOnOutOfMemoryError`, exit 137)라 재시도해도 안 풀림 → `retryable=false`
(`INTERNAL`/500). 로그의 `error.code=JVM_OOM` 유무로 kubelet OOMKill 과 구별한다.
- `ACTUATOR_FORBIDDEN`: 운영 환경에서 위험한
actuator 엔드포인트(env/configprops/heapdump/threaddump/shutdown) 접근 → 403(`AUTHZ`/403/false,
로그 WARN).
- `JVM_OOM`: JVM OutOfMemoryError 분류. JVM 이 죽는 종료성 장애(`ExitOnOutOfMemoryError`, 종료 코드 3)라
재시도해도 안 풀림 → `retryable=false`(`INTERNAL`/500). 이 코드를 로그에 쓰는 코드는 없다. kubelet OOMKill(137)과는
종료 코드와 stderr 마지막 줄로 구별한다(`docs/runbooks/runtime-jvm-oom.md`).
- `ACTUATOR_FORBIDDEN`: enum 상수와 registry 행(`AUTHZ`/403/false)만 있고 내는 코드가 없다. 노출 목록 밖의 actuator
경로(env/configprops/heapdump/threaddump/shutdown)는 401 `AUTH_TOKEN_MISSING`(token 없음)이나 404(인증됨)다
(`docs/runbooks/management-actuator-forbidden.md`).
### MappingException
- **경계 mapper 의 sentinel.** request→command/query 변환, response shaping, outbound ACL 등 어떤
@@ -253,9 +255,9 @@ Spring/Lettuce 타입을 노출하지 않는다.
`MappingException` 과 동일하다.
### DependencyFailureException
- **분류된 outbound HTTP(의존성) 실패의 프레임워크 중립 운반체**. adapter-outbound 의 `OutboundHttpErrorMapper` 가 raw 네트워크/HTTP 예외를 잡아 upstream
실패 매트릭스로 분류한 뒤, 안정적 `ApiErrorCode`(`DEPENDENCY_*`)와 upstream 의존성 이름을 담아
이 타입으로 감싸 다시 던진다.
- **분류된 outbound HTTP(의존성) 실패의 프레임워크 중립 운반체**. upstream 실패를 분류하는 서비스 코드가 raw
네트워크/HTTP 예외를 잡아 안정적 `ApiErrorCode`(`DEPENDENCY_*`)와 upstream 의존성 이름을 담아 이 타입으로 감싸 다시
던진다. 템플릿의 httpclient 는 이 타입을 만들지 않는다.
- **`diagnosticMessage` 는 서버 로그 전용이며 upstream raw 응답 본문을 절대 담아선 안 된다.** 테스트
계약: "upstream raw error body 가 response/log 에 노출되면 실패". web 어댑터는 `errorCode()` +
고정된 client-safe 메시지로 매핑하므로 upstream status/body/header/raw 예외 클래스가 API
@@ -1,10 +1,10 @@
package dev.caskeleton.shared.error;
/**
* Framework-neutral carrier for a classified outbound HTTP (dependency) failure. The
* adapter-outbound {@code OutboundHttpErrorMapper} classifies a raw network / HTTP exception and
* rethrows it wrapped in this type, carrying a stable {@link ApiErrorCode} (a {@code DEPENDENCY_*}
* code in {@link OperationalError}) and the upstream dependency name.
* Framework-neutral carrier for a classified outbound HTTP (dependency) failure. Service code that
* classifies a raw network / HTTP exception rethrows it wrapped in this type, carrying a stable
* {@link ApiErrorCode} (a {@code DEPENDENCY_*} code in {@link OperationalError}) and the upstream
* dependency name. The template's HTTP client does not raise it.
*
* <p>The {@code diagnosticMessage} is <strong>SERVER-LOG-ONLY</strong> and must
* <strong>NEVER</strong> contain the upstream raw response body. See the module README for the