Files
clean-architecture-backend-…/src/adapter/inbound/web-advanced
DongHyeonka 5786126cfa fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).

방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.

위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
2026-11-03 19:52:06 +09:00
..

adapter-inbound-web-advanced

라이브러리 API — 서비스의 어댑터 leaf에서 implementation으로 받아 직접 호출; 기본 조립에 없음.

adapter:inbound:web 에 있던 코드 중 servlet 운영 경로가 닿지 않는 것만 모은 opt-in leaf 다. app-bootstrap·sample-portfolio 는 이 leaf 에 의존하지 않는다. 패키지 루트는 dev.caskeleton.adapter.inbound.web.advanced (web 과 겹치는 패키지 없음).

추가할 한 줄

서비스의 어댑터 leaf build.gradle:

implementation project(':adapter:inbound:web-advanced')

registry(src/config/architecture/modules.json)의 그 leaf allowed_dependencies 에 adapter-inbound-web-advanced 를 더한다. 서비스 코드가 타입을 직접 부르므로 runtimeOnly 로는 안 된다 (AGENTS.md capability 규칙의 라이브러리형 예외).

제공하는 것

설정으로 켜는 것 (자기 AutoConfiguration.imports, 기본 off)

기능 켜는 설정 만드는 bean
MVC virtual thread 실행기 + admission 제한 app.web.advanced.mvc-virtual-threads.enabled=true, admission-limit, database-pool-size, outbound-bulkhead, admission-wait applicationTaskExecutor, VirtualThreadAdmissionGuard, VirtualThreadProfile
NDJSON 스트리밍 app.web.advanced.ndjson.enabled=true mvcNdjsonWriter + 공유 WebStreamPolicy·WebStreamRegistry·StreamRecordEncoder
JSON text sequence (RFC 7464) app.web.advanced.json-sequence.enabled=true mvcJsonSequenceWriter + 같은 공유 bean

virtual thread 실행기는 TaskDecorator bean 을 요구한다(요청 상관관계 전파). 조립 순서는 TaskExecutionAutoConfiguration 앞이다. 스트리밍 두 기능은 Boot 의 JsonMapper bean 으로 레코드를 쓴다(별도 mapper 없음).

라이브러리 (설정 없음, 직접 호출)

패키지 주요 타입
patch JsonMergePatchApplier, JsonPatchApplier, PatchFieldAuthorization, JsonPointerAuthorization
codec WebCborMapperFactory, WebXmlMapperFactory, RepresentationNegotiationPolicy (백엔드 jar 는 서비스가 추가)
stream, stream.encoding, stream.replay WebStreamRegistry, WebStreamDrainCoordinator, StreamRecordEncoder, MessagingReplayBridge
openapi WebOpenApi32Generator, WebOpenApiBreakingPolicy
http WebUriPolicy, WebMethodPolicy
versioning PathApiVersionResolver, ApiDeprecationPolicy
operation, budget, contract InMemoryWebOperationCatalog, WebRequestBudget, WebWireTypeManifest
security WebSecurityContextBridge (인증 결과 → ActorContext/TenantContext, 요청 입력의 tenant 거부)
idempotency JsonIdempotentResponseCodec
admin.route WebRouteInventory

오류 응답

이 leaf 의 예외는 모두 ApiErrorCarrier 다. 코드는 error.WebAdvancedError 한 enum 이 정하고, web 의 GlobalExceptionHandler.handleCarrier 한 분기가 Envelope 로 답한다(별도 @RestControllerAdvice 없음). 예전에는 10종 모두 500 INTERNAL_ERROR 였다(리뷰 2026-11-01 02-07). 아래 표와 enum 은 같은 값을 말하고, WebAdvancedErrorMappingTest 가 실제 응답으로 확인한다.

예외 error.code status category retryable 응답에 더 실리는 것 클라이언트 행동
AdmissionRefusedException ADMISSION_REFUSED 503 TRANSIENT_DEPENDENCY true Retry-After: 1 잠시 뒤 같은 요청
JsonPatchTestFailedException PATCH_TEST_FAILED 409 CONFLICT false details.pointer(서버 값은 없음) 다시 읽고 새 patch
JsonPatchRejectedException PATCH_REJECTED 400 VALIDATION false — patch 문서를 고친다
PatchAuthorizationException PATCH_PATH_FORBIDDEN 403 AUTHZ false details.refusedPaths 해당 경로를 빼거나 권한 확보
UnsupportedApiVersionException API_VERSION_UNSUPPORTED 404 NOT_FOUND false — 지원 버전 경로로
SunsetViolationException API_DEPRECATION_INVALID 500 INTERNAL false — 서버 설정 결함(등록 시점 오류)
UntrustedTenantInputException TENANT_INPUT_UNTRUSTED 403 AUTHZ false — 요청 입력으로 tenant 를 보내지 않는다
ReplayCursorExpiredException STREAM_RESNAPSHOT_REQUIRED 410 NOT_FOUND false — 리소스를 다시 읽고 새 스트림(docs/web/streaming-contract.md)
StreamItemTooLargeException STREAM_ITEM_TOO_LARGE 500 INTERNAL false — 서버 데이터 문제. commit 뒤면 스트림 terminal failure 로 끝난다
RouteInventoryMismatchException ROUTE_INVENTORY_MISMATCH 500 INTERNAL false — release gate 실패(요청 경로에서는 나오지 않아야 한다)
  • Retry-After 는 WebAdvancedError 가 web 의 RetryAfterHint 로 직접 말한다. web 의 RetryAfterAdvisor 표에 이 leaf 코드 이름을 넣지 않는다.
  • details 는 ClientSafeErrorDetails 로 고른 값만 나간다. 예외 메시지는 나가지 않는다.
  • 이 코드들은 docs/registries/error-codes.yaml(OperationalError SSOT) 밖이다. 5xx 는 handleCarrier 가 ERROR 로그를 남긴다(admission 거절 포함 — 경보 임계는 운영에서 정한다).
  • 응답 status 가 이미 commit 된 스트림 안에서는 HTTP status 가 바뀌지 않는다. 위 표는 commit 전에 던져진 경우다.

env 키

없다. 위 세 설정은 서비스가 자기 application.yml 에 둔다. 이 leaf 는 env key registry 에 키를 추가하지 않는다.

테스트

cd src
./gradlew :adapter:inbound:web-advanced:check              # 컴파일·테스트·포맷·스타일
./gradlew :adapter:inbound:web-advanced:webAdvancedTest    # @Tag("web-advanced") 묶음, 0건이면 실패

지원 표와 거부 규칙은 docs/web/advanced-capabilities.md.

없는 것

운영 web 경로가 이미 다른 방식으로 하는 기능(forwarded header, CORS/CSRF, cache header, JSON mapper, OpenAPI customizer)과 WebFlux functional 은 2026-09-25 에 지웠다. 무엇을 대신 쓰는지는 docs/web/advanced-capabilities.md 의 "Removed on 2026-09-25", 복구 경로는 docs/capability-status.md.