feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
This commit is contained in:
@@ -28,7 +28,12 @@ envelope shape, metric cardinality bounds, tracing seam, domain-context propagat
|
||||
SHA-256 digest value and the one `MessageDigest.getInstance("SHA-256")`), `digest/HmacSha256`
|
||||
(sign and constant-time verify), `retry/Backoff` (capped exponential ceiling; "full jitter" means
|
||||
`U[0, ceiling]` and nothing else). Vendored `messaging:*` and the optional gRPC build do not depend
|
||||
on this module and keep their own copies.
|
||||
on this module and keep their own copies. A leaf that has the `shared-contract` edge uses these and
|
||||
does not copy them (application-fileserver `SafeFileFingerprint` and cache-redis `RedisKeys` were
|
||||
the last two). Template leaves that still copy because the registry gives them no edge —
|
||||
identifier, persistence-mongo, application-objectstorage, redis-sdk — are an open decision: add the
|
||||
edge (recommended for template leaves) or keep the copy and say so in that leaf's CLAUDE.md
|
||||
(review 2026-11-01 01-11).
|
||||
- `observability/MdcKeys`: the snake_case MDC key names (registry `docs/registries/mdc-keys.yaml`)
|
||||
every transport puts a request's correlation under — web, GraphQL, STOMP and gRPC alike.
|
||||
- Registry-rule mirrors read only by contract tests live in `testFixtures`, not `main`:
|
||||
|
||||
@@ -295,23 +295,13 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## operation — 장기 실행 작업(LRO) 계약
|
||||
## operation — 없음 (sample로 옮김)
|
||||
|
||||
### Operation
|
||||
- **장기 실행 작업(long-running-operation) 폴링 본문**.
|
||||
`GET /v1/operations/{id}` 가 `Envelope` 의 `data` 로 반환한다.
|
||||
- 필드: `operationId`(opaque server id, 202 응답 `Location` 헤더의 마지막 segment 이기도 함,
|
||||
never null), `status`(`OperationStatus`, terminal 까지 클라이언트가 polling), `statusUrl`(self
|
||||
link), `result`(`SUCCEEDED` 일 때만, AIP151-C3), `error`(`FAILED` 일 때만, AIP151-C5, 스켈레톤
|
||||
`ApiError` 모양 재사용).
|
||||
- 프레임워크 중립. id 발급과 202/Location 배선은 web 어댑터가 한다.
|
||||
|
||||
### OperationStatus
|
||||
- **LRO lifecycle status**(D17).
|
||||
- **프로젝트 선택:** 이 5-value 어휘는 Google AIP-151 의 `done`/`response`/`error`
|
||||
이진 모델(AIP151-C4/C3/C5)을 프로젝트 내부용으로 투영한 것이다 — AIP-151 자체에는 enum 이 없다.
|
||||
매핑: `PENDING`=접수됐으나 미시작, `RUNNING`=`done=false` 진행 중, `SUCCEEDED`=`done=true`+
|
||||
`response`, `FAILED`=`done=true`+`error`, `CANCELLED`=`done=true`+취소.
|
||||
장기 실행 작업(LRO)의 정본 공개 계약은 application-core `DurableOperation` + web
|
||||
`OperationHttpResponse`(`GET /operations/{operationId}`, 소유자 결정 15·26)다. 이 모듈에 있던
|
||||
`Operation`·`OperationStatus`(`status` 필드, `CANCELLED` 철자)는 production 소비자가 sample뿐이라
|
||||
`sample-portfolio`의 `adapter.inbound.web.operation`으로 옮겼다(리뷰 2026-11-01 01-08). 같은 개념의
|
||||
두 번째 응답 모양을 "skeleton-wide 계약"으로 두면 파생 서비스가 틀린 쪽을 고르기 쉽다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -16,6 +16,5 @@ strictTestLanes {
|
||||
description = 'Runs exact Messaging shared schema qualification tests.'
|
||||
requires 'dev.caskeleton.shared.contract.messaging.MessagingEnvelopeSchemaResourceTest'
|
||||
rejectSkipped = true
|
||||
jvmArgs '-Duser.timezone=UTC'
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
|
||||
@@ -1,40 +0,0 @@
|
||||
package dev.caskeleton.shared.operation;
|
||||
|
||||
import dev.caskeleton.shared.response.ApiError;
|
||||
|
||||
/**
|
||||
* Long-running-operation polling body (feature-api-contract-baseline D17), returned as the {@code
|
||||
* data} of an {@link dev.caskeleton.shared.response.Envelope} by {@code GET /v1/operations/{id}}.
|
||||
*
|
||||
* <ul>
|
||||
* <li>{@code operationId} — opaque server id (also the last segment of the 202 {@code Location}
|
||||
* header). Never {@code null}.
|
||||
* <li>{@code status} — {@link OperationStatus}; clients poll until terminal ({@code
|
||||
* SUCCEEDED}/{@code FAILED}/{@code CANCELLED}).
|
||||
* <li>{@code statusUrl} — self link ({@code /v1/operations/{id}}); mirrors the 202 envelope
|
||||
* {@code data.statusUrl}.
|
||||
* <li>{@code result} — present only on {@code SUCCEEDED} (AIP151-C3), else {@code null}.
|
||||
* <li>{@code error} — present only on {@code FAILED} (AIP151-C5), reusing the skeleton {@link
|
||||
* ApiError} shape, else {@code null}.
|
||||
* </ul>
|
||||
*
|
||||
* <p>Framework-neutral (no Jackson/Spring). The web adapter mints ids and the 202/Location wiring.
|
||||
*/
|
||||
public record Operation<T>(
|
||||
String operationId, OperationStatus status, String statusUrl, T result, ApiError error) {
|
||||
|
||||
/** Initial 202 acknowledgement body: id + statusUrl + PENDING, no result/error. */
|
||||
public static <T> Operation<T> pending(String operationId, String statusUrl) {
|
||||
return new Operation<>(operationId, OperationStatus.PENDING, statusUrl, null, null);
|
||||
}
|
||||
|
||||
/** Terminal success: carries the result, no error. */
|
||||
public static <T> Operation<T> succeeded(String operationId, String statusUrl, T result) {
|
||||
return new Operation<>(operationId, OperationStatus.SUCCEEDED, statusUrl, result, null);
|
||||
}
|
||||
|
||||
/** Terminal failure: carries the error, no result. */
|
||||
public static <T> Operation<T> failed(String operationId, String statusUrl, ApiError error) {
|
||||
return new Operation<>(operationId, OperationStatus.FAILED, statusUrl, null, error);
|
||||
}
|
||||
}
|
||||
-16
@@ -1,16 +0,0 @@
|
||||
package dev.caskeleton.shared.operation;
|
||||
|
||||
/**
|
||||
* Long-running-operation (LRO) lifecycle status surfaced by the polling endpoint {@code GET
|
||||
* /v1/operations/{id}}.
|
||||
*
|
||||
* <p>See the module README for how this 5-value vocabulary maps onto the Google AIP-151
|
||||
* done/response/error model.
|
||||
*/
|
||||
public enum OperationStatus {
|
||||
PENDING,
|
||||
RUNNING,
|
||||
SUCCEEDED,
|
||||
FAILED,
|
||||
CANCELLED
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
package dev.caskeleton.shared.operation;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.shared.response.ApiError;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* Pins the D17 long-running-operation polling body shape: the 5-value status vocabulary and the
|
||||
* pending/succeeded/failed factory invariants.
|
||||
*/
|
||||
class OperationTest {
|
||||
|
||||
@Test
|
||||
void statusEnumIsTheFiveValueContractVocabulary() {
|
||||
assertThat(OperationStatus.values())
|
||||
.extracting(Enum::name)
|
||||
.containsExactly("PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELLED");
|
||||
}
|
||||
|
||||
@Test
|
||||
void pendingCarriesIdAndStatusUrlNoResultNoError() {
|
||||
Operation<String> op = Operation.pending("01HZX", "/v1/operations/01HZX");
|
||||
assertThat(op.operationId()).isEqualTo("01HZX");
|
||||
assertThat(op.status()).isEqualTo(OperationStatus.PENDING);
|
||||
assertThat(op.statusUrl()).isEqualTo("/v1/operations/01HZX");
|
||||
assertThat(op.result()).isNull();
|
||||
assertThat(op.error()).isNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void succeededCarriesResultNoError() {
|
||||
Operation<String> op = Operation.succeeded("01HZX", "/v1/operations/01HZX", "done");
|
||||
assertThat(op.status()).isEqualTo(OperationStatus.SUCCEEDED);
|
||||
assertThat(op.result()).isEqualTo("done");
|
||||
assertThat(op.error()).isNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void failedCarriesErrorNoResult() {
|
||||
ApiError err = ApiError.of("INTERNAL_ERROR", "INTERNAL", "boom", true);
|
||||
Operation<String> op = Operation.failed("01HZX", "/v1/operations/01HZX", err);
|
||||
assertThat(op.status()).isEqualTo(OperationStatus.FAILED);
|
||||
assertThat(op.result()).isNull();
|
||||
assertThat(op.error().code()).isEqualTo("INTERNAL_ERROR");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user