Commit Graph
4 Commits
Author SHA1 Message Date
DongHyeonka 18188f78c9 fix(web-advanced)!: patch·stream·virtual thread가 약속한 계약대로 답한다
문제: web-advanced의 계약 문서와 코드가 다섯 곳에서 갈렸다.
- patch 거부가 세 코드로 갈렸다. 형식 오류는 PATCH_REJECTED(400), 빈
  문서·연산 모양 오류·merge 깊이 초과는 IllegalArgumentException이라
  BAD_PARAMETER(400), 너무 깊은 pointer는 권한 거절 PATCH_PATH_FORBIDDEN(403)
  이었다. JSON이 아닌 본문과 결과가 대상 타입으로 읽히지 않는 patch는
  Jackson 예외로 catch-all에 닿아 500 INTERNAL_ERROR였다.
- patch-contract.md는 결과를 문서 전체로 검증한다고 했지만 두 applier는
  검증기를 받지 않았다.
- streaming-contract.md는 서버가 위치 증가를 강제하고 heartbeat·idle·max
  age·버퍼 상한·drain 재연결을 한다고 했다. MvcStreamWriter는 그 어느 것도
  하지 않았다.
- commit 뒤 Failure 기록이 어디에도 등록되지 않은 DEPENDENCY_FAILURE로
  고정이라, STREAM_ITEM_TOO_LARGE 같은 carrier 코드가 사라졌다.
- virtual thread profile은 503 + Retry-After를 약속했지만 admission guard는
  bean만 있었고 요청 경로에서 아무도 부르지 않았다.
- web AGENTS B2는 merge patch를 쓰지 않는다고 했고 patch-contract는 필드
  변경에 merge patch를 쓰라고 했다(정본 충돌).

고른 방법:
- 형식이 틀린 patch 문서는 모두 JsonPatchRejectedException(PATCH_REJECTED)
  이다. 본문 파싱과 결과 변환은 PatchBodies가 감싼다. 너무 깊은 pointer는
  권한 검사 앞에서 400으로 거절한다. 대상 타입이 객체가 아닌 것은 서버
  결함이라 IllegalStateException이다.
- 두 applier가 Bean Validation Validator를 받아 결과 객체 전체를 검증한다.
  위반은 @Valid 본문과 같은 ConstraintViolationException → VALIDATION_FAILED.
- writer는 위치가 앞 항목보다 크지 않으면 그 항목을 쓰지 않고 INTERNAL_ERROR
  Failure 기록으로 끝낸다. Failure 기록은 cause 사슬의 carrier 코드, 없으면
  INTERNAL_ERROR, 문구는 category 고정 문구다.
- writer가 할 수 없는 것(heartbeat, idle·max age, 버퍼, drain)은 계약
  문서를 고쳐 누가 하는지(WebStreamPolicy·Registry·DrainCoordinator를 쓰는
  서비스) 적었다. 요청 thread의 동기 writer라 heartbeat를 넣으려면 thread
  모델을 바꿔야 해서 버렸다.
- VirtualThreadAdmissionFilter가 모든 요청을 guard 아래 둔다(request-id
  filter 바로 뒤). async 요청은 async가 끝날 때 permit을 돌려준다. guard에
  Permit API를 더했다.
- 정본 충돌은 리뷰 README 6절 ③대로 patch-contract를 정본으로 두고 web
  AGENTS B2가 그쪽을 가리킨다.

위험·한계: patch를 쓰는 서비스는 applier 생성자에 Validator를 넘겨야
컴파일된다. client가 보는 patch·stream 오류 코드가 바뀐다. virtual thread
profile을 켠 배포는 처음으로 상한에 걸릴 수 있다(upgrade 안내 1~5).

BREAKING CHANGE: JsonMergePatchApplier·JsonPatchApplier 생성자가 Validator를
받는다. patch 거부는 모두 PATCH_REJECTED(400), 결과 제약 위반은
VALIDATION_FAILED, stream Failure 코드는 실패의 코드나 INTERNAL_ERROR다. 할
일은 docs/upgrade/2026-11-round9-contracts.md.

Refs: RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-26, RR9-03-27, RR9-03-28
2026-11-13 04:08:16 +09:00
DongHyeonka 9d6c67c14e 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 등 주석).
2026-11-07 17:29:57 +09:00
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00
DongHyeonka a24ece9cf7 feat: web, websocket 어댑터 추가 구현 2026-08-28 17:01:27 +09:00