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:
+80
@@ -0,0 +1,80 @@
|
||||
package dev.caskeleton.grpc.idempotency;
|
||||
|
||||
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedger;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
|
||||
/**
|
||||
* Deletes finished operation-ledger records once they are older than the retention.
|
||||
*
|
||||
* <p>Without it the ledger keeps every {@code COMMITTED} and {@code FAILED_TERMINAL} row forever. A
|
||||
* finished row exists only to answer a retry, so once it is older than any retry a caller still
|
||||
* sends, it is dead weight on the table every keyed call writes to.
|
||||
*
|
||||
* <p>This class decides <em>what</em> to delete; it does not decide <em>when</em>. Nothing here
|
||||
* schedules itself: the platform starter does not own a scheduler, does not start the server, and
|
||||
* cannot know which replica should run the purge, so the adopter calls {@link #purgeExpired} from
|
||||
* its own scheduler (one replica, or every replica — the bounded delete is safe either way).
|
||||
*/
|
||||
public final class GrpcOperationLedgerRetention {
|
||||
|
||||
/**
|
||||
* Rows deleted per statement. Small enough that one delete holds its row locks briefly on the
|
||||
* hottest table of the idempotency path, large enough that a day's backlog drains in few calls.
|
||||
*/
|
||||
public static final int DEFAULT_BATCH_SIZE = 500;
|
||||
|
||||
private final GrpcOperationLedger ledger;
|
||||
private final Duration retention;
|
||||
private final int batchSize;
|
||||
|
||||
/**
|
||||
* @param retention how long a finished record is kept after it completed. It must exceed the
|
||||
* longest window in which a caller still retries the same key: a retry after the purge finds
|
||||
* no record, claims afresh and runs the mutation again.
|
||||
* @param batchSize the most rows one delete statement removes
|
||||
*/
|
||||
public GrpcOperationLedgerRetention(
|
||||
GrpcOperationLedger ledger, Duration retention, int batchSize) {
|
||||
if (ledger == null) {
|
||||
throw new IllegalArgumentException("a ledger retention needs a ledger");
|
||||
}
|
||||
if (retention == null || retention.isZero() || retention.isNegative()) {
|
||||
throw new IllegalArgumentException("a ledger retention must be present and positive");
|
||||
}
|
||||
if (batchSize < 1) {
|
||||
throw new IllegalArgumentException("a ledger purge batch size must be positive");
|
||||
}
|
||||
this.ledger = ledger;
|
||||
this.retention = retention;
|
||||
this.batchSize = batchSize;
|
||||
}
|
||||
|
||||
/** How long a finished record is kept. */
|
||||
public Duration retention() {
|
||||
return retention;
|
||||
}
|
||||
|
||||
/**
|
||||
* Deletes every finished record that completed more than the retention before {@code now}, in
|
||||
* bounded batches, and never an {@code IN_PROGRESS} one.
|
||||
*
|
||||
* <p>The cutoff is fixed at the start, so the loop ends: records finishing while it runs are
|
||||
* newer than the cutoff and are left for the next call.
|
||||
*
|
||||
* @return how many records were deleted
|
||||
*/
|
||||
public int purgeExpired(Instant now) {
|
||||
if (now == null) {
|
||||
throw new IllegalArgumentException("a purge needs the current moment");
|
||||
}
|
||||
Instant cutoff = now.minus(retention);
|
||||
int total = 0;
|
||||
int purged;
|
||||
do {
|
||||
purged = ledger.purgeCompletedBefore(cutoff, batchSize);
|
||||
total += purged;
|
||||
} while (purged == batchSize);
|
||||
return total;
|
||||
}
|
||||
}
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
package dev.caskeleton.grpc.idempotency;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
|
||||
import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity;
|
||||
import dev.caskeleton.grpc.api.ledger.InMemoryOperationLedger;
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcOperationLedgerRetentionTest {
|
||||
|
||||
private static final GrpcMethodName CREATE =
|
||||
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/CreateDocument");
|
||||
private static final Instant NOW = Instant.parse("2026-11-01T10:00:00Z");
|
||||
private static final Duration RETENTION = Duration.ofHours(24);
|
||||
private static final String BODY = GrpcRequestFingerprint.of("body");
|
||||
|
||||
private final InMemoryOperationLedger ledger = new InMemoryOperationLedger();
|
||||
|
||||
@Test
|
||||
@DisplayName("보존 기간이 지난 종결 행을 batch 크기와 무관하게 모두 지운다")
|
||||
void everyFinishedRecordPastTheRetentionIsPurgedAcrossBatches() {
|
||||
// given
|
||||
List<GrpcOperationIdentity> old = List.of(identity("k1"), identity("k2"), identity("k3"));
|
||||
old.forEach(identity -> committed(identity, NOW.minus(RETENTION).minusSeconds(60)));
|
||||
GrpcOperationLedgerRetention retention = new GrpcOperationLedgerRetention(ledger, RETENTION, 2);
|
||||
|
||||
// when
|
||||
int purged = retention.purgeExpired(NOW);
|
||||
|
||||
// then
|
||||
assertThat(purged).isEqualTo(3);
|
||||
assertThat(old).allSatisfy(identity -> assertThat(ledger.find(identity)).isEmpty());
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("보존 기간 안에 끝난 행과 진행 중인 행은 남긴다")
|
||||
void recentFinishedRecordsAndInProgressClaimsAreKept() {
|
||||
// given
|
||||
GrpcOperationIdentity recent = identity("recent");
|
||||
GrpcOperationIdentity running = identity("running");
|
||||
committed(recent, NOW.minus(RETENTION).plusSeconds(60));
|
||||
ledger.claim(running, BODY, NOW.minus(Duration.ofDays(30)));
|
||||
GrpcOperationLedgerRetention retention = new GrpcOperationLedgerRetention(ledger, RETENTION, 2);
|
||||
|
||||
// when
|
||||
int purged = retention.purgeExpired(NOW);
|
||||
|
||||
// then
|
||||
assertThat(purged).isZero();
|
||||
assertThat(ledger.find(recent)).isPresent();
|
||||
assertThat(ledger.find(running)).isPresent();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("보존 기간이 양수가 아니면 만들 수 없다")
|
||||
void aNonPositiveRetentionIsRefused() {
|
||||
// when
|
||||
Throwable refused =
|
||||
catchThrowable(() -> new GrpcOperationLedgerRetention(ledger, Duration.ZERO, 2));
|
||||
|
||||
// then
|
||||
assertThat(refused)
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("retention must be present and positive");
|
||||
}
|
||||
|
||||
private static GrpcOperationIdentity identity(String key) {
|
||||
return new GrpcOperationIdentity(
|
||||
"tenant-1|actor-1", CREATE, GrpcRequestFingerprint.hashIdempotencyKey(key));
|
||||
}
|
||||
|
||||
// Finished at the claim moment; the completion moment is what the retention measures.
|
||||
private void committed(GrpcOperationIdentity identity, Instant claimedAt) {
|
||||
ledger.claim(identity, BODY, claimedAt);
|
||||
ledger.markCommitted(identity, "outcome://document/" + identity.storageKey(), claimedAt);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user