diff --git a/docs/web/advanced-capabilities.md b/docs/web/advanced-capabilities.md index da72f415..58ffd654 100644 --- a/docs/web/advanced-capabilities.md +++ b/docs/web/advanced-capabilities.md @@ -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`를 본다. diff --git a/docs/web/http-contract.md b/docs/web/http-contract.md index 67cb9f91..1f66a154 100644 --- a/docs/web/http-contract.md +++ b/docs/web/http-contract.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에 있어서 여기서 경로로 가리키지 않는다. diff --git a/docs/web/openapi-32-compatibility.md b/docs/web/openapi-32-compatibility.md index 1f042656..a6a477d6 100644 --- a/docs/web/openapi-32-compatibility.md +++ b/docs/web/openapi-32-compatibility.md @@ -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를 다룬다. diff --git a/docs/web/patch-contract.md b/docs/web/patch-contract.md index 8fffa985..5cb64725 100644 --- a/docs/web/patch-contract.md +++ b/docs/web/patch-contract.md @@ -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`를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다. diff --git a/docs/web/repository-adaptation.md b/docs/web/repository-adaptation.md index 8e233558..7f841345 100644 --- a/docs/web/repository-adaptation.md +++ b/docs/web/repository-adaptation.md @@ -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`를 +본다. diff --git a/docs/web/runbook.md b/docs/web/runbook.md index dde6316c..da66560b 100644 --- a/docs/web/runbook.md +++ b/docs/web/runbook.md @@ -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 ``` diff --git a/docs/web/streaming-contract.md b/docs/web/streaming-contract.md index 5bd6ab7a..b2ccb6a8 100644 --- a/docs/web/streaming-contract.md +++ b/docs/web/streaming-contract.md @@ -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가 +한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다. diff --git a/docs/web/virtual-thread-profile.md b/docs/web/virtual-thread-profile.md index ed3b9b5c..599927db 100644 --- a/docs/web/virtual-thread-profile.md +++ b/docs/web/virtual-thread-profile.md @@ -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다. 그래서 되돌리기 시험이 가장 중요하다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 5b33de9d..e4b0e803 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -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