diff --git a/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md b/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md index 2e109b0a..e2292be7 100644 --- a/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md +++ b/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md @@ -7,122 +7,110 @@ - 현재 정본: `src/build-logic/README.md` -# ADR-BUILD-001: `java-test-fixtures` is the standard for shared test code +# ADR-BUILD-001: 공유 시험 코드의 표준은 `java-test-fixtures`다 -- Status: Accepted -- Date: 2026-09-07 -- Scope: every leaf that publishes or consumes shared test code -- Source: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` BOOT-015 +- 상태: 채택 +- 날짜: 2026-09-07 +- 범위: 공유 시험 코드를 내놓거나 쓰는 모든 leaf +- 출처: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` BOOT-015 -## Context +## 배경 -Two conventions do the same job in this repository. +이 저장소에서 같은 일을 하는 규약이 둘 있다. -`ca.testkit-publisher` — a convention plugin — gives a leaf a `testkit` source set, wires its output -onto the lanes that leaf names, and optionally publishes it as a consumable configuration. Five -leaves use it: `persistence-jpa` (published as `jpaTestkit`), `web` (`webTestkit`), `websocket` -(`websocketTestkit`), `persistence-mongo` and `httpclient` (both unpublished). +`ca.testkit-publisher` — 규약 플러그인 — 는 leaf에 `testkit` source set을 주고, 그 출력을 leaf가 이름을 댄 lane에 +배선하고, 원하면 쓸 수 있는 configuration으로 내놓는다. 다섯 leaf가 쓴다: `persistence-jpa`(`jpaTestkit`으로 내놓음), +`web`(`webTestkit`), `websocket`(`websocketTestkit`), `persistence-mongo`와 `httpclient`(둘 다 내놓지 않음). -`java-test-fixtures` — Gradle's own plugin — gives a leaf a `testFixtures` source set, puts it on -`test`'s classpath automatically, and always publishes it as a variant consumers reach with -`testFixtures(project(':x'))`. One leaf uses it: `graphql`, which additionally fails its build when a -fixture is written outside `src/testFixtures/java`. +`java-test-fixtures` — Gradle 자신의 플러그인 — 는 leaf에 `testFixtures` source set을 주고, 그것을 `test`의 +classpath에 자동으로 올리고, 쓰는 쪽이 `testFixtures(project(':x'))`로 닿는 variant로 언제나 내놓는다. 한 leaf가 +쓴다: `graphql`. 이 leaf는 fixture를 `src/testFixtures/java` 밖에 쓰면 빌드를 실패시키기도 한다. -Two conventions for one purpose is the defect. A contributor adding shared test code has to know -which leaf they are in before they know where the file goes, and the two answers are not -interchangeable: a consumer of the first writes `project(path: ':x', configuration: 'jpaTestkit')` -and has to know the configuration's name, while a consumer of the second writes -`testFixtures(project(':x'))` and does not. +한 목적에 규약 둘이 있는 것이 결함이다. 공유 시험 코드를 더하는 사람은 파일을 어디 둘지 알기 전에 자기가 어느 +leaf에 있는지 알아야 하고, 두 답은 서로 바꿔 쓸 수 없다: 첫째를 쓰는 쪽은 +`project(path: ':x', configuration: 'jpaTestkit')`를 쓰고 configuration 이름을 알아야 하지만, 둘째를 쓰는 쪽은 +`testFixtures(project(':x'))`를 쓰고 그럴 필요가 없다. -## Decision +## 결정 -**`java-test-fixtures` is the standard.** New shared test code goes in `src/testFixtures/java`, and a -consumer depends on it with `testFixtures(project(':x'))`. +**`java-test-fixtures`가 표준이다.** 새 공유 시험 코드는 `src/testFixtures/java`에 두고, 쓰는 쪽은 +`testFixtures(project(':x'))`로 의존한다. -Three reasons, in order of weight: +이유 셋, 무게 순으로: -1. **The consumer side describes itself.** `testFixtures(project(':adapter:inbound:web'))` says what - it is. `project(path: ':adapter:inbound:web', configuration: 'webTestkit')` says where to look, - and only after the reader has learned that `webTestkit` is a testkit rather than a lane. -2. **The enforcement already exists and is copyable.** `graphql`'s build fails when a fixture is - declared in the wrong place. The same guard applies unchanged to any leaf that adopts the plugin. -3. **It is one fewer local concept.** A convention plugin that reimplements a Gradle plugin has to be - maintained against it. +1. **쓰는 쪽이 스스로를 설명한다.** `testFixtures(project(':adapter:inbound:web'))`는 그것이 무엇인지 말한다. + `project(path: ':adapter:inbound:web', configuration: 'webTestkit')`는 어디를 볼지 말하고, 읽는 사람이 + `webTestkit`이 lane이 아니라 testkit임을 배운 뒤에야 뜻이 통한다. +2. **강제 장치가 이미 있고 복사할 수 있다.** `graphql`의 빌드는 fixture를 엉뚱한 곳에 선언하면 실패한다. 같은 + guard를 플러그인을 쓰는 어느 leaf에든 바꾸지 않고 적용한다. +3. **지역 개념이 하나 준다.** Gradle 플러그인을 다시 구현한 규약 플러그인은 그 플러그인에 맞춰 계속 관리해야 한다. -## What the local plugin does better, and how it is replaced +## 지역 플러그인이 더 잘하는 것과 그것을 대신하는 방법 -This is worth writing down, because the review that prompted this ADR recommended the migration -before reading `ca.testkit-publisher`, and the plugin turns out to encode two deliberate decisions -rather than being an oversight. +이것은 적어 둘 만하다. 이 ADR을 낳은 리뷰는 `ca.testkit-publisher`를 읽기 전에 옮기기를 권했고, 읽어 보니 그 +플러그인은 빠뜨린 것이 아니라 일부러 정한 결정 둘을 담고 있었다. -**Publishing is opt-in.** `persistence-mongo` and `httpclient` have a testkit and publish nothing; -`persistence-jpa` publishes. The plugin's own comment names this as "a real difference in what each -leaf offers rather than an oversight to normalise away". `java-test-fixtures` always creates the -variant, so the distinction is lost — a leaf that never meant to offer its fixtures will offer them. +**내놓기는 고를 때만 한다.** `persistence-mongo`와 `httpclient`는 testkit이 있지만 아무것도 내놓지 않는다. +`persistence-jpa`는 내놓는다. 플러그인 자신의 주석이 이것을 "a real difference in what each leaf offers rather than +an oversight to normalise away"(각 leaf가 주는 것의 실제 차이이지, 맞춰 없앨 빠뜨림이 아니다)라고 부른다. +`java-test-fixtures`는 언제나 variant를 만드니 이 구별이 사라진다 — fixture를 줄 생각이 없던 leaf도 주게 된다. -> Replacement: none at the build level. The distinction moves to review: the fixtures of a leaf that -> nobody consumes are simply unconsumed. This is a real, accepted loss. +> 대신하는 것: 빌드 수준에서는 없다. 구별은 리뷰로 옮긴다: 아무도 쓰지 않는 leaf의 fixture는 그냥 쓰이지 않는다. +> 실제 손실이고, 받아들인 손실이다. -**Lane consumption is declared.** `persistence-jpa` says `consumedBy 'test', 'postgresqlIntegrationTest'`. -`java-test-fixtures` puts fixtures on `test` only, so every other lane needs the output added -explicitly. +**lane이 쓰는 것을 선언한다.** `persistence-jpa`는 `consumedBy 'test', 'postgresqlIntegrationTest'`라고 말한다. +`java-test-fixtures`는 fixture를 `test`에만 올리니, 다른 모든 lane에는 출력을 명시해서 더해야 한다. -> Replacement: `strictTestLanes`' existing `compilesAgainst` expresses this unchanged — a lane -> declares `compilesAgainst 'main', 'testFixtures'`. The first draft of this ADR assumed the DSL -> would need a change, because `sourceSet(name)` creates what it is given and `testFixtures` already -> exists. The `persistence-mongo` migration showed otherwise: `compilesAgainst` only *looks a source -> set up*, so naming a plugin-created one works as-is. What the leaf drops is the -> `sourceSet('testkit')` declaration, not the lane's. +> 대신하는 것: `strictTestLanes`의 기존 `compilesAgainst`가 바꾸지 않고 이것을 나타낸다 — lane이 +> `compilesAgainst 'main', 'testFixtures'`를 선언한다. 이 ADR의 첫 초안은 DSL을 바꿔야 한다고 가정했다. +> `sourceSet(name)`은 받은 것을 만들고 `testFixtures`는 이미 있기 때문이다. `persistence-mongo`를 옮겨 보니 아니었다: +> `compilesAgainst`는 source set을 *찾기만* 하므로, 플러그인이 만든 것의 이름을 대도 그대로 된다. leaf가 버리는 것은 +> lane의 선언이 아니라 `sourceSet('testkit')` 선언이다. -## Migration: done, and what it cost +## 옮기기: 끝났고, 든 비용 -Five leaves, eleven lanes, two published testkits, all migrated leaf by leaf with the suite run -between each. `ca.testkit-publisher` is deleted. +leaf 다섯, lane 열하나, 내놓은 testkit 둘을 leaf 하나씩, 그 사이마다 suite를 돌리며 모두 옮겼다. +`ca.testkit-publisher`는 지웠다. -The order was chosen so a mistake would be cheap: unpublished leaves first, published ones last with -their consumer in the same step. +순서는 실수가 싸게 끝나도록 골랐다: 내놓지 않는 leaf를 먼저, 내놓는 leaf를 마지막에 그 쓰는 쪽과 같은 단계에서. -1. `persistence-mongo` — one leaf, two lanes, no cross-module consumer; the proof the path works. - What it took, per leaf: - - `apply plugin: 'java-test-fixtures'` at the top of the leaf build file; +1. `persistence-mongo` — leaf 하나, lane 둘, 다른 모듈의 쓰는 쪽 없음. 길이 되는지 보는 증명이다. + leaf마다 든 일: + - leaf 빌드 파일 맨 위에 `apply plugin: 'java-test-fixtures'`; - `git mv src/testkit src/testFixtures`; - - drop `sourceSet('testkit')` and the whole `testkitPublisher` block; keep every other lane's - `compilesAgainst`, renaming `'testkit'` to `'testFixtures'`; - - rename `testkitImplementation` to `testFixturesImplementation`, **and add what the old source - set was inheriting silently**. This is the one non-mechanical step: `testkit*` extended - `testImplementation`, so the fixtures saw every test library the leaf declared. Mongo's needed - four more lines (AssertJ, BSON, Spring Data commons, Toxiproxy) — none of which the leaf had - ever stated the fixtures depended on; - - regenerate the leaf's lock state. -2. `httpclient`, then `websocket` — unpublished as well, more lanes. -3. `web` and `persistence-jpa` with `app-bootstrap`'s two consumer declarations, which became - `testImplementation(testFixtures(project(':…')))`. -4. `ca.testkit-publisher` deleted, along with its `plugins {}` entry and its application in the root - build. + - `sourceSet('testkit')`와 `testkitPublisher` 블록 전체를 버린다. 다른 모든 lane의 `compilesAgainst`는 두고 + `'testkit'`을 `'testFixtures'`로 이름을 바꾼다; + - `testkitImplementation`을 `testFixturesImplementation`으로 이름을 바꾸고, **옛 source set이 소리 없이 + 물려받던 것을 더한다**. 기계적이지 않은 단계는 이것 하나다: `testkit*`는 `testImplementation`을 상속해서, + fixture가 leaf가 선언한 모든 시험 라이브러리를 봤다. Mongo는 네 줄(AssertJ, BSON, Spring Data commons, + Toxiproxy)이 더 필요했다 — leaf가 fixture의 의존으로 적은 적이 한 번도 없는 것들이다; + - leaf의 잠금 상태를 다시 만든다. +2. `httpclient`, 그다음 `websocket` — 역시 내놓지 않고, lane이 더 많다. +3. `web`과 `persistence-jpa`, 그리고 `app-bootstrap`의 쓰는 쪽 선언 둘. 그 선언은 + `testImplementation(testFixtures(project(':…')))`가 됐다. +4. `ca.testkit-publisher`를 지웠다. 그 `plugins {}` 항목과 루트 빌드의 적용도 함께. -### Two things the migration broke, and what they taught +### 옮기기가 깨뜨린 것 둘과 그것이 가르친 것 -Both were caught by tests that exist to catch exactly this, which is the argument for having them. +둘 다 바로 이것을 잡으려고 있는 시험이 잡았다. 그런 시험을 둘 이유가 그것이다. -**ArchUnit corpora went wrong in opposite directions.** `httpclient`'s boundary rules *excluded* -`build/classes/java/testkit`; after the move the fixtures arrived as a `…-test-fixtures.jar` on the -same classpath, so the exclusion missed them and 258 fixture-to-fixture calls were reported as -production depending on the testkit. `persistence-jpa`'s rules *included* only -`build/classes/java/main`; applying `java-test-fixtures` makes the module's own test classpath carry -the module as a **jar** rather than as a class directory, so its corpus became empty. The second is -the dangerous one — an empty corpus makes every `noClasses()` rule pass — and it surfaced only -because that suite asserts its corpus is non-empty before asserting anything about it. +**ArchUnit 대상 묶음이 반대 방향으로 틀어졌다.** `httpclient`의 경계 규칙은 `build/classes/java/testkit`을 +*뺐다*. 옮긴 뒤 fixture는 같은 classpath에 `…-test-fixtures.jar`로 들어왔고, 그래서 빼기가 그것을 놓쳤으며 +fixture 사이 호출 258개가 운영 코드가 testkit에 의존한다고 보고됐다. `persistence-jpa`의 규칙은 +`build/classes/java/main`만 *넣었다*. `java-test-fixtures`를 적용하면 모듈 자신의 시험 classpath가 모듈을 class +디렉터리가 아니라 **jar**로 싣는다. 그래서 대상 묶음이 비었다. 위험한 쪽은 둘째다 — 빈 묶음이면 모든 +`noClasses()` 규칙이 통과한다 — 그리고 그 suite가 무엇이든 단언하기 전에 묶음이 비어 있지 않음을 단언했기 +때문에만 드러났다. -**Fixtures had invisible dependencies.** `testkit*` configurations extended `testImplementation`, so -the fixtures compiled against every test library their leaf declared without ever naming one. Making -them explicit took roughly thirty `testFixturesImplementation` lines across the five leaves — -Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ, Spring Data. None of them were -wrong; none of them were stated. +**fixture에 보이지 않는 의존이 있었다.** `testkit*` configuration은 `testImplementation`을 상속해서, fixture는 이름 +한 번 대지 않고 leaf가 선언한 모든 시험 라이브러리에 대고 컴파일됐다. 그것을 명시하는 데 다섯 leaf에 걸쳐 +`testFixturesImplementation` 줄이 대략 서른 개 들었다 — Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ, +Spring Data. 틀린 것은 없었다. 적힌 것도 없었다. -## Consequences +## 결과 -- `docs/testing/TESTING_STRATEGY.md` §5 records the standard; this ADR records why and at what cost. -- Until step 5, two conventions remain visible. The strategy document says so explicitly, so a - contributor reading it is not left to infer which one is current. -- The opt-in-publishing distinction is given up. If it later proves load-bearing — a leaf whose - fixtures genuinely must not be reachable — the answer is a separate module, not a third convention. +- `docs/testing/TESTING_STRATEGY.md` §5가 표준을 적는다. 이 ADR은 왜, 어떤 비용으로인지를 적는다. +- 5단계까지는 규약 둘이 보이는 채로 남는다. 전략 문서가 그것을 분명히 말하므로, 읽는 사람이 어느 것이 지금 + 것인지 짐작하게 두지 않는다. +- 고를 때만 내놓는 구별은 포기한다. 나중에 그것이 꼭 필요한 것으로 드러나면 — fixture에 정말 닿으면 안 되는 + leaf — 답은 세 번째 규약이 아니라 따로 둔 모듈이다. diff --git a/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md b/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md index 57af5bc7..d228397c 100644 --- a/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md +++ b/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md @@ -7,73 +7,63 @@ - 현재 정본: `src/adapter/inbound/graphql/README.md` -# ADR-GQL-001 — GraphQL context stays inbound; object authorization moves to application-core; the persisted-operation store stays an inbound SPI +# ADR-GQL-001 — GraphQL 문맥은 inbound에 머물고, 객체 인가는 application-core로 옮기며, persisted operation 저장소는 inbound SPI로 남는다 -- Status: Accepted -- Date: 2026-08-24 -- Review: `docs/reviews/2026-08-14-graphql-module-code-review.md` GQL-026 +- 상태: 채택 +- 날짜: 2026-08-24 +- 리뷰: `docs/reviews/2026-08-14-graphql-module-code-review.md` GQL-026 -## Context +## 배경 -The GraphQL leaf's own documentation described three things crossing its boundary: a -`GraphQlRequestContext` with a deadline propagated into application, JPA, Mongo and the HTTP client; -object authorization decided inside the transport; and a persisted-operation registry implemented by -an external durable store. +GraphQL leaf 자신의 문서는 경계를 넘는 것 셋을 적었다: application, JPA, Mongo, HTTP client로 deadline을 전파하는 +`GraphQlRequestContext`, 전송 계층 안에서 정하는 객체 인가, 외부 durable 저장소가 구현하는 persisted operation +registry. -Two of those invert the dependency direction. If `application-core` or an outbound adapter -implements a type that lives in `adapter:inbound:graphql`, the registry edge that says inbound -depends on application is satisfied while the real compile-time dependency runs the other way. +그중 둘은 의존 방향을 뒤집는다. `application-core`나 outbound 어댑터가 `adapter:inbound:graphql`에 있는 타입을 +구현하면, inbound가 application에 의존한다는 registry edge는 만족되지만 실제 컴파일 의존은 반대로 간다. -The third is a business rule in the wrong layer: whether an actor may see an object is a decision -about the domain, and GraphQL is one of four transports this skeleton ships. +셋째는 엉뚱한 계층의 업무 규칙이다: actor가 객체를 볼 수 있는지는 도메인에 대한 판단이고, GraphQL은 이 골격이 +싣는 전송 계층 넷 중 하나다. -## Decision +## 결정 -Three different answers, because the three problems are not the same problem. +세 문제가 같은 문제가 아니므로 답도 셋이다. -**GraphQL context stays inbound-local.** It is mapped explicitly onto application command fields — -actor, tenant, deadline — rather than travelling as a type. Nothing outside the leaf references -`GraphQlRequestContext`, and the boundary test is that grep returns nothing outside it. +**GraphQL 문맥은 inbound 안에 머문다.** 타입으로 실려 다니지 않고 application command 필드 — actor, tenant, +deadline — 로 명시해 대응시킨다. leaf 밖의 어떤 것도 `GraphQlRequestContext`를 참조하지 않고, 경계 시험은 leaf +밖에서 grep이 아무것도 돌려주지 않는 것이다. -**Object authorization moves to `application-core`.** `ObjectAccessPolicy`, `ObjectAccessRequest` -and `ObjectAccessDecision` are transport-neutral and live with the other application policies; -`ApplicationObjectAuthorization` in the GraphQL leaf is the bridge that calls them. This is the one -of the three that was a real layering defect, and it is fixed rather than documented. +**객체 인가는 `application-core`로 옮긴다.** `ObjectAccessPolicy`, `ObjectAccessRequest`, `ObjectAccessDecision`은 +전송 중립이고 다른 애플리케이션 정책과 함께 있다. GraphQL leaf의 `ApplicationObjectAuthorization`이 그것을 부르는 +다리다. 셋 중 이것이 실제 계층 결함이었고, 적어 두지 않고 고친다. -**The persisted-operation store stays an inbound-owned SPI.** `GraphQlPersistedOperationRegistry` -remains in `advanced/persisted`, and no leaf outside GraphQL implements it. +**persisted operation 저장소는 inbound가 가진 SPI로 남는다.** `GraphQlPersistedOperationRegistry`는 +`advanced/persisted`에 남고, GraphQL 밖의 어떤 leaf도 그것을 구현하지 않는다. -## Consequences +## 결과 -The third decision is the one that needs defending, because it leaves the reported risk in place -rather than removing it. +변호가 필요한 것은 셋째 결정이다. 보고된 위험을 없애지 않고 그 자리에 두기 때문이다. -The risk is conditional: the direction inverts only when something outside the leaf implements the -interface. Nothing does. The template ships an in-memory registry and no durable one, because it -ships no persisted-operation store at all. +위험은 조건부다: leaf 밖의 무엇이 그 인터페이스를 구현할 때만 방향이 뒤집힌다. 그런 것은 없다. 템플릿은 메모리 +registry를 싣고 durable registry는 싣지 않는다. persisted operation 저장소를 아예 싣지 않기 때문이다. -The alternative was to introduce a generic operational key-value store port owned by a neutral -contract holder, with the GraphQL adapter owning only the key and value mapping. That port would -have exactly one interface, zero implementations and one speculative consumer — a new abstraction -whose shape is guessed from a requirement nobody has stated. This repository has spent a full -remediation pass deleting controls that existed and were reached by nothing, and inventing a port -for a store that does not exist is how the next one of those gets written. +대안은 중립 계약 보유자가 가진 범용 운영 key-value 저장소 포트를 들이고, GraphQL 어댑터는 키와 값 대응만 가지는 +것이었다. 그 포트는 인터페이스 정확히 하나, 구현 0개, 짐작으로 정한 쓰는 쪽 하나를 가졌을 것이다 — 아무도 말하지 +않은 요구에서 모양을 짐작한 새 추상이다. 이 저장소는 있었지만 아무것도 닿지 않던 통제를 지우는 데 수정 한 바퀴를 +통째로 썼다. 없는 저장소를 위해 포트를 지어내는 것이 그런 것을 다음에 또 쓰는 길이다. -So the decision is to leave the SPI where it is and to move it when a durable store is actually -built. Moving it then is a rename across one leaf and one new adapter, which is cheaper than -carrying a wrong abstraction until then. What must not happen in the meantime is an outbound leaf -implementing the inbound interface, because that is the moment the direction actually inverts, and -it would happen in a commit whose diff looks like an implementation rather than a layering change. +그래서 결정은 SPI를 있는 곳에 두고, durable 저장소를 실제로 만들 때 옮기는 것이다. 그때 옮기는 일은 leaf 하나와 +새 어댑터 하나에 걸친 이름 바꾸기이고, 그때까지 틀린 추상을 끌고 다니는 것보다 싸다. 그동안 일어나면 안 되는 것은 +outbound leaf가 inbound 인터페이스를 구현하는 것이다. 그때가 방향이 실제로 뒤집히는 순간이고, 그것은 계층 변경이 +아니라 구현처럼 보이는 diff의 커밋에서 일어날 것이다. -The composition root wires these and owns no business or storage policy of its own. +조립 루트가 이것들을 배선하고, 자기 업무·저장 정책은 가지지 않는다. -## Enforcement +## 강제 -`verifyCleanArchitectureDependencies` and `modules.json` hold the leaf's edges to -`domain-core`, `application-core` and `shared-contract`. `ObjectAccessPolicyTest` covers the -application-side policy and `ApplicationObjectAuthorizationTest` the bridge. +`verifyCleanArchitectureDependencies`와 `modules.json`이 leaf의 `domain-core`, `application-core`, `shared-contract` +edge를 지킨다. `ObjectAccessPolicyTest`가 application 쪽 정책을, `ApplicationObjectAuthorizationTest`가 다리를 덮는다. -The condition this ADR turns on — that nothing outside the GraphQL leaf implements the -persisted-operation SPI — is a claim about the whole repository, so it is checked at the -composition root rather than inside the leaf, next to the other GraphQL boundary rules in -`app-bootstrap`'s architecture suite. +이 ADR이 기대는 조건 — GraphQL leaf 밖의 어떤 것도 persisted operation SPI를 구현하지 않는다 — 은 저장소 전체에 +대한 주장이다. 그래서 leaf 안이 아니라 조립 루트에서, `app-bootstrap` architecture suite의 다른 GraphQL 경계 규칙 +옆에서 검사한다. diff --git a/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md b/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md index c45ff9c8..617992bf 100644 --- a/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md +++ b/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md @@ -7,58 +7,51 @@ - 현재 정본: `docs/compatibility/grpc-support-matrix.md` -# ADR-GRPC-001: The gRPC platform ships as a registered family, not as one adapter leaf +# ADR-GRPC-001: gRPC 플랫폼은 adapter leaf 하나가 아니라 등록된 family로 싣는다 -- Status: accepted -- Date: 2026-08-30 -- Scope: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json` +- 상태: 채택 +- 날짜: 2026-08-30 +- 범위: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json` -## Context +## 배경 -The two source plans describe a type-safe gRPC execution platform with its own API, SPI, adapters and -composition root: fifteen Stable modules under `modules/grpc` and sixteen Advanced ones under -`modules/grpc-advanced`, on Gradle Kotlin DSL, in package `io.backend.skeleton.grpc`, against -Spring Boot 4.1. +두 원본 계획은 자기 API, SPI, 어댑터, 조립 루트를 가진 타입 안전 gRPC 실행 플랫폼을 설명한다: `modules/grpc` 아래 +Stable 모듈 열다섯과 `modules/grpc-advanced` 아래 Advanced 모듈 열여섯, Gradle Kotlin DSL, 패키지 +`io.backend.skeleton.grpc`, Spring Boot 4.1 기준. -None of that layout exists here. This repository uses Groovy DSL, a fail-closed module registry that -owns the leaf list, package root `dev.caskeleton`, and Spring Boot 4.0.8. The plans anticipate this: -their last Global Constraint says that when the repository structure differs, file paths are remapped -and the public contracts, invariants and test meanings are not changed. +그 배치는 여기 하나도 없다. 이 저장소는 Groovy DSL, leaf 목록을 가진 실패하면 닫히는 모듈 registry, 패키지 루트 +`dev.caskeleton`, Spring Boot 4.0.8을 쓴다. 계획은 이것을 예상한다: 마지막 Global Constraint가, 저장소 구조가 다르면 +파일 경로를 다시 대응시키고 공개 계약·불변식·시험의 뜻은 바꾸지 않는다고 말한다. -Two shapes were available. Fold the platform into the existing `:adapter:inbound:grpc` leaf as -packages — which is what the JPA, GraphQL, WebSocket and HTTP platforms did here — or register it as -a family the way `messaging:*` is registered. +고를 수 있는 모양은 둘이었다. 플랫폼을 기존 `:adapter:inbound:grpc` leaf에 패키지로 접어 넣기 — JPA, GraphQL, +WebSocket, HTTP 플랫폼이 여기서 그렇게 했다 — 또는 `messaging:*`를 등록한 방식대로 family로 등록하기. -## Decision +## 결정 -Register it as a family: twelve Stable leaves under `src/grpc/` and six Advanced ones under -`src/grpc-advanced/`. +family로 등록한다: `src/grpc/` 아래 Stable leaf 열둘과 `src/grpc-advanced/` 아래 Advanced leaf 여섯. -The deciding property is that this is not a layer of this application. Root `CLAUDE.md` already -describes `messaging:*` as "a vendored messaging platform: a product with its own API, SPI, adapters -and composition boundary, not a layer of this application", and the gRPC platform is the same shape -for the same reason — the application is meant to reach it the way it reaches a library, through an -application-owned port. The four platforms that became packages are all layers of this application; -this one is not. +결정을 가른 성질은 이것이 이 애플리케이션의 계층이 아니라는 점이다. 루트 `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 플랫폼은 같은 이유로 같은 모양이다 — 애플리케이션은 라이브러리에 닿듯, 애플리케이션이 +가진 포트를 거쳐 그것에 닿아야 한다. 패키지가 된 네 플랫폼은 모두 이 애플리케이션의 계층이다. 이것은 아니다. -The split between `src/grpc/` and `src/grpc-advanced/` is not organisational. The Stable plan -requires that the Stable starter's build fail if it reaches an Advanced module, and separate Gradle -path prefixes make that a `verifyCleanArchitectureDependencies` failure rather than a review note: -`grpc-spring-boot-starter`'s registry entry names no advanced id, and it cannot acquire one silently. +`src/grpc/`와 `src/grpc-advanced/`의 분리는 정리용이 아니다. Stable 계획은 Stable starter의 빌드가 Advanced 모듈에 +닿으면 실패해야 한다고 요구하고, Gradle 경로 접두어를 따로 두면 그것이 리뷰 메모가 아니라 +`verifyCleanArchitectureDependencies` 실패가 된다: `grpc-spring-boot-starter`의 registry 항목은 advanced id를 하나도 +대지 않고, 소리 없이 얻을 수도 없다. -## Consequences +## 결과 -**The registry grew from 44 leaves to 62.** That is a large registry change, made deliberately and in -one place. Every new leaf is `runtime_memberships: []`, so nothing ships until a second, explicit -decision moves it. +**registry가 leaf 44개에서 62개로 늘었다.** 큰 registry 변경이고, 일부러 한곳에서 했다. 새 leaf는 모두 +`runtime_memberships: []`라서, 두 번째로 명시한 결정이 옮기기 전까지 아무것도 실리지 않는다. -**The advanced boundary is checked twice.** Once by the registry at build time, and once by -`GrpcStableBuildInvariant` at runtime, because a fat jar or a shaded artifact is assembled by -something the registry never sees. +**advanced 경계는 두 번 검사한다.** 빌드 때 registry가 한 번, 런타임에 `GrpcStableBuildInvariant`가 한 번. fat jar나 +shaded artifact는 registry가 보지 못하는 무언가가 조립하기 때문이다. -**Four testkit modules became four test lanes.** The plan's split exists so in-process results cannot -be mistaken for network results; this repository expresses that with `ca.strict-test-lane`, whose -lanes fail when they discover nothing and never serve an up-to-date result. `GrpcEvidenceGrade` keeps -the same rule inside the code, so a report cannot cite a contract run as transport evidence. +**testkit 모듈 넷은 시험 lane 넷이 됐다.** 계획이 나눈 이유는 프로세스 안 결과를 네트워크 결과로 착각하지 못하게 +하려는 것이다. 이 저장소는 그것을 `ca.strict-test-lane`으로 나타낸다. 그 lane은 아무것도 찾지 못하면 실패하고, +up-to-date 결과를 내주지 않는다. `GrpcEvidenceGrade`가 코드 안에서 같은 규칙을 지키므로, 보고서가 계약 실행을 전송 +증거로 인용할 수 없다. -**Codegen is not wired.** See ADR-GRPC-002. +**codegen은 배선하지 않았다.** ADR-GRPC-002를 본다. diff --git a/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md b/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md index 82641867..67320b8e 100644 --- a/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md +++ b/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md @@ -8,74 +8,65 @@ - 대체됨: `docs/capability-status.md` -# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI +# ADR-GRPC-002: schema 관리는 protoc 없이, Buf CLI 없이 돈다 -- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up -- Date: 2026-08-30 -- Scope: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen` (both removed) +- 상태: **대체됨(2026-09-28)** — 2026-09-25 리뷰 후속의 소유자 결정 18 +- 날짜: 2026-08-30 +- 범위: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen`(둘 다 지움) -> **Superseded.** The regex `.proto` validator and the Java re-implementation of Buf's rules were -> deleted. The schema now lives in `:grpc:grpc-contract` (`src/grpc/grpc-contract/src/main/proto`), -> compiled by the Gradle protobuf plugin (`com.google.protobuf`, version pinned in -> `src/gradle/libs.versions.toml`; protoc and the protobuf-java runtime are both `protobufGrpc`). -> Generated sources are excluded from Spotless, Checkstyle and Error Prone in that leaf only. -> `buf lint` and `buf breaking` (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking) -> run in CI, job `grpc-proto-buf` in `.github/workflows/ci-quality-gates.yml`. The proto organization -> is `caskeleton` (was `hyeonworks`). The text below is kept as the record of the original decision. +> **대체됨.** 정규식 `.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`). 아래 글은 원래 결정의 +> 기록으로 남긴다. -## Context +## 배경 -Stable Tasks 8 through 11 require proto style rules, Buf format/lint/breaking governance, a single -Java codegen owner, and a descriptor artifact whose consumer-compile result gates a release. +Stable Task 8부터 11은 proto 문체 규칙, Buf format·lint·breaking 관리, Java codegen 소유자 하나, 그리고 쓰는 쪽 +컴파일 결과가 릴리스를 막는 descriptor artifact를 요구한다. -Two of the tools those tasks name are absent from this toolchain. The Buf CLI is not installed. And -`protoc` is available through the Gradle protobuf plugin, but every leaf in this repository passes -spotless with google-java-format, checkstyle, SpotBugs at HIGH confidence, Error Prone and `-Werror` -— and generated protobuf sources pass none of them. Turning codegen on means excluding a source set -from five quality gates. +그 Task가 이름을 대는 도구 중 둘이 이 toolchain에 없다. Buf CLI는 설치돼 있지 않다. 그리고 `protoc`는 Gradle +protobuf 플러그인으로 쓸 수 있지만, 이 저장소의 모든 leaf는 google-java-format을 쓴 spotless, checkstyle, HIGH +confidence의 SpotBugs, Error Prone, `-Werror`를 통과하는데 — 생성된 protobuf 소스는 그중 어느 것도 통과하지 못한다. +codegen을 켜면 source set 하나를 품질 게이트 다섯에서 빼야 한다. -There is precedent for such an exclusion: the `jmh` source set has `spotbugsJmh` and `checkstyleJmh` -disabled and Error Prone off. So the carve-out is available. It is also a decision about the quality -baseline of a leaf, taken for one task, and outside what this work was asked to change. +그런 예외에는 선례가 있다: `jmh` source set은 `spotbugsJmh`와 `checkstyleJmh`를 끄고 Error Prone도 끈다. 그러니 빼는 +길은 있다. 하지만 그것은 Task 하나를 위해 leaf의 품질 기준선에 대해 내리는 결정이고, 이 일이 바꾸라고 받은 범위 +밖이다. -`adapter:inbound:grpc` also carries a recorded decision in the opposite direction: its `CLAUDE.md` -forbids the protobuf plugin and `.proto` in that leaf, on the grounds that a consuming feature module -should own its schema. +`adapter:inbound:grpc`에도 반대 방향으로 기록된 결정이 있다: 그 `CLAUDE.md`는 쓰는 기능 모듈이 자기 schema를 가져야 +한다는 이유로 그 leaf에서 protobuf 플러그인과 `.proto`를 금지한다. -## Decision +## 결정 -Commit the `.proto` sources and implement every rule the tasks require as executable Java, with no -protoc run and no Buf CLI invocation. +`.proto` 소스를 커밋하고, Task가 요구하는 모든 규칙을 protoc 실행도 Buf CLI 호출도 없이 실행되는 Java로 구현한다. -`GrpcProtoContractValidator` reads `.proto` text and enforces proto3 syntax, the -`{organization}.{domain}.v{major}` package rule, `java_multiple_files`, a generated Java package -disjoint from the hand-written one, `_UNSPECIFIED` enum zero values, `reserved` declarations checked -against a supplied removal history, a well-known-type allowlist and a map-field allowlist. It runs -against the committed schema in its own test, so the shipped `.proto` files are live rather than -decorative. +`GrpcProtoContractValidator`는 `.proto` 글을 읽고 다음을 강제한다: proto3 문법, `{organization}.{domain}.v{major}` +패키지 규칙, `java_multiple_files`, 손으로 쓴 것과 겹치지 않는 생성 Java 패키지, `_UNSPECIFIED` enum 0값, 받은 삭제 +이력과 대조한 `reserved` 선언, well-known type 허용 목록, map 필드 허용 목록. 자기 시험에서 커밋한 schema에 대고 +돌므로, 출하하는 `.proto` 파일은 장식이 아니라 살아 있다. -`GrpcBufPolicy` fixes the breaking gate at Buf's `FILE` category and names the four lifecycle stages -a compliant pipeline registers. `GrpcCodegenManifest` fixes one codegen owner and refuses a literal -generator version. `GrpcDescriptorArtifact`, `GrpcConsumerFixture` and `GrpcSchemaArtifactPublisher` -carry the schema hash, the descriptor digest and the per-consumer source-break report, and refuse a -publish that breaks a consumer or republishes a released version with different bytes. +`GrpcBufPolicy`는 breaking gate를 Buf의 `FILE` category로 고정하고, 규칙을 따르는 pipeline이 등록하는 lifecycle 단계 +넷을 이름으로 댄다. `GrpcCodegenManifest`는 codegen 소유자를 하나로 고정하고 리터럴 생성기 버전을 거절한다. +`GrpcDescriptorArtifact`, `GrpcConsumerFixture`, `GrpcSchemaArtifactPublisher`는 schema hash, descriptor digest, 쓰는 +쪽별 소스 깨짐 보고를 싣고, 쓰는 쪽을 깨뜨리는 게시나 이미 릴리스한 버전을 다른 바이트로 다시 게시하는 것을 +거절한다. -The committed `buf.yaml` states the same rules, so running the CLI in an environment that has it -reaches the same verdict. +커밋한 `buf.yaml`도 같은 규칙을 적으므로, CLI가 있는 환경에서 돌리면 같은 판정에 닿는다. -## Consequences +## 결과 -**The invariants are enforced; the process is not run.** Everything Tasks 8 to 11 are about — which -schema changes are refused, which consumer breaks block a release, who owns generation — is a -build-checkable rule here. What is missing is the protoc invocation and the Buf binary. +**불변식은 강제하고, 과정은 돌리지 않는다.** Task 8부터 11이 다루는 모든 것 — 어떤 schema 변경을 거절하는지, 어떤 +쓰는 쪽 깨짐이 릴리스를 막는지, 생성을 누가 가지는지 — 이 여기서는 빌드로 검사하는 규칙이다. 빠진 것은 protoc +호출과 Buf 바이너리다. -**Turning codegen on is a bounded change.** `GrpcCodegenManifest.caSkeleton()` already names the -owner, the managed version source, the build-directory output paths and the disjoint package policy -that a real plugin configuration has to satisfy. The work is a source-set carve-out and a plugin -block, not a redesign. +**codegen을 켜는 것은 한계 있는 변경이다.** `GrpcCodegenManifest.caSkeleton()`이 이미 실제 플러그인 설정이 만족해야 +할 소유자, 관리되는 버전 출처, 빌드 디렉터리 출력 경로, 겹치지 않는 패키지 정책을 이름으로 댄다. 할 일은 source set +예외와 플러그인 블록이지 재설계가 아니다. -**The fixtures use a text codec.** `GrpcTextCodec` gives the testkit a UTF-8 marshaller so the -in-process and Netty lanes can exercise interceptors, status mapping, metadata limits and stream -sequencing without generated stubs. Those contracts are properties of the platform and the transport, -not of any message shape, so the substitution costs nothing — and the lanes run today rather than -after codegen lands. +**fixture는 텍스트 codec을 쓴다.** `GrpcTextCodec`이 testkit에 UTF-8 marshaller를 줘서, 프로세스 안 lane과 Netty +lane이 생성된 stub 없이 interceptor, status 대응, metadata 한계, stream 순서를 시험할 수 있다. 그 계약은 메시지 +모양이 아니라 플랫폼과 전송의 성질이므로 바꿔 넣어도 잃는 것이 없다 — 그리고 lane이 codegen이 들어온 뒤가 아니라 +오늘 돈다. diff --git a/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md b/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md index 9a944e96..c40c9fd9 100644 --- a/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md +++ b/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md @@ -7,53 +7,48 @@ - 현재 정본: `docs/compatibility/grpc-support-matrix.md` -# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another +# ADR-GRPC-003: 전송·업무·stream 증거는 세 축이고, 어느 것도 다른 것을 뜻하지 않는다 -- Status: accepted -- Date: 2026-08-30 -- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-testkit` +- 상태: 채택 +- 날짜: 2026-08-30 +- 범위: `:grpc:grpc-core-api`, `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-testkit` -## Context +## 배경 -A failed RPC produces a status code, and a status code is not an answer to the question the caller -actually has. `DEADLINE_EXCEEDED` on a mutation does not say whether the mutation happened; -`UNAVAILABLE` after the request was sent does not say the server never saw it; response headers -arriving does not say a transaction committed. +실패한 RPC는 status code를 낸다. 그리고 status code는 호출자가 실제로 가진 질문의 답이 아니다. 변경 요청의 +`DEADLINE_EXCEEDED`는 변경이 일어났는지 말하지 않는다. 요청을 보낸 뒤의 `UNAVAILABLE`은 서버가 그것을 한 번도 보지 +않았다고 말하지 않는다. 응답 header가 도착했다고 트랜잭션이 커밋된 것은 아니다. -Every one of those is a place where a plausible inference produces a duplicate write or a lost one, -and none of them is visible in a test that only exercises the happy path. +그 하나하나가 그럴듯한 추론이 중복 쓰기나 잃은 쓰기를 낳는 자리이고, 성공 경로만 시험하는 시험에서는 하나도 보이지 +않는다. -## Decision +## 결정 -Model what happened as three independent axes, and refuse the inferences between them. +일어난 일을 서로 독립인 세 축으로 모델링하고, 축 사이의 추론을 거절한다. -`GrpcTransportEvidence` records what the client observed on the wire, and distinguishes `NOT_SENT` — -the client watched its own send fail — from `UNOBSERVED`, which is every other case where nothing is -known. `GrpcBusinessEvidence` records what the application confirmed, with `COMMIT_UNKNOWN` as a real -state rather than a placeholder. `GrpcStreamEvidence` is a sealed hierarchy whose non-empty cases all -carry a position, because "partial" without a last sequence can be neither resumed nor reconciled. +`GrpcTransportEvidence`는 client가 wire에서 본 것을 기록하고, `NOT_SENT` — client가 자기 보내기가 실패하는 것을 봤다 +— 와, 아무것도 모르는 다른 모든 경우인 `UNOBSERVED`를 구별한다. `GrpcBusinessEvidence`는 애플리케이션이 확인한 것을 +기록하고, `COMMIT_UNKNOWN`은 자리표시가 아니라 실제 상태다. `GrpcStreamEvidence`는 sealed 계층이고, 비어 있지 않은 +경우는 모두 위치를 싣는다. 마지막 순번 없는 「부분」은 이어 가지도 맞춰 보지도 못하기 때문이다. -`GrpcExecutionEvidence` holds all three and rejects combinations nobody could have observed: a unary -call with stream evidence, or a request the client watched fail to send that nonetheless carries -business evidence. Promoting response headers to a confirmed commit is possible only by editing -`withResponseHeadersSeen`, which is one method rather than a plausible line in an interceptor. +`GrpcExecutionEvidence`는 셋을 모두 가지고, 아무도 볼 수 없었을 조합을 거절한다: stream 증거가 있는 unary 호출, 또는 +client가 보내기 실패를 봤는데도 업무 증거를 실은 요청. 응답 header를 확인된 커밋으로 올리는 것은 +`withResponseHeadersSeen`을 고쳐야만 할 수 있다. 그것은 interceptor 안의 그럴듯한 한 줄이 아니라 메서드 하나다. -`GrpcCompletionOutcome.forMutation` derives what a caller may conclude, and defaults -`DEADLINE_EXCEEDED` and post-send `UNAVAILABLE` on a mutation to `COMPLETION_UNKNOWN`. +`GrpcCompletionOutcome.forMutation`이 호출자가 결론 내릴 수 있는 것을 끌어내고, 변경 요청의 `DEADLINE_EXCEEDED`와 +보낸 뒤의 `UNAVAILABLE`을 기본으로 `COMPLETION_UNKNOWN`으로 둔다. -The same types are used by the failure model and by the observation convention, so an incident has -one account of a call rather than two. +실패 모델과 관측 규약이 같은 타입을 쓰므로, 사고 때 호출 하나에 대한 설명이 둘이 아니라 하나다. -## Consequences +## 결과 -**A whole class of retry bug becomes unrepresentable.** `GrpcRetryEligibility` reads all three axes -plus the idempotency profile; a caller cannot reach "retry" from a status alone because the status -alone is not an input. +**재시도 결함의 한 종류를 아예 나타낼 수 없게 된다.** `GrpcRetryEligibility`는 세 축 모두와 멱등성 profile을 읽는다. +status만으로는 입력이 아니므로, 호출자는 status만 보고 「재시도」에 닿을 수 없다. -**The fault lane has something to check.** `GrpcTransportEvidenceClassifier` turns a client's -observations into evidence and refuses to infer `NOT_SENT` from an unobserved state — and the lane -exercises it against a real connection dropped mid-call, not against a mock. +**장애 lane에 검사할 것이 생긴다.** `GrpcTransportEvidenceClassifier`가 client의 관찰을 증거로 바꾸고, 관찰하지 않은 +상태에서 `NOT_SENT`를 추론하기를 거절한다 — 그리고 lane은 mock이 아니라 호출 중간에 끊은 실제 연결에 대고 그것을 +시험한다. -**Callers must handle a third outcome.** `COMPLETION_UNKNOWN` is not a failure and not a success, and -a caller that treats it as either is wrong. `GrpcOperationStatusQuery` and `GrpcCompletionReconciler` -exist so that resolving it is a supported path rather than an exercise for the caller. +**호출자는 세 번째 결과를 다뤄야 한다.** `COMPLETION_UNKNOWN`은 실패도 성공도 아니고, 둘 중 하나로 다루는 호출자는 +틀렸다. `GrpcOperationStatusQuery`와 `GrpcCompletionReconciler`는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라 +지원하는 경로가 되게 하려고 있다. diff --git a/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md b/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md index 00a03ed1..f86b2b31 100644 --- a/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md +++ b/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md @@ -7,129 +7,106 @@ - 현재 정본: `docs/compatibility/grpc-support-matrix.md` -# ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger +# ADR-GRPC-004: 재시도 소유자는 하나이고, 키가 있는 변경에는 durable 원장이 필요하다 -- Status: accepted -- Date: 2026-08-30 -- Scope: `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api` +- 상태: 채택 +- 날짜: 2026-08-30 +- 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api` -## Context +## 배경 -Three layers can retry a gRPC call: the application, the channel's service config, and a service -mesh. Their effects multiply. Three attempts at each layer is twenty-seven requests for one call, and -the load arrives exactly when the dependency is already failing. +gRPC 호출을 재시도할 수 있는 계층이 셋 있다: 애플리케이션, channel의 service config, service mesh. 그 효과는 곱해진다. +계층마다 세 번 시도하면 호출 하나에 요청 스물일곱 개이고, 그 부하는 의존 대상이 이미 실패하고 있을 바로 그때 온다. -Separately, a mutation that is safe to repeat needs somewhere to record that it ran. Without one, a -retry after a lost response either duplicates the effect or drops it, and nothing distinguishes the -two afterwards. +따로, 되풀이해도 안전한 변경에는 그것이 돌았다는 기록을 둘 곳이 필요하다. 없으면 응답을 잃은 뒤의 재시도는 효과를 +겹치게 하거나 버리게 되고, 나중에 둘을 구별할 것이 없다. -## Decision +## 결정 -**Exactly one retry owner per channel.** `GrpcRetryOwner` has four values including `NONE`, which is a -decision rather than an omission. `GrpcServiceConfigPolicy` refuses an in-process retry entry when the -owner is the mesh or nobody, and `GrpcRetryOwnershipValidator` compares the service config's method -names against the policy catalog — a renamed method leaves its retry entry matching nothing, silently, -and the method then runs with channel defaults. +**channel마다 재시도 소유자는 정확히 하나다.** `GrpcRetryOwner`에는 `NONE`을 포함해 값이 넷 있고, `NONE`은 빠뜨림이 +아니라 결정이다. `GrpcServiceConfigPolicy`는 소유자가 mesh이거나 아무도 아닐 때 프로세스 안 재시도 항목을 거절하고, +`GrpcRetryOwnershipValidator`는 service config의 메서드 이름을 정책 catalog와 대조한다 — 이름이 바뀐 메서드는 그 재시도 +항목이 소리 없이 아무것과도 맞지 않게 되고, 그 메서드는 channel 기본값으로 돈다. -**Retry eligibility reads the method, the evidence and the status together.** -`GrpcRetryEligibility` refuses a non-idempotent method outright, refuses any call whose stream -delivered a prefix, and turns a `DEADLINE_EXCEEDED` or post-send `UNAVAILABLE` mutation into -"resolve the completion first" rather than a retry. +**재시도 자격은 메서드, 증거, status를 함께 읽는다.** `GrpcRetryEligibility`는 멱등이 아닌 메서드를 바로 거절하고, +stream이 앞부분을 전달한 호출을 모두 거절하며, 변경 요청의 `DEADLINE_EXCEEDED`나 보낸 뒤의 `UNAVAILABLE`을 재시도가 +아니라 「먼저 완료를 풀어라」로 바꾼다. -**A keyed mutation is retryable only with both a caller key and a durable ledger.** -`GrpcOperationLedger` is a port in `grpc-core-api`, so the policy layer can require durable -idempotency without depending on a database. Its `claim` contract is a single atomic insert-or-read -against a unique constraint: `JpaGrpcOperationLedger` inserts first and reads on constraint violation, -because a read-then-insert implementation has a window exactly as wide as the race it closes and -passes every test that does not run two attempts concurrently. +**키가 있는 변경은 호출자 키와 durable 원장이 둘 다 있을 때만 재시도할 수 있다.** `GrpcOperationLedger`는 +`grpc-core-api`의 포트라서, 정책 계층이 데이터베이스에 의존하지 않고 durable 멱등성을 요구할 수 있다. 그 `claim` 계약은 +unique 제약에 대한 원자적 insert-or-read 하나다: `JpaGrpcOperationLedger`는 먼저 insert하고 제약 위반이면 읽는다. +read-then-insert 구현에는 그것이 닫으려는 경쟁만큼 넓은 창이 있고, 두 시도를 동시에 돌리지 않는 모든 시험을 +통과하기 때문이다. -The identity is caller fingerprint plus full method plus hashed key. All three are load-bearing: -without the caller, one tenant's key suppresses another's write; without the method, a key reused -across operations makes the second a replay of the first. +identity는 호출자 fingerprint + 전체 메서드 + hash한 키다. 셋 모두 꼭 필요하다: 호출자가 없으면 한 테넌트의 키가 다른 +테넌트의 쓰기를 막는다. 메서드가 없으면 operation 사이에서 다시 쓴 키 때문에 둘째가 첫째의 재생이 된다. -## Consequences +## 결과 -**A budget bounds retries as a fraction of traffic.** `GrpcRetryBudget` degrades to roughly no -retries when everything is failing, which is the behaviour that lets a dependency recover. +**예산이 재시도를 traffic의 비율로 묶는다.** `GrpcRetryBudget`은 모든 것이 실패할 때 재시도가 거의 없는 쪽으로 +떨어진다. 그것이 의존 대상이 회복하게 하는 동작이다. -**The ledger and the mutation should commit together.** `JpaGrpcOperationLedger` carries no -transaction annotations, deliberately: a `REQUIRES_NEW` would put the claim in its own transaction and -reintroduce the window where the write is durable and the claim is not. +**원장과 변경은 함께 커밋해야 한다.** `JpaGrpcOperationLedger`는 일부러 트랜잭션 애너테이션을 달지 않는다: +`REQUIRES_NEW`는 claim을 자기 트랜잭션에 넣어서, 쓰기는 durable한데 claim은 아닌 창을 다시 들인다. -**A claim expires instead of blocking its key forever** (review 2026-11-01, 03-10). A claim still -`IN_PROGRESS` after the claim TTL is presumed abandoned by a dead owner, and the next retry of the same -request takes it over with `GrpcOperationLedger.reclaimStale` — one conditional -`UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff`, so of two concurrent takeovers exactly -one wins, the same shape as `reclaimFailed`. The TTL is the `claimTtl` argument of -`GrpcIdempotencyInterceptor`, refused at construction when it is not longer than every keyed method's -deadline. Since the 03-11 follow-up the starter assembles the interceptor when -`app.grpc.platform.operation-ledger-enabled=true` and takes the TTL from -`app.grpc.platform.operation-ledger-claim-ttl` (default 5m); a TTL the constructor refuses fails startup -naming that key, and an enabled flag without a `GrpcOperationLedger` bean fails startup too. +**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를 켜도 기동이 실패한다. -The takeover is safe only because the commit is recorded in the mutation's own transaction: then a -claim still `IN_PROGRESS` means the mutation never committed. An adopter that commits them separately -turns an abandoned claim into an unknown outcome, and a takeover can run the mutation twice. A takeover -of an owner that is merely slow does the same, which is why the TTL must exceed the slowest keyed -method and not just its deadline. +넘겨받기가 안전한 것은 커밋을 변경 자신의 트랜잭션 안에서 기록하기 때문뿐이다: 그러면 아직 `IN_PROGRESS`인 claim은 +변경이 한 번도 커밋되지 않았다는 뜻이다. 둘을 따로 커밋하는 채택자는 버려진 claim을 모르는 결과로 만들고, 넘겨받기가 +변경을 두 번 돌릴 수 있다. 그저 느린 주인을 넘겨받아도 같은 일이 생긴다. 그래서 TTL은 deadline만이 아니라 키가 있는 +가장 느린 메서드보다 길어야 한다. -Rejected: an owner token with a heartbeat lease (the outbox lease model) — needed only when a keyed -method can run longer than any fixed TTL; revisit when one exists. A sweeper job that deletes stale -rows — it needs a scheduler this family does not have, and deleting a claim makes the next retry a -fresh claim with no record that an attempt was abandoned. +버린 것: heartbeat lease를 단 owner token(outbox lease 모델) — 키가 있는 메서드가 어떤 고정 TTL보다 오래 돌 수 있을 때만 +필요하다. 그런 메서드가 생기면 다시 본다. 낡은 행을 지우는 sweeper job — 이 family에 없는 scheduler가 필요하고, +claim을 지우면 다음 재시도가 시도를 버렸다는 기록 없는 새 claim이 된다. -**A taken-over owner is fenced by a claim token** (re-review 2026-11-03, RR-02-04). The owner a -takeover presumes dead may only be slow. Without knowing which attempt held the claim, its late -`markFailed` turned the new attempt's claim `FAILED_TERMINAL`, the next retry re-claimed it, and two -attempts ran the mutation at once; its late `markCommitted` committed beside the new attempt. Every -claim now carries a `GrpcClaimToken` (`claim_attempt`, migration V003): 1 for the first claim, one more -for each `reclaimFailed` or `reclaimStale`. `decide` returns it on `PROCEED`, and `recordCommit` / -`recordFailure` hand it back. A commit or a failure is one conditional -`UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`: a commit by an attempt that lost -the claim is refused with an exception, so its business transaction rolls back; a failure by one is -ignored (`markFailed` returns false). The same conditional update closes the JPA commit race — -load-check-save let two commits that both read `IN_PROGRESS` both write; now exactly one matches. -A claim whose conflicting row is purged between insert and read retries the insert once instead of -failing the call. +**넘겨받긴 주인은 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)` is fenced the same way (re-review 2026-11-03 round 2, RR-01-15): it is a -conditional `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` and returns whether it -deleted. It used to delete by key alone, so any caller could erase the claim of the attempt that held -it, or a finished record a retry replays. The counter lives in the row, so a deleted row's key starts -again at attempt 1: the token separates the attempts of one row, not attempts across a delete. Both -deletions are limited accordingly — release only for a claim whose owner is known to be gone, purge -only for rows finished longer ago than any retry. Rejected: dropping `release` from the port -(`markFailed` then `reclaimFailed` keeps the counter, but a deployment that must free a key for a -different request has no other path), and a tombstone row that keeps the counter (a second state to -purge, for a window the two limits already close). +`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 행(지울 두 번째 상태가 생기는데, 그 창은 두 제한이 +이미 닫는다). -Chosen over the claim moment as the token (`WHERE claimed_at = :claimedAt`), which needs no column: -PostgreSQL stores microseconds while `Instant` carries nanoseconds, so the token a caller holds and -the one stored can differ by rounding, and two processes' clocks can give two attempts the same -moment. The counter has neither problem. The heartbeat lease above stays rejected for the same reason -as before; the token fences without one. +token으로 claim 시각(`WHERE claimed_at = :claimedAt`)을 쓰는 안보다 이것을 골랐다. 시각은 열이 따로 필요 없지만, +PostgreSQL은 마이크로초를 저장하고 `Instant`는 나노초를 싣는다. 그래서 호출자가 쥔 token과 저장된 것이 반올림만큼 +다를 수 있고, 두 프로세스의 시계가 두 시도에 같은 시각을 줄 수 있다. counter에는 두 문제가 다 없다. 위 heartbeat lease는 +앞과 같은 이유로 계속 버린다. token은 그것 없이 막는다. -**What `operation-ledger-enabled=true` promises (03-11 (b), recorded 2026-11-03, RR-02-07).** The -2026-11-01 review offered (a) delete the flag and judge by whether a ledger bean exists, or (b) keep the -flag and have the starter assemble the decision function from it. (b) is kept: the assembly and the -TTL validation live in one place instead of in every adopter. (a) was rejected because it removes the -false promise only by removing the assembly with it. The limit stays and is stated where an operator -meets it: the starter builds no server, so the flag assembles the decision function only, and keys are -honoured once the adopter's `IDEMPOTENCY` stage interceptor or service adapter calls `decide` and -`recordCommit`. `GrpcPlatformStartupValidator`'s refusal for a keyed method says exactly that; a running -process cannot see whether the stage exists, so the validator does not claim to check it. +**`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는 그것을 검사한다고 주장하지 않는다. -**Finished rows are purged after a retention; in-progress rows never are** (03-10 follow-up). -`GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)` deletes at most `limit` `COMMITTED` or -`FAILED_TERMINAL` rows that completed before the cutoff, oldest first — on PostgreSQL one bounded -`DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` served by the partial index -of migration V002. `GrpcOperationLedgerRetention.purgeExpired(now)` applies -`app.grpc.platform.operation-ledger-retention` (default 24h, the HTTP idempotency replay TTL) in -batches. A retry after its record was purged is a fresh claim and runs again, so the retention must -exceed the callers' retry window. The adopter schedules the purge; the starter assembles the policy -only, because a scheduled bean would force a scheduler onto every deployment and the starter cannot -know which replica should run it. +**끝난 행은 보존 기간 뒤에 지우고, 진행 중인 행은 절대 지우지 않는다**(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가 돌려야 하는지 알 수 없기 때문이다. -**A key reused for a different request is a caller error, not a duplicate.** The stored request -fingerprint turns that into `FAILED_PRECONDITION` rather than silently returning the first request's -answer. +**다른 요청에 다시 쓴 키는 중복이 아니라 호출자 오류다.** 저장된 요청 fingerprint가 그것을 소리 없이 첫 요청의 답을 +돌려주는 대신 `FAILED_PRECONDITION`으로 바꾼다. diff --git a/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md b/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md index 712eddf8..a210de5d 100644 --- a/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md +++ b/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md @@ -7,53 +7,46 @@ - 현재 정본: `docs/compatibility/grpc-support-matrix.md` -# ADR-GRPC-005: One writer per stream, a bounded queue, and resume that refuses to guess +# ADR-GRPC-005: stream마다 쓰는 쪽 하나, 한계 있는 queue, 짐작하기를 거절하는 resume -- Status: accepted -- Date: 2026-08-30 -- Scope: `:grpc:grpc-runtime` (was `grpc-policy`) +- 상태: 채택 +- 날짜: 2026-08-30 +- 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`) -## Context +## 배경 -`StreamObserver` is not thread-safe, and the failure when two producers call `onNext` concurrently is -not an exception — it is interleaved bytes, which a client decodes as a corrupt message or, worse, as -a valid one it should never have received. +`StreamObserver`는 thread-safe가 아니다. 두 producer가 동시에 `onNext`를 부를 때의 실패는 예외가 아니다 — 섞인 바이트이고, +client는 그것을 깨진 메시지로, 더 나쁘게는 받지 말았어야 할 유효한 메시지로 decode한다. -Two further properties of server streams are easy to get wrong in ways that look healthy. A consumer -that falls behind either terminates the stream or silently loses messages, and the second leaves a -client with a stream that appears fine and is missing changes. And a reconnect either continues from -a position the server can still replay, or skips whatever is no longer there. +server stream에는 건강해 보이는 방식으로 틀리기 쉬운 성질이 둘 더 있다. 뒤처진 소비자는 stream을 끝내거나 메시지를 소리 +없이 잃는데, 둘째는 client에게 멀쩡해 보이지만 변경이 빠진 stream을 남긴다. 그리고 재연결은 서버가 아직 재생할 수 있는 +위치에서 이어 가거나, 더는 없는 것을 건너뛴다. -## Decision +## 결정 -**A bounded queue drained by one writer.** `GrpcSerializedStreamWriter` accepts messages from any -thread and hands them to the transport only from `flush`, which is synchronized. `write` returning -`ACCEPTED` means queued, and the name is deliberately not `sent`: the transport call returns as soon -as bytes are handed over, so no method here can honestly report delivery. +**쓰는 쪽 하나가 비우는 한계 있는 queue.** `GrpcSerializedStreamWriter`는 어느 스레드에서든 메시지를 받고, synchronized인 +`flush`에서만 전송에 넘긴다. `write`가 `ACCEPTED`를 돌려주는 것은 줄 세웠다는 뜻이고, 이름을 일부러 `sent`로 하지 +않았다: 전송 호출은 바이트를 넘기자마자 돌아오므로, 여기 어떤 메서드도 전달을 정직하게 알릴 수 없다. -**Both a message bound and a byte bound.** Either alone is unbounded in the other dimension. -`GrpcFlowControlPolicy` also takes the transport's own readiness signal, because a writer that relies -only on its queue bound produces as fast as it can allocate. +**메시지 한계와 바이트 한계를 둘 다.** 하나만 두면 다른 차원으로는 한계가 없다. `GrpcFlowControlPolicy`는 전송 자신의 +readiness 신호도 받는다. queue 한계에만 기대는 쓰는 쪽은 메모리를 할당할 수 있는 만큼 빨리 만들어 내기 때문이다. -**Termination is the default for a slow consumer.** `GrpcSlowConsumerPolicy.DROP_OLDEST` exists for -feeds whose business meaning tolerates loss, and is not the default, because a client cannot detect -dropped messages: the sequence numbers it sees are the ones it was sent. +**느린 소비자에게는 끝내기가 기본이다.** `GrpcSlowConsumerPolicy.DROP_OLDEST`는 업무 뜻이 손실을 견디는 feed를 위해 +있고 기본값이 아니다. client는 버려진 메시지를 알아챌 수 없기 때문이다: client가 보는 순번은 보내진 것의 순번이다. -**Resume is refused rather than faked.** `GrpcStreamGapDetector` requires a signed, unexpired token -whose caller and filter fingerprints match the current request, refuses one whose snapshot version -moved, and returns `FULL_RESYNC_REQUIRED` when the cursor predates retained history. `GrpcResumeToken` -carries a key id so the signing key can rotate without invalidating every outstanding token. +**resume은 꾸며 내지 않고 거절한다.** `GrpcStreamGapDetector`는 서명됐고 만료되지 않았으며 호출자·필터 fingerprint가 +지금 요청과 맞는 token을 요구하고, snapshot version이 움직인 token을 거절하며, cursor가 보존한 이력보다 앞서면 +`FULL_RESYNC_REQUIRED`를 돌려준다. `GrpcResumeToken`은 key id를 싣는다. 그래서 서명 키를 바꿔도 아직 쓰이는 모든 token이 +무효가 되지 않는다. -## Consequences +## 결과 -**A stream carries an envelope, not a bare payload.** `GrpcStreamEnvelope` holds the stream id, -generation, sequence, snapshot version and resume token, because resume, gap detection and drain all -need a position and a generation. +**stream은 맨 payload가 아니라 envelope을 싣는다.** `GrpcStreamEnvelope`은 stream id, generation, 순번, snapshot version, +resume token을 가진다. resume, 빈틈 찾기, 비우기가 모두 위치와 generation을 필요로 하기 때문이다. -**Four clocks, not one.** `GrpcStreamLifetimePolicy` separates setup deadline, idle timeout, max -duration and heartbeat interval, and refuses combinations where one can never fire. Merging any pair -produces a familiar bug: an idle timeout used as a max duration kills healthy busy streams. +**시계는 하나가 아니라 넷이다.** `GrpcStreamLifetimePolicy`는 준비 deadline, idle timeout, 최대 지속 시간, heartbeat +간격을 나누고, 하나가 절대 울릴 수 없는 조합을 거절한다. 어느 둘을 합치든 익숙한 결함이 나온다: 최대 지속 시간으로 쓴 +idle timeout은 건강하게 바쁜 stream을 죽인다. -**A heartbeat is a liveness signal and nothing else.** It is not an application acknowledgement and -not an ordering guarantee; `GrpcStreamHeartbeat` says so in the place somebody would otherwise reuse -it. +**heartbeat는 살아 있다는 신호이고 그 밖의 무엇도 아니다.** 애플리케이션 확인 응답도 순서 보장도 아니다. +`GrpcStreamHeartbeat`가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다. diff --git a/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md b/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md index 17e677a6..c58764b0 100644 --- a/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md +++ b/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md @@ -7,71 +7,61 @@ - 현재 정본: `docs/compatibility/grpc-support-matrix.md` -# ADR-GRPC-006: Stable discovery is DNS and static, and a Kubernetes profile names who balances +# ADR-GRPC-006: Stable discovery는 DNS와 static이고, Kubernetes profile은 누가 분산하는지 이름으로 댄다 -- Status: accepted -- Date: 2026-08-31 -- Scope: `:grpc:grpc-runtime` (was `grpc-discovery`, `grpc-client`) +- 상태: 채택 +- 날짜: 2026-08-31 +- 범위: `:grpc:grpc-runtime`(예전 `grpc-discovery`, `grpc-client`) -## Context +## 배경 -A gRPC channel's discovery configuration has a failure mode with no runtime symptom: it works, and -it does not do what the dashboard says it does. +gRPC channel의 discovery 설정에는 런타임 증상이 없는 실패 방식이 있다: 동작은 하는데, 대시보드가 말하는 일을 하지 않는다. -The specific case is `round_robin` over a Kubernetes Service ClusterIP. The Service is one virtual -address, so the resolver returns one endpoint and the client-side balancer has nothing to rotate -across; kube-proxy picks a pod at connect time, and an HTTP/2 connection is long-lived, so every -request from that client goes to the same pod for the life of the connection. Nothing fails. The -configuration says `round_robin`, the metrics show requests spread across clients rather than pods, -and the conclusion "we have client-side load balancing" is wrong in a way nobody is prompted to -check. +구체적인 경우는 Kubernetes Service ClusterIP 위의 `round_robin`이다. Service는 가상 주소 하나라서 resolver가 endpoint 하나를 +돌려주고 client 쪽 분산기는 돌려 가며 보낼 대상이 없다. kube-proxy는 연결할 때 pod를 고르고, HTTP/2 연결은 오래 살기 +때문에, 그 client의 모든 요청이 연결이 사는 동안 같은 pod로 간다. 실패하는 것은 없다. 설정은 `round_robin`이라고 말하고, +metric은 요청이 pod가 아니라 client 사이에 퍼진 것을 보여 주며, 「client 쪽 부하 분산을 한다」는 결론은 아무도 확인할 +계기가 없는 방식으로 틀렸다. -The mirror-image mistake is `pick_first` over a headless record, which pins a client to one pod out -of many. +거울상 실수는 headless record 위의 `pick_first`다. 많은 pod 중 하나에 client를 묶는다. -Separately, a service mesh changes who owns retries, and a deployment that adds mesh routing without -removing its own retry policy has two retriers whose effects multiply. +따로, service mesh는 재시도를 누가 가지는지 바꾸고, mesh 라우팅을 더하면서 자기 재시도 정책을 빼지 않은 배포는 효과가 +곱해지는 재시도자 둘을 가진다. -## Decision +## 결정 -**Stable resolvers are Static, DNS and Unix domain socket; Stable load balancing is `pick_first` and -`round_robin`.** `GrpcDiscoveryPolicyValidator.requireStableScheme` refuses `xds`, `consul`, `etcd` -and `eureka` by name, with a message saying they are Advanced capabilities with their own control -plane and promotion gate rather than unknown schemes. +**Stable resolver는 Static, DNS, Unix domain socket이고, Stable 부하 분산은 `pick_first`와 `round_robin`이다.** +`GrpcDiscoveryPolicyValidator.requireStableScheme`은 `xds`, `consul`, `etcd`, `eureka`를 이름으로 거절하고, 그것이 모르는 +scheme이 아니라 자기 control plane과 승격 gate를 가진 Advanced capability라고 메시지로 말한다. -**The pairing is checked against the resolved address count, not against intent.** -`GrpcResolverProfile` carries `expectedAddressCount`, and `GrpcStableLoadBalancer.effective` answers -whether the policy distributes anything over that many endpoints. A `round_robin` profile over one -address is a reported violation whose message says it describes spreading that is not happening. +**짝 맞춤은 의도가 아니라 해석된 주소 수와 대조한다.** `GrpcResolverProfile`은 `expectedAddressCount`를 싣고, +`GrpcStableLoadBalancer.effective`가 그 수의 endpoint 위에서 정책이 무언가를 분산하는지 답한다. 주소 하나 위의 +`round_robin` profile은 보고되는 위반이고, 그 메시지는 그것이 일어나지 않는 퍼뜨리기를 설명한다고 말한다. -**A Kubernetes deployment names its routing mode**, and the mode implies both the balancer and the -retry owner. `GrpcKubernetesRoutingMode` has three values — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — and -`GrpcKubernetesProfile` refuses a mesh profile whose retry owner retries in-process. +**Kubernetes 배포는 자기 라우팅 모드를 이름으로 대고**, 그 모드가 분산기와 재시도 소유자를 둘 다 정한다. +`GrpcKubernetesRoutingMode`에는 값이 셋 있다 — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — 그리고 `GrpcKubernetesProfile`은 재시도 +소유자가 프로세스 안에서 재시도하는 mesh profile을 거절한다. -**A profile that carries long-lived streams must state a reconnect budget and a readiness drain -grace.** A stream pins a client to one pod for its whole life, so every rollout, eviction and -scale-down ends it. `GrpcKubernetesProfileValidator` additionally reports a VIP profile carrying -long streams, and a drain grace shorter than the reconnect budget — the second means the pod stops -serving before its clients have finished reconnecting elsewhere. +**오래 사는 stream을 싣는 profile은 재연결 예산과 readiness 비우기 유예를 밝혀야 한다.** stream은 사는 내내 client를 pod +하나에 묶으므로, 모든 rollout, eviction, scale-down이 그것을 끝낸다. `GrpcKubernetesProfileValidator`는 긴 stream을 싣는 +VIP profile과, 재연결 예산보다 짧은 비우기 유예도 알린다 — 후자는 client가 다른 곳으로 재연결을 마치기 전에 pod가 응답을 +멈춘다는 뜻이다. -**A DNS profile must refresh.** `GrpcResolverProfile` refuses a zero refresh interval on DNS, -because a channel that resolved once at startup keeps sending to addresses that stopped existing an -hour ago, and the resulting `UNAVAILABLE` looks like an unhealthy deployment long after the rollout -finished. +**DNS profile은 새로 고쳐야 한다.** `GrpcResolverProfile`은 DNS에서 새로 고침 간격 0을 거절한다. 기동 때 한 번 해석한 +channel은 한 시간 전에 없어진 주소로 계속 보내고, 그 결과인 `UNAVAILABLE`은 rollout이 끝난 지 한참 뒤에도 건강하지 않은 +배포처럼 보인다. -## Consequences +## 결과 -**Two validators, not one.** `GrpcDiscoveryPolicyValidator` asks whether a balancer does anything -over the addresses it will see; `GrpcKubernetesProfileValidator` asks whether the deployment shape, -the retry owner and the stream obligations agree. A deployment can have a coherent resolver profile -and still have put retries in two places, so merging them would let one answer hide the other. +**validator는 하나가 아니라 둘이다.** `GrpcDiscoveryPolicyValidator`는 분산기가 자기가 볼 주소 위에서 무언가를 하는지 +묻는다. `GrpcKubernetesProfileValidator`는 배포 모양, 재시도 소유자, stream 의무가 맞는지 묻는다. 배포는 resolver profile이 +앞뒤가 맞으면서도 재시도를 두 곳에 둘 수 있다. 그래서 둘을 합치면 한 답이 다른 답을 가린다. -**`expectedAddressCount` has to come from somewhere.** It is a declared number, and a declaration can -be wrong. It is still better than the alternative, which is not comparing anything: a wrong -declaration is a wrong statement somebody wrote down, and a missing one is a question nobody asked. -`GrpcChannelProfileValidator` takes resolved counts where they are known at startup and skips the -check where they are not, rather than guessing and failing on a name that cannot be resolved yet. +**`expectedAddressCount`는 어딘가에서 와야 한다.** 선언한 숫자이고, 선언은 틀릴 수 있다. 그래도 아무것도 비교하지 않는 +대안보다 낫다: 틀린 선언은 누가 적어 둔 틀린 말이고, 빠진 선언은 아무도 묻지 않은 질문이다. +`GrpcChannelProfileValidator`는 기동 때 알 수 있는 곳에서는 해석된 수를 받고, 알 수 없는 곳에서는 짐작해서 아직 해석할 수 +없는 이름에서 실패하는 대신 검사를 건너뛴다. -**xDS is reachable, and not by this route.** It lives in `grpc-advanced` (package `resilience`/`xds`) behind its -capability flag and its production approval, and `GrpcXdsStartupGuard.advertisableAsStableSupport()` -returns false so the Stable support statement cannot widen quietly. See ADR-GRPC-ADV-001. +**xDS에는 닿을 수 있지만, 이 길로는 아니다.** xDS는 `grpc-advanced`(패키지 `resilience`/`xds`)에서 자기 capability flag와 +운영 승인 뒤에 있고, `GrpcXdsStartupGuard.advertisableAsStableSupport()`가 false를 돌려주므로 Stable 지원 설명이 조용히 +넓어질 수 없다. ADR-GRPC-ADV-001을 본다. diff --git a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md index 63e6bfde..07decf9c 100644 --- a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md +++ b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md @@ -7,60 +7,51 @@ - 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md` -# ADR-GRPC-ADV-001: Each advanced capability has its own flag, its own grade and its own promotion +# ADR-GRPC-ADV-001: advanced capability마다 자기 flag, 자기 등급, 자기 승격이 있다 -- Status: accepted -- Date: 2026-08-30 -- Scope: `:grpc-advanced:*` +- 상태: 채택 +- 날짜: 2026-08-30 +- 범위: `:grpc-advanced:*` -## Context +## 배경 -The advanced plan covers sixteen capabilities that differ by orders of magnitude in what they bring -with them. gRPC-Web adds a proxy. Reactor adds a dependency. xDS adds a control plane, its outage -modes, its own security boundary and its own version skew. Hedging duplicates production traffic. +advanced 계획은 capability 열여섯을 다룬다. 그것들이 함께 가져오는 것은 몇 자릿수씩 다르다. gRPC-Web은 proxy를 더한다. +Reactor는 의존 하나를 더한다. xDS는 control plane, 그 장애 방식, 자기 보안 경계, 자기 버전 어긋남을 더한다. hedging은 운영 +traffic을 겹친다. -Bundling them under one flag makes enabling the cheapest of those the same decision as enabling the -most consequential. +그것들을 flag 하나로 묶으면 가장 싼 것을 켜는 일이 가장 무거운 것을 켜는 일과 같은 결정이 된다. -## Decision +## 결정 -**One flag per capability**, under `ca-skeleton.grpc.advanced..enabled`, all off by -default. +**capability마다 flag 하나.** `ca-skeleton.grpc.advanced..enabled` 아래에 있고, 기본은 모두 꺼짐이다. -**Four grades.** `ADVANCED_STABLE` starts on its flag; `EXPERIMENTAL` additionally needs a separate -production approval, because the flag says somebody wanted the feature and the approval says somebody -accepted that its failure modes are not fully characterised; `WATCH` cannot start at all; `DISABLED` -is withdrawn. +**등급 넷.** `ADVANCED_STABLE`은 flag로 시작한다. `EXPERIMENTAL`은 따로 운영 승인도 필요하다. flag는 누가 그 기능을 원했다는 +뜻이고, 승인은 누가 그 장애 방식이 다 밝혀지지 않았음을 받아들였다는 뜻이기 때문이다. `WATCH`는 아예 시작할 수 없다. +`DISABLED`는 거둬들인 것이다. -`GrpcAdvancedModuleGuard` distinguishes the three refusals — flag unset, grade unstartable, -production unapproved — because the remedy differs in each case. +`GrpcAdvancedModuleGuard`는 세 거절 — flag 없음, 시작할 수 없는 등급, 운영 승인 없음 — 을 구별한다. 경우마다 고치는 법이 +다르기 때문이다. -**Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per -capability, so no promotion can drag another along; -`GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested -property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside -their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a -review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for -`ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the -capability's dependencies and its failure modes. +**승격 증거는 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의 의존과 장애 방식을 +받는다는 뜻이기 때문이다. -**Infrastructure is named per capability.** `GrpcAdvancedInfrastructureTestkit` records that -gRPC-Web needs a proxy, Servlet needs a container, xDS needs a stoppable control plane and Kotlin -needs a toolchain. A suite that runs without its infrastructure passes and establishes nothing, which -is worse than not having one. +**기반 시설은 capability마다 이름으로 댄다.** `GrpcAdvancedInfrastructureTestkit`은 gRPC-Web에는 proxy가, Servlet에는 +container가, xDS에는 멈출 수 있는 control plane이, Kotlin에는 toolchain이 필요하다고 적는다. 기반 시설 없이 도는 suite는 +통과하고 아무것도 세우지 않는다. 없는 것보다 나쁘다. -## Consequences +## 결과 -**The Kotlin adapter fails closed here, and says why.** This repository has no Kotlin toolchain, so -`GrpcKotlinCompatibilityGate.supportableHere()` returns false. The four contract requirements — one -schema source, coroutine cancellation propagation, Flow backpressure inside the Stable bounds, -platform evidence types preserved — are checkable and are checked; only the compile lane is missing. +**Kotlin 어댑터는 여기서 실패하면 닫히고, 이유를 말한다.** 이 저장소에는 Kotlin toolchain이 없어서 +`GrpcKotlinCompatibilityGate.supportableHere()`가 false를 돌려준다. 계약 요구 넷 — schema 출처 하나, coroutine 취소 전파, +Stable 한계 안의 Flow backpressure, 플랫폼 증거 타입 보존 — 은 검사할 수 있고 검사한다. 빠진 것은 compile lane뿐이다. -**Edition 2026 cannot be used however its watch report reads.** `GrpcEdition2026Guard` is not -conditional on the report, because letting a status record also authorise use means a schema moves -onto an edition the moment somebody marks four fields SUPPORTED, with no promotion decision, no -consumer migration and no ADR. +**Edition 2026은 그 watch 보고가 무어라 하든 쓸 수 없다.** `GrpcEdition2026Guard`는 보고에 따라 달라지지 않는다. 상태 기록이 +사용까지 허락하게 두면, 누가 필드 넷을 SUPPORTED로 표시하는 순간 schema가 승격 결정도, 쓰는 쪽 옮기기도, ADR도 없이 그 +edition으로 옮겨 가기 때문이다. -**xDS is not part of the Stable support statement.** It works, behind its flag and its approval; -`GrpcXdsStartupGuard.advertisableAsStableSupport()` returns false so a support matrix cannot widen -quietly. +**xDS는 Stable 지원 설명의 일부가 아니다.** flag와 승인 뒤에서 동작한다. `GrpcXdsStartupGuard.advertisableAsStableSupport()`가 +false를 돌려주므로 support matrix가 조용히 넓어질 수 없다. diff --git a/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md b/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md index 24a06a89..65d7427e 100644 --- a/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md +++ b/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md @@ -7,38 +7,34 @@ - 현재 정본: `docs/jpa/repository-adaptation.md` -# ADR-JPA-001 — The domain owns the persistence model +# ADR-JPA-001 — 영속 모델은 도메인이 가진다 -- Status: Accepted -- Date: 2026-08-11 -- Design: §10.1, §23.3 +- 상태: 채택 +- 날짜: 2026-08-11 +- 설계: §10.1, §23.3 -## Context +## 배경 -A persistence platform can either own the repository abstraction — a `GenericRepository` -every aggregate inherits — or provide only the pieces domains assemble themselves. +영속 플랫폼은 repository 추상 — 모든 aggregate가 상속하는 `GenericRepository` — 을 가질 수도 있고, 도메인이 스스로 +조립할 조각만 줄 수도 있다. -## Decision +## 결정 -The domain owns entities, embeddables, repositories, queries, index requirements, and lock, -soft-delete, and audit policy. The platform provides no generic CRUD repository and no base -repository. `JpaRepositoryFragmentSupport` exists, has no `save`, `findById`, `findAll`, or -`delete`, and is enforced not to acquire them. +엔티티, embeddable, repository, query, index 요구, lock·soft-delete·감사 정책은 도메인이 가진다. 플랫폼은 범용 CRUD +repository도 기반 repository도 주지 않는다. `JpaRepositoryFragmentSupport`는 있지만 `save`, `findById`, `findAll`, `delete`가 +없고, 그것을 얻지 못하게 강제한다. -## Consequences +## 결과 -A generic base repository has one property that looks like a benefit and is not: every aggregate -gets the same operations. That means each aggregate is offered operations that may be wrong for it — -a `delete` on an append-only ledger, a `findAll` on a table that will never be small — and, worse, -one aggregate's later requirement changes the shared base and therefore changes behaviour for -aggregates nobody reviewed. +범용 기반 repository에는 이득처럼 보이지만 이득이 아닌 성질이 하나 있다: 모든 aggregate가 같은 operation을 받는다. 그러면 +aggregate마다 자기에게 틀릴 수 있는 operation을 받게 된다 — append-only 원장의 `delete`, 결코 작지 않을 테이블의 `findAll` — +그리고 더 나쁘게, 한 aggregate의 나중 요구가 공용 기반을 바꾸고 그래서 아무도 리뷰하지 않은 aggregate의 동작을 바꾼다. -Spring Data already implements CRUD. Re-implementing it adds a layer whose only function is to be -harder to opt out of. +Spring Data는 이미 CRUD를 구현한다. 그것을 다시 구현하면 빠져나가기 더 어렵게 만드는 것만이 하는 일인 계층이 더해진다. -The cost is a small amount of repetition: each domain declares the repository interface it needs. -That repetition is the thing that makes each aggregate's persistence surface reviewable. +비용은 약간의 되풀이다: 도메인마다 필요한 repository 인터페이스를 선언한다. 그 되풀이가 aggregate마다 영속 surface를 리뷰할 +수 있게 만든다. -## Enforcement +## 강제 -`JpaArchitectureRules.noGenericRepository()`; `JpaRepositoryFragmentSupportTest`. +`JpaArchitectureRules.noGenericRepository()`, `JpaRepositoryFragmentSupportTest`. diff --git a/docs/adr/ADR-JPA-002-full-transaction-retry.md b/docs/adr/ADR-JPA-002-full-transaction-retry.md index a2491bce..fb5f1e36 100644 --- a/docs/adr/ADR-JPA-002-full-transaction-retry.md +++ b/docs/adr/ADR-JPA-002-full-transaction-retry.md @@ -8,43 +8,39 @@ - 대체됨: `docs/capability-status.md` -# ADR-JPA-002 — Retry re-runs the whole use case +# ADR-JPA-002 — 재시도는 유스케이스 전체를 다시 돌린다 -- Status: Superseded (2026-09-25) — the retry engine this ADR describes - (`FullTransactionRetryCoordinator`, `JpaTransactionExecutor`) was removed. `SpringTransactionPort` - retries nothing; a caller that retries still re-runs the whole use case, which is the part of this - decision that stands. The last commit is in `docs/capability-status.md`. -- Date: 2026-08-11 -- Design: §19.2 +- 상태: 대체됨(2026-09-25) — 이 ADR이 설명하는 재시도 엔진(`FullTransactionRetryCoordinator`, `JpaTransactionExecutor`)은 + 지웠다. `SpringTransactionPort`는 아무것도 재시도하지 않는다. 재시도하는 호출자는 여전히 유스케이스 전체를 다시 돌리고, + 이 결정 중 그 부분이 남는다. 마지막 커밋은 `docs/capability-status.md`에 있다. +- 날짜: 2026-08-11 +- 설계: §19.2 -## Context +## 배경 -Optimistic conflicts, deadlocks, and serialization failures are recoverable. The question is what -unit gets retried: the failed statement, the transaction, or the use case. +낙관적 충돌, 교착, serialization 실패는 회복할 수 있다. 질문은 무엇을 단위로 재시도하느냐다: 실패한 문장, 트랜잭션, 또는 +유스케이스. -## Decision +## 결정 -The whole use case, in a new transaction with a new Persistence Context. -`FullTransactionRetryCoordinator` re-enters `JpaTransactionExecutor` for every attempt, and the -retry advice is ordered outside Spring's transaction advice so each attempt begins a new -transaction. +유스케이스 전체를, 새 Persistence Context를 가진 새 트랜잭션에서. `FullTransactionRetryCoordinator`는 시도마다 +`JpaTransactionExecutor`에 다시 들어가고, 재시도 advice는 Spring 트랜잭션 advice 바깥으로 순서를 잡아 시도마다 새 +트랜잭션을 시작한다. -## Consequences +## 결과 -Statement-level retry is wrong for exactly the failures being retried. An optimistic conflict means -the state the attempt computed against is no longer the committed state; re-issuing the same -statement computes the same wrong answer against a version that has moved on. The domain rules have -to run again over reloaded data, which means the whole use case. +문장 단위 재시도는 바로 재시도하려는 실패에 틀린 답이다. 낙관적 충돌은 시도가 계산의 바탕으로 삼은 상태가 더는 커밋된 +상태가 아니라는 뜻이다. 같은 문장을 다시 내면 이미 움직인 version에 대고 같은 틀린 답을 계산한다. 도메인 규칙은 다시 읽은 +데이터 위에서 다시 돌아야 하고, 그것은 유스케이스 전체라는 뜻이다. -Reusing the Persistence Context would be equally wrong: the second attempt would read the first -attempt's stale entities out of the first-level cache. And with the advice ordering inverted, the -retry loop would run inside one transaction that has already been marked rollback-only, so the -second attempt fails immediately without executing anything. +Persistence Context를 다시 쓰는 것도 똑같이 틀렸다: 두 번째 시도가 1차 cache에서 첫 시도의 낡은 엔티티를 읽게 된다. 그리고 +advice 순서가 뒤집히면 재시도 반복문이 이미 rollback-only로 표시된 트랜잭션 하나 안에서 돌아서, 두 번째 시도가 아무것도 +실행하지 않고 바로 실패한다. -The cost is that a retryable use case must be safe to run from scratch — no irreversible external -effect before the commit. `IrreversibleSideEffectContext` lets a use case declare when that does not -hold, and the policy then refuses to retry it whatever budget remains. +비용은 재시도할 수 있는 유스케이스가 처음부터 돌려도 안전해야 한다는 것이다 — 커밋 전에 되돌릴 수 없는 외부 효과가 없어야 +한다. `IrreversibleSideEffectContext`로 유스케이스가 그렇지 않을 때를 선언할 수 있고, 그러면 정책은 남은 예산이 얼마든 그 +재시도를 거절한다. -## Enforcement +## 강제 -`FullTransactionRetryCoordinatorTest`; `RetryableJpaTransactionInterceptor.DEFAULT_ORDER`. +`FullTransactionRetryCoordinatorTest`, `RetryableJpaTransactionInterceptor.DEFAULT_ORDER`. diff --git a/docs/adr/ADR-JPA-003-completion-unknown.md b/docs/adr/ADR-JPA-003-completion-unknown.md index c283d6db..eef2a271 100644 --- a/docs/adr/ADR-JPA-003-completion-unknown.md +++ b/docs/adr/ADR-JPA-003-completion-unknown.md @@ -7,57 +7,49 @@ - 현재 정본: `docs/jpa/transaction-guide.md` -# ADR-JPA-003 — Completion unknown is never retried +# ADR-JPA-003 — 완료를 모름은 절대 재시도하지 않는다 -- Status: Accepted; amended 2026-09-25 — `TransactionCompletionResolver`, `CommitFailureClassifier` - and the retry engine were removed. The invariant holds because `SpringTransactionPort`, the only - transaction engine, retries nothing; enforcement below is updated accordingly. -- Date: 2026-08-11 -- Design: §17 +- 상태: 채택. 2026-09-25 보완 — `TransactionCompletionResolver`, `CommitFailureClassifier`, 재시도 엔진을 지웠다. 유일한 + 트랜잭션 엔진인 `SpringTransactionPort`가 아무것도 재시도하지 않으므로 불변식이 지켜진다. 아래 강제 절도 그에 맞게 + 고쳤다. +- 날짜: 2026-08-11 +- 설계: §17 -## Context +## 배경 -A connection can break while a commit is in flight. The server may have committed; the -acknowledgement may simply have been lost. The driver cannot tell the two apart. +커밋이 진행 중일 때 연결이 끊길 수 있다. 서버가 커밋했을 수도 있고, 확인 응답만 잃었을 수도 있다. driver는 둘을 구별하지 +못한다. -## Decision +## 결정 -`TransactionCompletionUnknownException` is never retried, automatically or otherwise. It is -produced only by a failure observed while the transaction phase is `COMMITTING`, and only for -SQLSTATE `40003`, a connection-class (`08*`) state, or a transport break. Recovery is -domain-specific reconciliation. +`TransactionCompletionUnknownException`은 자동이든 아니든 절대 재시도하지 않는다. 트랜잭션 단계가 `COMMITTING`인 동안 본 +실패에서만, 그리고 SQLSTATE `40003`, 연결 class(`08*`) 상태, 전송 끊김에 대해서만 만든다. 회복은 도메인별 맞춰 보기다. -## Consequences +## 결과 -Retrying a possibly-committed write is the most damaging thing this platform could do: a duplicate -payment, a duplicate order, a double decrement. There is no budget or backoff that makes it safe, -because the failure is epistemic rather than transient. +커밋됐을지 모르는 쓰기를 재시도하는 것이 이 플랫폼이 할 수 있는 가장 해로운 일이다: 중복 결제, 중복 주문, 두 번 깎기. +실패가 일시적인 것이 아니라 알 수 없는 것이라서, 그것을 안전하게 만드는 예산이나 backoff는 없다. -The invariant is enforced at the type level rather than by policy alone. `JpaFailureContext` refuses -to construct a retryable completion-unknown context, and the exception rebuilds its context through -the safe factory whatever it is handed. A future policy bug therefore cannot produce an unsafe -retry — the value it would need does not exist. +불변식은 정책만이 아니라 타입 수준에서 강제한다. `JpaFailureContext`는 재시도할 수 있는 completion-unknown 문맥을 만들기를 +거절하고, 예외는 무엇을 받든 안전한 factory로 자기 문맥을 다시 만든다. 그래서 나중의 정책 결함이 안전하지 않은 재시도를 낳을 +수 없다 — 그것에 필요한 값이 존재하지 않는다. -The rule is deliberately narrow in the other direction too. Classifying every connection failure as -completion-unknown would push ordinary pool exhaustion and server restarts into the reconciliation -queue, which trains operators to clear that queue without reading it — and then the one entry that -mattered gets cleared with the rest. +규칙은 반대 방향으로도 일부러 좁다. 모든 연결 실패를 completion-unknown으로 분류하면 보통의 pool 고갈과 서버 재시작이 맞춰 +보기 queue로 밀려 들어가고, 그것은 운영자에게 그 queue를 읽지 않고 비우도록 길들인다 — 그러면 중요했던 항목 하나가 나머지와 +함께 지워진다. -The cost is that the domain must supply the resolver. The platform cannot: only the domain knows -which idempotency record, business row, or outbox entry proves the write happened. +비용은 도메인이 resolver를 줘야 한다는 것이다. 플랫폼은 할 수 없다: 어떤 멱등성 레코드, 업무 행, outbox 항목이 쓰기가 +일어났음을 증명하는지는 도메인만 안다. -## Enforcement +## 강제 -Production path: `SpringTransaction` records when the action has returned in a write transaction it -began; a failure after that point goes through -`PersistenceExceptionTranslator#translateCommitFailure`, which builds this exception for `08*`, -`40003`, a vendor termination state (`SqlStateErrorMapping#commitOutcomeUnknownStates`, PostgreSQL -`57P01`/`57P02`) or a transport break. Hibernate's flush inside the commit is not separated from the -COMMIT itself, so a connection lost during that flush is also reported as unknown — the safe side. -Until review 04-01 (2026-11-01) nothing constructed the exception and a commit-phase `08*` reached -callers as the retryable `DB_UNAVAILABLE`. +운영 경로: `SpringTransaction`은 자기가 시작한 쓰기 트랜잭션에서 action이 돌아온 때를 기록한다. 그 뒤의 실패는 +`PersistenceExceptionTranslator#translateCommitFailure`를 거치고, 그것이 `08*`, `40003`, vendor 종료 상태 +(`SqlStateErrorMapping#commitOutcomeUnknownStates`, PostgreSQL `57P01`/`57P02`), 전송 끊김에 대해 이 예외를 만든다. 커밋 안의 +Hibernate flush는 COMMIT 자체와 나뉘지 않으므로, 그 flush 중에 잃은 연결도 모름으로 알린다 — 안전한 쪽이다. review +04-01(2026-11-01) 전까지는 아무것도 이 예외를 만들지 않았고, 커밋 단계의 `08*`가 재시도할 수 있는 `DB_UNAVAILABLE`로 호출자에게 +닿았다. -`JpaFailureContextTest`; `SpringTransactionTest`; `PersistenceExceptionTranslatorTest`; +`JpaFailureContextTest`, `SpringTransactionTest`, `PersistenceExceptionTranslatorTest`, `PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried` -(asserts `DB_COMPLETION_UNKNOWN`; also the `jpa-failure` lane, i.e. release gate -`completion-unknown-no-retry`). +(`DB_COMPLETION_UNKNOWN`을 단언한다. `jpa-failure` lane, 곧 릴리스 gate `completion-unknown-no-retry`이기도 하다). diff --git a/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md b/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md index 63be96de..fbd69256 100644 --- a/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md +++ b/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md @@ -7,41 +7,37 @@ - 현재 정본: `docs/jpa/migration-guide.md` -# ADR-JPA-004 — Flyway is the schema source of truth +# ADR-JPA-004 — schema의 정본은 Flyway다 -- Status: Accepted -- Date: 2026-08-11 -- Design: §31 +- 상태: 채택 +- 날짜: 2026-08-11 +- 설계: §31 -## Context +## 배경 -Hibernate can create and alter schema from the entity mapping. Flyway can apply versioned scripts. -Both cannot own the schema. +Hibernate는 엔티티 대응에서 schema를 만들고 바꿀 수 있다. Flyway는 버전 있는 script를 적용할 수 있다. 둘이 함께 schema를 가질 +수는 없다. -## Decision +## 결정 -Flyway owns every schema change. Hibernate validates and never mutates: `ddl-auto` is `validate` or -`none`, enforced at startup. The runtime database credential holds no DDL privilege, so the rule is -enforced by the server as well as by configuration. +모든 schema 변경은 Flyway가 가진다. Hibernate는 검증만 하고 절대 바꾸지 않는다: `ddl-auto`는 `validate`나 `none`이고, 기동 때 +강제한다. 런타임 데이터베이스 credential에는 DDL 권한이 없으므로, 규칙을 설정만이 아니라 서버도 강제한다. -## Consequences +## 결과 -`ddl-auto=update` fails in a specific and expensive way: it adds but never drops or narrows, so the -result is a schema that is neither the previous one nor the one the mappings describe — produced -silently, by whichever instance started first, with no record of what it did. +`ddl-auto=update`는 구체적이고 비싸게 실패한다: 더하기만 하고 지우거나 좁히지 않아서, 결과는 이전 것도 대응이 설명하는 것도 +아닌 schema다 — 먼저 시작한 인스턴스가 무엇을 했는지 기록도 없이 소리 없이 만든다. -Two credentials rather than one is what makes this more than a convention. A configuration rule can -be overridden by a property; a role without `CREATE` cannot be overridden by anything the -application does. +credential을 하나가 아니라 둘 두는 것이 이것을 관례 이상으로 만든다. 설정 규칙은 속성 하나로 덮을 수 있다. `CREATE`가 없는 +role은 애플리케이션이 무엇을 하든 덮을 수 없다. -Validation fails closed and never repairs. `repair` rewrites the schema history to match the scripts -on disk, which resolves a checksum mismatch by deleting the evidence of which change is missing. +검증은 실패하면 닫히고 절대 고치지 않는다. `repair`는 schema 이력을 디스크의 script에 맞게 다시 쓰는데, 그것은 어떤 변경이 +빠졌는지의 증거를 지워서 checksum 불일치를 푸는 것이다. -The cost is that a schema change requires a migration script and a deployment step. That is the -intended cost: it makes schema change reviewable and reversible. +비용은 schema 변경에 migration script와 배포 단계가 필요하다는 것이다. 그것이 의도한 비용이다: schema 변경을 리뷰할 수 있고 +되돌릴 수 있게 만든다. -## Enforcement +## 강제 -`JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate` (testkit, used by the -migration contract tests); `PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and -`runtime-role-no-ddl`. +`JpaDangerousConfigurationGuard`, `FlywaySchemaPolicy`, `FlywayValidationGate`(testkit, migration 계약 시험이 쓴다), +`PostgreSqlRuntimeRoleVerifier`, 릴리스 gate `flyway-validate`와 `runtime-role-no-ddl`. diff --git a/docs/adr/ADR-JPA-005-postgresql-real-contract.md b/docs/adr/ADR-JPA-005-postgresql-real-contract.md index 116d2487..26223db6 100644 --- a/docs/adr/ADR-JPA-005-postgresql-real-contract.md +++ b/docs/adr/ADR-JPA-005-postgresql-real-contract.md @@ -7,41 +7,36 @@ - 현재 정본: `docs/jpa/support-matrix.md` -# ADR-JPA-005 — Contracts run against real PostgreSQL +# ADR-JPA-005 — 계약은 실제 PostgreSQL에 대고 돈다 -- Status: Accepted -- Date: 2026-08-11 -- Design: §40 +- 상태: 채택 +- 날짜: 2026-08-11 +- 설계: §40 -## Context +## 배경 -An in-memory database makes tests fast and hermetic. A container makes them slow and requires -Docker. +메모리 데이터베이스는 시험을 빠르고 밀폐되게 만든다. container는 느리게 만들고 Docker를 요구한다. -## Decision +## 결정 -Every persistence contract runs against real PostgreSQL 16, 17, and 18 in containers. H2 remains a -local-development convenience and never satisfies a contract. The lanes fail closed when Docker is -absent rather than skipping. +모든 영속 계약은 container 안의 실제 PostgreSQL 16, 17, 18에 대고 돈다. H2는 로컬 개발 편의로 남고 어떤 계약도 만족시키지 +않는다. Docker가 없으면 lane은 건너뛰지 않고 실패하면 닫힌다. -## Consequences +## 결과 -The behaviours these contracts verify either do not exist in H2 or differ there: SQLSTATE values for -the same violation, `FOR UPDATE SKIP LOCKED` semantics, JSONB operators, range types, concurrent -index builds, `search_path` privileges, and the generated SQL for a paged collection fetch. A green -H2 run is evidence that the code compiles and runs — not that any of the above holds. +이 계약이 검증하는 동작은 H2에 없거나 다르다: 같은 위반의 SQLSTATE 값, `FOR UPDATE SKIP LOCKED`의 뜻, JSONB 연산자, 범위 타입, +concurrent index 만들기, `search_path` 권한, page를 나눈 컬렉션 fetch의 생성 SQL. H2 실행이 초록이면 코드가 컴파일되고 돈다는 +증거이지 — 위 어느 것이 지켜진다는 증거가 아니다. -Three versions rather than one because the platform claims three. A contract suite that ran only on -16 would make "Stable on 17 and 18" an assumption. +버전을 하나가 아니라 셋 두는 것은 플랫폼이 셋을 주장하기 때문이다. 16에서만 도는 계약 suite는 「17과 18에서 Stable」을 가정으로 +만든다. -Skipping on missing Docker is the failure mode this decision most wants to avoid: a skipped contract -reports success, and CI eventually inherits that silence. `PostgreSqlContainerFactory.assertDockerAvailable()` -throws instead. +Docker가 없을 때 건너뛰는 것이 이 결정이 가장 피하려는 실패 방식이다: 건너뛴 계약은 성공을 알리고, CI는 결국 그 침묵을 +물려받는다. `PostgreSqlContainerFactory.assertDockerAvailable()`은 대신 던진다. -The cost is that the contract lanes need Docker and take minutes. The unit lane stays hermetic and -fast, and is where most tests live; the container lanes verify the things only a real server can -answer. +비용은 계약 lane에 Docker가 필요하고 몇 분이 걸린다는 것이다. 단위 lane은 밀폐되고 빠른 채로 남고 대부분의 시험이 거기 있다. +container lane은 실제 서버만 답할 수 있는 것을 검증한다. -## Enforcement +## 강제 -`PostgreSqlVersion.stable()`; `PostgreSqlContainerFactory`; release gate `postgresql-contract`. +`PostgreSqlVersion.stable()`, `PostgreSqlContainerFactory`, 릴리스 gate `postgresql-contract`. diff --git a/docs/adr/ADR-JPA-006-canonical-technical-audit.md b/docs/adr/ADR-JPA-006-canonical-technical-audit.md index 80aadd31..476d9ce3 100644 --- a/docs/adr/ADR-JPA-006-canonical-technical-audit.md +++ b/docs/adr/ADR-JPA-006-canonical-technical-audit.md @@ -7,68 +7,58 @@ - 현재 정본: `docs/jpa/repository-adaptation.md` -# ADR-JPA-006 — `audit` is the sole technical audit model +# ADR-JPA-006 — 기술 감사 모델은 `audit` 하나뿐이다 -- Status: Accepted -- Date: 2026-08-24 -- Review: `docs/reviews/2026-08-14-jpa-module-code-review.md` JPA-022 +- 상태: 채택 +- 날짜: 2026-08-24 +- 리뷰: `docs/reviews/2026-08-14-jpa-module-code-review.md` JPA-022 -## Context +## 배경 -Two complete technical-audit mechanisms live in this leaf and they disagree about the schema. +이 leaf에 완전한 기술 감사 장치가 둘 있고, 둘은 schema에 대해 의견이 다르다. -`audit/AuditableEntity` stamps `created_at`/`created_by`/`updated_at`/`updated_by` with an actor -column of length 256, captured through explicit `initializeAudit`/`applyModification` calls and an -`AuditContextPort`. `auditing/AuditMetadata` is a Spring Data embeddable that stamps -`created_*`/`modified_*` with an actor column of length 64, captured by `@CreatedDate` and friends -through an `AuditorAware`. +`audit/AuditableEntity`는 길이 256의 actor 열과 함께 `created_at`/`created_by`/`updated_at`/`updated_by`를 넣고, 명시적인 +`initializeAudit`/`applyModification` 호출과 `AuditContextPort`로 값을 잡는다. `auditing/AuditMetadata`는 길이 64의 actor 열과 +함께 `created_*`/`modified_*`를 넣는 Spring Data embeddable이고, `AuditorAware`를 거쳐 `@CreatedDate` 같은 것으로 값을 잡는다. -Only the first is real: it is what the sample entities extend and what the migrations were written -for. `JpaAuditingConfiguration` is not a Spring `@Configuration`, and nothing in production -constructs any of the three `auditing` types. +실제로 쓰이는 것은 첫째뿐이다: 샘플 엔티티가 상속하는 것이고 migration도 그것을 위해 썼다. `JpaAuditingConfiguration`은 Spring +`@Configuration`이 아니고, 운영 코드의 어떤 것도 `auditing` 타입 셋 중 하나를 만들지 않는다. -The review asked for one canonical model with a migration or activation decision. The failure mode -it was protecting against is specific: an author of a new entity picks whichever package they find -first, and column names, actor lengths and capture lifecycles then diverge per table. +리뷰는 migration이나 켜기 결정이 붙은 정해진 모델 하나를 요구했다. 막으려던 실패 방식은 구체적이다: 새 엔티티를 쓰는 사람이 +먼저 찾은 패키지를 고르고, 그러면 열 이름, actor 길이, 값 잡는 lifecycle이 테이블마다 갈라진다. -## Decision +## 결정 -`audit/AuditableEntity` is canonical and the unused `auditing/*` implementation is removed. +`audit/AuditableEntity`가 정본이고, 쓰지 않는 `auditing/*` 구현은 지운다. -Keeping a complete, incompatible implementation as a dormant candidate created exactly the -ambiguity the review warned about: a new entity could choose a package by autocomplete and silently -change column names, actor bounds and capture lifecycle. A future move to Spring Data auditing is a -migration of the canonical model, not activation of a second model that has drifted beside it. +완전하고 호환되지 않는 구현을 잠든 후보로 두는 것이 바로 리뷰가 경고한 모호함을 만들었다: 새 엔티티가 자동 완성으로 패키지를 +고르고 열 이름, actor 한계, 값 잡는 lifecycle을 소리 없이 바꿀 수 있었다. 나중에 Spring Data auditing으로 옮기는 것은 정본 +모델의 migration이지, 옆에서 어긋나 온 두 번째 모델을 켜는 것이 아니다. -That future migration must preserve `created_*`/`updated_*`, the 256-character actor contract, -`AuditContextPort`, and the shared `Clock`; listener wiring and entity conversion land atomically. +그 나중의 migration은 `created_*`/`updated_*`, 256자 actor 계약, `AuditContextPort`, 공용 `Clock`을 지켜야 한다. listener 배선과 +엔티티 변환은 한 번에 들어온다. -## Consequences +## 결과 -Two audit mechanisms remain readable in one leaf, and a reader has to be told which one is live. -That cost is paid in this document, in the package javadoc and in a test whose name says so. +감사 장치 둘이 한 leaf 안에 읽을 수 있게 남고, 읽는 사람에게 어느 것이 살아 있는지 알려야 한다. 그 비용은 이 문서, 패키지 +javadoc, 그리고 이름이 그것을 말하는 시험이 낸다. -Two failure modes stay silent unless they are asserted, so both are: +단언하지 않으면 소리 없이 남는 실패 방식이 둘 있으므로, 둘 다 단언한다: -- The candidate acquires a stereotype and starts stamping in every deployment that has this module - on the classpath, including the ones whose tables have no `modified_*` columns — where the result - is a failed startup rather than a feature. -- Somebody "harmonises" the two by editing one side's column names, at which point the schema a - deployed table was migrated for and the schema its entity expects diverge with no migration - between them. +- 후보가 stereotype을 얻어 이 모듈이 classpath에 있는 모든 배포에서 값을 넣기 시작한다. 테이블에 `modified_*` 열이 없는 배포도 + 포함된다 — 거기서 결과는 기능이 아니라 기동 실패다. +- 누가 한쪽 열 이름을 고쳐 둘을 「맞춘다」. 그러면 배포된 테이블이 migration된 schema와 그 엔티티가 기대하는 schema가 둘 사이 + migration 없이 갈라진다. -If the candidate is ever promoted, it is promoted atomically: forward migration, sample conversion, -`AuditContextPort → AuditorAware` and `Clock → DateTimeProvider` bridges land together, and this -ADR is superseded rather than amended. +후보를 언젠가 승격하면 한 번에 승격한다: 앞으로 가는 migration, 샘플 변환, `AuditContextPort → AuditorAware`와 +`Clock → DateTimeProvider` 다리가 함께 들어오고, 이 ADR은 보완이 아니라 대체된다. -Bulk and native updates stamp nothing under either mechanism. That is a property of JPA, not of the -choice made here, so it is enforced separately rather than assumed away. +bulk·native update는 어느 장치에서든 아무것도 넣지 않는다. 그것은 여기서 고른 것의 성질이 아니라 JPA의 성질이므로, 없다고 +치지 않고 따로 강제한다. -## Enforcement +## 강제 -`JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism` and -`bulkUpdatesOfAuditedEntitiesStampAudit`, run against the real production graph by -`JpaProductionArchitectureTest` at the composition root — not against fixtures, which is how the -earlier version of this rule pack passed while applying to nothing. `AuditingCandidateStatusTest` -asserts the candidate carries no composing stereotype and that the two column sets stay distinct. -`JpaAuditMechanismRuleTest` exercises the rules' own negative cases. +`JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism`과 `bulkUpdatesOfAuditedEntitiesStampAudit`를 조립 루트의 +`JpaProductionArchitectureTest`가 실제 운영 그래프에 대고 돌린다 — fixture가 아니다. 이 규칙 묶음의 앞 버전은 fixture에 대고 +돌아서 아무것에도 적용되지 않은 채 통과했다. `AuditingCandidateStatusTest`가 후보에 조립하는 stereotype이 없고 두 열 집합이 +따로 남는다고 단언한다. `JpaAuditMechanismRuleTest`가 규칙 자신의 부정 경우를 시험한다. diff --git a/docs/adr/ADR-MONGO-001-platform-boundary.md b/docs/adr/ADR-MONGO-001-platform-boundary.md index 62358927..7da70fc2 100644 --- a/docs/adr/ADR-MONGO-001-platform-boundary.md +++ b/docs/adr/ADR-MONGO-001-platform-boundary.md @@ -7,66 +7,59 @@ - 현재 정본: `docs/mongodb/repository-adaptation.md` -# ADR-MONGO-001 — MongoDB platform boundary +# ADR-MONGO-001 — MongoDB 플랫폼 경계 -- **Status:** Accepted -- **Date:** 2026-08-13 -- **Design source:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6 +- **상태:** 채택 +- **날짜:** 2026-08-13 +- **설계 출처:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6 -## Context +## 배경 -Two failure modes are common when a team wraps MongoDB. +팀이 MongoDB를 감쌀 때 흔한 실패 방식이 둘 있다. -The first is flattening: a shared `CommonMongoRepository` and a generic CRUD facade, which -forces every collection to share an id strategy, a consistency profile and a query surface. MongoDB's -single-document atomicity, aggregation model and change streams stop being reachable, and the first -collection that needs something different gets a cast or a leaky generic. +첫째는 납작하게 만들기다: 공용 `CommonMongoRepository`와 범용 CRUD 창구. 모든 collection이 id 전략, 일관성 profile, +query surface를 같이 쓰게 강요한다. MongoDB의 단일 문서 원자성, aggregation 모델, change stream에 더는 닿을 수 없고, 다른 것이 +필요한 첫 collection은 cast나 새는 제네릭을 받는다. -The second is unrestricted exposure: the driver and `runCommand` available everywhere. Then any -service can drop a collection, run an unbounded pipeline, or issue an admin command from a request -thread, and no review catches it because there is nothing structural to catch. +둘째는 제한 없는 노출이다: driver와 `runCommand`를 어디서나 쓸 수 있다. 그러면 어느 서비스든 요청 스레드에서 collection을 +지우거나, 한계 없는 pipeline을 돌리거나, admin 명령을 낼 수 있고, 구조로 잡을 것이 없으니 어떤 리뷰도 잡지 못한다. -## Decision +## 결정 -The domain owns its documents; the platform owns the cross-cutting decisions. Four exposure planes: +도메인이 자기 문서를 가지고, 플랫폼이 가로지르는 결정을 가진다. 노출 plane 넷: -| Plane | Contents | Client | +| plane | 내용 | client | |---|---|---| -| D1 Standard document persistence | Spring Data repositories, typed queries, mapping manifest, atomic update primitives, optimistic revision | Stable API V1, `apiStrict=true` | -| D2 Advanced document operations | `MongoTemplate`, transactions/sessions, bulk, aggregation, keyset cursors, change streams | Stable API V1, `apiStrict=true` | -| D3 Explicit Mongo capability | Native BSON, time series, search/vector, CSFLE/QE, shard-aware operations | Separate capability client | -| D4 Admin plane | Collection, validator, index, migration, shard, repair | Separate admin client and credential | +| D1 표준 문서 영속 | Spring Data repository, 타입 있는 query, 대응 manifest, 원자 update 기본 장치, 낙관적 revision | Stable API V1, `apiStrict=true` | +| D2 고급 문서 연산 | `MongoTemplate`, 트랜잭션·세션, bulk, aggregation, keyset cursor, change stream | Stable API V1, `apiStrict=true` | +| D3 명시적 Mongo capability | native BSON, time series, search·vector, CSFLE·QE, shard를 아는 연산 | 따로 둔 capability client | +| D4 admin plane | collection, validator, index, migration, shard, repair | 따로 둔 admin client와 credential | -Specifically: +구체적으로: -1. **No `CommonMongoRepository`.** Each aggregate declares its own repository. -2. **D1/D2 run on Stable API V1 with `apiStrict=true`,** so a command outside the versioned API fails - at development time instead of on the next server upgrade. -3. **D3 is not a raw-client escape.** Every call passes a fixed admission order: capability registered - → database profile → collection allowlist → operation name → timeout → consistency profile → - result limit → trace → redaction → command category → admin-command refusal → execute. -4. **D4 is a separate client with a separate credential.** No application-plane path reaches it; - `PolicyAwareMongoNativeGateway` refuses admin-category commands regardless of capability. -5. **Advanced and Experimental capabilities are opt-in modules**, never transitive dependencies of the - Stable surface. +1. **`CommonMongoRepository`가 없다.** aggregate마다 자기 repository를 선언한다. +2. **D1·D2는 `apiStrict=true`인 Stable API V1에서 돈다.** 그래서 버전 있는 API 밖의 명령은 다음 서버 업그레이드 때가 아니라 + 개발 때 실패한다. +3. **D3는 raw client로 빠져나가는 길이 아니다.** 모든 호출이 정해진 허가 순서를 지난다: capability 등록 → 데이터베이스 + profile → collection 허용 목록 → operation 이름 → timeout → 일관성 profile → 결과 한계 → trace → 가리기 → 명령 category → + admin 명령 거절 → 실행. +4. **D4는 따로 둔 credential을 가진 따로 둔 client다.** 애플리케이션 plane 경로는 그것에 닿지 않는다. + `PolicyAwareMongoNativeGateway`는 capability와 관계없이 admin category 명령을 거절한다. +5. **Advanced와 Experimental capability는 골라 쓰는 모듈이고**, Stable surface의 전이 의존이 되지 않는다. -## Consequences +## 결과 -**Positive.** MongoDB's semantics stay reachable. Misuse is refused structurally rather than reviewed -for. A server upgrade cannot silently change D1/D2 behaviour. Admin operations have their own audit -trail and credential. +**좋은 점.** MongoDB의 뜻에 계속 닿을 수 있다. 잘못된 사용은 리뷰로 찾지 않고 구조로 거절한다. 서버 업그레이드가 D1·D2 +동작을 소리 없이 바꿀 수 없다. admin 연산은 자기 감사 흔적과 credential을 가진다. -**Negative.** Every operation needs a registered name and profile, so a new query is a small amount of -configuration rather than zero. A genuinely new capability requires a registration before it can be -used. Both are deliberate: the cost is paid once per operation, at review time. +**나쁜 점.** 모든 operation에 등록된 이름과 profile이 필요해서, 새 query에는 0이 아니라 약간의 설정이 든다. 정말 새 capability는 +쓰기 전에 등록이 필요하다. 둘 다 일부러다: 비용은 operation마다 한 번, 리뷰 때 낸다. -**Rejected alternative — "expose the driver, rely on code review."** Review does not scale to every -query in every service, and the operations that matter (unbounded pipeline, `dropCollection`, -unanchored regex on user input) look unremarkable in a diff. +**버린 대안 — 「driver를 내놓고 코드 리뷰에 기댄다」.** 리뷰는 모든 서비스의 모든 query로 늘어나지 못하고, 중요한 연산 +(한계 없는 pipeline, `dropCollection`, 사용자 입력에 대한 anchor 없는 정규식)은 diff에서 눈에 띄지 않는다. -## Repository adaptation +## 저장소에 맞추기 -The design assumes 19 Gradle modules under `modules/mongodb/`. This repository's fail-closed registry -declares exactly 19 leaf identities, so the modules became package boundaries inside -`:adapter:outbound:persistence-mongo`, enforced by ArchUnit. See -[docs/mongodb/repository-adaptation.md](../mongodb/repository-adaptation.md). +설계는 `modules/mongodb/` 아래 Gradle 모듈 19개를 가정한다. 이 저장소의 실패하면 닫히는 registry는 정확히 19개의 leaf identity를 +선언하므로, 그 모듈들은 `:adapter:outbound:persistence-mongo` 안의 패키지 경계가 됐고 ArchUnit이 강제한다. +[docs/mongodb/repository-adaptation.md](../mongodb/repository-adaptation.md)를 본다. diff --git a/docs/adr/ADR-MONGO-002-bson-representation.md b/docs/adr/ADR-MONGO-002-bson-representation.md index 73e478a7..a53a5915 100644 --- a/docs/adr/ADR-MONGO-002-bson-representation.md +++ b/docs/adr/ADR-MONGO-002-bson-representation.md @@ -7,61 +7,53 @@ - 현재 정본: `docs/mongodb/bson-mapping-guide.md` -# ADR-MONGO-002 — BSON representation is a pinned manifest +# ADR-MONGO-002 — BSON 표현은 고정한 manifest다 -- **Status:** Accepted -- **Date:** 2026-08-13 -- **Design source:** design §10, decision D-06 +- **상태:** 채택 +- **날짜:** 2026-08-13 +- **설계 출처:** 설계 §10, 결정 D-06 -## Context +## 배경 -How a Java value is represented in BSON is a data contract, but nothing in the default toolchain -treats it as one. Spring Data and the MongoDB driver both have defaults, and those defaults have -changed across versions. A `BigDecimal` can land as a `Double`, a `String` or a `Decimal128`; a `UUID` -can land as `Binary` subtype 3 or subtype 4; an `Instant` can land as a `Date` or a `String`. +Java 값을 BSON으로 어떻게 나타내는지는 데이터 계약인데, 기본 toolchain의 어떤 것도 그것을 계약으로 다루지 않는다. Spring Data와 +MongoDB driver에는 둘 다 기본값이 있고, 그 기본값은 버전마다 바뀌어 왔다. `BigDecimal`은 `Double`, `String`, `Decimal128` 중 +무엇으로든 들어갈 수 있다. `UUID`는 `Binary` subtype 3이나 subtype 4로 들어갈 수 있다. `Instant`는 `Date`나 `String`으로 들어갈 +수 있다. -The consequences are asymmetric. A representation change is invisible in a value-equality test — -`12.30` looks like `12.30` whether it is a double or a `Decimal128` — but once a collection holds -production data, changing it is a full migration. And the UUID case is worse than a migration: legacy -Java representation byte-swaps two halves of the UUID, so a document written under one representation -and read under the other yields a *different, valid-looking* UUID. Nothing errors. You get the wrong -record. +결과는 비대칭이다. 표현이 바뀌어도 값 동등 시험에는 보이지 않는다 — `12.30`은 double이든 `Decimal128`이든 `12.30`처럼 보인다 — +하지만 collection에 운영 데이터가 들면 그것을 바꾸는 것은 전체 migration이다. 그리고 UUID 경우는 migration보다 나쁘다: 옛 Java +표현은 UUID의 두 절반을 byte-swap하므로, 한 표현으로 쓰고 다른 표현으로 읽은 문서는 *다르지만 유효해 보이는* UUID를 낸다. +오류는 없다. 엉뚱한 레코드를 받는다. -## Decision +## 결정 -`MongoTypeRepresentationManifest` pins the representation for every type the platform maps, and -`MongoMappingConfiguration` builds the Spring Data converters from it. Nothing relies on a library -default. +`MongoTypeRepresentationManifest`가 플랫폼이 대응시키는 모든 타입의 표현을 고정하고, `MongoMappingConfiguration`이 그것으로 +Spring Data converter를 만든다. 라이브러리 기본값에 기대는 것은 없다. -| Java | BSON | Rationale | +| Java | BSON | 근거 | |---|---|---| -| `UUID` | `Binary` subtype 4 (`STANDARD`) | Subtype 3 byte-swaps; cross-representation reads are silently wrong. | -| `BigDecimal` | `Decimal128` | A double cannot represent `12.30`; money compared as a double is eventually wrong by a cent. | -| `BigInteger` | `Decimal128`, or declared `String` when out of range | 34 significant digits; out of range fails on write instead of rounding. | -| `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | One instant, one representation. | -| `LocalDate` | declared per field | A calendar day is not an instant. | -| `LocalDateTime` | **refused** | No offset: the stored value depends on the writing JVM's default zone. | -| `enum` | `String` name | Ordinals renumber when someone inserts a constant. | +| `UUID` | `Binary` subtype 4(`STANDARD`) | subtype 3은 byte-swap한다. 표현을 넘나드는 읽기는 소리 없이 틀린다. | +| `BigDecimal` | `Decimal128` | double은 `12.30`을 나타내지 못한다. double로 비교한 돈은 결국 1원씩 틀린다. | +| `BigInteger` | `Decimal128`, 범위를 넘으면 선언한 `String` | 유효 숫자 34자리. 범위를 넘으면 반올림하지 않고 쓰기에서 실패한다. | +| `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | 시각 하나, 표현 하나. | +| `LocalDate` | 필드마다 선언 | 달력의 날은 시각이 아니다. | +| `LocalDateTime` | **거절** | offset이 없다: 저장 값이 쓰는 JVM의 기본 시간대에 따라 달라진다. | +| `enum` | `String` 이름 | 누가 상수를 끼워 넣으면 ordinal이 다시 매겨진다. | -Type metadata follows `MongoTypeMetadataPolicy` — `NONE`, `ALIAS` or `CLASS_NAME`. A -`@LongLivedMongoDocument` type may not use `CLASS_NAME`: writing a FQCN into a million documents makes -a package rename a data migration. +타입 metadata는 `MongoTypeMetadataPolicy` — `NONE`, `ALIAS`, `CLASS_NAME` — 를 따른다. `@LongLivedMongoDocument` 타입은 +`CLASS_NAME`을 쓰면 안 된다: 문서 백만 개에 FQCN을 쓰면 패키지 이름 바꾸기가 데이터 migration이 된다. -The manifest is enforced by a golden gate. `MongoBsonSnapshot` canonicalises a stored document, -preserving BSON types and keeping missing distinct from null, and -`MongoBsonSnapshotAssert.hasTypeSignature(...)` fails on any representation change. The registry -pins `UuidCodec(STANDARD)` explicitly rather than inheriting a default, since inheriting the default -is the exact drift the gate exists to catch. +manifest는 golden gate가 강제한다. `MongoBsonSnapshot`이 저장된 문서를 정규화하면서 BSON 타입을 지키고 없음과 null을 구별해 +두며, `MongoBsonSnapshotAssert.hasTypeSignature(...)`가 표현이 바뀌면 실패한다. registry는 기본값을 물려받지 않고 +`UuidCodec(STANDARD)`를 명시해 고정한다. 기본값을 물려받는 것이 바로 gate가 잡으려는 어긋남이기 때문이다. -## Consequences +## 결과 -**Positive.** A library upgrade cannot move a representation without failing a test. Money is exact. -UUIDs read back as themselves. Class moves stay refactors. +**좋은 점.** 라이브러리 업그레이드가 시험을 실패시키지 않고 표현을 옮길 수 없다. 돈이 정확하다. UUID가 자기 자신으로 다시 +읽힌다. 클래스 옮기기는 리팩터링으로 남는다. -**Negative.** Every representation-affecting change requires updating a snapshot *and* writing a -migration. A new mapped type needs a manifest entry before it can be used. This is the intended -friction: the alternative is discovering the change in production. +**나쁜 점.** 표현에 영향을 주는 모든 변경에 snapshot 갱신 *그리고* migration 작성이 필요하다. 새로 대응시키는 타입은 쓰기 전에 +manifest 항목이 필요하다. 의도한 마찰이다: 대안은 운영에서 변경을 발견하는 것이다. -**Rejected alternative — "snapshot the JSON."** JSON destroys exactly the distinctions the gate -protects: `Decimal128` and `String` both render as text, `Binary` UUID and `ObjectId` both render as -hex, and missing and null both disappear. +**버린 대안 — 「JSON을 snapshot한다」.** JSON은 gate가 지키는 바로 그 구별을 없앤다: `Decimal128`과 `String`은 둘 다 글로 +나오고, `Binary` UUID와 `ObjectId`는 둘 다 hex로 나오며, 없음과 null은 둘 다 사라진다. diff --git a/docs/adr/ADR-MONGO-003-transaction-retry.md b/docs/adr/ADR-MONGO-003-transaction-retry.md index 7d675461..ec655164 100644 --- a/docs/adr/ADR-MONGO-003-transaction-retry.md +++ b/docs/adr/ADR-MONGO-003-transaction-retry.md @@ -7,33 +7,29 @@ - 현재 정본: `docs/mongodb/consistency-transaction-guide.md` -# ADR-MONGO-003 — Transaction body retry and commit retry are separate loops +# ADR-MONGO-003 — 트랜잭션 본문 재시도와 커밋 재시도는 따로 도는 반복문이다 -- **Status:** Accepted -- **Date:** 2026-08-13 -- **Design source:** design §14–§16, decisions D-07 through D-10 +- **상태:** 채택 +- **날짜:** 2026-08-13 +- **설계 출처:** 설계 §14–§16, 결정 D-07부터 D-10 -## Context +## 배경 -MongoDB reports two transaction failures that look similar and must be handled in opposite ways. +MongoDB는 비슷해 보이지만 정반대로 다뤄야 하는 트랜잭션 실패 둘을 알린다. -`TransientTransactionError` means the transaction definitively did not commit. The correct response is -to run the whole thing again. +`TransientTransactionError`는 트랜잭션이 분명히 커밋되지 않았다는 뜻이다. 맞는 대응은 전체를 다시 돌리는 것이다. -`UnknownTransactionCommitResult` means the commit **may already have applied** — typically because the -primary changed while the commit was in flight. The correct response is to retry *the commit*, which -is a no-op if it already succeeded. +`UnknownTransactionCommitResult`는 커밋이 **이미 적용됐을 수 있다**는 뜻이다 — 보통 커밋이 진행 중일 때 primary가 바뀌었기 +때문이다. 맞는 대응은 *커밋*을 재시도하는 것이고, 이미 성공했다면 그것은 아무 일도 하지 않는다. -The common implementation wraps everything in one retry loop. That loop replays the body after an -unknown commit, and if the commit did apply, the body applies twice. In a payment or notification path -that is a duplicate charge or a duplicate message, produced by the error handler. +흔한 구현은 모든 것을 재시도 반복문 하나로 감싼다. 그 반복문은 모르는 커밋 뒤에 본문을 다시 돌리고, 커밋이 적용됐었다면 본문이 +두 번 적용된다. 결제나 알림 경로에서 그것은 오류 handler가 만든 중복 청구나 중복 메시지다. -The related trap is session reuse: retrying on the same session after an abort carries the aborted -transaction's state into the retry. +관련된 함정은 세션 다시 쓰기다: abort 뒤에 같은 세션으로 재시도하면 abort된 트랜잭션의 상태가 재시도로 넘어간다. -## Decision +## 결정 -`MongoTransactionRetryCoordinator` implements two loops with different scopes. +`MongoTransactionRetryCoordinator`가 범위가 다른 반복문 둘을 구현한다. ``` for each body attempt within the budget: @@ -44,34 +40,30 @@ for each body attempt within the budget: UnknownTransactionCommitResult -> retry the COMMIT ONLY, same session ``` -Rules that follow, all of them load-bearing: +따라 나오는 규칙. 모두 꼭 필요하다: -1. **A new session per body attempt.** No aborted state leaks into a retry. -2. **The body is never replayed after a commit ambiguity.** `MongoRetryScope.COMMIT_ONLY` is a - distinct value from `BODY` precisely so this cannot be collapsed by accident. -3. **One budget bounds both loops.** `MongoRetryBudget` limits attempts *and* elapsed time, with - jittered backoff, so a struggling primary is not retried into the ground by every instance at once. -4. **An exhausted commit retry surfaces `TRANSACTION_COMMIT_UNKNOWN`,** never a generic failure. An - ambiguous outcome reported as a failure invites the caller to retry — the one thing that must not - happen. See [docs/mongodb/runbooks/unknown-commit.md](../mongodb/runbooks/unknown-commit.md). -5. **Transaction bodies write a deterministic marker** so `MongoCommitReconciler` can establish what - actually happened. A transaction that cannot be reconciled has no recovery path. -6. **Classification reads labels before codes.** Server error labels are the authoritative statement - about retryability; error codes vary by version. +1. **본문 시도마다 새 세션.** abort된 상태가 재시도로 새지 않는다. +2. **커밋이 모호해진 뒤에는 본문을 절대 다시 돌리지 않는다.** `MongoRetryScope.COMMIT_ONLY`가 `BODY`와 다른 값인 것은 바로 + 이것이 실수로 뭉개지지 않게 하려는 것이다. +3. **예산 하나가 두 반복문을 묶는다.** `MongoRetryBudget`이 시도 수 *그리고* 흐른 시간을 jitter 있는 backoff와 함께 제한한다. + 그래서 힘든 primary를 모든 인스턴스가 한꺼번에 재시도로 짓밟지 않는다. +4. **바닥난 커밋 재시도는 일반 실패가 아니라 `TRANSACTION_COMMIT_UNKNOWN`으로 드러난다.** 실패로 알린 모호한 결과는 호출자에게 + 재시도를 부른다 — 일어나면 안 되는 바로 그 일이다. + [docs/mongodb/runbooks/unknown-commit.md](../mongodb/runbooks/unknown-commit.md)를 본다. +5. **트랜잭션 본문은 결정적인 표지를 쓴다.** 그래서 `MongoCommitReconciler`가 실제로 무엇이 일어났는지 세울 수 있다. 맞춰 볼 수 + 없는 트랜잭션에는 회복 길이 없다. +6. **분류는 코드보다 label을 먼저 읽는다.** 서버 오류 label이 재시도 가능성에 대한 정본 진술이고, 오류 코드는 버전마다 다르다. -Surrounding decisions that reduce how often this path is reached at all: single-document atomic -operations are preferred over transactions (D-09), partial changes use update operators rather than -`save()` (D-07), and whole-document replacement requires an optimistic revision (D-08). +이 경로에 닿는 횟수 자체를 줄이는 주변 결정: 트랜잭션보다 단일 문서 원자 연산을 고른다(D-09), 부분 변경은 `save()`가 아니라 +update 연산자를 쓴다(D-07), 문서 전체 바꾸기에는 낙관적 revision이 필요하다(D-08). -## Consequences +## 결과 -**Positive.** A commit ambiguity cannot become a duplicate effect. The ambiguity reaches the caller as -an ambiguity. The retry budget is bounded in both attempts and time. +**좋은 점.** 커밋 모호함이 중복 효과가 될 수 없다. 모호함이 모호함으로 호출자에게 닿는다. 재시도 예산이 시도 수와 시간 둘 다에서 +한계를 가진다. -**Negative.** Callers must handle a third outcome beyond success and failure. Transaction bodies must -write a marker they would not otherwise need. Both costs are small compared with reconciling -duplicated financial effects after the fact. +**나쁜 점.** 호출자는 성공과 실패 밖의 세 번째 결과를 다뤄야 한다. 트랜잭션 본문은 그렇지 않으면 필요 없을 표지를 써야 한다. 두 +비용 모두 중복된 금전 효과를 나중에 맞춰 보는 것에 비하면 작다. -**Rejected alternative — "one retry loop, at-least-once everywhere."** It requires every transaction -body to be fully idempotent, which is a much stronger and much less checkable property than writing -one marker, and it is silently violated the first time someone adds a non-idempotent step. +**버린 대안 — 「재시도 반복문 하나, 어디서나 at-least-once」.** 모든 트랜잭션 본문이 완전히 멱등이어야 한다. 표지 하나를 쓰는 +것보다 훨씬 강하고 훨씬 검사하기 어려운 성질이고, 누가 멱등이 아닌 단계를 처음 더하는 순간 소리 없이 깨진다. diff --git a/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md b/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md index eeb2896c..f26ca08d 100644 --- a/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md +++ b/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md @@ -7,65 +7,55 @@ - 현재 정본: `docs/mongodb/schema-index-migration-guide.md` -# ADR-MONGO-004 — Index and schema changes belong to the admin plane +# ADR-MONGO-004 — index와 schema 변경은 admin plane의 것이다 -- **Status:** Accepted -- **Date:** 2026-08-13 -- **Design source:** design §21–§25, decisions D-11, D-13 +- **상태:** 채택 +- **날짜:** 2026-08-13 +- **설계 출처:** 설계 §21–§25, 결정 D-11, D-13 -## Context +## 배경 -Spring Data can create indexes automatically from annotations. On a laptop this is convenient. On a -collection with a hundred million documents, an index build is a capacity event: it consumes CPU, IO -and memory on the primary for minutes to hours, and it starts because a pod restarted. +Spring Data는 애너테이션에서 index를 자동으로 만들 수 있다. 노트북에서는 편하다. 문서 1억 개가 든 collection에서 index 만들기는 +용량 사건이다: primary의 CPU, IO, 메모리를 몇 분에서 몇 시간 동안 쓰고, pod 하나가 재시작했다는 이유로 시작된다. -Worse, it starts N times when N pods restart, and there is no approval step, no ordering relative to -the code that needs the index, and no record afterwards of what was created. +더 나쁘게, pod N개가 재시작하면 N번 시작하고, 승인 단계도, 그 index가 필요한 코드와의 순서도, 나중에 무엇을 만들었는지의 기록도 +없다. -Schema validators have the same shape with a sharper edge: tightening a validator on a collection with -existing data rejects writes to documents that were legal when they were written. +schema validator도 같은 모양인데 날이 더 서 있다: 데이터가 있는 collection에서 validator를 조이면, 쓸 때는 적법했던 문서에 대한 +쓰기를 거절한다. -TTL has a third shape. It looks like a scheduler and is not one: the TTL monitor runs about once a -minute and deletes in batches, so an expired document routinely remains readable for minutes or hours. +TTL은 세 번째 모양이다. scheduler처럼 보이지만 아니다: TTL monitor는 대략 1분에 한 번 돌고 batch로 지우므로, 만료된 문서가 몇 +분에서 몇 시간 동안 읽히는 것이 예사다. -## Decision +## 결정 -**Indexes and validators are declared in a manifest and applied by the admin plane (D4).** Automatic -index creation in production is disabled. +**index와 validator는 manifest에 선언하고 admin plane(D4)이 적용한다.** 운영에서 자동 index 만들기는 끈다. -1. `MongoManifestRegistry` holds the declared indexes (`MongoIndexManifest`) and validator - (`MongoSchemaManifest`) per collection. The manifest is the source of truth, reviewed in a pull - request. -2. `MongoIndexDiffEngine` compares manifest against observed state and reports missing, extra and - *changed* indexes. Changed ones are reported rather than re-issued: MongoDB will not silently - rebuild an index whose definition moved. -3. `MongoIndexApplyPolicy` sets what an environment may do — `APPLY` (local), `APPLY_WITH_DIFF` - (staging), `DIFF_WITH_APPROVED_APPLY` (production), `REPORT_ONLY` (audit). -4. **Ownership gates every drop.** `MongoMetadataOwnership` distinguishes `APPLICATION_MANAGED` from - `SEARCH_MANAGED`, `ENCRYPTION_MANAGED` and `EXTERNAL`. Only application-managed objects are - droppable on drift. A diff engine without ownership eventually proposes dropping - `enxcol_.customers.esc`, and "the drift tool cleaned it up" is a very bad incident summary. -5. **Retirement is staged.** `MongoIndexRetirementState` moves an index declared → hidden → - observed-unused → droppable, one deployment per transition. Hiding is instantly reversible; - dropping is a rebuild. -6. **Stable validation actions are `error` and `warn` only.** `errorAndLog` is not part of the Stable - contract on 7.0 or 8.0 and is refused. Tightening goes `warn`+`MODERATE` → confirm zero warnings → - `error`+`STRICT`, in two deployments. -7. **TTL is physical cleanup only** (D-13). `MongoExpirationAccessPolicy` states the rule: a - document's presence is not authorization and its absence is not a deadline. Access control checks - the expiry field; scheduling uses a scheduler. -8. **Migrations are checksummed, locked, precondition-checked and resumable.** - `MongoMigrationRunner` fails hard when an applied id's checksum changed — two environments running - different code under one id is worse than a failed deploy. +1. `MongoManifestRegistry`가 collection마다 선언한 index(`MongoIndexManifest`)와 validator(`MongoSchemaManifest`)를 가진다. + manifest가 정본이고 pull request에서 리뷰한다. +2. `MongoIndexDiffEngine`이 manifest를 관찰한 상태와 비교해 빠진 index, 남는 index, *바뀐* index를 알린다. 바뀐 것은 다시 내지 + 않고 알린다: MongoDB는 정의가 움직인 index를 소리 없이 다시 만들지 않는다. +3. `MongoIndexApplyPolicy`가 환경이 할 수 있는 것을 정한다 — `APPLY`(로컬), `APPLY_WITH_DIFF`(staging), + `DIFF_WITH_APPROVED_APPLY`(운영), `REPORT_ONLY`(감사). +4. **모든 drop은 소유권이 막는다.** `MongoMetadataOwnership`이 `APPLICATION_MANAGED`를 `SEARCH_MANAGED`, `ENCRYPTION_MANAGED`, + `EXTERNAL`과 구별한다. 어긋났을 때 지울 수 있는 것은 애플리케이션이 관리하는 객체뿐이다. 소유권 없는 diff 엔진은 결국 + `enxcol_.customers.esc`를 지우자고 제안하고, 「drift 도구가 치웠다」는 아주 나쁜 사고 요약이다. +5. **은퇴는 단계를 밟는다.** `MongoIndexRetirementState`가 index를 선언됨 → 숨김 → 안 쓰는 것 확인 → 지울 수 있음으로 옮기고, + 전이마다 배포 한 번이다. 숨기기는 바로 되돌릴 수 있다. 지우기는 다시 만들기다. +6. **Stable validation action은 `error`와 `warn`뿐이다.** `errorAndLog`는 7.0이나 8.0에서 Stable 계약에 속하지 않아 거절한다. + 조이기는 `warn`+`MODERATE` → 경고 0 확인 → `error`+`STRICT`로, 배포 두 번에 걸쳐 간다. +7. **TTL은 물리적 치우기일 뿐이다**(D-13). `MongoExpirationAccessPolicy`가 규칙을 말한다: 문서가 있다고 인가가 아니고, 없다고 + 기한이 아니다. 접근 통제는 만료 필드를 검사하고, 일정은 scheduler를 쓴다. +8. **migration은 checksum을 두고, 잠그고, 전제 조건을 검사하고, 이어서 할 수 있다.** `MongoMigrationRunner`는 적용한 id의 + checksum이 바뀌면 단단히 실패한다 — 두 환경이 id 하나 아래 다른 코드를 돌리는 것은 실패한 배포보다 나쁘다. -## Consequences +## 결과 -**Positive.** Index builds are scheduled by people who know the capacity. Rollback is possible at -every step. Drift is visible without being dangerous. Nothing drops what it does not own. +**좋은 점.** index 만들기 일정은 용량을 아는 사람이 잡는다. 모든 단계에서 되돌릴 수 있다. drift는 위험하지 않게 보인다. 아무것도 +자기가 가지지 않은 것을 지우지 않는다. -**Negative.** Adding an index is a manifest change plus an apply, not an annotation. Local development -uses `APPLY` so the friction is confined to environments where it is warranted. +**나쁜 점.** index 더하기는 애너테이션이 아니라 manifest 변경 + 적용이다. 로컬 개발은 `APPLY`를 쓰므로 마찰은 그것이 정당한 +환경에만 머문다. -**Rejected alternative — "auto-create with a feature flag."** The flag is either on in production, -which is the problem, or off, in which case the manifest is the real mechanism and the annotation is a -second, divergent source of truth. +**버린 대안 — 「feature flag와 함께 자동으로 만들기」.** flag가 운영에서 켜져 있으면 그것이 문제이고, 꺼져 있으면 manifest가 +실제 장치이고 애너테이션은 두 번째의 갈라진 정본이다. diff --git a/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md b/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md index 9b3bc6b3..1ac930b9 100644 --- a/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md +++ b/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md @@ -7,90 +7,78 @@ - 현재 정본: `docs/mongodb/support-matrix.md` -# ADR-MONGO-ADV-001 — Advanced capability promotion +# ADR-MONGO-ADV-001 — Advanced capability 승격 -- **Status:** Accepted -- **Date:** 2026-08-13 -- **Design source:** design §2 (D-15), §3.2–§3.3; Advanced expansion plan Task 15 -- **Amended 2026-09-25:** the `ca-skeleton.persistence-mongo.advanced.*.enabled` binding - (`MongoAdvancedConfiguration`/`MongoAdvancedSettings`) was imported by nothing, so no deployment - property ever reached the flags; it was removed together with `propertyFor`. The flags are now - built in code by the adapter that constructs an entry point. `MongoAdvancedPromotionGate`, - `MongoAdvancedPromotionEvidence`, `MongoVectorSearchBenchmarkGate` and the search, vector, time - series and GridFS packages (interfaces with no implementation) were removed. The evidence - categories below remain a review obligation; no class checks them. +- **상태:** 채택 +- **날짜:** 2026-08-13 +- **설계 출처:** 설계 §2 (D-15), §3.2–§3.3. Advanced 확장 계획 Task 15 +- **2026-09-25 보완:** `ca-skeleton.persistence-mongo.advanced.*.enabled` 바인딩(`MongoAdvancedConfiguration`/ + `MongoAdvancedSettings`)은 아무것도 import하지 않아서 어떤 배포 속성도 flag에 닿지 않았다. `propertyFor`와 함께 지웠다. flag는 + 이제 entry point를 만드는 어댑터가 코드로 만든다. `MongoAdvancedPromotionGate`, `MongoAdvancedPromotionEvidence`, + `MongoVectorSearchBenchmarkGate`, 그리고 search, vector, time series, GridFS 패키지(구현 없는 인터페이스)를 지웠다. 아래 증거 + category는 리뷰 의무로 남는다. 그것을 검사하는 클래스는 없다. -## Context +## 배경 -Sharding, time series, CSFLE, Queryable Encryption, search, vector search and multi-tenancy each work -in a demo within an afternoon. What they do not do is behave the same way in production, and the -differences are not discovered by functional tests: +sharding, time series, CSFLE, Queryable Encryption, search, vector search, multi-tenancy는 하나같이 오후 한나절이면 demo에서 +동작한다. 하지 않는 것은 운영에서 같은 방식으로 동작하는 것이고, 그 차이는 기능 시험으로 찾지 못한다: -- Sharding changes which queries are efficient. A query that misses the shard key becomes - scatter-gather, which passes every test on a one-shard cluster. -- Encryption's failure modes are KMS failure modes — wrong key, revoked permission, mid-rotation — - none of which occur against a local key provider. -- Search and vector search can be functionally correct and useless: the index returns results, and - the results are not relevant. Recall is not visible in a pass/fail assertion. -- Database-per-tenant works until the tenant count crosses what the connection and file-handle - budget supports, which is an operational property, not a code property. +- sharding은 어떤 query가 효율적인지 바꾼다. shard key를 놓친 query는 scatter-gather가 되는데, shard 하나짜리 cluster에서는 + 모든 시험을 통과한다. +- 암호화의 실패 방식은 KMS의 실패 방식이다 — 틀린 키, 거둬들인 권한, 교체 중 — 로컬 키 provider에 대고는 하나도 일어나지 않는다. +- search와 vector search는 기능상 맞으면서 쓸모없을 수 있다: index는 결과를 돌려주는데 결과가 관련이 없다. recall은 통과·실패 + 단언에 보이지 않는다. +- 테넌트마다 데이터베이스는 테넌트 수가 연결·파일 handle 예산이 받쳐 주는 수를 넘을 때까지 동작한다. 그것은 코드가 아니라 운영의 + 성질이다. -The failure mode this ADR prevents is a capability marked "done" on the strength of a green test that -never touched the environment where it will run. +이 ADR이 막는 실패 방식은 그것이 돌 환경을 한 번도 건드리지 않은 초록 시험을 근거로 capability를 「끝남」으로 표시하는 것이다. -## Decision +## 결정 -Every Advanced and Experimental capability is an **opt-in module behind its own flag**, and promotion -requires evidence, not confidence. +모든 Advanced·Experimental capability는 **자기 flag 뒤의 골라 쓰는 모듈**이고, 승격에는 자신감이 아니라 증거가 필요하다. -### Enablement +### 켜기 -`MongoAdvancedCapabilityFlags` gates construction of every Advanced entry point. A disabled capability -does not produce a runtime warning — the type refuses to be constructed, naming the property that -enables it (`MongoAdvancedCapabilityFlags.propertyFor(capability)`). Being on the classpath is not -being enabled, and `stableNeverDependsOnAdvanced` (ArchUnit) keeps the Stable surface free of them. +`MongoAdvancedCapabilityFlags`가 모든 Advanced entry point의 생성을 막는다. 꺼진 capability는 런타임 경고를 내지 않는다 — 타입이 +그것을 켜는 속성 이름을 대며 만들어지기를 거절한다(`MongoAdvancedCapabilityFlags.propertyFor(capability)`). classpath에 있다고 +켜진 것이 아니고, `stableNeverDependsOnAdvanced`(ArchUnit)가 Stable surface에서 그것을 떼어 둔다. -### Promotion evidence +### 승격 증거 -`MongoAdvancedPromotionGate.verify(evidence)` requires every category: +`MongoAdvancedPromotionGate.verify(evidence)`는 모든 category를 요구한다: -| Category | Means | +| category | 뜻 | |---|---| -| `stable-platform` | The Stable release gate passed on the same revision. | -| `actual-topology` | The capability ran on the real topology — a real sharded cluster, the real KMS, the actual target deployment. Atlas Local is a pull-request convenience and explicitly not release evidence (`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). | -| `security` | Privileges reviewed; the capability's admin role is separate from the application role. | -| `migration` | A documented path in and, where the capability is irreversible, an explicit statement that there is no path back. | -| `failure` | Negative cases fail closed: wrong key, missing permission, rotation, non-ready index, unrouted query. | -| `runbook` | A runbook exists for the capability's characteristic incident. | +| `stable-platform` | 같은 revision에서 Stable 릴리스 gate가 통과했다. | +| `actual-topology` | capability가 실제 topology에서 돌았다 — 실제 sharded cluster, 실제 KMS, 실제 대상 배포. Atlas Local은 pull request용 편의이고 릴리스 증거가 아님을 명시한다(`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). | +| `security` | 권한을 리뷰했다. capability의 admin role은 애플리케이션 role과 따로다. | +| `migration` | 들어가는 길을 적었고, capability가 되돌릴 수 없으면 돌아오는 길이 없다고 명시했다. | +| `failure` | 부정 경우가 실패하면 닫힌다: 틀린 키, 빠진 권한, 교체, 준비되지 않은 index, 라우팅되지 않은 query. | +| `runbook` | capability의 대표 사고를 위한 runbook이 있다. | -### Additional per-capability requirements +### capability별 추가 요구 -- **Search / vector search:** relevance and performance evidence, not functional success alone. - `MongoVectorSearchBenchmarkGate` requires recall alongside latency and index size; a gate that - measures only latency certifies a fast wrong answer. -- **Database-per-tenant and reshard orchestration remain Experimental** until operational scale - evidence exists. Both are correct in the small and unbounded in the large. -- **Reshard requires an explicit `ReshardApproval`** — a named approver and a stated window. It - rewrites the collection. +- **search / vector search:** 기능 성공만이 아니라 관련성과 성능 증거. `MongoVectorSearchBenchmarkGate`는 지연 시간·index 크기와 + 함께 recall을 요구한다. 지연 시간만 재는 gate는 빠른 틀린 답을 인증한다. +- **테넌트마다 데이터베이스와 reshard 조율은 운영 규모 증거가 생길 때까지 Experimental로 남는다.** 둘 다 작게는 맞고 크게는 + 한계가 없다. +- **reshard에는 명시한 `ReshardApproval`이 필요하다** — 이름 있는 승인자와 밝힌 시간 창. reshard는 collection을 다시 쓴다. -### Promotion does not change the dependency boundary +### 승격은 의존 경계를 바꾸지 않는다 -A capability promoted to Stable **remains an opt-in module** unless a later starter ADR changes the -dependency boundary. Promotion is a statement about evidence, not an invitation to add a transitive -dependency to every service. +Stable로 승격한 capability도 나중의 starter ADR이 의존 경계를 바꾸지 않는 한 **골라 쓰는 모듈로 남는다**. 승격은 증거에 대한 +진술이지, 모든 서비스에 전이 의존을 더하라는 초대가 아니다. -## Consequences +## 결과 -**Positive.** No capability reaches production on the strength of a container-only test. The evidence -list is the same for every capability, so promotion is reviewable rather than negotiated. +**좋은 점.** container 전용 시험을 근거로 운영에 닿는 capability는 없다. 증거 목록이 모든 capability에 같으므로, 승격은 흥정이 +아니라 리뷰할 수 있는 것이 된다. -**Negative.** Promotion requires access to real infrastructure — a sharded cluster, a real KMS, the -target deployment. That is the cost of the guarantee: the alternative is finding out in production, -where encryption and sharding are both expensive to reverse. +**나쁜 점.** 승격에는 실제 기반 시설 — sharded cluster, 실제 KMS, 대상 배포 — 에 대한 접근이 필요하다. 그것이 보장의 비용이다: +대안은 운영에서 알게 되는 것이고, 거기서는 암호화와 sharding 둘 다 되돌리기 비싸다. -## Verification +## 검증 -`scripts/verify-mongodb-advanced.sh` enforced this ADR until it was removed on 2026-08-15. The -promotion evidence categories this ADR requires are therefore no longer checked by any automated -gate; they are a review obligation until one is rebuilt. See `docs/mongodb/repository-adaptation.md` -§5 for the Gradle lanes the script wrapped. +`scripts/verify-mongodb-advanced.sh`가 2026-08-15에 지워질 때까지 이 ADR을 강제했다. 그래서 이 ADR이 요구하는 승격 증거 +category는 이제 어떤 자동 gate도 검사하지 않는다. 다시 만들 때까지 리뷰 의무다. 그 script가 감싸던 Gradle lane은 +`docs/mongodb/repository-adaptation.md` §5를 본다. diff --git a/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md b/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md index 8883fe61..d83135de 100644 --- a/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md +++ b/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md @@ -7,73 +7,62 @@ - 현재 정본: `docs/web/streaming-contract.md` -# ADR-WEB-ADV-001: Streaming is live delivery, and the web module stores no history +# ADR-WEB-ADV-001: streaming은 실시간 전달이고, web 모듈은 이력을 저장하지 않는다 -- Status: Accepted -- Date: 2026-08-25 -- Scope: `adapter:inbound:web` — `advanced.stream.**` +- 상태: 채택 +- 날짜: 2026-08-25 +- 범위: `adapter:inbound:web` — `advanced.stream.**` -## Context +## 배경 -Advanced Tasks 6–13 add SSE, NDJSON and JSON text sequences, with a `Last-Event-ID` resume path. +Advanced Task 6–13은 `Last-Event-ID` resume 경로와 함께 SSE, NDJSON, JSON text sequence를 더한다. -One fact drives every decision here: **after the first byte, the HTTP status is 200 and cannot -change.** A stream that ends because a dependency failed and one that ends because it finished are -identical at the transport layer — both are a closed connection after a 200. So is a stream that was -cut off mid-flight. +여기의 모든 결정을 이끄는 사실은 하나다: **첫 바이트 뒤에 HTTP status는 200이고 바꿀 수 없다.** 의존 대상이 실패해서 끝난 +stream과 다 마쳐서 끝난 stream은 전송 계층에서 똑같다 — 둘 다 200 뒤에 닫힌 연결이다. 도중에 잘린 stream도 그렇다. -The second fact is that a resume path invites the web module to remember things. It must not: the -messaging platform already owns durable event history, and a second copy would have its own -retention, its own eviction and its own opinion about ordering. +둘째 사실은 resume 경로가 web 모듈에게 무언가를 기억하라고 꾄다는 것이다. 그러면 안 된다: durable 이벤트 이력은 이미 메시징 +플랫폼이 가지고, 두 번째 사본은 자기 보존 기간, 자기 eviction, 순서에 대한 자기 의견을 가질 것이다. -## Decision +## 결정 -**Three outcomes, expressed in the stream rather than in the status.** The wire record (for NDJSON, -`NdjsonRecord`) is an item, a failure or a completion. A client that sees neither terminal record -has been cut off, and that third case is recorded as `ABRUPT_CLOSE` rather than counted as a -completion — which is where a rising rate of mid-stream failures would otherwise hide. +**결과는 셋이고, status가 아니라 stream 안에서 나타낸다.** wire record(NDJSON이면 `NdjsonRecord`)는 항목, 실패, 완료 중 하나다. +끝 record를 하나도 보지 못한 client는 잘린 것이고, 그 셋째 경우는 완료로 세지 않고 `ABRUPT_CLOSE`로 기록한다 — 그렇지 않으면 +도중 실패 비율이 오르는 것이 거기 숨는다. -**Nothing writes an error body onto a committed response.** Before commit, a failure is an ordinary -HTTP error (the `Envelope`) with a real status; after, a terminal record. Attempting both produces a -body that is half stream and half JSON, which no client parses and every proxy caches as a success. -(The mapper that encoded this, `WebStreamTerminationMapper`, was removed on 2026-09-25 with the -problem-document vocabulary it returned; the rule stands.) +**커밋된 응답 위에 오류 body를 쓰는 것은 없다.** 커밋 전의 실패는 실제 status를 가진 보통 HTTP 오류(`Envelope`)이고, 커밋 뒤에는 +끝 record다. 둘 다 하려 하면 반은 stream이고 반은 JSON인 body가 나오는데, 어떤 client도 그것을 파싱하지 못하고 모든 proxy가 +성공으로 cache한다. (이것을 인코딩하던 mapper `WebStreamTerminationMapper`는 그것이 돌려주던 problem document 어휘와 함께 +2026-09-25에 지웠다. 규칙은 남는다.) -**Positions are monotonic, and it is enforced.** `WebStreamEvidence.recordDelivered` refuses a -repeated or regressing position. A client deduplicating on position would silently drop the second -item. +**위치는 단조 증가하고, 그것을 강제한다.** `WebStreamEvidence.recordDelivered`는 되풀이되거나 뒤로 가는 위치를 거절한다. 위치로 +중복을 거르는 client는 두 번째 항목을 소리 없이 버리게 된다. -**A slow consumer is disconnected, not buffered.** `WebStreamPolicy.maxBufferedItems` is a hard -bound. Backpressure protects the reactive pipeline; it does not protect the server's heap from a -consumer that reads slowly for an hour. +**느린 소비자는 buffer에 담지 않고 연결을 끊는다.** `WebStreamPolicy.maxBufferedItems`는 단단한 한계다. backpressure는 reactive +pipeline을 지키지만, 한 시간 동안 천천히 읽는 소비자로부터 서버 heap을 지키지는 않는다. -**Every stream is in a registry, and shutdown drains it.** A node with a hundred open streams and no -other traffic looks idle by request rate. `WebStreamDrainCoordinator` stops accepting first, asks -clients to reconnect, and only then forces the remainder — because a client whose socket is cut -retries immediately, and if every socket is cut at once, every client retries at once. +**모든 stream은 registry에 있고, 종료가 그것을 비운다.** 열린 stream 백 개 말고 다른 traffic이 없는 노드는 요청 비율로 보면 놀고 +있는 것처럼 보인다. `WebStreamDrainCoordinator`는 먼저 받기를 멈추고, client에게 다시 연결하라고 요청하고, 그다음에야 나머지를 +강제로 끊는다 — socket이 끊긴 client는 바로 다시 시도하고, 모든 socket을 한꺼번에 끊으면 모든 client가 한꺼번에 다시 시도하기 +때문이다. -**The web module stores no durable history.** `WebStreamReplaySource` is an interface this module -implements nowhere. An expired cursor raises `ReplayCursorExpiredException` rather than resuming from -the oldest retained position, because that delivers a stream with a hole the client cannot see. +**web 모듈은 durable 이력을 저장하지 않는다.** `WebStreamReplaySource`는 이 모듈이 어디에서도 구현하지 않는 인터페이스다. 만료된 +cursor는 보존한 가장 오래된 위치에서 이어 가지 않고 `ReplayCursorExpiredException`을 올린다. 그렇게 하면 client가 볼 수 없는 +구멍이 있는 stream을 전달하기 때문이다. -**The replay-to-live seam is watched.** `GapAndDuplicateGuard` detects both directions. Neither is -visible in either half on its own. +**재생에서 실시간으로 넘어가는 이음매를 지켜본다.** `GapAndDuplicateGuard`가 두 방향을 모두 찾는다. 어느 쪽도 한 절반만 보면 +보이지 않는다. -## Consequences +## 결과 -- Clients must handle three outcomes. A client that treats a closed connection as completion will be - wrong, and no server change can fix that for it. -- An expired `Last-Event-ID` costs the client a full re-read. That is the honest answer. -- JSON-seq is preferred over NDJSON where truncation matters: its separator comes first, so a parser - resynchronises at the next record. NDJSON's delimiter is the thing that gets truncated away. +- client는 결과 셋을 다뤄야 한다. 닫힌 연결을 완료로 다루는 client는 틀리고, 서버가 무엇을 바꿔도 그것을 대신 고칠 수 없다. +- 만료된 `Last-Event-ID`는 client에게 전체 다시 읽기를 치르게 한다. 그것이 정직한 답이다. +- 잘림이 중요한 곳에서는 NDJSON보다 JSON-seq를 고른다: 구분자가 앞에 오므로 parser가 다음 record에서 다시 맞춘다. NDJSON의 + 구분자는 잘려 나가는 바로 그것이다. -## Alternatives considered +## 따져 본 대안 -- **Emit a problem document when a stream fails after commit.** Rejected: the body becomes - unparseable and the 200 is cached. -- **Resume from the oldest retained position when the cursor expires.** Rejected: positions are - contiguous from where the replay started, so nothing in the data says events are missing. -- **Store replay history in the web module.** Rejected: a second source of truth that drifts - invisibly. -- **Unbounded buffering for slow consumers.** Rejected: it moves the client's slowness into the - server's heap. +- **커밋 뒤에 stream이 실패하면 problem document를 낸다.** 버렸다: body가 파싱할 수 없게 되고 200이 cache된다. +- **cursor가 만료되면 보존한 가장 오래된 위치에서 이어 간다.** 버렸다: 위치는 재생이 시작된 곳부터 이어지므로, 데이터 안의 어떤 + 것도 이벤트가 빠졌다고 말하지 않는다. +- **재생 이력을 web 모듈에 저장한다.** 버렸다: 보이지 않게 어긋나는 두 번째 정본이다. +- **느린 소비자를 위한 한계 없는 buffer.** 버렸다: client의 느림을 서버 heap으로 옮긴다. diff --git a/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md b/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md index fafaeeae..4f3a9397 100644 --- a/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md +++ b/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md @@ -7,73 +7,60 @@ - 현재 정본: `docs/web/virtual-thread-profile.md` -# ADR-WEB-ADV-002: Virtual threads change scheduling, not the concurrency budget +# ADR-WEB-ADV-002: virtual thread는 스케줄링을 바꾸지 동시성 예산을 바꾸지 않는다 -- Status: Accepted -- Date: 2026-08-25 -- Scope: `adapter:inbound:web` — `advanced.virtualthread`, `advanced.blockingbridge` +- 상태: 채택 +- 날짜: 2026-08-25 +- 범위: `adapter:inbound:web` — `advanced.virtualthread`, `advanced.blockingbridge` -## Context +## 배경 -Advanced Task 2 offers a virtual-thread executor for MVC; Task 3 offered a bounded blocking bridge -for WebFlux. (The WebFlux adapter for it was removed on 2026-09-25 — the template is servlet only; -`advanced.blockingbridge` remains as library code.) +Advanced Task 2는 MVC용 virtual thread executor를 준다. Task 3은 WebFlux용 한계 있는 blocking bridge를 줬다. (그 WebFlux 어댑터는 +2026-09-25에 지웠다 — 템플릿은 servlet만이다. `advanced.blockingbridge`는 라이브러리 코드로 남는다.) -A platform-thread MVC deployment has an implicit concurrency limit — the thread pool — and that -limit is usually what has been protecting the database pool, the outbound HTTP bulkhead and every -downstream service from the full arrival rate. Nobody wrote it down as an admission policy; it was a -side effect of the pool size. +platform thread MVC 배포에는 숨은 동시성 한계 — thread pool — 가 있고, 보통 그 한계가 데이터베이스 pool, outbound HTTP +bulkhead, 모든 하류 서비스를 전체 도착 비율로부터 지켜 왔다. 아무도 그것을 admission 정책으로 적지 않았다. pool 크기의 +부작용이었다. -Switching to virtual threads deletes that limit without deleting anything that depended on it. +virtual thread로 바꾸면 그 한계가 지워지는데, 그것에 기대던 것은 하나도 지워지지 않는다. -## Decision +## 결정 -**An explicit admission limit is required when virtual threads are enabled.** -`VirtualThreadProfile` refuses construction without one. Without it the deployment accepts every -arrival, queues all of them on the downstream budgets, and times out work that would have succeeded -had it been refused. The load that used to be shed at the front door is shed at the back, after the -cost of accepting it. +**virtual thread를 켜면 명시적 admission 한계가 필요하다.** `VirtualThreadProfile`은 그것 없이는 만들어지기를 거절한다. 없으면 +배포는 모든 도착을 받고, 그것을 모두 하류 예산 위에 줄 세우며, 거절됐으면 성공했을 일을 timeout으로 끝낸다. 예전에 정문에서 +덜어 내던 부하를, 받아들이는 비용을 치른 뒤 뒷문에서 덜어 낸다. -**The limit bounds concurrent use cases, not threads.** `VirtualThreadAdmissionGuard` is a fair -semaphore, not a pool. Bounding threads would put the waiting back and throw away what virtual -threads bought. Ten thousand virtual threads may exist while a hundred hold permits. +**한계는 스레드가 아니라 동시 유스케이스를 묶는다.** `VirtualThreadAdmissionGuard`는 pool이 아니라 공정한 semaphore다. 스레드를 +묶으면 기다림을 되돌려 놓고 virtual thread가 산 것을 버린다. virtual thread 만 개가 있어도 허가를 쥔 것은 백 개일 수 있다. -**The downstream budgets are carried in the profile and stated as unchanged.** The whole point is -that they did not grow. `admissionFitsDownstreamBudgets()` reports when the admission limit exceeds -them, without refusing — a deployment can legitimately admit more than its pool when the work is not -all database-bound, and that should be a choice rather than an accident. +**하류 예산은 profile에 싣고 바뀌지 않았다고 밝힌다.** 요점은 그것이 늘지 않았다는 것이다. `admissionFitsDownstreamBudgets()`는 +admission 한계가 그것을 넘으면 거절하지 않고 알린다 — 일이 모두 데이터베이스에 묶인 것이 아니면 배포가 pool보다 많이 받는 +것이 정당할 수 있고, 그것은 사고가 아니라 선택이어야 한다. -**Blocking offloads are registered, bounded and timed out.** `boundedElastic()` is available from -anywhere and unbounded in practice, so a controller that calls it has silently opted the whole -application into an unbounded pool. `BlockingBridgeProfile` names the operations permitted to -offload; `BlockingBridgeBudget` bounds the concurrency and refuses a caller that cannot get a slot -in time, because otherwise a slow dependency's callers accumulate until the heap does and the fast -dependencies starve behind them. +**blocking offload는 등록하고, 한계를 두고, timeout을 둔다.** `boundedElastic()`은 어디서나 쓸 수 있고 실제로는 한계가 없어서, +그것을 부르는 controller는 애플리케이션 전체를 소리 없이 한계 없는 pool에 들여놓는다. `BlockingBridgeProfile`이 offload해도 되는 +operation을 이름으로 대고, `BlockingBridgeBudget`이 동시성을 묶으며 제때 자리를 얻지 못한 호출자를 거절한다. 그렇지 않으면 느린 +의존 대상의 호출자가 heap이 찰 때까지 쌓이고 빠른 의존 대상이 그 뒤에서 굶는다. -> 2026-09-25: `advanced.blockingbridge` was removed. Its WebFlux adapter went with the WebFlux twin -> (D4), and a budget for a bridge that no longer exists bounded nothing. +> 2026-09-25: `advanced.blockingbridge`를 지웠다. 그 WebFlux 어댑터는 WebFlux 쌍둥이와 함께 갔고(D4), 더는 없는 bridge의 예산은 +> 아무것도 묶지 않았다. -**Pinning is observed, not assumed away.** `VirtualThreadProfile.requiredObservations()` lists what -has to be watched — `jdk.VirtualThreadPinned` above all. A synchronized block held across a blocking -call pins the carrier thread, the carrier pool is bounded by CPU count, and enough pinned carriers is -a deadlock a thread dump does not obviously show. +**pinning은 없다고 치지 않고 관찰한다.** `VirtualThreadProfile.requiredObservations()`가 지켜봐야 할 것 — 무엇보다 +`jdk.VirtualThreadPinned` — 을 적는다. blocking 호출을 가로질러 쥔 synchronized 블록은 carrier thread를 고정하고, carrier pool은 +CPU 수로 묶여 있으며, 고정된 carrier가 충분히 많으면 thread dump로도 잘 드러나지 않는 교착이 된다. -## Consequences +## 결과 -- Enabling virtual threads is a two-part change: the executor and the admission limit. The profile - will not let it be one. -- Refusals rise under load, and that is correct. A request refused in a millisecond is better for - the client than the same request accepted and timed out thirty seconds later behind a full pool. - An operator seeing 503s climb should read them as the limit working. -- `VirtualThreadAdmissionGuard.peakActive()` exists so a load test can assert the limit was applied. - It is invisible from throughput, which is why a load test that only measures throughput would pass - with the guard removed. +- virtual thread 켜기는 두 부분짜리 변경이다: executor와 admission 한계. profile은 그것이 한 부분이 되게 두지 않는다. +- 부하 아래에서 거절이 오르고, 그것이 맞다. 1밀리초 안에 거절된 요청이, 꽉 찬 pool 뒤에서 받아들여졌다가 30초 뒤 timeout된 같은 + 요청보다 client에게 낫다. 503이 오르는 것을 본 운영자는 그것을 한계가 동작하는 것으로 읽어야 한다. +- `VirtualThreadAdmissionGuard.peakActive()`는 부하 시험이 한계가 적용됐음을 단언할 수 있게 하려고 있다. 처리량에서는 보이지 + 않는다. 그래서 처리량만 재는 부하 시험은 guard를 빼도 통과한다. -## Alternatives considered +## 따져 본 대안 -- **Enable virtual threads and raise the downstream budgets to match.** Rejected: the budgets are - sized to what the dependencies can serve, not to what the web tier can accept. -- **Bound the virtual threads themselves with a fixed-size executor.** Rejected: that is a platform - thread pool with extra steps. -- **Let controllers call `boundedElastic()` directly.** Rejected: every such call site is invisible - until the pool is the thing consuming the heap. +- **virtual thread를 켜고 하류 예산을 거기 맞춰 올린다.** 버렸다: 예산은 web 계층이 받을 수 있는 양이 아니라 의존 대상이 감당할 + 수 있는 양에 맞춘 것이다. +- **고정 크기 executor로 virtual thread 자체를 묶는다.** 버렸다: 단계만 더 많은 platform thread pool이다. +- **controller가 `boundedElastic()`을 직접 부르게 둔다.** 버렸다: 그런 호출 자리는 pool이 heap을 먹는 범인이 될 때까지 하나도 + 보이지 않는다. diff --git a/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md b/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md index d850da30..32782c1e 100644 --- a/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md +++ b/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md @@ -7,62 +7,51 @@ - 현재 정본: `docs/web/openapi-32-compatibility.md` -# ADR-WEB-ADV-003: OpenAPI 3.2 is generated in parallel and stays experimental +# ADR-WEB-ADV-003: OpenAPI 3.2는 나란히 생성하고 실험용으로 남는다 -- Status: Accepted -- Date: 2026-08-25 -- Scope: `adapter:inbound:web` — `advanced.openapi` +- 상태: 채택 +- 날짜: 2026-08-25 +- 범위: `adapter:inbound:web` — `advanced.openapi` -## Context +## 배경 -Advanced Task 17 adds an OpenAPI 3.2 generation lane beside the Stable 3.1.2 snapshot. +Advanced Task 17은 Stable 3.1.2 snapshot 옆에 OpenAPI 3.2 생성 lane을 더한다. -Generating 3.2 is cheap. Adopting it is not, and the two get conflated because the generated -document looks fine. The value of an API description is entirely in what consumes it, and a document -in a version a client generator does not fully understand produces a client that compiles and is -wrong — which is worse than no document at all. +3.2 생성은 싸다. 채택은 싸지 않고, 생성된 문서가 멀쩡해 보여서 둘이 뒤섞인다. API 설명의 가치는 전부 그것을 쓰는 쪽에 있고, +client 생성기가 다 이해하지 못하는 버전의 문서는 컴파일되지만 틀린 client를 낳는다 — 문서가 아예 없는 것보다 나쁘다. -## Decision +## 결정 -**3.1.2 remains the release artifact.** `OpenApiVersionLane.STABLE_3_1.releaseArtifact()` is true and -`EXPERIMENTAL_3_2`'s is false. This is a property of the type, not a configuration setting. +**3.1.2가 릴리스 artifact로 남는다.** `OpenApiVersionLane.STABLE_3_1.releaseArtifact()`는 true이고 `EXPERIMENTAL_3_2`의 것은 +false다. 이것은 설정이 아니라 타입의 성질이다. -**Generating 3.2 must not change the 3.1 snapshot.** Both are produced from the same model, so a -contributor that mutates it on the way to 3.2 changes the artifact that is actually shipped — -silently, and only when the experimental lane runs. `OpenApi32CompatibilityReport` compares the -snapshot hash before and after and makes a difference a promotion blocker. +**3.2를 생성해도 3.1 snapshot이 바뀌면 안 된다.** 둘은 같은 모델에서 만들어지므로, 3.2로 가는 길에 모델을 바꾸는 기여자는 실제로 +출하하는 artifact를 바꾼다 — 소리 없이, 실험 lane이 돌 때만. `OpenApi32CompatibilityReport`가 전후의 snapshot hash를 비교하고, +차이를 승격을 막는 것으로 만든다. -> 2026-09-25: `OpenApi32CompatibilityReport` and `OpenApiToolchainMatrix` were removed — promotion -> checks kept in production code, called only by their own tests. `WebOpenApi32Generator` remains -> as library code in `adapter:inbound:web-advanced`; the decision below is unchanged. +> 2026-09-25: `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`를 지웠다 — 운영 코드에 둔 승격 검사인데 자기 시험만 +> 불렀다. `WebOpenApi32Generator`는 `adapter:inbound:web-advanced`에 라이브러리 코드로 남는다. 아래 결정은 바뀌지 않았다. -**Four kinds of tool are checked separately.** A parser reports structural errors; a linter applies -style rules and accepts documents a parser rejects; a generator produces client code, and this is -where an unsupported construct surfaces — not as an error but as a method with the wrong signature; -a compile of that generated code is the only step that catches it. "OpenAPI 3.2 works" is not a -statement anybody can make. "This document is read correctly by these four tools at these versions" -is. +**도구 네 종류를 따로 검사한다.** parser는 구조 오류를 알린다. linter는 문체 규칙을 적용하고 parser가 거절하는 문서도 받는다. +생성기는 client 코드를 만들고, 지원되지 않는 구문이 드러나는 곳이 여기다 — 오류가 아니라 시그니처가 틀린 메서드로. 그 생성 코드를 +컴파일하는 것이 그것을 잡는 유일한 단계다. 「OpenAPI 3.2가 된다」는 누구도 할 수 있는 말이 아니다. 「이 문서를 이 버전의 이 네 +도구가 맞게 읽는다」는 할 수 있다. -**Promotion requires an accepted ADR regardless of how green the matrix is.** -`promotionBlockers(false)` always contains that blocker. A machine-checkable matrix cannot decide -whether the consumer population is ready. +**표가 얼마나 초록이든 승격에는 채택된 ADR이 필요하다.** `promotionBlockers(false)`는 언제나 그 막음을 담는다. 기계로 검사하는 +표는 쓰는 쪽 집단이 준비됐는지 정할 수 없다. -**Streaming description differences are reported separately.** They are the substantive difference -between the two versions for this application, and folding them into a pass/fail hides what -changed. +**streaming 설명의 차이는 따로 알린다.** 이 애플리케이션에서 두 버전의 실질적 차이가 그것이고, 통과·실패 하나로 접으면 무엇이 +바뀌었는지 가려진다. -## Consequences +## 결과 -- The 3.2 document is published as an artifact of the experimental workflow, never of the release - workflow. -- A client generator that only understands 3.1 is unaffected, which is the point. -- Adopting 3.2 later is a documented decision with a named consumer matrix behind it. +- 3.2 문서는 릴리스 workflow가 아니라 실험 workflow의 artifact로만 게시한다. +- 3.1만 이해하는 client 생성기는 영향을 받지 않는다. 그것이 요점이다. +- 나중에 3.2를 채택하는 것은 이름 있는 쓰는 쪽 표를 뒤에 둔, 문서로 남긴 결정이다. -## Alternatives considered +## 따져 본 대안 -- **Switch to 3.2 and keep a 3.1 downgrade.** Rejected: the downgrade is lossy in exactly the - constructs 3.2 was wanted for, so it would ship a description that is wrong for both audiences. -- **Generate only 3.2 and let consumers cope.** Rejected: the failure mode is a generated client - that compiles and misbehaves. -- **Skip the client-compile step in the matrix.** Rejected: it is the only one that catches the - failure the others miss. +- **3.2로 바꾸고 3.1로 낮춘 것을 둔다.** 버렸다: 낮추기는 바로 3.2를 원한 이유인 구문에서 손실이 있어서, 두 독자 모두에게 틀린 + 설명을 출하하게 된다. +- **3.2만 생성하고 쓰는 쪽이 알아서 하게 둔다.** 버렸다: 실패 방식은 컴파일되고 잘못 동작하는 생성 client다. +- **표에서 client 컴파일 단계를 건너뛴다.** 버렸다: 다른 단계가 놓치는 실패를 잡는 유일한 단계다. diff --git a/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md b/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md index 69cc7efb..81465281 100644 --- a/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md +++ b/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md @@ -8,62 +8,51 @@ - 대체됨: `docs/capability-status.md` -# ADR-WS-001: The WebSocket platform ships as packages in one leaf, with machine-checked boundaries +# ADR-WS-001: WebSocket 플랫폼은 leaf 하나 안의 패키지로 싣고, 경계는 기계로 검사한다 -- Status: Superseded 2026-09-25 — the eighteen-package platform was cut to the parts a Spring - configuration or a real-container lane reaches: the `stomp` channel and the servlet handler - library (`servlet`, `outbound`, `budget`). The Advanced packages, the reactive runtime and the - `WebSocketArchitectureRules` pack went with the rest (see `docs/capability-status.md`). -- Date: 2026-08-25 -- Scope: `:adapter:inbound:websocket` +- 상태: 대체됨 2026-09-25 — 패키지 열여덟 개짜리 플랫폼을 Spring 설정이나 실제 container lane이 닿는 부분으로 잘랐다: `stomp` + 채널과 servlet handler 라이브러리(`servlet`, `outbound`, `budget`). Advanced 패키지, reactive runtime, `WebSocketArchitectureRules` + 묶음은 나머지와 함께 갔다(`docs/capability-status.md`를 본다). +- 날짜: 2026-08-25 +- 범위: `:adapter:inbound:websocket` -## Context +## 배경 -The realtime connection platform design models itself as eighteen Gradle modules under -`modules/websocket`, each with a declared purity grade and a declared set of allowed dependencies. -This repository's `src/config/architecture/modules.json` is a fail-closed registry that owns the -leaf list; adding eighteen leaves is a registry change of a size that needs its own decision, and -HARD-STOP #5 forbids doing it implicitly. +실시간 연결 플랫폼 설계는 스스로를 `modules/websocket` 아래 Gradle 모듈 열여덟 개로 모델링하고, 모듈마다 순수성 등급과 허용 의존 +집합을 선언한다. 이 저장소의 `src/config/architecture/modules.json`은 leaf 목록을 가진 실패하면 닫히는 registry다. leaf 열여덟 개를 +더하는 것은 자기 결정이 필요한 크기의 registry 변경이고, HARD-STOP #5가 그것을 은근슬쩍 하는 것을 금지한다. -Three earlier platforms in this repository — JPA, GraphQL, and the HTTP platform — met the same -situation and resolved it the same way. +이 저장소의 앞선 플랫폼 셋 — JPA, GraphQL, HTTP 플랫폼 — 이 같은 상황을 만났고 같은 방식으로 풀었다. -## Decision +## 결정 -The eighteen design modules ship as packages inside the single registered leaf. `WebSocketStableModule` -declares each one's package, purity grade and exact allowed edges, and `WebSocketModuleBoundaryTest` -scans the production tree and fails when the declaration and the tree disagree in either direction. +설계 모듈 열여덟 개를 등록된 leaf 하나 안의 패키지로 싣는다. `WebSocketStableModule`이 모듈마다 패키지, 순수성 등급, 정확한 허용 +edge를 선언하고, `WebSocketModuleBoundaryTest`가 운영 트리를 scan해 선언과 트리가 어느 방향으로든 다르면 실패한다. -Three deviations from the design's module map were forced by the check and are recorded in -`docs/websocket/repository-adaptation.md`: `WebSocketSubprotocolName` moved to `core` and the codec -moved to its own FRAMEWORK_BOUND module, both to avoid cycles the design's placement created here; -and the `budget -> core` edge was inverted because `budget` imports nothing from `core`. +검사가 강요한, 설계 모듈 지도와 다른 점 셋은 `docs/websocket/repository-adaptation.md`에 적었다: `WebSocketSubprotocolName`을 +`core`로 옮겼고 codec을 자기 FRAMEWORK_BOUND 모듈로 옮겼다. 둘 다 설계의 배치가 여기서 만든 순환을 피하려는 것이다. 그리고 +`budget`이 `core`에서 아무것도 import하지 않으므로 `budget -> core` edge를 뒤집었다. -## Consequences +## 결과 -**The boundary is enforced, not documented.** Six violations were caught during implementation that -a document would not have: two would-be cycles, a duplicate module declaration where two ids claimed -one package, and three undeclared edges. The duplicate is the instructive one — with two ids on one -package, ownership depends on iteration order and one module's rules silently apply to nothing. A -guard against it is now part of the boundary test. +**경계를 문서로 두지 않고 강제한다.** 구현 중에 문서라면 잡지 못했을 위반 여섯 개를 잡았다: 순환이 될 뻔한 것 둘, id 둘이 패키지 +하나를 주장한 중복 모듈 선언, 선언하지 않은 edge 셋. 배울 것이 있는 쪽은 중복이다 — 패키지 하나에 id가 둘이면 소유가 반복 순서에 +달리고 한 모듈의 규칙이 소리 없이 아무것에도 적용되지 않는다. 그것을 막는 guard가 이제 경계 시험의 일부다. -**The detector had a hole.** Its framework-import list named `com.fasterxml` (Jackson 2) and not -`tools.jackson` (Jackson 3), which is what Spring 7 actually uses — so a CORE module could have -imported a mapper unnoticed. Fixed here and in the HTTP platform, which shared the list. +**찾는 장치에 구멍이 있었다.** 그 프레임워크 import 목록은 `com.fasterxml`(Jackson 2)를 대고 Spring 7이 실제로 쓰는 +`tools.jackson`(Jackson 3)을 대지 않았다 — 그래서 CORE 모듈이 mapper를 import해도 들키지 않을 수 있었다. 여기와, 그 목록을 같이 쓰던 +HTTP 플랫폼에서 고쳤다. -**Promotion stays cheap.** Each enum constant is already shaped like a leaf specification, so -splitting one out later is a registry edit rather than an archaeology exercise. +**승격은 싸게 남는다.** enum 상수 하나하나가 이미 leaf 명세 모양이라서, 나중에 하나를 떼어 내는 것은 고고학이 아니라 registry +수정이다. -**The design's own rules were kept where they cost something.** `core` names no framework, so the -same decisions serve both runtimes and are testable without a server; no Java class name reaches the -wire; the payload is an encoded string rather than a map; and handlers are given no way to write, -which is what makes ordering and backpressure guarantees rather than conventions. +**비용이 드는 곳에서도 설계 자신의 규칙을 지켰다.** `core`는 어떤 프레임워크도 이름으로 대지 않으므로 같은 결정이 두 runtime에 +쓰이고 서버 없이 시험할 수 있다. Java 클래스 이름이 wire에 닿지 않는다. payload는 map이 아니라 인코딩한 문자열이다. 그리고 +handler에게는 쓸 길을 주지 않는다. 그것이 순서와 backpressure를 관례가 아니라 보장으로 만든다. -## Alternatives considered +## 따져 본 대안 -**Register eighteen leaves.** Faithful to the design and a large change to a fail-closed registry -for a platform that ships as one artifact either way. Rejected as disproportionate; the boundary -test provides the property the modules were for. +**leaf 열여덟 개를 등록한다.** 설계에 충실하지만, 어느 쪽이든 artifact 하나로 싣는 플랫폼을 위해 실패하면 닫히는 registry를 크게 +바꾼다. 지나치다고 보고 버렸다. 경계 시험이 모듈이 주려던 성질을 준다. -**Ship the modules as packages with no enforcement.** Cheapest, and it makes the boundary a claim. -The six violations found during implementation are the argument against it. +**모듈을 강제 없는 패키지로 싣는다.** 가장 싸지만 경계를 주장으로 만든다. 구현 중에 찾은 위반 여섯 개가 그것에 반대하는 근거다. diff --git a/docs/adr/ADR-WS-002-resume-and-cluster.md b/docs/adr/ADR-WS-002-resume-and-cluster.md index 6f089e9d..30ad5578 100644 --- a/docs/adr/ADR-WS-002-resume-and-cluster.md +++ b/docs/adr/ADR-WS-002-resume-and-cluster.md @@ -8,64 +8,56 @@ - 대체됨: `docs/capability-status.md` -# ADR-WS-002: Resume and cluster state are caches, and are treated as caches +# ADR-WS-002: resume와 cluster 상태는 cache이고, cache로 다룬다 -- Status: Superseded 2026-09-25 — `advanced.resume`, `advanced.cluster` and `advanced.presence` - were removed: nothing assembled them (see `docs/capability-status.md`). -- Date: 2026-08-25 -- Scope: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence` +- 상태: 대체됨 2026-09-25 — `advanced.resume`, `advanced.cluster`, `advanced.presence`를 지웠다: 아무것도 그것을 조립하지 + 않았다(`docs/capability-status.md`를 본다). +- 날짜: 2026-08-25 +- 범위: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence` -## Context +## 배경 -Advanced Tasks 2–8 add three things that all look like state and are not: a resume token that says -where a client got to, a cluster index that says which node holds a session, and a presence summary -derived from that index. +Advanced Task 2–8은 모두 상태처럼 보이지만 상태가 아닌 것 셋을 더한다: client가 어디까지 왔는지 말하는 resume token, 어느 노드가 +세션을 가졌는지 말하는 cluster index, 그 index에서 끌어낸 presence 요약. -Each is a statement about the past. The resume token was minted before the disconnect; the index -entry was written by a node that may since have died; presence is a read of the index and inherits -everything wrong with it. The failure this ADR exists to prevent is treating any of them as current -fact, because each reads as one at the call site. +하나하나가 과거에 대한 진술이다. resume token은 연결이 끊기기 전에 만들어졌다. index 항목은 그 뒤에 죽었을 수 있는 노드가 썼다. +presence는 index를 읽은 것이고 그것의 틀린 점을 모두 물려받는다. 이 ADR이 막으려는 실패는 그중 어느 것이든 지금의 사실로 다루는 +것이다. 부르는 자리에서는 하나같이 사실처럼 읽히기 때문이다. -## Decision +## 결정 -**Resume is bounded by what the replay store actually holds, not by what the token claims.** -`ResumeCoordinator` consults `ReplayAvailability` before honouring a position. A token that names a -position the store has evicted produces a resynchronise, not a gap-filled stream. The alternative — -trusting the token — silently delivers a stream with a hole in it, which is worse than an explicit -resynchronise because the client believes it is complete. +**resume은 token이 주장하는 것이 아니라 replay 저장소가 실제로 가진 것으로 묶는다.** `ResumeCoordinator`는 위치를 받아 주기 전에 +`ReplayAvailability`를 묻는다. 저장소가 이미 버린 위치를 대는 token은 빈틈을 메운 stream이 아니라 다시 맞추기를 낸다. 대안 — token을 +믿기 — 은 구멍 난 stream을 소리 없이 전달하고, client가 그것이 완전하다고 믿으므로 명시적 다시 맞추기보다 나쁘다. -**Cluster index entries carry an observation time and are checked against it on every read.** -`ExternalSessionSummary.staleAt` exists so that "the index says edge-2" cannot be used without also -answering "as of when". An entry whose node stopped reporting is not evidence that the node holds -the session. +**cluster index 항목은 관찰 시각을 싣고, 읽을 때마다 그것과 대조한다.** `ExternalSessionSummary.staleAt`은 「index가 edge-2라고 +한다」를 「언제 기준으로」에 답하지 않고는 쓸 수 없게 하려고 있다. 보고를 멈춘 노드의 항목은 그 노드가 세션을 가졌다는 증거가 +아니다. -**Durable fan-out is deduplicated by stream position, not by message id.** At-least-once is the -contract, so redelivery is normal operation: a redeploy, a slow consumer or a broker rebalance all -produce it. `FanoutDeduplicator` keys on `(stream, position)` and advances a high-water mark under -`compute`, so two consumer threads cannot both deliver the same position. +**durable fan-out의 중복은 message id가 아니라 stream 위치로 거른다.** 계약이 at-least-once이므로 재전달은 보통 동작이다: 재배포, +느린 소비자, broker rebalance가 모두 그것을 낳는다. `FanoutDeduplicator`는 `(stream, position)`을 키로 쓰고 `compute` 아래에서 +high-water mark를 올리므로, 소비자 스레드 둘이 같은 위치를 둘 다 전달할 수 없다. -**Presence has four states, not two.** `OFFLINE` is a reported fact; `STALE` is the absence of one. -Collapsing them reports every user as disconnected during a Redis partition, when what happened is -that the index went dark and the connections are fine. +**presence에는 상태가 둘이 아니라 넷이다.** `OFFLINE`은 보고된 사실이고, `STALE`은 사실이 없는 것이다. 둘을 합치면 Redis partition +동안 모든 사용자를 연결 끊김으로 알리는데, 실제로 일어난 일은 index가 어두워졌고 연결은 멀쩡한 것이다. -**Nothing security-relevant may depend on presence.** An attacker who can make a node stop reporting -can move the platform's belief about who is present. Presence answers "show a green dot". +**보안에 관련된 어떤 것도 presence에 기대면 안 된다.** 노드가 보고를 멈추게 할 수 있는 공격자는 누가 있는지에 대한 플랫폼의 믿음을 +움직일 수 있다. presence는 「초록 점을 보여 줄까」에 답한다. -## Consequences +## 결과 -- A resume that cannot be honoured is visible to the client as a resynchronise. Clients must - implement one; there is no mode in which the platform silently pretends. -- Every read of the cluster index needs a clock. This is deliberate friction. -- `PresenceSummary.classify` refuses an idle window at or past the stale window, because otherwise - `IDLE` is unreachable and the caller believes it has a four-state model when it has three. -- Fan-out envelopes carry a bounded reference and the catalog-encoded document, never a business - object. A rolling deploy has two versions of the code reading the same envelope. +- 받아 줄 수 없는 resume은 client에게 다시 맞추기로 보인다. client는 그것을 구현해야 한다. 플랫폼이 소리 없이 시늉하는 모드는 없다. +- cluster index를 읽을 때마다 시계가 필요하다. 일부러 둔 마찰이다. +- `PresenceSummary.classify`는 stale 창 이상인 idle 창을 거절한다. 그렇지 않으면 `IDLE`에 닿을 수 없고, 호출자는 상태 셋짜리를 + 가지고 넷짜리 모델이라고 믿는다. +- fan-out envelope은 한계 있는 참조와 catalog로 인코딩한 문서를 싣고, 업무 객체는 싣지 않는다. rolling deploy에서는 코드 두 버전이 + 같은 envelope을 읽는다. -## Alternatives considered +## 따져 본 대안 -- **Trust the resume token.** Rejected: it makes a gap indistinguishable from a complete stream. -- **Deduplicate by message id.** Rejected: a broker that redelivers may re-mint ids, and a producer - that retries certainly does. Position is the property the ordering actually has. -- **A single `online` boolean.** Rejected for the partition case above. -- **Write presence separately from the session index.** Rejected: two sources of truth for "who is - connected" drift, and the drift is invisible — both look plausible and nothing reconciles them. +- **resume token을 믿는다.** 버렸다: 빈틈을 완전한 stream과 구별할 수 없게 만든다. +- **message id로 중복을 거른다.** 버렸다: 재전달하는 broker는 id를 다시 만들 수 있고, 재시도하는 producer는 반드시 그렇게 한다. + 위치가 순서가 실제로 가진 성질이다. +- **`online` boolean 하나.** 위 partition 경우 때문에 버렸다. +- **presence를 세션 index와 따로 쓴다.** 버렸다: 「누가 연결돼 있나」의 정본이 둘이면 어긋나고, 그 어긋남은 보이지 않는다 — 둘 다 + 그럴듯해 보이고 아무것도 둘을 맞추지 않는다. diff --git a/docs/adr/ADR-WS-003-stomp-and-broker-relay.md b/docs/adr/ADR-WS-003-stomp-and-broker-relay.md index fab91a73..b87857ec 100644 --- a/docs/adr/ADR-WS-003-stomp-and-broker-relay.md +++ b/docs/adr/ADR-WS-003-stomp-and-broker-relay.md @@ -8,78 +8,66 @@ - 대체됨: `docs/capability-status.md` -# ADR-WS-003: STOMP is an Advanced adapter with a declared destination catalog +# ADR-WS-003: STOMP는 destination catalog를 선언한 Advanced 어댑터다 -- Status: Superseded 2026-09-25 — `advanced.stomp` and `advanced.stomp.rabbit` were removed; the - `stomp` package is the only STOMP channel (see `docs/capability-status.md`). -- Date: 2026-08-25 -- Scope: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit` +- 상태: 대체됨 2026-09-25 — `advanced.stomp`와 `advanced.stomp.rabbit`을 지웠다. `stomp` 패키지가 유일한 STOMP 채널이다 + (`docs/capability-status.md`를 본다). +- 날짜: 2026-08-25 +- 범위: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit` -## Context +## 배경 -Advanced Tasks 9–13 add STOMP 1.2 alongside the platform's own protocol, plus a RabbitMQ broker -relay and cross-node user destinations. +Advanced Task 9–13은 플랫폼 자신의 프로토콜 옆에 STOMP 1.2를 더하고, RabbitMQ broker relay와 노드를 가로지르는 user destination도 +더한다. -This leaf already ships an older STOMP-over-SockJS channel (`stomp`, gated on -`app.websocket.enabled`). Two `@EnableWebSocketMessageBroker` configurations in one context -do not conflict loudly — both contribute a configurer, both call `configureMessageBroker`, and the -broker that results is whichever ran last. Nothing errors and nothing logs. +이 leaf는 이미 더 오래된 STOMP-over-SockJS 채널(`stomp`, `app.websocket.enabled`로 막는다)을 싣는다. 한 context 안의 +`@EnableWebSocketMessageBroker` 설정 둘은 시끄럽게 충돌하지 않는다 — 둘 다 configurer를 기여하고, 둘 다 +`configureMessageBroker`를 부르며, 결과 broker는 마지막에 돈 쪽의 것이다. 오류도 로그도 없다. -STOMP also brings a destination model that is a free string from the client. Without a catalog, the -set of reachable destinations is whatever the broker accepts, which for the simple broker is every -string. +STOMP는 client에게서 오는 자유 문자열인 destination 모델도 가져온다. catalog가 없으면 닿을 수 있는 destination 집합은 broker가 받는 +모든 것이고, simple broker에게 그것은 모든 문자열이다. -## Decision +## 결정 -**The Advanced adapter is its own module (`advanced-stomp`), separate from `advanced`.** It is the -one Advanced capability that cannot be pure — STOMP here *is* the Spring Messaging types — and -folding it into `advanced` would relax that module's purity for every capability in it. +**Advanced 어댑터는 `advanced`와 따로 둔 자기 모듈(`advanced-stomp`)이다.** 순수할 수 없는 유일한 Advanced capability다 — 여기서 +STOMP는 곧 Spring Messaging 타입이다 — 그리고 `advanced`에 접어 넣으면 그 모듈의 모든 capability에 대해 순수성을 느슨하게 만든다. -**The relay is a further module (`advanced-stomp-rabbit`).** The adapter parses a protocol; the -relay opens a TCP connection to somebody else's broker and makes every delivery depend on it. -Different blast radius, different decision, different module. +**relay는 그다음 모듈(`advanced-stomp-rabbit`)이다.** 어댑터는 프로토콜을 파싱한다. relay는 남의 broker에 TCP 연결을 열고 모든 +전달을 그것에 기대게 만든다. 피해 범위가 다르고, 결정이 다르고, 모듈이 다르다. -**Destinations are declared, per operation.** `StompDestinationCatalog` maps `(operation, -destination)` to a required permission. Undeclared is refused. `SUBSCRIBE` and `SEND` are separate -declarations, because reading a feed and publishing into it are different rights. +**destination은 operation마다 선언한다.** `StompDestinationCatalog`는 `(operation, destination)`을 필요한 권한에 대응시킨다. 선언하지 +않은 것은 거절한다. `SUBSCRIBE`와 `SEND`는 따로 선언한다. feed를 읽는 것과 거기에 게시하는 것은 다른 권리이기 때문이다. -**The authorization decision is a value, not an interceptor method.** `StompAuthorizationPolicy` -returns a `StompAuthorizationDecision`; `StompSecurityInterceptor` only extracts and enforces. A rule -reachable only through a `MessageChannel` gets tested for the cases somebody built a channel for. +**인가 판정은 interceptor 메서드가 아니라 값이다.** `StompAuthorizationPolicy`가 `StompAuthorizationDecision`을 돌려주고, +`StompSecurityInterceptor`는 꺼내서 강제하기만 한다. `MessageChannel`을 거쳐서만 닿는 규칙은 누가 channel을 만들어 둔 경우만 +시험된다. -**Only one STOMP runtime may run.** `StompBrokerExclusivity` fails the context when both channels -are enabled, when both brokers are, or when the adapter is enabled with no broker behind it. +**STOMP runtime은 하나만 돌 수 있다.** `StompBrokerExclusivity`는 두 채널이 모두 켜졌을 때, 두 broker가 모두 켜졌을 때, 또는 뒤에 +broker 없이 어댑터가 켜졌을 때 context를 실패시킨다. -**A `RECEIPT` is never promoted to a commit.** `StompEvidence` has six stages and -`StompAckPolicy.evidenceForReceipt()` is fixed at `PROTOCOL_RECEIPT`. The receipt is written by the -protocol layer, which knows nothing about whether the work succeeded. +**`RECEIPT`는 절대 커밋으로 올리지 않는다.** `StompEvidence`에는 단계가 여섯 있고 `StompAckPolicy.evidenceForReceipt()`는 +`PROTOCOL_RECEIPT`로 고정이다. receipt는 프로토콜 계층이 쓰고, 그 계층은 일이 성공했는지 아무것도 모른다. -**The simple broker declares what it cannot do.** `SimpleBrokerProfile` cannot be constructed -claiming cluster support or durable acks, and refuses activation outside local/test — in a -multi-node deployment it does not error, it delivers to whichever fraction of users is on the -publishing node. +**simple broker는 할 수 없는 것을 선언한다.** `SimpleBrokerProfile`은 cluster 지원이나 durable ack를 주장하며 만들 수 없고, +local·test 밖에서 켜기를 거절한다 — 여러 노드 배포에서 그것은 오류를 내지 않고, 게시한 노드에 있는 사용자 일부에게만 전달한다. -**Unresolved user destinations are broadcast once and then dead-lettered.** -`MultiNodeUserDestination` distinguishes a message that arrived *via* the broadcast from one that did -not. Without that, every node rebroadcasts every unresolvable message on receipt. +**풀리지 않은 user destination은 한 번 broadcast한 뒤 dead-letter로 보낸다.** `MultiNodeUserDestination`은 broadcast를 *거쳐* 온 +메시지와 그렇지 않은 메시지를 구별한다. 그렇지 않으면 모든 노드가 풀 수 없는 메시지를 받을 때마다 다시 broadcast한다. -## Consequences +## 결과 -- Enabling Advanced STOMP requires disabling the legacy channel. There is no migration path that - runs both; the exclusivity check makes that explicit at startup rather than at 3am. -- A deployment must write its own catalog. There is deliberately no default: an empty one refuses - every frame and reads as a broken adapter, and a non-empty one publishes destinations nobody chose. -- The relay's cost is one broker connection per authenticated session plus one system connection. - `brokerConnectionsFor` exists so this is computed before the first outage. -- User-destination metrics are tagged with `UserDestinationAction`, never the destination — a user - destination contains a user identifier by construction. +- Advanced STOMP를 켜려면 옛 채널을 꺼야 한다. 둘을 함께 돌리는 옮기기 길은 없다. 배타성 검사가 그것을 새벽 3시가 아니라 기동 + 때 분명히 한다. +- 배포는 자기 catalog를 써야 한다. 일부러 기본값이 없다: 빈 catalog는 모든 frame을 거절해서 고장 난 어댑터처럼 읽히고, 비어 있지 + 않은 기본 catalog는 아무도 고르지 않은 destination을 게시한다. +- relay의 비용은 인증된 세션마다 broker 연결 하나 + 시스템 연결 하나다. `brokerConnectionsFor`는 첫 장애 전에 그것을 계산하려고 + 있다. +- user destination metric은 destination이 아니라 `UserDestinationAction`으로 tag를 단다 — user destination은 구조상 사용자 식별자를 + 담는다. -## Alternatives considered +## 따져 본 대안 -- **Extend the existing `stomp` package.** Rejected: it is Stable, and WS-ARCH-6 forbids a Stable - module naming an Advanced one. Making the legacy channel profile-driven would have required that - edge. -- **One `advanced-stomp` module including the relay.** Rejected: the relay is a separate operational - decision and deserves to be refusable on its own. -- **Allow undeclared destinations with a wildcard permission.** Rejected: the wildcard becomes the - default and the catalog becomes documentation. +- **기존 `stomp` 패키지를 넓힌다.** 버렸다: 그것은 Stable이고, WS-ARCH-6은 Stable 모듈이 Advanced 모듈 이름을 대는 것을 금지한다. + 옛 채널을 profile로 움직이게 하려면 그 edge가 필요했다. +- **relay를 포함한 `advanced-stomp` 모듈 하나.** 버렸다: relay는 따로 정할 운영 결정이고, 그것만 따로 거절할 수 있어야 한다. +- **wildcard 권한으로 선언하지 않은 destination을 허용한다.** 버렸다: wildcard가 기본이 되고 catalog는 문서가 된다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 173f1fd2..acde70c0 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -9,32 +9,6 @@ language .github/dependency-vulnerability-policy.md language .github/pull_request_template.md language compose/keycloak/README.md language compose/redis/acl/README.md -language docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md -language docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md -language docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md -language docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md -language docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md -language docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md -language docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md -language docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md -language docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md -language docs/adr/ADR-JPA-001-domain-owns-persistence-model.md -language docs/adr/ADR-JPA-002-full-transaction-retry.md -language docs/adr/ADR-JPA-003-completion-unknown.md -language docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md -language docs/adr/ADR-JPA-005-postgresql-real-contract.md -language docs/adr/ADR-JPA-006-canonical-technical-audit.md -language docs/adr/ADR-MONGO-001-platform-boundary.md -language docs/adr/ADR-MONGO-002-bson-representation.md -language docs/adr/ADR-MONGO-003-transaction-retry.md -language docs/adr/ADR-MONGO-004-index-schema-admin-plane.md -language docs/adr/ADR-MONGO-ADV-001-capability-promotion.md -language docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md -language docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md -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