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 "제거된 코드" 표에 복구 커밋(27022328)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
2702232830
commit
fd80de369d
+12
@@ -40,6 +40,18 @@ public interface GrpcOperationLedger {
|
||||
/** Marks a claim terminally failed. */
|
||||
void markFailed(GrpcOperationIdentity identity, Instant now);
|
||||
|
||||
/**
|
||||
* Re-claims a {@code FAILED_TERMINAL} record for a new attempt of the same request.
|
||||
*
|
||||
* <p>A compare-and-set to {@code IN_PROGRESS}, atomic like {@link #claim}: of two concurrent
|
||||
* re-claims exactly one returns true. A record in any other state, or made for a different
|
||||
* request, is left untouched. A retry that proceeds without winning this leaves its commit with
|
||||
* no owner and runs concurrently with every other retry of the same key.
|
||||
*
|
||||
* @return true when this call now owns the record as a fresh attempt claimed at {@code now}
|
||||
*/
|
||||
boolean reclaimFailed(GrpcOperationIdentity identity, String requestFingerprint, Instant now);
|
||||
|
||||
/**
|
||||
* Releases a claim that will never complete, so the caller may try again.
|
||||
*
|
||||
|
||||
+4
-1
@@ -12,7 +12,10 @@ public enum GrpcOperationLedgerState {
|
||||
IN_PROGRESS(false),
|
||||
/** Committed, with a replayable outcome. */
|
||||
COMMITTED(true),
|
||||
/** Failed in a way that will not succeed on repetition. */
|
||||
/**
|
||||
* The attempt failed and changed nothing. A retry of the same request may reclaim it (one winner)
|
||||
* and run again; see {@code GrpcOperationLedger.reclaimFailed}.
|
||||
*/
|
||||
FAILED_TERMINAL(true);
|
||||
|
||||
private final boolean terminal;
|
||||
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
package dev.caskeleton.grpc.api.ledger;
|
||||
|
||||
class InMemoryOperationLedgerContractTest extends GrpcOperationLedgerContract {
|
||||
|
||||
private final InMemoryOperationLedger ledger = new InMemoryOperationLedger();
|
||||
|
||||
@Override
|
||||
protected GrpcOperationLedger ledger() {
|
||||
return ledger;
|
||||
}
|
||||
}
|
||||
+260
@@ -0,0 +1,260 @@
|
||||
package dev.caskeleton.grpc.api.ledger;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.concurrent.Callable;
|
||||
import java.util.concurrent.CountDownLatch;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.Future;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* The transitions every {@link GrpcOperationLedger} allows and refuses.
|
||||
*
|
||||
* <p>The in-memory fake and the JPA adapter (against real PostgreSQL) both extend this. A fake that
|
||||
* allows a transition the database refuses lets every policy test pass for code that fails in
|
||||
* production — which is how a retry of a {@code FAILED_TERMINAL} row once proceeded unclaimed.
|
||||
*/
|
||||
public abstract class GrpcOperationLedgerContract {
|
||||
|
||||
private static final GrpcOperationIdentity ID =
|
||||
new GrpcOperationIdentity(
|
||||
"tenant-1.actor-1",
|
||||
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/CreateDocument"),
|
||||
"sha256:aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899");
|
||||
private static final String FINGERPRINT =
|
||||
"sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0";
|
||||
private static final String OTHER_FINGERPRINT =
|
||||
"sha256:1122334455667788990011223344556677889900112233445566778899001122";
|
||||
private static final String OUTCOME = "outcome://document/42";
|
||||
private static final Instant NOW = Instant.parse("2026-09-25T10:00:00Z");
|
||||
|
||||
/** The ledger under test, holding no records when a test starts. */
|
||||
protected abstract GrpcOperationLedger ledger();
|
||||
|
||||
@Test
|
||||
void theFirstClaimOfAnOperationIsOwnedByItsCaller() {
|
||||
assertThat(ledger().claim(ID, FINGERPRINT, NOW)).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aSecondClaimReadsTheFirstClaimInProgress() {
|
||||
// given
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
|
||||
// when
|
||||
Optional<GrpcOperationLedgerRecord> second =
|
||||
ledger().claim(ID, OTHER_FINGERPRINT, NOW.plusSeconds(1));
|
||||
|
||||
// then
|
||||
assertThat(second)
|
||||
.get()
|
||||
.extracting(
|
||||
GrpcOperationLedgerRecord::state,
|
||||
GrpcOperationLedgerRecord::requestFingerprint,
|
||||
GrpcOperationLedgerRecord::claimedAt)
|
||||
.containsExactly(GrpcOperationLedgerState.IN_PROGRESS, FINGERPRINT, NOW);
|
||||
}
|
||||
|
||||
@Test
|
||||
void concurrentClaimsHaveExactlyOneOwner() throws Exception {
|
||||
// when
|
||||
List<Boolean> owned = concurrently(() -> ledger().claim(ID, FINGERPRINT, NOW).isEmpty());
|
||||
|
||||
// then
|
||||
assertThat(owned).containsExactlyInAnyOrder(true, false);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aCommittedClaimKeepsTheOutcomeARetryReplays() {
|
||||
// given
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
|
||||
// when
|
||||
ledger().markCommitted(ID, OUTCOME, NOW.plusSeconds(1));
|
||||
|
||||
// then
|
||||
assertThat(ledger().find(ID))
|
||||
.get()
|
||||
.extracting(
|
||||
GrpcOperationLedgerRecord::state,
|
||||
GrpcOperationLedgerRecord::outcomeReference,
|
||||
GrpcOperationLedgerRecord::completedAt)
|
||||
.containsExactly(
|
||||
GrpcOperationLedgerState.COMMITTED,
|
||||
Optional.of(OUTCOME),
|
||||
Optional.of(NOW.plusSeconds(1)));
|
||||
}
|
||||
|
||||
@Test
|
||||
void committingWithoutAClaimIsRefused() {
|
||||
// when
|
||||
Throwable refused = catchThrowable(() -> ledger().markCommitted(ID, OUTCOME, NOW));
|
||||
|
||||
// then
|
||||
assertThat(refused)
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("no claim exists");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aCommittedClaimCannotBeCommittedAgain() {
|
||||
// given
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
ledger().markCommitted(ID, OUTCOME, NOW.plusSeconds(1));
|
||||
|
||||
// when
|
||||
Throwable refused =
|
||||
catchThrowable(
|
||||
() -> ledger().markCommitted(ID, "outcome://document/99", NOW.plusSeconds(2)));
|
||||
|
||||
// then
|
||||
assertThat(refused)
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("cannot transition again");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aFailedClaimIsTerminal() {
|
||||
// given
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
|
||||
// when
|
||||
ledger().markFailed(ID, NOW.plusSeconds(1));
|
||||
|
||||
// then
|
||||
assertThat(ledger().find(ID))
|
||||
.get()
|
||||
.extracting(GrpcOperationLedgerRecord::state, GrpcOperationLedgerRecord::completedAt)
|
||||
.containsExactly(GrpcOperationLedgerState.FAILED_TERMINAL, Optional.of(NOW.plusSeconds(1)));
|
||||
}
|
||||
|
||||
@Test
|
||||
void aFailedClaimCannotBeCommittedWithoutBeingReclaimed() {
|
||||
// given
|
||||
failedClaim();
|
||||
|
||||
// when
|
||||
Throwable refused =
|
||||
catchThrowable(() -> ledger().markCommitted(ID, OUTCOME, NOW.plusSeconds(2)));
|
||||
|
||||
// then
|
||||
assertThat(refused)
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("cannot transition again");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aFailedClaimIsReclaimedByARetryOfTheSameRequest() {
|
||||
// given
|
||||
failedClaim();
|
||||
|
||||
// when
|
||||
boolean reclaimed = ledger().reclaimFailed(ID, FINGERPRINT, NOW.plusSeconds(2));
|
||||
|
||||
// then
|
||||
assertThat(reclaimed).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aReclaimedClaimIsANewAttemptInProgressSinceTheReclaim() {
|
||||
// given
|
||||
failedClaim();
|
||||
|
||||
// when
|
||||
ledger().reclaimFailed(ID, FINGERPRINT, NOW.plusSeconds(2));
|
||||
|
||||
// then
|
||||
assertThat(ledger().find(ID))
|
||||
.get()
|
||||
.extracting(
|
||||
GrpcOperationLedgerRecord::state,
|
||||
GrpcOperationLedgerRecord::claimedAt,
|
||||
GrpcOperationLedgerRecord::completedAt)
|
||||
.containsExactly(
|
||||
GrpcOperationLedgerState.IN_PROGRESS, NOW.plusSeconds(2), Optional.empty());
|
||||
}
|
||||
|
||||
@Test
|
||||
void aReclaimedClaimCanBeCommitted() {
|
||||
// given
|
||||
failedClaim();
|
||||
ledger().reclaimFailed(ID, FINGERPRINT, NOW.plusSeconds(2));
|
||||
|
||||
// when
|
||||
ledger().markCommitted(ID, OUTCOME, NOW.plusSeconds(3));
|
||||
|
||||
// then
|
||||
assertThat(ledger().find(ID))
|
||||
.get()
|
||||
.extracting(GrpcOperationLedgerRecord::state, GrpcOperationLedgerRecord::outcomeReference)
|
||||
.containsExactly(GrpcOperationLedgerState.COMMITTED, Optional.of(OUTCOME));
|
||||
}
|
||||
|
||||
@Test
|
||||
void aFailedClaimIsNotReclaimedForADifferentRequest() {
|
||||
failedClaim();
|
||||
|
||||
assertThat(ledger().reclaimFailed(ID, OTHER_FINGERPRINT, NOW.plusSeconds(2))).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
void anInProgressClaimIsNotReclaimed() {
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
|
||||
assertThat(ledger().reclaimFailed(ID, FINGERPRINT, NOW.plusSeconds(1))).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aCommittedClaimIsNotReclaimed() {
|
||||
// given
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
ledger().markCommitted(ID, OUTCOME, NOW.plusSeconds(1));
|
||||
|
||||
// when
|
||||
boolean reclaimed = ledger().reclaimFailed(ID, FINGERPRINT, NOW.plusSeconds(2));
|
||||
|
||||
// then
|
||||
assertThat(reclaimed).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
void concurrentReclaimsOfAFailedClaimHaveExactlyOneWinner() throws Exception {
|
||||
// given
|
||||
failedClaim();
|
||||
|
||||
// when
|
||||
List<Boolean> reclaimed =
|
||||
concurrently(() -> ledger().reclaimFailed(ID, FINGERPRINT, NOW.plusSeconds(2)));
|
||||
|
||||
// then
|
||||
assertThat(reclaimed).containsExactlyInAnyOrder(true, false);
|
||||
}
|
||||
|
||||
private void failedClaim() {
|
||||
ledger().claim(ID, FINGERPRINT, NOW);
|
||||
ledger().markFailed(ID, NOW.plusSeconds(1));
|
||||
}
|
||||
|
||||
/** Runs {@code attempt} on two threads released together and returns both results. */
|
||||
private static List<Boolean> concurrently(Callable<Boolean> attempt) throws Exception {
|
||||
CountDownLatch start = new CountDownLatch(1);
|
||||
Callable<Boolean> gated =
|
||||
() -> {
|
||||
start.await();
|
||||
return attempt.call();
|
||||
};
|
||||
try (ExecutorService executor = Executors.newFixedThreadPool(2)) {
|
||||
Future<Boolean> first = executor.submit(gated);
|
||||
Future<Boolean> second = executor.submit(gated);
|
||||
start.countDown();
|
||||
return List.of(first.get(), second.get());
|
||||
}
|
||||
}
|
||||
}
|
||||
+111
@@ -0,0 +1,111 @@
|
||||
package dev.caskeleton.grpc.api.ledger;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Optional;
|
||||
import java.util.concurrent.ConcurrentHashMap;
|
||||
import java.util.concurrent.ConcurrentMap;
|
||||
|
||||
/**
|
||||
* A hand-rolled ledger for tests of code that depends on {@link GrpcOperationLedger}.
|
||||
*
|
||||
* <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 and re-claim 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 {
|
||||
|
||||
private final ConcurrentMap<String, GrpcOperationLedgerRecord> records =
|
||||
new ConcurrentHashMap<>();
|
||||
private volatile boolean unavailable;
|
||||
|
||||
/** Makes every read fail, so the UNKNOWN path can be exercised. */
|
||||
public void makeUnavailable() {
|
||||
unavailable = true;
|
||||
}
|
||||
|
||||
@Override
|
||||
public Optional<GrpcOperationLedgerRecord> claim(
|
||||
GrpcOperationIdentity identity, String requestFingerprint, Instant now) {
|
||||
GrpcOperationLedgerRecord existing =
|
||||
records.putIfAbsent(
|
||||
identity.storageKey(),
|
||||
GrpcOperationLedgerRecord.claim(identity, requestFingerprint, now));
|
||||
return Optional.ofNullable(existing);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Optional<GrpcOperationLedgerRecord> find(GrpcOperationIdentity identity) {
|
||||
if (unavailable) {
|
||||
throw new IllegalStateException("ledger unavailable");
|
||||
}
|
||||
return Optional.ofNullable(records.get(identity.storageKey()));
|
||||
}
|
||||
|
||||
@Override
|
||||
public void markCommitted(GrpcOperationIdentity identity, String outcomeReference, Instant now) {
|
||||
GrpcOperationLedgerRecord committed =
|
||||
records.computeIfPresent(
|
||||
identity.storageKey(),
|
||||
(key, existing) ->
|
||||
finish(
|
||||
existing,
|
||||
GrpcOperationLedgerState.COMMITTED,
|
||||
Optional.of(outcomeReference),
|
||||
now));
|
||||
if (committed == null) {
|
||||
throw new IllegalStateException(
|
||||
"cannot commit operation '" + identity.storageKey() + "': no claim exists");
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public void markFailed(GrpcOperationIdentity identity, Instant now) {
|
||||
records.computeIfPresent(
|
||||
identity.storageKey(),
|
||||
(key, existing) ->
|
||||
finish(existing, GrpcOperationLedgerState.FAILED_TERMINAL, Optional.empty(), now));
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean reclaimFailed(
|
||||
GrpcOperationIdentity identity, String requestFingerprint, Instant now) {
|
||||
GrpcOperationLedgerRecord current = records.get(identity.storageKey());
|
||||
return current != null
|
||||
&& current.state() == GrpcOperationLedgerState.FAILED_TERMINAL
|
||||
&& current.sameRequestAs(requestFingerprint)
|
||||
&& records.replace(
|
||||
identity.storageKey(),
|
||||
current,
|
||||
GrpcOperationLedgerRecord.claim(identity, requestFingerprint, now));
|
||||
}
|
||||
|
||||
@Override
|
||||
public void release(GrpcOperationIdentity identity) {
|
||||
records.remove(identity.storageKey());
|
||||
}
|
||||
|
||||
// Only an IN_PROGRESS claim finishes; a terminal row is re-opened by reclaimFailed alone.
|
||||
private static GrpcOperationLedgerRecord finish(
|
||||
GrpcOperationLedgerRecord existing,
|
||||
GrpcOperationLedgerState state,
|
||||
Optional<String> outcomeReference,
|
||||
Instant now) {
|
||||
if (existing.state() != GrpcOperationLedgerState.IN_PROGRESS) {
|
||||
throw new IllegalStateException(
|
||||
"operation '"
|
||||
+ existing.identity().storageKey()
|
||||
+ "' is already "
|
||||
+ existing.state()
|
||||
+ " and cannot transition again");
|
||||
}
|
||||
return new GrpcOperationLedgerRecord(
|
||||
existing.identity(),
|
||||
state,
|
||||
existing.requestFingerprint(),
|
||||
outcomeReference,
|
||||
existing.claimedAt(),
|
||||
Optional.of(now));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user