diff --git a/docs/compatibility/grpc-advanced-support-matrix.md b/docs/compatibility/grpc-advanced-support-matrix.md index 9df35cbf..bb29f12c 100644 --- a/docs/compatibility/grpc-advanced-support-matrix.md +++ b/docs/compatibility/grpc-advanced-support-matrix.md @@ -1,60 +1,55 @@ -# gRPC advanced capability support matrix +# gRPC advanced capability 지원 매트릭스 -Every capability in `:grpc-advanced:*`, its grade, and what it would take to raise it. -`GrpcAdvancedSupportMatrix` is the machine-readable form; `GrpcAdvancedCapability.defaultGrade` -carries the same values. +`:grpc-advanced:*`의 모든 capability, 그 등급, 그리고 등급을 올리는 데 필요한 것이다. 기본 등급의 정본은 +`GrpcAdvancedCapability.defaultGrade`다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로 바꾼다. -All capabilities are off by default. Flags are `app.grpc.advanced..enabled`. +capability는 모두 기본으로 꺼져 있다. 스위치는 `app.grpc.advanced..enabled`다. -## Grades +## 등급 -| Grade | May start | Production needs a separate approval | +| 등급 | 뜰 수 있나 | 운영에 별도 승인이 필요한가 | | --- | --- | --- | -| `ADVANCED_STABLE` | Yes | No | -| `EXPERIMENTAL` | Yes | Yes | -| `WATCH` | No | — | -| `DISABLED` | No | — | +| `ADVANCED_STABLE` | 예 | 아니요 | +| `EXPERIMENTAL` | 예 | 예 | +| `WATCH` | 아니요 | — | +| `DISABLED` | 아니요 | — | -## Capabilities +## capability -| Capability | Flag | Grade | Real infrastructure its evidence needs | +| capability | 스위치 | 등급 | 증거에 필요한 실제 인프라 | | --- | --- | --- | --- | | Protobuf Edition 2024 | `edition-2024` | `ADVANCED_STABLE` | — | | Protobuf Edition 2026 | `edition-2026` | `WATCH` | — | -| Client streaming | `client-streaming` | `ADVANCED_STABLE` | — | -| Bidirectional streaming | `bidi-streaming` | `ADVANCED_STABLE` | — | -| Manual flow control | `manual-flow-control` | `ADVANCED_STABLE` | — | -| Read-only unary hedging | `hedging` | `EXPERIMENTAL` | — | -| Custom name resolver | `custom-resolver` | `ADVANCED_STABLE` | — | -| Custom load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — | -| Proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane | +| client streaming | `client-streaming` | `ADVANCED_STABLE` | — | +| bidirectional streaming | `bidi-streaming` | `ADVANCED_STABLE` | — | +| 수동 flow control | `manual-flow-control` | `ADVANCED_STABLE` | — | +| 읽기 전용 unary hedging | `hedging` | `EXPERIMENTAL` | — | +| 사용자 정의 name resolver | `custom-resolver` | `ADVANCED_STABLE` | — | +| 사용자 정의 load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — | +| proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane | | gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy | -| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE` (flag only; no Servlet transport code since 2026-09-25) | Servlet container | +| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE`(스위치만 있다. 2026-09-25부터 Servlet 전송 코드가 없다) | Servlet 컨테이너 | | Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — | -| Reactor adapter | `reactor` | `ADVANCED_STABLE` | — | +| Reactor 어댑터 | `reactor` | `ADVANCED_STABLE` | — | | Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain | -| Channelz / CSDS diagnostics | `channel-diagnostics` | `ADVANCED_STABLE` | — | +| Channelz / CSDS 진단 | `channel-diagnostics` | `ADVANCED_STABLE` | — | -## What the grades mean here, concretely +## 여기서 등급이 구체적으로 뜻하는 것 -**Grade is a statement about the contract, not about a deployment.** Every capability's contract is -implemented and tested in this repository. What no capability has is evidence from a real deployment: -`GrpcAdvancedPromotionEvidence` for each one is empty, and no promotion has been granted. +**등급은 배포가 아니라 계약에 대한 말이다.** 모든 capability의 계약은 이 저장소에서 구현되고 시험됐다. 실제 배포에서 나온 +증거는 어느 capability에도 없고, 승격된 것도 없다. -**Four capabilities cannot produce meaningful evidence here at all**, because the infrastructure they -need is absent (gRPC-Web proxy, Servlet container, xDS control plane, Kotlin toolchain), and a suite -that runs without its infrastructure passes and establishes nothing. +**capability 넷은 여기서 의미 있는 증거를 아예 낼 수 없다.** 필요한 인프라(gRPC-Web proxy, Servlet 컨테이너, xDS control +plane, Kotlin toolchain)가 없고, 인프라 없이 돈 suite는 통과해도 아무것도 세우지 않기 때문이다. -**Kotlin is the sharpest case.** This repository has no Kotlin toolchain, so Kotlin is not -supportable here until one exists. Only the Java-side coroutine cancellation bridge -(`GrpcCoroutineContextBridge`) is implemented and tested; there is no compile lane. +**Kotlin이 가장 날카로운 경우다.** 이 저장소에는 Kotlin toolchain이 없으므로 그것이 생기기 전까지 Kotlin은 여기서 지원할 수 +없다. Java 쪽 coroutine 취소 bridge(`GrpcCoroutineContextBridge`)만 구현되고 시험됐다. 컴파일 lane은 없다. -## Promotion thresholds +## 승격 기준 -| To | Soak | Also required | +| 목표 | soak | 그 밖에 필요한 것 | | --- | --- | --- | -| `ADVANCED_STABLE` | 7 days | compatibility evidence, security review, fault evidence, performance evidence, ADR, runbook, real-environment test | -| Stable default | 30 days | all of the above, plus a dependency, security and operational-cost review | +| `ADVANCED_STABLE` | 7일 | 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험 | +| Stable 기본값 | 30일 | 위의 모두와 의존성·보안·운영 비용 리뷰 | -`WATCH` becomes `EXPERIMENTAL` before anything else. Promotions are independent: promoting one -capability changes no other's grade. +`WATCH`는 무엇보다 먼저 `EXPERIMENTAL`이 된다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은 바뀌지 않는다. diff --git a/docs/compatibility/grpc-support-matrix.md b/docs/compatibility/grpc-support-matrix.md index 525f33f7..67e9f739 100644 --- a/docs/compatibility/grpc-support-matrix.md +++ b/docs/compatibility/grpc-support-matrix.md @@ -1,77 +1,74 @@ -# gRPC platform support matrix +# gRPC 플랫폼 지원 매트릭스 -What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only checked against, and -what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement -anyone can act on. +Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이 +요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다. -The release gate is the `grpc-stable-release-gate` job in `.github/workflows/release.yml`: each -certified lane is a strict test lane that fails when it runs nothing. The in-code -`GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` pair was removed (review 2026-09-24 S5-lead-4): -no production or build code called it, so it gated nothing. +릴리스 gate는 `.github/workflows/release.yml`의 `grpc-stable-release-gate` job이다. 인증된 lane마다 아무것도 돌리지 않으면 +실패하는 strict test lane이다. -## Lanes +> 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드 +> 코드도 그것을 부르지 않아서 아무것도 막지 않았다. -| Lane | Grade | Failure blocks a release | +## lane + +| lane | 등급 | 실패하면 릴리스를 막나 | | --- | --- | --- | -| Boot-managed platform (Spring Boot 4.0.8 BOM) | Certified | Yes | -| proto3 with explicit `optional` | Certified | Yes | -| `grpc-netty-shaded` | Certified | Yes | -| `grpc-netty` (unshaded) | Compatibility | No | -| Upstream gRPC Java version override | Compatibility | No | -| Protobuf Edition 2024 | Watch | No | -| Protobuf Edition 2026 | Watch | No | +| Boot가 관리하는 플랫폼(저장소의 Spring Boot BOM) | Certified | 예 | +| 명시적 `optional`을 쓰는 proto3 | Certified | 예 | +| `grpc-netty-shaded` | Certified | 예 | +| `grpc-netty`(shade하지 않음) | Compatibility | 아니요 | +| upstream gRPC Java 버전 override | Compatibility | 아니요 | +| Protobuf Edition 2024 | Watch | 아니요 | +| Protobuf Edition 2026 | Watch | 아니요 | -## Runtime baseline +## 런타임 기준선 | | | | --- | --- | | Java | 21 | -| Spring Boot | 4.0.8 (the repository baseline; the plans assume 4.1) | -| io.grpc | `ext.grpcVersion` in `src/build.gradle` | -| Protobuf | `ext.protobufVersion` in `src/build.gradle` | -| Stable transport | Netty (shaded) | -| Stable RPC shapes | Unary, Server Streaming | -| Stable resolvers | Static, DNS, Unix domain socket | +| Spring Boot | 저장소 기준선, `src/gradle/libs.versions.toml`(계획은 4.1을 가정한다) | +| io.grpc | `src/gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 | +| Protobuf | `src/gradle/libs.versions.toml`의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다) | +| Stable 전송 | Netty(shaded) | +| Stable RPC 모양 | Unary, Server Streaming | +| Stable resolver | Static, DNS, Unix domain socket | | Stable load balancing | `pick_first`, `round_robin` | -## Evidence grades +## 증거 등급 -A capability may only be advertised on evidence of a grade that can establish it. -`GrpcEvidenceGrade.requireCertifies` enforces this, and `GrpcReleaseEvidence.supports` refuses a -claim backed by the wrong lane. +capability는 그것을 세울 수 있는 등급의 증거로만 광고한다. `GrpcEvidenceGrade.requireCertifies`가 이것을 강제하고, +`GrpcReleaseEvidence.supports`가 맞지 않는 lane이 뒷받침하는 주장을 거부한다. -| Grade | Lane | Establishes | +| 등급 | lane | 세우는 것 | | --- | --- | --- | -| `CONTRACT` | `grpcInProcessContractTest` | adapter, interceptor order, status mapping, validation, idempotency replay, context propagation | -| `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata limit, message limit, GOAWAY, keepalive, graceful shutdown | -| `FAULT` | `grpcFaultTest` | connection loss, completion unknown, partial stream, evidence classifier | -| `PERFORMANCE` | `grpcPerformanceTest` | latency, stream saturation, executor saturation, drain budget | +| `CONTRACT` | `grpcInProcessContractTest` | 어댑터, interceptor 순서, 상태 매핑, 검증, 멱등 replay, context 전파 | +| `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata 한도, 메시지 한도, GOAWAY, keepalive, graceful shutdown | +| `FAULT` | `grpcFaultTest` | 연결 끊김, 완료 모름, 부분 stream, 증거 분류기 | +| `PERFORMANCE` | `grpcPerformanceTest` | 지연, stream 포화, executor 포화, drain 예산 | -In-process results are never transport evidence. The in-process transport does not negotiate TLS, -does not frame HTTP/2 and does not enforce transport-level limits, so a suite that passes there has -tested the adapter and not the transport. +in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS를 협상하지 않고, HTTP/2 frame을 만들지 않고, 전송 수준 한도를 +강제하지 않는다. 그래서 거기서 통과한 suite는 전송이 아니라 어댑터를 시험한 것이다. -## What is not supported +## 지원하지 않는 것 -| | Where it lives | +| | 있는 곳 | | --- | --- | -| Client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) | -| Manual flow control | `grpc-advanced` (`streaming`) | +| client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) | +| 수동 flow control | `grpc-advanced` (`streaming`) | | Hedging | `grpc-advanced` (`resilience`) | -| Custom name resolver, custom load balancer | `grpc-advanced` (`resilience`) | +| 사용자 정의 name resolver, 사용자 정의 load balancer | `grpc-advanced` (`resilience`) | | xDS | `grpc-advanced` (`resilience`) | | gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` | -| Channelz / CSDS diagnostics | `grpc-advanced` (`diagnostics`) | +| Channelz / CSDS 진단 | `grpc-advanced` (`diagnostics`) | -## Current release status +## 지금 릴리스 상태 -Not released. Every `:grpc:*` leaf is `runtime_memberships: []` in the module registry, so the -platform is build-only: it compiles, its lanes run, and no deployed artifact carries it. +릴리스하지 않았다. registry에서 모든 `:grpc:*` leaf는 `"build": "optional-grpc"`라 주 빌드 밖에 있고 어느 조립에도 들어가지 +않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다. -Two release gate inputs are outstanding and are the work between here and a release: +릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다. -- **Performance baseline.** The performance lane runs and asserts shape — ordered percentiles, a gate - that reads them — rather than absolute numbers. A recorded baseline on a known runner is what turns - it into a regression gate. -- **Schema codegen.** No `protoc` runs in this build (ADR-GRPC-002), so the descriptor artifact and - the consumer-compile fixture are governed as policy rather than produced from a compiled schema. +- **성능 기준선.** 성능 lane은 돌고, 절대 수치가 아니라 모양을 단언한다. 순서 있는 백분위수와 그것을 읽는 gate다. 알려진 + runner에서 기록한 기준선이 생겨야 회귀 gate가 된다. +- **schema codegen.** 이 빌드에서는 `protoc`가 돌지 않는다(ADR-GRPC-002). 그래서 descriptor 산출물과 consumer-compile fixture는 + 컴파일한 schema에서 만들어지지 않고 정책으로 다스린다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 52bc3ede..4e569949 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -35,8 +35,6 @@ language docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md language docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md language docs/adr/ADR-WS-002-resume-and-cluster.md language docs/adr/ADR-WS-003-stomp-and-broker-relay.md -language docs/compatibility/grpc-advanced-support-matrix.md -language docs/compatibility/grpc-support-matrix.md language docs/fileserver/configuration.md language docs/fileserver/design-deviations.md language docs/fileserver/http-contract.md @@ -128,7 +126,6 @@ reference src/README.md .github/ci-gate-matrix.yml reference src/README.md .github/scripts/verify-gate-matrix.sh # 숫자: 정본(src/gradle/libs.versions.toml, registry)이 정하는 값을 복사한 곳. 정본을 가리키게 고치면 지운다. -number docs/compatibility/grpc-support-matrix.md Spring Boot 4.0.8 number docs/httpclient/repository-adaptation.md 19 leaf number docs/httpclient/repository-adaptation.md Spring Boot 4.0.8 number docs/manual/01-generator.md 5 leaf