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:
+21
@@ -82,6 +82,27 @@ public interface GrpcOperationLedger {
|
||||
Instant claimedBefore,
|
||||
Instant now);
|
||||
|
||||
/**
|
||||
* Deletes up to {@code limit} finished records ({@code COMMITTED} or {@code FAILED_TERMINAL})
|
||||
* that completed before {@code completedBefore}, oldest first.
|
||||
*
|
||||
* <p>Retention, not recovery. A finished row only answers retries, so once it is older than any
|
||||
* retry a caller will still send, keeping it only grows the table. Deleting it is a trade the
|
||||
* deployment makes knowingly: a retry of the same key arriving after the purge is a fresh claim
|
||||
* and runs the mutation again. The retention must therefore exceed the callers' retry window.
|
||||
*
|
||||
* <p>An {@code IN_PROGRESS} record is never deleted, however old. It is either running or
|
||||
* abandoned, and an abandoned one is taken over by {@link #reclaimStale}, which keeps the record
|
||||
* that an attempt started; deleting it would erase that.
|
||||
*
|
||||
* <p>Bounded so a backlog is drained in short transactions rather than one long delete that holds
|
||||
* locks on the hottest table of the idempotency path.
|
||||
*
|
||||
* @return how many records were deleted, at most {@code limit}
|
||||
* @throws IllegalArgumentException when {@code limit} is not positive
|
||||
*/
|
||||
int purgeCompletedBefore(Instant completedBefore, int limit);
|
||||
|
||||
/**
|
||||
* Releases a claim that will never complete, so the caller may try again.
|
||||
*
|
||||
|
||||
+102
-2
@@ -13,6 +13,7 @@ import java.util.concurrent.CountDownLatch;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.Future;
|
||||
import java.util.stream.Stream;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
@@ -40,6 +41,10 @@ public abstract class GrpcOperationLedgerContract {
|
||||
// A retry arriving after the TTL: its cutoff (LATER - TTL) is past the original claim at NOW.
|
||||
private static final Instant LATER = NOW.plus(CLAIM_TTL).plusSeconds(1);
|
||||
private static final Instant CUTOFF = LATER.minus(CLAIM_TTL);
|
||||
// A purge run a day after NOW: rows finished around NOW are past retention.
|
||||
private static final Instant RETENTION_CUTOFF = NOW.plus(Duration.ofDays(1));
|
||||
private static final GrpcOperationIdentity SECOND_ID = identityWithKeyHash('b');
|
||||
private static final GrpcOperationIdentity THIRD_ID = identityWithKeyHash('c');
|
||||
|
||||
/** The ledger under test, holding no records when a test starts. */
|
||||
protected abstract GrpcOperationLedger ledger();
|
||||
@@ -397,9 +402,104 @@ public abstract class GrpcOperationLedgerContract {
|
||||
assertThat(refused).isInstanceOf(IllegalArgumentException.class).hasMessageContaining("cutoff");
|
||||
}
|
||||
|
||||
private void failedClaim() {
|
||||
@Test
|
||||
@DisplayName("보존 기간이 지난 COMMITTED·FAILED_TERMINAL 행은 정리된다")
|
||||
void finishedRecordsCompletedBeforeTheCutoffArePurged() {
|
||||
// given
|
||||
committedClaim(ID, NOW);
|
||||
failedClaim(SECOND_ID, NOW);
|
||||
|
||||
// when
|
||||
int purged = ledger().purgeCompletedBefore(RETENTION_CUTOFF, 10);
|
||||
|
||||
// then
|
||||
assertThat(purged).isEqualTo(2);
|
||||
assertThat(ledger().find(ID)).isEmpty();
|
||||
assertThat(ledger().find(SECOND_ID)).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("IN_PROGRESS 행은 아무리 오래되어도 정리하지 않는다")
|
||||
void anInProgressClaimIsNeverPurgedHoweverOld() {
|
||||
// given
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
ledger().markFailed(ID, NOW.plusSeconds(1));
|
||||
|
||||
// when
|
||||
int purged = ledger().purgeCompletedBefore(RETENTION_CUTOFF, 10);
|
||||
|
||||
// then
|
||||
assertThat(purged).isZero();
|
||||
assertThat(ledger().find(ID))
|
||||
.get()
|
||||
.extracting(GrpcOperationLedgerRecord::state)
|
||||
.isEqualTo(GrpcOperationLedgerState.IN_PROGRESS);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("cutoff 이후에 끝난 행은 남긴다")
|
||||
void finishedRecordsCompletedAtOrAfterTheCutoffAreKept() {
|
||||
// given
|
||||
committedClaim(ID, RETENTION_CUTOFF.minusSeconds(1));
|
||||
failedClaim(SECOND_ID, RETENTION_CUTOFF.minusSeconds(1));
|
||||
|
||||
// when
|
||||
int purged = ledger().purgeCompletedBefore(RETENTION_CUTOFF, 10);
|
||||
|
||||
// then
|
||||
assertThat(purged).isZero();
|
||||
assertThat(ledger().find(ID)).isPresent();
|
||||
assertThat(ledger().find(SECOND_ID)).isPresent();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("한 번의 정리는 limit 개수까지만 지운다")
|
||||
void onePurgeDeletesAtMostTheLimit() {
|
||||
// given
|
||||
committedClaim(ID, NOW);
|
||||
committedClaim(SECOND_ID, NOW.plusSeconds(1));
|
||||
committedClaim(THIRD_ID, NOW.plusSeconds(2));
|
||||
|
||||
// when
|
||||
int purged = ledger().purgeCompletedBefore(RETENTION_CUTOFF, 2);
|
||||
|
||||
// then
|
||||
assertThat(purged).isEqualTo(2);
|
||||
assertThat(
|
||||
Stream.of(ID, SECOND_ID, THIRD_ID)
|
||||
.filter(identity -> ledger().find(identity).isPresent())
|
||||
.count())
|
||||
.isEqualTo(1);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("limit이 양수가 아니면 정리를 거부한다")
|
||||
void aNonPositivePurgeLimitIsRefused() {
|
||||
// when
|
||||
Throwable refused = catchThrowable(() -> ledger().purgeCompletedBefore(RETENTION_CUTOFF, 0));
|
||||
|
||||
// then
|
||||
assertThat(refused).isInstanceOf(IllegalArgumentException.class).hasMessageContaining("limit");
|
||||
}
|
||||
|
||||
private void failedClaim() {
|
||||
failedClaim(ID, NOW);
|
||||
}
|
||||
|
||||
// Claimed at `claimedAt`, finished one second later, so the completion moment is what a purge
|
||||
// cutoff is compared with.
|
||||
private void failedClaim(GrpcOperationIdentity identity, Instant claimedAt) {
|
||||
ledger().claim(identity, FINGERPRINT, claimedAt);
|
||||
ledger().markFailed(identity, claimedAt.plusSeconds(1));
|
||||
}
|
||||
|
||||
private void committedClaim(GrpcOperationIdentity identity, Instant claimedAt) {
|
||||
ledger().claim(identity, FINGERPRINT, claimedAt);
|
||||
ledger().markCommitted(identity, OUTCOME, claimedAt.plusSeconds(1));
|
||||
}
|
||||
|
||||
private static GrpcOperationIdentity identityWithKeyHash(char hexDigit) {
|
||||
return new GrpcOperationIdentity(
|
||||
ID.callerFingerprint(), ID.method(), "sha256:" + String.valueOf(hexDigit).repeat(64));
|
||||
}
|
||||
|
||||
/** Runs {@code attempt} on two threads released together and returns both results. */
|
||||
|
||||
+27
-2
@@ -1,6 +1,8 @@
|
||||
package dev.caskeleton.grpc.api.ledger;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Comparator;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.concurrent.ConcurrentHashMap;
|
||||
import java.util.concurrent.ConcurrentMap;
|
||||
@@ -10,8 +12,8 @@ import java.util.concurrent.ConcurrentMap;
|
||||
*
|
||||
* <p>{@code putIfAbsent} on a concurrent map is the in-memory equivalent of the unique constraint
|
||||
* the real adapter relies on, and {@code replace(key, expected, next)} of its conditional update,
|
||||
* so claim, re-claim and stale takeover are atomic here for the same reason they are there. The
|
||||
* transitions match the JPA adapter's because {@link GrpcOperationLedgerContract} runs against
|
||||
* so claim, re-claim, stale takeover and purge are atomic here for the same reason they are there.
|
||||
* The transitions match the JPA adapter's because {@link GrpcOperationLedgerContract} runs against
|
||||
* both; a fake that allowed more would let the policy tests pass for code the database refuses.
|
||||
*/
|
||||
public final class InMemoryOperationLedger implements GrpcOperationLedger {
|
||||
@@ -102,6 +104,29 @@ public final class InMemoryOperationLedger implements GrpcOperationLedger {
|
||||
GrpcOperationLedgerRecord.claim(identity, requestFingerprint, now));
|
||||
}
|
||||
|
||||
@Override
|
||||
public int purgeCompletedBefore(Instant completedBefore, int limit) {
|
||||
if (limit < 1) {
|
||||
throw new IllegalArgumentException("a purge limit must be positive");
|
||||
}
|
||||
List<GrpcOperationLedgerRecord> expired =
|
||||
records.values().stream()
|
||||
.filter(record -> record.state().terminal())
|
||||
.filter(record -> record.completedAt().orElseThrow().isBefore(completedBefore))
|
||||
.sorted(Comparator.comparing(record -> record.completedAt().orElseThrow()))
|
||||
.limit(limit)
|
||||
.toList();
|
||||
int purged = 0;
|
||||
for (GrpcOperationLedgerRecord record : expired) {
|
||||
// Conditional, like the database's re-checked DELETE: a row re-claimed since it was read is
|
||||
// IN_PROGRESS again and stays.
|
||||
if (records.remove(record.identity().storageKey(), record)) {
|
||||
purged++;
|
||||
}
|
||||
}
|
||||
return purged;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void release(GrpcOperationIdentity identity) {
|
||||
records.remove(identity.storageKey());
|
||||
|
||||
Reference in New Issue
Block a user