Files
clean-architecture-backend-…/src/adapter/inbound/grpc

adapter-grpc — 설계 결정 참조

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

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


왜 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. shutdownGraceSeconds 동안 in-flight RPC 를 기다린 뒤 shutdownNow(). 종료 진입 시 health 를 enterTerminalState()(NOT_SERVING)로 뒤집어 로드밸런서가 드레이닝을 인지하게 한다.
  • fail-closed local insecure bind. 기본은 서버 비활성·reflection 비활성이다. 현재 구현의 plaintext credential은 allowInsecureLocal=true를 명시하고 실제 loopback 주소에 바인딩할 때만 허용한다. wildcard/외부 주소의 insecure 시작은 실패한다.

왜 .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와 정확히 한 개의 GrpcAuthenticationPolicy를 Spring 빈으로 함께 기여한다. runner는 feature 이름을 알지 않고 generic하게 등록하되, 서비스가 하나라도 있는데 인증 정책이 없거나 단일하지 않으면 listener 시작을 거부한다. 정책은 gRPC Metadata만 받아 Spring Security에 결합되지 않으며, false 반환과 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 는 Status trailer Metadata(error-code / error-category)에 실어 클라이언트가 switch 하게 한다.
  • 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 버전을 관리하지 않고 이 저장소엔 version catalog 도 없다. 그래서 io.grpc:grpc-bom + com.google.protobuf:protobuf-bom 을 이 모듈의 dependencyManagement 에서 platform 으로 import 한다(루트 ext.grpcVersion/ext.protobufVersion 가 단일 SSOT). 모듈 스코프로 두어 strict per-module lockfile 의 blast radius 를 이 모듈에만 가둔다 — 공유 루트 dependencyManagement 블록은 io.grpc-free 로 유지된다.

P1 qualification과 P2 유보

GrpcSafeActivationTest는 disabled bean/listener 부재와 설정/인증-policy fail-closed를 검증한다. GrpcP1BoundaryWireTest는 실제 loopback ephemeral Netty unary service로 auth 성공/실패, reflection-off, 모든 오류 경로의 안정 code/category 및 sentinel redaction을 검증한다.

이는 local plaintext unary 경계에 대한 P1 증거이며 production-ready 주장 근거가 아니다. TLS/mTLS, external bind, deadline, streaming/backpressure, generated protobuf 호환성은 P2에서 별도 설계·검증해야 한다.