문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(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·의존 없음이어야 한다.
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(envAPP_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 NettyServer를 SpringSmartLifecycle빈으로 직접 소유한다. 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 가 집행), 더 길면 서버 값으로 줄인다. derivedContext를 취소해도 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.grpcServerCallExecutorSupplier(@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 은 도착 시점부터 잰다. - bounded
왜 .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은StatustrailerMetadata(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-contractClientErrorMessages의 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에서 별도 설계·검증해야 한다.