refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링

This commit is contained in:
donghyeon-ka
2026-09-23 17:27:09 +09:00
parent 04b71a9139
commit f578ab859a
109 changed files with 1234 additions and 389 deletions
+11
View File
@@ -1,8 +1,18 @@
plugins {
id 'ca.architecture'
}
ext.sourceRevision = providers.gradleProperty('gitRevision')
.orElse(providers.environmentVariable('GIT_SHA'))
.orElse(providers.environmentVariable('GITHUB_SHA'))
.getOrElse('unknown')
tasks.register('resolveAndLockAll') {
group = 'build setup'
description = 'Regenerates dependency locks for every optional gRPC leaf (requires --write-locks).'
dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:resolveAndLockAll" }
}
tasks.register('checkAll') {
group = 'verification'
description = 'Runs every gRPC optional-platform leaf check.'
@@ -20,4 +30,5 @@ tasks.register('ci') {
description = 'Runs the optional gRPC platform verification surface.'
dependsOn tasks.named('checkAll')
dependsOn tasks.named('qualityCheck')
dependsOn tasks.named('verifyCleanArchitectureDependencies')
}
@@ -91,7 +91,7 @@ leaf 경계가 아니라 capability별 독립 promotion evidence로 표현되므
| D5 | Buf CLI (`bufLint`/`bufBreaking` 등) | 저장소 소유 규칙 엔진 + Gradle verify task | Buf CLI 바이너리가 이 환경에 없다. lint/format/breaking **규칙**을 Java로 구현해 동일 판정을 내리고, CLI는 동일 규칙을 재확인하는 선택 경로로 남긴다 |
| D6 | protoc/grpc-java codegen을 빌드에서 실행 | `.proto` 소스 + codegen **정책·descriptor 계약**만 실행, protoc 실행은 명시적 확장점 | 아래 별도 절 |
| D7 | `grpc-kotlin`의 `.kt` 소스 | Java 쪽 coroutine/Flow **경계 계약**만 | 저장소에 Kotlin 플러그인·소스셋이 없다. A16의 5개 요구사항 중 4개(스키마 단일 소스, cancellation 전파 계약, backpressure 우회 금지, evidence 타입 보존)는 Java 계약으로 표현 가능하고, Kotlin 툴체인 lane은 `GrpcKotlinCompatibilityGate`가 미충족으로 fail-closed 판정한다 |
| D8 | 새 leaf가 곧 런타임 | 신규 leaf 전부 `runtime_memberships: []` (build-only) | `messaging:*`가 처음 착지한 방식과 동일. 런타임 투입은 registry membership 변경 + `verifyRuntimeModuleMembership` 통과가 선행 조건이며, 그것은 별도 결정이다 |
| D8 | 새 leaf가 곧 런타임 | 신규 leaf 전부 `build: "optional-grpc"` (main runtime composition은 별도 Gradle edge로 결정) (build-only) | `messaging:*`가 처음 착지한 방식과 동일. 런타임 투입은 registry membership 변경 + `verifyRuntimeModuleMembership` 통과가 선행 조건이며, 그것은 별도 결정이다 |
### D6 — protoc 실행을 지금 켜지 않는 이유
@@ -1,6 +1,6 @@
package dev.caskeleton.grpc.advanced.integration;
import dev.caskeleton.grpc.context.GrpcMetadataKey;
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Set;
@@ -1,6 +1,6 @@
package dev.caskeleton.grpc.advanced.integration;
import dev.caskeleton.grpc.context.GrpcRequestContext;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import java.util.Map;
import org.springframework.messaging.Message;
import org.springframework.messaging.support.MessageBuilder;
@@ -1,6 +1,6 @@
package dev.caskeleton.grpc.advanced.integration;
import dev.caskeleton.grpc.context.GrpcMetadataKey;
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
import java.util.Map;
import org.springframework.messaging.Message;
@@ -1,7 +1,7 @@
package dev.caskeleton.grpc.advanced.reactor;
import dev.caskeleton.grpc.context.GrpcContextSnapshot;
import dev.caskeleton.grpc.context.GrpcRequestContext;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import java.util.function.BiFunction;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Scheduler;
@@ -6,15 +6,15 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.advanced.integration.GrpcIntegrationBridgePolicy;
import dev.caskeleton.grpc.advanced.integration.GrpcIntegrationInboundGateway;
import dev.caskeleton.grpc.advanced.integration.GrpcIntegrationOutboundGateway;
import dev.caskeleton.grpc.context.GrpcClientIdentity;
import dev.caskeleton.grpc.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.context.GrpcMetadataKey;
import dev.caskeleton.grpc.context.GrpcRequestContext;
import dev.caskeleton.grpc.api.context.GrpcClientIdentity;
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import java.time.Duration;
import java.util.Map;
import java.util.Set;
@@ -8,7 +8,7 @@ import dev.caskeleton.grpc.advanced.kotlin.GrpcKotlinCompatibilityGate;
import dev.caskeleton.grpc.advanced.kotlin.GrpcKotlinProfile;
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import java.time.Instant;
import java.util.concurrent.atomic.AtomicBoolean;
import org.junit.jupiter.api.DisplayName;
@@ -5,17 +5,17 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.advanced.reactor.GrpcReactorCancellationBridge;
import dev.caskeleton.grpc.advanced.reactor.GrpcReactorContextBridge;
import dev.caskeleton.grpc.context.GrpcClientIdentity;
import dev.caskeleton.grpc.api.context.GrpcClientIdentity;
import dev.caskeleton.grpc.context.GrpcContextSnapshot;
import dev.caskeleton.grpc.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.context.GrpcRequestContext;
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import java.time.Duration;
import java.time.Instant;
import java.util.Map;
@@ -1,5 +1,9 @@
package dev.caskeleton.grpc.advanced.diagnostics;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.regex.Pattern;
@@ -43,9 +47,22 @@ public final class GrpcDiagnosticsRedactor {
if (address == null || address.isBlank()) {
return "unknown";
}
return IPV4_WITH_PORT
.matcher(address)
.replaceAll(matchResult -> matchResult.group(1) + "." + matchResult.group(2) + ".x.x");
var matcher = IPV4_WITH_PORT.matcher(address);
if (matcher.find()) {
return matcher.replaceAll(
matchResult -> matchResult.group(1) + "." + matchResult.group(2) + ".x.x");
}
return "masked:" + stableAddressToken(address);
}
private static String stableAddressToken(String address) {
try {
byte[] digest =
MessageDigest.getInstance("SHA-256").digest(address.getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(digest, 0, 8);
} catch (NoSuchAlgorithmException impossible) {
throw new IllegalStateException("SHA-256 is required by the Java runtime", impossible);
}
}
/**
@@ -72,6 +72,12 @@ class GrpcChannelDiagnosticsPolicyTest {
void addressesAreMaskedRatherThanDropped() {
assertThat(GrpcDiagnosticsRedactor.maskAddress("10.4.13.201:9090")).isEqualTo("10.4.x.x");
assertThat(GrpcDiagnosticsRedactor.maskAddress("10.9.13.201")).isEqualTo("10.9.x.x");
String ipv6 = GrpcDiagnosticsRedactor.maskAddress("[2001:db8::10]:9090");
String hostname = GrpcDiagnosticsRedactor.maskAddress("payments.internal.example:443");
assertThat(ipv6).startsWith("masked:").doesNotContain("2001", "db8");
assertThat(hostname).startsWith("masked:").doesNotContain("payments", "internal.example");
assertThat(ipv6).isNotEqualTo(hostname);
assertThat(GrpcDiagnosticsRedactor.maskAddress(null)).isEqualTo("unknown");
Map<String, String> redacted =
@@ -1,8 +1,8 @@
package dev.caskeleton.grpc.advanced.resilience;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
import java.util.Optional;
@@ -45,7 +45,7 @@ public final class GrpcHedgingEligibility {
+ "because the second attempt duplicates a success in progress rather than retrying a "
+ "failure");
}
if (!retryOwner.hedgingAllowed()) {
if (!retryOwner.permitsHedging()) {
return Optional.of(
"retry owner is " + retryOwner + ", which does not permit in-process hedging");
}
@@ -5,10 +5,10 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
import java.time.Duration;
import org.junit.jupiter.api.DisplayName;
+21 -5
View File
@@ -98,11 +98,11 @@ focused test는 registry의 `gradle_path`에서 파생한다.
```bash
cd src
./gradlew :grpc:<leaf>:test --console=plain
./gradlew :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
./gradlew :grpc:grpc-testkit:grpcNettyContractTest --console=plain
./gradlew :grpc:grpc-testkit:grpcFaultTest --console=plain
./gradlew :grpc:grpc-testkit:grpcPerformanceTest --console=plain
./gradlew -p optional-platforms :grpc:<leaf>:test --console=plain
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcNettyContractTest --console=plain
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcFaultTest --console=plain
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcPerformanceTest --console=plain
```
## 금지
@@ -113,3 +113,19 @@ cd src
- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다).
- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것
(`GrpcMetricCardinalityPolicy`가 거부한다).
### Adoption-time observability gate
The metric names implemented by `grpc-observability` are **not registered in
`docs/registries/metrics.yaml` yet** because this optional family is not a shipped runtime capability.
Do not present those names as repository-certified metrics until adoption adds registry entries with
the repository's `.seconds` / `.total` unit naming and the corresponding validation gate.
### Durable operation ledger adoption
`grpc-spring-boot-starter` does not pull the JPA ledger adapter transitively. A deployment that needs
durable operation idempotency adds `:grpc:grpc-operation-ledger-jpa` explicitly, enables the ledger
configuration, and includes that adapter's Flyway location `db/migration/grpc`. A deployment that
does not adopt the ledger therefore pays no Spring Data JPA classpath cost.
@@ -1,8 +1,8 @@
package dev.caskeleton.grpc.client;
import dev.caskeleton.grpc.context.GrpcMetadataKey;
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
@@ -1,7 +1,7 @@
package dev.caskeleton.grpc.client;
import dev.caskeleton.grpc.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.context.GrpcMetadataKey;
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Set;
@@ -1,10 +1,10 @@
package dev.caskeleton.grpc.client;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineCalculator;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.resilience.GrpcWaitForReadyDecision;
import dev.caskeleton.grpc.resilience.GrpcWaitForReadyProfile;
import dev.caskeleton.grpc.resilience.GrpcWaitForReadyValidator;
@@ -3,12 +3,12 @@ package dev.caskeleton.grpc.client;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.context.GrpcMetadataKey;
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
import dev.caskeleton.grpc.core.GrpcChannelProfileName;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import java.time.Duration;
import java.time.Instant;
import java.util.LinkedHashMap;
@@ -5,9 +5,9 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcChannelProfileName;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.resilience.GrpcWaitForReadyProfile;
import java.time.Duration;
import java.time.Instant;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.context;
package dev.caskeleton.grpc.api.context;
/**
* Who is calling, as established by authentication — never as claimed by a header.
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.context;
package dev.caskeleton.grpc.api.context;
import java.util.Map;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.context;
package dev.caskeleton.grpc.api.context;
import java.util.regex.Pattern;
@@ -1,9 +1,9 @@
package dev.caskeleton.grpc.context;
package dev.caskeleton.grpc.api.context;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Optional;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.deadline;
package dev.caskeleton.grpc.api.deadline;
import java.time.Instant;
import java.util.Optional;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.deadline;
package dev.caskeleton.grpc.api.deadline;
import java.time.Duration;
@@ -1,7 +1,7 @@
package dev.caskeleton.grpc.deadline;
package dev.caskeleton.grpc.api.deadline;
import dev.caskeleton.grpc.error.GrpcFailureContext;
import dev.caskeleton.grpc.error.GrpcPlatformException;
import dev.caskeleton.grpc.api.error.GrpcFailureContext;
import dev.caskeleton.grpc.api.error.GrpcPlatformException;
/**
* A deadline elapsed.
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.deadline;
package dev.caskeleton.grpc.api.deadline;
import java.time.Duration;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.error;
package dev.caskeleton.grpc.api.error;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.evidence.GrpcBusinessEvidence;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.error;
package dev.caskeleton.grpc.api.error;
import dev.caskeleton.grpc.core.GrpcStatusCode;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.error;
package dev.caskeleton.grpc.api.error;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.GrpcStatusCode;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.error;
package dev.caskeleton.grpc.api.error;
/**
* The platform's failure carrier.
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.ledger;
package dev.caskeleton.grpc.api.ledger;
import dev.caskeleton.grpc.core.GrpcMethodName;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.ledger;
package dev.caskeleton.grpc.api.ledger;
import java.time.Instant;
import java.util.Optional;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.ledger;
package dev.caskeleton.grpc.api.ledger;
import java.time.Instant;
import java.util.Optional;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.ledger;
package dev.caskeleton.grpc.api.ledger;
/**
* Where a durable operation claim is in its life.
@@ -1,8 +1,8 @@
package dev.caskeleton.grpc.policy;
package dev.caskeleton.grpc.api.policy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
/**
* Everything the platform decides per method, in one immutable value.
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.policy;
package dev.caskeleton.grpc.api.policy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import java.util.LinkedHashMap;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.policy;
package dev.caskeleton.grpc.api.policy;
/**
* How safe a method is to run more than once — the property every retry decision starts from.
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.policy;
package dev.caskeleton.grpc.api.policy;
/**
* Whether a call queues while the channel is disconnected, instead of failing fast.
@@ -1,13 +1,13 @@
package dev.caskeleton.grpc.context;
package dev.caskeleton.grpc.api.context;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.deadline;
package dev.caskeleton.grpc.api.deadline;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -1,4 +1,4 @@
package dev.caskeleton.grpc.error;
package dev.caskeleton.grpc.api.error;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -1,11 +1,11 @@
package dev.caskeleton.grpc.policy;
package dev.caskeleton.grpc.api.policy;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import java.time.Duration;
import java.util.Set;
import org.junit.jupiter.api.DisplayName;
@@ -3,7 +3,10 @@ package dev.caskeleton.grpc.core;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Set;
import java.util.regex.Pattern;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -20,6 +23,33 @@ class GrpcStableModuleCatalogTest {
assertThat(GrpcStableBuildInvariant.advancedDependencyAllowed()).isFalse();
}
@Test
@DisplayName("the optional gRPC registry is exactly classified as Stable or Advanced")
void registryAndCatalogStayTogether() throws Exception {
Path candidate = Path.of("").toAbsolutePath();
while (candidate != null
&& !Files.isRegularFile(candidate.resolve("src/config/architecture/modules.json"))) {
candidate = candidate.getParent();
}
assertThat(candidate).as("repository root").isNotNull();
String registry = Files.readString(candidate.resolve("src/config/architecture/modules.json"));
Pattern entry =
Pattern.compile(
"\\{[^{}]*\"id\"\\s*:\\s*\"(grpc-[^\"]+)\"[^{}]*"
+ "\"build\"\\s*:\\s*\"optional-grpc\"[^{}]*\\}",
Pattern.DOTALL);
Set<String> registered =
entry
.matcher(registry)
.results()
.map(result -> result.group(1))
.collect(java.util.stream.Collectors.toUnmodifiableSet());
Set<String> classified = new java.util.HashSet<>(GrpcStableModuleCatalog.standard().modules());
classified.addAll(GrpcStableModuleCatalog.advancedModules());
assertThat(registered).isNotEmpty().containsExactlyInAnyOrderElementsOf(classified);
}
@Test
@DisplayName("the Stable and Advanced sets are disjoint")
void stableAndAdvancedAreDisjoint() {
@@ -3,7 +3,7 @@ package dev.caskeleton.grpc.observability;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.error.GrpcCompletionOutcome;
import dev.caskeleton.grpc.api.error.GrpcCompletionOutcome;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
@@ -6,7 +6,7 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.error.GrpcCompletionOutcome;
import dev.caskeleton.grpc.api.error.GrpcCompletionOutcome;
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
import java.time.Duration;
import java.util.LinkedHashMap;
+21 -3
View File
@@ -1,14 +1,20 @@
plugins {
id 'ca.auxiliary-source-set'
id 'ca.platform-module'
}
auxiliarySourceSets {
sourceSet('integrationTest') {
compilesAgainst 'main'
}
}
// Durable mutation idempotency: the operation ledger entity, its state machine, the vendor-neutral
// repository port and the Spring Data JPA binding, plus the migration that owns the unique
// constraint the whole contract rests on.
//
// The port is what the policy layer consumes; the Spring Data interface is the adapter. Tests here
// run against a hand-rolled in-memory port implementation — a real datastore is only justified when
// vendor semantics are the thing under test, and the constraint is asserted by the migration.
// The claim algorithm is PostgreSQL-specific by design (INSERT ... ON CONFLICT DO NOTHING), so its
// atomicity is certified against a real PostgreSQL instead of a hand-written repository fake.
dependencies {
api project(':grpc:grpc-core-api')
@@ -16,4 +22,16 @@ dependencies {
// Data type, so both vendor APIs appear in this module's public signatures.
api 'jakarta.persistence:jakarta.persistence-api'
api 'org.springframework.data:spring-data-jpa'
integrationTestImplementation 'org.testcontainers:testcontainers-postgresql'
integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter'
integrationTestImplementation 'org.postgresql:postgresql'
}
strictTestLanes {
lane('integrationTest') {
integration()
sourceSet = 'integrationTest'
description = 'Certifies atomic gRPC idempotency claims against real PostgreSQL.'
}
}
+67 -50
View File
@@ -1,49 +1,57 @@
# 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.fasterxml.jackson.core:jackson-annotations:2.21=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
com.github.docker-java:docker-java-api:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.docker-java:docker-java-transport-zerodep:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.docker-java:docker-java-transport:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
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,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
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,integrationTestAnnotationProcessor,testAnnotationProcessor
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,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
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,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
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-codec:commons-codec:1.19.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
commons-io:commons-io:2.21.0=spotbugs
commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
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
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.annotation:jakarta.annotation-api:3.0.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.persistence:jakarta.persistence-api:3.2.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
io.micrometer:micrometer-commons:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.annotation:jakarta.annotation-api:3.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.persistence:jakarta.persistence-api:3.2.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle,compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.antlr:antlr4-runtime:4.13.2=checkstyle,compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-compress:1.28.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.apache.commons:commons-lang3:3.20.0=checkstyle,integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
@@ -55,45 +63,54 @@ 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=integrationTestCompileClasspath,testCompileClasspath
org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.checkerframework:checker-qual:3.55.1=integrationTestRuntimeClasspath
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,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,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-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.jetbrains:annotations:17.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,integrationTestAnnotationProcessor,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath
org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,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=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,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,integrationTestAnnotationProcessor,testAnnotationProcessor
org.postgresql:postgresql:42.7.13=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=compileClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath
org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.slf4j:slf4j-api:2.0.18=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.springframework.data:spring-data-commons:4.0.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.data:spring-data-jpa:4.0.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-beans:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-context:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-core:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-jdbc:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-orm:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.data:spring-data-commons:4.0.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.data:spring-data-jpa:4.0.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-beans:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-context:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-core:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-jdbc:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-orm:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.testcontainers:testcontainers-database-commons:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers-jdbc:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers-postgresql:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
@@ -0,0 +1,159 @@
package dev.caskeleton.grpc.ledger;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.postgresql.ds.PGSimpleDataSource;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;
/** Certifies the native idempotency claim against the PostgreSQL semantics it depends on. */
@Testcontainers(disabledWithoutDocker = true)
class GrpcOperationLedgerPostgresIT {
private static final String STORAGE_KEY = "caller|svc/Create|sha256:key";
private static final String CALLER = "tenant-1.actor-1";
private static final String METHOD = "svc/Create";
private static final String KEY_HASH =
"sha256:aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899";
private static final String FINGERPRINT =
"sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0";
private static final String OTHER_FINGERPRINT =
"sha256:1122334455667788990011223344556677889900112233445566778899001122";
private static final Instant NOW = Instant.parse("2026-09-19T00:00:00Z");
@SuppressWarnings("resource")
@Container
private static final PostgreSQLContainer POSTGRES =
new PostgreSQLContainer("postgres:16-alpine")
.withDatabaseName("grpc")
.withUsername("grpc")
.withPassword("grpc");
private PGSimpleDataSource dataSource;
@BeforeEach
void migrate() throws SQLException, IOException {
dataSource = new PGSimpleDataSource();
dataSource.setUrl(POSTGRES.getJdbcUrl());
dataSource.setUser(POSTGRES.getUsername());
dataSource.setPassword(POSTGRES.getPassword());
try (Connection connection = dataSource.getConnection();
Statement statement = connection.createStatement()) {
statement.execute("DROP TABLE IF EXISTS grpc_operation_ledger");
statement.execute(migration());
}
}
@Test
void concurrentClaimsHaveExactlyOneWinner() throws Exception {
CountDownLatch start = new CountDownLatch(1);
try (var executor = Executors.newFixedThreadPool(2)) {
Future<Integer> first =
executor.submit(
() -> {
start.await();
return claim(FINGERPRINT);
});
Future<Integer> second =
executor.submit(
() -> {
start.await();
return claim(FINGERPRINT);
});
start.countDown();
assertThat(List.of(first.get(), second.get())).containsExactlyInAnyOrder(1, 0);
}
}
@Test
void retryingACommittedClaimDoesNotOverwriteItsOutcome() throws SQLException {
assertThat(claim(FINGERPRINT)).isEqualTo(1);
try (Connection connection = dataSource.getConnection();
PreparedStatement update =
connection.prepareStatement(
"""
UPDATE grpc_operation_ledger
SET state = 'COMMITTED', outcome_reference = ?, completed_at = ?
WHERE storage_key = ?
""")) {
update.setString(1, "outcome://document/42");
update.setObject(2, NOW.plusSeconds(1).atOffset(ZoneOffset.UTC));
update.setString(3, STORAGE_KEY);
assertThat(update.executeUpdate()).isEqualTo(1);
}
assertThat(claim(OTHER_FINGERPRINT)).isZero();
try (Connection connection = dataSource.getConnection();
PreparedStatement select =
connection.prepareStatement(
"""
SELECT state, outcome_reference, request_fingerprint
FROM grpc_operation_ledger
WHERE storage_key = ?
""")) {
select.setString(1, STORAGE_KEY);
try (ResultSet row = select.executeQuery()) {
assertThat(row.next()).isTrue();
assertThat(row.getString("state")).isEqualTo("COMMITTED");
assertThat(row.getString("outcome_reference")).isEqualTo("outcome://document/42");
assertThat(row.getString("request_fingerprint")).isEqualTo(FINGERPRINT);
}
}
}
private int claim(String requestFingerprint) throws SQLException {
try (Connection connection = dataSource.getConnection();
PreparedStatement insert = connection.prepareStatement(jdbcClaimSql())) {
insert.setString(1, STORAGE_KEY);
insert.setString(2, CALLER);
insert.setString(3, METHOD);
insert.setString(4, KEY_HASH);
insert.setString(5, requestFingerprint);
insert.setObject(6, NOW.atOffset(ZoneOffset.UTC));
return insert.executeUpdate();
}
}
private static String jdbcClaimSql() {
return GrpcOperationLedgerRepository.ATOMIC_CLAIM_SQL
.replace(":storageKey", "?")
.replace(":callerFingerprint", "?")
.replace(":fullMethodName", "?")
.replace(":idempotencyKeyHash", "?")
.replace(":requestFingerprint", "?")
.replace(":claimedAt", "?");
}
private static String migration() throws IOException {
try (InputStream stream =
GrpcOperationLedgerPostgresIT.class
.getClassLoader()
.getResourceAsStream("db/migration/grpc/V001__create_grpc_operation_ledger.sql")) {
if (stream == null) {
throw new IOException("gRPC operation-ledger migration is missing");
}
return new String(stream.readAllBytes(), StandardCharsets.UTF_8);
}
}
}
@@ -1,5 +1,9 @@
package dev.caskeleton.grpc.ledger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerRecord;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerState;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.EnumType;
@@ -1,20 +1,68 @@
package dev.caskeleton.grpc.ledger;
import java.time.Instant;
import java.util.Optional;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.Repository;
import org.springframework.data.repository.query.Param;
import org.springframework.transaction.annotation.Transactional;
/**
* The narrow persistence interface the ledger adapter needs.
*
* <p>Extends {@code Repository} rather than {@code JpaRepository}, and the difference is the point:
* {@code JpaRepository} publishes {@code deleteAll}, {@code findAll} and {@code saveAll} on the
* table that decides whether a payment runs twice. Naming the four methods that are actually used
* also makes a hand-rolled test double a few lines rather than thirty stubs.
* <p>The claim path is deliberately not {@code save}. A claim entity already has a non-null string
* id, so Spring Data JPA treats it as detached and routes {@code save} through {@code merge}; merge
* can overwrite a committed row back to {@code IN_PROGRESS}. Claiming therefore uses one native
* insert with PostgreSQL conflict handling and decides ownership from the affected-row count.
*/
public interface GrpcOperationLedgerRepository
extends Repository<GrpcOperationLedgerEntity, String> {
/** Inserts or updates a claim. */
/** Atomic PostgreSQL claim statement, also executed by the real-database certification test. */
String ATOMIC_CLAIM_SQL =
"""
INSERT INTO grpc_operation_ledger (
storage_key,
caller_fingerprint,
full_method_name,
idempotency_key_hash,
request_fingerprint,
state,
outcome_reference,
claimed_at,
completed_at
) VALUES (
:storageKey,
:callerFingerprint,
:fullMethodName,
:idempotencyKeyHash,
:requestFingerprint,
'IN_PROGRESS',
NULL,
:claimedAt,
NULL
)
ON CONFLICT DO NOTHING
""";
/**
* Attempts to create the claim atomically.
*
* @return one when this caller inserted the claim, zero when another claim already exists
*/
@Modifying
@Transactional
@Query(value = ATOMIC_CLAIM_SQL, nativeQuery = true)
int tryInsertClaim(
@Param("storageKey") String storageKey,
@Param("callerFingerprint") String callerFingerprint,
@Param("fullMethodName") String fullMethodName,
@Param("idempotencyKeyHash") String idempotencyKeyHash,
@Param("requestFingerprint") String requestFingerprint,
@Param("claimedAt") Instant claimedAt);
/** Updates an existing claim after it has been loaded. */
GrpcOperationLedgerEntity save(GrpcOperationLedgerEntity entity);
/** Reads a claim by its derived storage key. */
@@ -1,18 +1,21 @@
package dev.caskeleton.grpc.ledger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerRecord;
import java.time.Instant;
import java.util.Optional;
import org.springframework.dao.DataIntegrityViolationException;
/**
* The JPA-backed operation ledger.
*
* <p>{@link #claim} is insert-first, read-on-conflict — not read-then-insert. That ordering is the
* whole adapter. Two concurrent attempts with the same idempotency key both try to insert; the
* database's unique constraint lets exactly one through and the other catches the violation and
* reads the winner's row. A read-first implementation has a window between the read and the insert
* that is exactly as wide as the race it is supposed to close, and it passes every test that does
* not run the two attempts concurrently.
* whole adapter. Two concurrent attempts with the same idempotency key both execute one PostgreSQL
* {@code INSERT ... ON CONFLICT DO NOTHING}; the affected-row count identifies the single winner
* and every loser reads the winner's row. The claim path deliberately does not use Spring Data
* {@code save}: this entity has a non-null application-assigned id, so save routes through merge
* and can overwrite an existing terminal row.
*
* <p>No transaction annotations here. The commit is meant to happen inside the caller's business
* transaction, and a {@code REQUIRES_NEW} on this adapter would put the ledger in its own
@@ -34,14 +37,21 @@ public final class JpaGrpcOperationLedger implements GrpcOperationLedger {
public Optional<GrpcOperationLedgerRecord> claim(
GrpcOperationIdentity identity, String requestFingerprint, Instant now) {
requireIdentity(identity);
try {
repository.save(GrpcOperationLedgerEntity.claim(identity, requestFingerprint, now));
int inserted =
repository.tryInsertClaim(
identity.storageKey(),
identity.callerFingerprint(),
identity.method().canonical(),
identity.idempotencyKeyHash(),
requestFingerprint,
now);
if (inserted == 1) {
return Optional.empty();
} catch (DataIntegrityViolationException alreadyClaimed) {
// The unique constraint fired, which means somebody else won the race. Their row is the
// answer; the exception is how we find out, not a failure.
return repository.findById(identity.storageKey()).map(entity -> entity.toRecord(identity));
}
if (inserted != 0) {
throw new IllegalStateException("claim insert affected an unexpected row count: " + inserted);
}
return repository.findById(identity.storageKey()).map(entity -> entity.toRecord(identity));
}
@Override
@@ -1,5 +1,10 @@
package dev.caskeleton.grpc.ledger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerRecord;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerState;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -15,7 +20,6 @@ import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.dao.DataIntegrityViolationException;
class GrpcOperationLedgerRepositoryTest {
@@ -30,21 +34,34 @@ class GrpcOperationLedgerRepositoryTest {
"sha256:aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899";
/**
* An in-memory stand-in for the Spring Data repository, with the unique constraint the real table
* carries. {@code putIfAbsent} is what makes the claim atomic here for the same reason the
* constraint does there; a fake without it would let the adapter's insert-first ordering pass
* while the property it protects does not hold.
* An in-memory stand-in for Spring Data's non-null-id save semantics.
*
* <p>A newly constructed ledger entity already has its string id, so a real {@code
* SimpleJpaRepository.save} treats it as detached and merges it. The old fake used {@code
* putIfAbsent} and therefore tested the database constraint we wished save() would hit rather
* than the merge behavior it actually uses.
*/
private static final class InMemoryRepository implements GrpcOperationLedgerRepository {
private final ConcurrentMap<String, GrpcOperationLedgerEntity> rows = new ConcurrentHashMap<>();
@Override
public int tryInsertClaim(
String storageKey,
String callerFingerprint,
String fullMethodName,
String idempotencyKeyHash,
String requestFingerprint,
Instant claimedAt) {
GrpcOperationIdentity identity =
new GrpcOperationIdentity(
callerFingerprint, GrpcMethodName.parse(fullMethodName), idempotencyKeyHash);
GrpcOperationLedgerEntity claim =
GrpcOperationLedgerEntity.claim(identity, requestFingerprint, claimedAt);
return rows.putIfAbsent(storageKey, claim) == null ? 1 : 0;
}
@Override
public GrpcOperationLedgerEntity save(GrpcOperationLedgerEntity entity) {
GrpcOperationLedgerEntity existing = rows.putIfAbsent(entity.getStorageKey(), entity);
if (existing != null && existing != entity) {
throw new DataIntegrityViolationException(
"uq_grpc_operation_ledger_identity violated for " + entity.getStorageKey());
}
rows.put(entity.getStorageKey(), entity);
return entity;
}
@@ -123,6 +140,21 @@ class GrpcOperationLedgerRepositoryTest {
assertThat(record.completedAt()).contains(NOW.plusSeconds(1));
}
@Test
@DisplayName("claiming a committed operation returns the stored outcome without rewriting it")
void retryingACommittedClaimPreservesTheWinner() {
GrpcOperationIdentity id = identity("tenant-1.actor-1");
assertThat(ledger.claim(id, FINGERPRINT, NOW)).isEmpty();
ledger.markCommitted(id, "outcome://document/42", NOW.plusSeconds(1));
GrpcOperationLedgerRecord retry =
ledger.claim(id, OTHER_FINGERPRINT, NOW.plusSeconds(2)).orElseThrow();
assertThat(retry.state()).isEqualTo(GrpcOperationLedgerState.COMMITTED);
assertThat(retry.outcomeReference()).contains("outcome://document/42");
assertThat(retry.requestFingerprint()).isEqualTo(FINGERPRINT);
}
@Test
@DisplayName("a commit without a claim is refused rather than silently inserted")
void committingWithoutAClaimIsRefused() {
@@ -1,8 +1,11 @@
package dev.caskeleton.grpc.context;
import dev.caskeleton.grpc.api.context.GrpcClientIdentity;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import java.time.Instant;
import java.util.Optional;
@@ -1,5 +1,7 @@
package dev.caskeleton.grpc.deadline;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashMap;
@@ -1,7 +1,10 @@
package dev.caskeleton.grpc.deadline;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import java.time.Duration;
/**
@@ -2,8 +2,8 @@ package dev.caskeleton.grpc.deadline;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
@@ -1,5 +1,9 @@
package dev.caskeleton.grpc.error;
import dev.caskeleton.grpc.api.error.GrpcFailureCategory;
import dev.caskeleton.grpc.api.error.GrpcFailureContext;
import dev.caskeleton.grpc.api.error.GrpcPlatformException;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.validation.GrpcValidationViolation;
import io.grpc.Metadata;
@@ -1,5 +1,7 @@
package dev.caskeleton.grpc.error;
import dev.caskeleton.grpc.api.error.GrpcFailureCategory;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import io.grpc.Status;
@@ -1,12 +1,12 @@
package dev.caskeleton.grpc.idempotency;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.ledger.GrpcOperationLedgerRecord;
import dev.caskeleton.grpc.ledger.GrpcOperationLedgerState;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerRecord;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerState;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
@@ -1,10 +1,10 @@
package dev.caskeleton.grpc.idempotency;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.ledger.GrpcOperationLedgerRecord;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerRecord;
import java.time.Duration;
import java.util.Optional;
@@ -1,37 +1,54 @@
package dev.caskeleton.grpc.idempotency;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
/**
* Returns the stored answer for an operation that already committed.
*
* <p>Separated from the ledger because the two have different size problems. The ledger row must
* stay small and is written inside the business transaction; a response may be large and is only
* needed if somebody actually retries. So the ledger stores a reference and this resolves it,
* against whatever the deployment chose — a small inline store, an object store, or a re-read of
* the committed resource.
* needed if somebody actually retries. This in-memory implementation is deliberately bounded; a
* deployment that needs durable or larger replay should keep the response behind an object
* reference instead.
*/
public final class GrpcOutcomeReplay {
private final ConcurrentMap<String, byte[]> storedOutcomes = new ConcurrentHashMap<>();
private static final int DEFAULT_MAX_ENTRIES = 1024;
private final Map<String, byte[]> storedOutcomes = new LinkedHashMap<>(16, 0.75f, true);
private final int maxInlineBytes;
private final int maxEntries;
/**
* Creates a bounded in-memory replay store with the default entry ceiling.
*
* @param maxInlineBytes the largest response stored inline
*/
public GrpcOutcomeReplay(int maxInlineBytes) {
this(maxInlineBytes, DEFAULT_MAX_ENTRIES);
}
/**
* @param maxInlineBytes the largest response stored inline; anything larger must be kept behind a
* reference in an object store instead, which is why {@link #store} refuses it rather than
* silently truncating
* reference in an object store instead
* @param maxEntries the maximum number of inline outcomes retained in-process
*/
public GrpcOutcomeReplay(int maxInlineBytes) {
public GrpcOutcomeReplay(int maxInlineBytes, int maxEntries) {
if (maxInlineBytes < 1) {
throw new IllegalArgumentException("an inline outcome store needs a positive size limit");
}
if (maxEntries < 1) {
throw new IllegalArgumentException("an inline outcome store needs a positive entry limit");
}
this.maxInlineBytes = maxInlineBytes;
this.maxEntries = maxEntries;
}
/** Stores a response under {@code outcomeReference}. */
public void store(String outcomeReference, byte[] serializedResponse) {
public synchronized void store(String outcomeReference, byte[] serializedResponse) {
if (outcomeReference == null || outcomeReference.isBlank()) {
throw new IllegalArgumentException("an outcome needs a reference to be stored under");
}
@@ -47,16 +64,21 @@ public final class GrpcOutcomeReplay {
+ "; store it behind an object reference instead");
}
storedOutcomes.put(outcomeReference, serializedResponse.clone());
while (storedOutcomes.size() > maxEntries) {
Iterator<Map.Entry<String, byte[]>> iterator = storedOutcomes.entrySet().iterator();
iterator.next();
iterator.remove();
}
}
/** The stored response, if there is one. */
public Optional<byte[]> replay(String outcomeReference) {
public synchronized Optional<byte[]> replay(String outcomeReference) {
byte[] stored = storedOutcomes.get(outcomeReference);
return Optional.ofNullable(stored).map(byte[]::clone);
}
/** How many outcomes are held. */
public int size() {
public synchronized int size() {
return storedOutcomes.size();
}
}
@@ -1,9 +1,9 @@
package dev.caskeleton.grpc.resilience;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.evidence.GrpcExecutionEvidence;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import java.time.Duration;
import java.util.random.RandomGenerator;
@@ -2,8 +2,8 @@ package dev.caskeleton.grpc.resilience;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.evidence.GrpcExecutionEvidence;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
/**
* Whether an attempt may be repeated at all, judged from the method, the evidence and the status
@@ -33,7 +33,7 @@ public enum GrpcRetryOwner {
}
/** Whether hedging may be configured under this owner. */
public boolean hedgingAllowed() {
public boolean permitsHedging() {
return this == GRPC_PLATFORM;
}
}
@@ -1,8 +1,8 @@
package dev.caskeleton.grpc.resilience;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
@@ -71,7 +71,7 @@ public final class GrpcRetryOwnershipValidator {
});
if (serviceConfig.retryOwner() == GrpcRetryOwner.SERVICE_MESH
&& serviceConfig.hedgingAllowed()) {
&& serviceConfig.retryOwnerPermitsHedging()) {
violations.add("a mesh-owned channel may not also configure hedging in-process");
}
return List.copyOf(violations);
@@ -67,7 +67,7 @@ public record GrpcServiceConfigPolicy(
}
/** Whether hedging may be configured on this channel. */
public boolean hedgingAllowed() {
return retryOwner.hedgingAllowed();
public boolean retryOwnerPermitsHedging() {
return retryOwner.permitsHedging();
}
}
@@ -1,6 +1,6 @@
package dev.caskeleton.grpc.resilience;
import dev.caskeleton.grpc.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.api.policy.WaitForReadyPolicy;
import java.time.Duration;
/**
@@ -1,7 +1,7 @@
package dev.caskeleton.grpc.resilience;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import java.time.Duration;
/**
@@ -28,7 +28,7 @@ public final class GrpcSerializedStreamWriter<T> {
private final GrpcFlowControlPolicy flowControl;
private final Consumer<GrpcStreamEnvelope<T>> transport;
private final LongSupplier payloadSizer;
private final Deque<GrpcStreamEnvelope<T>> queue = new ArrayDeque<>();
private final Deque<QueuedEnvelope<T>> queue = new ArrayDeque<>();
private GrpcStreamWriterState state = GrpcStreamWriterState.OPEN;
private long queuedBytes;
@@ -79,13 +79,23 @@ public final class GrpcSerializedStreamWriter<T> {
yield GrpcStreamWriteResult.OVERFLOW_TERMINATING;
}
case DROP_OLDEST -> {
GrpcStreamEnvelope<T> dropped = queue.pollFirst();
if (dropped != null) {
queuedBytes = Math.max(0L, queuedBytes - nextBytes);
while (true) {
QueuedEnvelope<T> dropped = queue.pollFirst();
if (dropped == null) {
// The incoming message cannot fit even into an empty bounded queue. A lossy profile
// drops that message rather than violating the byte bound it exists to enforce.
droppedMessages++;
yield GrpcStreamWriteResult.DROPPED;
}
queuedBytes = Math.max(0L, queuedBytes - dropped.serializedBytes());
droppedMessages++;
GrpcFlowControlDecision afterDrop =
flowControl.decide(queue.size(), queuedBytes, nextBytes, transportReady);
if (afterDrop.action() != GrpcFlowControlDecision.Action.DROP_OLDEST) {
enqueue(kind, payload, snapshotVersion, resumeToken, nextBytes);
yield GrpcStreamWriteResult.DROPPED;
}
}
enqueue(kind, payload, snapshotVersion, resumeToken, nextBytes);
yield GrpcStreamWriteResult.DROPPED;
}
case PAUSE, PROCEED -> {
enqueue(kind, payload, snapshotVersion, resumeToken, nextBytes);
@@ -101,8 +111,10 @@ public final class GrpcSerializedStreamWriter<T> {
String resumeToken,
long bytes) {
queue.addLast(
GrpcStreamEnvelope.message(
streamId, sequence.next(), kind, payload, snapshotVersion, resumeToken));
new QueuedEnvelope<>(
GrpcStreamEnvelope.message(
streamId, sequence.next(), kind, payload, snapshotVersion, resumeToken),
bytes));
queuedBytes += bytes;
}
@@ -114,7 +126,7 @@ public final class GrpcSerializedStreamWriter<T> {
public synchronized List<Long> flush() {
java.util.List<Long> flushed = new java.util.ArrayList<>();
while (!queue.isEmpty()) {
GrpcStreamEnvelope<T> envelope = queue.pollFirst();
GrpcStreamEnvelope<T> envelope = queue.pollFirst().envelope();
transport.accept(envelope);
lastFlushedSequence = envelope.sequence();
flushed.add(envelope.sequence());
@@ -173,4 +185,12 @@ public final class GrpcSerializedStreamWriter<T> {
public synchronized Optional<Long> lastFlushedSequence() {
return lastFlushedSequence == 0L ? Optional.empty() : Optional.of(lastFlushedSequence);
}
private record QueuedEnvelope<T>(GrpcStreamEnvelope<T> envelope, long serializedBytes) {
private QueuedEnvelope {
if (envelope == null || serializedBytes < 0L) {
throw new IllegalArgumentException("a queued envelope needs a message and byte size");
}
}
}
}
@@ -35,7 +35,7 @@ public final class GrpcStreamAdmission {
*
* @return false when either bound is reached; the caller answers RESOURCE_EXHAUSTED
*/
public boolean tryAdmit(String callerFingerprint) {
public synchronized boolean tryAdmit(String callerFingerprint) {
if (callerFingerprint == null || callerFingerprint.isBlank()) {
throw new IllegalArgumentException("stream admission needs a caller fingerprint");
}
@@ -53,14 +53,16 @@ public final class GrpcStreamAdmission {
}
/** Releases a stream's slot. */
public void release(String callerFingerprint) {
public synchronized void release(String callerFingerprint) {
AtomicInteger callerCount = perCaller.get(callerFingerprint);
if (callerCount != null && callerCount.get() > 0) {
callerCount.decrementAndGet();
if (callerCount == null || callerCount.get() <= 0) {
return;
}
if (openStreams.get() > 0) {
openStreams.decrementAndGet();
int remaining = callerCount.decrementAndGet();
if (remaining == 0) {
perCaller.remove(callerFingerprint, callerCount);
}
openStreams.decrementAndGet();
}
/** How many streams are open. */
@@ -73,4 +75,8 @@ public final class GrpcStreamAdmission {
AtomicInteger callerCount = perCaller.get(callerFingerprint);
return callerCount == null ? 0 : callerCount.get();
}
int trackedCallers() {
return perCaller.size();
}
}
@@ -20,7 +20,7 @@ import java.util.Map;
* carries only field paths and reason constants. The rejected values never leave the process —
* which is the reason {@link GrpcValidationViolation} has nowhere to put them.
*/
public final class ProtovalidateGrpcInterceptor implements ServerInterceptor {
public final class GrpcValidationInterceptor implements ServerInterceptor {
/** Trailer carrying the violated field paths and reasons, comma-separated. */
public static final Metadata.Key<String> VIOLATIONS_KEY =
@@ -35,7 +35,7 @@ public final class ProtovalidateGrpcInterceptor implements ServerInterceptor {
* entry is passed through untouched rather than rejected, because "this method has no
* transport constraints" is a legitimate state
*/
public ProtovalidateGrpcInterceptor(
public GrpcValidationInterceptor(
Map<String, GrpcTransportValidator<?>> validatorsByFullMethodName) {
if (validatorsByFullMethodName == null) {
throw new IllegalArgumentException("the validator map must not be null");
@@ -1,13 +1,17 @@
package dev.caskeleton.grpc.context;
import dev.caskeleton.grpc.api.context.GrpcClientIdentity;
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import java.time.Duration;
import java.time.Instant;
import java.util.Map;
@@ -1,5 +1,7 @@
package dev.caskeleton.grpc.deadline;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -1,11 +1,14 @@
package dev.caskeleton.grpc.deadline;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import java.time.Duration;
import java.util.Map;
import java.util.Set;
@@ -1,5 +1,10 @@
package dev.caskeleton.grpc.error;
import dev.caskeleton.grpc.api.error.GrpcCompletionOutcome;
import dev.caskeleton.grpc.api.error.GrpcFailureCategory;
import dev.caskeleton.grpc.api.error.GrpcFailureContext;
import dev.caskeleton.grpc.api.error.GrpcPlatformException;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.grpc.core.GrpcMethodName;
@@ -22,7 +22,7 @@ class GrpcCompletionReconcilerTest {
private void claim() {
ledger.claim(
new dev.caskeleton.grpc.ledger.GrpcOperationIdentity(
new dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity(
CALLER, CREATE, GrpcRequestFingerprint.hashIdempotencyKey(KEY)),
GrpcRequestFingerprint.of("body"),
NOW);
@@ -66,7 +66,7 @@ class GrpcCompletionReconcilerTest {
void aCommittedOperationReturnsItsStoredOutcome() {
claim();
ledger.markCommitted(
new dev.caskeleton.grpc.ledger.GrpcOperationIdentity(
new dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity(
CALLER, CREATE, GrpcRequestFingerprint.hashIdempotencyKey(KEY)),
"outcome://document/42",
NOW.plusSeconds(1));
@@ -89,7 +89,7 @@ class GrpcCompletionReconcilerTest {
void theLedgerIsConsultedFirst() {
claim();
ledger.markCommitted(
new dev.caskeleton.grpc.ledger.GrpcOperationIdentity(
new dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity(
CALLER, CREATE, GrpcRequestFingerprint.hashIdempotencyKey(KEY)),
"outcome://from-ledger",
NOW.plusSeconds(1));
@@ -5,11 +5,11 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.WaitForReadyPolicy;
import java.time.Duration;
import java.time.Instant;
import org.junit.jupiter.api.DisplayName;
@@ -151,7 +151,7 @@ class GrpcIdempotencyInterceptorTest {
assertThat(hashed).startsWith("sha256:").doesNotContain(KEY);
assertThat(
new dev.caskeleton.grpc.ledger.GrpcOperationIdentity(CALLER, CREATE, hashed)
new dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity(CALLER, CREATE, hashed)
.storageKey())
.doesNotContain(KEY);
}
@@ -0,0 +1,24 @@
package dev.caskeleton.grpc.idempotency;
import static org.assertj.core.api.Assertions.assertThat;
import org.junit.jupiter.api.Test;
class GrpcOutcomeReplayBoundTest {
@Test
void boundedReplayEvictsTheLeastRecentlyUsedOutcome() {
GrpcOutcomeReplay replay = new GrpcOutcomeReplay(16, 2);
replay.store("one", new byte[] {1});
replay.store("two", new byte[] {2});
assertThat(replay.replay("one")).isPresent();
replay.store("three", new byte[] {3});
assertThat(replay.replay("one")).isPresent();
assertThat(replay.replay("two")).isEmpty();
assertThat(replay.replay("three")).isPresent();
assertThat(replay.size()).isEqualTo(2);
}
}
@@ -1,9 +1,9 @@
package dev.caskeleton.grpc.idempotency;
import dev.caskeleton.grpc.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.ledger.GrpcOperationLedgerRecord;
import dev.caskeleton.grpc.ledger.GrpcOperationLedgerState;
import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedger;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerRecord;
import dev.caskeleton.grpc.api.ledger.GrpcOperationLedgerState;
import java.time.Instant;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
@@ -5,15 +5,15 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.evidence.GrpcBusinessEvidence;
import dev.caskeleton.grpc.evidence.GrpcExecutionEvidence;
import dev.caskeleton.grpc.evidence.GrpcStreamEvidence;
import dev.caskeleton.grpc.evidence.GrpcTransportEvidence;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.WaitForReadyPolicy;
import java.time.Duration;
import java.util.random.RandomGenerator;
import org.junit.jupiter.api.DisplayName;
@@ -6,11 +6,11 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.WaitForReadyPolicy;
import java.time.Duration;
import java.util.Map;
import java.util.Set;
@@ -52,8 +52,8 @@ class GrpcRetryOwnershipValidatorTest {
assertThat(GrpcRetryOwner.GRPC_PLATFORM.explicitRetryInProcess()).isTrue();
assertThat(GrpcRetryOwner.SERVICE_MESH.explicitRetryInProcess()).isFalse();
assertThat(GrpcRetryOwner.NONE.explicitRetryInProcess()).isFalse();
assertThat(GrpcRetryOwner.GRPC_PLATFORM.hedgingAllowed()).isTrue();
assertThat(GrpcRetryOwner.SERVICE_MESH.hedgingAllowed()).isFalse();
assertThat(GrpcRetryOwner.GRPC_PLATFORM.permitsHedging()).isTrue();
assertThat(GrpcRetryOwner.SERVICE_MESH.permitsHedging()).isFalse();
}
@Test
@@ -75,7 +75,7 @@ class GrpcRetryOwnershipValidatorTest {
GrpcServiceConfigPolicy mesh =
GrpcServiceConfigPolicy.meshOwned(Map.of(GET, GrpcMethodRetryConfig.disabled(GET)));
assertThat(mesh.hedgingAllowed()).isFalse();
assertThat(mesh.retryOwnerPermitsHedging()).isFalse();
assertThat(GrpcRetryOwnershipValidator.validate(mesh, catalog())).isEmpty();
}
@@ -5,11 +5,11 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.WaitForReadyPolicy;
import java.time.Duration;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -9,6 +9,7 @@ import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicLong;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -110,6 +111,56 @@ class GrpcSerializedStreamWriterTest {
assertThat(writer.queuedMessages()).isEqualTo(1);
}
@Test
@DisplayName("DROP_OLDEST subtracts the dropped message bytes, not the next message bytes")
void dropOldestKeepsByteAccountingExactForVariableSizedMessages() {
AtomicLong nextSize = new AtomicLong();
GrpcSerializedStreamWriter<String> writer =
new GrpcSerializedStreamWriter<>(
STREAM,
GrpcStreamSequence.forNewStream(STREAM),
new GrpcFlowControlPolicy(10, 1000L, 9, GrpcSlowConsumerPolicy.DROP_OLDEST),
sent::add,
nextSize::get);
nextSize.set(900L);
assertThat(writer.write(GrpcStreamEnvelope.Kind.LIVE, "large", null, null, true))
.isEqualTo(GrpcStreamWriteResult.ACCEPTED);
nextSize.set(200L);
assertThat(writer.write(GrpcStreamEnvelope.Kind.LIVE, "small", null, null, true))
.isEqualTo(GrpcStreamWriteResult.DROPPED);
// Correct accounting is now 200 bytes. The old bug subtracted 200 rather than the dropped
// 900-byte message, leaving a phantom 900 bytes and causing this write to drop again.
nextSize.set(300L);
assertThat(writer.write(GrpcStreamEnvelope.Kind.LIVE, "medium", null, null, true))
.isEqualTo(GrpcStreamWriteResult.ACCEPTED);
assertThat(writer.droppedMessages()).isEqualTo(1);
}
@Test
@DisplayName("DROP_OLDEST removes as many queued messages as the byte bound requires")
void dropOldestRepeatsUntilTheIncomingMessageFits() {
AtomicLong nextSize = new AtomicLong(300L);
GrpcSerializedStreamWriter<String> writer =
new GrpcSerializedStreamWriter<>(
STREAM,
GrpcStreamSequence.forNewStream(STREAM),
new GrpcFlowControlPolicy(10, 700L, 9, GrpcSlowConsumerPolicy.DROP_OLDEST),
sent::add,
nextSize::get);
writer.write(GrpcStreamEnvelope.Kind.LIVE, "first", null, null, true);
writer.write(GrpcStreamEnvelope.Kind.LIVE, "second", null, null, true);
nextSize.set(600L);
assertThat(writer.write(GrpcStreamEnvelope.Kind.LIVE, "large", null, null, true))
.isEqualTo(GrpcStreamWriteResult.DROPPED);
assertThat(writer.droppedMessages()).isEqualTo(2);
assertThat(writer.queuedMessages()).isEqualTo(1);
}
@Test
@DisplayName("the terminal signal is sent exactly once")
void theTerminalSignalIsSentOnce() {
@@ -0,0 +1,48 @@
package dev.caskeleton.grpc.streaming;
import static org.assertj.core.api.Assertions.assertThat;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import org.junit.jupiter.api.Test;
class GrpcStreamAdmissionConcurrencyTest {
@Test
void concurrentAdmissionsNeverExceedThePerCallerBoundAndReleaseRemovesCallerState()
throws Exception {
GrpcStreamAdmission admission = new GrpcStreamAdmission(4, 1);
CountDownLatch start = new CountDownLatch(1);
try (var executor = Executors.newFixedThreadPool(16)) {
List<Future<Boolean>> attempts = new ArrayList<>();
for (int index = 0; index < 16; index++) {
attempts.add(
executor.submit(
() -> {
start.await();
return admission.tryAdmit("caller");
}));
}
start.countDown();
int admitted = 0;
for (Future<Boolean> attempt : attempts) {
if (attempt.get()) {
admitted++;
}
}
assertThat(admitted).isOne();
assertThat(admission.openStreamsFor("caller")).isOne();
admission.release("caller");
assertThat(admission.openStreams()).isZero();
assertThat(admission.trackedCallers()).isZero();
}
}
}
@@ -20,7 +20,7 @@ import java.util.concurrent.atomic.AtomicInteger;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class ProtovalidateGrpcInterceptorTest {
class GrpcValidationInterceptorTest {
private static final String FULL_METHOD = "hyeonworks.document.v1.DocumentService/CreateDocument";
@@ -165,8 +165,8 @@ class ProtovalidateGrpcInterceptorTest {
@Test
@DisplayName("a valid message reaches the handler untouched")
void validMessagesReachTheHandler() {
ProtovalidateGrpcInterceptor interceptor =
new ProtovalidateGrpcInterceptor(Map.of(FULL_METHOD, titleValidator()));
GrpcValidationInterceptor interceptor =
new GrpcValidationInterceptor(Map.of(FULL_METHOD, titleValidator()));
RecordingServerCall call = new RecordingServerCall();
RecordingHandler handler = new RecordingHandler();
@@ -182,8 +182,8 @@ class ProtovalidateGrpcInterceptorTest {
@Test
@DisplayName("an invalid message is closed as INVALID_ARGUMENT and never reaches the handler")
void invalidMessagesAreRefusedBeforeTheUseCase() {
ProtovalidateGrpcInterceptor interceptor =
new ProtovalidateGrpcInterceptor(Map.of(FULL_METHOD, titleValidator()));
GrpcValidationInterceptor interceptor =
new GrpcValidationInterceptor(Map.of(FULL_METHOD, titleValidator()));
RecordingServerCall call = new RecordingServerCall();
RecordingHandler handler = new RecordingHandler();
@@ -194,15 +194,15 @@ class ProtovalidateGrpcInterceptorTest {
assertThat(handler.delivered).isEmpty();
assertThat(handler.halfCloses).hasValue(0);
assertThat(call.closedStatus.getCode()).isEqualTo(Status.Code.INVALID_ARGUMENT);
assertThat(call.closedTrailers.get(ProtovalidateGrpcInterceptor.VIOLATIONS_KEY))
assertThat(call.closedTrailers.get(GrpcValidationInterceptor.VIOLATIONS_KEY))
.isEqualTo("document.title: LENGTH_EXCEEDED");
}
@Test
@DisplayName("the rejected value never appears in the status or the trailers")
void theRejectedValueIsNeverEchoed() {
ProtovalidateGrpcInterceptor interceptor =
new ProtovalidateGrpcInterceptor(Map.of(FULL_METHOD, titleValidator()));
GrpcValidationInterceptor interceptor =
new GrpcValidationInterceptor(Map.of(FULL_METHOD, titleValidator()));
RecordingServerCall call = new RecordingServerCall();
String secret = "national-id-900101-1234567";
@@ -211,14 +211,14 @@ class ProtovalidateGrpcInterceptorTest {
listener.onMessage(secret);
assertThat(call.closedStatus.getDescription()).doesNotContain(secret);
assertThat(call.closedTrailers.get(ProtovalidateGrpcInterceptor.VIOLATIONS_KEY))
assertThat(call.closedTrailers.get(GrpcValidationInterceptor.VIOLATIONS_KEY))
.doesNotContain(secret);
}
@Test
@DisplayName("a method with no registered validator is passed through rather than refused")
void unregisteredMethodsPassThrough() {
ProtovalidateGrpcInterceptor interceptor = new ProtovalidateGrpcInterceptor(Map.of());
GrpcValidationInterceptor interceptor = new GrpcValidationInterceptor(Map.of());
RecordingHandler handler = new RecordingHandler();
ServerCall.Listener<String> listener =
@@ -6,6 +6,8 @@ option java_multiple_files = true;
option java_package = "hyeonworks.grpc.common.v1.generated";
option java_outer_classname = "ErrorProto";
import "google/protobuf/duration.proto";
// The platform's allowlisted rich error details.
//
// Deliberately this repository's own messages rather than google.rpc.*: the Stable contract is that
@@ -30,8 +32,8 @@ message BadRequest {
// Whether and when the caller may try again. The only channel for a retry hint.
message RetryInfo {
// Seconds to wait before the next attempt. Zero means "do not retry".
int64 retry_delay_seconds = 1;
// Delay before the next attempt. Zero duration means "do not retry".
google.protobuf.Duration retry_delay = 1;
// Attempts already made, 1-based.
int32 attempt = 2;
}
@@ -51,7 +53,6 @@ message PreconditionFailure {
message Violation {
string type = 1;
string subject = 2;
optional string description = 3;
}
repeated Violation violations = 1;
}
@@ -1,6 +1,6 @@
package dev.caskeleton.grpc.server;
import dev.caskeleton.grpc.context.GrpcRequestContext;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
/**
* The single call an adapter makes into the application.
@@ -1,8 +1,8 @@
package dev.caskeleton.grpc.server;
import dev.caskeleton.grpc.context.GrpcRequestContext;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import dev.caskeleton.grpc.error.GrpcErrorMapper;
import dev.caskeleton.grpc.error.GrpcPlatformException;
import dev.caskeleton.grpc.api.error.GrpcPlatformException;
import java.util.function.Function;
/**
@@ -33,7 +33,7 @@ class GrpcApplicationBoundaryRulesTest {
"DocumentServiceAdapter",
Set.of(
"dev.caskeleton.application.document.CreateDocumentUseCase",
"dev.caskeleton.grpc.context.GrpcRequestContext")))
"dev.caskeleton.grpc.api.context.GrpcRequestContext")))
.isEmpty();
}
@@ -3,20 +3,20 @@ package dev.caskeleton.grpc.server;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.context.GrpcClientIdentity;
import dev.caskeleton.grpc.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.context.GrpcRequestContext;
import dev.caskeleton.grpc.api.context.GrpcClientIdentity;
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.GrpcStatusCode;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.error.GrpcCompletionOutcome;
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.error.GrpcCompletionOutcome;
import dev.caskeleton.grpc.error.GrpcErrorMapper;
import dev.caskeleton.grpc.error.GrpcFailureCategory;
import dev.caskeleton.grpc.error.GrpcFailureContext;
import dev.caskeleton.grpc.error.GrpcPlatformException;
import dev.caskeleton.grpc.api.error.GrpcFailureCategory;
import dev.caskeleton.grpc.api.error.GrpcFailureContext;
import dev.caskeleton.grpc.api.error.GrpcPlatformException;
import dev.caskeleton.grpc.evidence.GrpcExecutionEvidence;
import io.grpc.Status;
import java.time.Duration;
+1 -1
View File
@@ -20,7 +20,7 @@ dependencies {
implementation project(':grpc:grpc-proto-contract')
implementation project(':grpc:grpc-codegen')
implementation project(':grpc:grpc-operation-ledger-jpa')
implementation 'org.springframework.boot:spring-boot-autoconfigure'
}
@@ -42,13 +42,11 @@ io.grpc:grpc-stub:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.annotation:jakarta.annotation-api:3.0.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.persistence:jakarta.persistence-api:3.2.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle,compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
@@ -92,21 +90,16 @@ 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.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=compileClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.springframework.boot:spring-boot-autoconfigure:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-configuration-processor:4.0.8=annotationProcessor
org.springframework.boot:spring-boot:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.data:spring-data-commons:4.0.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.data:spring-data-jpa:4.0.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-beans:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-context:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-core:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-jdbc:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-orm:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
@@ -5,18 +5,24 @@ import dev.caskeleton.grpc.admin.GrpcDrainPolicy;
import dev.caskeleton.grpc.admin.GrpcHealthPolicy;
import dev.caskeleton.grpc.admin.GrpcReflectionPolicy;
import dev.caskeleton.grpc.admin.GrpcServiceHealthRegistry;
import dev.caskeleton.grpc.client.GrpcNamedChannelProfile;
import dev.caskeleton.grpc.context.GrpcContextBinder;
import dev.caskeleton.grpc.context.GrpcContextPropagationPolicy;
import dev.caskeleton.grpc.error.GrpcErrorMapper;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.server.GrpcAdmissionController;
import dev.caskeleton.grpc.server.GrpcExecutorProfile;
import dev.caskeleton.grpc.server.GrpcServerProfile;
import java.time.Duration;
import java.util.Set;
import java.util.UUID;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Assembles the Stable platform when, and only when, a deployment asks for it.
@@ -26,7 +32,7 @@ import org.springframework.context.annotation.Configuration;
* and nothing can: the registry does not permit the edge, so an import here would fail the build
* rather than this comment.
*/
@Configuration(proxyBeanMethods = false)
@AutoConfiguration
@ConditionalOnProperty(
prefix = "ca-skeleton.grpc.platform",
name = "enabled",
@@ -46,8 +52,18 @@ public class GrpcPlatformAutoConfiguration {
/** The server transport profile. */
@Bean
@ConditionalOnMissingBean
public GrpcServerProfile grpcServerProfile(GrpcExecutorProfile executorProfile) {
return GrpcServerProfile.stableNetty(executorProfile);
public GrpcServerProfile grpcServerProfile(
GrpcPlatformProperties properties, GrpcExecutorProfile executorProfile) {
return new GrpcServerProfile(
properties.getTransport(),
1024L * 1024L,
8192,
Duration.ofSeconds(30),
Duration.ofSeconds(10),
Duration.ofSeconds(30),
Duration.ofMinutes(30),
Duration.ofSeconds(30),
executorProfile);
}
/** Admission control, sized from the executor. */
@@ -97,6 +113,26 @@ public class GrpcPlatformAutoConfiguration {
return new GrpcContextBinder(GrpcContextPropagationPolicy.stable());
}
/**
* Runs the Stable startup validator against the bean graph after singleton assembly.
*
* <p>The Gradle architecture gate owns dependency-graph isolation. Runtime validation therefore
* passes no synthetic dependency list; it validates only inputs a running process can actually
* observe: typed properties, the method-policy catalog and named client channels.
*/
@Bean
public SmartInitializingSingleton grpcPlatformStartupCheck(
GrpcPlatformProperties properties,
ObjectProvider<GrpcMethodPolicyCatalog> catalogs,
ObjectProvider<GrpcNamedChannelProfile> channelProfiles) {
return () ->
GrpcPlatformStartupValidator.requireValid(
properties,
catalogs.getIfAvailable(() -> GrpcMethodPolicyCatalog.builder().build()),
channelProfiles.orderedStream().toList(),
Set.of());
}
/** The shared error mapper. Its execution ids are random and carry no derived content. */
@Bean
@ConditionalOnMissingBean
@@ -3,7 +3,6 @@ package dev.caskeleton.grpc.boot;
import dev.caskeleton.grpc.admin.GrpcReflectionMode;
import dev.caskeleton.grpc.security.GrpcTlsProfile;
import dev.caskeleton.grpc.server.GrpcServerTransport;
import java.time.Duration;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
@@ -46,9 +45,6 @@ public class GrpcPlatformProperties {
/** The bounded executor's maximum size. */
private int executorMaxPoolSize = 32;
/** The default deadline applied to a Stable unary method that declares none. */
private Duration defaultUnaryDeadline = Duration.ofSeconds(2);
/** Whether the operation ledger is available, which gates keyed idempotency. */
private boolean operationLedgerEnabled;
@@ -116,14 +112,6 @@ public class GrpcPlatformProperties {
this.executorMaxPoolSize = executorMaxPoolSize;
}
public Duration getDefaultUnaryDeadline() {
return defaultUnaryDeadline;
}
public void setDefaultUnaryDeadline(Duration defaultUnaryDeadline) {
this.defaultUnaryDeadline = defaultUnaryDeadline;
}
public boolean isOperationLedgerEnabled() {
return operationLedgerEnabled;
}
@@ -6,9 +6,9 @@ import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.GrpcStableBuildInvariant;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.discovery.GrpcDiscoveryPolicyValidator;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
import java.util.ArrayList;
import java.util.LinkedHashSet;
@@ -33,8 +33,9 @@ public final class GrpcPlatformStartupValidator {
/**
* Every reason this configuration is refused.
*
* @param stableModuleDependencies the module ids the Stable starter resolves, so an Advanced leak
* is caught at startup as well as by the registry gate at build time
* @param stableModuleDependencies dependency ids supplied by a caller that can observe a runtime
* dependency set; the Spring auto-configuration passes an empty set because the Gradle
* registry gate is authoritative for the compiled graph
* @return an empty list when the configuration is safe to start
*/
public static List<String> violations(
@@ -104,8 +105,8 @@ public final class GrpcPlatformStartupValidator {
private static void validateExecutor(GrpcPlatformProperties properties, List<String> violations) {
if (properties.getExecutorQueueCapacity() < 1) {
violations.add(
"the server executor queue is unbounded; overload becomes unbounded latency, and the work "
+ "that eventually runs is work nobody is waiting for");
"the server executor queue is unbounded; overload becomes unbounded latency, and the work"
+ " that eventually runs is work nobody is waiting for");
}
if (properties.getExecutorMaxPoolSize() < 1) {
violations.add("the server executor pool size must be positive");
@@ -166,7 +167,8 @@ public final class GrpcPlatformStartupValidator {
violations.add(
"two retry owners retry in-process across the configured channels "
+ ownersRetryingInProcess
+ "; retries at two layers multiply the load on a dependency that is already failing");
+ "; retries at two layers multiply the load on a dependency that is already"
+ " failing");
}
}
@@ -0,0 +1,75 @@
package dev.caskeleton.grpc.boot;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.util.Map;
import org.junit.jupiter.api.Test;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.core.env.MapPropertySource;
class GrpcPlatformAutoConfigurationContextTest {
@Test
void invalidProductionSecurityFailsDuringActualAutoConfigurationStartup() {
assertThatThrownBy(
() ->
start(
Map.of(
"ca-skeleton.grpc.platform.enabled", "true",
"ca-skeleton.grpc.platform.environment", "PROD",
"ca-skeleton.grpc.platform.transport", "NETTY_SHADED",
"ca-skeleton.grpc.platform.tls-enabled", "true",
"ca-skeleton.grpc.platform.trust-all-certificates", "true")))
.isInstanceOf(GrpcPlatformConfigurationException.class)
.hasMessageContaining("trust-all is enabled in PROD")
.hasMessageContaining("providing none");
}
@Test
void coherentLocalConfigurationRunsTheStartupValidatorAndStarts() {
try (AnnotationConfigApplicationContext context =
start(
Map.of(
"ca-skeleton.grpc.platform.enabled", "true",
"ca-skeleton.grpc.platform.environment", "LOCAL",
"ca-skeleton.grpc.platform.transport", "NETTY_SHADED",
"ca-skeleton.grpc.platform.executor-queue-capacity", "32",
"ca-skeleton.grpc.platform.executor-max-pool-size", "4"))) {
assertThat(context.getBean(GrpcPlatformProperties.class).isEnabled()).isTrue();
assertThat(
context.getBeansOfType(
org.springframework.beans.factory.SmartInitializingSingleton.class))
.isNotEmpty();
}
}
@Test
void configuredTransportIsUsedByTheServerProfile() {
try (AnnotationConfigApplicationContext context =
start(
Map.of(
"ca-skeleton.grpc.platform.enabled", "true",
"ca-skeleton.grpc.platform.environment", "LOCAL",
"ca-skeleton.grpc.platform.transport", "NETTY"))) {
assertThat(context.getBean(dev.caskeleton.grpc.server.GrpcServerProfile.class).transport())
.isEqualTo(dev.caskeleton.grpc.server.GrpcServerTransport.NETTY);
}
}
private static AnnotationConfigApplicationContext start(Map<String, Object> properties) {
AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext();
context
.getEnvironment()
.getPropertySources()
.addFirst(new MapPropertySource("grpc-platform-test", properties));
context.register(GrpcPlatformAutoConfiguration.class);
try {
context.refresh();
return context;
} catch (RuntimeException failure) {
context.close();
throw failure;
}
}
}
@@ -7,11 +7,11 @@ import dev.caskeleton.grpc.admin.GrpcReflectionMode;
import dev.caskeleton.grpc.client.GrpcNamedChannelProfile;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.core.RpcType;
import dev.caskeleton.grpc.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicy;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
import dev.caskeleton.grpc.api.policy.WaitForReadyPolicy;
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
import dev.caskeleton.grpc.security.GrpcTlsProfile;
import dev.caskeleton.grpc.server.GrpcServerTransport;
@@ -16,7 +16,7 @@ public record GrpcUnaryContractResult(
GrpcEvidenceGrade grade,
int attempts,
int businessInvocations,
dev.caskeleton.grpc.error.GrpcCompletionOutcome observedOutcome) {
dev.caskeleton.grpc.api.error.GrpcCompletionOutcome observedOutcome) {
/** Requires the scenario, the grade and non-negative counts. */
public GrpcUnaryContractResult {
@@ -3,7 +3,7 @@ package dev.caskeleton.grpc.testkit;
import dev.caskeleton.grpc.core.GrpcMethodName;
import dev.caskeleton.grpc.deadline.GrpcDeadlinePolicyValidator;
import dev.caskeleton.grpc.deadline.GrpcDependencyBudget;
import dev.caskeleton.grpc.policy.GrpcMethodPolicyCatalog;
import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

Some files were not shown because too many files have changed in this diff Show More