Merge branch 'claude/d2b-src-adr-d46d23' — 모듈 문서와 ADR 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(D2a 11줄, D2b 81줄, 겹침 0). 기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(220 → 128줄).
This commit is contained in:
@@ -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 — 답은 세 번째 규약이 아니라 따로 둔 모듈이다.
|
||||
|
||||
@@ -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 경계 규칙
|
||||
옆에서 검사한다.
|
||||
|
||||
@@ -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를 본다.
|
||||
|
||||
@@ -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이 들어온 뒤가 아니라
|
||||
오늘 돈다.
|
||||
|
||||
@@ -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`는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라
|
||||
지원하는 경로가 되게 하려고 있다.
|
||||
|
||||
@@ -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`으로 바꾼다.
|
||||
|
||||
@@ -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`가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다.
|
||||
|
||||
@@ -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을 본다.
|
||||
|
||||
@@ -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.<capability>.enabled`, all off by
|
||||
default.
|
||||
**capability마다 flag 하나.** `ca-skeleton.grpc.advanced.<capability>.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가 조용히 넓어질 수 없다.
|
||||
|
||||
@@ -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<T, ID>`
|
||||
every aggregate inherits — or provide only the pieces domains assemble themselves.
|
||||
영속 플랫폼은 repository 추상 — 모든 aggregate가 상속하는 `GenericRepository<T, ID>` — 을 가질 수도 있고, 도메인이 스스로
|
||||
조립할 조각만 줄 수도 있다.
|
||||
|
||||
## 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`.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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`이기도 하다).
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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`가 규칙 자신의 부정 경우를 시험한다.
|
||||
|
||||
@@ -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<T, ID>` 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<T, ID>`와 범용 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<T, ID>`.** 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<T, ID>`가 없다.** 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)를 본다.
|
||||
|
||||
@@ -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은 둘 다 사라진다.
|
||||
|
||||
@@ -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」.** 모든 트랜잭션 본문이 완전히 멱등이어야 한다. 표지 하나를 쓰는
|
||||
것보다 훨씬 강하고 훨씬 검사하기 어려운 성질이고, 누가 멱등이 아닌 단계를 처음 더하는 순간 소리 없이 깨진다.
|
||||
|
||||
@@ -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가
|
||||
실제 장치이고 애너테이션은 두 번째의 갈라진 정본이다.
|
||||
|
||||
@@ -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를 본다.
|
||||
|
||||
@@ -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으로 옮긴다.
|
||||
|
||||
@@ -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을 먹는 범인이 될 때까지 하나도
|
||||
보이지 않는다.
|
||||
|
||||
@@ -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 컴파일 단계를 건너뛴다.** 버렸다: 다른 단계가 놓치는 실패를 잡는 유일한 단계다.
|
||||
|
||||
@@ -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.
|
||||
**모듈을 강제 없는 패키지로 싣는다.** 가장 싸지만 경계를 주장으로 만든다. 구현 중에 찾은 위반 여섯 개가 그것에 반대하는 근거다.
|
||||
|
||||
@@ -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와 따로 쓴다.** 버렸다: 「누가 연결돼 있나」의 정본이 둘이면 어긋나고, 그 어긋남은 보이지 않는다 — 둘 다
|
||||
그럴듯해 보이고 아무것도 둘을 맞추지 않는다.
|
||||
|
||||
@@ -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는 문서가 된다.
|
||||
|
||||
@@ -7,30 +7,28 @@
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-001 — `submit()` means durable acceptance
|
||||
# NOTIF-ADR-001 — `submit()`은 durable 접수를 뜻한다
|
||||
|
||||
## Status
|
||||
## 상태
|
||||
|
||||
Accepted.
|
||||
채택.
|
||||
|
||||
## Context
|
||||
## 배경
|
||||
|
||||
The obvious API for a notification platform is `send()` returning success or failure. Every channel
|
||||
this platform supports makes that return value a lie:
|
||||
알림 플랫폼의 뻔한 API는 성공이나 실패를 돌려주는 `send()`다. 이 플랫폼이 지원하는 모든 채널이 그 반환값을 거짓말로 만든다:
|
||||
|
||||
- SES accepts a request, returns a `MessageId`, and can still decline to send.
|
||||
- Twilio separates `accepted`, `sent` and `delivered` into distinct, later events.
|
||||
- APNs accepts a notification and may then deliver, store or discard it.
|
||||
- Web Push separates push-service acceptance from user-agent acknowledgement at the protocol level.
|
||||
- SES는 요청을 받고 `MessageId`를 돌려준 뒤에도 보내기를 거절할 수 있다.
|
||||
- Twilio는 `accepted`, `sent`, `delivered`를 따로따로, 나중에 오는 이벤트로 나눈다.
|
||||
- APNs는 알림을 받은 뒤 전달하거나, 저장하거나, 버릴 수 있다.
|
||||
- Web Push는 프로토콜 수준에서 push service의 접수와 user agent의 확인 응답을 나눈다.
|
||||
|
||||
## Decision
|
||||
## 결정
|
||||
|
||||
`submit()` and `schedule()` return once the logical request and its recipient jobs are committed to
|
||||
the database. The receipt carries `notificationId`, `RequestStatus` and `acceptedAt`, and has no
|
||||
`delivered`, `sent` or `read` component. No provider is contacted while the transaction is open.
|
||||
`submit()`과 `schedule()`은 논리 요청과 그 수신자 job이 데이터베이스에 커밋되면 돌아온다. 접수증은 `notificationId`,
|
||||
`RequestStatus`, `acceptedAt`을 싣고, `delivered`·`sent`·`read` 요소가 없다. 트랜잭션이 열려 있는 동안에는 어떤 provider에도
|
||||
연락하지 않는다.
|
||||
|
||||
## Consequences
|
||||
## 결과
|
||||
|
||||
Callers cannot mistake acceptance for delivery, because the type does not offer that reading.
|
||||
Delivery state is a separate query against the projection built from the provider event ledger. The
|
||||
cost is that "did it arrive?" is a second question — which is the honest number of questions.
|
||||
타입이 그렇게 읽을 길을 주지 않으므로, 호출자는 접수를 전달로 착각할 수 없다. 전달 상태는 provider 이벤트 원장에서 만든
|
||||
projection에 대한 따로 둔 query다. 비용은 「도착했나?」가 두 번째 질문이라는 것이다 — 그것이 정직한 질문 수다.
|
||||
|
||||
@@ -7,28 +7,25 @@
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-002 — append-only event ledger with channel projectors
|
||||
# NOTIF-ADR-002 — 채널 projector를 둔 append-only 이벤트 원장
|
||||
|
||||
## Status
|
||||
## 상태
|
||||
|
||||
Accepted.
|
||||
채택.
|
||||
|
||||
## Context
|
||||
## 배경
|
||||
|
||||
A single linear delivery status has to be updated in place, which forces a rule for deciding whether
|
||||
a new event outranks the stored one. The natural rule — compare ordinals — is wrong for real provider
|
||||
traffic. Twilio does not guarantee callback ordering, so `sent` arrives after `delivered`. Email
|
||||
generates complaints after deliveries. Both cases lose information under an ordinal rule.
|
||||
선형 전달 상태 하나는 제자리에서 고쳐야 하고, 그러면 새 이벤트가 저장된 것보다 앞서는지 정할 규칙이 필요하다. 자연스러운 규칙 —
|
||||
ordinal 비교 — 은 실제 provider traffic에서 틀린다. Twilio는 callback 순서를 보장하지 않아서 `sent`가 `delivered` 뒤에 온다. email은
|
||||
전달 뒤에 불만 신고를 낸다. 두 경우 모두 ordinal 규칙 아래에서 정보를 잃는다.
|
||||
|
||||
## Decision
|
||||
## 결정
|
||||
|
||||
Provider events are appended to an immutable ledger before any projection runs. Channel-specific
|
||||
projectors merge events into `SubmissionOutcome`, `DeliveryOutcome`, `EvidenceLevel`,
|
||||
`EngagementFacts` and `SuppressionFacts` using explicit transition tables. Projection is idempotent
|
||||
and can be replayed from the ledger.
|
||||
provider 이벤트는 어떤 projection이 돌기 전에 바뀌지 않는 원장에 덧붙인다. 채널별 projector가 명시한 전이 표로 이벤트를
|
||||
`SubmissionOutcome`, `DeliveryOutcome`, `EvidenceLevel`, `EngagementFacts`, `SuppressionFacts`로 합친다. projection은 멱등이고 원장에서
|
||||
다시 돌릴 수 있다.
|
||||
|
||||
## Consequences
|
||||
## 결과
|
||||
|
||||
Duplicate, out-of-order and late events are normal inputs rather than defects. A projector bug is
|
||||
recoverable, because the events it mis-projected are still stored. Projector versions can be migrated
|
||||
by replay. The cost is a second write per event and a projection that can lag its ledger.
|
||||
중복, 순서가 뒤바뀐, 늦은 이벤트는 결함이 아니라 보통 입력이다. 잘못 project한 이벤트가 아직 저장돼 있으므로 projector 결함은
|
||||
회복할 수 있다. projector 버전은 다시 돌려서 옮길 수 있다. 비용은 이벤트마다 두 번째 쓰기와, 원장보다 늦을 수 있는 projection이다.
|
||||
|
||||
@@ -7,40 +7,36 @@
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-003 — ambiguous submission is a first-class state
|
||||
# NOTIF-ADR-003 — 모호한 제출은 정식 상태다
|
||||
|
||||
## Status
|
||||
## 상태
|
||||
|
||||
Accepted.
|
||||
채택.
|
||||
|
||||
## Context
|
||||
## 배경
|
||||
|
||||
The most common serious failure is not a rejection. It is a request whose body reached the provider
|
||||
and whose response never came back. The platform has no provider request id, and the user may or may
|
||||
not have received the notification.
|
||||
가장 흔한 심각한 실패는 거절이 아니다. body는 provider에 닿았는데 응답이 돌아오지 않은 요청이다. 플랫폼에는 provider 요청 id가 없고,
|
||||
사용자는 알림을 받았을 수도 안 받았을 수도 있다.
|
||||
|
||||
Treating that as a failure produces duplicates: a retry sends a second message, and a cross-channel
|
||||
fallback sends the SMS next to the push that already arrived. Treating it as a success loses real
|
||||
failures.
|
||||
그것을 실패로 다루면 중복이 생긴다: 재시도가 두 번째 메시지를 보내고, 채널을 넘는 대체가 이미 도착한 push 옆에 SMS를 보낸다. 성공으로
|
||||
다루면 실제 실패를 잃는다.
|
||||
|
||||
## Decision
|
||||
## 결정
|
||||
|
||||
`AMBIGUOUS` is a stored `SubmissionOutcome` and `AttemptConfirmation`. Attempts record
|
||||
`requestStarted`, `requestBodyCommitted` and `providerResponseReceived`, each with an
|
||||
`EvidenceCertainty` of `PROVEN`, `INFERRED` or `UNKNOWN`, so an adapter that does not know is not
|
||||
forced to answer `false`.
|
||||
`AMBIGUOUS`는 저장되는 `SubmissionOutcome`이자 `AttemptConfirmation`이다. 시도는 `requestStarted`, `requestBodyCommitted`,
|
||||
`providerResponseReceived`를 기록하고, 각각 `PROVEN`, `INFERRED`, `UNKNOWN` 중 하나의 `EvidenceCertainty`를 가진다. 그래서 모르는
|
||||
어댑터가 `false`로 답하도록 강요받지 않는다.
|
||||
|
||||
While an ambiguous attempt exists on a recipient delivery:
|
||||
수신자 전달에 모호한 시도가 있는 동안에는:
|
||||
|
||||
- automatic retry is blocked unless the provider proves per-request idempotency
|
||||
- automatic cross-channel fallback is blocked unconditionally
|
||||
- reconciliation runs where the provider supports a status query
|
||||
- otherwise the delivery stops and waits for an operator
|
||||
- provider가 요청별 멱등성을 증명하지 않으면 자동 재시도를 막는다
|
||||
- 채널을 넘는 자동 대체는 조건 없이 막는다
|
||||
- provider가 상태 query를 지원하면 맞춰 보기를 돌린다
|
||||
- 그렇지 않으면 전달을 멈추고 운영자를 기다린다
|
||||
|
||||
Operator redrive of an ambiguous attempt requires explicit duplicate-risk approval.
|
||||
모호한 시도를 운영자가 다시 보내려면 중복 위험을 명시해 승인해야 한다.
|
||||
|
||||
## Consequences
|
||||
## 결과
|
||||
|
||||
Some notifications stop in a state that needs a human or a reconciliation pass. That is the intended
|
||||
trade: an unresolved unknown is cheaper than a guaranteed duplicate, and the state is visible rather
|
||||
than silently resolved in either direction.
|
||||
어떤 알림은 사람이나 맞춰 보기 한 바퀴가 필요한 상태에서 멈춘다. 그것이 의도한 거래다: 풀리지 않은 모름이 보장된 중복보다 싸고,
|
||||
상태는 어느 쪽으로든 소리 없이 풀리지 않고 보인다.
|
||||
|
||||
@@ -7,30 +7,27 @@
|
||||
- 현재 정본: `docs/notification/provider-runbooks.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-004 — FCM installation id is the primary target
|
||||
# NOTIF-ADR-004 — FCM installation id가 주 대상이다
|
||||
|
||||
## Status
|
||||
## 상태
|
||||
|
||||
Accepted.
|
||||
채택.
|
||||
|
||||
## Context
|
||||
## 배경
|
||||
|
||||
Firebase now recommends the installation id (FID) and treats registration-token multicast paths as
|
||||
legacy. A contact point model built on a single `token` string would encode the older model as the
|
||||
only one, and a later migration would be a runtime interpretation problem: the same string field
|
||||
would mean different things for different rows.
|
||||
Firebase는 이제 installation id(FID)를 권하고 registration token multicast 경로를 옛것으로 다룬다. `token` 문자열 하나 위에 세운
|
||||
contact point 모델은 옛 모델을 유일한 것으로 담게 되고, 나중의 옮기기는 런타임 해석 문제가 된다: 같은 문자열 필드가 행마다 다른
|
||||
뜻이 된다.
|
||||
|
||||
## Decision
|
||||
## 결정
|
||||
|
||||
`MobilePushTarget` is a sealed hierarchy of `FcmInstallationId`, `LegacyFcmRegistrationToken` and
|
||||
`ApnsDeviceToken`. The kinds are separate types, never a discriminator on one string field, and each
|
||||
carries its own `ContactPointType` so the uniqueness scope and the encryption associated data differ.
|
||||
`MobilePushTarget`은 `FcmInstallationId`, `LegacyFcmRegistrationToken`, `ApnsDeviceToken`으로 된 sealed 계층이다. 종류는 문자열 필드
|
||||
하나의 구분자가 아니라 따로 둔 타입이고, 각각 자기 `ContactPointType`을 싣는다. 그래서 유일성 범위와 암호화 associated data가 다르다.
|
||||
|
||||
APNs tokens additionally carry their environment, because sandbox and production are separate
|
||||
namespaces rather than a flag.
|
||||
APNs token은 환경도 싣는다. sandbox와 production은 flag가 아니라 따로 둔 namespace이기 때문이다.
|
||||
|
||||
## Consequences
|
||||
## 결과
|
||||
|
||||
Migrating a target kind is a compile-time change with an exhaustive `switch`, not a runtime guess.
|
||||
The adapter maps each kind to its own wire representation, so a provider changing one path cannot
|
||||
silently change the other. The cost is one more type than a string field would need.
|
||||
대상 종류를 옮기는 것은 런타임 짐작이 아니라 빠짐없는 `switch`를 쓴 컴파일 시점 변경이다. 어댑터가 종류마다 자기 wire 표현으로
|
||||
대응시키므로, provider가 한 경로를 바꿔도 다른 경로가 소리 없이 바뀌지 않는다. 비용은 문자열 필드보다 타입이 하나 더 필요하다는
|
||||
것이다.
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
## 상태
|
||||
|
||||
Accepted (2026-08-15). NTF-018 대응.
|
||||
채택(2026-08-15). NTF-018 대응.
|
||||
|
||||
**갱신 (2026-09-25):** R1 type은 삭제됐다. production consumer가 끝까지 0건이었고 fake로만 증명된
|
||||
계약이라, 새 consumer를 막는 ArchUnit 규칙을 유지할 이유가 없어졌다. 남은 것은 adapter core의
|
||||
@@ -47,9 +47,10 @@ bridge도 import도 없다.
|
||||
reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며
|
||||
스스로 그렇게 선언한다 — `application-core/CLAUDE.md`가 "R1 application contract proven with fakes.
|
||||
It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime
|
||||
wiring qualification"이라고 적어 둔 그대로다.
|
||||
wiring qualification"(fake로 증명한 R1 애플리케이션 계약이다. PostgreSQL schema·locking, provider 프로토콜, 암호
|
||||
검증기, 런타임 배선 검증은 주장하지 않는다)이라고 적어 둔 그대로다.
|
||||
|
||||
## Disposition
|
||||
## 처분
|
||||
|
||||
R1 public type 100개의 처분은 네 가지 중 하나다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user