docs(web): web 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/web 아래 살아 있는 문서 7개가 영어였다(language 예외). http-contract.md는 짝 프론트 repo의 문서를 이 repo 경로처럼 인라인 코드로 적었다(reference 예외). repository-adaptation.md는 번역하며 보니 지금 코드와 여러 곳이 달랐다. - 1절 표: 설계 모듈 대부분을 「planned」로 적었지만 `core`·`mvc`는 web leaf에, `contract`·`versioning`·`admin`·`openapi`·`idempotency`는 web-advanced leaf에 이미 있다. `fileserver.*`·`notification.*`는 web leaf가 아니라 web-fileserver·web-notification leaf다. - Advanced 절: Advanced가 「이 leaf」의 package이고 `WebArchitectureRules.stableDoesNotDependOnAdvanced()` (`WEB-ARCH-ADV`)가 방향을 막는다고 했다. 그런 규칙은 없고, Advanced는 따로 된 leaf `adapter:inbound:web-advanced`이며 registry가 web-advanced → web 방향만 허락한다. - 4절: Spring Boot 기준을 4.0.8로 옮겨 적고 없는 `.vscode/settings.json`을 근거로 들었다. - 6절: 다시 보내기 JSON 인코딩이 web leaf에 남는다고 했지만 web-advanced에 있다. - 7절: web leaf가 의존할 수 있는 leaf에서 `adapter-outbound-support`가 빠졌다. 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·오류 코드·표 구조는 원문으로 둔다. 위 불일치는 registry와 트리에 맞춰 고쳤다. 다른 repo 문서는 경로 대신 repo 이름과 문서 이름을 문장으로 쓴다. 버전은 src/gradle/libs.versions.toml을 가리킨다. 버린 대안: 1절 표를 지우고 registry만 가리키기. 설계와 트리를 대조하는 사람에게 필요한 대응이 사라진다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/web을 읽는 테스트는 주석뿐이다(`grep -rn 'docs/web' src --include=*.java`: EnvelopeWireShapeTest 등 주석).
This commit is contained in:
@@ -1,78 +1,71 @@
|
||||
# Web Advanced: support matrix
|
||||
# Web Advanced: 지원 매트릭스
|
||||
|
||||
The Advanced capabilities live in their own leaf, `adapter:inbound:web-advanced`
|
||||
(`src/adapter/inbound/web-advanced`, package `dev.caskeleton.adapter.inbound.web.advanced`). No
|
||||
default composition carries it: `app-bootstrap`은 이 leaf에 의존하지 않는다. A
|
||||
service that wants one of these capabilities adds the leaf as `implementation` in its own adapter
|
||||
leaf and calls the types directly.
|
||||
Advanced capability는 따로 된 leaf `adapter:inbound:web-advanced`(`src/adapter/inbound/web-advanced`, package
|
||||
`dev.caskeleton.adapter.inbound.web.advanced`)에 있다. 이 leaf를 가진 기본 조립은 없다. `app-bootstrap`은 이 leaf에
|
||||
의존하지 않는다. 이 capability 중 하나가 필요한 서비스는 자기 어댑터 leaf에 이 leaf를 `implementation`으로 더하고
|
||||
타입을 직접 부른다.
|
||||
|
||||
Three capabilities have a runtime switch, published through the leaf's own
|
||||
`META-INF/spring/...AutoConfiguration.imports`. Everything else is a library: no property, no bean,
|
||||
nothing happens until service code calls it.
|
||||
실행 중 스위치가 있는 capability는 셋이고, leaf 자신의 `META-INF/spring/...AutoConfiguration.imports`로 등록한다.
|
||||
나머지는 모두 라이브러리다. 속성도 bean도 없고, 서비스 코드가 부르기 전에는 아무 일도 일어나지 않는다.
|
||||
|
||||
| Capability | How it is turned on | What it adds | Tests |
|
||||
| Capability | 켜는 법 | 더하는 것 | 테스트 |
|
||||
| --- | --- | --- | --- |
|
||||
| MVC virtual threads | `app.web.advanced.mvc-virtual-threads.enabled=true` (+ admission limit and budgets) | A different scheduling model for **every** request | `MvcAdvancedConfigurationTest`, `VirtualThreadAdmissionTest` |
|
||||
| NDJSON streaming | `app.web.advanced.ndjson.enabled=true` | Long-lived connections | `MvcStreamingWiringTest`, `WebStreamCoreTest`, `WebStreamDrainTest`, `WebStreamingSoakIT` |
|
||||
| JSON text sequences (RFC 7464) | `app.web.advanced.json-sequence.enabled=true` | Long-lived connections | as NDJSON |
|
||||
| JSON Merge Patch (RFC 7396) | library — `JsonMergePatchApplier` | Partial documents | `JsonMergePatchApplierTest` |
|
||||
| JSON Patch (RFC 6902) | library — `JsonPatchApplier` | Arbitrary pointers | `JsonPatchApplierTest` |
|
||||
| CBOR / XML codecs | library — `WebCborMapperFactory`, `WebXmlMapperFactory`; the backend jar is the service's choice | A second decoder | `WebCodecMapperTest`, `WebCodecSecurityTest` |
|
||||
| OpenAPI 3.2 | library — `WebOpenApi32Generator` | A parallel description artifact | `WebOpenApi32GeneratorTest` |
|
||||
| Stream replay from messaging | library — `MessagingReplayBridge` | Resume after reconnect | `MessagingReplayBridgeTest` |
|
||||
| MVC virtual thread | `app.web.advanced.mvc-virtual-threads.enabled=true`(+ 허가 상한과 예산) | **모든** 요청에 대한 다른 스케줄링 모델 | `MvcAdvancedConfigurationTest`, `VirtualThreadAdmissionTest` |
|
||||
| NDJSON 스트리밍 | `app.web.advanced.ndjson.enabled=true` | 오래 사는 connection | `MvcStreamingWiringTest`, `WebStreamCoreTest`, `WebStreamDrainTest`, `WebStreamingSoakIT` |
|
||||
| JSON text sequence(RFC 7464) | `app.web.advanced.json-sequence.enabled=true` | 오래 사는 connection | NDJSON과 같다 |
|
||||
| JSON Merge Patch(RFC 7396) | 라이브러리 — `JsonMergePatchApplier` | 부분 문서 | `JsonMergePatchApplierTest` |
|
||||
| JSON Patch(RFC 6902) | 라이브러리 — `JsonPatchApplier` | 임의의 pointer | `JsonPatchApplierTest` |
|
||||
| CBOR / XML codec | 라이브러리 — `WebCborMapperFactory`, `WebXmlMapperFactory`. backend jar는 서비스가 고른다 | 두 번째 decoder | `WebCodecMapperTest`, `WebCodecSecurityTest` |
|
||||
| OpenAPI 3.2 | 라이브러리 — `WebOpenApi32Generator` | 나란히 만드는 설명 산출물 | `WebOpenApi32GeneratorTest` |
|
||||
| messaging에서 stream 다시 보내기 | 라이브러리 — `MessagingReplayBridge` | 다시 연결한 뒤 이어 받기 | `MessagingReplayBridgeTest` |
|
||||
|
||||
The same leaf also holds the web library packages the servlet production path never reaches:
|
||||
`http` (URI and method policy), `versioning`, `operation`, `budget`, `contract`, `security`
|
||||
(security-context bridge), `idempotency` (`JsonIdempotentResponseCodec`) and `admin/route`.
|
||||
같은 leaf에 servlet 운영 경로가 닿지 않는 web 라이브러리 package도 있다: `http`(URI와 method 정책), `versioning`,
|
||||
`operation`, `budget`, `contract`, `security`(security context 다리), `idempotency`(`JsonIdempotentResponseCodec`),
|
||||
`admin/route`.
|
||||
|
||||
`./gradlew :adapter:inbound:web-advanced:test` runs all of it. `webAdvancedTest` is the tagged
|
||||
subset and fails when the tag selects nothing.
|
||||
`./gradlew :adapter:inbound:web-advanced:test`가 전부 돌린다. `webAdvancedTest`는 tag를 단 부분집합이고, tag가 아무
|
||||
것도 고르지 않으면 실패한다.
|
||||
|
||||
## Removed on 2026-09-25
|
||||
## 2026-09-25에 지운 것
|
||||
|
||||
- The promotion/release gate (`WebAdvancedPromotionGate`, `WebAdvancedReleaseManifest`,
|
||||
`WebAdvancedFeature`) and the OpenAPI 3.2 promotion report (`OpenApi32CompatibilityReport`,
|
||||
`OpenApiToolchainMatrix`). They were checks on this repository's release process kept in
|
||||
production code, and only their own tests called them. The feature catalog also named flags that
|
||||
no code reads (`…json-merge-patch.enabled`, `…sse.enabled`, `…cbor.enabled` and others).
|
||||
- `advanced.blockingbridge`: the accounting half of the WebFlux blocking bridge, whose adapter went
|
||||
with the WebFlux twin.
|
||||
- `functional` (`FunctionalRouteRegistry`, `WebFunctionalHandlerAdapter`): it built a WebFlux
|
||||
`RouterFunction`, which nothing serves in a servlet-only template (D4). `spring-webflux` left the
|
||||
leaf with it.
|
||||
- Packages that re-implemented what the production web path already does another way, and the
|
||||
`webNginxProxyTest` lane that certified only one of them:
|
||||
- `proxy` + `http.External*` — production uses `server.forward-headers-strategy`
|
||||
- 승격/릴리스 게이트(`WebAdvancedPromotionGate`, `WebAdvancedReleaseManifest`, `WebAdvancedFeature`)와 OpenAPI 3.2
|
||||
승격 보고서(`OpenApi32CompatibilityReport`, `OpenApiToolchainMatrix`). 이 저장소의 릴리스 절차를 검사하는 것이
|
||||
production 코드에 있었고, 자기 테스트만 그것을 불렀다. 기능 목록은 어떤 코드도 읽지 않는 flag(`…json-merge-patch.enabled`,
|
||||
`…sse.enabled`, `…cbor.enabled` 등)도 적었다.
|
||||
- `advanced.blockingbridge`: WebFlux blocking 다리의 회계 쪽 절반. 어댑터 쪽은 WebFlux 쌍과 함께 사라졌다.
|
||||
- `functional`(`FunctionalRouteRegistry`, `WebFunctionalHandlerAdapter`): WebFlux `RouterFunction`을 만들었는데,
|
||||
servlet만 쓰는 템플릿(D4)에서는 아무것도 그것을 내보내지 않는다. `spring-webflux`도 함께 leaf를 떠났다.
|
||||
- 운영 web 경로가 이미 다른 방식으로 하는 일을 다시 구현한 package들, 그리고 그중 하나만 인증하던 `webNginxProxyTest`
|
||||
lane:
|
||||
- `proxy` + `http.External*` — 운영은 `server.forward-headers-strategy`를 쓴다
|
||||
(`app-bootstrap/src/main/resources/config/server.yml`).
|
||||
- `security` CORS/CSRF profiles — production uses `CorsSettings` and `SecurityConfig`.
|
||||
- `cache` — production uses `CacheControlFilter`.
|
||||
- `json` (`WebObjectMapperFactory`) — production uses Boot's `JsonMapper`; the streaming encoder
|
||||
now writes with that bean.
|
||||
- `openapi.WebOpenApiCustomizer` (+ `WebOpenApiProfile`, `CursorSchemaContributor`) —
|
||||
production customizes springdoc through `OpenApiContractConfig`.
|
||||
- `security` CORS/CSRF profile — 운영은 `CorsSettings`와 `SecurityConfig`를 쓴다.
|
||||
- `cache` — 운영은 `CacheControlFilter`를 쓴다.
|
||||
- `json`(`WebObjectMapperFactory`) — 운영은 Boot의 `JsonMapper`를 쓴다. 스트리밍 encoder도 이제 그 bean으로 쓴다.
|
||||
- `openapi.WebOpenApiCustomizer`(+ `WebOpenApiProfile`, `CursorSchemaContributor`) — 운영은
|
||||
`OpenApiContractConfig`로 springdoc을 손본다.
|
||||
|
||||
Recovery paths are in `docs/capability-status.md` (the removed-code table).
|
||||
되살리는 길은 `docs/capability-status.md`(제거된 코드 표)에 있다.
|
||||
|
||||
## What is refused, and why the row is here
|
||||
## 거부하는 것과 그 행이 여기 있는 이유
|
||||
|
||||
| Refused | Reason |
|
||||
| 거부 | 이유 |
|
||||
| --- | --- |
|
||||
| Virtual threads without an admission limit | The pool size *was* the admission policy. Removing it accepts every arrival and queues them on downstream budgets that did not grow. |
|
||||
| A merge patch outside its field allowlist | A merge patch is partial, so no DTO's absent fields say "not permitted". Without an allowlist the writable set grows every time somebody adds a field. |
|
||||
| A JSON Patch pointer above its allowed prefix | Replacing a parent deletes every sibling, so permission on a child cannot grant it. |
|
||||
| A `move` whose source is unauthorized | Checking only the destination lets a caller relocate data out of a field they may not touch. |
|
||||
| XML with a DTD or an external entity | Billion-laughs and XXE. Neither errors when it fires; the parse succeeds and the document contains something it should not. |
|
||||
| A non-JSON representation without all three gates | The enabled set the service passes to `RepresentationNegotiationPolicy`, route `produces`, and client allowlist. An `Accept` header is not evidence the route was tested against that codec. |
|
||||
| Compression-style silent fallback on a 406 | A client that asked only for CBOR and gets JSON parses the bytes as CBOR and fails somewhere far away. |
|
||||
| Changing HTTP status after commit | The body becomes half stream, half JSON, and the 200 is cached. |
|
||||
| Unbounded buffering for a slow consumer | It moves the client's slowness into the server's heap. |
|
||||
| 허가 상한 없는 virtual thread | pool 크기가 *곧* 허가 정책이었다. 그것을 없애면 오는 요청을 다 받고, 늘지 않은 하류 예산에 줄 세운다. |
|
||||
| 필드 허용 목록 밖의 merge patch | merge patch는 부분이라, 어떤 DTO의 빠진 필드도 「허락 안 함」을 뜻하지 않는다. 허용 목록이 없으면 누가 필드를 더할 때마다 쓸 수 있는 집합이 커진다. |
|
||||
| 허락한 접두사보다 위의 JSON Patch pointer | 부모를 바꾸면 모든 형제가 지워진다. 그래서 자식에 대한 권한이 부모 권한을 줄 수 없다. |
|
||||
| 출처가 허락되지 않은 `move` | 목적지만 검사하면 호출자가 건드릴 수 없는 필드의 데이터를 옮겨 낼 수 있다. |
|
||||
| DTD나 외부 entity가 있는 XML | Billion-laughs와 XXE. 둘 다 터져도 오류가 나지 않는다. 파싱은 성공하고 문서에 있으면 안 되는 것이 들어 있다. |
|
||||
| 세 관문을 다 지나지 않은 JSON 아닌 표현 | 서비스가 `RepresentationNegotiationPolicy`에 넘기는 켜진 집합, route의 `produces`, client 허용 목록. `Accept` 헤더는 그 route가 그 codec으로 시험됐다는 증거가 아니다. |
|
||||
| 406에서 압축처럼 조용히 물러서기 | CBOR만 요청한 client가 JSON을 받으면 그 바이트를 CBOR로 파싱하다 먼 곳에서 실패한다. |
|
||||
| commit 뒤 HTTP 상태 바꾸기 | 본문이 반은 stream, 반은 JSON이 되고, 200이 cache된다. |
|
||||
| 느린 소비자를 위한 상한 없는 버퍼링 | client의 느림을 서버의 heap으로 옮긴다. |
|
||||
|
||||
## Turning it off
|
||||
## 끄기
|
||||
|
||||
Removing the dependency removes the capability. With the dependency present, the three switches
|
||||
default to off; `WebAdvancedRollbackIT` asserts that no Advanced bean exists with no flag set and
|
||||
with each flag explicitly `false`.
|
||||
의존성을 빼면 capability가 사라진다. 의존성이 있어도 스위치 셋은 기본으로 꺼져 있다. `WebAdvancedRollbackIT`가
|
||||
flag를 하나도 주지 않았을 때와 각 flag를 명시적으로 `false`로 줬을 때 Advanced bean이 하나도 없음을 단언한다.
|
||||
|
||||
See `docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md`,
|
||||
`ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md`, and
|
||||
`ADR-WEB-ADV-003-openapi-32-remains-experimental.md`.
|
||||
`docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md`,
|
||||
`ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md`,
|
||||
`ADR-WEB-ADV-003-openapi-32-remains-experimental.md`를 본다.
|
||||
|
||||
@@ -206,5 +206,5 @@ CORS가 켜져 있으면(`app.cors.enabled=true`) cross-origin 실제 응답의
|
||||
`docs/registries/error-codes.yaml`, 이 문서 2절을 같은 변경에서 고친다. 공유 코드의 `retryable`은
|
||||
gRPC trailer(`error-retryable`)와 GraphQL extension(`retryable`)에도 그대로 나가므로 그 둘의 README와
|
||||
매핑 테스트(`GrpcStatusMapperTest`, `GraphQlWireErrorMapperTest`)도 같이 본다.
|
||||
- 짝 프론트의 백엔드 계약 문서(`clean-architecture-frontend-template`
|
||||
`docs/architecture/backend-api-and-server-state-contract.md` §4.1·§6)는 이 문서를 가리켜야 한다.
|
||||
- 짝 프론트 repo `clean-architecture-frontend-template`의 백엔드 계약 문서(「backend API와 server state
|
||||
계약」 §4.1·§6)는 이 문서를 가리켜야 한다. 그 문서는 다른 repo에 있어서 여기서 경로로 가리키지 않는다.
|
||||
|
||||
@@ -1,32 +1,27 @@
|
||||
# OpenAPI 3.2: the experimental lane
|
||||
# OpenAPI 3.2: 실험 lane
|
||||
|
||||
## Why it is a lane rather than an upgrade
|
||||
## 업그레이드가 아니라 lane인 이유
|
||||
|
||||
Generating 3.2 is cheap. Adopting it is not, and the two get conflated because the generated
|
||||
document looks fine.
|
||||
3.2를 만드는 것은 싸다. 받아들이는 것은 싸지 않다. 만든 문서가 멀쩡해 보여서 둘이 섞인다.
|
||||
|
||||
The value of an API description is entirely in what consumes it. A document in a version a client
|
||||
generator does not fully understand does not fail — it produces a client that compiles and is wrong,
|
||||
which is worse than no document at all.
|
||||
API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지
|
||||
않는다. 컴파일되는데 틀린 client를 만든다. 문서가 아예 없는 것보다 나쁘다.
|
||||
|
||||
So 3.1.2 stays the release artifact and 3.2 is generated beside it.
|
||||
그래서 3.1.2가 릴리스 산출물로 남고, 3.2는 그 옆에서 만든다.
|
||||
|
||||
## The invariant
|
||||
## 불변식
|
||||
|
||||
**Generating 3.2 must not change the 3.1 snapshot.** Both come 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 3.2 is generated.
|
||||
**3.2를 만드는 것이 3.1 snapshot을 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에 모델을
|
||||
바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만.
|
||||
|
||||
Nothing in this repository checks it any more. `OpenApi32CompatibilityReport` and
|
||||
`OpenApiToolchainMatrix` — the promotion report that hashed the snapshot and recorded which parser,
|
||||
linter, generator and client compile had read the 3.2 output — were removed on 2026-09-25: they
|
||||
lived in production code and only their own tests called them. A service that generates 3.2 with
|
||||
`WebOpenApi32Generator` (library, `adapter:inbound:web-advanced`) owns that check in its own build.
|
||||
이 저장소에는 그것을 검사하는 것이 더는 없다. snapshot을 hash하고 어떤 parser, linter, generator, client 컴파일이
|
||||
3.2 출력을 읽었는지 기록하던 승격 보고서 `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`는 2026-09-25에
|
||||
지웠다. production 코드에 있었고 자기 테스트만 그것을 불렀다. `WebOpenApi32Generator`(라이브러리,
|
||||
`adapter:inbound:web-advanced`)로 3.2를 만드는 서비스는 그 검사를 자기 빌드에서 가진다.
|
||||
|
||||
Promotion stays a judgement, recorded in
|
||||
`docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`.
|
||||
승격은 판단으로 남고, `docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`에 기록한다.
|
||||
|
||||
## Running it
|
||||
## 돌리기
|
||||
|
||||
No workflow in this repository generates 3.2. `OpenApiVersionLane.STABLE_3_1` is the release
|
||||
artifact; `WebOpenApi32GeneratorTest` covers the generator.
|
||||
이 저장소의 어떤 workflow도 3.2를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`이 릴리스 산출물이고,
|
||||
`WebOpenApi32GeneratorTest`가 generator를 다룬다.
|
||||
|
||||
+37
-49
@@ -1,60 +1,50 @@
|
||||
# Web patch: the client contract
|
||||
# Web patch: client 계약
|
||||
|
||||
Two patch formats, and they are not interchangeable. Both appliers are library code in
|
||||
`adapter:inbound:web-advanced` (opt-in): a service adds the leaf and calls `JsonMergePatchApplier`
|
||||
or `JsonPatchApplier` from its controller.
|
||||
patch 형식은 둘이고, 서로 바꿔 쓸 수 없다. 두 applier 모두 `adapter:inbound:web-advanced`(골라 쓰는 leaf)의 라이브러리
|
||||
코드다. 서비스가 그 leaf를 더하고 자기 controller에서 `JsonMergePatchApplier`나 `JsonPatchApplier`를 부른다.
|
||||
|
||||
## Choosing one
|
||||
## 하나 고르기
|
||||
|
||||
A route accepts exactly one, and sending the other is a 415 rather than a best-effort guess. The
|
||||
reason is that a mismatch is silent in the worst direction:
|
||||
route는 정확히 하나만 받고, 다른 것을 보내면 최선의 짐작 대신 415다. 어긋남이 가장 나쁜 방향으로 조용하기 때문이다.
|
||||
|
||||
- `{"a": null}` as a **merge patch** deletes `a`. As a **JSON Patch** it is not a patch at all — it
|
||||
is an object where an array was required.
|
||||
- A JSON Patch array read as a merge patch is a document whose fields are array indices. It merges
|
||||
nothing and reports success.
|
||||
- `{"a": null}`은 **merge patch**로는 `a`를 지운다. **JSON Patch**로는 patch가 아예 아니다. 배열이 필요한 곳의 객체다.
|
||||
- JSON Patch 배열을 merge patch로 읽으면 필드가 배열 index인 문서다. 아무것도 합치지 않고 성공을 보고한다.
|
||||
|
||||
| | Merge patch | JSON Patch |
|
||||
| --- | --- | --- |
|
||||
| Media type | `application/merge-patch+json` | `application/json-patch+json` |
|
||||
| RFC | 7396 | 6902 |
|
||||
| Shape | A partial document | An ordered array of operations |
|
||||
| Delete | `"field": null` | `{"op":"remove","path":"/field"}` |
|
||||
| Arrays | Replaced whole | Addressable per index |
|
||||
| Preconditions | `If-Match` only | `If-Match`, plus per-field `test` |
|
||||
| 모양 | 부분 문서 | 순서 있는 연산 배열 |
|
||||
| 삭제 | `"field": null` | `{"op":"remove","path":"/field"}` |
|
||||
| 배열 | 통째로 바꾼다 | index마다 가리킬 수 있다 |
|
||||
| 선행 조건 | `If-Match`만 | `If-Match`, 그리고 필드별 `test` |
|
||||
|
||||
Use merge patch for "change these fields". Use JSON Patch when you need array element edits or a
|
||||
precondition on one field that `If-Match` cannot express.
|
||||
「이 필드들을 바꿔라」에는 merge patch를 쓴다. 배열 원소를 고치거나, `If-Match`로 표현할 수 없는 필드 하나의 선행
|
||||
조건이 필요하면 JSON Patch를 쓴다.
|
||||
|
||||
## What is refused
|
||||
## 거부하는 것
|
||||
|
||||
**Fields outside the allowlist.** The server declares which fields a merge patch may modify and
|
||||
which pointers a JSON Patch may address. Anything else is refused, and *every* refused path is
|
||||
named — you will not discover them one round trip at a time.
|
||||
**허용 목록 밖의 필드.** 서버가 merge patch가 바꿀 수 있는 필드와 JSON Patch가 가리킬 수 있는 pointer를 선언한다.
|
||||
그 밖의 것은 거부하고, 거부한 경로는 *모두* 이름을 댄다. 왕복 한 번에 하나씩 알게 되지 않는다.
|
||||
|
||||
The allowlist is checked **before** anything is applied. A refusal tells you nothing about the
|
||||
current values, which is deliberate: deciding afterwards whether a refused field "actually changed
|
||||
anything" would answer a question about data you may not read.
|
||||
허용 목록은 무엇이든 적용하기 **전에** 검사한다. 거부는 지금 값에 대해 아무것도 알려 주지 않는다. 일부러 그렇다.
|
||||
거부한 필드가 「실제로 무언가를 바꿨는지」를 나중에 따지면 읽어서는 안 되는 데이터에 대한 질문에 답하게 된다.
|
||||
|
||||
**Pointer permission does not travel upwards.** Permission on `/profile` covers
|
||||
`/profile/displayName`; permission on `/profile/displayName` does not cover `/profile`, because
|
||||
replacing the parent deletes every sibling.
|
||||
**pointer 권한은 위로 올라가지 않는다.** `/profile`에 대한 권한은 `/profile/displayName`을 덮는다.
|
||||
`/profile/displayName`에 대한 권한은 `/profile`을 덮지 않는다. 부모를 바꾸면 모든 형제가 지워지기 때문이다.
|
||||
|
||||
**A `move` needs permission on both ends.** Checking only the destination would let you relocate
|
||||
data out of a field you may not touch.
|
||||
**`move`는 양쪽 끝의 권한이 필요하다.** 목적지만 검사하면 건드릴 수 없는 필드의 데이터를 옮겨 낼 수 있다.
|
||||
|
||||
**Limits.** At most 100 operations, pointer depth at most 16, merge-patch nesting depth at most 32.
|
||||
The first two multiply — each operation walks its pointer over a document the server deep-copied
|
||||
first.
|
||||
**한도.** 연산은 최대 100개, pointer 깊이는 최대 16, merge patch 중첩 깊이는 최대 32. 앞의 둘은 곱해진다. 연산마다
|
||||
서버가 먼저 깊이 복사한 문서 위로 pointer를 따라 걷는다.
|
||||
|
||||
## Atomicity
|
||||
## 원자성
|
||||
|
||||
A JSON Patch document applies entirely or not at all. Every operation runs against a working copy;
|
||||
the resource is not touched until all of them have succeeded and the result has passed full
|
||||
validation.
|
||||
JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고
|
||||
결과가 전체 검증을 통과하기 전에는 자원을 건드리지 않는다.
|
||||
|
||||
This is what makes `test` useful. A client putting a `test` first is relying on nothing after it
|
||||
having happened when the test fails, and that reliance holds:
|
||||
그래서 `test`가 쓸모 있다. `test`를 맨 앞에 둔 client는 test가 실패하면 그 뒤의 어떤 것도 일어나지 않았다고 믿고,
|
||||
그 믿음은 지켜진다.
|
||||
|
||||
```json
|
||||
[
|
||||
@@ -63,18 +53,16 @@ having happened when the test fails, and that reliance holds:
|
||||
]
|
||||
```
|
||||
|
||||
A failed `test` is **409**, not 400: the document was well-formed and permitted, and the resource
|
||||
simply was not in the state you expected. Re-read and retry. The response names the pointer that
|
||||
failed and does not return the server's value — returning it would make `test` a read primitive for
|
||||
fields you may not read.
|
||||
실패한 `test`는 400이 아니라 **409**다. 문서는 형식이 맞고 허락됐지만, 자원이 기대한 상태가 아니었을 뿐이다. 다시
|
||||
읽고 재시도한다. 응답은 실패한 pointer의 이름을 대고 서버의 값은 돌려주지 않는다. 돌려주면 `test`가 읽어서는 안 되는
|
||||
필드를 읽는 도구가 된다.
|
||||
|
||||
## Validation
|
||||
## 검증
|
||||
|
||||
The patched result is validated as a whole document, not field by field. A patch whose individual
|
||||
fields are all valid can produce an object that is not — two fields that must agree, a state
|
||||
transition that is not allowed — and validating only what changed sees none of it.
|
||||
patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검증한다. 필드 하나하나는 모두 유효한 patch가 유효하지 않은
|
||||
객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도
|
||||
보지 못한다.
|
||||
|
||||
## Preconditions
|
||||
## 선행 조건
|
||||
|
||||
Patch routes require `If-Match`. A partial update against a resource that moved underneath you
|
||||
applies your changes to a version you never saw.
|
||||
patch route는 `If-Match`를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다.
|
||||
|
||||
+184
-211
@@ -1,284 +1,257 @@
|
||||
# Web platform — repository adaptation
|
||||
# Web 플랫폼 — 저장소 적응
|
||||
|
||||
The inbound HTTP API execution platform design
|
||||
(`docs/history/packages/web-superpowers-package/docs/superpowers/specs/2026-08-13-web-inbound-http-api-execution-platform-design.md`)
|
||||
was written against a standalone repository. Four of its assumptions do not hold here, and this
|
||||
document records what each became and why, so a reader comparing the design to the tree is not left
|
||||
guessing whether a difference is a decision or a mistake.
|
||||
inbound HTTP API 실행 플랫폼 설계서
|
||||
(`docs/history/packages/web-superpowers-package/docs/superpowers/specs/2026-08-13-web-inbound-http-api-execution-platform-design.md`)는
|
||||
따로 선 저장소를 전제로 썼다. 그 가정 중 넷이 여기서는 맞지 않는다. 이 문서는 각각이 무엇이 됐고 왜 그런지 적는다.
|
||||
설계와 트리를 비교하는 사람이 차이가 결정인지 실수인지 짐작하지 않게 하려는 것이다.
|
||||
|
||||
> **2026-09-25 (D4, Wave 2 W2-3).** The template is servlet (Spring MVC) on virtual threads. The
|
||||
> WebFlux twin, the second-generation problem-document/budget/throttle/admission platform, the
|
||||
> durable-operation HTTP projection and the in-leaf module-boundary check were removed. HTTP errors
|
||||
> are the `Envelope` written by `GlobalExceptionHandler`. What was removed, and the commit it last
|
||||
> existed in, is listed in `docs/capability-status.md` ("제거된 코드").
|
||||
> **2026-09-25 (D4, Wave 2 W2-3).** 템플릿은 virtual thread 위의 servlet(Spring MVC)이다. WebFlux 쌍, 2세대
|
||||
> problem-document/budget/throttle/admission 플랫폼, 지속 작업 HTTP 투영, leaf 안의 모듈 경계 검사를 지웠다. HTTP
|
||||
> 오류는 `GlobalExceptionHandler`가 쓰는 `Envelope`다. 무엇을 지웠고 마지막으로 있던 commit이 무엇인지는
|
||||
> `docs/capability-status.md`(「제거된 코드」)에 있다.
|
||||
|
||||
## 1. Twenty-three Gradle modules became sub-packages of one leaf
|
||||
## 1. Gradle 모듈 스물셋이 leaf의 하위 package가 됐다
|
||||
|
||||
The design lays the platform out as `modules/web/web-core-api`, `web-contract`, `web-mvc` and so on.
|
||||
This repository's `src/config/architecture/modules.json` is a fail-closed registry that owns the leaf
|
||||
list, and adding twenty-three leaves to it is an architecture decision the design cannot make on the
|
||||
repository's behalf. The JPA and GraphQL platforms reached the same fork and resolved it the same
|
||||
way, so this is the established answer rather than a new one.
|
||||
설계는 플랫폼을 `modules/web/web-core-api`, `web-contract`, `web-mvc` 같은 식으로 배치한다. 이 저장소의
|
||||
`src/config/architecture/modules.json`은 leaf 목록을 가진, 닫힌 쪽으로 실패하는 registry다. leaf 스물셋을 더하는
|
||||
것은 설계가 저장소 대신 내릴 수 없는 아키텍처 결정이다. JPA와 GraphQL 플랫폼도 같은 갈림길에서 같은 답을 냈다.
|
||||
그래서 이것은 새 답이 아니라 이미 정한 답이다.
|
||||
|
||||
A Gradle dependency gate cannot see inside a leaf. The in-leaf module map that used to check the
|
||||
package edges (`WebStableModule`) was removed with the second-generation platform; the ArchUnit
|
||||
rules in `testkit/arch` (`WebArchitectureRules`) are what remains.
|
||||
설계 모듈은 지금 web leaf(`adapter:inbound:web`)와 Advanced leaf(`adapter:inbound:web-advanced`)의 package로
|
||||
나뉘어 있다. Gradle 의존성 게이트는 leaf 안을 보지 못한다. package edge를 검사하던 leaf 안의 모듈 지도
|
||||
(`WebStableModule`)는 2세대 플랫폼과 함께 지웠다. 남은 것은 web leaf testFixtures의 `testkit/arch`에 있는 ArchUnit
|
||||
규칙(`WebArchitectureRules`)이다.
|
||||
|
||||
| Design module | Package under `dev.caskeleton.adapter.inbound.web` | Status |
|
||||
| 설계 모듈 | 지금 있는 곳(package는 `dev.caskeleton.adapter.inbound.web` 아래) | 상태 |
|
||||
| --- | --- | --- |
|
||||
| `web-core-api` | `core` | planned (Task 2+) |
|
||||
| `web-contract` | `contract` | planned |
|
||||
| `web-error` | `error` | present |
|
||||
| `web-pagination` | `pagination` | present |
|
||||
| `web-idempotency` | `idempotency` | present |
|
||||
| `web-idempotency-jpa` | `idempotency.jpa` | planned |
|
||||
| `web-idempotency-redis` | `idempotency.redis` | planned |
|
||||
| `web-versioning` | `versioning` | planned |
|
||||
| `web-security-integration` | `auth`, `authz` | present |
|
||||
| `web-observability` | `observability` | present |
|
||||
| `web-openapi` | `openapi` | planned |
|
||||
| `web-mvc` | `mvc` | planned |
|
||||
| `web-webflux` | — | removed (D4: servlet only) |
|
||||
| `web-admin` | `admin` | planned |
|
||||
| `web-operation-jpa` | `operation.jpa` | planned |
|
||||
| `web-operation-messaging` | `operation.messaging` | planned |
|
||||
| `web-spring-boot-starter-mvc` | `autoconfigure.mvc` | planned |
|
||||
| `web-spring-boot-starter-webflux` | — | removed (D4: servlet only) |
|
||||
| `web-testkit-*` | `testkit`, `testkit.mvc` | present |
|
||||
| — | `conditional`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | present, pre-dates the design |
|
||||
| — | `fileserver.*`, `notification.*` | present, feature integrations rather than platform modules |
|
||||
| `web-core-api` | web leaf `core` | 있음 |
|
||||
| `web-contract` | web-advanced leaf `advanced.contract` | 있음(라이브러리) |
|
||||
| `web-error` | web leaf `error` | 있음 |
|
||||
| `web-pagination` | web leaf `pagination` | 있음 |
|
||||
| `web-idempotency` | web-advanced leaf `advanced.idempotency`. 저장소 SPI는 `application-core`(6절) | 있음 |
|
||||
| `web-idempotency-jpa` | web 쪽에는 없다. `persistence-jpa`의 `PostgreSqlIdempotencyStore`(6절) | 다른 곳에 있음 |
|
||||
| `web-idempotency-redis` | web 쪽에는 없다. `cache-redis`의 `RedisIdempotencyStoreAdapter`(6절) | 다른 곳에 있음 |
|
||||
| `web-versioning` | web-advanced leaf `advanced.versioning` | 있음(라이브러리) |
|
||||
| `web-security-integration` | web leaf `auth`, `authz` | 있음 |
|
||||
| `web-observability` | web leaf `observability` | 있음 |
|
||||
| `web-openapi` | web leaf `config`의 `OpenApiContractConfig`(springdoc, 3.1), web-advanced leaf `advanced.openapi`(3.2 생성기) | 있음 |
|
||||
| `web-mvc` | web leaf `mvc` | 있음 |
|
||||
| `web-webflux` | — | 지움(D4: servlet만) |
|
||||
| `web-admin` | web-advanced leaf `advanced.admin` | 있음(라이브러리) |
|
||||
| `web-operation-jpa` | web 쪽에는 없다. `persistence-jpa`의 `operation`(7절) | 다른 곳에 있음 |
|
||||
| `web-operation-messaging` | — | 없음 |
|
||||
| `web-spring-boot-starter-mvc` | web leaf `mvc.autoconfigure`(`WebAdapterAutoConfiguration`) | 있음 |
|
||||
| `web-spring-boot-starter-webflux` | — | 지움(D4: servlet만) |
|
||||
| `web-testkit-*` | web leaf testFixtures의 `testkit`(`arch`, `fault`, `mvc`, `order`, `performance`) | 있음 |
|
||||
| — | web leaf `conditional`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | 있음, 설계보다 먼저 있었다 |
|
||||
| — | web leaf `operation`(지속 작업 HTTP 면, 7절) | 있음 |
|
||||
| — | 파일서버·알림 HTTP 면 | 따로 된 leaf `adapter:inbound:web-fileserver`, `adapter:inbound:web-notification` |
|
||||
|
||||
## 2. Root package
|
||||
|
||||
The design uses `io.backend.skeleton.web`. This repository's package root is
|
||||
`dev.caskeleton.adapter.inbound.web`, and the registry, the ArchUnit rules and the composition root's
|
||||
component scan are all written against it.
|
||||
설계는 `io.backend.skeleton.web`을 쓴다. 이 저장소의 package root는 `dev.caskeleton.adapter.inbound.web`이고,
|
||||
registry, ArchUnit 규칙, 조립 루트의 component scan이 모두 그것을 기준으로 쓰였다.
|
||||
|
||||
## 3. Gradle DSL
|
||||
|
||||
The design's snippets are Kotlin DSL. Every build file in this repository is Groovy DSL, and
|
||||
`src/build-logic` carries the shared convention plugins the leaf inherits. The build logic is
|
||||
translated, not copied.
|
||||
설계의 조각은 Kotlin DSL이다. 이 저장소의 빌드 파일은 모두 Groovy DSL이고, `src/build-logic`이 leaf가 물려받는 공용
|
||||
convention plugin을 가진다. 빌드 로직은 복사하지 않고 옮겨 썼다.
|
||||
|
||||
## 4. Spring Boot baseline
|
||||
## 4. Spring Boot 기준
|
||||
|
||||
The design names "Spring Boot 4.1 BOM". This repository's baseline is **4.0.8** — see
|
||||
`.vscode/settings.json` for why the 4.1 minor line is a planned migration rather than a currency
|
||||
fix. Where the design depends on a 4.1-only API the difference is recorded at the call site rather
|
||||
than silently absorbed.
|
||||
설계는 「Spring Boot 4.1 BOM」을 든다. 이 저장소의 기준은 Spring Boot 4.0 계열이다(정확한 버전은
|
||||
`src/gradle/libs.versions.toml`의 `springBoot`). 설계가 4.1에만 있는 API에 기대는 곳은 그 차이를 조용히 흡수하지 않고
|
||||
호출하는 자리에 적는다.
|
||||
|
||||
## 5. Sample application
|
||||
## 5. 샘플 애플리케이션
|
||||
|
||||
설계의 `examples/web-platform-sample`에 해당하는 모듈은 없다. 그 역할을 하던 샘플 leaf는 2026-11-07에
|
||||
지웠고, 그 안의 OpenAPI 드리프트 검사와 실서버 계약 lane도 함께 사라졌다. 예시는 `docs/manual/`과
|
||||
`scripts/new-feature.sh` 출력이 맡는다.
|
||||
|
||||
## 6. Idempotency: the design's store SPI is already owned by `application-core`
|
||||
## 6. 멱등성: 설계의 저장소 SPI는 이미 `application-core`가 가진다
|
||||
|
||||
The design gives `web-idempotency` its own `IdempotencyStore`, `IdempotencyRecord`,
|
||||
`IdempotencyState`, `IdempotencyScope` and `RequestFingerprint`. This repository already has the
|
||||
equivalents in `application-core/idempotency` — `IdempotencyStorePort`, `IdempotencyState`,
|
||||
`IdempotencyScopeDigest` and `RequestFingerprint` — with two provider stores behind the port:
|
||||
PostgreSQL (`PostgreSqlIdempotencyStore` in `persistence-jpa`) and Redis
|
||||
(`RedisIdempotencyStoreAdapter` in `cache-redis`), selected by
|
||||
`app.capabilities.idempotency.provider`. That is what the design's Tasks 39 and 40 ask for,
|
||||
built in the direction the registry permits.
|
||||
설계는 `web-idempotency`에 자기 `IdempotencyStore`, `IdempotencyRecord`, `IdempotencyState`, `IdempotencyScope`,
|
||||
`RequestFingerprint`를 준다. 이 저장소에는 이미 `application-core/idempotency`에 같은 것들이 있다:
|
||||
`IdempotencyStorePort`, `IdempotencyState`, `IdempotencyScopeDigest`, `RequestFingerprint`. port 뒤에는 provider
|
||||
저장소가 둘 있다. PostgreSQL(`persistence-jpa`의 `PostgreSqlIdempotencyStore`)과 Redis(`cache-redis`의
|
||||
`RedisIdempotencyStoreAdapter`)이고, `app.capabilities.idempotency.provider`로 고른다. 설계의 Task 39와 40이 요구하는
|
||||
것이 이것이고, registry가 허락하는 방향으로 만들었다.
|
||||
|
||||
Implementing the design's SPI literally would have required
|
||||
`adapter-outbound-persistence-jpa → adapter-inbound-web`, an edge the registry forbids and one that
|
||||
points the wrong way regardless: the store is an application concern that two transports could
|
||||
share, not something the HTTP layer owns.
|
||||
설계의 SPI를 글자 그대로 구현하려면 `adapter-outbound-persistence-jpa → adapter-inbound-web` edge가 필요했다.
|
||||
registry가 금하는 edge이고, 어쨌든 방향이 틀렸다. 저장소는 두 transport가 함께 쓸 수 있는 애플리케이션 관심사이지,
|
||||
HTTP 계층이 가질 것이 아니다.
|
||||
|
||||
So the web leaf keeps only the part that is genuinely HTTP: JSON encoding of a replayed
|
||||
application result. Claiming, scope, fingerprint construction and replay policy remain at the
|
||||
application use-case boundary.
|
||||
그래서 web 쪽에는 정말 HTTP인 부분만 남는다: 다시 보내는 애플리케이션 결과의 JSON 인코딩이고,
|
||||
`adapter:inbound:web-advanced`에 있다. 잡기, 범위, fingerprint 만들기, 다시 보내기 정책은 애플리케이션 use case
|
||||
경계에 남는다.
|
||||
|
||||
| Design concern | Here |
|
||||
| 설계 관심사 | 여기 |
|
||||
| --- | --- |
|
||||
| store / record / scope / claim / replay | `application-core/idempotency` |
|
||||
| request fingerprint policy | application use case, because only the use case knows which fields define the same work |
|
||||
| `Idempotency-Key` extraction | concrete inbound endpoint that opts into idempotency |
|
||||
| replay JSON encoding | `adapter-inbound-web-advanced/idempotency/JsonIdempotentResponseCodec` |
|
||||
| 요청 fingerprint 정책 | 애플리케이션 use case. 어떤 필드가 같은 일을 정하는지는 use case만 안다 |
|
||||
| `Idempotency-Key` 꺼내기 | 멱등성을 골라 쓰는 구체 inbound endpoint |
|
||||
| 다시 보내기 JSON 인코딩 | `adapter-inbound-web-advanced/idempotency/JsonIdempotentResponseCodec` |
|
||||
|
||||
This avoids two authorities for “same request”. The HTTP adapter does not run its own database
|
||||
replay policy; it translates the transport input into the application idempotency context and lets
|
||||
the use case own duplicate execution.
|
||||
이렇게 하면 「같은 요청」을 정하는 권한이 둘이 되지 않는다. HTTP 어댑터는 자기 DB 다시 보내기 정책을 돌리지 않는다.
|
||||
transport 입력을 애플리케이션 멱등성 context로 옮기고, 중복 실행은 use case가 갖게 한다.
|
||||
|
||||
## 7. Durable operations: the design's `web-operation-jpa` cannot exist here
|
||||
## 7. 지속 작업: 설계의 `web-operation-jpa`는 여기 있을 수 없다
|
||||
|
||||
The design gives the web platform its own persistence module — `modules/web/web-operation-jpa` —
|
||||
holding a JPA store for long-running operations, with the port
|
||||
(`DurableOperationStore`) in `web-core-api` beside `WebProblem`.
|
||||
설계는 web 플랫폼에 자기 persistence 모듈 `modules/web/web-operation-jpa`를 준다. 오래 도는 작업을 위한 JPA 저장소를
|
||||
담고, port(`DurableOperationStore`)는 `web-core-api`에 `WebProblem` 옆에 둔다.
|
||||
|
||||
`src/config/architecture/modules.json` forbids both halves of that:
|
||||
`src/config/architecture/modules.json`은 그 두 절반을 모두 금한다.
|
||||
|
||||
- `:adapter:inbound:web` may depend only on `domain-core`, `application-core` and
|
||||
`shared-contract`, so the web leaf cannot take a JPA dependency.
|
||||
- `:adapter:outbound:persistence-jpa` is an outbound adapter and cannot depend on an inbound one,
|
||||
so a JPA store cannot see a web type.
|
||||
- `:adapter:inbound:web`은 registry가 허락한 leaf에만 의존할 수 있다(`domain-core`, `application-core`,
|
||||
`shared-contract`, `adapter-outbound-support`). 그래서 web leaf는 JPA 의존성을 가질 수 없다.
|
||||
- `:adapter:outbound:persistence-jpa`는 outbound 어댑터라 inbound 어댑터에 의존할 수 없다. 그래서 JPA 저장소는 web
|
||||
타입을 볼 수 없다.
|
||||
|
||||
This is the same shape as §6 and takes the same resolution — the one the repository already used
|
||||
for idempotency, where `IdempotencyStorePort` lives in `application-core` and
|
||||
`PostgreSqlIdempotencyStore` in `persistence-jpa`:
|
||||
6절과 같은 모양이고 같은 해결을 쓴다. 저장소가 멱등성에 이미 쓴 해결이다. 거기서 `IdempotencyStorePort`는
|
||||
`application-core`에, `PostgreSqlIdempotencyStore`는 `persistence-jpa`에 있다.
|
||||
|
||||
| Design type | Here |
|
||||
| 설계 타입 | 여기 |
|
||||
| --- | --- |
|
||||
| `DurableOperationStore` | `application-core/operation/DurableOperationStorePort` |
|
||||
| `OperationSubmission` | `application-core/operation/DurableOperationSubmission` |
|
||||
| the stored operation | `application-core/operation/DurableOperation` |
|
||||
| the lease | `application-core/operation/OperationLease` |
|
||||
| the stored failure | `application-core/operation/OperationFailure` — a code and an already-safe message, never an exception |
|
||||
| 저장한 작업 | `application-core/operation/DurableOperation` |
|
||||
| lease | `application-core/operation/OperationLease` |
|
||||
| 저장한 실패 | `application-core/operation/OperationFailure` — code와 이미 안전한 메시지. 예외가 아니다 |
|
||||
| `JpaDurableOperationStore`, `JpaOperationEntity`, `V002__web_operation.sql` | `persistence-jpa/operation/*`, `db/migration/postgresql/V11__durable_operation.sql` |
|
||||
| `OperationResource`, `OperationStatus`, `OperationProgress`, `OperationId` | removed 2026-09-25 — the web `operationasync` projection and `/api/v1/operations` controller had no production wiring and published failures only as `WebProblem` |
|
||||
| `OperationResource`, `OperationStatus`, `OperationProgress`, `OperationId` | 2026-09-25에 지움 — web `operationasync` 투영과 `/api/v1/operations` controller는 운영 연결이 없었고 실패를 `WebProblem`으로만 내보냈다 |
|
||||
|
||||
The split is not only a registry workaround; it puts each half where its invariants belong. A
|
||||
problem document is an HTTP concept and has no business being persisted, so the stored failure is a
|
||||
code plus a safe message.
|
||||
이 나눔은 registry 우회만이 아니다. 각 절반을 그 불변식이 속한 곳에 둔다. problem document는 HTTP 개념이고 저장될
|
||||
이유가 없다. 그래서 저장한 실패는 code와 안전한 메시지다.
|
||||
|
||||
The HTTP surface was added back on 2026-09-25 (owner decision 15) as a thin transport over the
|
||||
application use cases: `adapter:inbound:web` `operation/DurableOperationController` —
|
||||
`POST /operations` (202 + `Location`), `GET /operations/{id}`, `DELETE /operations/{id}` (202),
|
||||
answers in the `Envelope` contract, and a caller's operation that is not theirs is the same 404
|
||||
(`OPERATION_NOT_FOUND`) as one that does not exist. The controller and the three use cases are
|
||||
assembled by `composition:durable-operation` (`DurableOperationAutoConfiguration`), which turns on only
|
||||
when the operation store and the outbox append port exist (the JPA module with
|
||||
`app.outbox.enabled=true`). Submit and cancel need `operation:submit` / `operation:cancel`
|
||||
(that module's `config/module-defaults/durable-operation.yml` grants both to the `operation-submit`
|
||||
role).
|
||||
HTTP 면은 2026-09-25에 애플리케이션 use case 위의 얇은 transport로 다시 더했다(소유자 결정 15).
|
||||
`adapter:inbound:web` `operation/DurableOperationController`다.
|
||||
|
||||
The state machine is enforced three times on purpose: in `DurableOperation`'s constructor, in the
|
||||
`CHECK` constraints of `V11__durable_operation.sql`, and in the `WHERE` clause of every statement
|
||||
that changes a row. The constructor catches application bugs, the constraints catch any other
|
||||
writer, and the predicates make each transition atomic — a worker whose lease lapsed while it was
|
||||
still working cannot record a result over the worker that took over, because its `UPDATE` matches
|
||||
no row and it learns that from the affected count.
|
||||
- `POST /operations`(202 + `Location`), `GET /operations/{id}`, `DELETE /operations/{id}`(202).
|
||||
- `Envelope` 계약으로 답한다.
|
||||
- 호출자의 것이 아닌 작업은 없는 작업과 같은 404(`OPERATION_NOT_FOUND`)다.
|
||||
|
||||
## 8. Budget enforcement: what the edge stops and what the application stops
|
||||
controller와 use case 셋은 `composition:durable-operation`(`DurableOperationAutoConfiguration`)이 조립한다. 작업
|
||||
저장소와 outbox append port가 있을 때만 켜진다(JPA 모듈과 `app.outbox.enabled=true`). 제출과 취소에는
|
||||
`operation:submit` / `operation:cancel`이 필요하다(그 모듈의 `config/module-defaults/durable-operation.yml`이 둘 다
|
||||
`operation-submit` role에 준다).
|
||||
|
||||
> **Removed 2026-09-25.** The servlet budget filter (`WebMvcBudgetFilter`) and its problem mapping
|
||||
> were deleted with the second-generation platform. The shipped application no longer enforces the
|
||||
> application column below; the `budget` catalog (`WebRequestBudget`, `WebBudgetCatalog`) remains as
|
||||
> library code in `adapter:inbound:web-advanced`, and its unused meter (`WebBudgetMeter` and its
|
||||
> outcome/violation types) was removed. The edge column still applies.
|
||||
상태 기계는 일부러 세 번 강제한다: `DurableOperation`의 생성자, `V11__durable_operation.sql`의 `CHECK` 제약, 행을 바꾸는
|
||||
모든 문의 `WHERE` 절. 생성자는 애플리케이션 결함을 잡고, 제약은 다른 쓰는 쪽을 잡고, 조건은 전이마다 원자적으로
|
||||
만든다. 일하는 동안 lease가 끝난 worker는 이어받은 worker 위에 결과를 기록할 수 없다. 그 `UPDATE`가 행에 맞지 않고,
|
||||
worker는 바뀐 행 수로 그것을 안다.
|
||||
|
||||
The design (Task 49) requires that the difference between an edge proxy's limits and the
|
||||
application's own be written down rather than discovered during an incident. Two limits on the same
|
||||
dimension always exist, they are never equal, and which one fires decides what the caller sees.
|
||||
## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것
|
||||
|
||||
| Dimension | Edge (nginx) | Application | Who answers when crossed |
|
||||
> **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다.
|
||||
> 내보내는 애플리케이션은 더는 아래 애플리케이션 칸을 강제하지 않는다. `budget` 목록(`WebRequestBudget`,
|
||||
> `WebBudgetCatalog`)은 `adapter:inbound:web-advanced`에 라이브러리 코드로 남고, 쓰이지 않던 meter(`WebBudgetMeter`와
|
||||
> 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다.
|
||||
|
||||
설계(Task 49)는 edge proxy의 한도와 애플리케이션 자체 한도의 차이를 장애 중에 발견하지 말고 적어 두라고 요구한다.
|
||||
같은 차원에 한도는 늘 둘 있고, 둘은 결코 같지 않으며, 어느 쪽이 걸리는지가 호출자가 보는 것을 정한다.
|
||||
|
||||
| 차원 | Edge (nginx) | 애플리케이션 | 넘으면 누가 답하나 |
|
||||
| --- | --- | --- | --- |
|
||||
| Request line / URI | `large_client_header_buffers` (default 8k) | `maxUriBytes` | Edge first — nginx answers 414 with its own HTML |
|
||||
| Request headers | `large_client_header_buffers` | `maxHeaderBytes` | Edge first — nginx 400, no problem document |
|
||||
| Request body | `client_max_body_size` (default 1m) | `maxBodyBytes` (platform ceiling 8 MiB) | Whichever is smaller; nginx answers 413 with HTML |
|
||||
| Query parameter count | not enforced | `maxQueryParameters` | Application, always |
|
||||
| JSON depth / array size | not enforced | `maxJsonDepth`, `maxArrayElements` | Application, always |
|
||||
| Execution time | `proxy_read_timeout` (default 60s) | `maxExecutionTime` (ceiling 2 min) | Edge first if the platform's is larger |
|
||||
| Response size | not enforced | `maxResponseBytes` (ceiling 32 MiB) | Application, always |
|
||||
| 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 |
|
||||
| 요청 헤더 | `large_client_header_buffers` | `maxHeaderBytes` | edge가 먼저 — nginx 400, problem document 없음 |
|
||||
| 요청 본문 | `client_max_body_size`(기본 1m) | `maxBodyBytes`(플랫폼 상한 8 MiB) | 더 작은 쪽. nginx는 HTML로 413 |
|
||||
| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 늘 애플리케이션 |
|
||||
| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 |
|
||||
| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | 플랫폼 쪽이 더 크면 edge가 먼저 |
|
||||
| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 늘 애플리케이션 |
|
||||
|
||||
Two consequences worth stating, because both are counterintuitive:
|
||||
둘 다 직관과 반대라서 적어 둘 만한 결과가 둘 있다.
|
||||
|
||||
**An edge limit below the application's means clients never see the application's error body.**
|
||||
nginx answers its own HTML error page, so a client that branches on `error.code` gets a body it
|
||||
cannot parse.
|
||||
Where a dimension matters to clients, the edge limit must be set *above* the application's so the
|
||||
application is the one that refuses.
|
||||
**edge 한도가 애플리케이션 한도보다 낮으면 client는 애플리케이션의 오류 본문을 절대 보지 못한다.** nginx가 자기
|
||||
HTML 오류 쪽을 답하므로, `error.code`로 분기하는 client는 파싱할 수 없는 본문을 받는다. client에게 중요한 차원이면
|
||||
edge 한도를 애플리케이션보다 *높게* 두어 애플리케이션이 거부하게 한다.
|
||||
|
||||
**An edge limit above the application's is not redundant.** It is the only thing standing between
|
||||
the process and a body large enough to matter before the application's own meter has counted it.
|
||||
Both belong; only their ordering is a decision.
|
||||
**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션의 meter가 세기 전에 문제가 될 만큼 큰 본문과
|
||||
프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다.
|
||||
|
||||
## 9. The Nginx lane (removed 2026-09-25)
|
||||
## 9. Nginx lane (2026-09-25에 지움)
|
||||
|
||||
The `webNginxProxyTest` lane ran the forwarded-header library (`proxy`, `http.External*`) behind a
|
||||
Testcontainers `nginx:1.27-alpine`. That library was a second way of doing what the shipped path
|
||||
does with `server.forward-headers-strategy`, so the library and its lane were removed together
|
||||
(`docs/capability-status.md`, "제거된 코드").
|
||||
`webNginxProxyTest` lane은 forwarded header 라이브러리(`proxy`, `http.External*`)를 Testcontainers
|
||||
`nginx:1.27-alpine` 뒤에서 돌렸다. 그 라이브러리는 내보내는 경로가 `server.forward-headers-strategy`로 하는 일을 다른
|
||||
방식으로 하는 것이었다. 그래서 라이브러리와 lane을 함께 지웠다(`docs/capability-status.md`, 「제거된 코드」).
|
||||
|
||||
One finding from that lane still applies to any Nginx in front of this service. Nginx's
|
||||
inheritance rule for array directives is *replacement*: a single `proxy_set_header` inside a
|
||||
`location` discards every `proxy_set_header` inherited from `server`. Setting the forwarded headers
|
||||
once at `server` level and adding only `X-Forwarded-Prefix` per `location` therefore sends none of
|
||||
the others, and the application falls back to the upstream's own `Host`. Keep the forwarded headers
|
||||
in one included file and `include` it in every `location`.
|
||||
그 lane에서 얻은 발견 하나는 이 서비스 앞의 어떤 Nginx에도 여전히 맞다. Nginx의 배열 지시어 상속 규칙은
|
||||
*교체*다. `location` 안의 `proxy_set_header` 하나가 `server`에서 물려받은 `proxy_set_header`를 모두 버린다. 그래서
|
||||
forwarded header를 `server` 수준에 한 번 두고 `location`마다 `X-Forwarded-Prefix`만 더하면 나머지는 하나도 보내지
|
||||
않고, 애플리케이션은 upstream 자신의 `Host`로 물러선다. forwarded header는 include 파일 하나에 두고 모든
|
||||
`location`에서 `include`한다.
|
||||
|
||||
## Advanced capabilities
|
||||
## Advanced capability
|
||||
|
||||
The Advanced expansion plan asks for eleven Gradle modules under `modules/web-advanced/`. They are
|
||||
packages under `advanced.**` in this leaf, for the reason the Stable platform is one leaf:
|
||||
`src/config/architecture/modules.json` is fail-closed and owns the leaf list, and eleven entries to
|
||||
satisfy a directory layout is a registry change rather than an architecture one.
|
||||
Advanced 확장 계획서는 `modules/web-advanced/` 아래에 Gradle 모듈 열하나를 요구한다. 여기서는 따로 된 leaf
|
||||
`adapter:inbound:web-advanced`의 `advanced.**` package다. Stable 플랫폼이 leaf 하나인 것과 같은 이유다.
|
||||
`src/config/architecture/modules.json`이 닫힌 쪽으로 실패하고 leaf 목록을 가진다. 폴더 배치를 맞추려고 항목 열하나를
|
||||
더하는 것은 아키텍처 변경이 아니라 registry 변경이다.
|
||||
|
||||
What the design wanted from the separation is enforced instead by two machine checks:
|
||||
설계가 나눔으로 얻으려던 것은 대신 registry가 강제한다. registry는 `adapter-inbound-web-advanced →
|
||||
adapter-inbound-web` 방향만 허락한다. 그래서 Stable 클래스가 Advanced 타입을 이름 대면 Gradle 의존성 게이트
|
||||
(`verifyCleanArchitectureDependencies`)가 빌드를 실패시킨다. feature flag는 bean을 만들지 정할 뿐 컴파일 시점 edge에는
|
||||
아무것도 하지 않는다. 그런 edge 하나면 Advanced 없이는 Stable을 빌드할 수 없다.
|
||||
|
||||
- **`WEB-ARCH-ADV`** in `WebArchitectureRules.stableDoesNotDependOnAdvanced()` fails the build when a
|
||||
Stable class names an Advanced type. A feature flag decides whether a bean is created; it does
|
||||
nothing about a compile-time edge, and one such edge makes Stable unbuildable without Advanced.
|
||||
`advanced.patch`와 `advanced.codec`은 framework에 묶이고, 묶일 수밖에 없었다. 앞의 것은 Jackson의 tree 모델 때문이다.
|
||||
merge patch의 「null은 지움」은 Java 객체로 표현할 수 없어서 applier가 node 위에서 일한다. 뒤의 것은
|
||||
`XMLInputFactory` 때문이다. `advanced.stream.encoding`을 `advanced.stream`에서 떼어 낸 것도 같은 이유다. framing은
|
||||
직렬화하고, 직렬화는 Jackson에 묶인다.
|
||||
|
||||
`advanced.patch` and `advanced.codec` bind to a framework and had to: Jackson's tree model is the
|
||||
reason for the first — a merge patch's null-means-delete has no representation in a Java object, so
|
||||
the applier works on nodes — and `XMLInputFactory` is the reason for the second.
|
||||
`advanced.stream.encoding` is separated from `advanced.stream` for the same reason: framing
|
||||
serializes, and serializing binds to Jackson.
|
||||
### 복사하지 않고 고친 것
|
||||
|
||||
### What was adapted rather than copied
|
||||
**`WebStreamErrorPolicy`의 factory 메서드는 `startOver` / `resumeFromPosition` / `nothingToDo`다.** 설계의 이름은
|
||||
record 자신의 accessor와 겹쳤고, Java가 그것을 거부한다.
|
||||
|
||||
**`WebStreamErrorPolicy`'s factory methods are `startOver` / `resumeFromPosition` / `nothingToDo`.**
|
||||
The design's names collided with the record's own accessors, which Java rejects.
|
||||
**codec backend는 compile 전용이고, 그 이유를 알아내는 데 조립 루트 하나가 깨졌다.** `WebCborMapperFactory`와
|
||||
`WebXmlMapperFactory`를 구현했고, 실패 모드를 지닌 부분도 함께 구현했다.
|
||||
|
||||
**The codec backends are compile-only, and finding out why cost a broken composition root.**
|
||||
`WebCborMapperFactory` and `WebXmlMapperFactory` are implemented, along with the parts that carry
|
||||
the failure modes: `SecureXmlInputFactory` (the DTD and external-entity defaults, both of which
|
||||
produce no error when they fire), `CodecBudget` (per representation, because a megabyte of CBOR can
|
||||
declare an array of a billion elements in a handful of bytes), and `RepresentationNegotiationPolicy`
|
||||
(three gates, because an `Accept` header is not evidence the route was tested against that codec).
|
||||
- `SecureXmlInputFactory`: DTD와 외부 entity 기본값. 둘 다 터져도 오류를 내지 않는다.
|
||||
- `CodecBudget`: 표현마다 둔다. CBOR 1메가바이트는 몇 바이트로 원소 10억 개짜리 배열을 선언할 수 있다.
|
||||
- `RepresentationNegotiationPolicy`: 관문 셋. `Accept` 헤더는 그 route가 그 codec으로 시험됐다는 증거가 아니다.
|
||||
|
||||
`jackson-dataformat-cbor` and `jackson-dataformat-xml` were declared `implementation` first, so that
|
||||
a missing backend could not surface as a `NoClassDefFoundError` at the first request that negotiated
|
||||
one. That reasoning was wrong about what the jars do. Spring Boot's Jackson auto-configuration
|
||||
registers an `xmlMapper` and a `cborMapper` bean the moment each backend is on the runtime
|
||||
classpath, and Spring registers an XML message converter with it. Two things followed, and only the
|
||||
first was noisy:
|
||||
처음에는 `jackson-dataformat-cbor`와 `jackson-dataformat-xml`을 `implementation`으로 선언했다. backend가 없을 때 그것을
|
||||
협상한 첫 요청에서 `NoClassDefFoundError`로 드러나지 않게 하려는 것이었다. jar가 하는 일에 대해 그 판단은 틀렸다.
|
||||
Spring Boot의 Jackson auto-configuration은 각 backend가 런타임 classpath에 올라오는 순간 `xmlMapper`와 `cborMapper`
|
||||
bean을 등록하고, Spring은 그것으로 XML 메시지 변환기를 등록한다. 두 가지가 뒤따랐고, 시끄러운 것은 첫째뿐이었다.
|
||||
|
||||
- The composition root held three `ObjectMapper` beans — `webStrictObjectMapper`, `xmlMapper`,
|
||||
`cborMapper` — so every `@Autowired ObjectMapper` became ambiguous and the application would not
|
||||
start. Six `app-bootstrap` tests failed with `UnsatisfiedDependencyException`.
|
||||
- Every deployment silently began accepting `application/xml` request bodies. An XXE surface,
|
||||
acquired by adding a dependency, on a capability that is supposed to be off unless a deployment
|
||||
names it.
|
||||
- 조립 루트가 `ObjectMapper` bean 셋(`webStrictObjectMapper`, `xmlMapper`, `cborMapper`)을 가졌다. 그래서 모든
|
||||
`@Autowired ObjectMapper`가 모호해지고 애플리케이션이 시작하지 않았다. `app-bootstrap` 테스트 여섯 개가
|
||||
`UnsatisfiedDependencyException`으로 실패했다.
|
||||
- 모든 배포가 조용히 `application/xml` 요청 본문을 받기 시작했다. 배포가 이름을 대지 않으면 꺼져 있어야 하는
|
||||
capability에서, 의존성 하나를 더해서 얻은 XXE 면이다.
|
||||
|
||||
So both are `compileOnly` plus `testImplementation`: the factories compile, their tests run against
|
||||
real backends, and the runtime classpath belongs to the deployment that enables the capability.
|
||||
`WebRepresentation.available()` turns an absent backend into a sentence naming the missing
|
||||
coordinate. `RepresentationBackendScopeTest` reads `build.gradle` and fails if either coordinate
|
||||
returns to `implementation`, because nothing else catches it — the codec's own tests pass either
|
||||
way, and the failure only appears in whatever composes this leaf.
|
||||
그래서 둘 다 `compileOnly`와 `testImplementation`이다. factory는 컴파일되고, 그 테스트는 실제 backend로 돌고, 런타임
|
||||
classpath는 capability를 켜는 배포의 몫이다. `WebRepresentation.available()`은 없는 backend를 빠진 좌표를 이름 댄
|
||||
문장으로 바꾼다. `RepresentationBackendScopeTest`는 `build.gradle`을 읽고 둘 중 하나라도 `implementation`으로
|
||||
돌아가면 실패한다. 다른 어떤 것도 그것을 잡지 못하기 때문이다. codec 자체 테스트는 어느 쪽이든 통과하고, 실패는
|
||||
이 leaf를 조립하는 곳에서만 나타난다.
|
||||
|
||||
**The framing and the writer are separate.** `NdjsonFraming` and `JsonSequenceFraming` hold the
|
||||
contract; `MvcStreamWriter` is what puts it on a response. There is no MVC SSE writer: this
|
||||
repository's `NO_SSE_EMITTER` ArchUnit rule forbids `SseEmitter` outright, and the only SSE writer
|
||||
was the WebFlux one removed on 2026-09-25. So the servlet stack streams NDJSON and JSON-seq, and SSE
|
||||
is framing-only — nothing serves it until a servlet writer exists.
|
||||
**framing과 writer는 따로다.** `NdjsonFraming`과 `JsonSequenceFraming`이 계약을 가지고, `MvcStreamWriter`가 그것을
|
||||
응답에 싣는다. MVC SSE writer는 없다. 이 저장소의 `NO_SSE_EMITTER` ArchUnit 규칙이 `SseEmitter`를 아예 금하고, 유일한
|
||||
SSE writer는 2026-09-25에 지운 WebFlux 것이었다. 그래서 servlet stack은 NDJSON과 JSON-seq를 스트리밍하고, SSE는
|
||||
framing만 있다. servlet writer가 생기기 전에는 아무것도 SSE를 내보내지 않는다.
|
||||
|
||||
**`MessagingReplayBridge` is `WebStreamReplaySource`, an interface this module implements nowhere.**
|
||||
The design's requirement is that the web module store no durable event history; an implementation
|
||||
here would be the thing it forbids.
|
||||
**`MessagingReplayBridge`는 이 모듈이 어디서도 구현하지 않는 interface인 `WebStreamReplaySource`다.** 설계의 요구는
|
||||
web 모듈이 지속되는 이벤트 이력을 저장하지 않는 것이다. 여기서 구현하면 그것이 금하는 바로 그것이 된다.
|
||||
|
||||
### What the execution layer had to get right
|
||||
### 실행 계층이 맞혀야 했던 것
|
||||
|
||||
On the servlet stack there is no disconnect event at all: the first sign a client is gone is a write that throws, which is why the heartbeat is the probe rather than a
|
||||
courtesy and why a failed beat is recorded as disconnect evidence.
|
||||
servlet stack에는 연결 끊김 이벤트가 아예 없다. client가 사라졌다는 첫 신호는 예외를 던지는 쓰기다. 그래서
|
||||
heartbeat는 예의가 아니라 탐침이고, 실패한 heartbeat는 연결 끊김 증거로 기록한다.
|
||||
|
||||
### Verification
|
||||
### 확인
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:web:test # the shipped web leaf
|
||||
./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
|
||||
./gradlew :adapter:inbound:web:webJettyCompatTest # Jetty, real socket
|
||||
./gradlew :adapter:inbound:web-advanced:test # the opt-in Advanced leaf
|
||||
./gradlew :adapter:inbound:web-advanced:webAdvancedTest # the tagged Advanced lane
|
||||
./gradlew :adapter:inbound:web:test # 내보내는 web leaf
|
||||
./gradlew :adapter:inbound:web:systemTest # Tomcat, 실제 socket
|
||||
./gradlew :adapter:inbound:web:webJettyCompatTest # Jetty, 실제 socket
|
||||
./gradlew :adapter:inbound:web-advanced:test # 골라 쓰는 Advanced leaf
|
||||
./gradlew :adapter:inbound:web-advanced:webAdvancedTest # tag를 단 Advanced lane
|
||||
```
|
||||
|
||||
See `docs/web/advanced-capabilities.md`, `docs/web/streaming-contract.md`,
|
||||
`docs/web/patch-contract.md`, `docs/web/virtual-thread-profile.md`,
|
||||
`docs/web/openapi-32-compatibility.md`, and `docs/adr/ADR-WEB-ADV-00{1,2,3}-*.md`.
|
||||
`docs/web/advanced-capabilities.md`, `docs/web/streaming-contract.md`, `docs/web/patch-contract.md`,
|
||||
`docs/web/virtual-thread-profile.md`, `docs/web/openapi-32-compatibility.md`, `docs/adr/ADR-WEB-ADV-00{1,2,3}-*.md`를
|
||||
본다.
|
||||
|
||||
+65
-71
@@ -1,104 +1,98 @@
|
||||
# Web platform runbook
|
||||
# Web 플랫폼 runbook
|
||||
|
||||
What an operator needs when the HTTP boundary misbehaves. Organised by what you observe, because
|
||||
that is what you have at 3am — not by which module owns it.
|
||||
HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈이 가졌는지가 아니라 무엇을 보았는지로 나눴다. 새벽
|
||||
3시에 손에 있는 것이 그것이기 때문이다.
|
||||
|
||||
## Reading a `429`
|
||||
## `429` 읽기
|
||||
|
||||
`RateLimitInterceptor` answers `429 RATE_LIMIT_EXCEEDED` with `Retry-After` when the edge rate
|
||||
limit refuses a caller. `RATE_LIMIT_UNAVAILABLE` means the rate-limit store could not be reached,
|
||||
not that the caller exceeded anything — look at the store, not the caller.
|
||||
`RateLimitInterceptor`는 edge 속도 제한이 호출자를 거부하면 `Retry-After`와 함께 `429 RATE_LIMIT_EXCEEDED`로 답한다.
|
||||
`RATE_LIMIT_UNAVAILABLE`은 호출자가 무언가를 넘었다는 뜻이 아니라 속도 제한 저장소에 닿지 못했다는 뜻이다. 호출자가
|
||||
아니라 저장소를 본다.
|
||||
|
||||
## Errors that are not the `Envelope`
|
||||
## `Envelope`가 아닌 오류
|
||||
|
||||
Every HTTP error the application writes is the `Envelope` from `GlobalExceptionHandler`
|
||||
(`spring.mvc.problemdetails.enabled=false`), with an `error.code` a client branches on.
|
||||
애플리케이션이 쓰는 모든 HTTP 오류는 `GlobalExceptionHandler`가 쓰는 `Envelope`이고
|
||||
(`spring.mvc.problemdetails.enabled=false`), client가 분기하는 `error.code`를 가진다.
|
||||
|
||||
- **How to confirm quickly:** send a request that must fail validation and check the body has
|
||||
`error.code`. A body without it (Spring's `ProblemDetail`, or the container's error page) means
|
||||
the handler is not installed or the response came from the edge.
|
||||
- **빨리 확인하는 법:** 검증에 실패해야 하는 요청을 보내고 본문에 `error.code`가 있는지 본다. 없으면(Spring의
|
||||
`ProblemDetail`이나 container의 오류 쪽) handler가 설치되지 않았거나 응답이 edge에서 왔다.
|
||||
|
||||
## A response is truncated or the connection dies mid-document
|
||||
## 응답이 잘리거나 문서 중간에 connection이 끊긴다
|
||||
|
||||
Two different causes, distinguished by the status the client did receive.
|
||||
원인은 둘이고, client가 받은 상태로 구분한다.
|
||||
|
||||
- **Client got a status, then nothing** — the response failed after commit. The status cannot be
|
||||
retracted, so the connection ends mid-document.
|
||||
- **Client got nothing from the application** — the proxy refused it. `client_max_body_size` in
|
||||
nginx answers with its own HTML rather than the `Envelope`. See `repository-adaptation.md` §8.
|
||||
- **client가 상태를 받고 그다음 아무것도 없다** — 응답이 commit 뒤에 실패했다. 상태는 되돌릴 수 없으므로 문서 중간에
|
||||
connection이 끝난다.
|
||||
- **client가 애플리케이션에서 아무것도 받지 못했다** — proxy가 거부했다. nginx의 `client_max_body_size`는 `Envelope`가
|
||||
아니라 자기 HTML로 답한다. `repository-adaptation.md` §8을 본다.
|
||||
|
||||
## A retried write happened twice
|
||||
## 재시도한 쓰기가 두 번 일어났다
|
||||
|
||||
The idempotency key is the control, and there are exactly three ways it fails to apply.
|
||||
통제 수단은 멱등 key이고, 그것이 적용되지 않는 길은 정확히 셋이다.
|
||||
|
||||
1. **The client did not send one.** The endpoint does not require the key, so it ran unguarded.
|
||||
Require it if a duplicate is unacceptable.
|
||||
2. **The client sent a different body.** Answered `422 IDEMPOTENT_REQUEST_MISMATCH`, never a
|
||||
replay — replaying would hand back a receipt for a request the caller never made.
|
||||
3. **The record expired.** TTL is per-operation with a 72h cap. A retry after expiry is a new
|
||||
request by definition.
|
||||
1. **client가 key를 보내지 않았다.** endpoint가 key를 요구하지 않으니 보호 없이 돌았다. 중복을 받아들일 수 없으면 key를
|
||||
요구한다.
|
||||
2. **client가 다른 본문을 보냈다.** `422 IDEMPOTENT_REQUEST_MISMATCH`로 답하고 절대 다시 보내지 않는다. 다시 보내면
|
||||
호출자가 한 적 없는 요청의 영수증을 돌려주게 된다.
|
||||
3. **기록이 만료됐다.** TTL은 연산마다 정하고 상한은 72h다. 만료 뒤의 재시도는 정의상 새 요청이다.
|
||||
|
||||
A `409 IDEMPOTENT_IN_FLIGHT` (retryable=true, `Retry-After: 2`) is not a failure: an earlier
|
||||
attempt is still running and its result is unknown. The caller resends with the **same**
|
||||
`Idempotency-Key` after `Retry-After`; a new key is a new request and is how a write ends up
|
||||
applied twice. The four idempotency answers are in `http-contract.md` §2.
|
||||
`409 IDEMPOTENT_IN_FLIGHT`(retryable=true, `Retry-After: 2`)는 실패가 아니다. 앞 시도가 아직 돌고 있고 그 결과를
|
||||
모른다. 호출자는 `Retry-After` 뒤에 **같은** `Idempotency-Key`로 다시 보낸다. 새 key는 새 요청이고, 쓰기가 두 번
|
||||
적용되는 길이 그것이다. 멱등성 답 넷은 `http-contract.md` §2에 있다.
|
||||
|
||||
## Rolling deploy stalls with instances half-drained
|
||||
## rolling 배포가 인스턴스를 반쯤 비운 채 멈춘다
|
||||
|
||||
`shutDownGracefully` waits for in-flight work, and an open-but-idle keep-alive connection can count
|
||||
as in-flight. Calling `stop()` while that wait is in progress hangs.
|
||||
`shutDownGracefully`는 진행 중인 일을 기다리고, 열려 있지만 노는 keep-alive connection이 진행 중으로 셀 수 있다. 그
|
||||
기다림 중에 `stop()`을 부르면 멈춘다.
|
||||
|
||||
- **Symptom:** an instance neither serving nor exiting, no error in its log.
|
||||
- **Cause:** an unbounded graceful wait. `GracefulShutdownProbe` bounds it at a stated grace period
|
||||
and stops the server regardless once it elapses; a deployment must do the same.
|
||||
- **Setting:** `spring.lifecycle.timeout-per-shutdown-phase`. Without a bound the deploy waits for
|
||||
a connection that may never go idle.
|
||||
- **증상:** 요청을 받지도 않고 끝나지도 않는 인스턴스. 로그에 오류가 없다.
|
||||
- **원인:** 상한 없는 graceful 기다림. `GracefulShutdownProbe`는 정한 유예 시간으로 그것을 제한하고, 시간이 지나면
|
||||
어쨌든 서버를 멈춘다. 배포도 같게 해야 한다.
|
||||
- **설정:** `spring.lifecycle.timeout-per-shutdown-phase`. 상한이 없으면 배포는 영영 놀지 않을 수도 있는 connection을
|
||||
기다린다.
|
||||
|
||||
## Metrics stopped arriving, or the bill jumped
|
||||
## metric이 오지 않거나 청구액이 뛰었다
|
||||
|
||||
Almost always a high-cardinality tag — typically a `routeTemplate` carrying a *resolved* path, which
|
||||
is one series per resource.
|
||||
거의 늘 가짓수가 많은 tag다. 흔히 *풀린* 경로를 담은 `routeTemplate`이고, 자원마다 시계열 하나가 된다.
|
||||
|
||||
- **Check:** the tag values in the metrics backend for `routeTemplate`. Braces mean templates;
|
||||
identifiers mean the resolved path leaked through.
|
||||
- **Never tags:** the URL, the query string, any identifier, the tenant, a key, a token, a cookie,
|
||||
a body. A tag value reaches the metrics backend unredacted and usually a third-party SaaS with it.
|
||||
- **확인:** metric 저장소에서 `routeTemplate`의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린
|
||||
경로가 새어 나갔다.
|
||||
- **절대 tag로 쓰지 않는 것:** URL, query string, 식별자, tenant, key, token, cookie, 본문. tag 값은 가려지지 않은 채
|
||||
metric 저장소에 닿고, 보통 그와 함께 외부 SaaS에도 닿는다.
|
||||
|
||||
## Cross-origin requests fail only in the browser
|
||||
## 브라우저에서만 cross-origin 요청이 실패한다
|
||||
|
||||
The API answers correctly and the browser refuses the response. CORS is `CorsSettings`
|
||||
(`app.cors.*`) applied by `SecurityConfig`. Startup refuses two settings:
|
||||
API는 맞게 답하는데 브라우저가 응답을 거부한다. CORS는 `SecurityConfig`가 적용하는 `CorsSettings`(`app.cors.*`)다.
|
||||
시작 단계는 두 설정을 거부한다.
|
||||
|
||||
- `APP_SECURITY_CORS_ENABLED=true` with no origin.
|
||||
- `*` in `APP_SECURITY_CORS_ORIGINS` with `APP_SECURITY_CORS_ALLOW_CREDENTIALS=true` — no browser
|
||||
honours it.
|
||||
- origin 없이 `APP_SECURITY_CORS_ENABLED=true`.
|
||||
- `APP_SECURITY_CORS_ALLOW_CREDENTIALS=true`와 함께 `APP_SECURITY_CORS_ORIGINS`의 `*` — 어떤 브라우저도 받아들이지
|
||||
않는다.
|
||||
|
||||
Two more start fine and still fail in the browser:
|
||||
다음 둘은 시작은 되지만 브라우저에서 여전히 실패한다.
|
||||
|
||||
- `https://*.example.com` in the origin list — it is compared as a literal and matches nothing.
|
||||
- An origin with a path (`https://app.example.com/ui`) — an origin is scheme, host and port only.
|
||||
- origin 목록의 `https://*.example.com` — 글자 그대로 비교하므로 아무것에도 맞지 않는다.
|
||||
- 경로가 있는 origin(`https://app.example.com/ui`) — origin은 scheme, host, port뿐이다.
|
||||
|
||||
The response arrives but a header reads as `null` in browser code (`Retry-After`, `X-Request-Id`,
|
||||
`Location`, a tus `Upload-Offset`): the header is not in `Access-Control-Expose-Headers`. The exposed
|
||||
list is `CorsExposedHeaders.PLATFORM` plus each module's `CorsExposedHeaders` bean
|
||||
(`docs/web/http-contract.md` §3); a header a service adds needs its own bean. A proxy that strips or
|
||||
rewrites `Access-Control-Expose-Headers` has the same symptom.
|
||||
응답은 오는데 브라우저 코드에서 헤더가 `null`로 읽힌다(`Retry-After`, `X-Request-Id`, `Location`, tus
|
||||
`Upload-Offset`): 그 헤더가 `Access-Control-Expose-Headers`에 없다. 노출 목록은 `CorsExposedHeaders.PLATFORM`과 모듈마다의
|
||||
`CorsExposedHeaders` bean이다(`docs/web/http-contract.md` §3). 서비스가 더한 헤더에는 자기 bean이 필요하다.
|
||||
`Access-Control-Expose-Headers`를 지우거나 고쳐 쓰는 proxy도 같은 증상을 낸다.
|
||||
|
||||
A preflight answered `401` means CORS ran after authentication. Preflights carry no credentials by
|
||||
design; the order is asserted by `WebPipelineOrderContract`.
|
||||
preflight가 `401`로 답하면 CORS가 인증 뒤에 돈 것이다. preflight는 설계상 credential을 싣지 않는다. 순서는
|
||||
`WebPipelineOrderContract`가 단언한다.
|
||||
|
||||
## Two access-log lines for one request
|
||||
## 요청 하나에 접근 로그 줄이 둘
|
||||
|
||||
An async request passes through the servlet filter chain twice — once for the initial request and
|
||||
again on the ASYNC redispatch. A completion recorded without checking `isAsyncStarted()` is written
|
||||
both times, and every latency percentile computed from that data is wrong while looking plausible.
|
||||
`WebPipelineOrderContract` asserts exactly one observation per logical request on every container.
|
||||
async 요청은 servlet filter chain을 두 번 지난다. 처음 요청 때 한 번, ASYNC 재전달 때 또 한 번이다.
|
||||
`isAsyncStarted()`를 확인하지 않고 기록한 완료는 두 번 쓰이고, 그 데이터로 계산한 모든 지연 백분위수는 그럴듯해
|
||||
보이면서 틀린다. `WebPipelineOrderContract`가 모든 container에서 논리 요청마다 관측이 정확히 하나임을 단언한다.
|
||||
|
||||
## Verification commands
|
||||
## 확인 명령
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:web:test # unit, boundary, architecture
|
||||
./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
|
||||
./gradlew :adapter:inbound:web:webJettyCompatTest # second servlet container
|
||||
./gradlew :adapter:inbound:web:test # 단위, 경계, 아키텍처
|
||||
./gradlew :adapter:inbound:web:systemTest # Tomcat, 실제 socket
|
||||
./gradlew :adapter:inbound:web:webJettyCompatTest # 두 번째 servlet container
|
||||
```
|
||||
|
||||
@@ -1,84 +1,75 @@
|
||||
# Web streaming: the client contract
|
||||
# Web 스트리밍: client 계약
|
||||
|
||||
What a client must implement to consume NDJSON or `application/json-seq` from this platform. SSE
|
||||
framing exists, but since the WebFlux twin was removed (2026-09-25) nothing on the servlet stack
|
||||
writes it.
|
||||
이 플랫폼의 NDJSON이나 `application/json-seq`를 받으려면 client가 무엇을 구현해야 하는지 적는다. SSE framing은 있지만,
|
||||
WebFlux 쌍을 지운 뒤(2026-09-25) servlet stack에서는 아무것도 그것을 쓰지 않는다.
|
||||
|
||||
The writers ship in `adapter:inbound:web-advanced` (opt-in, switched by
|
||||
`app.web.advanced.ndjson.enabled` / `app.web.advanced.json-sequence.enabled`); no default
|
||||
composition carries them.
|
||||
writer는 `adapter:inbound:web-advanced`(골라 쓰는 leaf, `app.web.advanced.ndjson.enabled` /
|
||||
`app.web.advanced.json-sequence.enabled`로 켠다)에 있다. 기본 조립에는 없다.
|
||||
|
||||
## Three outcomes, not two
|
||||
## 끝은 둘이 아니라 셋이다
|
||||
|
||||
After the first byte the HTTP status is 200 and cannot change. So the status tells you nothing about
|
||||
whether the stream succeeded, and a closed connection is ambiguous. There are three endings:
|
||||
첫 바이트 뒤에는 HTTP 상태가 200이고 바뀔 수 없다. 그래서 상태는 stream이 성공했는지 아무것도 말해 주지 않고, 닫힌
|
||||
connection은 결과를 알 수 없다. 끝은 셋이다.
|
||||
|
||||
1. **A `Complete` envelope.** The stream finished. `lastSequence` is the final position.
|
||||
2. **A `Failure` record.** Something failed after commit. Carries an error code and a client-safe
|
||||
message. The status is still 200.
|
||||
3. **Neither.** The connection closed mid-stream. The server records this as `ABRUPT_CLOSE`; from
|
||||
the client's side it is indistinguishable from a completed stream *unless the client is looking
|
||||
for the terminal envelope*.
|
||||
1. **`Complete` envelope.** stream이 끝났다. `lastSequence`가 마지막 위치다.
|
||||
2. **`Failure` 기록.** commit 뒤에 무언가 실패했다. 오류 code와 client에게 보여도 되는 메시지를 담는다. 상태는 여전히
|
||||
200이다.
|
||||
3. **둘 다 아님.** stream 중간에 connection이 닫혔다. 서버는 이것을 `ABRUPT_CLOSE`로 기록한다. client 쪽에서는 *끝
|
||||
envelope를 찾지 않는 한* 끝난 stream과 구분할 수 없다.
|
||||
|
||||
**A client that treats a closed connection as completion will silently truncate data.** No server
|
||||
change can fix that for it. Looking for the terminal envelope is the contract.
|
||||
**닫힌 connection을 완료로 보는 client는 데이터를 조용히 잘라 먹는다.** 어떤 서버 변경도 그것을 대신 고칠 수 없다.
|
||||
끝 envelope를 찾는 것이 계약이다.
|
||||
|
||||
## Positions
|
||||
## 위치
|
||||
|
||||
Every `Item` carries a `sequence`, counting from 1. Positions are strictly increasing, and the
|
||||
server enforces it — a repeat or a regression is a server-side error, not something a client has to
|
||||
tolerate.
|
||||
모든 `Item`은 1부터 세는 `sequence`를 가진다. 위치는 엄격히 증가하고, 서버가 그것을 강제한다. 반복이나 후퇴는 client가
|
||||
견뎌야 할 것이 아니라 서버 쪽 오류다.
|
||||
|
||||
Zero is never a valid position. A stream whose first item claimed 0 and one whose sequence was never
|
||||
set would look identical.
|
||||
0은 절대 유효한 위치가 아니다. 첫 항목이 0을 주장한 stream과 sequence를 아예 정하지 않은 stream이 똑같아 보이기
|
||||
때문이다.
|
||||
|
||||
## Resuming
|
||||
## 이어 받기
|
||||
|
||||
Where a route supports it, send the last position you applied as `Last-Event-ID`.
|
||||
route가 지원하면 마지막으로 적용한 위치를 `Last-Event-ID`로 보낸다.
|
||||
|
||||
- If the source still holds it, delivery continues from the next position.
|
||||
- If it does not, the response is a **resnapshot-required** error, not a partial stream. Resuming
|
||||
from the oldest retained position would give you contiguous positions with a hole in the middle,
|
||||
and nothing in the data would say so.
|
||||
- source가 아직 그 위치를 가지고 있으면 다음 위치부터 이어서 보낸다.
|
||||
- 가지고 있지 않으면 응답은 부분 stream이 아니라 **resnapshot-required** 오류다. 남아 있는 가장 오래된 위치부터 이어
|
||||
주면 위치는 이어지는데 가운데에 구멍이 생기고, 데이터 어디에도 그 사실이 드러나지 않는다.
|
||||
|
||||
A resnapshot means re-reading the resource from its normal endpoint and starting a fresh stream.
|
||||
Clients that cannot do that cheaply should not use the resume path.
|
||||
resnapshot은 자원을 보통 endpoint에서 다시 읽고 새 stream을 시작한다는 뜻이다. 그것을 싸게 할 수 없는 client는 이어
|
||||
받기 경로를 쓰지 않는다.
|
||||
|
||||
## Framing
|
||||
|
||||
| Format | Media type | Framing | Truncation behaviour |
|
||||
| 형식 | Media type | Framing | 잘렸을 때 |
|
||||
| --- | --- | --- | --- |
|
||||
| SSE | `text/event-stream` | `data:` lines, blank-line separated | Partial event at the end |
|
||||
| NDJSON | `application/x-ndjson` | One JSON value, then `\n` | The truncated line has no newline, and the delimiter is what was lost |
|
||||
| JSON-seq | `application/json-seq` | `0x1E`, value, `\n` | The next `0x1E` unambiguously starts the next record |
|
||||
| SSE | `text/event-stream` | `data:` 줄, 빈 줄로 구분 | 끝에 반쪽 event |
|
||||
| NDJSON | `application/x-ndjson` | JSON 값 하나, 그다음 `\n` | 잘린 줄에는 줄바꿈이 없고, 잃은 것이 바로 구분자다 |
|
||||
| JSON-seq | `application/json-seq` | `0x1E`, 값, `\n` | 다음 `0x1E`가 모호함 없이 다음 기록의 시작이다 |
|
||||
|
||||
Prefer JSON-seq where truncation matters. Its separator comes *first*, so a parser resynchronises at
|
||||
the next record rather than trying to parse the truncation joined to what follows. For a long-lived
|
||||
stream, truncation is the normal way it ends.
|
||||
잘림이 중요하면 JSON-seq를 쓴다. 구분자가 *먼저* 오므로, parser는 잘린 것과 뒤따르는 것을 이어 파싱하려 하지 않고 다음
|
||||
기록에서 다시 맞춘다. 오래 사는 stream에서는 잘림이 보통의 끝이다.
|
||||
|
||||
Records never contain a raw newline. The server refuses to write one, because for NDJSON the
|
||||
consumer's line split is the only record boundary there is.
|
||||
기록에는 날것의 줄바꿈이 절대 없다. 서버가 그것을 쓰기를 거부한다. NDJSON에서는 소비자의 줄 나누기가 유일한 기록
|
||||
경계이기 때문이다.
|
||||
|
||||
## Heartbeats and timeouts
|
||||
## Heartbeat와 시간 초과
|
||||
|
||||
The server writes a keepalive every `heartbeatInterval`. A client that sees nothing for longer than
|
||||
that should assume the connection is dead — a silent connection and a disconnected one are the same
|
||||
thing at the socket, and the heartbeat is what separates them.
|
||||
서버는 `heartbeatInterval`마다 keepalive를 쓴다. 그보다 오래 아무것도 보지 못한 client는 connection이 죽었다고 봐야
|
||||
한다. socket에서는 조용한 connection과 끊긴 connection이 같고, heartbeat가 둘을 가른다.
|
||||
|
||||
Streams are closed at `idleTimeout` (nothing produced) and at `maxStreamAge` (regardless of
|
||||
activity). Both are normal endings, and both send a terminal envelope where the connection permits.
|
||||
stream은 `idleTimeout`(만든 것이 없음)과 `maxStreamAge`(활동과 상관없음)에 닫힌다. 둘 다 보통의 끝이고, connection이
|
||||
허락하면 둘 다 끝 envelope를 보낸다.
|
||||
|
||||
## Slow consumers
|
||||
## 느린 소비자
|
||||
|
||||
The server buffers at most `maxBufferedItems` for a consumer that is behind. Past that it closes the
|
||||
connection rather than growing the buffer. A client that cannot keep up should reconnect with a
|
||||
resume cursor, not expect the server to hold its backlog.
|
||||
서버는 뒤처진 소비자를 위해 최대 `maxBufferedItems`까지만 버퍼링한다. 그것을 넘으면 버퍼를 키우지 않고 connection을
|
||||
닫는다. 따라가지 못하는 client는 서버가 밀린 것을 쥐고 있기를 기대하지 말고, 이어 받기 cursor로 다시 연결한다.
|
||||
|
||||
## Shutdown
|
||||
## 종료
|
||||
|
||||
During a rolling deploy, open streams receive a reconnect request before the node stops accepting.
|
||||
Reconnect promptly — the node force-closes anything still open at its drain deadline, and that
|
||||
arrives as an abrupt close.
|
||||
rolling 배포 중에는 노드가 받기를 멈추기 전에 열린 stream이 다시 연결하라는 요청을 받는다. 바로 다시 연결한다. 노드는
|
||||
drain 기한에 아직 열린 것을 강제로 닫고, 그것은 갑작스러운 닫힘으로 도착한다.
|
||||
|
||||
Do not reconnect immediately on an abrupt close without backoff and jitter. If a node's streams are
|
||||
all cut at once, every client reconnecting at once is what keeps the replacement down.
|
||||
갑작스러운 닫힘에 backoff와 jitter 없이 바로 다시 연결하지 않는다. 노드의 stream이 한꺼번에 끊겼을 때 모든 client가
|
||||
한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.
|
||||
|
||||
@@ -1,23 +1,20 @@
|
||||
# The virtual-thread MVC profile
|
||||
# Virtual thread MVC profile
|
||||
|
||||
## What it changes, and what it does not
|
||||
## 바꾸는 것과 바꾸지 않는 것
|
||||
|
||||
Virtual threads remove the cost of a thread waiting. They do not remove the reason the waiting was
|
||||
bounded.
|
||||
virtual thread는 스레드가 기다리는 비용을 없앤다. 기다림에 상한을 둔 이유는 없애지 않는다.
|
||||
|
||||
A platform-thread MVC deployment has an implicit concurrency limit — the thread pool. Nobody wrote
|
||||
it down as an admission policy, but it is what has been protecting the database pool, the outbound
|
||||
HTTP bulkhead and every downstream service from the full arrival rate.
|
||||
platform 스레드 MVC 배포에는 숨은 동시성 상한이 있다. 스레드 pool이다. 아무도 그것을 허가 정책으로 적지 않았지만,
|
||||
DB pool, 외부 HTTP bulkhead, 모든 하류 서비스를 전체 도착률로부터 지켜 온 것이 그것이다.
|
||||
|
||||
Switching to virtual threads deletes that limit and deletes nothing that depended on it. The result
|
||||
is not a slow system. It is a system that accepts ten thousand concurrent requests, queues all of
|
||||
them on a twenty-connection pool, and times out every one — having done no useful work. The load
|
||||
that used to be shed at the front door is shed at the back, after the cost of accepting it.
|
||||
virtual thread로 바꾸면 그 상한이 사라지고, 그것에 기대던 것은 하나도 사라지지 않는다. 결과는 느린 시스템이 아니다.
|
||||
동시 요청 만 개를 받아 connection 스무 개짜리 pool에 모두 줄 세우고, 쓸모 있는 일은 하나도 못 한 채 모두 시간 초과를
|
||||
내는 시스템이다. 예전에 앞문에서 버리던 부하를 받는 비용을 치른 뒤 뒷문에서 버린다.
|
||||
|
||||
## Enabling it
|
||||
## 켜기
|
||||
|
||||
The profile ships in `adapter:inbound:web-advanced`, which no default composition carries. Add
|
||||
that leaf to the service, then two settings — the profile refuses to be constructed with only one:
|
||||
profile은 기본 조립에 없는 `adapter:inbound:web-advanced`에 있다. 서비스에 그 leaf를 더하고, 설정 둘을 준다. profile은
|
||||
하나만 주면 만들어지기를 거부한다.
|
||||
|
||||
```yaml
|
||||
app:
|
||||
@@ -25,54 +22,48 @@ app:
|
||||
advanced:
|
||||
mvc-virtual-threads:
|
||||
enabled: true
|
||||
admission-limit: 100 # required
|
||||
database-pool-size: 20 # stated, and unchanged
|
||||
outbound-bulkhead: 20 # stated, and unchanged
|
||||
admission-limit: 100 # 필수
|
||||
database-pool-size: 20 # 밝혀 둔다. 바뀌지 않는다
|
||||
outbound-bulkhead: 20 # 밝혀 둔다. 바뀌지 않는다
|
||||
```
|
||||
|
||||
The downstream numbers are carried in the profile because the whole point is that they did not grow.
|
||||
`VirtualThreadProfile.admissionFitsDownstreamBudgets()` reports when the admission limit exceeds
|
||||
them. It does not refuse — a deployment can legitimately admit more than its pool when the work is
|
||||
not all database-bound — but it makes the choice a choice.
|
||||
하류 숫자를 profile에 싣는 것은, 핵심이 바로 그 숫자가 늘지 않았다는 데 있기 때문이다.
|
||||
`VirtualThreadProfile.admissionFitsDownstreamBudgets()`가 허가 상한이 그것을 넘으면 보고한다. 거부하지는 않는다. 일이
|
||||
모두 DB에 묶이지 않았으면 배포가 pool보다 많이 허가하는 것도 정당하다. 다만 그 선택을 선택으로 만든다.
|
||||
|
||||
## The limit bounds use cases, not threads
|
||||
## 상한은 스레드가 아니라 use case를 제한한다
|
||||
|
||||
`VirtualThreadAdmissionGuard` is a fair semaphore, not a pool. Bounding the threads would put the
|
||||
waiting back and throw away what virtual threads bought. Ten thousand virtual threads may exist
|
||||
while a hundred hold permits and the rest are refused at the door.
|
||||
`VirtualThreadAdmissionGuard`는 pool이 아니라 공정한 semaphore다. 스레드를 제한하면 기다림을 되돌려 놓고 virtual
|
||||
thread로 얻은 것을 버리게 된다. virtual thread 만 개가 있어도 백 개만 허가를 쥐고 나머지는 문 앞에서 거부된다.
|
||||
|
||||
A refusal is a **503 with `Retry-After`**, and it is the outcome the limit exists to produce. A
|
||||
request refused in a millisecond is strictly better for the client than the same request accepted
|
||||
and timed out thirty seconds later behind a full pool.
|
||||
거부는 **`Retry-After`가 붙은 503**이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤
|
||||
가득 찬 pool 뒤에서 30초 뒤에 시간 초과가 난 같은 요청보다 client에게 확실히 낫다.
|
||||
|
||||
The semaphore is fair on purpose. An unfair one is faster and lets newer arrivals overtake waiting
|
||||
ones, which the overtaken client experiences as a random timeout.
|
||||
semaphore는 일부러 공정하다. 불공정한 것이 빠르지만, 새로 온 요청이 기다리던 요청을 앞지르게 두고, 앞지름당한
|
||||
client는 그것을 무작위 시간 초과로 겪는다.
|
||||
|
||||
## What to watch
|
||||
## 볼 것
|
||||
|
||||
| Signal | Why |
|
||||
| 신호 | 이유 |
|
||||
| --- | --- |
|
||||
| `jdk.VirtualThreadPinned` JFR events | A `synchronized` block held across a blocking call pins the carrier thread. The carrier pool is bounded by CPU count, so enough pinned carriers is a deadlock — and a thread dump does not obviously show it. |
|
||||
| Carrier pool queue depth | The same problem, from the other side. |
|
||||
| Admission rejections | They should rise under load. If they do not, the limit is not being applied. |
|
||||
| Downstream wait time | The signal that admission is admitting more than the pools serve. |
|
||||
| `jdk.VirtualThreadPinned` JFR event | blocking 호출을 가로질러 쥔 `synchronized` 블록은 carrier 스레드를 고정한다. carrier pool은 CPU 수로 제한되므로 고정된 carrier가 충분하면 deadlock이다. thread dump로는 잘 보이지 않는다. |
|
||||
| carrier pool 큐 깊이 | 같은 문제를 반대쪽에서 본 것이다. |
|
||||
| 허가 거부 | 부하가 오르면 같이 올라야 한다. 오르지 않으면 상한이 적용되지 않고 있다. |
|
||||
| 하류 대기 시간 | 허가가 pool이 받을 수 있는 것보다 많이 허가하고 있다는 신호다. |
|
||||
|
||||
`VirtualThreadProfile.requiredObservations()` is the same list, in code.
|
||||
`VirtualThreadProfile.requiredObservations()`가 코드로 된 같은 목록이다.
|
||||
|
||||
## Testing it
|
||||
## 시험하기
|
||||
|
||||
`VirtualThreadAdmissionGuard.peakActive()` exists so a load test can assert the limit was applied.
|
||||
It is invisible from throughput — a load test that only measures throughput passes with the guard
|
||||
removed, which is precisely the failure this profile guards against.
|
||||
`VirtualThreadAdmissionGuard.peakActive()`는 부하 시험이 상한이 적용됐음을 단언할 수 있게 하려고 있다. 처리량으로는 보이지
|
||||
않는다. 처리량만 재는 부하 시험은 guard를 빼도 통과한다. 이 profile이 막으려는 실패가 바로 그것이다.
|
||||
|
||||
The test that matters asserts two things together: peak concurrency at or below the limit, **and**
|
||||
more threads created than the limit. Without the second, the test would pass on a deployment that
|
||||
never used virtual threads at all.
|
||||
중요한 시험은 두 가지를 함께 단언한다. 최대 동시성이 상한 이하이고, **그리고** 만든 스레드가 상한보다 많다. 둘째가
|
||||
없으면 virtual thread를 아예 쓰지 않은 배포에서도 시험이 통과한다.
|
||||
|
||||
## Rolling back
|
||||
## 되돌리기
|
||||
|
||||
Set `enabled: false`, or drop the leaf. The rollback test asserts that Stable behaviour is then
|
||||
identical — if it is not, the feature was never optional and every deployment has it.
|
||||
`enabled: false`로 두거나 leaf를 뺀다. 되돌리기 시험은 그때 Stable 동작이 같은지 단언한다. 같지 않으면 그 기능은 처음부터
|
||||
선택 사항이 아니었고 모든 배포가 그것을 가지고 있다.
|
||||
|
||||
This is the only web Advanced capability that affects requests which do not use them, which is why
|
||||
its rollback test is the one that matters most.
|
||||
이것은 쓰지 않는 요청에도 영향을 주는 유일한 web Advanced capability다. 그래서 되돌리기 시험이 가장 중요하다.
|
||||
|
||||
@@ -107,13 +107,6 @@ language docs/runbooks/startup-required-adapter-disabled.md
|
||||
language docs/runbooks/startup-validation-failed.md
|
||||
language docs/runbooks/template.md
|
||||
language docs/storage-capability-boundary.md
|
||||
language docs/web/advanced-capabilities.md
|
||||
language docs/web/openapi-32-compatibility.md
|
||||
language docs/web/patch-contract.md
|
||||
language docs/web/repository-adaptation.md
|
||||
language docs/web/runbook.md
|
||||
language docs/web/streaming-contract.md
|
||||
language docs/web/virtual-thread-profile.md
|
||||
language docs/websocket/runbook.md
|
||||
language src/adapter/inbound/messaging/CLAUDE.md
|
||||
language src/adapter/inbound/web-advanced/CLAUDE.md
|
||||
@@ -150,7 +143,6 @@ language src/shared-contract/CLAUDE.md
|
||||
|
||||
# 참조: 지금 트리·registry에 없는 경로. 고치거나 「> 이력」 인용 블록으로 옮기면 지운다.
|
||||
reference AGENTS.md src/build-tools/
|
||||
reference docs/web/http-contract.md docs/architecture/backend-api-and-server-state-contract.md
|
||||
reference docs/work/operate.md :a:test
|
||||
reference docs/work/operate.md :b:test
|
||||
reference src/README.md .github/ci-gate-matrix.yml
|
||||
|
||||
Reference in New Issue
Block a user