review-followup Wave 2: 정합성 수정 통합과 검증, 현황표·재개 프롬프트

13개 작업 묶음(P1–P13)의 W2 커밋을 합치고 전체 게이트로 검증했다.

- 묶음별 정합성 수정(notification dispatch·recovery, object storage staged
  publication, fileserver 복구·정리, gRPC 플랫폼, Redis 분류·lease TTL, JPA
  outbox claim 순서·durable operation HTTP, web 요청 id·category 필수, graphql
  에러 mapper, Mongo profile 바인딩, build 소스 보존 게이트·compose smoke info 확인)
- 통합 때 드러난 3건 수정: outbox claim 테스트 fixture의 가짜 envelope hash,
  sample scan이 새 operation controller를 등록하던 문제, SpotBugs aux classpath
  파일이 truncate되지 않아 로컬에서 ".jar.jar"로 실패하던 문제
- 현황표: 묶음 결과 반영, 소유자 결정 21–27, 후속 발견 결함 47행, 요약 갱신
- docs/capability-status.md 「제거된 코드」에 85행 추가
- 묶음 결과 파일·에이전트 지시·스크립트를 docs로 옮기고 desktop 재개 프롬프트 추가

검증: check, ci verifyDependencyLocks, mainCheck, architecture/public path/env
keys/config contract, bootstrap·sample integration/system, build-logic·build-tools
test, optional-platforms ci, qualificationBootJar 통과. integrationCheck는 이번
작업 전에도 실패하던 lane(Redis topology 모드 인자, httpclient failure
injection, AWS 보호 lane)만 실패.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-28 14:46:30 +09:00
co-authored by Claude Opus 5.5
parent 2c7d1d58f3
commit 2c612cb95b
28 changed files with 763 additions and 134 deletions
@@ -1,6 +1,7 @@
package dev.caskeleton.grpc.api.deadline;
import java.time.Duration;
import java.util.function.LongSupplier;
/**
* How much time a call actually has, after the parent deadline and the method profile have both had
@@ -9,17 +10,40 @@ import java.time.Duration;
* <p>The rule is "shorter of the two, minus the reserve", and it is here rather than at each call
* site because the failure mode of getting it wrong is silent: a downstream timeout longer than the
* inbound deadline never fires, and the caller sees a deadline the server has no idea it missed.
*
* <p>The budget is an absolute deadline on a monotonic nanosecond clock, so {@link #remaining()}
* shrinks and {@link #expired()} turns true as time passes. A request context carries one budget
* for the whole call; a budget that remembered only the duration it started with would hand every
* later dependency call the full original time.
*/
public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile) {
public final class GrpcDeadlineBudget {
/** Rejects a budget with no time in it. */
public GrpcDeadlineBudget {
if (remaining == null || profile == null) {
throw new IllegalArgumentException("a deadline budget needs a remaining time and a profile");
private final long deadlineNanos;
private final GrpcDeadlineProfile profile;
private final LongSupplier nanoClock;
/** A budget of {@code remaining} from now on the system's monotonic clock. */
public GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile) {
this(remaining, profile, System::nanoTime);
}
/**
* A budget of {@code remaining} from now on {@code nanoClock}.
*
* @param nanoClock a monotonic nanosecond source, {@code System::nanoTime} outside tests
*/
public GrpcDeadlineBudget(
Duration remaining, GrpcDeadlineProfile profile, LongSupplier nanoClock) {
if (remaining == null || profile == null || nanoClock == null) {
throw new IllegalArgumentException(
"a deadline budget needs a remaining time, a profile and a clock");
}
if (remaining.isNegative()) {
throw new IllegalArgumentException("remaining time must not be negative; got " + remaining);
}
this.deadlineNanos = nanoClock.getAsLong() + remaining.toNanos();
this.profile = profile;
this.nanoClock = nanoClock;
}
/**
@@ -31,6 +55,12 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile
*/
public static GrpcDeadlineBudget forEntryPoint(
Duration parentRemaining, GrpcDeadlineProfile profile) {
return forEntryPoint(parentRemaining, profile, System::nanoTime);
}
/** {@link #forEntryPoint(Duration, GrpcDeadlineProfile)} on {@code nanoClock}. */
public static GrpcDeadlineBudget forEntryPoint(
Duration parentRemaining, GrpcDeadlineProfile profile, LongSupplier nanoClock) {
if (profile == null) {
throw new IllegalArgumentException("a deadline budget needs a profile");
}
@@ -42,17 +72,13 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile
throw new IllegalArgumentException(
"a Stable unary call requires a positive deadline; got " + parentRemaining);
}
Duration bounded =
parentRemaining.compareTo(profile.total()) <= 0 ? parentRemaining : profile.total();
Duration afterReserve = bounded.minus(profile.safetyMargin());
return new GrpcDeadlineBudget(
afterReserve.isNegative() ? Duration.ZERO : afterReserve, profile);
return new GrpcDeadlineBudget(afterReserve(parentRemaining, profile), profile, nanoClock);
}
/**
* Derives the budget for a downstream dependency call under {@code downstream}.
*
* <p>Takes the shorter of what is left here and what the downstream profile allows, then
* <p>Takes the shorter of what is left here now and what the downstream profile allows, then
* subtracts the downstream reserve. A dependency can never be given more time than its caller
* has.
*/
@@ -60,11 +86,18 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile
if (downstream == null) {
throw new IllegalArgumentException("a downstream budget needs a profile");
}
Duration bounded =
remaining.compareTo(downstream.total()) <= 0 ? remaining : downstream.total();
Duration afterReserve = bounded.minus(downstream.safetyMargin());
return new GrpcDeadlineBudget(
afterReserve.isNegative() ? Duration.ZERO : afterReserve, downstream);
return new GrpcDeadlineBudget(afterReserve(remaining(), downstream), downstream, nanoClock);
}
/** What is left now; zero once the deadline has passed. */
public Duration remaining() {
long left = deadlineNanos - nanoClock.getAsLong();
return left <= 0 ? Duration.ZERO : Duration.ofNanos(left);
}
/** The profile this budget was cut from. */
public GrpcDeadlineProfile profile() {
return profile;
}
/**
@@ -75,11 +108,23 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile
* investigates the wrong system.
*/
public boolean canStartDependencyCall() {
return remaining.compareTo(profile.minimumAttemptBudget()) >= 0 && !remaining.isZero();
Duration left = remaining();
return !left.isZero() && left.compareTo(profile.minimumAttemptBudget()) >= 0;
}
/** Whether any time is left at all. */
public boolean expired() {
return remaining.isZero() || remaining.isNegative();
return remaining().isZero();
}
@Override
public String toString() {
return "GrpcDeadlineBudget[remaining=" + remaining() + ", profile=" + profile + "]";
}
private static Duration afterReserve(Duration available, GrpcDeadlineProfile profile) {
Duration bounded = available.compareTo(profile.total()) <= 0 ? available : profile.total();
Duration afterReserve = bounded.minus(profile.safetyMargin());
return afterReserve.isNegative() ? Duration.ZERO : afterReserve;
}
}
@@ -16,6 +16,13 @@ import dev.caskeleton.grpc.core.GrpcMethodName;
public record GrpcOperationIdentity(
String callerFingerprint, GrpcMethodName method, String idempotencyKeyHash) {
// Column widths of grpc_operation_ledger (V001). An identity that does not fit is refused here,
// not by the database in the middle of a claim.
private static final int MAX_CALLER_FINGERPRINT = 256;
private static final int MAX_METHOD = 256;
private static final int MAX_KEY_HASH = 80;
private static final int MAX_STORAGE_KEY = 512;
/** Requires all three parts, with the key already hashed. */
public GrpcOperationIdentity {
if (callerFingerprint == null || callerFingerprint.isBlank()) {
@@ -30,6 +37,24 @@ public record GrpcOperationIdentity(
throw new IllegalArgumentException(
"the idempotency key is stored hashed; got '" + idempotencyKeyHash + "'");
}
requireAtMost("caller fingerprint", callerFingerprint, MAX_CALLER_FINGERPRINT);
requireAtMost("full method name", method.canonical(), MAX_METHOD);
requireAtMost("idempotency key hash", idempotencyKeyHash, MAX_KEY_HASH);
requireAtMost(
"storage key",
callerFingerprint + "|" + method.canonical() + "|" + idempotencyKeyHash,
MAX_STORAGE_KEY);
}
private static void requireAtMost(String what, String value, int max) {
if (value.length() > max) {
throw new IllegalArgumentException(
what
+ " must be at most "
+ max
+ " characters to fit the ledger; got "
+ value.length());
}
}
/** The stable storage key: the three parts joined, safe to index and safe to log. */
@@ -5,6 +5,7 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.time.Duration;
import java.time.Instant;
import java.util.concurrent.atomic.AtomicLong;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -27,9 +28,11 @@ class GrpcDeadlineBudgetTest {
@DisplayName("the budget takes the shorter of the parent remaining and the method default")
void budgetTakesTheShorterOfParentAndMethodDefault() {
GrpcDeadlineBudget fromShortParent =
GrpcDeadlineBudget.forEntryPoint(Duration.ofMillis(500), TWO_SECONDS);
GrpcDeadlineBudget.forEntryPoint(
Duration.ofMillis(500), TWO_SECONDS, GrpcDeadlineBudgetTest::frozenNanos);
GrpcDeadlineBudget fromLongParent =
GrpcDeadlineBudget.forEntryPoint(Duration.ofSeconds(30), TWO_SECONDS);
GrpcDeadlineBudget.forEntryPoint(
Duration.ofSeconds(30), TWO_SECONDS, GrpcDeadlineBudgetTest::frozenNanos);
assertThat(fromShortParent.remaining())
.isEqualTo(Duration.ofMillis(500).minus(TWO_SECONDS.safetyMargin()));
@@ -44,7 +47,9 @@ class GrpcDeadlineBudgetTest {
new GrpcDeadlineProfile(
Duration.ofSeconds(10), Duration.ofSeconds(1), Duration.ofMillis(100));
GrpcDeadlineBudget budget = GrpcDeadlineBudget.forEntryPoint(Duration.ofSeconds(10), profile);
GrpcDeadlineBudget budget =
GrpcDeadlineBudget.forEntryPoint(
Duration.ofSeconds(10), profile, GrpcDeadlineBudgetTest::frozenNanos);
assertThat(budget.remaining()).isEqualTo(Duration.ofSeconds(9));
assertThat(profile.usable()).isEqualTo(Duration.ofSeconds(9));
@@ -54,7 +59,8 @@ class GrpcDeadlineBudgetTest {
@DisplayName("a downstream call never gets more time than its caller has left")
void downstreamNeverExceedsTheCaller() {
GrpcDeadlineBudget caller =
GrpcDeadlineBudget.forEntryPoint(Duration.ofMillis(400), TWO_SECONDS);
GrpcDeadlineBudget.forEntryPoint(
Duration.ofMillis(400), TWO_SECONDS, GrpcDeadlineBudgetTest::frozenNanos);
GrpcDeadlineProfile generousDownstream =
new GrpcDeadlineProfile(Duration.ofSeconds(30), Duration.ZERO, Duration.ofMillis(10));
@@ -77,6 +83,39 @@ class GrpcDeadlineBudgetTest {
assertThat(new GrpcDeadlineBudget(Duration.ZERO, profile).canStartDependencyCall()).isFalse();
}
@Test
void aBudgetRunsOutAsTimePassesAfterItWasCreated() {
// given
AtomicLong nanos = new AtomicLong();
GrpcDeadlineBudget budget =
new GrpcDeadlineBudget(Duration.ofMillis(300), TWO_SECONDS, nanos::get);
// when
nanos.addAndGet(Duration.ofMillis(300).toNanos());
// then
assertThat(budget)
.extracting(GrpcDeadlineBudget::remaining, GrpcDeadlineBudget::expired)
.containsExactly(Duration.ZERO, true);
}
@Test
void aDownstreamDerivedLaterGetsOnlyWhatIsLeftThen() {
// given
AtomicLong nanos = new AtomicLong();
GrpcDeadlineBudget caller =
new GrpcDeadlineBudget(Duration.ofSeconds(1), TWO_SECONDS, nanos::get);
nanos.addAndGet(Duration.ofMillis(700).toNanos());
// when
GrpcDeadlineBudget downstream =
caller.deriveDownstream(
new GrpcDeadlineProfile(Duration.ofSeconds(30), Duration.ZERO, Duration.ofMillis(10)));
// then
assertThat(downstream.remaining()).isEqualTo(Duration.ofMillis(300));
}
@Test
@DisplayName("a profile whose reserve leaves no usable time is refused")
void profileWithNoUsableTimeIsRefused() {
@@ -121,4 +160,8 @@ class GrpcDeadlineBudgetTest {
.hasMessageContaining("charge-card")
.hasMessageContaining("deadline-exceeded");
}
private static long frozenNanos() {
return 0L;
}
}
@@ -0,0 +1,44 @@
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 dev.caskeleton.grpc.core.GrpcServiceName;
import org.junit.jupiter.api.Test;
class GrpcOperationIdentityTest {
private static final GrpcMethodName CREATE =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/CreateDocument");
private static final String KEY_HASH =
"sha256:aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899";
@Test
void aCallerFingerprintWiderThanItsLedgerColumnIsRefused() {
// when
Throwable failure =
catchThrowable(() -> new GrpcOperationIdentity("c".repeat(257), CREATE, KEY_HASH));
// then
assertThat(failure)
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("caller fingerprint must be at most 256");
}
@Test
void anIdentityWhoseStorageKeyWouldNotFitTheLedgerIsRefused() {
// given
GrpcMethodName longMethod =
new GrpcMethodName(new GrpcServiceName("p.S" + "s".repeat(197)), "M" + "m".repeat(54));
// when
Throwable failure =
catchThrowable(() -> new GrpcOperationIdentity("c".repeat(256), longMethod, KEY_HASH));
// then
assertThat(failure)
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("storage key must be at most 512");
}
}