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:
@@ -1,5 +1,6 @@
|
||||
plugins {
|
||||
id 'ca.java-library'
|
||||
id 'java-test-fixtures'
|
||||
}
|
||||
|
||||
// Optional fileserver application product. Shared error codes are part of its public failure
|
||||
@@ -7,4 +8,12 @@ plugins {
|
||||
dependencies {
|
||||
implementation project(':application-core')
|
||||
implementation project(':shared-contract')
|
||||
|
||||
// Port contracts (`*Contract`) are abstract JUnit classes that the in-memory fakes here and the
|
||||
// JPA adapters in persistence-fileserver both extend, so a use-case test that passes against a
|
||||
// fake is passing against the behaviour the real store is held to (AGENTS.md test rule 6).
|
||||
// FileserverException's error code is a shared-contract type; the contracts assert on it.
|
||||
testFixturesImplementation project(':shared-contract')
|
||||
testFixturesImplementation 'org.junit.jupiter:junit-jupiter-api'
|
||||
testFixturesImplementation 'org.assertj:assertj-core'
|
||||
}
|
||||
|
||||
@@ -1,40 +1,40 @@
|
||||
# This is a Gradle generated file for dependency locking.
|
||||
# Manual edits can break the build and are not advised.
|
||||
# This file is expected to be part of source control.
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
|
||||
com.github.spotbugs:spotbugs:4.10.2=spotbugs
|
||||
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
|
||||
com.google.code.gson:gson:2.13.2=spotbugs
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
jaxen:jaxen:2.0.6=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
@@ -50,32 +50,32 @@ org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testFixturesCompileClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath,testFixturesAnnotationProcessor,testFixturesCompileClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.3=testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.1.0=spotbugs
|
||||
org.mockito:mockito-core:5.20.0=mockitoAgent
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
|
||||
org.ow2.asm:asm-analysis:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
|
||||
+13
-2
@@ -4,17 +4,28 @@ import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* A persisted unit of deferred physical work.
|
||||
* A claimed unit of deferred physical work.
|
||||
*
|
||||
* <p>The queue owns {@code cleanupId}; the application only ever supplies the {@link
|
||||
* CleanupRequest}. The worker re-checks state, version, and lease before deleting, so an item can
|
||||
* never remove content an active upload still owns.
|
||||
*
|
||||
* <p>{@code claimToken} is the fence of the claim that produced this item. Settling the item
|
||||
* ({@link CleanupQueuePort#markDone}, {@link CleanupQueuePort#markFailed}, {@link
|
||||
* CleanupQueuePort#markAbandoned}) applies only while the queue still records this token, so a
|
||||
* worker that wakes up after its lease expired and the item was reclaimed settles nothing. The
|
||||
* token used to live in a map inside the JPA adapter, which kept the fence out of this contract:
|
||||
* nothing but that one adapter knew it existed, and a fake could not be held to it (review 04-13).
|
||||
*
|
||||
* <p>{@code attempt} is how many attempts were already recorded before this claim. The retry budget
|
||||
* is the application's decision ({@link DefaultCleanupService}); the queue only counts.
|
||||
*/
|
||||
public record CleanupItem(UUID cleanupId, CleanupRequest request, int attempt) {
|
||||
public record CleanupItem(UUID cleanupId, CleanupRequest request, int attempt, UUID claimToken) {
|
||||
|
||||
public CleanupItem {
|
||||
Objects.requireNonNull(cleanupId, "cleanupId");
|
||||
Objects.requireNonNull(request, "request");
|
||||
Objects.requireNonNull(claimToken, "claimToken");
|
||||
if (attempt < 0) {
|
||||
throw new IllegalArgumentException("attempt must not be negative");
|
||||
}
|
||||
|
||||
+36
-2
@@ -1,5 +1,6 @@
|
||||
package dev.caskeleton.application.fileserver.cleanup;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
|
||||
@@ -9,23 +10,56 @@ import java.util.List;
|
||||
* <p>Enqueuing is always the last step of a state transition that already succeeded, so a queued
|
||||
* item never implies that the logical operation is still pending. The queue assigns each item's
|
||||
* identity, keeping identifier generation out of the application layer.
|
||||
*
|
||||
* <p>The queue stores and fences; it does not decide. How long a claim lasts is an argument of
|
||||
* {@link #claimDue}, and when an item has failed often enough to stop retrying is the caller's
|
||||
* decision, expressed by calling {@link #markAbandoned} instead of {@link #markFailed}. Both used
|
||||
* to be constants inside the JPA adapter (review 04-13).
|
||||
*
|
||||
* <p>Every settlement is conditional on the item's {@link CleanupItem#claimToken()}: once the claim
|
||||
* it came from has been reclaimed, settling it changes nothing.
|
||||
*/
|
||||
public interface CleanupQueuePort {
|
||||
|
||||
void enqueue(CleanupRequest request);
|
||||
|
||||
List<CleanupItem> claimDue(Instant now, int limit);
|
||||
/**
|
||||
* Claims due items for this caller.
|
||||
*
|
||||
* <p>Due means PENDING or FAILED with its next attempt at or before {@code now}. A claimed item
|
||||
* is out of the due set until it is settled or its lease expires and {@link
|
||||
* #reclaimExpiredClaims} hands it back. Two callers claiming at once receive disjoint items, and
|
||||
* one does not wait for the other's claim to commit.
|
||||
*
|
||||
* @param now the moment due-ness and the lease are measured from
|
||||
* @param limit how many items one call may claim
|
||||
* @param lease how long the claim holds before a reaper may take the item over
|
||||
* @return the claimed items, each carrying its claim token
|
||||
*/
|
||||
List<CleanupItem> claimDue(Instant now, int limit, Duration lease);
|
||||
|
||||
/** Records a successful attempt, if {@code item}'s claim is still the current one. */
|
||||
void markDone(CleanupItem item);
|
||||
|
||||
/** Records a failed attempt and when to try again, if {@code item}'s claim is still current. */
|
||||
void markFailed(CleanupItem item, String reasonCode, Instant nextAttemptAt);
|
||||
|
||||
/**
|
||||
* Parks an item for good, if {@code item}'s claim is still current.
|
||||
*
|
||||
* <p>An abandoned item is never claimed again but stays visible to an operator. It is parked, not
|
||||
* discarded.
|
||||
*/
|
||||
void markAbandoned(CleanupItem item, String reasonCode);
|
||||
|
||||
/**
|
||||
* Returns items whose worker died mid-claim to the queue.
|
||||
*
|
||||
* <p>A claim moves an item out of the due set, so an item whose worker performed the physical
|
||||
* delete and then died is invisible to {@link #claimDue}: nothing reclaims it, and the file's
|
||||
* quota and lifecycle stay unsettled for good. This is the only path back.
|
||||
* quota and lifecycle stay unsettled for good. This is the only path back. A reclaimed item
|
||||
* counts as one more attempt, so an item whose worker dies every time runs out of the same retry
|
||||
* budget as one that fails outright.
|
||||
*
|
||||
* @param now the moment expiry is judged against
|
||||
* @param limit how many items one pass may reclaim
|
||||
|
||||
+41
-2
@@ -31,6 +31,24 @@ import java.util.Optional;
|
||||
*/
|
||||
public final class DefaultCleanupService implements CleanupService {
|
||||
|
||||
/**
|
||||
* After this many recorded attempts an item is parked instead of rescheduled.
|
||||
*
|
||||
* <p>A poison entry that never succeeds would otherwise occupy a slot in every batch and starve
|
||||
* the work behind it. This is retry policy, so it is decided here rather than in the queue's
|
||||
* adapter, where it used to be a constant nothing outside the persistence leaf could see (review
|
||||
* 04-13).
|
||||
*/
|
||||
public static final int MAXIMUM_ATTEMPTS = 8;
|
||||
|
||||
/**
|
||||
* How long a claim holds before a reaper may hand the item to another worker.
|
||||
*
|
||||
* <p>Long enough for one delete against slow storage; short enough that a worker that died
|
||||
* mid-item does not hold the quota and lifecycle of that file unsettled for long.
|
||||
*/
|
||||
public static final Duration CLAIM_LEASE = Duration.ofMinutes(10);
|
||||
|
||||
private final CleanupQueuePort queue;
|
||||
private final CleanupContentPort contentGateway;
|
||||
private final FileMetadataPort metadataStore;
|
||||
@@ -76,7 +94,7 @@ public final class DefaultCleanupService implements CleanupService {
|
||||
// reclaimed it, and the file's quota and lifecycle stayed unsettled for good. Reclaiming before
|
||||
// claiming means the recovered items are eligible in this same pass.
|
||||
transactions.inWrite(() -> queue.reclaimExpiredClaims(now, maxItems));
|
||||
List<CleanupItem> due = transactions.inWrite(() -> queue.claimDue(now, maxItems));
|
||||
List<CleanupItem> due = transactions.inWrite(() -> queue.claimDue(now, maxItems, CLAIM_LEASE));
|
||||
|
||||
int deleted = 0;
|
||||
int skippedActiveLease = 0;
|
||||
@@ -85,6 +103,16 @@ public final class DefaultCleanupService implements CleanupService {
|
||||
long reclaimed = 0;
|
||||
|
||||
for (CleanupItem item : due) {
|
||||
if (item.attempt() >= MAXIMUM_ATTEMPTS) {
|
||||
// Only a reclaimed claim reaches this: its worker died mid-item often enough to spend the
|
||||
// whole budget without ever reporting a failure, so markFailed never got to park it.
|
||||
transactions.inWrite(
|
||||
() -> {
|
||||
queue.markAbandoned(item, "CLEANUP_ATTEMPTS_EXHAUSTED");
|
||||
});
|
||||
failed++;
|
||||
continue;
|
||||
}
|
||||
if (reclaimed >= maxBytes) {
|
||||
// The byte budget is spent; the remaining claims are released for the next batch rather
|
||||
// than being marked done, so nothing is silently dropped.
|
||||
@@ -302,10 +330,21 @@ public final class DefaultCleanupService implements CleanupService {
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Reschedules an item, or parks it once this failure spends its retry budget.
|
||||
*
|
||||
* <p>{@code item.attempt()} counts the attempts recorded before this one, so this failure is
|
||||
* attempt {@code attempt + 1}.
|
||||
*/
|
||||
private void markFailed(CleanupItem item, String reasonCode, Instant now) {
|
||||
boolean exhausted = item.attempt() + 1 >= MAXIMUM_ATTEMPTS;
|
||||
transactions.inWrite(
|
||||
() -> {
|
||||
queue.markFailed(item, reasonCode, now.plus(retryBackoff));
|
||||
if (exhausted) {
|
||||
queue.markAbandoned(item, reasonCode);
|
||||
} else {
|
||||
queue.markFailed(item, reasonCode, now.plus(retryBackoff));
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
+7
-14
@@ -1,11 +1,7 @@
|
||||
package dev.caskeleton.application.fileserver.observability;
|
||||
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.security.InvalidKeyException;
|
||||
import java.security.NoSuchAlgorithmException;
|
||||
import dev.caskeleton.shared.digest.HmacSha256;
|
||||
import java.util.HexFormat;
|
||||
import javax.crypto.Mac;
|
||||
import javax.crypto.spec.SecretKeySpec;
|
||||
|
||||
/**
|
||||
* Keyed pseudonym for correlating telemetry without disclosing an identifier.
|
||||
@@ -16,10 +12,12 @@ import javax.crypto.spec.SecretKeySpec;
|
||||
*
|
||||
* <p>The output is truncated deliberately. A full digest is longer than any operator needs and
|
||||
* makes a rainbow table over the truncated space no easier.
|
||||
*
|
||||
* <p>The MAC itself is shared-contract's {@link HmacSha256}; this class adds only the key-length
|
||||
* floor and the truncation.
|
||||
*/
|
||||
public final class SafeFileFingerprint {
|
||||
|
||||
private static final String ALGORITHM = "HmacSHA256";
|
||||
private static final int FINGERPRINT_HEX_LENGTH = 16;
|
||||
|
||||
private final byte[] key;
|
||||
@@ -33,13 +31,8 @@ public final class SafeFileFingerprint {
|
||||
|
||||
/** Derives a keyed fingerprint from a canonical identifier. */
|
||||
public String of(String canonicalIdentifier) {
|
||||
try {
|
||||
Mac mac = Mac.getInstance(ALGORITHM);
|
||||
mac.init(new SecretKeySpec(key, ALGORITHM));
|
||||
byte[] digest = mac.doFinal(canonicalIdentifier.getBytes(StandardCharsets.UTF_8));
|
||||
return HexFormat.of().formatHex(digest).substring(0, FINGERPRINT_HEX_LENGTH);
|
||||
} catch (NoSuchAlgorithmException | InvalidKeyException failure) {
|
||||
throw new IllegalStateException("HMAC-SHA256 is required by the platform", failure);
|
||||
}
|
||||
return HexFormat.of()
|
||||
.formatHex(HmacSha256.sign(key, canonicalIdentifier))
|
||||
.substring(0, FINGERPRINT_HEX_LENGTH);
|
||||
}
|
||||
}
|
||||
|
||||
+1
-4
@@ -263,10 +263,7 @@ class FileserverAdminUseCasesTest {
|
||||
uploading.fileId(), "LEGAL_TAKEDOWN_2026_08", FileserverFixtures.context()));
|
||||
|
||||
// then
|
||||
assertThat(
|
||||
List.of(
|
||||
sessions.find(uploadId).orElseThrow().terminal(),
|
||||
queue.queued().stream().map(item -> item.request()).toList()))
|
||||
assertThat(List.of(sessions.find(uploadId).orElseThrow().terminal(), queue.queued()))
|
||||
.containsExactly(
|
||||
true,
|
||||
List.of(
|
||||
|
||||
+57
@@ -28,6 +28,7 @@ import java.time.Duration;
|
||||
import java.time.ZoneOffset;
|
||||
import java.util.OptionalLong;
|
||||
import java.util.UUID;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class CleanupServiceTest {
|
||||
@@ -441,6 +442,62 @@ class CleanupServiceTest {
|
||||
assertThat(content.quarantineHolds(orphan)).isFalse();
|
||||
}
|
||||
|
||||
/** The retry budget is the service's decision; the queue only counts (review 04-13). */
|
||||
@Test
|
||||
@DisplayName("시도 한도를 다 쓰는 실패는 재시도 예약 대신 포기로 기록된다")
|
||||
void theFailureThatSpendsTheLastAttemptParksTheItemInsteadOfReschedulingIt() {
|
||||
// given
|
||||
UploadId uploadId = UploadId.of(UUID.randomUUID());
|
||||
FileId fileId = FileId.of(UUID.randomUUID());
|
||||
leasedSession(uploadId, fileId);
|
||||
content.storeStaging(uploadId);
|
||||
queue.enqueue(CleanupRequest.forStaging(CleanupType.CANCELLED_STAGING, fileId, uploadId));
|
||||
failPreviousAttempts(DefaultCleanupService.MAXIMUM_ATTEMPTS - 1);
|
||||
|
||||
// when
|
||||
cleanup.runBatch(100, 1L << 30);
|
||||
|
||||
// then
|
||||
assertThat(queue.abandoned().values()).containsExactly("ACTIVE_WRITER_LEASE");
|
||||
assertThat(queue.queued()).isEmpty();
|
||||
}
|
||||
|
||||
/**
|
||||
* A reclaimed claim counts as an attempt but never reaches markFailed, so an item whose worker
|
||||
* dies every time would otherwise be claimed forever.
|
||||
*/
|
||||
@Test
|
||||
@DisplayName("이미 시도 한도를 다 쓴 채 claim된 항목은 처리하지 않고 포기한다")
|
||||
void anItemClaimedWithItsBudgetAlreadySpentIsParkedWithoutBeingProcessed() {
|
||||
// given
|
||||
FileRecord deleting = deletingRecord();
|
||||
content.store(ContentKey.of(ReadyFileFixture.CONTENT_KEY));
|
||||
queue.enqueue(
|
||||
CleanupRequest.forContent(
|
||||
CleanupType.DELETED_READY_CONTENT,
|
||||
deleting.fileId(),
|
||||
ContentKey.of(ReadyFileFixture.CONTENT_KEY)));
|
||||
failPreviousAttempts(DefaultCleanupService.MAXIMUM_ATTEMPTS);
|
||||
|
||||
// when
|
||||
CleanupBatchResult result = cleanup.runBatch(100, 1L << 30);
|
||||
|
||||
// then
|
||||
assertThat(result.failed()).isEqualTo(1);
|
||||
assertThat(queue.abandoned().values()).containsExactly("CLEANUP_ATTEMPTS_EXHAUSTED");
|
||||
assertThat(content.exists(ContentKey.of(ReadyFileFixture.CONTENT_KEY))).isTrue();
|
||||
}
|
||||
|
||||
/** Records {@code attempts} failures against every queued item, each due again at once. */
|
||||
private void failPreviousAttempts(int attempts) {
|
||||
for (int attempt = 0; attempt < attempts; attempt++) {
|
||||
for (CleanupItem item :
|
||||
queue.claimDue(FileserverFixtures.NOW, 100, DefaultCleanupService.CLAIM_LEASE)) {
|
||||
queue.markFailed(item, "EARLIER_ATTEMPT", FileserverFixtures.NOW);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private UploadId expiredSession(FileId fileId) {
|
||||
UploadId uploadId = UploadId.of(UUID.randomUUID());
|
||||
sessions.create(
|
||||
|
||||
+1
-4
@@ -141,10 +141,7 @@ class FileLifecycleUseCasesTest {
|
||||
new DeleteFileCommand(uploading.fileId(), Optional.empty(), FileserverFixtures.context()));
|
||||
|
||||
// then
|
||||
assertThat(
|
||||
List.of(
|
||||
sessions.find(uploadId).orElseThrow().terminal(),
|
||||
cleanup.queued().stream().map(item -> item.request()).toList()))
|
||||
assertThat(List.of(sessions.find(uploadId).orElseThrow().terminal(), cleanup.queued()))
|
||||
.containsExactly(
|
||||
true,
|
||||
List.of(
|
||||
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
package dev.caskeleton.application.fileserver.observability;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class SafeFileFingerprintTest {
|
||||
|
||||
private static final byte[] KEY = "0123456789abcdef".getBytes(StandardCharsets.US_ASCII);
|
||||
|
||||
/** Pinned so a change of implementation cannot silently change every logged fingerprint. */
|
||||
@Test
|
||||
void theFingerprintIsTheFirstSixteenHexDigitsOfTheHmacSha256() {
|
||||
assertThat(new SafeFileFingerprint(KEY).of("file-1")).isEqualTo("36ab85774f9cd9ce");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aKeyShorterThanSixteenBytesIsRefused() {
|
||||
// when
|
||||
Throwable thrown = catchThrowable(() -> new SafeFileFingerprint(new byte[15]));
|
||||
|
||||
// then
|
||||
assertThat(thrown)
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessage("fingerprint key must be at least 16 bytes");
|
||||
}
|
||||
}
|
||||
-77
@@ -1,77 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.testkit;
|
||||
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupItem;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
|
||||
import java.time.Instant;
|
||||
import java.util.ArrayList;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Hand-rolled cleanup queue that records what was scheduled.
|
||||
*
|
||||
* <p>Like the durable queue, it assigns the item identity on enqueue. Claim leases are recorded
|
||||
* rather than enforced: the fencing they exist for is a database property, and a fake that pretends
|
||||
* to have it would report success for a guarantee only real PostgreSQL can give.
|
||||
*/
|
||||
public final class InMemoryCleanupQueue implements CleanupQueuePort {
|
||||
|
||||
private final List<CleanupItem> queued = new ArrayList<>();
|
||||
private final List<CleanupItem> done = new ArrayList<>();
|
||||
private final Map<CleanupItem, String> failed = new LinkedHashMap<>();
|
||||
private final List<Instant> reclaimSweeps = new ArrayList<>();
|
||||
private final List<Instant> claimSweeps = new ArrayList<>();
|
||||
|
||||
@Override
|
||||
public void enqueue(CleanupRequest request) {
|
||||
queued.add(new CleanupItem(UUID.randomUUID(), request, 0));
|
||||
}
|
||||
|
||||
@Override
|
||||
public int reclaimExpiredClaims(Instant now, int limit) {
|
||||
reclaimSweeps.add(now);
|
||||
return 0;
|
||||
}
|
||||
|
||||
/** The moments a batch asked for abandoned claims back, in order. */
|
||||
public List<Instant> reclaimSweeps() {
|
||||
return List.copyOf(reclaimSweeps);
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<CleanupItem> claimDue(Instant now, int limit) {
|
||||
claimSweeps.add(now);
|
||||
return List.copyOf(queued.subList(0, Math.min(limit, queued.size())));
|
||||
}
|
||||
|
||||
@Override
|
||||
public void markDone(CleanupItem item) {
|
||||
queued.remove(item);
|
||||
done.add(item);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void markFailed(CleanupItem item, String reasonCode, Instant nextAttemptAt) {
|
||||
failed.put(item, reasonCode);
|
||||
}
|
||||
|
||||
/** The moments a batch claimed due items, in order. */
|
||||
public List<Instant> claimSweeps() {
|
||||
return List.copyOf(claimSweeps);
|
||||
}
|
||||
|
||||
public List<CleanupItem> queued() {
|
||||
return List.copyOf(queued);
|
||||
}
|
||||
|
||||
public List<CleanupItem> done() {
|
||||
return List.copyOf(done);
|
||||
}
|
||||
|
||||
public Map<CleanupItem, String> failed() {
|
||||
return Map.copyOf(failed);
|
||||
}
|
||||
}
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
package dev.caskeleton.application.fileserver.testkit;
|
||||
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
|
||||
import java.time.Instant;
|
||||
|
||||
class InMemoryCleanupQueueContractTest extends CleanupQueuePortContract {
|
||||
|
||||
private final InMemoryCleanupQueue queue = new InMemoryCleanupQueue();
|
||||
|
||||
@Override
|
||||
protected CleanupQueuePort queue() {
|
||||
return queue;
|
||||
}
|
||||
|
||||
@Override
|
||||
protected Instant enqueueInstant() {
|
||||
return FileserverFixtures.NOW;
|
||||
}
|
||||
}
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
package dev.caskeleton.application.fileserver.testkit;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
|
||||
|
||||
class InMemoryFileMetadataStoreContractTest extends FileMetadataPortContract {
|
||||
|
||||
private final InMemoryFileMetadataStore metadata = new InMemoryFileMetadataStore();
|
||||
|
||||
@Override
|
||||
protected FileMetadataPort metadata() {
|
||||
return metadata;
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -130,7 +130,7 @@ class ResumableUploadUseCasesTest {
|
||||
|
||||
// then
|
||||
assertThat(cleanup.queued())
|
||||
.extracting(item -> item.request().type())
|
||||
.extracting(request -> request.type())
|
||||
.contains(CleanupType.DELETED_READY_CONTENT);
|
||||
}
|
||||
|
||||
|
||||
+241
@@ -0,0 +1,241 @@
|
||||
package dev.caskeleton.application.fileserver.testkit;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupItem;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupType;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.UUID;
|
||||
import java.util.function.Supplier;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* What every {@link CleanupQueuePort} promises, run against the in-memory fake and the PostgreSQL
|
||||
* adapter alike.
|
||||
*
|
||||
* <p>The queue stores and fences; the retry budget and the lease length are the caller's. So this
|
||||
* contract is about the mechanics the cleanup worker relies on: a claim takes an item out of the
|
||||
* due set and hands it a token, a settlement applies only under that token, and an expired claim
|
||||
* comes back as one more attempt. Concurrency between transactions ({@code SKIP LOCKED}) is a
|
||||
* database property and is proved by the PostgreSQL test on its own.
|
||||
*
|
||||
* <p>Every test enqueues its own items; the subclass supplies an empty queue per test.
|
||||
*/
|
||||
public abstract class CleanupQueuePortContract {
|
||||
|
||||
private static final Duration LEASE = Duration.ofMinutes(1);
|
||||
|
||||
protected abstract CleanupQueuePort queue();
|
||||
|
||||
/**
|
||||
* An instant, fixed for the duration of one test, by which every item the test enqueues is due by
|
||||
* the queue's own clock. The contract claims one second after it.
|
||||
*/
|
||||
protected abstract Instant enqueueInstant();
|
||||
|
||||
/** Runs one store call inside the caller transaction the adapter requires. */
|
||||
protected <T> T transactionally(Supplier<T> action) {
|
||||
return action.get();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("넣은 항목은 요청과 시도 0회, claim 토큰을 실어 claim된다")
|
||||
void anEnqueuedItemIsClaimedWithItsRequestNoAttemptsAndAClaimToken() {
|
||||
// given
|
||||
CleanupRequest request = contentCleanup();
|
||||
enqueue(request);
|
||||
|
||||
// when
|
||||
List<CleanupItem> claimed = claim(due(), 10);
|
||||
|
||||
// then
|
||||
assertThat(claimed)
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
item -> {
|
||||
assertThat(item.request()).isEqualTo(request);
|
||||
assertThat(item.attempt()).isZero();
|
||||
assertThat(item.claimToken()).isNotNull();
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("한 번의 claim은 limit보다 많은 항목을 가져가지 않는다")
|
||||
void aClaimTakesNoMoreItemsThanItsLimit() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
enqueue(contentCleanup());
|
||||
enqueue(contentCleanup());
|
||||
|
||||
// when
|
||||
List<CleanupItem> claimed = claim(due(), 2);
|
||||
|
||||
// then
|
||||
assertThat(claimed).hasSize(2);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("claim된 항목은 lease가 남아 있는 동안 다른 claim에 다시 나오지 않는다")
|
||||
void aClaimedItemIsNotHandedToASecondClaimWhileItsLeaseHolds() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
claim(due(), 10);
|
||||
|
||||
// when
|
||||
List<CleanupItem> second = claim(due().plusSeconds(1), 10);
|
||||
|
||||
// then
|
||||
assertThat(second).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("실패 처리된 항목은 다음 시도 시각 이후에만 시도 횟수 1을 달고 다시 claim된다")
|
||||
void aFailedItemComesBackOnlyAfterItsNextAttemptWithTheAttemptCounted() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
CleanupItem item = claim(due(), 10).get(0);
|
||||
Instant retryAt = due().plus(Duration.ofMinutes(5));
|
||||
settle(() -> queue().markFailed(item, "STORAGE_UNAVAILABLE", retryAt));
|
||||
assertThat(claim(retryAt.minusSeconds(1), 10)).isEmpty();
|
||||
|
||||
// when
|
||||
List<CleanupItem> retried = claim(retryAt, 10);
|
||||
|
||||
// then
|
||||
assertThat(retried)
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
again -> {
|
||||
assertThat(again.cleanupId()).isEqualTo(item.cleanupId());
|
||||
assertThat(again.attempt()).isEqualTo(1);
|
||||
assertThat(again.claimToken()).isNotEqualTo(item.claimToken());
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("완료된 항목은 다시 claim되지 않는다")
|
||||
void aDoneItemIsNeverClaimedAgain() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
CleanupItem item = claim(due(), 10).get(0);
|
||||
settle(() -> queue().markDone(item));
|
||||
|
||||
// when
|
||||
List<CleanupItem> later = claim(due().plus(Duration.ofDays(1)), 10);
|
||||
|
||||
// then
|
||||
assertThat(later).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("포기된 항목은 다시 claim되지 않는다")
|
||||
void anAbandonedItemIsNeverClaimedAgain() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
CleanupItem item = claim(due(), 10).get(0);
|
||||
settle(() -> queue().markAbandoned(item, "CLEANUP_ATTEMPTS_EXHAUSTED"));
|
||||
|
||||
// when
|
||||
List<CleanupItem> later = claim(due().plus(Duration.ofDays(1)), 10);
|
||||
|
||||
// then
|
||||
assertThat(later).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("lease가 끝나기 전의 claim은 회수되지 않는다")
|
||||
void aClaimIsNotReclaimedBeforeItsLeaseEnds() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
claim(due(), 10);
|
||||
|
||||
// when
|
||||
int reclaimed = transactionally(() -> queue().reclaimExpiredClaims(due().plus(LEASE), 10));
|
||||
|
||||
// then
|
||||
assertThat(reclaimed).isZero();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("lease가 끝난 claim은 회수되어 시도 하나를 더 센 채 다시 claim된다")
|
||||
void anExpiredClaimIsReclaimedAndComesBackWithOneMoreAttempt() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
CleanupItem stalled = claim(due(), 10).get(0);
|
||||
Instant afterLease = due().plus(LEASE).plusSeconds(1);
|
||||
assertThat(transactionally(() -> queue().reclaimExpiredClaims(afterLease, 10))).isEqualTo(1);
|
||||
|
||||
// when
|
||||
List<CleanupItem> takenOver = claim(afterLease, 10);
|
||||
|
||||
// then
|
||||
assertThat(takenOver)
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
item -> {
|
||||
assertThat(item.cleanupId()).isEqualTo(stalled.cleanupId());
|
||||
assertThat(item.attempt()).isEqualTo(1);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* The fence: a worker that wakes up after its claim was reclaimed and handed to another worker
|
||||
* settles nothing. Had its DONE landed, the second worker's claim would be gone and its item
|
||||
* would never be reclaimed again.
|
||||
*/
|
||||
@Test
|
||||
@DisplayName("회수된 claim의 토큰으로 한 완료는 새 claim을 덮어쓰지 않는다")
|
||||
void aCompletionUnderAReclaimedTokenDoesNotOverwriteTheNewClaim() {
|
||||
// given
|
||||
enqueue(contentCleanup());
|
||||
CleanupItem stalled = claim(due(), 10).get(0);
|
||||
Instant afterFirstLease = due().plus(LEASE).plusSeconds(1);
|
||||
transactionally(() -> queue().reclaimExpiredClaims(afterFirstLease, 10));
|
||||
claim(afterFirstLease, 10);
|
||||
|
||||
// when
|
||||
settle(() -> queue().markDone(stalled));
|
||||
|
||||
// then
|
||||
Instant afterSecondLease = afterFirstLease.plus(LEASE).plusSeconds(1);
|
||||
assertThat(transactionally(() -> queue().reclaimExpiredClaims(afterSecondLease, 10)))
|
||||
.as("the second claim is still the one the queue holds")
|
||||
.isEqualTo(1);
|
||||
}
|
||||
|
||||
private void enqueue(CleanupRequest request) {
|
||||
settle(() -> queue().enqueue(request));
|
||||
}
|
||||
|
||||
private List<CleanupItem> claim(Instant now, int limit) {
|
||||
return transactionally(() -> queue().claimDue(now, limit, LEASE));
|
||||
}
|
||||
|
||||
private void settle(Runnable action) {
|
||||
transactionally(
|
||||
() -> {
|
||||
action.run();
|
||||
return null;
|
||||
});
|
||||
}
|
||||
|
||||
/** A moment at which everything enqueued so far is due. */
|
||||
private Instant due() {
|
||||
return enqueueInstant().plusSeconds(1);
|
||||
}
|
||||
|
||||
private static CleanupRequest contentCleanup() {
|
||||
String flat = UUID.randomUUID().toString().replace("-", "");
|
||||
return CleanupRequest.forContent(
|
||||
CleanupType.DELETED_READY_CONTENT,
|
||||
FileId.of(UUID.randomUUID()),
|
||||
ContentKey.of(flat.substring(0, 2) + '/' + flat.substring(2, 4) + '/' + flat));
|
||||
}
|
||||
}
|
||||
+157
@@ -0,0 +1,157 @@
|
||||
package dev.caskeleton.application.fileserver.testkit;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
import dev.caskeleton.application.fileserver.api.StorageNamespace;
|
||||
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
|
||||
import dev.caskeleton.application.fileserver.api.error.FileserverException;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileOwner;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileRecordDraft;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
import java.util.UUID;
|
||||
import java.util.function.Supplier;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* What every {@link FileMetadataPort} promises, run against the in-memory fake and the PostgreSQL
|
||||
* adapter alike.
|
||||
*
|
||||
* <p>Use-case tests run on the fake. They are only worth something if the fake answers the way the
|
||||
* database does — the same version after insert and transition, the same refusal for a stale
|
||||
* version, and the same refusal for an id that already exists — so both are held to this.
|
||||
*
|
||||
* <p>Every test inserts its own records under fresh ids.
|
||||
*/
|
||||
public abstract class FileMetadataPortContract {
|
||||
|
||||
protected abstract FileMetadataPort metadata();
|
||||
|
||||
/** Runs one store call inside the caller transaction the adapter requires, and commits it. */
|
||||
protected <T> T transactionally(Supplier<T> action) {
|
||||
return action.get();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("새 레코드는 CREATED 상태, 버전 0으로 저장되고 그대로 다시 읽힌다")
|
||||
void anInsertedRecordIsStoredAsCreatedAtVersionZeroAndReadBack() {
|
||||
// given
|
||||
FileId fileId = FileId.of(UUID.randomUUID());
|
||||
|
||||
// when
|
||||
FileRecord inserted = transactionally(() -> metadata().insert(draft(fileId, "report.bin")));
|
||||
|
||||
// then
|
||||
FileRecord found = transactionally(() -> metadata().find(fileId)).orElseThrow();
|
||||
assertThat(inserted.state()).isEqualTo(FileState.CREATED);
|
||||
assertThat(inserted.version()).isZero();
|
||||
assertThat(found.version()).isZero();
|
||||
assertThat(found.originalName()).isEqualTo("report.bin");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("상태 전이는 상태를 바꾸고 버전을 하나 올린다")
|
||||
void aTransitionChangesTheStateAndAdvancesTheVersion() {
|
||||
// given
|
||||
FileRecord created = insert();
|
||||
|
||||
// when
|
||||
FileRecord uploading =
|
||||
transactionally(
|
||||
() ->
|
||||
metadata()
|
||||
.transition(
|
||||
created.fileId(),
|
||||
created.version(),
|
||||
FileState.CREATED,
|
||||
FileState.UPLOADING,
|
||||
FileRecordMutation.none()));
|
||||
|
||||
// then
|
||||
assertThat(uploading.state()).isEqualTo(FileState.UPLOADING);
|
||||
assertThat(uploading.version()).isEqualTo(created.version() + 1);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("지난 버전으로 한 전이는 동시 수정으로 거절되고 레코드는 그대로다")
|
||||
void aTransitionFromAStaleVersionIsRefusedAsAConcurrentModification() {
|
||||
// given
|
||||
FileRecord created = insert();
|
||||
transactionally(
|
||||
() ->
|
||||
metadata()
|
||||
.transition(
|
||||
created.fileId(),
|
||||
created.version(),
|
||||
FileState.CREATED,
|
||||
FileState.UPLOADING,
|
||||
FileRecordMutation.none()));
|
||||
|
||||
// when
|
||||
Throwable refused =
|
||||
catchThrowable(
|
||||
() ->
|
||||
transactionally(
|
||||
() ->
|
||||
metadata()
|
||||
.transition(
|
||||
created.fileId(),
|
||||
created.version(),
|
||||
FileState.CREATED,
|
||||
FileState.UPLOADING,
|
||||
FileRecordMutation.none())));
|
||||
|
||||
// then
|
||||
assertThat(refused)
|
||||
.isInstanceOfSatisfying(
|
||||
FileserverException.class,
|
||||
failure ->
|
||||
assertThat(failure.code()).isEqualTo(FileserverErrorCode.CONCURRENT_MODIFICATION));
|
||||
assertThat(transactionally(() -> metadata().find(created.fileId())).orElseThrow().version())
|
||||
.isEqualTo(created.version() + 1);
|
||||
}
|
||||
|
||||
/**
|
||||
* An id is assigned before the insert, so a second insert under it is a caller bug or a replay.
|
||||
* It has to fail. The JPA adapter used to merge it into the existing row instead — the second
|
||||
* draft silently replaced the first record (review 04-17).
|
||||
*/
|
||||
@Test
|
||||
@DisplayName("이미 있는 id로 다시 넣으면 거절되고 처음 레코드가 그대로 남는다")
|
||||
void insertingASecondRecordUnderAnExistingIdIsRefusedAndKeepsTheFirst() {
|
||||
// given
|
||||
FileId fileId = FileId.of(UUID.randomUUID());
|
||||
transactionally(() -> metadata().insert(draft(fileId, "report.bin")));
|
||||
|
||||
// when
|
||||
Throwable refused =
|
||||
catchThrowable(() -> transactionally(() -> metadata().insert(draft(fileId, "other.bin"))));
|
||||
|
||||
// then
|
||||
assertThat(refused).isNotNull();
|
||||
assertThat(transactionally(() -> metadata().find(fileId)).orElseThrow().originalName())
|
||||
.isEqualTo("report.bin");
|
||||
}
|
||||
|
||||
private FileRecord insert() {
|
||||
return transactionally(
|
||||
() -> metadata().insert(draft(FileId.of(UUID.randomUUID()), "report.bin")));
|
||||
}
|
||||
|
||||
private static FileRecordDraft draft(FileId fileId, String originalName) {
|
||||
return new FileRecordDraft(
|
||||
fileId,
|
||||
StorageNamespace.of("tenant-a"),
|
||||
originalName,
|
||||
Optional.of("application/octet-stream"),
|
||||
OptionalLong.of(10),
|
||||
new FileOwner("user-1", Optional.of("tenant-a")));
|
||||
}
|
||||
}
|
||||
+191
@@ -0,0 +1,191 @@
|
||||
package dev.caskeleton.application.fileserver.testkit;
|
||||
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupItem;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
|
||||
import java.time.Clock;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.time.ZoneOffset;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Comparator;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Hand-rolled cleanup queue with the durable queue's claim, fencing and settlement rules.
|
||||
*
|
||||
* <p>It is held to {@link CleanupQueuePortContract}, the same contract the JPA adapter passes
|
||||
* against PostgreSQL: claims hand out tokens, a settlement with a token the row no longer carries
|
||||
* changes nothing, and an expired lease is taken back by {@link #reclaimExpiredClaims}. What it
|
||||
* cannot reproduce is concurrency between transactions — {@code SKIP LOCKED} only exists in the
|
||||
* database — so that part of the contract is proved by the PostgreSQL test alone.
|
||||
*
|
||||
* <p>Like the durable queue, it assigns the item identity on enqueue, and an enqueued item is due
|
||||
* at the queue clock's instant.
|
||||
*/
|
||||
public final class InMemoryCleanupQueue implements CleanupQueuePort {
|
||||
|
||||
private static final Instant DEFAULT_NOW = Instant.parse("2026-08-07T10:00:00Z");
|
||||
|
||||
private final Clock clock;
|
||||
private final Map<UUID, Row> rows = new LinkedHashMap<>();
|
||||
private final List<CleanupItem> done = new ArrayList<>();
|
||||
private final Map<CleanupItem, String> failed = new LinkedHashMap<>();
|
||||
private final Map<CleanupItem, String> abandoned = new LinkedHashMap<>();
|
||||
private final List<Instant> reclaimSweeps = new ArrayList<>();
|
||||
private final List<Instant> claimSweeps = new ArrayList<>();
|
||||
|
||||
public InMemoryCleanupQueue() {
|
||||
this(Clock.fixed(DEFAULT_NOW, ZoneOffset.UTC));
|
||||
}
|
||||
|
||||
public InMemoryCleanupQueue(Clock clock) {
|
||||
this.clock = Objects.requireNonNull(clock, "clock");
|
||||
}
|
||||
|
||||
@Override
|
||||
public void enqueue(CleanupRequest request) {
|
||||
UUID cleanupId = UUID.randomUUID();
|
||||
rows.put(cleanupId, new Row(cleanupId, request, clock.instant()));
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<CleanupItem> claimDue(Instant now, int limit, Duration lease) {
|
||||
if (limit < 1) {
|
||||
throw new IllegalArgumentException("limit must be positive");
|
||||
}
|
||||
if (lease == null || lease.isNegative() || lease.isZero()) {
|
||||
throw new IllegalArgumentException("lease must be positive");
|
||||
}
|
||||
claimSweeps.add(now);
|
||||
List<CleanupItem> claimed = new ArrayList<>();
|
||||
rows.values().stream()
|
||||
.filter(row -> row.status == Status.PENDING || row.status == Status.FAILED)
|
||||
.filter(row -> !row.nextAttemptAt.isAfter(now))
|
||||
.sorted(Comparator.comparing((Row row) -> row.nextAttemptAt))
|
||||
.limit(limit)
|
||||
.forEach(
|
||||
row -> {
|
||||
row.status = Status.IN_PROGRESS;
|
||||
row.claimToken = UUID.randomUUID();
|
||||
row.leaseUntil = now.plus(lease);
|
||||
claimed.add(new CleanupItem(row.cleanupId, row.request, row.attempt, row.claimToken));
|
||||
});
|
||||
return List.copyOf(claimed);
|
||||
}
|
||||
|
||||
@Override
|
||||
public int reclaimExpiredClaims(Instant now, int limit) {
|
||||
reclaimSweeps.add(now);
|
||||
int reclaimed = 0;
|
||||
for (Row row : rows.values()) {
|
||||
if (reclaimed >= limit) {
|
||||
break;
|
||||
}
|
||||
if (row.status == Status.IN_PROGRESS && row.leaseUntil.isBefore(now)) {
|
||||
row.settle(Status.FAILED, now);
|
||||
reclaimed++;
|
||||
}
|
||||
}
|
||||
return reclaimed;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void markDone(CleanupItem item) {
|
||||
if (settle(item, Status.DONE, clock.instant())) {
|
||||
done.add(item);
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public void markFailed(CleanupItem item, String reasonCode, Instant nextAttemptAt) {
|
||||
if (settle(item, Status.FAILED, nextAttemptAt)) {
|
||||
failed.put(item, reasonCode);
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public void markAbandoned(CleanupItem item, String reasonCode) {
|
||||
if (settle(item, Status.ABANDONED, clock.instant())) {
|
||||
abandoned.put(item, reasonCode);
|
||||
}
|
||||
}
|
||||
|
||||
private boolean settle(CleanupItem item, Status status, Instant nextAttemptAt) {
|
||||
Row row = rows.get(item.cleanupId());
|
||||
if (row == null || !item.claimToken().equals(row.claimToken)) {
|
||||
return false;
|
||||
}
|
||||
row.settle(status, nextAttemptAt);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** The moments a batch asked for abandoned claims back, in order. */
|
||||
public List<Instant> reclaimSweeps() {
|
||||
return List.copyOf(reclaimSweeps);
|
||||
}
|
||||
|
||||
/** The moments a batch claimed due items, in order. */
|
||||
public List<Instant> claimSweeps() {
|
||||
return List.copyOf(claimSweeps);
|
||||
}
|
||||
|
||||
/** The requests of every item not yet done or abandoned, in enqueue order. */
|
||||
public List<CleanupRequest> queued() {
|
||||
return rows.values().stream()
|
||||
.filter(row -> row.status != Status.DONE && row.status != Status.ABANDONED)
|
||||
.map(row -> row.request)
|
||||
.toList();
|
||||
}
|
||||
|
||||
public List<CleanupItem> done() {
|
||||
return List.copyOf(done);
|
||||
}
|
||||
|
||||
/** Items whose last settlement was a reschedule, with the reason given. */
|
||||
public Map<CleanupItem, String> failed() {
|
||||
return Map.copyOf(failed);
|
||||
}
|
||||
|
||||
/** Items the caller parked for good, with the reason given. */
|
||||
public Map<CleanupItem, String> abandoned() {
|
||||
return Map.copyOf(abandoned);
|
||||
}
|
||||
|
||||
private enum Status {
|
||||
PENDING,
|
||||
IN_PROGRESS,
|
||||
DONE,
|
||||
FAILED,
|
||||
ABANDONED
|
||||
}
|
||||
|
||||
private static final class Row {
|
||||
|
||||
private final UUID cleanupId;
|
||||
private final CleanupRequest request;
|
||||
private Status status = Status.PENDING;
|
||||
private int attempt;
|
||||
private Instant nextAttemptAt;
|
||||
private UUID claimToken;
|
||||
private Instant leaseUntil;
|
||||
|
||||
private Row(UUID cleanupId, CleanupRequest request, Instant nextAttemptAt) {
|
||||
this.cleanupId = cleanupId;
|
||||
this.request = request;
|
||||
this.nextAttemptAt = nextAttemptAt;
|
||||
}
|
||||
|
||||
private void settle(Status status, Instant nextAttemptAt) {
|
||||
this.status = status;
|
||||
this.attempt++;
|
||||
this.nextAttemptAt = nextAttemptAt;
|
||||
this.claimToken = null;
|
||||
this.leaseUntil = null;
|
||||
}
|
||||
}
|
||||
}
|
||||
+7
-1
@@ -23,7 +23,8 @@ import java.util.concurrent.atomic.AtomicInteger;
|
||||
* Hand-rolled metadata store with the same optimistic-transition semantics as the JPA adapter.
|
||||
*
|
||||
* <p>Application tests must observe identical conflict behaviour, so this fake enforces the
|
||||
* expected state and version rather than accepting any write.
|
||||
* expected state and version rather than accepting any write. It is held to {@link
|
||||
* FileMetadataPortContract}, the contract the JPA adapter passes against PostgreSQL.
|
||||
*/
|
||||
public final class InMemoryFileMetadataStore implements FileMetadataPort {
|
||||
|
||||
@@ -42,6 +43,11 @@ public final class InMemoryFileMetadataStore implements FileMetadataPort {
|
||||
|
||||
@Override
|
||||
public FileRecord insert(FileRecordDraft draft) {
|
||||
if (records.containsKey(draft.fileId())) {
|
||||
// The database refuses this on the primary key; a fake that overwrote would let a caller
|
||||
// pass every unit test with an insert that fails in production (FileMetadataPortContract).
|
||||
throw new IllegalStateException("a file record already exists under " + draft.fileId());
|
||||
}
|
||||
FileRecord record =
|
||||
new FileRecord(
|
||||
draft.fileId(),
|
||||
Reference in New Issue
Block a user