fix(docs): 옮긴 gRPC 기록은 템플릿에 남기고 머리 블록만 고친다
앞 커밋이 ADR-GRPC 7개와 gRPC 설계서를 살아 있는 문서와 함께 지웠다. 그러자 기록 docs/history/plans/2026-08-30-grpc-platform-implementation.md의 상대 링크가 깨졌다(desktop: check-work-docs --links broken 1, lychee Error 1). 기록 본문은 고치지 않는다는 규칙이라 링크를 고칠 수 없다. 기록은 그때 템플릿 안 코드를 두고 한 결정·설계이므로 템플릿에도 남는 것이 맞다(설계 Q15 「리뷰 기록은 템플릿에 남김」과 같은 이유). - ADR-GRPC 7개와 설계서를 22df3525에서 되살리고, 머리 블록 「현재 정본」을 「없음 — grpc-library로 옮겼다」로 바꿨다. 사본은 grpc-library에도 있다. - 업그레이드 안내 B-55의 지운 목록에서 그 기록들을 뺐다. - persistence-jpa testkit 주석 둘을 Spotless 줄바꿈대로 다시 쌌다 (desktop ci의 spotlessJavaCheck 실패). 검증(로컬, 문서만): check-docs.py rc=0, check-work-docs.py --links broken 0. Gradle 게이트는 desktop에서 다시 돈다.
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 플랫폼을 adapter leaf 하나가 아니라 registry에 등록한 family로 낸다는 결정이다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-001: gRPC 플랫폼은 adapter leaf 하나가 아니라 등록된 family로 싣는다
|
||||
|
||||
- 상태: 채택
|
||||
- 날짜: 2026-08-30
|
||||
- 범위: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json`
|
||||
|
||||
## 배경
|
||||
|
||||
두 원본 계획은 자기 API, SPI, 어댑터, 조립 루트를 가진 타입 안전 gRPC 실행 플랫폼을 설명한다: `modules/grpc` 아래
|
||||
Stable 모듈 열다섯과 `modules/grpc-advanced` 아래 Advanced 모듈 열여섯, Gradle Kotlin DSL, 패키지
|
||||
`io.backend.skeleton.grpc`, Spring Boot 4.1 기준.
|
||||
|
||||
그 배치는 여기 하나도 없다. 이 저장소는 Groovy DSL, leaf 목록을 가진 실패하면 닫히는 모듈 registry, 패키지 루트
|
||||
`dev.caskeleton`, Spring Boot 4.0.8을 쓴다. 계획은 이것을 예상한다: 마지막 Global Constraint가, 저장소 구조가 다르면
|
||||
파일 경로를 다시 대응시키고 공개 계약·불변식·시험의 뜻은 바꾸지 않는다고 말한다.
|
||||
|
||||
고를 수 있는 모양은 둘이었다. 플랫폼을 기존 `:adapter:inbound:grpc` leaf에 패키지로 접어 넣기 — JPA, GraphQL,
|
||||
WebSocket, HTTP 플랫폼이 여기서 그렇게 했다 — 또는 `messaging:*`를 등록한 방식대로 family로 등록하기.
|
||||
|
||||
## 결정
|
||||
|
||||
family로 등록한다: `src/grpc/` 아래 Stable leaf 열둘과 `src/grpc-advanced/` 아래 Advanced leaf 여섯.
|
||||
|
||||
결정을 가른 성질은 이것이 이 애플리케이션의 계층이 아니라는 점이다. 루트 `CLAUDE.md`는 이미 `messaging:*`를 "a
|
||||
vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this
|
||||
application"(들여온 메시징 플랫폼: 자기 API, SPI, 어댑터, 조립 경계를 가진 제품이고 이 애플리케이션의 계층이
|
||||
아니다)이라고 설명하고, gRPC 플랫폼은 같은 이유로 같은 모양이다 — 애플리케이션은 라이브러리에 닿듯, 애플리케이션이
|
||||
가진 포트를 거쳐 그것에 닿아야 한다. 패키지가 된 네 플랫폼은 모두 이 애플리케이션의 계층이다. 이것은 아니다.
|
||||
|
||||
`src/grpc/`와 `src/grpc-advanced/`의 분리는 정리용이 아니다. Stable 계획은 Stable starter의 빌드가 Advanced 모듈에
|
||||
닿으면 실패해야 한다고 요구하고, Gradle 경로 접두어를 따로 두면 그것이 리뷰 메모가 아니라
|
||||
`verifyCleanArchitectureDependencies` 실패가 된다: `grpc-spring-boot-starter`의 registry 항목은 advanced id를 하나도
|
||||
대지 않고, 소리 없이 얻을 수도 없다.
|
||||
|
||||
## 결과
|
||||
|
||||
**registry가 leaf 44개에서 62개로 늘었다.** 큰 registry 변경이고, 일부러 한곳에서 했다. 새 leaf는 모두
|
||||
`runtime_memberships: []`라서, 두 번째로 명시한 결정이 옮기기 전까지 아무것도 실리지 않는다.
|
||||
|
||||
**advanced 경계는 두 번 검사한다.** 빌드 때 registry가 한 번, 런타임에 `GrpcStableBuildInvariant`가 한 번. fat jar나
|
||||
shaded artifact는 registry가 보지 못하는 무언가가 조립하기 때문이다.
|
||||
|
||||
**testkit 모듈 넷은 시험 lane 넷이 됐다.** 계획이 나눈 이유는 프로세스 안 결과를 네트워크 결과로 착각하지 못하게
|
||||
하려는 것이다. 이 저장소는 그것을 `ca.strict-test-lane`으로 나타낸다. 그 lane은 아무것도 찾지 못하면 실패하고,
|
||||
up-to-date 결과를 내주지 않는다. `GrpcEvidenceGrade`가 코드 안에서 같은 규칙을 지키므로, 보고서가 계약 실행을 전송
|
||||
증거로 인용할 수 없다.
|
||||
|
||||
**codegen은 배선하지 않았다.** ADR-GRPC-002를 본다.
|
||||
@@ -0,0 +1,72 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-002: schema 관리는 protoc 없이, Buf CLI 없이 돈다
|
||||
|
||||
- 상태: **대체됨(2026-09-28)** — 2026-09-25 리뷰 후속의 소유자 결정 18
|
||||
- 날짜: 2026-08-30
|
||||
- 범위: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen`(둘 다 지움)
|
||||
|
||||
> **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract`
|
||||
> (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은
|
||||
> `src/gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
|
||||
> 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking`
|
||||
> (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml`
|
||||
> job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의
|
||||
> 기록으로 남긴다.
|
||||
|
||||
## 배경
|
||||
|
||||
Stable Task 8부터 11은 proto 문체 규칙, Buf format·lint·breaking 관리, Java codegen 소유자 하나, 그리고 쓰는 쪽
|
||||
컴파일 결과가 릴리스를 막는 descriptor artifact를 요구한다.
|
||||
|
||||
그 Task가 이름을 대는 도구 중 둘이 이 toolchain에 없다. Buf CLI는 설치돼 있지 않다. 그리고 `protoc`는 Gradle
|
||||
protobuf 플러그인으로 쓸 수 있지만, 이 저장소의 모든 leaf는 google-java-format을 쓴 spotless, checkstyle, HIGH
|
||||
confidence의 SpotBugs, Error Prone, `-Werror`를 통과하는데 — 생성된 protobuf 소스는 그중 어느 것도 통과하지 못한다.
|
||||
codegen을 켜면 source set 하나를 품질 게이트 다섯에서 빼야 한다.
|
||||
|
||||
그런 예외에는 선례가 있다: `jmh` source set은 `spotbugsJmh`와 `checkstyleJmh`를 끄고 Error Prone도 끈다. 그러니 빼는
|
||||
길은 있다. 하지만 그것은 Task 하나를 위해 leaf의 품질 기준선에 대해 내리는 결정이고, 이 일이 바꾸라고 받은 범위
|
||||
밖이다.
|
||||
|
||||
`adapter:inbound:grpc`에도 반대 방향으로 기록된 결정이 있다: 그 `CLAUDE.md`는 쓰는 기능 모듈이 자기 schema를 가져야
|
||||
한다는 이유로 그 leaf에서 protobuf 플러그인과 `.proto`를 금지한다.
|
||||
|
||||
## 결정
|
||||
|
||||
`.proto` 소스를 커밋하고, Task가 요구하는 모든 규칙을 protoc 실행도 Buf CLI 호출도 없이 실행되는 Java로 구현한다.
|
||||
|
||||
`GrpcProtoContractValidator`는 `.proto` 글을 읽고 다음을 강제한다: proto3 문법, `{organization}.{domain}.v{major}`
|
||||
패키지 규칙, `java_multiple_files`, 손으로 쓴 것과 겹치지 않는 생성 Java 패키지, `_UNSPECIFIED` enum 0값, 받은 삭제
|
||||
이력과 대조한 `reserved` 선언, well-known type 허용 목록, map 필드 허용 목록. 자기 시험에서 커밋한 schema에 대고
|
||||
돌므로, 출하하는 `.proto` 파일은 장식이 아니라 살아 있다.
|
||||
|
||||
`GrpcBufPolicy`는 breaking gate를 Buf의 `FILE` category로 고정하고, 규칙을 따르는 pipeline이 등록하는 lifecycle 단계
|
||||
넷을 이름으로 댄다. `GrpcCodegenManifest`는 codegen 소유자를 하나로 고정하고 리터럴 생성기 버전을 거절한다.
|
||||
`GrpcDescriptorArtifact`, `GrpcConsumerFixture`, `GrpcSchemaArtifactPublisher`는 schema hash, descriptor digest, 쓰는
|
||||
쪽별 소스 깨짐 보고를 싣고, 쓰는 쪽을 깨뜨리는 게시나 이미 릴리스한 버전을 다른 바이트로 다시 게시하는 것을
|
||||
거절한다.
|
||||
|
||||
커밋한 `buf.yaml`도 같은 규칙을 적으므로, CLI가 있는 환경에서 돌리면 같은 판정에 닿는다.
|
||||
|
||||
## 결과
|
||||
|
||||
**불변식은 강제하고, 과정은 돌리지 않는다.** Task 8부터 11이 다루는 모든 것 — 어떤 schema 변경을 거절하는지, 어떤
|
||||
쓰는 쪽 깨짐이 릴리스를 막는지, 생성을 누가 가지는지 — 이 여기서는 빌드로 검사하는 규칙이다. 빠진 것은 protoc
|
||||
호출과 Buf 바이너리다.
|
||||
|
||||
**codegen을 켜는 것은 한계 있는 변경이다.** `GrpcCodegenManifest.caSkeleton()`이 이미 실제 플러그인 설정이 만족해야
|
||||
할 소유자, 관리되는 버전 출처, 빌드 디렉터리 출력 경로, 겹치지 않는 패키지 정책을 이름으로 댄다. 할 일은 source set
|
||||
예외와 플러그인 블록이지 재설계가 아니다.
|
||||
|
||||
**fixture는 텍스트 codec을 쓴다.** `GrpcTextCodec`이 testkit에 UTF-8 marshaller를 줘서, 프로세스 안 lane과 Netty
|
||||
lane이 생성된 stub 없이 interceptor, status 대응, metadata 한계, stream 순서를 시험할 수 있다. 그 계약은 메시지
|
||||
모양이 아니라 플랫폼과 전송의 성질이므로 바꿔 넣어도 잃는 것이 없다 — 그리고 lane이 codegen이 들어온 뒤가 아니라
|
||||
오늘 돈다.
|
||||
@@ -0,0 +1,54 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 전송·업무·스트림 증거를 서로 대신하지 않는 세 축으로 본다는 결정이다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-003: 전송·업무·stream 증거는 세 축이고, 어느 것도 다른 것을 뜻하지 않는다
|
||||
|
||||
- 상태: 채택
|
||||
- 날짜: 2026-08-30
|
||||
- 범위: `:grpc:grpc-core-api`, `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-testkit`
|
||||
|
||||
## 배경
|
||||
|
||||
실패한 RPC는 status code를 낸다. 그리고 status code는 호출자가 실제로 가진 질문의 답이 아니다. 변경 요청의
|
||||
`DEADLINE_EXCEEDED`는 변경이 일어났는지 말하지 않는다. 요청을 보낸 뒤의 `UNAVAILABLE`은 서버가 그것을 한 번도 보지
|
||||
않았다고 말하지 않는다. 응답 header가 도착했다고 트랜잭션이 커밋된 것은 아니다.
|
||||
|
||||
그 하나하나가 그럴듯한 추론이 중복 쓰기나 잃은 쓰기를 낳는 자리이고, 성공 경로만 시험하는 시험에서는 하나도 보이지
|
||||
않는다.
|
||||
|
||||
## 결정
|
||||
|
||||
일어난 일을 서로 독립인 세 축으로 모델링하고, 축 사이의 추론을 거절한다.
|
||||
|
||||
`GrpcTransportEvidence`는 client가 wire에서 본 것을 기록하고, `NOT_SENT` — client가 자기 보내기가 실패하는 것을 봤다
|
||||
— 와, 아무것도 모르는 다른 모든 경우인 `UNOBSERVED`를 구별한다. `GrpcBusinessEvidence`는 애플리케이션이 확인한 것을
|
||||
기록하고, `COMMIT_UNKNOWN`은 자리표시가 아니라 실제 상태다. `GrpcStreamEvidence`는 sealed 계층이고, 비어 있지 않은
|
||||
경우는 모두 위치를 싣는다. 마지막 순번 없는 「부분」은 이어 가지도 맞춰 보지도 못하기 때문이다.
|
||||
|
||||
`GrpcExecutionEvidence`는 셋을 모두 가지고, 아무도 볼 수 없었을 조합을 거절한다: stream 증거가 있는 unary 호출, 또는
|
||||
client가 보내기 실패를 봤는데도 업무 증거를 실은 요청. 응답 header를 확인된 커밋으로 올리는 것은
|
||||
`withResponseHeadersSeen`을 고쳐야만 할 수 있다. 그것은 interceptor 안의 그럴듯한 한 줄이 아니라 메서드 하나다.
|
||||
|
||||
`GrpcCompletionOutcome.forMutation`이 호출자가 결론 내릴 수 있는 것을 끌어내고, 변경 요청의 `DEADLINE_EXCEEDED`와
|
||||
보낸 뒤의 `UNAVAILABLE`을 기본으로 `COMPLETION_UNKNOWN`으로 둔다.
|
||||
|
||||
실패 모델과 관측 규약이 같은 타입을 쓰므로, 사고 때 호출 하나에 대한 설명이 둘이 아니라 하나다.
|
||||
|
||||
## 결과
|
||||
|
||||
**재시도 결함의 한 종류를 아예 나타낼 수 없게 된다.** `GrpcRetryEligibility`는 세 축 모두와 멱등성 profile을 읽는다.
|
||||
status만으로는 입력이 아니므로, 호출자는 status만 보고 「재시도」에 닿을 수 없다.
|
||||
|
||||
**장애 lane에 검사할 것이 생긴다.** `GrpcTransportEvidenceClassifier`가 client의 관찰을 증거로 바꾸고, 관찰하지 않은
|
||||
상태에서 `NOT_SENT`를 추론하기를 거절한다 — 그리고 lane은 mock이 아니라 호출 중간에 끊은 실제 연결에 대고 그것을
|
||||
시험한다.
|
||||
|
||||
**호출자는 세 번째 결과를 다뤄야 한다.** `COMPLETION_UNKNOWN`은 실패도 성공도 아니고, 둘 중 하나로 다루는 호출자는
|
||||
틀렸다. `GrpcOperationStatusQuery`와 `GrpcCompletionReconciler`는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라
|
||||
지원하는 경로가 되게 하려고 있다.
|
||||
@@ -0,0 +1,112 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 재시도 주인은 하나이고 키가 있는 변경은 영속 원장이 필요하다는 결정이다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-004: 재시도 소유자는 하나이고, 키가 있는 변경에는 durable 원장이 필요하다
|
||||
|
||||
- 상태: 채택
|
||||
- 날짜: 2026-08-30
|
||||
- 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
|
||||
|
||||
## 배경
|
||||
|
||||
gRPC 호출을 재시도할 수 있는 계층이 셋 있다: 애플리케이션, channel의 service config, service mesh. 그 효과는 곱해진다.
|
||||
계층마다 세 번 시도하면 호출 하나에 요청 스물일곱 개이고, 그 부하는 의존 대상이 이미 실패하고 있을 바로 그때 온다.
|
||||
|
||||
따로, 되풀이해도 안전한 변경에는 그것이 돌았다는 기록을 둘 곳이 필요하다. 없으면 응답을 잃은 뒤의 재시도는 효과를
|
||||
겹치게 하거나 버리게 되고, 나중에 둘을 구별할 것이 없다.
|
||||
|
||||
## 결정
|
||||
|
||||
**channel마다 재시도 소유자는 정확히 하나다.** `GrpcRetryOwner`에는 `NONE`을 포함해 값이 넷 있고, `NONE`은 빠뜨림이
|
||||
아니라 결정이다. `GrpcServiceConfigPolicy`는 소유자가 mesh이거나 아무도 아닐 때 프로세스 안 재시도 항목을 거절하고,
|
||||
`GrpcRetryOwnershipValidator`는 service config의 메서드 이름을 정책 catalog와 대조한다 — 이름이 바뀐 메서드는 그 재시도
|
||||
항목이 소리 없이 아무것과도 맞지 않게 되고, 그 메서드는 channel 기본값으로 돈다.
|
||||
|
||||
**재시도 자격은 메서드, 증거, status를 함께 읽는다.** `GrpcRetryEligibility`는 멱등이 아닌 메서드를 바로 거절하고,
|
||||
stream이 앞부분을 전달한 호출을 모두 거절하며, 변경 요청의 `DEADLINE_EXCEEDED`나 보낸 뒤의 `UNAVAILABLE`을 재시도가
|
||||
아니라 「먼저 완료를 풀어라」로 바꾼다.
|
||||
|
||||
**키가 있는 변경은 호출자 키와 durable 원장이 둘 다 있을 때만 재시도할 수 있다.** `GrpcOperationLedger`는
|
||||
`grpc-core-api`의 포트라서, 정책 계층이 데이터베이스에 의존하지 않고 durable 멱등성을 요구할 수 있다. 그 `claim` 계약은
|
||||
unique 제약에 대한 원자적 insert-or-read 하나다: `JpaGrpcOperationLedger`는 먼저 insert하고 제약 위반이면 읽는다.
|
||||
read-then-insert 구현에는 그것이 닫으려는 경쟁만큼 넓은 창이 있고, 두 시도를 동시에 돌리지 않는 모든 시험을
|
||||
통과하기 때문이다.
|
||||
|
||||
identity는 호출자 fingerprint + 전체 메서드 + hash한 키다. 셋 모두 꼭 필요하다: 호출자가 없으면 한 테넌트의 키가 다른
|
||||
테넌트의 쓰기를 막는다. 메서드가 없으면 operation 사이에서 다시 쓴 키 때문에 둘째가 첫째의 재생이 된다.
|
||||
|
||||
## 결과
|
||||
|
||||
**예산이 재시도를 traffic의 비율로 묶는다.** `GrpcRetryBudget`은 모든 것이 실패할 때 재시도가 거의 없는 쪽으로
|
||||
떨어진다. 그것이 의존 대상이 회복하게 하는 동작이다.
|
||||
|
||||
**원장과 변경은 함께 커밋해야 한다.** `JpaGrpcOperationLedger`는 일부러 트랜잭션 애너테이션을 달지 않는다:
|
||||
`REQUIRES_NEW`는 claim을 자기 트랜잭션에 넣어서, 쓰기는 durable한데 claim은 아닌 창을 다시 들인다.
|
||||
|
||||
**claim은 키를 영원히 막지 않고 만료된다**(review 2026-11-01, 03-10). claim TTL이 지난 뒤에도 `IN_PROGRESS`인 claim은
|
||||
죽은 주인이 버린 것으로 보고, 같은 요청의 다음 재시도가 `GrpcOperationLedger.reclaimStale`로 넘겨받는다 — 조건부
|
||||
`UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff` 하나라서, 동시에 넘겨받기 둘이 오면 정확히 하나가 이긴다.
|
||||
`reclaimFailed`와 같은 모양이다. TTL은 `GrpcIdempotencyInterceptor`의 `claimTtl` 인자이고, 키가 있는 모든 메서드의
|
||||
deadline보다 길지 않으면 만들 때 거절한다. 03-11 후속부터 starter는 `app.grpc.platform.operation-ledger-enabled=true`이면
|
||||
interceptor를 조립하고 TTL을 `app.grpc.platform.operation-ledger-claim-ttl`(기본 5m)에서 가져온다. 생성자가 거절하는
|
||||
TTL은 그 키 이름을 대며 기동을 실패시키고, `GrpcOperationLedger` bean 없이 flag를 켜도 기동이 실패한다.
|
||||
|
||||
넘겨받기가 안전한 것은 커밋을 변경 자신의 트랜잭션 안에서 기록하기 때문뿐이다: 그러면 아직 `IN_PROGRESS`인 claim은
|
||||
변경이 한 번도 커밋되지 않았다는 뜻이다. 둘을 따로 커밋하는 채택자는 버려진 claim을 모르는 결과로 만들고, 넘겨받기가
|
||||
변경을 두 번 돌릴 수 있다. 그저 느린 주인을 넘겨받아도 같은 일이 생긴다. 그래서 TTL은 deadline만이 아니라 키가 있는
|
||||
가장 느린 메서드보다 길어야 한다.
|
||||
|
||||
버린 것: heartbeat lease를 단 owner token(outbox lease 모델) — 키가 있는 메서드가 어떤 고정 TTL보다 오래 돌 수 있을 때만
|
||||
필요하다. 그런 메서드가 생기면 다시 본다. 낡은 행을 지우는 sweeper job — 이 family에 없는 scheduler가 필요하고,
|
||||
claim을 지우면 다음 재시도가 시도를 버렸다는 기록 없는 새 claim이 된다.
|
||||
|
||||
**넘겨받긴 주인은 claim token으로 막는다**(re-review 2026-11-03, RR-02-04). 넘겨받기가 죽었다고 보는 주인은 그저 느릴
|
||||
수 있다. 어느 시도가 claim을 쥐었는지 모르면, 그 주인의 늦은 `markFailed`가 새 시도의 claim을 `FAILED_TERMINAL`로
|
||||
만들었고, 다음 재시도가 그것을 다시 claim해서 두 시도가 동시에 변경을 돌렸다. 늦은 `markCommitted`는 새 시도 옆에서
|
||||
커밋했다. 이제 모든 claim은 `GrpcClaimToken`(`claim_attempt`, migration V003)을 싣는다: 첫 claim은 1이고,
|
||||
`reclaimFailed`나 `reclaimStale`마다 하나씩 늘어난다. `decide`는 `PROCEED`에서 그것을 돌려주고, `recordCommit` /
|
||||
`recordFailure`가 그것을 되돌려 준다. 커밋이나 실패는 조건부
|
||||
`UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` 하나다: claim을 잃은 시도의 커밋은 예외로 거절해서
|
||||
그 업무 트랜잭션이 롤백되고, 그런 시도의 실패는 무시한다(`markFailed`가 false를 돌려준다). 같은 조건부 update가 JPA
|
||||
커밋 경쟁도 닫는다 — load-check-save에서는 둘 다 `IN_PROGRESS`를 읽은 커밋 둘이 둘 다 썼다. 이제 정확히 하나만 맞는다.
|
||||
insert와 read 사이에 충돌 행이 지워진 claim은 호출을 실패시키지 않고 insert를 한 번 다시 시도한다.
|
||||
|
||||
`release(identity, claimToken)`도 같은 방식으로 막는다(re-review 2026-11-03 round 2, RR-01-15): 조건부
|
||||
`DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`이고 지웠는지를 돌려준다. 예전에는 키만으로 지웠기
|
||||
때문에, 아무 호출자나 그것을 쥔 시도의 claim이나 재시도가 재생하는 끝난 레코드를 지울 수 있었다. counter는 행 안에
|
||||
있으므로 지운 행의 키는 다시 attempt 1에서 시작한다: token은 행 하나의 시도들을 가르지, 삭제를 넘는 시도들을 가르지
|
||||
않는다. 그래서 두 삭제를 모두 제한한다 — release는 주인이 사라졌다고 아는 claim에만, purge는 어떤 재시도보다 오래 전에
|
||||
끝난 행에만. 버린 것: 포트에서 `release`를 빼기(`markFailed` 뒤 `reclaimFailed`는 counter를 지키지만, 다른 요청을 위해
|
||||
키를 풀어야 하는 배포에는 다른 길이 없다), counter를 지키는 tombstone 행(지울 두 번째 상태가 생기는데, 그 창은 두 제한이
|
||||
이미 닫는다).
|
||||
|
||||
token으로 claim 시각(`WHERE claimed_at = :claimedAt`)을 쓰는 안보다 이것을 골랐다. 시각은 열이 따로 필요 없지만,
|
||||
PostgreSQL은 마이크로초를 저장하고 `Instant`는 나노초를 싣는다. 그래서 호출자가 쥔 token과 저장된 것이 반올림만큼
|
||||
다를 수 있고, 두 프로세스의 시계가 두 시도에 같은 시각을 줄 수 있다. counter에는 두 문제가 다 없다. 위 heartbeat lease는
|
||||
앞과 같은 이유로 계속 버린다. token은 그것 없이 막는다.
|
||||
|
||||
**`operation-ledger-enabled=true`가 약속하는 것(03-11 (b), 2026-11-03 기록, RR-02-07).** 2026-11-01 리뷰는 (a) flag를
|
||||
지우고 원장 bean이 있는지로 판단하기와 (b) flag를 두고 starter가 그것으로 판정 함수를 조립하기를 내놓았다. (b)를
|
||||
지킨다: 조립과 TTL 검증이 채택자마다가 아니라 한곳에 있다. (a)는 거짓 약속을 없애되 조립까지 함께 없애기 때문에
|
||||
버렸다. 한계는 남고, 운영자가 그것을 만나는 곳에 적는다: starter는 서버를 만들지 않으므로 flag는 판정 함수만
|
||||
조립하고, 채택자의 `IDEMPOTENCY` 단계 interceptor나 service adapter가 `decide`와 `recordCommit`을 부를 때 비로소 키가
|
||||
지켜진다. 키가 있는 메서드에 대한 `GrpcPlatformStartupValidator`의 거절이 바로 그것을 말한다. 돌고 있는 프로세스는 그
|
||||
단계가 있는지 볼 수 없으니, validator는 그것을 검사한다고 주장하지 않는다.
|
||||
|
||||
**끝난 행은 보존 기간 뒤에 지우고, 진행 중인 행은 절대 지우지 않는다**(03-10 후속).
|
||||
`GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)`는 cutoff 전에 끝난 `COMMITTED`나 `FAILED_TERMINAL` 행을 오래된
|
||||
것부터 많아야 `limit`개 지운다 — PostgreSQL에서는 migration V002의 부분 index가 받쳐 주는 한계 있는
|
||||
`DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` 하나다.
|
||||
`GrpcOperationLedgerRetention.purgeExpired(now)`가 `app.grpc.platform.operation-ledger-retention`(기본 24h, HTTP 멱등성
|
||||
재생 TTL)을 batch로 적용한다. 레코드가 지워진 뒤의 재시도는 새 claim이고 다시 돈다. 그래서 보존 시간은 호출자의 재시도
|
||||
창보다 길어야 한다. 지우기 일정은 채택자가 잡는다. starter는 정책만 조립한다. 예약된 bean은 모든 배포에 scheduler를
|
||||
강요하고, starter는 어느 replica가 돌려야 하는지 알 수 없기 때문이다.
|
||||
|
||||
**다른 요청에 다시 쓴 키는 중복이 아니라 호출자 오류다.** 저장된 요청 fingerprint가 그것을 소리 없이 첫 요청의 답을
|
||||
돌려주는 대신 `FAILED_PRECONDITION`으로 바꾼다.
|
||||
@@ -0,0 +1,52 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 서버 스트림은 writer 하나, 제한된 큐, 추측하지 않는 resume로 다룬다는 결정이다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-005: stream마다 쓰는 쪽 하나, 한계 있는 queue, 짐작하기를 거절하는 resume
|
||||
|
||||
- 상태: 채택
|
||||
- 날짜: 2026-08-30
|
||||
- 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`)
|
||||
|
||||
## 배경
|
||||
|
||||
`StreamObserver`는 thread-safe가 아니다. 두 producer가 동시에 `onNext`를 부를 때의 실패는 예외가 아니다 — 섞인 바이트이고,
|
||||
client는 그것을 깨진 메시지로, 더 나쁘게는 받지 말았어야 할 유효한 메시지로 decode한다.
|
||||
|
||||
server stream에는 건강해 보이는 방식으로 틀리기 쉬운 성질이 둘 더 있다. 뒤처진 소비자는 stream을 끝내거나 메시지를 소리
|
||||
없이 잃는데, 둘째는 client에게 멀쩡해 보이지만 변경이 빠진 stream을 남긴다. 그리고 재연결은 서버가 아직 재생할 수 있는
|
||||
위치에서 이어 가거나, 더는 없는 것을 건너뛴다.
|
||||
|
||||
## 결정
|
||||
|
||||
**쓰는 쪽 하나가 비우는 한계 있는 queue.** `GrpcSerializedStreamWriter`는 어느 스레드에서든 메시지를 받고, synchronized인
|
||||
`flush`에서만 전송에 넘긴다. `write`가 `ACCEPTED`를 돌려주는 것은 줄 세웠다는 뜻이고, 이름을 일부러 `sent`로 하지
|
||||
않았다: 전송 호출은 바이트를 넘기자마자 돌아오므로, 여기 어떤 메서드도 전달을 정직하게 알릴 수 없다.
|
||||
|
||||
**메시지 한계와 바이트 한계를 둘 다.** 하나만 두면 다른 차원으로는 한계가 없다. `GrpcFlowControlPolicy`는 전송 자신의
|
||||
readiness 신호도 받는다. queue 한계에만 기대는 쓰는 쪽은 메모리를 할당할 수 있는 만큼 빨리 만들어 내기 때문이다.
|
||||
|
||||
**느린 소비자에게는 끝내기가 기본이다.** `GrpcSlowConsumerPolicy.DROP_OLDEST`는 업무 뜻이 손실을 견디는 feed를 위해
|
||||
있고 기본값이 아니다. client는 버려진 메시지를 알아챌 수 없기 때문이다: client가 보는 순번은 보내진 것의 순번이다.
|
||||
|
||||
**resume은 꾸며 내지 않고 거절한다.** `GrpcStreamGapDetector`는 서명됐고 만료되지 않았으며 호출자·필터 fingerprint가
|
||||
지금 요청과 맞는 token을 요구하고, snapshot version이 움직인 token을 거절하며, cursor가 보존한 이력보다 앞서면
|
||||
`FULL_RESYNC_REQUIRED`를 돌려준다. `GrpcResumeToken`은 key id를 싣는다. 그래서 서명 키를 바꿔도 아직 쓰이는 모든 token이
|
||||
무효가 되지 않는다.
|
||||
|
||||
## 결과
|
||||
|
||||
**stream은 맨 payload가 아니라 envelope을 싣는다.** `GrpcStreamEnvelope`은 stream id, generation, 순번, snapshot version,
|
||||
resume token을 가진다. resume, 빈틈 찾기, 비우기가 모두 위치와 generation을 필요로 하기 때문이다.
|
||||
|
||||
**시계는 하나가 아니라 넷이다.** `GrpcStreamLifetimePolicy`는 준비 deadline, idle timeout, 최대 지속 시간, heartbeat
|
||||
간격을 나누고, 하나가 절대 울릴 수 없는 조합을 거절한다. 어느 둘을 합치든 익숙한 결함이 나온다: 최대 지속 시간으로 쓴
|
||||
idle timeout은 건강하게 바쁜 stream을 죽인다.
|
||||
|
||||
**heartbeat는 살아 있다는 신호이고 그 밖의 무엇도 아니다.** 애플리케이션 확인 응답도 순서 보장도 아니다.
|
||||
`GrpcStreamHeartbeat`가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다.
|
||||
@@ -0,0 +1,67 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-31
|
||||
- 요약: Stable discovery는 DNS와 정적 목록이고 Kubernetes에서는 누가 부하를 나누는지 profile이 정한다는 결정이다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-006: Stable discovery는 DNS와 static이고, Kubernetes profile은 누가 분산하는지 이름으로 댄다
|
||||
|
||||
- 상태: 채택
|
||||
- 날짜: 2026-08-31
|
||||
- 범위: `:grpc:grpc-runtime`(예전 `grpc-discovery`, `grpc-client`)
|
||||
|
||||
## 배경
|
||||
|
||||
gRPC channel의 discovery 설정에는 런타임 증상이 없는 실패 방식이 있다: 동작은 하는데, 대시보드가 말하는 일을 하지 않는다.
|
||||
|
||||
구체적인 경우는 Kubernetes Service ClusterIP 위의 `round_robin`이다. Service는 가상 주소 하나라서 resolver가 endpoint 하나를
|
||||
돌려주고 client 쪽 분산기는 돌려 가며 보낼 대상이 없다. kube-proxy는 연결할 때 pod를 고르고, HTTP/2 연결은 오래 살기
|
||||
때문에, 그 client의 모든 요청이 연결이 사는 동안 같은 pod로 간다. 실패하는 것은 없다. 설정은 `round_robin`이라고 말하고,
|
||||
metric은 요청이 pod가 아니라 client 사이에 퍼진 것을 보여 주며, 「client 쪽 부하 분산을 한다」는 결론은 아무도 확인할
|
||||
계기가 없는 방식으로 틀렸다.
|
||||
|
||||
거울상 실수는 headless record 위의 `pick_first`다. 많은 pod 중 하나에 client를 묶는다.
|
||||
|
||||
따로, service mesh는 재시도를 누가 가지는지 바꾸고, mesh 라우팅을 더하면서 자기 재시도 정책을 빼지 않은 배포는 효과가
|
||||
곱해지는 재시도자 둘을 가진다.
|
||||
|
||||
## 결정
|
||||
|
||||
**Stable resolver는 Static, DNS, Unix domain socket이고, Stable 부하 분산은 `pick_first`와 `round_robin`이다.**
|
||||
`GrpcDiscoveryPolicyValidator.requireStableScheme`은 `xds`, `consul`, `etcd`, `eureka`를 이름으로 거절하고, 그것이 모르는
|
||||
scheme이 아니라 자기 control plane과 승격 gate를 가진 Advanced capability라고 메시지로 말한다.
|
||||
|
||||
**짝 맞춤은 의도가 아니라 해석된 주소 수와 대조한다.** `GrpcResolverProfile`은 `expectedAddressCount`를 싣고,
|
||||
`GrpcStableLoadBalancer.effective`가 그 수의 endpoint 위에서 정책이 무언가를 분산하는지 답한다. 주소 하나 위의
|
||||
`round_robin` profile은 보고되는 위반이고, 그 메시지는 그것이 일어나지 않는 퍼뜨리기를 설명한다고 말한다.
|
||||
|
||||
**Kubernetes 배포는 자기 라우팅 모드를 이름으로 대고**, 그 모드가 분산기와 재시도 소유자를 둘 다 정한다.
|
||||
`GrpcKubernetesRoutingMode`에는 값이 셋 있다 — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — 그리고 `GrpcKubernetesProfile`은 재시도
|
||||
소유자가 프로세스 안에서 재시도하는 mesh profile을 거절한다.
|
||||
|
||||
**오래 사는 stream을 싣는 profile은 재연결 예산과 readiness 비우기 유예를 밝혀야 한다.** stream은 사는 내내 client를 pod
|
||||
하나에 묶으므로, 모든 rollout, eviction, scale-down이 그것을 끝낸다. `GrpcKubernetesProfileValidator`는 긴 stream을 싣는
|
||||
VIP profile과, 재연결 예산보다 짧은 비우기 유예도 알린다 — 후자는 client가 다른 곳으로 재연결을 마치기 전에 pod가 응답을
|
||||
멈춘다는 뜻이다.
|
||||
|
||||
**DNS profile은 새로 고쳐야 한다.** `GrpcResolverProfile`은 DNS에서 새로 고침 간격 0을 거절한다. 기동 때 한 번 해석한
|
||||
channel은 한 시간 전에 없어진 주소로 계속 보내고, 그 결과인 `UNAVAILABLE`은 rollout이 끝난 지 한참 뒤에도 건강하지 않은
|
||||
배포처럼 보인다.
|
||||
|
||||
## 결과
|
||||
|
||||
**validator는 하나가 아니라 둘이다.** `GrpcDiscoveryPolicyValidator`는 분산기가 자기가 볼 주소 위에서 무언가를 하는지
|
||||
묻는다. `GrpcKubernetesProfileValidator`는 배포 모양, 재시도 소유자, stream 의무가 맞는지 묻는다. 배포는 resolver profile이
|
||||
앞뒤가 맞으면서도 재시도를 두 곳에 둘 수 있다. 그래서 둘을 합치면 한 답이 다른 답을 가린다.
|
||||
|
||||
**`expectedAddressCount`는 어딘가에서 와야 한다.** 선언한 숫자이고, 선언은 틀릴 수 있다. 그래도 아무것도 비교하지 않는
|
||||
대안보다 낫다: 틀린 선언은 누가 적어 둔 틀린 말이고, 빠진 선언은 아무도 묻지 않은 질문이다.
|
||||
`GrpcChannelProfileValidator`는 기동 때 알 수 있는 곳에서는 해석된 수를 받고, 알 수 없는 곳에서는 짐작해서 아직 해석할 수
|
||||
없는 이름에서 실패하는 대신 검사를 건너뛴다.
|
||||
|
||||
**xDS에는 닿을 수 있지만, 이 길로는 아니다.** xDS는 `grpc-advanced`(패키지 `resilience`/`xds`)에서 자기 capability flag와
|
||||
운영 승인 뒤에 있고, `GrpcXdsStartupGuard.advertisableAsStableSupport()`가 false를 돌려주므로 Stable 지원 설명이 조용히
|
||||
넓어질 수 없다. ADR-GRPC-ADV-001을 본다.
|
||||
@@ -0,0 +1,57 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 고급 기능마다 따로 플래그·등급·승격 기준을 둔다는 결정이다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-advanced-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-ADV-001: advanced capability마다 자기 flag, 자기 등급, 자기 승격이 있다
|
||||
|
||||
- 상태: 채택
|
||||
- 날짜: 2026-08-30
|
||||
- 범위: `:grpc-advanced:*`
|
||||
|
||||
## 배경
|
||||
|
||||
advanced 계획은 capability 열여섯을 다룬다. 그것들이 함께 가져오는 것은 몇 자릿수씩 다르다. gRPC-Web은 proxy를 더한다.
|
||||
Reactor는 의존 하나를 더한다. xDS는 control plane, 그 장애 방식, 자기 보안 경계, 자기 버전 어긋남을 더한다. hedging은 운영
|
||||
traffic을 겹친다.
|
||||
|
||||
그것들을 flag 하나로 묶으면 가장 싼 것을 켜는 일이 가장 무거운 것을 켜는 일과 같은 결정이 된다.
|
||||
|
||||
## 결정
|
||||
|
||||
**capability마다 flag 하나.** `ca-skeleton.grpc.advanced.<capability>.enabled` 아래에 있고, 기본은 모두 꺼짐이다.
|
||||
|
||||
**등급 넷.** `ADVANCED_STABLE`은 flag로 시작한다. `EXPERIMENTAL`은 따로 운영 승인도 필요하다. flag는 누가 그 기능을 원했다는
|
||||
뜻이고, 승인은 누가 그 장애 방식이 다 밝혀지지 않았음을 받아들였다는 뜻이기 때문이다. `WATCH`는 아예 시작할 수 없다.
|
||||
`DISABLED`는 거둬들인 것이다.
|
||||
|
||||
`GrpcAdvancedModuleGuard`는 세 거절 — flag 없음, 시작할 수 없는 등급, 운영 승인 없음 — 을 구별한다. 경우마다 고치는 법이
|
||||
다르기 때문이다.
|
||||
|
||||
**승격 증거는 capability마다다.** `GrpcAdvancedPromotionEvidence`는 capability마다 record 하나라서, 어떤 승격도 다른 것을
|
||||
끌고 가지 못한다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`은 빈 목록을 돌려주고, 그것은 주장이 아니라 시험한
|
||||
성질이다. (2026-09-28: gate 클래스는 자기 시험 밖에서 부르는 것이 없어서 지웠다 — review 2026-09-24 S5-lead-4.
|
||||
capability별 규칙은 `docs/runbooks/grpc-advanced-capabilities.md`의 리뷰 규칙으로 남는다.) 문턱은 둘이다:
|
||||
`ADVANCED_STABLE`에는 7일 soak와 완전한 증거, Stable 기본값에는 30일. 후자는 모든 배포가 그 capability의 의존과 장애 방식을
|
||||
받는다는 뜻이기 때문이다.
|
||||
|
||||
**기반 시설은 capability마다 이름으로 댄다.** `GrpcAdvancedInfrastructureTestkit`은 gRPC-Web에는 proxy가, Servlet에는
|
||||
container가, xDS에는 멈출 수 있는 control plane이, Kotlin에는 toolchain이 필요하다고 적는다. 기반 시설 없이 도는 suite는
|
||||
통과하고 아무것도 세우지 않는다. 없는 것보다 나쁘다.
|
||||
|
||||
## 결과
|
||||
|
||||
**Kotlin 어댑터는 여기서 실패하면 닫히고, 이유를 말한다.** 이 저장소에는 Kotlin toolchain이 없어서
|
||||
`GrpcKotlinCompatibilityGate.supportableHere()`가 false를 돌려준다. 계약 요구 넷 — schema 출처 하나, coroutine 취소 전파,
|
||||
Stable 한계 안의 Flow backpressure, 플랫폼 증거 타입 보존 — 은 검사할 수 있고 검사한다. 빠진 것은 compile lane뿐이다.
|
||||
|
||||
**Edition 2026은 그 watch 보고가 무어라 하든 쓸 수 없다.** `GrpcEdition2026Guard`는 보고에 따라 달라지지 않는다. 상태 기록이
|
||||
사용까지 허락하게 두면, 누가 필드 넷을 SUPPORTED로 표시하는 순간 schema가 승격 결정도, 쓰는 쪽 옮기기도, ADR도 없이 그
|
||||
edition으로 옮겨 가기 때문이다.
|
||||
|
||||
**xDS는 Stable 지원 설명의 일부가 아니다.** flag와 승인 뒤에서 동작한다. `GrpcXdsStartupGuard.advertisableAsStableSupport()`가
|
||||
false를 돌려주므로 support matrix가 조용히 넓어질 수 없다.
|
||||
@@ -0,0 +1,224 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 타입 안전 gRPC 실행 플랫폼 계획을 이 저장소의 구조와 게이트에 맞춘 설계다.
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 타입 안전 gRPC 실행 플랫폼 — 이 저장소 규약으로의 어댑팅 설계
|
||||
|
||||
두 계획 문서를 이 저장소(`ca-skeleton`)의 실제 구조·정책·빌드 게이트에 맞춰 실행 가능한 형태로
|
||||
옮기는 설계다.
|
||||
|
||||
- 원본 A: `docs/2026-08-13-grpc-type-safe-rpc-platform-implementation-plan.md` (Stable, Task 1–53)
|
||||
- 원본 B: `docs/2026-08-13-grpc-advanced-capabilities-expansion-plan.md` (Advanced, Task 1–18)
|
||||
|
||||
원본은 `modules/grpc/**` · Gradle Kotlin DSL · 패키지 `io.backend.skeleton.grpc` · Spring Boot 4.1을
|
||||
전제한다. 이 저장소는 `src/**` · Groovy DSL · `dev.caskeleton` · Spring Boot 4.0.8 · fail-closed
|
||||
module registry를 쓴다. 원본 Global Constraint의 마지막 항목이 이 어댑팅을 명시적으로 허용한다:
|
||||
"실제 저장소 구조가 예상 경로와 다르면 파일 경로만 매핑하고 공개 계약·불변 조건·테스트 의미는
|
||||
변경하지 않는다."
|
||||
|
||||
## 1. 패밀리 위치 — 왜 `adapter:inbound:grpc` 확장이 아닌가
|
||||
|
||||
원본이 기술하는 것은 인바운드 어댑터 하나가 아니라 **자기 API·SPI·adapter·조립 경계를 가진 벤더드
|
||||
RPC 플랫폼**이다. 이 저장소에는 그 형태의 선례가 이미 있다 — `messaging:*`. root `CLAUDE.md`가
|
||||
직접 그렇게 규정한다: "vendored messaging platform: a product with its own API, SPI, adapters and
|
||||
composition boundary, not a layer of this application".
|
||||
|
||||
따라서 gRPC 플랫폼도 같은 자리에 둔다.
|
||||
|
||||
```text
|
||||
src/grpc/ → :grpc:* Stable 플랫폼 (12 leaf)
|
||||
src/grpc-advanced/ → :grpc-advanced:* Advanced/Experimental (6 leaf)
|
||||
src/adapter/inbound/grpc 기존 인바운드 전송 어댑터 (그대로 유지)
|
||||
```
|
||||
|
||||
`grpc-advanced`를 별도 디렉터리·별도 Gradle prefix로 分離하는 이유는 원본 Stable Task 1의 불변
|
||||
조건 "Stable starter가 `modules/grpc-advanced`를 참조하면 build를 실패시킨다"를 registry의
|
||||
`allowed_dependencies`만으로 기계 검증할 수 있게 만들기 위해서다. `verifyCleanArchitectureDependencies`가
|
||||
그 게이트다.
|
||||
|
||||
패키지 루트는 `dev.caskeleton.grpc` / `dev.caskeleton.grpc.advanced`다.
|
||||
|
||||
## 2. Leaf 매핑 — 원본 31개 모듈 → 이 저장소 18개 leaf
|
||||
|
||||
원본 모듈 경계 중 **이 저장소가 이미 다른 메커니즘으로 표현하는 것**만 합친다. 능력(capability)은
|
||||
하나도 버리지 않는다.
|
||||
|
||||
> **2026-09-28 변경(리뷰 후속 S7-#3·S7-#13, 소유자 결정 18).** 아래 두 표는 채택 당시의 leaf 구성이다.
|
||||
> 현재는 `grpc-policy`·`grpc-server`·`grpc-client`·`grpc-discovery`·`grpc-admin` → `grpc-runtime`,
|
||||
> `grpc-proto-contract`·`grpc-codegen` → `grpc-contract`(protobuf Gradle 플러그인 + CI의 Buf, D5/D6 폐기 —
|
||||
> ADR-GRPC-002 superseded), `grpc-advanced-bootstrap`·`-edition`·`-streaming`·`-resilience`·`-diagnostics`
|
||||
> → `grpc-advanced`로 합쳐졌다. `grpc-advanced-compat`은 그대로다. 패키지 이름은 바뀌지 않았다. 현재
|
||||
> leaf 목록은 registry(`src/config/architecture/modules.json`)가 SSOT다.
|
||||
|
||||
### Stable — `src/grpc/`
|
||||
|
||||
| leaf | 원본 모듈 | 담는 Task | 의존 |
|
||||
| --- | --- | --- | --- |
|
||||
| `grpc-core-api` | grpc-core-api | 2–7 | (없음, Java stdlib) |
|
||||
| `grpc-proto-contract` | grpc-proto-contract | 8 | core-api |
|
||||
| `grpc-codegen` | grpc-codegen | 9–11 | core-api, proto-contract |
|
||||
| `grpc-policy` | grpc-policy | 12, 16, 17, 20, 28–31, 33, 34, 37–43 | core-api |
|
||||
| `grpc-server` | grpc-server | 13–15, 18, 19 | core-api, policy |
|
||||
| `grpc-client` | grpc-client | 24–27 | core-api, policy |
|
||||
| `grpc-discovery` | grpc-discovery | 35, 36 | core-api, client |
|
||||
| `grpc-admin` | grpc-admin | 21–23, 45 | core-api, server |
|
||||
| `grpc-observability` | grpc-observability | 44 | core-api |
|
||||
| `grpc-operation-ledger-jpa` | grpc-operation-ledger-jpa | 32 | core-api |
|
||||
| `grpc-spring-boot-starter` | grpc-spring-boot-starter | 52 | 위 전부 |
|
||||
| `grpc-testkit` | testkit-core + -inprocess + -netty + -fault | 46–51, 53 | 위 전부 |
|
||||
|
||||
**testkit 4개를 1개로 합친 근거.** 원본이 testkit을 넷으로 쪼갠 목적은 "in-process 증거를 실제
|
||||
네트워크 증거로 오인하지 않게 한다"이다. 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test
|
||||
lane** 컨벤션(`ca.strict-test-lane`)으로 이미 표현한다 — lane은 태그/소스셋/명시 테스트 중 하나로만
|
||||
선택하고, 아무것도 실행하지 않으면 실패하며, up-to-date 결과를 제공하지 않는다. 그래서 네 모듈은
|
||||
`grpc-testkit` 한 leaf 안의 네 lane이 된다:
|
||||
`grpcInProcessContractTest`, `grpcNettyContractTest`, `grpcFaultTest`, `grpcPerformanceTest`.
|
||||
원본의 "in-process는 HTTP/2·TLS 증거가 아니다"는 lane 분리와 `GrpcEvidenceGrade`로 강제한다.
|
||||
|
||||
### Advanced — `src/grpc-advanced/`
|
||||
|
||||
| leaf | 원본 모듈 | 담는 Task |
|
||||
| --- | --- | --- |
|
||||
| `grpc-advanced-bootstrap` | grpc-advanced-bootstrap | A1, A18 |
|
||||
| `grpc-advanced-edition` | grpc-edition-2024 + grpc-edition-2026-experimental | A2, A3 |
|
||||
| `grpc-advanced-streaming` | grpc-client-streaming + grpc-bidi-streaming + grpc-manual-flow-control | A4–A7 |
|
||||
| `grpc-advanced-resilience` | grpc-hedging + grpc-custom-resolver + grpc-custom-load-balancer + grpc-xds | A8–A11 |
|
||||
| `grpc-advanced-compat` | grpc-web + grpc-servlet-compat + grpc-integration-bridge + grpc-reactor + grpc-kotlin | A12–A16 |
|
||||
| `grpc-advanced-diagnostics` | grpc-channel-diagnostics | A17 |
|
||||
|
||||
Advanced 모듈은 capability마다 leaf를 나누는 대신 **capability grade와 feature flag**
|
||||
(`GrpcAdvancedCapability` / `GrpcAdvancedFeatureFlags`)로 분리한다. A18의 요구사항
|
||||
"Edition, streaming, xDS, gRPC-Web, Servlet, language adapter가 서로의 승격을 묶지 않는다"는
|
||||
leaf 경계가 아니라 capability별 독립 promotion evidence로 표현되므로, 합쳐도 그 불변 조건은 유지된다.
|
||||
|
||||
## 3. 원본과 달라지는 지점 (deviation)과 근거
|
||||
|
||||
| # | 원본 | 이 저장소 | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| D1 | Spring Boot 4.1 BOM | Spring Boot 4.0.8 BOM | 저장소 실제 baseline(`src/build.gradle:13`). BOM이 SSOT라는 계약 자체는 유지 |
|
||||
| D2 | Boot-managed Spring gRPC starter | self-managed `io.grpc` (`ext.grpcVersion`) | 기존 기록된 결정(`adapter/inbound/grpc/README.md` "왜 self-managed Netty 인가"). starter 커플링 회피 |
|
||||
| D3 | Gradle Kotlin DSL, `settings.gradle.kts` | Groovy DSL + `config/architecture/modules.json` | registry가 leaf 목록의 SSOT이고 settings는 그것을 읽기만 한다 |
|
||||
| D4 | `io.backend.skeleton.grpc` | `dev.caskeleton.grpc` | 저장소 기본 패키지 |
|
||||
| D5 | Buf CLI (`bufLint`/`bufBreaking` 등) | 저장소 소유 규칙 엔진 + Gradle verify task | Buf CLI 바이너리가 이 환경에 없다. lint/format/breaking **규칙**을 Java로 구현해 동일 판정을 내리고, CLI는 동일 규칙을 재확인하는 선택 경로로 남긴다 |
|
||||
| D6 | protoc/grpc-java codegen을 빌드에서 실행 | `.proto` 소스 + codegen **정책·descriptor 계약**만 실행, protoc 실행은 명시적 확장점 | 아래 별도 절 |
|
||||
| D7 | `grpc-kotlin`의 `.kt` 소스 | Java 쪽 coroutine/Flow **경계 계약**만 | 저장소에 Kotlin 플러그인·소스셋이 없다. A16의 5개 요구사항 중 4개(스키마 단일 소스, cancellation 전파 계약, backpressure 우회 금지, evidence 타입 보존)는 Java 계약으로 표현 가능하고, Kotlin 툴체인 lane은 `GrpcKotlinCompatibilityGate`가 미충족으로 fail-closed 판정한다 |
|
||||
| D8 | 새 leaf가 곧 런타임 | 신규 leaf 전부 `build: "optional-grpc"` (main runtime composition은 별도 Gradle edge로 결정) (build-only) | `messaging:*`가 처음 착지한 방식과 동일. 런타임 투입은 registry membership 변경 + `verifyRuntimeModuleMembership` 통과가 선행 조건이며, 그것은 별도 결정이다 |
|
||||
|
||||
### D6 — protoc 실행을 지금 켜지 않는 이유
|
||||
|
||||
이 저장소의 모든 leaf는 예외 없이 spotless(google-java-format) · checkstyle · spotbugs(HIGH) ·
|
||||
errorprone · `-Werror`를 통과해야 한다(`src/build.gradle`의 `configure(subprojects)` 블록). protoc가
|
||||
만든 소스는 그 어느 것도 통과하지 못하므로, 실제 codegen을 켜려면 해당 소스셋에서 다섯 게이트를
|
||||
모두 끄는 carve-out이 필요하다. 저장소에 선례는 있다(`jmh` 소스셋). 하지만 그 carve-out은 Task
|
||||
10 하나를 위해 품질 게이트를 여는 결정이고, 그 결정은 이 작업 범위 밖의 승인 사항이다.
|
||||
|
||||
그래서 Task 8–11의 **불변 조건**은 전부 실행 가능한 형태로 구현한다:
|
||||
proto style 규칙 검증, 삭제 필드 `reserved` 이력 대조, Buf breaking category(`FILE`) 판정,
|
||||
generated package와 hand-written package 겹침 금지, descriptor+schema hash 릴리스 아티팩트,
|
||||
consumer fixture 실패 시 릴리스 차단. 빠지는 것은 protoc 프로세스 호출 하나이고,
|
||||
`GrpcCodegenManifest`가 그 지점을 단일 owner로 고정한 채 비워둔다.
|
||||
|
||||
## 4. 유지되는 원본 불변 조건 (변경 없음)
|
||||
|
||||
- 실행 증거 3축(Transport/Business/Stream) 분리, `RESPONSE_HEADERS_SEEN` → `COMMIT_CONFIRMED` 자동 승격 금지
|
||||
- `DEADLINE_EXCEEDED` mutation = `COMPLETION_UNKNOWN` 후보, `UNAVAILABLE`만으로 상태 변경 RPC 재호출 금지
|
||||
- `NON_IDEMPOTENT`에 explicit retry·hedging 금지, explicit retry owner는 하나
|
||||
- Stable Unary는 positive deadline 필수
|
||||
- Server Streaming: bounded queue + single serialized writer, partial delivery 후 whole-call retry 금지
|
||||
- Stable RPC 유형은 Unary·Server Streaming, Client/Bidi는 Advanced
|
||||
- production reflection 기본 비활성, dev·stage·prod TLS 필수, trust-all 금지
|
||||
- Stable resolver = Static·DNS, Stable LB = pick_first·round_robin
|
||||
- metric tag에 raw metadata/payload/actor/tenant/object/stream/idempotency ID 금지
|
||||
- Netty가 Stable certification transport, in-process는 network/TLS 증거가 아님
|
||||
|
||||
## 5. 애플리케이션이 이 패밀리에 도달하는 경로
|
||||
|
||||
`messaging:*`의 MSG-015(bridge 부재)를 반복하지 않는다. 계약상의 경로는
|
||||
|
||||
```text
|
||||
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-server SPI
|
||||
```
|
||||
|
||||
이고, Stable Task 13/14가 그 경계를 소유한다(`GrpcApplicationBoundaryRules`,
|
||||
`GrpcRawApiImportRule`, `GrpcServiceAdapter`). 플랫폼이 green이 된 뒤 마지막 단계에서
|
||||
`adapter-inbound-grpc`의 `allowed_dependencies`에 `grpc-core-api`·`grpc-server`를 추가하고
|
||||
브리지를 배선한다. 그 전까지 플랫폼은 self-contained build-only다.
|
||||
|
||||
## 6. 원본 파일 목록 대비 대조 (2026-08-31 감사)
|
||||
|
||||
두 계획이 `Files:` 절에 명시한 산출물 전체를 기계적으로 대조했다. 감사 스크립트는 각 Task의 파일
|
||||
basename이 저장소에 존재하는지 확인한다(build 산출물 제외, 단 annotation processor가 생성하는
|
||||
`spring-configuration-metadata.json`은 build 출력에서 확인).
|
||||
|
||||
```text
|
||||
STABLE (Task 1–53) : present=250 missing=11
|
||||
ADVANCED (Task 1–18) : present= 91 missing= 2
|
||||
TOTAL : present=341 missing=13
|
||||
```
|
||||
|
||||
잔여 13건은 전부 아래 편차로 설명된다. **행동이 빠진 것은 없다.**
|
||||
|
||||
### 6.1 ADR 파일명 (6건) — 저장소 명명 규약
|
||||
|
||||
계획은 `ADR-060` ~ `ADR-065` 연번을 쓴다. 이 저장소의 `docs/adr/`는 접두사 규약을 쓴다
|
||||
(`ADR-WS-001`, `ADR-MONGO-004`, `ADR-WEB-ADV-003`). 내용은 1:1이다.
|
||||
|
||||
| 계획 | 이 저장소 |
|
||||
| --- | --- |
|
||||
| ADR-060 platform-boundary | `ADR-GRPC-001-platform-family-and-registry-shape.md` |
|
||||
| ADR-061 execution-evidence | `ADR-GRPC-003-three-axis-execution-evidence.md` |
|
||||
| ADR-062 retry-idempotency | `ADR-GRPC-004-retry-ownership-and-durable-idempotency.md` |
|
||||
| ADR-063 streaming-resume | `ADR-GRPC-005-server-streaming-single-writer-and-resume.md` |
|
||||
| ADR-064 discovery-kubernetes | `ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md` |
|
||||
| ADR-065 advanced-promotion | `ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md` |
|
||||
|
||||
계획에 없던 `ADR-GRPC-002-schema-governance-without-protoc.md`가 추가로 있다 — D6 결정을 기록한다.
|
||||
|
||||
### 6.2 codegen convention plugin 3건 — D6
|
||||
|
||||
`io.backend.grpc-buf-conventions.gradle.kts`, `io.backend.grpc-codegen-conventions.gradle.kts`,
|
||||
그 `.properties`. protoc를 실행하지 않으므로 실행할 convention plugin이 없다. 이들이 고정했을 결정은
|
||||
`GrpcCodegenManifest`·`GrpcCodegenOutput`·`GrpcGeneratedPackagePolicy`가 Java로 강제하고,
|
||||
`buf.yaml`·`buf.gen.yaml`·`buf.lock`이 CLI가 있는 환경에서 같은 판정을 내리도록 커밋되어 있다.
|
||||
|
||||
### 6.3 TLS 인증서 3건 — 런타임 생성으로 대체
|
||||
|
||||
`ca.crt`, `server.crt`, `client.crt`. 커밋된 인증서는 만료되고, 커밋된 개인키는 개인키다.
|
||||
`GrpcTlsTestMaterial`이 JDK `keytool`로 fixture마다 PKCS12를 생성하고 `close()`가 지운다. Netty의
|
||||
`SelfSignedCertificate`는 JDK 21에서 `sun.security.x509` 미export로 실패하므로 쓰지 않았다.
|
||||
|
||||
### 6.4 Kotlin 소스 1건 — D7
|
||||
|
||||
`GrpcCoroutineAdapter.kt`. 저장소에 Kotlin 툴체인이 없다. 계약 요구 4건은 Java로 검증하고
|
||||
(`GrpcKotlinProfile`, `GrpcCoroutineContextBridge`), compile lane은
|
||||
`GrpcKotlinCompatibilityGate.supportableHere()`가 `false`로 fail-closed다.
|
||||
|
||||
### 6.5 2026-08-31 감사에서 실제로 메꾼 것 (6건)
|
||||
|
||||
감사가 아니었으면 남았을 것들이다.
|
||||
|
||||
| 항목 | 조치 |
|
||||
| --- | --- |
|
||||
| `GrpcKubernetesProfileValidator` | 이름 있는 타입으로 분리. VIP+장기스트림, drain grace < reconnect budget 두 규칙 추가 |
|
||||
| ADR-064 상당 (discovery/Kubernetes) | `ADR-GRPC-006` 작성 |
|
||||
| xDS `bootstrap.json` | 테스트 리소스로 추가 + `GrpcXdsStartupGuard.bootstrapMismatches`가 실제로 대조 (namespace 불일치·비TLS control plane 검출) |
|
||||
| `control-plane-snapshot.json` | 테스트 리소스로 추가 + redactor가 실제 모양의 데이터로 검증됨 |
|
||||
| `DocumentClientFixture.java` + fixture `build.gradle.kts` | 추가. `GrpcConsumerFixture.fromJavaSource`가 fixture 소스에서 service·method·package 요구사항을 **역산**하므로 손으로 적은 목록이 아니다 |
|
||||
| `buf.gen.yaml`, `buf.lock` | 추가 + proto contract 테스트가 내용을 검증 |
|
||||
|
||||
### 6.6 테스트 클래스 17건 — 감사 후 계획대로 분리
|
||||
|
||||
감사 시점에 leaf별로 통합돼 있던 테스트를 계획이 명시한 이름으로 분리했다. 분리 전에도 모든
|
||||
타입이 실제로 검증되고 있었으나(통합 클래스가 해당 타입을 참조), 계획과의 추적성을 위해 나눴다:
|
||||
|
||||
`GrpcNettyVariantSelectorTest`, `GrpcReflectionPolicyTest`, `GrpcClientMetadataPolicyTest`,
|
||||
`GrpcKubernetesProfileTest`, `GrpcEdition2026GuardTest`, `GrpcClientStreamPolicyTest`,
|
||||
`GrpcClientMessageDeduplicatorTest`, `GrpcBidiSequenceTrackerTest`, `GrpcDemandControllerTest`,
|
||||
`GrpcHedgingEligibilityTest`, `GrpcResolverSafetyPolicyTest`, `GrpcLoadBalancerSafetyPolicyTest`,
|
||||
`GrpcXdsStartupGuardTest`, `GrpcWebCompatibilityGateTest`, `GrpcServletStartupValidatorTest`,
|
||||
`GrpcIntegrationBridgePolicyTest`, `GrpcReactorContextBridgeTest`, `GrpcKotlinCompatibilityGateTest`.
|
||||
@@ -159,7 +159,7 @@ PR 단계 trivy 검사(`dependency-vulnerability.yml`의 HIGH·CRITICAL 단계)
|
||||
|
||||
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|
||||
|---|---|---|---|---|
|
||||
| B-55 | 삭제: `src/platforms/grpc`, `src/platforms/grpc-advanced`, `src/platforms/optional-build`(두 번째 빌드 `optional-platforms` 전체), registry의 `"build": "optional-grpc"` 9행, workflow job `ci-quality-gates.yml` `optional-platforms`·`grpc-proto-buf`(그리고 `release-gate`의 두 `needs`), `integration-main.yml`의 optional 성능 단계와 job `grpc-optional-platform-integration`, `release.yml` job `grpc-stable-release-gate`(그리고 이미지 job의 `needs` 한 줄), 문서 `docs/adr/ADR-GRPC-001`~`006`·`ADR-GRPC-ADV-001`, `docs/compatibility/`(폴더째), `docs/runbooks/grpc-platform-operations.md`·`grpc-advanced-capabilities.md`, `docs/design/2026-08-30-grpc-platform-adaptation-design.md`. 새 자리는 grpc-library repo이고 같은 이름의 파일이 이력째 있다. 그 repo에서 Java 패키지는 `com.hyeonworks.grpc`, proto 패키지는 `hyeonworks.grpc.common.v1`이다 | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌이 난다. `project(':grpc:…')`·`project(':grpc-advanced:…')`나 `-p platforms/optional-build`를 쓴 서비스는 빌드가 실패한다 | 쓰지 않았으면 삭제를 그대로 받는다. 썼으면 grpc-library 첫 버전(`1.0.0`, 소유자가 태그를 단 뒤)을 좌표 `com.hyeonworks.grpc:<모듈>:1.0.0`으로 받고(저장소 선언은 그 repo README 「받는 법」), import를 `dev.caskeleton.grpc` → `com.hyeonworks.grpc`로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절, `docs/work/reference/related-repos.md` |
|
||||
| B-55 | 삭제: `src/platforms/grpc`, `src/platforms/grpc-advanced`, `src/platforms/optional-build`(두 번째 빌드 `optional-platforms` 전체), registry의 `"build": "optional-grpc"` 9행, workflow job `ci-quality-gates.yml` `optional-platforms`·`grpc-proto-buf`(그리고 `release-gate`의 두 `needs`), `integration-main.yml`의 optional 성능 단계와 job `grpc-optional-platform-integration`, `release.yml` job `grpc-stable-release-gate`(그리고 이미지 job의 `needs` 한 줄), 살아 있는 문서 `docs/compatibility/`(폴더째), `docs/runbooks/grpc-platform-operations.md`·`grpc-advanced-capabilities.md`. 새 자리는 grpc-library repo이고 같은 이름의 파일이 이력째 있다. 기록(`docs/adr/ADR-GRPC-*` 7개, `docs/design/2026-08-30-grpc-platform-adaptation-design.md`)은 본문을 두고 머리 블록 「현재 정본」만 그 repo를 가리키게 했다. 사본이 그 repo에도 있다. 그 repo에서 Java 패키지는 `com.hyeonworks.grpc`, proto 패키지는 `hyeonworks.grpc.common.v1`이다 | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌이 난다. `project(':grpc:…')`·`project(':grpc-advanced:…')`나 `-p platforms/optional-build`를 쓴 서비스는 빌드가 실패한다 | 쓰지 않았으면 삭제를 그대로 받는다. 썼으면 grpc-library 첫 버전(`1.0.0`, 소유자가 태그를 단 뒤)을 좌표 `com.hyeonworks.grpc:<모듈>:1.0.0`으로 받고(저장소 선언은 그 repo README 「받는 법」), import를 `dev.caskeleton.grpc` → `com.hyeonworks.grpc`로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절, `docs/work/reference/related-repos.md` |
|
||||
| B-56 | 빌드 규칙·카탈로그: build-logic의 `ca.grpc-platform-module`·`ca.optional-architecture-registry` 플러그인과 `MainBuild`(두 번째 빌드에서 주 빌드를 찾던 것)를 지웠다. 도구 설정·테스트 이미지 목록·registry는 Gradle 루트(`src/`)에서만 찾는다. 카탈로그에서 `protobufPlugin`·`protobuf-java-grpc`·`protoc`·plugin `protobuf`를, SpotBugs 제외에서 gRPC 플랫폼 클래스 줄을 지웠다 | 서비스 leaf가 `ca.grpc-platform-module`이나 `libs.protoc`·`libs.protobuf.java.grpc`·`libs.plugins.protobuf`를 쓰면 빌드가 실패한다. `src/` 밖 두 번째 빌드에서 이 build-logic을 쓰던 서비스는 도구 설정을 못 찾는다 | 그 leaf `build.gradle`에서 `io.grpc:grpc-bom` import와 protobuf 플러그인 버전을 직접 적거나, 지운 카탈로그 항목을 서비스 카탈로그에 다시 더한다 | 같은 설계 13.1절 2단계 |
|
||||
|
||||
## 4. DB 마이그레이션
|
||||
|
||||
+3
-3
@@ -38,9 +38,9 @@ import java.util.regex.Pattern;
|
||||
*
|
||||
* <p>The gRPC ledger's lane uses it too. Since 2026-11-08 that lane lives in the separate
|
||||
* grpc-library repository, which keeps a copy of this file and {@link MigrationResource} in its
|
||||
* integration-test sources (until then its build compiled them from here; round 7, RR7-03-01).
|
||||
* This file is the original: a fix here is copied there by hand. Hence the rule for both files:
|
||||
* the JDK only, nothing else from this testkit.
|
||||
* integration-test sources (until then its build compiled them from here; round 7, RR7-03-01). This
|
||||
* file is the original: a fix here is copied there by hand. Hence the rule for both files: the JDK
|
||||
* only, nothing else from this testkit.
|
||||
*/
|
||||
public final class ConcurrentIndexMigrationInspector {
|
||||
|
||||
|
||||
+4
-4
@@ -25,10 +25,10 @@ import java.util.stream.Stream;
|
||||
* pinned nor held to the lock-wait rule (re-review 2026-11-03 round 3, RR3-02-03).
|
||||
*
|
||||
* <p>The gRPC ledger's lanes use it too. Since 2026-11-08 they live in the separate grpc-library
|
||||
* repository, which keeps a copy of this file in its integration-test sources (until then its
|
||||
* build compiled this one from here; re-review README 12, r6-b; r9). This file is the original: a
|
||||
* fix here is copied there by hand. Hence the rule for this file: the JDK only, nothing else from
|
||||
* this testkit.
|
||||
* repository, which keeps a copy of this file in its integration-test sources (until then its build
|
||||
* compiled this one from here; re-review README 12, r6-b; r9). This file is the original: a fix
|
||||
* here is copied there by hand. Hence the rule for this file: the JDK only, nothing else from this
|
||||
* testkit.
|
||||
*/
|
||||
public final class VersionedMigrationFiles {
|
||||
|
||||
|
||||
Reference in New Issue
Block a user