Files
clean-architecture-backend-…/src/adapter/inbound/web/README.md
T
DongHyeonka 75df7615e5 fix(logging)!: 로그 줄이 원본 경로·SQL을 싣지 않고 감사 줄을 버리지 않게 한다
로그 줄이 남기지 말아야 할 값을 싣고, 남겨야 할 줄을 버린다. 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행.
2026-11-13 13:12:09 +09:00

51 KiB
Raw Blame History

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 Security Authentication 토큰 필드의 관례적 해결책이 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/JwtException cause) → AUTH_TOKEN_INVALID_SIGNATURE / AUTH_TOKEN_MALFORMED / AUTH_KID_UNKNOWN
    • JWKS endpoint 장애 → AUTH_JWKS_UNAVAILABLE (503, transient)
  • 텍스트 휴리스틱은 의도적으로 좁고 순서가 있다. 매핑되지 않은 실패는 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_UNAVAILABLE 503, INTERNAL_AUTH_MISCONFIGURATION 500)는 서버 쪽 고장이라 ERROR다. 다른 경로가 5xx를 ERROR로 남기는 규칙(shared-contract ServerFailureLog)과 같다. 레벨은 오류 코드 레지스트리의 칸이 아니라 이 코드가 정한다(설계 메모 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_PERMISSION 403).
  • AUTHZ_TENANT_MISMATCH 는 application-layer 의 cross-tenant 결정이라 일반 Spring AccessDeniedException 으로는 추론 불가 — 여기서 방출하지 않는다.

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_INFRASTRUCTURE static @Bean 으로 등록 — 일반 싱글톤보다 먼저 인스턴스화되어 애플리케이션 빈을 조기 초기화로 끌어들이지 않는다.

RequiresPermissionAuthorizationManager

  • RequiresPermission 의 Spring-aware 강제 메커니즘(커스텀 AuthorizationManager<MethodInvocation>).
  • 가로챈 메서드(또는 선언 타입)에서 애너테이션을 읽고, 현재 Authentication 을 프레임워크 독립적 AuthorizationPrincipal 로 매핑해 결정을 application AuthorizationPort 에 위임한다. 따라서 application/domain 은 어떤 Spring Security 타입도 갖지 않으며, 이 어댑터가 두 세계가 만나는 유일한 지점이다.
  • 포트가 거부 시 application AuthorizationDeniedException 을 던지고, 이 매니저가 그것을 거부된 AuthorizationDecision 으로 변환한다. method-security 인터셉터가 이를 AccessDeniedException → AUTHZ_INSUFFICIENT_PERMISSION 403 으로 만든다(§4). null 반환은 기권(abstain)이라 애너테이션 없는 메서드는 영향받지 않는다.
  • 매핑은 fail-closed: 미인증 요청이거나 우리 AuthenticatedPrincipal 이 아닌 principal 은 0개 role 로 해석되어 거부된다.

AuthorizationAdapter

  • application AuthorizationPort 의 web-adapter 구현체.
  • 결정은 fail-closed: principal 의 유효 권한 집합에 요구 권한이 없으면 AuthorizationDeniedException 으로 거부 → RequiresPermissionAuthorizationManager 가 변환 → 최종 AUTHZ_INSUFFICIENT_PERMISSION 403.

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_ 접두사는 Spring GrantedAuthority 에만 있고 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-contract ClientErrorMessages의 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(shared MappingException·AdapterDisabledException·PersistenceFailureException· DependencyFailureException, application 멱등성·분산 락 예외, adopter 예외)는 handleCarrier 분기 하나로 매핑한다. 5xx 는 원인과 함께 로그를 남기고(persistence 는 분류만), retryable 코드는 RetryAfterAdvisor로 Retry-After를 붙인다.
  • carrier 를 다른 예외로 감싸 던져도 같다. handleUnknown(그 밖의 예외)과 handleIllegalArgument 는 원인 사슬의 첫 carrier(ApiErrorCarrier.firstIn)를 찾아 handleCarrier 로 넘긴다. 감싼 persistence 실패도 500 INTERNAL_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 실패 등)는 handleExceptionInternal override 가 상태 코드 → 코드로 바꿔 같은 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 의 @ConditionalOnMissingBean bean 하나뿐이다. 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() → Spring HttpStatus 매핑, error.category 운반, MDC 에서 meta 추출).

envelope / filter

EnvelopeBodyAdvice

  • 컨트롤러는 도메인/DTO 타입을 반환하고, 이 advice 가 와이어 형태를 항상 {success, data | error, meta} 로 보장한다.
  • null 필드는 키째 생략한다. 성공에는 error 키가, 실패에는 data 키가, 단일 아이템 meta 에는 page 키가 없다. 빈 목록은 생략하지 않는다. 규칙은 EnvelopeWireFormatConfig 의 Jackson mix-in 이 Boot JsonMapper 에 등록한다(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 이면 ClassCastException 500, */* 면 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 은 logger org.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→MDC trace_id, spanId→span_id. 부재/공백/무효면 fresh ROOT traceparent 생성(32-hex traceId, 16-hex spanId, sampled=false)하여 MDC trace_id 가 항상 의미 있는 W3C id 이고 절대 null 이 아니게 한다(D4: 추적 비활성 상태에서도 meta.traceId non-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 로 가명화. raw idpUserId() 는 절대 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 를 MDC trace_id 에 쓴다. 어느 값이 최종 반영될지는 필터/observation 의 ORDER 와 scope 에 달려 있다 — 이 필터가 이기면 클라이언트의 meta.traceId 가 실제 export 된 span 의 trace-id 와 불일치해, "응답 id 로 trace 조회"라는 D4 의 핵심 목적이 조용히 깨진다. 실제 tracer 를 연결하는 fork 는 tracer 가 MDC trace_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계층 검증 전략.
    1. 단순 제약(범위/필수/정규식)은 JSR-303 + @Validated 로 선언해 잘못된 값이 BindValidationException 으로 기동 실패(maxAgeSeconds).
    2. JSR-303 로 표현 불가한 조건부/교차필드 규칙은 compact constructor 의 fail-fast throw 로 강제(관대한 기본값 폴백 금지).
    3. 정상 기본값(CORS disabled 시 빈 origins, 미설정 method/header)은 invalid 가 아니라 합리적 기본값으로 채움.
  • 교차필드 불변식: 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-*)에 모든 CorsExposedHeaders bean 을 더해 노출한다. 헤더를 쓰는 모듈이 기여한다(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가 무해화하고 MDC correlation_id에 넣은 값을 application-core의 CorrelationIdPort로 투영한다.
  • absent/blank는 Optional.empty()로 반환한다. application 계층은 SLF4J/MDC를 직접 참조하지 않고 event-id fallback 정책만 소유한다.

ResponseMetaFactory

  • snake_case MDC 진단 키를 camelCase ResponseMeta wire 객체로 projection 하는 D19 단일 변환 지점. adapter-web 에 위치하는 이유: shared-contract 는 프레임워크 중립이라 MDC 를 읽으면 안 된다.

RetryAfterAdvisor

  • Retry-After 노출 지점. 구체 헤더 값과 429/503 세부는 이 영역의 책임이고, per-code retry_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-advanced WebAdvancedError). 서버 포화는 공용 SERVER_BUSY(1초)이고 이 표에 있다.
  • IDEMPOTENT_IN_FLIGHT 는 2초: 기본 processing lease(30s)보다 짧아 첫 시도가 끝날 수 있는 동안 같은 키로 다시 묻게 한다. 근거와 클라이언트 행동은 docs/web/http-contract.md §2.
  • 표는 레지스트리의 retry_after_seconds 가 있는 행마다 한 줄이다(LOCK_ACQUISITION_TIMEOUT 1초, DB·outbox·job 코드 포함). OperationalErrorRegistryContractTest(app-bootstrap document-contract)가 OperationalError 마다 표와 레지스트리를 대조한다. 전에는 대조가 없어 7개가 빠진 채였다(advisor 단위 테스트는 값을 코드마다 손으로 옮겨 적었고, enum·레지스트리 대조 테스트는 category·status·retryable 만 봤다).

pagination

PageParams

  • 검증된 offset 페이지네이션 파라미터. page 0-indexed: Spring Pageable parity(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-Match validator 가 현재 리소스 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 을 쓴다.