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:
DongHyeonka
2026-09-25 12:49:07 +09:00
co-authored by Claude Opus 5.5
parent 2702232830
commit fd80de369d
18 changed files with 747 additions and 112 deletions
@@ -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.
*
@@ -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;
@@ -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;
}
}
@@ -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());
}
}
}
@@ -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));
}
}