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:
DongHyeonka
2026-11-07 17:29:57 +09:00
parent e38c949c2f
commit 9d6c67c14e
9 changed files with 448 additions and 531 deletions
+55 -62
View File
@@ -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`를 본다.
+2 -2
View File
@@ -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에 있어서 여기서 경로로 가리키지 않는다.
+17 -22
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
```
+48 -57
View File
@@ -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가
한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.
+40 -49
View File
@@ -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다. 그래서 되돌리기 시험이 가장 중요하다.
-8
View File
@@ -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