로그 줄이 남기지 말아야 할 값을 싣고, 남겨야 할 줄을 버린다. 401·403
보안 WARN, route를 못 찾은 요청 로그, 처리하지 못한 예외 ERROR가 원본
request URI(식별자·토큰이 든 경로)를 싣는다. outbox relay·파일 서버 정리
스케줄러는 실패를 통째로 남겨 SQL·제약 이름·값이 원인 사슬로 따라간다.
SamplingTurboFilter는 INFO 이하를 logger 구분 없이 표본으로 버려 감사
logger의 INFO 줄도 사라진다. JSON 로그 profile 칸은 Logback이 처음 읽은
환경 변수 값이라 Spring이 해석한 profile과 다를 수 있다. HeaderSanitizer는
운영 코드가 부르지 않는 공개 유틸리티로 남아 있다.
- LoggedPath: route template이 있으면 그것, 없으면 식별자가 들 수 있는
마디를 {}로 가린 경로. 세 줄이 모두 쓴다. 버린 안: 원본 URI 그대로 두고
문서로 경고(로그 수집기가 이미 받는다).
- 스케줄러 실패는 새 ServerFailureLog.forBackgroundTask로 남긴다: 분류된
persistence 실패는 원인 사슬 없이, 그 밖의 carrier는 client 쪽 코드여도
stack과 함께(요청이 없으니 결함이다). composition:outbox-relay에
shared-contract edge를 더한다(gradle/modules.json).
- SamplingTurboFilter는 AUDIT marker와 이름 끝 마디가 audit·security인
logger를 표본에서 뺀다(이름별 판정은 캐시).
- ResolvedProfileJsonProvider가 줄을 쓸 때의 해석된 profile을 쓴다.
- HeaderSanitizer와 시험을 지우고 capability-status 제거 표에 적는다.
위험: 경로를 보던 로그 검색이 가린 경로를 본다. 감사 줄이 표본에서 빠져
양이 늘 수 있다. docs/upgrade/2026-11-round9-observability.md 1~5행.
검증: desktop에서 바뀐 leaf check·:app-bootstrap:test·systemTest·
documentContractTest·repositoryContractTest, scripts/verify.sh pr rc=0
(묶음 셋을 합친 트리). 새 시험은 고치기 전 트리에서 실패했다(RED).
Refs: RR9-02-09, RR9-02-15, RR9-02-21, RR9-02-22, RR9-02-26
BREAKING CHANGE: 보안·요청·예외 로그 줄의 경로 값과 JSON profile 칸의 출처,
HeaderSanitizer 삭제. docs/upgrade/2026-11-round9-observability.md 1~5행.
51 KiB
adapter-web — 설계 결정 참조
인바운드 HTTP / 보안 어댑터 모듈. 패키지 루트: dev.caskeleton.adapter.inbound.web.
모든 서비스에 들어가는 leaf 이므로 servlet 운영 경로가 실제로 쓰는 코드만 둔다. 운영 경로가 닿지 않는
라이브러리형 패키지(streaming, virtual thread, patch, codec, OpenAPI 3.2, URI/method policy,
versioning, operation, budget, contract, security-context bridge, JsonIdempotentResponseCodec,
route inventory)는 opt-in leaf adapter:inbound:web-advanced 에 있다
(README).
허용/금지 의존, 경계 계약(B1B8), 스키마/직렬화 계약(S1S5), 비즈니스 규칙 검증 계약(C1~C8),
테스트 명령 같은 모듈 규칙은 AGENTS.md 가 SSOT 다. 이 문서는 코드 주석에서
덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할
때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로
풀어 둔다.
OpenAPI 계약 고정
Springdoc 3은 타입 없는 Java Object를 제약 없는 OAS 3.1 schema({})로 나타낸다.
OpenApiContractConfig가 공용 ApiError.details 필드에 대한 전송 계층 보정을 가지고 그 필드를
type: object로 낸다. 그래서 shared-contract에 Swagger 애너테이션이나 의존성을 더하지 않고 커밋한 HTTP
계약을 지킨다. 실제 서버 OpenAPI 시험은 이 운영 설정을 import하고 결과를 커밋한 snapshot과 비교한다.
auth — 인증 (OIDC resource server)
SecurityConfig
- Spring Security 기본 Cache-Control writer 비활성화. 이 모듈이
HTTP cache 헤더 정책을 소유한다(
CacheControlFilter가Cache-Control: no-store+Vary방출). 헤더의 단일·결정적 소유자를 보장하기 위해 Spring Security 자체의 기본 writer 를 끈다. - AuthN/AuthZ 분류기를
exceptionHandling과oauth2ResourceServer양쪽에 설정. entry point 는 missing-token(authorization-layer)과 invalid-token(bearer-filter-layer) 실패를, access-denied handler 는 403 을 담당한다. 두 곳 모두에 설정해야 bearer filter 와 authorization filter 가 동일한 Envelope writer 로 귀결된다.
JwtDecoderConfig
- Spring Boot auto-config decoder 를 대체해 validator chain 을 기본값 의존이 아닌 명시적 구성으로 만든다.
- D2 — clock skew 60s 명시 고정(
JwtTimestampValidator). framework 기본값에 의존하면 Spring 업그레이드로 기본값이 바뀔 때 silent-drift 위험이 있어 여기서 못박는다. - D4 — issuer 검증(
SecuritySettings.issuerUri()). D3 — audience 검증(SecuritySettings.audience()). JWT 모드에서 audience 는 필수이고(비면 기동 실패, 메시지에APP_SECURITY_JWT_AUDIENCE), 쉼표 목록을 받는다. 토큰aud가 설정 목록 중 하나라도 담으면 통과한다. "비우면 검사 생략"은 없앴다 — 같은 issuer 의 다른 client 용 토큰이 통과하기 때문이다(2026-11-01 리뷰 02-03·07-05, 소유자 결정 대안 A). 버린 대안: prod 프로필에서만 필수(dev·staging 이 열리고 보안이 프로필 이름에 걸린다), 문서 강조만. - role 범위:
JwtToAuthenticatedPrincipalConverter는realm_access.roles와,resource_access중 audience 목록에 있는 client 의 roles 만 읽는다. 다른 client 가 같은 이름의 role 을 정의해도 이 서비스 권한이 되지 않는다. client id 와 audience 가 다른 IdP 구성이 생기면 별도 키를 둔다(지금은 없음). - JWKS lazy discovery (
SupplierJwtDecoder): 기동 시 IdP 가 reachable 일 필요가 없고, 첫 decode 시점에 issuer-uri/.well-known네트워크 호출이 일어난다(Spring Boot auto-config 와 동일한 lazy 동작). lazy 초기화 중 외부 discovery/JWKS I/O 실패는 필터 밖 runtime exception으로 탈출시키지 않고AUTH_JWKS_UNAVAILABLE로 분류하며, 비-I/O 초기화 실패는INTERNAL_AUTH_MISCONFIGURATION으로 fail-closed 한다. 두 carrier 모두 고정 진단만 가지며 원격 응답/URL은 공개 응답에 넣지 않는다. - Minimal 결정: JWKS cache TTL 과 unknown-kid rate-limit 은 override 하지 않는다. 정확한 수치는 IdP-side token TTL 에 달린 NEEDS_CONTEXT 라 Nimbus/Spring 기본값을 쓰고 문서로만 남긴다.
jwtValidator가 package-private + static 인 이유: 네트워크/IdP 의존 없이 단위 테스트 가능하게 하려고.- audience validator 의 오류 description(
"The aud claim is not valid")은SecurityErrorClassifier의 "aud claim" 휴리스틱과 매칭되어AUTH_AUDIENCE_MISMATCH로 분류되도록 의도적으로 맞춘 문자열 계약이다.
JwtToAuthenticatedPrincipalConverter
principal필드를transient로 두는 근거: principal 은 매 인증마다 converter 가 재구성하며ObjectOutputStream으로 round-trip 되지 않는다. Redis session mode에서도 아래 primitive snapshot repository가Authentication객체 그래프를 저장하지 않는다. Serializable 이 아닌 Spring SecurityAuthentication토큰 필드의 관례적 해결책이 transient 표시다.
JWT / Redis session 상호배타 모드
app.security.auth-mode=jwt|redis-session은 하나만 선택한다. JWT mode는 stateless이고
CSRF/session repository를 만들지 않는다. Redis session mode는 Secure, HttpOnly, host-only
session cookie, SameSite=Lax, cookie/header CSRF와 migrateSession fixation 방어를 함께 켠다.
기본 HttpSessionSecurityContextRepository는 Spring Security 객체 전체를 session attribute에 넣어
outbound session codec의 primitive allowlist를 깨므로 사용하지 않는다.
PrimitiveSessionSecurityContextRepository가 AuthenticatedPrincipal의 bounded
principal/email/roles/authorities만 versioned byte[] snapshot으로 저장한다. credential, bearer/JWT,
arbitrary principal graph와 SPRING_SECURITY_CONTEXT 객체는 저장하지 않는다. foreign principal이나
손상·초과 snapshot은 인증 없음으로 fail closed한다. 실제 security filter save/restore 테스트가 다음
요청에서 principal과 authorities가 복원되고 session에는 primitive snapshot만 남는 것을 검증한다.
응답 본문 flush/redirect/error가 새 session보다 먼저 commit되지 않도록 repository가 Spring Security의
commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML 로그인 복귀용 request cache를
사용하지 않는 API 경계이므로 request cache를 명시적으로 비활성화한다. 따라서 미인증 요청이
DefaultSavedRequest 같은 framework object를 session에 넣지 않는다. app-bootstrap의
redisSessionHttpIntegrationTest가 TLS/ACL Redis와 서로 다른 세 개의 web context를 사용해 생성,
복구, logout tombstone, stale save 거부, 장애 시 controller 이전 fail-closed를 검증한다.
SecurityErrorClassifier
- AuthN/AuthZ decision matrix 구현. 실행 앱이 coarse 한 3-way 매핑 대신 registry(
docs/registries/error-codes.yaml)가 선언한 세분화 코드를 방출한다. - 메커니즘 & 트레이드오프: Spring Security 는 JWT 실패에 단일 typed reason 을 노출하지 않으므로,
classifier 가 예외 그래프와 validator/Nimbus 메시지 텍스트를 검사한다. 매핑:
- missing token →
InsufficientAuthenticationException→AUTH_TOKEN_MISSING - claim validators(
JwtValidationException) → description 에 따라AUTH_TOKEN_EXPIRED/AUTH_ISSUER_MISMATCH/AUTH_AUDIENCE_MISMATCH - decode/signature/unknown-kid(
BadJwtException/JwtExceptioncause) →AUTH_TOKEN_INVALID_SIGNATURE/AUTH_TOKEN_MALFORMED/AUTH_KID_UNKNOWN - JWKS endpoint 장애 →
AUTH_JWKS_UNAVAILABLE(503, transient)
- missing token →
- 텍스트 휴리스틱은 의도적으로 좁고 순서가 있다. 매핑되지 않은 실패는 500 이 아니라 안전한
AUTH_TOKEN_MALFORMED(401)로 폴백한다. AUTHZ_TENANT_MISMATCH는 여기서 추론 불가 — application-layer 의 cross-tenant 결정이며, 일반AccessDeniedException에는AUTHZ_INSUFFICIENT_PERMISSION만 방출한다.
EnvelopeResponseWriter
- 컨버터 밖에서 본문을 직접 쓰는 거부 응답(보안 entry point·access-denied handler·rate-limit
interceptor)이 쓰는 하나의 writer. status·
application/json·UTF-8·ErrorResponseFactory본문을 정한다. Tomcat 의 기본 응답 문자셋은 ISO-8859-1 이라 문자셋을 빠뜨리면 한국어 문구가???가 된다 (리뷰 02-04 — rate-limit 이 그랬다). 거부별 헤더(WWW-Authenticate,Retry-After,X-RateLimit-*)는 호출자가 본문을 쓰기 전에 붙인다. GraphQL body limit filter 는 다른 leaf 라 자기 writer 를 쓴다(UTF-8 지정).
AuthErrorResponseWriter
- 토큰/PII 리댁션. 응답 본문엔 해당
코드의 일반
client_safe_message만 담고, 원시 예외 텍스트·Authorization헤더·issuer·audience 는 절대 포함하지 않는다. 로그 라인엔 code/category/요청 path 만 기록하고 bearer token 은 절대 로깅하지 않는다(leak 테스트가 강제하는 계약). 전체 로그 마스킹 필터는 별도 log-management 영역에서 다룬다. - 로그 레벨. 4xx(토큰 누락·만료·서명·issuer·audience·kid 실패, 권한 부족)는 호출자 쪽 실패라 WARN이다.
5xx(
AUTH_JWKS_UNAVAILABLE503,INTERNAL_AUTH_MISCONFIGURATION500)는 서버 쪽 고장이라 ERROR다. 다른 경로가 5xx를 ERROR로 남기는 규칙(shared-contractServerFailureLog)과 같다. 레벨은 오류 코드 레지스트리의 칸이 아니라 이 코드가 정한다(설계 메모docs/design/2026-11-06-error-code-log-level-design.md). - WWW-Authenticate(RFC 9110 §15.5.2). 401 응답은 반드시 WWW-Authenticate 헤더를 갖되,
error_description으로 issuer/token 세부가 새지 않도록 최소한으로 유지한다.
EnvelopeAuthenticationEntryPoint
- AuthN matrix 구현(인증 실패를 세분화
OperationalError로 분류). - resource-server 인증 실패는 filter layer(
BearerTokenAuthenticationFilter/ExceptionTranslationFilter)에서 처리되어@RestControllerAdvice에 도달하지 않는다. 따라서 세분화 분류는GlobalExceptionHandler가 아니라 반드시 이 entry point 에 위치해야 한다.
EnvelopeAccessDeniedHandler
- AuthN/AuthZ decision matrix 의 AuthZ 분기(유효 토큰 + 권한 부족 →
AUTHZ_INSUFFICIENT_PERMISSION403). AUTHZ_TENANT_MISMATCH는 application-layer 의 cross-tenant 결정이라 일반 SpringAccessDeniedException으로는 추론 불가 — 여기서 방출하지 않는다.
authz — 인가 (@RequiresPermission 강제)
WebMethodSecurityAutoConfiguration — 인가는 인증 체인과 따로 켜진다
MethodSecurityConfig·AuthorizationAdapter·RolePermissionRegistry·RolePermissionPolicy(app.authz)는WebSecurityAutoConfiguration(JWT/session 체인)이 아니라 이 auto-configuration이 들여온다.- 이유: 인증 방식(체인)을 바꾸는 애플리케이션은
WebSecurityAutoConfiguration만 뺀다. 둘이 한 root에 있을 때는 체인을 빼면 advisor도 같이 빠져서, 그 애플리케이션의@RequiresPermission이 아무 경고 없이 주석이 됐다(지운 샘플 모듈이 그랬다 — 익명 삭제 가능). 이제 체인을 바꿔도 권한 검사는 남는다. - 메서드 보안까지 끄려면 이 클래스를 따로 exclude 해야 한다. 그 결정은 exclude 목록에 이름으로 드러난다.
MethodSecurityConfig
RequiresPermission강제 지점을 Spring method security 에 배선한다.@EnableMethodSecurity(prePostEnabled = false)— method-security 인프라는 켜되@PreAuthorize/@PostAuthorize인터셉터는 등록하지 않는다(의도적). 컨텍스트 내 유일한 authorization advice 가 아래 커스텀 advisor 가 되게 하기 위함.- 이 선택이 애플리케이션 계층을 Spring Security 애너테이션으로부터 자유롭게 유지(D1): 유스케이스는
프레임워크 독립적 plain 애너테이션
RequiresPermission만 선언하고 Spring-aware 강제는 이 어댑터가 공급. - advisor 는
ROLE_INFRASTRUCTUREstatic@Bean으로 등록 — 일반 싱글톤보다 먼저 인스턴스화되어 애플리케이션 빈을 조기 초기화로 끌어들이지 않는다.
RequiresPermissionAuthorizationManager
RequiresPermission의 Spring-aware 강제 메커니즘(커스텀AuthorizationManager<MethodInvocation>).- 가로챈 메서드(또는 선언 타입)에서 애너테이션을 읽고, 현재
Authentication을 프레임워크 독립적AuthorizationPrincipal로 매핑해 결정을 applicationAuthorizationPort에 위임한다. 따라서 application/domain 은 어떤 Spring Security 타입도 갖지 않으며, 이 어댑터가 두 세계가 만나는 유일한 지점이다. - 포트가 거부 시 application
AuthorizationDeniedException을 던지고, 이 매니저가 그것을 거부된AuthorizationDecision으로 변환한다. method-security 인터셉터가 이를AccessDeniedException→AUTHZ_INSUFFICIENT_PERMISSION403 으로 만든다(§4).null반환은 기권(abstain)이라 애너테이션 없는 메서드는 영향받지 않는다. - 매핑은 fail-closed: 미인증 요청이거나 우리
AuthenticatedPrincipal이 아닌 principal 은 0개 role 로 해석되어 거부된다.
AuthorizationAdapter
- application
AuthorizationPort의 web-adapter 구현체. - 결정은 fail-closed: principal 의 유효 권한 집합에 요구 권한이 없으면
AuthorizationDeniedException으로 거부 →RequiresPermissionAuthorizationManager가 변환 → 최종AUTHZ_INSUFFICIENT_PERMISSION403.
RolePermissionRegistry
- 호출자의 raw role 들을 유효
Permission집합으로 해석한다. - role 키를 소문자로 normalize: Keycloak 이 role 대소문자를 보장하지 않으므로 조회를 대소문자 무관으로.
- 권한은 role 별로 명시적으로 열거한 집합이며 와일드카드(예:
worklog:*)는 의도적으로 미지원 — 미래의worklog:delete가 암묵적으로 부여되지 않도록(least-privilege, OWASP-AUTHZ-C4; §3 default B). - 해석은 fail-closed: 알 수 없는 role / 빈 role 집합 / 빈 registry 모두 0개 권한.
RolePermissionPolicy
- app-side role→permission 매핑 소스.
- 키가 raw IdP role 이름인 이유:
ROLE_접두사는 SpringGrantedAuthority에만 있고 principal 의 raw role 집합엔 없으므로 붙이지 않는다. - startup-bound static config 라 staleness 가 없다.
- app-side config 를 기본값으로 택한 근거: resource server 를 IdP 의 permission-claim 발급으로부터 디커플링한다. IdP-authoritative 소스(Keycloak Authorization Services / permission claims)는 본 contract 에서 의도적으로 out-of-scope 인 대안이다.
error — 에러 → Envelope 변환
GlobalExceptionHandler
스켈레톤 공통 기반 에러 → Envelope 변환기.
- D5: RFC 7807
ProblemDetail표현은 거부하고 자체Envelope형식을 쓴다. - 운영/전송/보안 예외만 처리한다. 도메인 예외는 소비 모듈의 별도
@RestControllerAdvice가 처리하고 Spring 이 두 advice 를 합성(compose)한다(AGENTS.md 의@Order(HIGHEST_PRECEDENCE)규칙 참조). - 클라이언트 메시지는 allowlist다. 예외 메시지, validation interpolated message, rejected
request value, raw request URL은
error.message/details에 넣지 않는다.error.message는 항상 shared-contractClientErrorMessages의 Category 별 한국어 문구다(소유자 결정 11 — GraphQL·gRPC 도 같은 표).ErrorResponseFactory는 message 인자를 받지 않으므로 호출자가 문구를 만들 수 없다. 더 알려야 할 것은 정규화된 server-owned field, allowlisted reason code/fixed message, expectedType, parameter, supported-method 같은 bounded 구조 메타데이터로details에 둔다. collection/map index와 key는 field path에서 제거한다. ApiErrorCarrier(sharedMappingException·AdapterDisabledException·PersistenceFailureException·DependencyFailureException, application 멱등성·분산 락 예외, adopter 예외)는handleCarrier분기 하나로 매핑한다. 5xx 는 원인과 함께 로그를 남기고(persistence 는 분류만), retryable 코드는RetryAfterAdvisor로Retry-After를 붙인다.- carrier 를 다른 예외로 감싸 던져도 같다.
handleUnknown(그 밖의 예외)과handleIllegalArgument는 원인 사슬의 첫 carrier(ApiErrorCarrier.firstIn)를 찾아handleCarrier로 넘긴다. 감싼 persistence 실패도 500INTERNAL_ERROR와 SQL 원인 대신 그 분류 코드와 분류 한 줄로 남는다. GraphQL·gRPC·STOMP 도 같은 함수를 쓴다(소유자 결정 2026-11-06, 재리뷰 RR7-01-05). - 인자 변환 단계는 원인의 carrier 를 보지 않는다. 경로 변수·쿼리 파라미터가 바뀌지 않은
MethodArgumentTypeMismatchException은BAD_PARAMETER, 읽지 못한 본문의HttpMessageNotReadableException은VALIDATION_FAILED다. 사용자Converter나 Jackson creator 가 carrier 를 던져 그 원인에 있어도 같다. 요청 형식 오류이고 그 코드는 전송이 정한다(소유자 결정 2026-11-07, 재리뷰 README 19.4절 ④). STOMP 도 같은 실패를 거부로 남긴다. 단언은TransportErrorHandlingTest. - 개별 override 가 없는 Spring MVC 예외(필수 파라미터·헤더·part 누락, binding 실패 등)는
handleExceptionInternaloverride 가 상태 코드 → 코드로 바꿔 같은 Envelope 로 보낸다. 503(Spring 의 async 요청 시간 초과)은INTERNAL_ERROR가 아니라REQUEST_TIMEOUT(503, retryable) 이다(리뷰 02-08).application/problem+json은 나가지 않는다(I-3a). - carrier 가
ClientSafeErrorDetails도 구현하면 그 값이error.details가 된다(web-advanced 의 patch pointer·거절 경로). 코드가RetryAfterHint를 구현하면Retry-After값은 그 코드가 정한다. - 등록은 한 곳이다.
WebMvcPlatformAutoConfiguration의@ConditionalOnMissingBeanbean 하나뿐이다.app.web.mvc.enabled=false면 이 핸들러·요청 id 필터·JSON 본문 상한·중복 키 거부가 함께 빠지고, 서비스가 셋을 직접 준다. 같은 타입 bean 을 주면 그것만 쓰인다(리뷰 02-10,WebMvcPlatformAutoConfigurationTest). adapter-web에 위치하는 이유: 실행 앱이 기능 모듈 없이도 envelope 형식 에러 응답을 제공하도록.spanErrorRecorder. 프로덕션 코드를 특정 트레이서 라이브러리에 결합하지 않고 span 에러를 기록하기 위한 이음새. 기본값SpanErrorRecorder.NOOP.@Autowired생성자가ObjectProvider로 self-default 하므로 전체 컨텍스트 /@WebMvcTest슬라이스 / 순수 단위 테스트 모두 seam 빈 등록을 강제하지 않고 와이어링된다. Micrometer Tracing fork 는 자체SpanErrorRecorder빈만 등록하면 no-op 을 오버라이드한다.
예외 → 에러코드 → HTTP 상태 매핑 계약 (매핑 자체는 코드가 SSOT; 아래는 근거):
| 예외 | 코드 | 상태 | 근거 |
|---|---|---|---|
MappingException |
MAPPING_FAILED |
400 | B3: 매퍼 내부 실패는 MAPPING_FAILED 로, BAD_PARAMETER/INTERNAL_ERROR 로 보내지 않음 |
AdapterDisabledException |
ADAPTER_DISABLED |
500 (retryable=false) | Layer 3 런타임 fail-fast(integration-adapter-templates §4/D4). 시작-수명주기용 REQUIRED_ADAPTER_DISABLED 가 아님(§Audit A2). 예외 메시지의 어댑터 이름은 서버 로그용, 클라이언트는 category 문구만 |
IllegalArgumentException |
BAD_PARAMETER |
400 | B3: 매퍼가 아닌 호출자의 일반 예외 |
ConstraintViolationException |
VALIDATION_FAILED |
400 | 정규화된 field + allowlisted reason code/fixed message 리스트를 details 로. interpolated message와 iterable key/index는 미노출 |
MethodArgumentTypeMismatchException |
BAD_PARAMETER |
400 | parameter·expectedType 을 details 로 |
HandlerMethodValidationException |
VALIDATION_FAILED |
400 | 컨트롤러 파라미터 제약(@RequestParam @Max(10)) 위반. 요청 본문 위반과 같은 코드·같은 details 모양(field=파라미터 이름, code=제약). 거절된 값은 미노출(리뷰 02-08) |
InvalidIdempotencyKeyException |
IDEMPOTENCY_KEY_INVALID |
400 | IdempotencyKeyHeader.parse 가 헤더 누락·문법 밖을 거부. details.reason = MISSING/MALFORMED, 키 원문 미노출(리뷰 02-12) |
InvalidBearerTokenException |
INVALID_TOKEN |
코드 상태 | |
AuthenticationException |
UNAUTHENTICATED |
코드 상태 | |
AccessDeniedException |
SecurityErrorClassifier 결정(예: AUTHZ_INSUFFICIENT_PERMISSION) |
분류기 결정 | 메서드-시큐리티 거부가 컨트롤러를 빠져나오면 여기 도달. 필터 계층 EnvelopeAccessDeniedHandler 와 동일한 세분화 코드를 내도록 무상태 classifier 에 위임 |
PreconditionFailedException |
PRECONDITION_FAILED |
412 | D15: If-Match 불일치 쓰기 = 낙관적 동시성 충돌 → 412 (raw 409/500 금지) |
PageValidationException |
VALIDATION_FAILED |
400 | D18/D20/D21: 계약 범위 밖 페이지/정렬/필터 파라미터. field + reasonCode 를 details 로 |
IdempotencyUnavailableException |
IDEMPOTENCY_UNAVAILABLE |
503 (retryable=true) | action 전에 거부 — 조정 저장소가 응답하지 않았거나, claim의 processing lease가 시작 전에 끝나 저장소가 시작을 거절했다(실행 안 됨, 저장소는 정상일 수 있다). 같은 키로 나중에 재전송하면 다음 요청이 그 claim을 넘겨받아 실행한다(docs/web/http-contract.md §2, 라운드6 RR6-02-04). carrier 분기 |
IdempotencyCompletionUnknownException |
IDEMPOTENCY_COMPLETION_UNKNOWN |
503 (retryable=true) | action 이 돈 뒤 결과 기록(complete) 중 저장소가 응답하지 않음. 결과 불명 — 같은 키로 재전송, 새 키 금지(docs/web/http-contract.md §2, 재리뷰 RR-02-03). carrier 분기 |
IdempotencyRecoveryRequiredException |
IDEMPOTENCY_RECOVERY_REQUIRED |
500 (retryable=false) | 이전 시도의 외부 효과 여부를 판단할 수 없음. carrier 분기 |
IdempotencyInFlightException |
IDEMPOTENT_IN_FLIGHT |
409 (retryable=true, Retry-After: 2) |
같은 scope 의 다른 시도가 아직 처리 중(executor 는 기다리지 않는다). 클라이언트 행동: 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지(docs/web/http-contract.md §2). 진단정보(scope digest)는 클라이언트 미도달 |
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_*) |
코드 결정 | 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 전용 코드는 없다) |
HttpMediaTypeNotAcceptableException |
NOT_ACCEPTABLE |
406 | D9: Accept 에 맞는 표현 없음 — 415 와 구별(합치면 RFC 9110 의미론 상실) |
MethodArgumentNotValidException |
VALIDATION_FAILED |
코드 상태 | 정규화된 field + allowlisted reason code/fixed message 리스트를 details 로. rejectedValue/defaultMessage/iterable key/index는 secret/PII 가능성이 있어 미노출 |
HttpMessageNotReadableException |
VALIDATION_FAILED |
코드 상태 | cause 클래스명을 details 로 |
NoHandlerFoundException, NoResourceFoundException |
ROUTE_NOT_FOUND |
코드 상태 | controller/static-resource 어느 404 경로도 같은 Envelope를 사용하고 raw request URL을 echo하지 않음 |
AsyncRequestTimeoutException |
REQUEST_TIMEOUT |
503 (retryable=true) | Spring 이 503 으로 분류한 일시적 시간 초과. 이전에는 INTERNAL_ERROR 500 이었다(리뷰 02-08) |
그 밖의 Spring MVC 예외(MissingServletRequestParameterException, MissingRequestHeaderException, MissingServletRequestPartException, ServletRequestBindingException …) |
상태 → 코드(4xx 는 대개 BAD_PARAMETER, 나머지 5xx 는 INTERNAL_ERROR) |
코드 상태 | handleExceptionInternal override. problem+json 이 새지 않게 |
ApiErrorCarrier (위에 없는 adopter 예외 포함) |
errorCode() |
코드 결정 | handleCarrier 한 분기 |
Exception (catch-all) |
INTERNAL_ERROR |
500 | span 에러 기록 + 불투명 문구(ClientErrorMessages.OPAQUE) |
ErrorResponseFactory
- 기반 운영 핸들러와 모든 도메인 핸들러가 공유하여 envelope 형식이 정확히 한 곳에서만 만들어지게
하는 단일-소스 컴포넌트(
httpStatus()→ SpringHttpStatus매핑,error.category운반, MDC 에서meta추출).
envelope / filter
EnvelopeBodyAdvice
- 컨트롤러는 도메인/DTO 타입을 반환하고, 이 advice 가 와이어 형태를 항상
{success, data | error, meta}로 보장한다. - null 필드는 키째 생략한다. 성공에는
error키가, 실패에는data키가, 단일 아이템meta에는page키가 없다. 빈 목록은 생략하지 않는다. 규칙은EnvelopeWireFormatConfig의 Jackson mix-in 이 BootJsonMapper에 등록한다(shared-contract 는 Jackson 에 의존하지 않으므로 타입에 애너테이션을 달지 않는다). 키 목록과 근거는docs/web/http-contract.md§1, 원문 키 집합 단언은EnvelopeWireShapeTest. - 이미 직렬화된
byte[]본문은 감싸지 않는다. 그 본문을 쓰는 converter 는 받은 값을 그대로 복사하므로 envelope 객체를 받으면 500 으로 끝난다. springdoc 이 OpenAPI 문서를byte[]로 돌려주어, 감싸던 시절에는 실행 중인 앱의/api/v3/api-docs가 항상 500 이었다(리뷰 09-04).String반환은 감싸되 JSON 문자열로 직렬화해 넘긴다(리뷰 02-06). 단언은EnvelopeBodyAdviceTest. String반환도 JSON 클라이언트에게는 Envelope 다.String은StringHttpMessageConverter가 Jackson 보다 먼저 고른다. 예전에는 그 컨버터에Envelope객체를 넘겨Accept: application/json이면ClassCastException500,*/*면 200 text 였다(리뷰 02-06). 지금은 String 컨버터가 JSON 을 쓰게 될 때 advice 가 같은 mapper 로 Envelope 를 문자열로 직렬화해 넘긴다. 텍스트를 요청한 클라이언트는 그대로 문자열을 받는다. ArchUnit 으로String반환을 금지하는 안은 버렸다:text/plain엔드포인트의 정당한 용도를 막고, 규칙을 돌리지 않는 서비스에는 함정이 그대로 남는다.- 4xx·5xx 본문은 감싸지 않는다.
success는 클라이언트가 가르는 판별자라, 오류 status 본문을success:true로 감싸면 성공으로 읽힌다. Boot/error의 map 이 그렇게 나갔다(재리뷰 RR-02-02). - 위치: adapter-web. 실행 앱이 늘 싣는 leaf 라, 응답 래핑이 실제로 동작하려면 여기 있어야 한다.
EnvelopeErrorController
- 컨트롤러에 닿기 전에 생긴 오류(보안 방화벽의
RequestRejectedException, 필터의sendError, 필터가 던진 예외)는GlobalExceptionHandler를 지나지 않고 컨테이너의/error디스패치로 간다. Boot 기본BasicErrorController는 거기서{timestamp, status, error, path}를 썼고, advice 가 그것을success:true로 감쌌으며path는 요청 경로 원문이었다(재리뷰 RR-02-02). 이 컨트롤러가 그 자리를 대신해 status 를GlobalExceptionHandler와 같은 표(HttpStatusErrorCodes)로 코드에 매핑하고 실패 Envelope 를EnvelopeResponseWriter로 쓴다. 요청에서 가져온 값은 싣지 않는다. - 필터가 던진 예외는
GlobalExceptionHandler를 지나지 않으니ServerFailureLog의 줄(persistence 는 분류만)도 없다. 대신 컨테이너가/error로 넘기기 전에 그 예외를 원인 사슬째 ERROR 로 남긴다. Tomcat 은 loggerorg.apache.catalina.core.ContainerBase.[…].[dispatcherServlet]에Servlet.service() for servlet [dispatcherServlet] … threw exception과 스택을 쓰고, persistence 실패의 SQL 원인(값·제약 이름·접속 문자열)도Caused by:로 그대로 실린다. 필터에서 저장소나 외부 의존을 부르면 실패를 필터에서 잡아EnvelopeResponseWriter로 답하고, 로그 줄은ServerFailureLog.of로 정한다. 단언은 실제 Tomcat 의FilterFailureContainerLogIT(systemTest, 2026-11-07). Jetty 는 확인하지 않았다. WebMvcPlatformAutoConfiguration이ErrorMvcAutoConfiguration보다 먼저ErrorController가 없을 때만 등록한다. 어댑터가 자기ErrorController를 두면 물러난다.SecurityConfig는 오류 디스패치만 허용한다(DispatcherType.ERROR). 예전에는/error가 공개 경로가 아니라서 익명 요청의 400 이 401 로 바뀌었다./error를 직접 부른 요청은 여전히 인증이 필요하다. 단언은 실제 Tomcat 의TomcatWebContractIT(공유WebContractAssertions)와JwtChainErrorDispatchIT.- 앱이 보안 체인을 직접 정의하면(예: 데모용 체인) 같은 한 줄
(
dispatcherTypeMatchers(DispatcherType.ERROR).permitAll())을 그 체인에도 둬야 원래 status 가 나간다.
CacheControlFilter
- 스켈레톤 기본 HTTP 캐시 정책.
Cache-Control: no-store는 인증된 API 의 안전한 기본값.Vary: Accept, Accept-Encoding, Authorization로 공유 프록시/CDN 이 협상이나 주체를 가로질러 콘텐츠를 오염(poison)시키지 못하게 한다.- 기본값을 체인 이전에 설정: 캐시 가능한 엔드포인트가 반환값 처리에서
Cache-Control(예:private, max-age=60)을 가진ResponseEntity를 반환해 기본값을 덮어쓰는 opt-in 이 가능하도록. - 책임 경계: 이 모듈은 캐시 헤더 정책을 소유하고, 캐시 레이어(Redis/CDN)는 별도 인프라가 소유한다.
- 단일 소유권: Spring Security 기본
Cache-Control은SecurityConfig에서 비활성화 → 실행 앱에서 이 필터가 헤더 단일 소유자. 독립 MockMvc(보안 체인 없음)에서도 이 필터가 유일 writer.
WebMvcRequestIdFilter / RequestLoggingFilter
- id 는 한 곳에서 만든다. request/correlation/trace/span id 발급, MDC 기록, 응답 헤더(
X-Request-Id,X-Correlation-Id,traceparent)는WebMvcRequestIdFilter(HIGHEST+10, Spring Security 앞)가 한다. 그래서 보안 체인이 쓰는 401/403 Envelope 의meta도 id 를 가진다.RequestLoggingFilter는 id 를 만들지 않고 접근 로그 한 줄과user_principal만 담당한다(principal 을 읽으려고 보안 체인 안쪽에서 돈다). 보안 체인이 거절한 요청의 로그는 entry point / access-denied handler 가 남긴다. 아래 traceparent 규칙은WebMvcRequestIdFilter의 것이다. - MDC 키 정책(D11/D19).
MdcKeys의 snake_case 키 사용. - 인바운드 id 헤더(D14/D15).
X-Request-Id는 기본적으로 받지 않고 서버가 만든다(신뢰 설정 시 안전 문자만).X-Correlation-Id는 요청 id 와 같은 규칙([A-Za-z0-9._-]{1,128}, 앞뒤 공백 제거)을 통과하면 그대로 잇고, 아니면 서버가 새로 만든다. 예전에는 제어문자만 지우고 200자까지 그대로 내보내 공백·유니코드·DEL 이 응답 헤더와meta.correlationId에 실렸고, 짝 프론트의 envelope 검증([A-Za-z0-9._:-]{1,128})이 그 응답 전체를 거절했다(리뷰 02-11). 고친 값을 쓰지 않고 바꾸는 이유: 고친 값은 더 이상 호출자의 값이 아니라 상관관계를 잇지 못한다. - W3C
traceparent(D5/D7/D4). 유효한 인바운드 traceparent 가 있으면 채택해 그traceId→MDCtrace_id,spanId→span_id. 부재/공백/무효면 fresh ROOT traceparent 생성(32-hex traceId, 16-hex spanId, sampled=false)하여 MDCtrace_id가 항상 의미 있는 W3C id 이고 절대 null 이 아니게 한다(D4: 추적 비활성 상태에서도meta.traceIdnon-null 보장). 해석된 traceparent 는 응답 헤더에 설정.sampled=false근거: tracer seam 이 실제 sampling 결정을 소유하며 스켈레톤엔 exporter 가 없다.freshHex16근거: 16-char span id 는 fresh UUID 의 least-significant bits 에서 파생·zero-pad — 64비트 전체가 entropy 를 갖도록(UUIDv4 version nibble 은 most-significant bits 라 제외). variant bits 가 값을 non-zero 로 유지해 W3C non-all-zero 규칙 충족.
- 사용자 주체 가명화.
user_principal은 MDC 에 놓이기 전UserPrincipalPseudonymizerPort로 가명화. rawidpUserId()는 절대 MDC/로그에 기록되지 않는다. - route template 해석. 저-cardinality 매칭 라우트 템플릿 반환.
BEST_MATCHING_PATTERN_ATTRIBUTE는 handler mapping 이후 DispatcherServlet 이 설정하므로finally블록에서 항상 사용 가능. - 주의 — 생성된
trace_id는 실제 span 의 trace-id 가 아니다. 무-tracer 스켈레톤에선 이 필터가(인바운드 traceparent 부재 시)trace_id를 발급(MINT)하고ResponseMetaFactory가 이를meta.traceId로 투영한다. fork 가 Micrometer Tracing 을 켜면 OTel SDK 도 같은 요청에 trace-id 를 발급하고 SLF4J-Micrometer 브리지가 자신의 id 를 MDCtrace_id에 쓴다. 어느 값이 최종 반영될지는 필터/observation 의 ORDER 와 scope 에 달려 있다 — 이 필터가 이기면 클라이언트의meta.traceId가 실제 export 된 span 의 trace-id 와 불일치해, "응답 id 로 trace 조회"라는 D4 의 핵심 목적이 조용히 깨진다. 실제 tracer 를 연결하는 fork 는 tracer 가 MDCtrace_id의 유일 소유자가 되게 해야 한다(이 필터를 tracing observation 이후로 정렬하거나, 생성 대신Span.current()채택). 현 green 테스트 스위트는 이를 잡지 못한다 — 무-tracer 메커니즘만 검증한다.
ratelimit
provider 중립 edge 계약
- inbound web은
shared-contract의EdgeRateLimitPort만 호출한다. Redis key, Lua, local counter와 provider 설정을 알지 못한다. - outbound provider activation SSOT는
app.capabilities.rate-limit.provider=disabled|redis이고, HTTP enforcement의 별도 축은app.rate-limit.enabled다. transport가 enabled인데 exact provider가 없거나 중복이면 startup을 실패시킨다. - fixed window, sliding counter, token bucket 선택과 policy revision은 Redis provider가 소유한다. 과거 process-local unbounded fixed-window map/factory/settings는 제거되었다. local emergency가 필요하면 bounded cardinality/TTL/in-flight와 명시적 degraded-provider 계약을 먼저 추가해야 하며, silent primary fallback은 허용하지 않는다.
EdgeRateLimitTransportBridge는 provider의 typed allow/deny/unavailable/incompatible outcome을 HTTP 2xx/429/503과Retry-After로만 투영한다. timeout은 quota가 소비되지 않았다는 증거가 아니다.
RateLimitKeyResolver
- 키 형태: service-to-service
apikey:<id>(api_key_id override), 인증user:<id>, 미인증ip:<source-ip>:<METHOD route-template>(정규화). - principal 은 로그
user_principal(AuthenticatedPrincipal#idpUserId)과 동일 표현 재사용. pseudonymization 은 이 영역의 책임 seam — 이 브랜치는 표현을 재사용만 하고 변환하지 않는다. - tenant prefixing 은 아직 구현하지 않은 확장 지점이다.
- 하드 룰: 키는 raw 토큰이나 요청 본문에서 절대 도출하지 않는다.
HandlerInterceptor입력으로 resolve 하는 이유: route template(/v1/worklogs/{id})을 쓰기 위함. servlet filter 는 handler mapping 이전에 실행돼 구체 경로만 보므로 모든 id 가 서로 다른 키가 되어버린다.
클라이언트 IP
- 비인증 키의 IP 는
getRemoteAddr()하나다. 헤더를 직접 읽는 모드는 없다. XFF 맨 왼쪽 값(호출자가 쓰는 값)을 키로 써서 지웠다(docs/capability-status.md「제거된 코드」). - 프록시 뒤에서는
server.forward-headers-strategy=native+server.tomcat.remoteip.internal-proxies로 Tomcat 이 신뢰 프록시에게서 온 XFF 만 반영한다.framework는 모든 peer 를 믿으므로RateLimitWebConfig가 기동을 거부한다.
RateLimitWebConfig
- servlet filter 가 아니라 interceptor 를 쓰는 이유: 비인증 키에 필요한 route template 이 interceptor 단계에서 resolve 되기 때문(RateLimitKeyResolver 참조).
@EnableConfigurationProperties근거: 앱 레벨@ConfigurationPropertiesScan을 돌리지 않는@WebMvcTest슬라이스에서도EdgeRateLimitTransportSettings를 쓰게 하려고.Clock은 공유 application bean 이 있으면 가져오고 슬라이스에선Clock#systemUTC()로 fallback.
RateLimitInterceptor
- provider가 선택한 rate-limit policy를 매핑된 handler 실행 전에 적용. quota 결과에는
X-RateLimit-*헤더를 포함한다(generated_if_missing=true). - 한도 초과 거부 응답의 세 보장(RATE_LIMIT category + retryable +
Retry-After)이 클라이언트가 이를 retryable 의존성 장애로 오분류하는 것을 막는다. - 본문은
EnvelopeResponseWriter로 쓴다(UTF-8).
settings / config / http
CorsSettings
- 3계층 검증 전략.
- 단순 제약(범위/필수/정규식)은 JSR-303 +
@Validated로 선언해 잘못된 값이BindValidationException으로 기동 실패(maxAgeSeconds). - JSR-303 로 표현 불가한 조건부/교차필드 규칙은 compact constructor 의 fail-fast
throw로 강제(관대한 기본값 폴백 금지). - 정상 기본값(CORS disabled 시 빈 origins, 미설정 method/header)은 invalid 가 아니라 합리적 기본값으로 채움.
- 단순 제약(범위/필수/정규식)은 JSR-303 +
- 교차필드 불변식: CORS enabled 시 최소 하나의 allowed origin 필수(JSR-303 표현 불가 → fail-fast). 빈 목록 관대한 폴백은 모든 브라우저 호출자를 조용히 거부하게 된다.
- D9 (WHATWG Fetch §3.3, FETCH-CORS-C3): wildcard origin + credentials 금지 —
Access-Control-Allow-Origin: *는Access-Control-Allow-Credentials: true와 함께 보낼 수 없다. Spring 런타임 검사에 의존하지 않고 기동 시점에 fail-fast 거부.
CorsExposedHeaders
- 브라우저는 CORS 안전 목록 밖의 응답 헤더를
Access-Control-Expose-Headers에 없으면 숨긴다. 예전에는 노출 목록이 비어 cross-origin 클라이언트가Retry-After·X-Request-Id·Location·tus offset 을 못 읽었다(리뷰 02-05). SecurityConfig는CorsExposedHeaders.PLATFORM(이 leaf 가 쓰는Retry-After,X-Request-Id,X-Correlation-Id,traceparent,Location,ETag,X-RateLimit-*)에 모든CorsExposedHeadersbean 을 더해 노출한다. 헤더를 쓰는 모듈이 기여한다(RestrictedPathRule과 같은 방식). web-fileserver 는 tus·draft-12 헤더와Content-Disposition·Accept-Ranges를 기여한다.- 설정 키(env)로 열지 않은 이유: 노출할 헤더는 코드가 쓰는 헤더라 운영자가 고를 값이 아니다. env 로 두면
기본 배포가 계속 깨지거나 모듈과 목록이 따로 논다.
*는 credentials 모드에서 리터럴 이름으로 취급돼 쓰지 않는다. 노출 헤더는 실제 응답에만 붙는다(preflight 에는 의미가 없다).
EdgeRateLimitTransportSettings
app.rate-limit.*은 HTTP enforcement, default policy ID, pseudonymization key version, caller deadline, trusted client-IP mode만 소유한다.- algorithm/quota/state TTL/HMAC secret는 outbound Redis capability 설정이 소유하며 web settings로 복제하지 않는다.
SecuritySettings
- OIDC resource-server 설정.
issuerUri는 인증이 연결될 때 필수 — 없으면 Spring Boot oauth2 auto-config 가 기동 시 실패하므로 여기서 명확한 에러를 먼저 표면화한다. 나머지 knob 은 warn 후 폴백. app.security전체(인증 모드 포함)의 유일한 소유자다.SecuritySettingsConfig가 support 의StrictSettingsBinder로 묶어(리뷰 07-10) 철자가 틀린 키(app.security.audence)나 어떤 설정도 아닌APP_SECURITY_*환경 변수가 있으면 기동을 거부한다. 예전@ConfigurationProperties스캔 바인딩은 둘 다 무시했다. bootstrap 의 인증 모드 검사도 이 bean 의authMode()를 읽는다(같은 prefix 를 두 번 바인딩하지 않는다). 슬라이스 테스트는@Import(SecuritySettingsConfig.class)로 운영과 같은 바인딩을 쓴다.
PresentationSettings
- 검증 정책 "warn-and-default": 부재/잘못된 prefix 값은 앱을 멈추는 대신 빈 prefix 로 폴백 — 모든 엔드포인트가 (/api 없이) 계속 접근 가능하게 유지.
JacksonNullableConfig
JacksonNullableConfig가JsonNullable처리기 모듈(JsonNullableJackson3Module)을 Spring 관리ObjectMapper에 등록. 없으면 PATCH 요청 DTO 의JsonNullable<T>(B2)를 Jackson 이 역직렬화하지 못해 absent / explicit-null 구분이 조용히 붕괴된다.- 스켈레톤 전역 web 관심사(공유
Patch<T>타입과 짝)라 기능 모듈이 아니라 adapter-web 에 위치.
IdempotencyKeyHeader
- KEYED 엔드포인트가 헤더를 키로 바꾸는 유일한 지점(리뷰 02-12). 문법: 보이는 ASCII(
0x21–0x7E) 1~256자, trim·재작성 없음 — 짝 프론트의isValidIdempotencyKey와 같은 규칙. - 누락과 형식 오류는 둘 다
400 IDEMPOTENCY_KEY_INVALID(details.reason=MISSING/MALFORMED). 헤더는required = false로 받고IdempotencyKeyHeader.parse를 부른다.required = true면 누락이BAD_PARAMETER로 먼저 나간다. - 공용으로 만든 것은 추출뿐이다. claim·fingerprint·replay 는 use case 와
IdempotencyExecutor가 소유한다 (아래 idempotency 절). 대안 — 엔드포인트마다 검증(현상 유지)은 복사본이 갈라지고, 모든 POST 에 강제하는 필터는 KEYED 가 아닌 엔드포인트까지 막아 버렸다.
ApiHeaders
- 인바운드 web 어댑터 전역의 HTTP 헤더명 상수 —
docs/registries/headers.yaml의 코드 미러. 리터럴을 중앙집중해 controller/filter/advice 가 casing 으로 drift 하지 않게 하고, 레지스트리 일관성 테스트가 단일 출처를 참조하게 한다. - 소유권:
X-Api-Version(D2)·Idempotency-Key(D3 — 이름만; key shape/scope/replay 정책은 application-core 소유)는 여기서 생산. conditional-request(D15)·cache(D16)·method/negotiation/ LRO(D12/D17)·pagination(D18)·rate-limit signaling(generated_if_missing=true; Limit/Remaining 은 numeric, Reset 은 rfc3339 = fixed-window end)·deep-offset deprecation marker(D18)·always-emitted(D24)는 표준 RFC 9110/9111 이름 참조.
observability
MdcKeys
- 키 상수는 shared-contract
observability/MdcKeys가 소유한다(GraphQL·WebSocket·gRPC 도 같은 이름을 쓰도록 web 에서 옮겼다). snake_case MDC 키 이름은 로그/진단 레지스트리(mdc-keys.yaml)를 따른다. 같은 논리 ID 의 envelope 형태(camelCase)와 HTTP 헤더 형태(kebab-case)는 D19 projection 이며, 변환 단일 지점은ResponseMetaFactory.
LoggedPath
- 서버 로그 줄이 요청을 부르는 경로 하나다. 401·403 보안 줄의
path=(AuthErrorResponseWriter), 요청 로그 줄의uri_template=(RequestLoggingFilter), 처리하지 못한 예외 줄(GlobalExceptionHandler)이 같이 쓴다. - DispatcherServlet이 handler를 고르면 그 pattern(
/v1/orders/{id})이다. 정적 자원 handler가 받은 없는 경로는/**다. 그 밖(보안 chain이 dispatch 전에 거부한 요청, 어떤 handler mapping도 받지 않은 요청)은 요청 경로에서 값이 들 수 있는 마디를{}로 가린다. 글자·하이픈만인 마디와 API 버전(v1)만 남기고, 8마디까지만 쓴다. - 모양으로 가르는 규칙이라 가장자리가 둘이다. 글자만인 값(
/users/alice)은 남으니 경로에 이름을 넣는 route는 id로 바꾼다. 숫자나 점이 든 route 글자(oauth2,.well-known)는 값처럼 가려진다. handler가 고른 요청은 pattern으로 남아 둘 다 해당하지 않는다.
MdcCorrelationIdPortAdapter
WebMvcRequestIdFilter가 무해화하고 MDCcorrelation_id에 넣은 값을 application-core의CorrelationIdPort로 투영한다.- absent/blank는
Optional.empty()로 반환한다. application 계층은 SLF4J/MDC를 직접 참조하지 않고 event-id fallback 정책만 소유한다.
ResponseMetaFactory
- snake_case MDC 진단 키를 camelCase
ResponseMetawire 객체로 projection 하는 D19 단일 변환 지점. adapter-web 에 위치하는 이유: shared-contract 는 프레임워크 중립이라 MDC 를 읽으면 안 된다.
RetryAfterAdvisor
Retry-After노출 지점. 구체 헤더 값과 429/503 세부는 이 영역의 책임이고, per-coderetry_after_seconds는 error-codes.yaml 에 존재한다. 이 helper 는 "재시도 가능한 코드가Retry-After헤더를 받을 자격이 있는가?"만 답해, 호출부가 재시도 가능 여부를 재도출하지 않고 헤더를 붙이게 한다.- Tracing wiring: 운영 5xx 는 서버 span 에
exception이벤트 + span status ERROR 를 기록해야 하나, Micrometer-Tracing/OTel 가 classpath 에 없어 wiring 은 이 영역의 책임 — 의도적 미구현. - 필드
RETRY_AFTER_SECONDS는 error-codes.yaml 의retry_after_seconds컬럼 미러. 이 advisor 가 유일한 Retry-After 노출 지점이라 여기 중앙화한다.DEPENDENCY_4XX_CLIENT는 비재시도(retryable=false)라shouldAdvise가드로 empty 반환. - 다른 leaf 가 소유한 코드는 이 표에 이름으로 넣지 않고
RetryAfterHint를 구현해 값을 스스로 말한다 (web-advancedWebAdvancedError). 서버 포화는 공용SERVER_BUSY(1초)이고 이 표에 있다. IDEMPOTENT_IN_FLIGHT는 2초: 기본 processing lease(30s)보다 짧아 첫 시도가 끝날 수 있는 동안 같은 키로 다시 묻게 한다. 근거와 클라이언트 행동은docs/web/http-contract.md§2.- 표는 레지스트리의
retry_after_seconds가 있는 행마다 한 줄이다(LOCK_ACQUISITION_TIMEOUT1초, DB·outbox·job 코드 포함).OperationalErrorRegistryContractTest(app-bootstrap document-contract)가OperationalError마다 표와 레지스트리를 대조한다. 전에는 대조가 없어 7개가 빠진 채였다(advisor 단위 테스트는 값을 코드마다 손으로 옮겨 적었고, enum·레지스트리 대조 테스트는 category·status·retryable 만 봤다).
pagination
PageParams
- 검증된 offset 페이지네이션 파라미터.
page0-indexed: SpringPageableparity(SPRING-PAGE-C1).size기본 20 / min 1 / max 100: 프로젝트 DoS 캡(Spring 자체DEFAULT_MAX_PAGE_SIZE는 2000, SPRING-PAGE-C4). 프로젝트 선택: 정확한 size 캡(100)/min(1)/deep-offset 임계값(10000)은 프로젝트 내부 트레이드오프 — 표준은 원칙만 고정하고 숫자는 고정하지 않는다.
SortParam
- Spring
Pageable네이티브 문법field,direction의 단일 정렬 term(D20). 비-네이티브 문법 거부 근거: JSON:API prefix(-foo)·colon form(foo:desc)·AIP-132 space form("foo desc")은 모두 Spring 자동 바인딩을 깨뜨리므로 금지.
PageValidationException
- 페이지네이션/정렬 요청 파라미터가 스켈레톤의 요청 경계를 위반할 때 발생.
conditional
ETags
- HTTP 계층 낙관적 동시성/캐시 검증용 weak-ETag 도출 및 조건부 요청 매칭(D15, RFC9110-C13..C17).
weakFromVersion산출물W/"<version>"는 스켈레톤의 예시 wire 형태다. 프로젝트 선택: RFC 9110 은If-Match에 strong 비교를 의무화하나, 이 스켈레톤은 불투명 값을 leniently 비교(W/weak 마커와 둘러싼 따옴표 무시)해 문서화된 weak-ETag 형태로도 낙관적 잠금을 구동한다. strong ETag 를 발행하는 프로덕션 fork 도 동일 호출 지점을 유지 가능.
PreconditionFailedException
- 쓰기 요청의
If-Matchvalidator 가 현재 리소스 ETag 와 불일치할 때 발생(D15). 412 로 매핑해 raw 409/500 과 구분 — persistence 계층이 serialization failure 로 surface 할 동일한 낙관적 동시성 충돌의 HTTP 계층 표현.
idempotency
소유
Idempotency-Key는 HTTP 경계가 읽어 application command/context로 전달할 수 있지만, claim / fingerprint / replay / in-flight arbitration은 application use case가 소유한다.- web leaf에는 별도 DB replay 엔진을 두지 않는다. 같은 요청 의미를 web/application 두 계층이 서로 다른 fingerprint로 판정하면 동일 key의 의미가 endpoint마다 달라지기 때문이다.
- 헤더 → 키 변환은
IdempotencyKeyHeader하나로 한다(위 settings / config / http 절). - controller는 key를 받기만 하고, 유스케이스가 application
IdempotencyExecutor를 쓴다. 템플릿에는 이 경로를 HTTP부터 끝까지 이은 업무 기능 예가 없다(docs/manual/05-idempotency.md). - response-loss system fixture도 동일한 application executor를 사용해, 연결이 끊긴 뒤 같은 key 재시도에서 첫 committed 결과가 복구되고 side effect가 한 번만 실행되는지 검증한다.
JsonIdempotentResponseCodec
adapter:inbound:web-advanced로 옮겼다(운영 경로 호출자 0). response-loss fixture 는 fixture 안의 익명 codec 을 쓴다.