Files
clean-architecture-backend-…/src/adapter/inbound/grpc
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00
..

adapter-grpc — 설계 결정 참조

인바운드 gRPC 어댑터 스켈레톤 머시너리 모듈. 패키지 루트: dev.caskeleton.adapter.inbound.grpc.

허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 모듈 규칙은 CLAUDE.md 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다.


제공하는 것 · 추가할 한 줄 · 설정 키

  • 제공: io.grpc Netty 서버(GrpcServerRunner, SmartLifecycle), health·(선택) reflection 서비스, @GrpcExposedService 서비스만 노출, 인증 정책 강제, 에러 매핑 인터셉터. 진입점은 모듈 자신의 AutoConfiguration.imports에 있는 GrpcServerConfig이고 설정 바인딩도 그 안에서 한다.

  • 추가할 한 줄(기본 조립에는 없다):

    // app-bootstrap/build.gradle
    runtimeOnly project(':adapter:inbound:grpc')  // gRPC 서버
    

    이 줄을 지우면 서버, 포트, 설정 바인딩이 모두 함께 빠진다.

  • 켜기와 끄기: 모듈이 있으면 켜진다. app.grpc.server.enabled=false로만 끈다.

  • 필요한 설정: 전용 APP_* env 키는 registry에 없다. 켜진 상태에서 지금 구현이 받는 listener는 loopback plaintext뿐이라 app.grpc.server.allow-insecure-local=true(env APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true)를 명시해야 기동한다. 선택: app.grpc.server.port (기본 9090), .bind-address(기본 127.0.0.1), .reflection-enabled, .shutdown-grace-seconds, .shutdown-drain-seconds, 그리고 아래 「서버 한도」 절의 전송 한도 키.

왜 self-managed Netty 인가

  • third-party grpc-spring-boot starter 를 쓰지 않는다. GrpcServerRunner 가 io.grpc Netty Server 를 Spring SmartLifecycle 빈으로 직접 소유한다. starter 를 쓰면 Spring Boot 릴리스에 버전이 커플링되는데, 스켈레톤은 io.grpc 런타임에만 의존해 그 커플링을 피한다(web 어댑터가 third-party 없이 서블릿 컨테이너를 쓰는 것과 같은 정신).
  • getPhase() = Integer.MAX_VALUE - 1. web 서버가 뜬 뒤에 시작하고 종료 시 web 서버 전에 멈춘다(SmartLifecycle: 높은 phase 가 늦게 시작·먼저 종료). gRPC 는 web 과 별개의 TCP 포트를 소유하는 부가 전송이므로 애플리케이션 수명주기 맨 바깥에 둔다.
  • graceful shutdown. 종료 진입 시 health 를 enterTerminalState()(NOT_SERVING)로 뒤집고, listener 를 연 채로 shutdownDrainSeconds(기본 2초) 기다린 뒤 shutdown() → 남은 grace (shutdownGraceSeconds - shutdownDrainSeconds) 동안 awaitTermination → shutdownNow() 순서로 닫는다. NOT_SERVING 과 listener 닫기를 같은 순간에 하면 health 확인이 UNAVAILABLE 로 끝나 로드밸런서가 드레이닝과 장애를 구분하지 못한다. drain 은 grace 예산 안에서 쓰며(drain > grace 는 기동 실패), Health/Watch 구독자는 즉시 알림을 받으므로 2초면 충분하다. 주기가 더 긴 poll 방식 probe 는 이 값으로 기다릴 수 없으니 preStop 지연으로 맞춘다. 끝나면 call/dispatch executor 와 deadline scheduler 도 shutdownNow() 한다.
  • fail-closed local insecure bind. 모듈이 있으면 서버가 켜지지만 reflection은 비활성이다. 현재 구현의 plaintext credential은 allowInsecureLocal=true를 명시하고 실제 loopback 주소에 바인딩할 때만 허용한다. wildcard/외부 주소의 insecure 시작은 실패한다. 이 제약의 운영적 의미는 명확하다: 현재 어댑터는 local/same-Pod sidecar 전용이다. 0.0.0.0에 바인딩해 Kubernetes Service 뒤에서 다른 Pod의 RPC를 받는 구성은 현재 구현으로 만들 수 없다. 그런 cluster-facing 노출은 TLS/mTLS credential 경로와 non-loopback qualification이 추가된 뒤의 범위다.

서버 한도 — io.grpc 기본값을 쓰지 않는다 (리뷰 03-09)

io.grpc 기본값은 메시지 4 MiB, 연결당 동시 호출 무제한, 호출마다 스레드를 늘리는 cached executor, 서버 deadline 없음, 연결 수명 무제한이다. 어댑터 서버는 이 값을 모두 명시한다.

키 (app.grpc.server.*) 기본값 같은 값의 출처 (vendored 플랫폼)
max-inbound-message-bytes 1048576 (1 MiB) GrpcTransportLimits.DEFAULT_MAX_MESSAGE_BYTES
max-inbound-metadata-bytes 8192 (8 KiB) GrpcTransportLimits.DEFAULT_MAX_METADATA_BYTES
executor-max-pool-size 32 GrpcPlatformProperties.executorMaxPoolSize
executor-queue-capacity 256 (최대 10000) GrpcPlatformProperties.executorQueueCapacity, 상한은 GrpcExecutorProfile
keep-alive-time / keep-alive-timeout 30s / 10s GrpcServerProfile.stable(..)
permit-keep-alive-time 30s GrpcServerProfile.stable(..)
max-connection-age / max-connection-age-grace 30m / 30s GrpcServerProfile.stable(..)
max-concurrent-calls-per-connection 100 플랫폼에 없음. RFC 9113 §6.5.2 가 권하는 MAX_CONCURRENT_STREAMS 하한
default-deadline 10s 플랫폼은 메서드별 GrpcDeadlineProfile 만 있다. GraphQL 어댑터의 요청 예산 10초와 맞춤
  • 값이 두 곳에 있는 이유. 03-09 는 (a) 어댑터가 같은 이름·값을 자기 설정으로 노출, (b) 어댑터가 플랫폼 GrpcServerProfile 을 받음(registry edge 추가), (c) 현상 유지 중 (a)를 골랐다. 두 스택 분리(X1-#10)를 건드리지 않기 위해서다. 어댑터는 플랫폼 타입을 import 할 수 없어(registry edge 없음, 플랫폼은 optional-platforms 별도 빌드) 상수를 직접 비교하는 테스트는 만들 수 없다. 대신 GrpcSafeActivationTest.transportBoundDefaultsMatchTheVendoredPlatformDefaults 가 위 표의 플랫폼 값을 literal 로 고정한다. 플랫폼 값을 바꾸면 이 표와 그 테스트를 같이 바꾼다.

  • duration 순서 검증. keep-alive-timeout < keep-alive-time, permit-keep-alive-time <= keep-alive-time, max-connection-age-grace <= max-connection-age, 모든 duration 양수 — GrpcServerProfile 생성자가 거절하는 조합을 바인딩 단계에서 똑같이 거절한다.

  • keep-alive·connection age 를 loopback 에서도 켜는 이유. 지금 listener 는 loopback 전용이라 중간 장비가 idle 연결을 끊는 일은 없다. 그래도 플랫폼과 같은 값을 둬서 non-loopback bind(P2)를 열 때 따로 정할 값이 남지 않게 했다. loopback 에서의 효과는 멈춘 클라이언트 연결을 30분에 정리하는 것뿐이다.

  • 기본 deadline(GrpcServerDeadlineInterceptor). 클라이언트가 deadline 없이 부른 feature 호출은 default-deadline 에서 DEADLINE_EXCEEDED 로 끝난다. 클라이언트 deadline 이 더 짧으면 그대로 두고(io.grpc 가 집행), 더 길면 서버 값으로 줄인다. derived Context 를 취소해도 io.grpc 는 스트림을 닫지 않으므로 인터셉터가 직접 닫고, 그 close 가 handler 의 쓰기와 겹치지 않게 call 을 직렬화한다. handler 는 Context.current().isCancelled() 로 만료를 본다. 확인하지 않는 handler 는 반환할 때까지 스레드를 잡는다 — deadline 이 풀어 주는 것은 호출자이지 스레드가 아니다. 상태에는 code/category trailer 를 붙이지 않는다(io.grpc 의 클라이언트 deadline 만료와 같은 모양). health/reflection 에는 적용하지 않는다(Health/Watch 는 원래 오래 사는 스트림이다).

  • 포화 시 동작(GrpcCallAdmission). feature 호출은 executor-max-pool-size + executor-queue-capacity 개까지만 받고, 넘친 호출은 handler 를 시작하지 않고 즉시 RESOURCE_EXHAUSTED(RATE_LIMIT_EXCEEDED, retryable)로 닫는다. 구현: io.grpc ServerCallExecutorSupplier(@ExperimentalApi, 1.39부터)가 호출 시작 전에 permit 을 확인해 받은 호출만 고정 크기 work pool 로 옮기고, 못 받은 호출은 가장 바깥 인터셉터가 닫는다. 메서드 조회·context 정리·health·reflection 은 작은 dispatch pool 에서 돈다. 버린 대안:

    • bounded ThreadPoolExecutor + AbortPolicy 만 두기 — 실행으로 확인한 결과 io.grpc 는 거절을 Netty 스레드 로그로만 남기고 스트림을 열어 둔다. 클라이언트는 자기 deadline 까지(없으면 영원히) 기다린다.
    • caller-runs — handler 가 dispatch/Netty 스레드에서 돌아 같은 연결의 다른 호출을 모두 멈춘다.
    • 큰(또는 무제한) 대기열 — 같은 실패를 모든 호출자의 deadline 뒤로 미룰 뿐이다.
    • 플랫폼 GrpcAdmissionController 사용 — 03-09 (b)의 배선 결정이 필요하다.

    work pool 대기열은 permit 수만큼 깊다. io.grpc 는 한 호출의 콜백을 직렬화하므로 받아들인 호출은 pool 에 많아야 작업 하나를 두고, 따라서 이 대기열은 차지 않는다(AbortPolicy 는 도달하지 않는 안전장치다). 대기열에서 기다린 시간은 서버 기본 deadline 에 들어가지 않는다 — 서버 deadline 은 handler 가 시작될 때부터 잰다. 클라이언트 deadline 은 도착 시점부터 잰다.

왜 .proto 도 protobuf 플러그인도 없는가

이 모듈은 protobuf 를 하나도 컴파일하지 않는다 — com.google.protobuf 플러그인도, src/main/proto 도 없다. health(grpc.health.v1) 와 v1 server reflection 은 grpc-services 런타임 jar에 이미 컴파일된 채 들어 있다. 서버를 명시적으로 켜면 feature RPC가 없어도 health로 수명주기를 확인할 수 있고, reflection은 별도 flag를 켠 경우에만 등록된다. 현재 저장소에는 feature .proto, generated stub, feature gRPC service가 없다. 향후 도입하는 feature 모듈이 이들을 소유해야 한다.

기능(feature)은 어떻게 기여하는가 — machinery/feature 분리

향후 feature 모듈은 노출할 BindableService bean에 @GrpcExposedService를 붙이고 정확히 한 개의 GrpcAuthenticationPolicy를 함께 기여한다. runner는 qualifier로 선택된 서비스만 등록하며, 같은 context의 unqualified BindableService는 gRPC 포트에 노출하지 않는다. 노출 서비스가 하나라도 있는데 인증 정책이 없거나 단일하지 않으면 listener 시작을 거부한다. 정책은 gRPC Metadata만 받아 Spring Security에 결합되지 않는다. 인증된 호출자(Optional<Principal>)는 인터셉터가 gRPC Context에 담아(Contexts.interceptCall) handler가 GrpcAuthenticatedCaller.current()로 읽으므로, handler가 metadata를 다시 해석하지 않는다. 빈 값·null 반환과 policy 예외는 동일한 안정적 UNAUTHENTICATED 계약으로 끝난다.

에러 매핑 — web GlobalExceptionHandler 의 gRPC 형제

GrpcExceptionHandlingInterceptor는 forwarding ServerCall의 close까지 감싼다. 동기 handler throw, listener callback throw, responseObserver.onError(...), raw StatusRuntimeException이 모두 같은 sanitizer를 거친다. 서비스 구현은 web 컨트롤러처럼 "그냥 던지기만" 하고, 이 인터셉터가 와이어 계약을 단일 소유한다.

  • 와이어 status(coarse) 는 GrpcStatusMapper.toStatus(Category) 가 결정한다(HTTP status 가 coarse 인 것과 동형). 정확한 code/category/retryable 은 Status trailer Metadata (error-code / error-category / error-retryable)에 실어 클라이언트가 switch 하게 한다. retryable 은 코드의 값이다(처리 중 중복 IDEMPOTENT_IN_FLIGHT 는 2026-11-01 리뷰 02-01부터 ABORTED + error-retryable: true — 같은 키로 다시 보내면 서버가 판정한다. GrpcStatusMapperTest 가 고정, 재리뷰 RR-02-06). status description 은 shared-contract ClientErrorMessages 의 Category 별 한국어 문구(web·GraphQL 과 같은 표)다.
  • IllegalArgumentException 은 BAD_PARAMETER(INVALID_ARGUMENT) — 모든 전송이 같다.
  • ApiErrorCode 추출: feature 예외는 ApiErrorCarrier(이 모듈이 제공하는 전송-중립 hook)를 구현해 자신의 ApiErrorCode 를 노출한다. shared-contract 의 PersistenceFailureException / DependencyFailureException(outbound 어댑터에서 올라온 분류된 실패)도 직접 인식한다.
  • leak 방지: 인식된 코드는 안정적 code 문자열만 status description/trailer 로 노출하고, raw 예외 메시지(SQLState/업스트림 세부를 담을 수 있음)는 절대 클라이언트에 내보내지 않는다. 인식되지 않은 예외와 raw gRPC status/description은 원래 status를 신뢰하지 않고 Status.INTERNAL + INTERNAL_ERROR로 폴백한다. 입력 trailers도 폐기한다.

Category → Status 표(설계 스펙 Error Mapping SSOT):

Category gRPC Status
VALIDATION INVALID_ARGUMENT
AUTH UNAUTHENTICATED
AUTHZ PERMISSION_DENIED
NOT_FOUND NOT_FOUND
CONFLICT ABORTED
RATE_LIMIT RESOURCE_EXHAUSTED
TRANSIENT_DEPENDENCY UNAVAILABLE
PERMANENT_DEPENDENCY INTERNAL
DATA_INTEGRITY INTERNAL
INTERNAL INTERNAL

의존성 버전 — strict locking

Spring Boot BOM은 io.grpc:*/protobuf 버전을 관리하지 않는다. 이 저장소에는 gradle/libs.versions.toml version catalog가 있고, 이 leaf는 그 grpc / protobufGrpc 버전을 읽어 io.grpc:grpc-bom + com.google.protobuf:protobuf-bom을 모듈 로컬 dependencyManagement에 import한다. 모듈 스코프로 두는 이유는 catalog 부재가 아니라 strict per-module lockfile과 dependency-management blast radius를 이 leaf에 가두기 위해서다.

P1 qualification과 P2 유보

GrpcSafeActivationTest는 disabled bean/listener 부재와 설정/인증-policy fail-closed를 검증한다. GrpcP1BoundaryWireTest는 실제 loopback ephemeral Netty unary service로 auth 성공/실패, reflection-off, 모든 오류 경로의 안정 code/category 및 sentinel redaction을 검증한다. 서버 한도도 같은 wire 에서 검증한다: 1 MiB 초과 요청 RESOURCE_EXHAUSTED(정확히 1 MiB 는 통과), deadline 없는 느린 호출의 서버 기본 deadline DEADLINE_EXCEEDED, 더 짧은 클라이언트 deadline 유지, 연결당 동시 호출 상한, executor·대기열 포화 시 즉시 RESOURCE_EXHAUSTED. GrpcServerRunnerBootTest는 종료 drain 동안 listener 가 살아서 health NOT_SERVING 을 답하는지 검증한다.

이는 local plaintext unary 경계에 대한 P1 증거이며 production-ready 주장 근거가 아니다. TLS/mTLS, external bind, 메서드별 deadline(지금은 서버 전체 기본값 하나), streaming/backpressure, generated protobuf 호환성은 P2에서 별도 설계·검증해야 한다.