review-followup Wave 3 라운드 3(P22): Redis runtime·SDK 분리, 좁은 semantic 포트, startup rule, lease fencing 계약

- pub/sub 표면 삭제(G-6b·G-4i — 소비자 0, capability 규칙 3): SDK pub/sub·runtime gateway·PUBSUB lane·env 키 2개
- runtime을 `…cache.redis.runtime`으로(split package 해소), runtime은 소비자가 쓰는 8개 명령(`SemanticRedisCommands`)만,
  118개 메서드 gateway는 redis-sdk가 확장. SDK의 blocking·transaction·admin lane은 코드로 조립(env 키 4개 삭제)
- EVALSHA+NOSCRIPT 재로드 헬퍼 하나(메시지에만 NOSCRIPT가 온 경우도 재로드 — `LeaseScriptsTest` FAIL→PASS)
- startup rule 목록 + runner 하나(환경 검사 8개, exit code·문구 유지), Redis secret 요구는 모듈이 기여,
  ratelimit 정책을 cache-redis 밖으로, lease fencing 계약 테스트(fake·어댑터·실제 Redis)
- 통합: redis-sdk 테스트 2개가 옛 split package 경로를 보던 것 수정(ORCH-new-4)

검증: ./gradlew check architectureCheck verifyDependencyLocks :app-bootstrap:verifyEnvKeys configContractCheck
:app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest --continue 통과(682 task),
Redis 7.4 standalone topology lane: runtime 7 · sdk 14 · cache-redis 19, 실패·skip 0

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 13:39:24 +09:00
co-authored by Claude Opus 5.5
parent 486d85a603
commit 4f4bd1fd34
283 changed files with 5499 additions and 5120 deletions
-6
View File
@@ -138,9 +138,6 @@ APP_CACHE_REDIS_NEGATIVE_TTL=10s
APP_IDEMPOTENCY_REDIS_COMMAND_TIMEOUT=200ms
APP_LEASE_REDIS_COMMAND_TIMEOUT=200ms
APP_LEASE_REDIS_CONTENTION_RETRY_AFTER=50ms
APP_REDIS_ADMIN_CREDENTIAL_REFERENCE=
APP_REDIS_ADMIN_ENABLED=false
APP_REDIS_BLOCKING_MAX_CONNECTIONS=32
APP_REDIS_DATABASE=0
APP_REDIS_MODE=standalone
APP_REDIS_NAMESPACE_DOMAIN=shared
@@ -150,11 +147,9 @@ APP_REDIS_NODES=localhost:6379
APP_REDIS_TIMEOUT_BATCH=2s
APP_REDIS_TIMEOUT_FAST=500ms
APP_REDIS_TIMEOUT_SCRIPT=1s
APP_REDIS_TRANSACTION_MAX_CONNECTIONS=16
APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false
APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE=
APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_COMMANDS=64
APP_REDIS_CAPACITY_MAXIMUM_SCRIPT_CONNECTIONS=8
APP_REDIS_CAPACITY_REJECT_WHEN_DISCONNECTED=true
@@ -166,7 +161,6 @@ APP_REDIS_LIFECYCLE_CONNECT_TIMEOUT=2s
APP_REDIS_LIFECYCLE_DRAIN_TIMEOUT=6s
APP_REDIS_LIFECYCLE_SHUTDOWN_QUIET_PERIOD=100ms
APP_REDIS_LIFECYCLE_SHUTDOWN_TIMEOUT=3s
APP_REDIS_PUBSUB_BUFFER_CAPACITY=1024
APP_REDIS_SENTINEL_CREDENTIAL_REFERENCE=
APP_REDIS_SENTINEL_MASTER_NAME=
APP_REDIS_SENTINEL_NODES=app.redis.nodes
+35 -28
View File
@@ -22,25 +22,32 @@ Package root: `dev.caskeleton.adapter.outbound.cache`.
- Keep the legacy cache router isolated while consumers migrate to semantic ports.
- Reuse `adapter:outbound:support` for shared outbound concerns.
- Depend on `:adapter:outbound:redis-runtime` for the shared topology client, connection lifecycle,
low-level gateway and conditional Redis runtime composition used by the semantic adapters.
the eight `SemanticRedisCommands` and conditional Redis runtime composition used by the semantic
adapters.
- Keep the general-purpose typed SDK in the separate library leaf `:adapter:outbound:redis-sdk`
(see its `README.md`). This leaf does not depend on it in any configuration, tests included; the
SDK's tests and lanes live in that leaf.
## Redis runtime and optional typed SDK (`…cache.redis.sdk`)
## Redis runtime (`…cache.redis.runtime`) and optional typed SDK (`…cache.redis.sdk`)
The package namespace is shared across two registered Gradle leaves, but their deployment roles are
different.
Two registered leaves, two packages, one direction: the SDK builds on the runtime, the runtime knows
nothing of the SDK (`RedisRuntimePackageBoundaryTest` in the runtime holds that direction).
- `:adapter:outbound:redis-runtime` is production substrate: settings binding, credential
resolution, topology clients, `RedisRuntimeOwner`, the low-level command gateway and health.
`cache-redis` depends on this leaf.
- `:adapter:outbound:redis-sdk` owns the optional general-purpose typed API, command catalog/policy,
operation budgets, command guard, raw/admin surfaces, programmability and extensions.
`cache-redis` does **not** depend on it, in production or in tests.
- The semantic cache/idempotency/rate-limit/lease/realtime adapters in this leaf intentionally call
the runtime gateway through their own closed semantic programs/contracts. They do not pass through
`CommandPolicyGuard`, and `redis-command-policy.yml` does not control those semantic adapters.
- `:adapter:outbound:redis-runtime` is production substrate: `RedisRuntimeSettings` binding,
credential resolution, topology clients, `RedisRuntimeOwner` with the runtime's own lanes
(`RedisConnectionKind.REGULAR`, `SCRIPT`), `SemanticRedisCommands` (the eight commands this leaf
and the health contributor send) and health. `cache-redis` depends on this leaf.
- `:adapter:outbound:redis-sdk` owns the optional general-purpose typed API: `RedisCommandGateway`
(extends `SemanticRedisCommands`), command catalog/policy, operation budgets, command guard,
raw/admin surfaces, programmability and extensions — and its own lanes (`RedisSdkLane`: blocking,
transaction, admin) and admin account, which a service contributes to the runtime as
`RedisLaneContribution`/`RedisAccountContribution` beans (`RedisSdkComposition`). `cache-redis`
does **not** depend on it, in production or in tests.
- The semantic cache/idempotency/rate-limit/lease adapters in this leaf send the runtime's
`SemanticRedisCommands` through their own closed semantic programs (`RegisteredLuaScript`). They
do not pass through `CommandPolicyGuard`, and `redis-command-policy.yml` does not control them.
- Which roles need Redis for correctness is this leaf's `RedisCorrectnessRoleSelectors`, registered
in `META-INF/spring.factories` as the runtime's `RedisCorrectnessRequirement`.
The typed SDK described in
`docs/superpowers/specs/2026-08-07-redis-wrapper-typed-api-design.md` remains an optional library
@@ -86,9 +93,9 @@ in `docs/superpowers/plans/2026-08-07-redis-wrapper-typed-api-status.md`.
only a pre-filter — and all of them build commands through `ExtensionCommandRunner` so the guard
sees their keys. Search is the exception that proves it: an index is not a key, so its name is
namespaced by `LettuceRedisSearchOperations` itself.
- `RedisSdkModuleBoundaryTest` (in `redis-sdk`) scans both `redis-runtime` and `redis-sdk` source
roots and enforces the internal package graph, driver containment, the absence of an arbitrary string
command surface, and the designed module list.
- `RedisSdkModuleBoundaryTest` (in `redis-sdk`) scans the `redis-sdk` source root and enforces the
internal package graph, driver containment, the absence of an arbitrary string command surface,
and the designed module list.
- Decisions that must not be changed without revisiting the design: no unbounded `entries`,
`members`, `rangeAll`, or `keys`; no optional R2 permit or budget; no arbitrary command string
overload; no automatic retry of a non-idempotent write after a timeout; no real key in a metric or
@@ -113,9 +120,9 @@ in `docs/superpowers/plans/2026-08-07-redis-wrapper-typed-api-status.md`.
## Tests
Focused tests drive the semantic adapters against the in-memory gateway from
`testFixtures(project(':adapter:outbound:redis-runtime'))` (`InMemoryGatewayAccess`), the one fake
of `RedisCommandGateway`. R1/R2 promotion requires a separate real Redis service lane; it may never
Focused tests drive the semantic adapters against `InMemorySemanticRedisCommands` from
`testFixtures(project(':adapter:outbound:redis-runtime'))`, the one fake of `SemanticRedisCommands`,
served through `StubRedisRuntimeClient`. R1/R2 promotion requires a separate real Redis service lane; it may never
be silently skipped when selected.
`redisTopologyTest` is the only real-server lane, declared through `ca.redis-topology-lane`. This
@@ -137,7 +144,7 @@ containing the same text satisfied it. A hand-maintained per-mode floor on the e
## Composition
`RedisSdkAutoConfiguration` now belongs to `:adapter:outbound:redis-runtime`. It is the only
`RedisRuntimeAutoConfiguration` now belongs to `:adapter:outbound:redis-runtime`. It is the only
place Redis settings and the shared runtime substrate come into existence, and it exists only while
`app.redis.enabled` (env `APP_REDIS_ENABLED`, default `true` — the module is on when present) is
true. It builds the topology client, connection owner and health contributors; `RedisCapabilityConfig`
@@ -153,19 +160,19 @@ Every capability renders its keys under the one namespace from `app.redis.namesp
prefix tokens: four capabilities each joining two free-form strings produced four different key
shapes, and the deployment's ACL pattern matched none of them.
Lanes authenticate as different accounts. `RedisConnectionKind.credentialRole()` maps the lane to a
`RedisCredentialRole`, and the topology factory builds one client per *configured* role — so a
single-account deployment still gets exactly one client and one event loop. The `SCRIPT` lane is
Lanes authenticate as different accounts. `RedisLane.account()` names the lane's `RedisAccount`,
and the topology factory builds one client per *configured* account — so a single-account
deployment still gets exactly one client and one event loop. The `SCRIPT` lane is
the reason it exists: `SCRIPT LOAD` and `EVALSHA` belong to the advanced account, so the account
that reads a cache entry cannot execute a script.
A Cluster transaction runs on one node, so `RedisTransactionRunner` derives a routing key from the
watched keys (or an explicit `RedisSlotTag`) and pins the `TRANSACTION` lane to the node that owns
that slot. Routed leases are never pooled: a pooled connection is pinned to the previous caller's
A Cluster transaction runs on one node, so the SDK's `RedisTransactionRunner` derives a routing key
from the watched keys (or an explicit `RedisSlotTag`) and borrows `RedisSdkLane.TRANSACTION`, which
is pinned to its key's owner, on the node that owns that slot. Routed leases are never pooled: a pooled connection is pinned to the previous caller's
node.
`RedisSdkSettings`
must never carry a class-level `@ConfigurationProperties`: `RedisSdkAutoConfiguration` binds it, so
`RedisRuntimeSettings`
must never carry a class-level `@ConfigurationProperties`: `RedisRuntimeAutoConfiguration` binds it, so
`APP_REDIS_ENABLED=false` binds no Redis configuration at all. A properties scan that reached this
package would bind it regardless (bootstrap's `@ConfigurationPropertiesScan` lists only
`dev.caskeleton.bootstrap.*` packages). Role selectors (cache binding, session auth-mode, idempotency/lease/rate-limit provider)
+10 -6
View File
@@ -4,15 +4,17 @@ This module is the **semantic Redis capability adapter**, not a general Redis SD
The Redis implementation is deliberately split into three Gradle leaves:
- `:adapter:outbound:redis-runtime` — shipped connection/topology/settings/gateway substrate.
- `:adapter:outbound:redis-runtime` (`dev.caskeleton.adapter.outbound.cache.redis.runtime`) —
shipped connection/topology/settings substrate: `RedisRuntimeSettings`, the lane owner, and the
eight `SemanticRedisCommands` this module sends. It knows nothing of the typed SDK.
- `:adapter:outbound:cache-redis` — shipped application-facing cache, rate-limit, lease and
idempotency adapters.
- `:adapter:outbound:redis-sdk` — optional typed/general-purpose SDK. It is not on the default
application runtime graph.
The default application therefore does not acquire the optional SDK's command policy merely by
selecting a semantic Redis capability. Semantic adapters call the runtime gateway directly and own
their own correctness rules.
selecting a semantic Redis capability. Semantic adapters call the runtime's `SemanticRedisCommands`
directly and own their own correctness rules.
## Using it as a capability module — what it provides, the one line, the env keys
@@ -29,12 +31,14 @@ runtimeOnly project(':adapter:outbound:cache-redis') // brings :adapter:outbou
- the port implementations the role selectors ask for — `CacheRegionPort` (cache),
`EdgeRateLimitPort` (rate limit), `DistributedLeasePort` (lease), `IdempotencyStorePort`
(idempotency; the application builds the executor over it);
- `RedisCapabilityConfig` (`AutoConfiguration.imports`, after `RedisSdkAutoConfiguration`). With
`APP_REDIS_ENABLED=false` neither it nor redis-runtime's `RedisSdkAutoConfiguration` contributes a
- `RedisCapabilityConfig` (`AutoConfiguration.imports`, after `RedisRuntimeAutoConfiguration`). With
`APP_REDIS_ENABLED=false` neither it nor redis-runtime's `RedisRuntimeAutoConfiguration` contributes a
bean — no settings, client, connection, thread or health contributor. The module pulls no Spring
Data Redis, so there is no Boot Redis auto-configuration to exclude;
- the readiness contribution `RedisReadinessGroupPostProcessor` (this module's `spring.factories`):
`redisRequired` joins the readiness group only when a correctness role selects Redis;
`redisRequired` joins the readiness group only when a correctness role selects Redis. Which roles
those are is this module's `RedisCorrectnessRoleSelectors`, registered in the same file as the
runtime's `RedisCorrectnessRequirement` — the runtime asks, it does not list selectors;
- the shipped settings `config/module-defaults/cache-redis.yml` — `app.redis.enabled`,
`app.rate-limit.*`, and the Redis parts of `ca-skeleton.capabilities.*` (cache, lease, rate-limit,
the Redis idempotency store's tuning). The support leaf's `ModuleDefaultsEnvironmentPostProcessor`
@@ -18,6 +18,8 @@ dependencies {
// The in-memory gateway and the topology endpoint the semantic adapter tests run against.
testImplementation testFixtures(project(':adapter:outbound:redis-runtime'))
// The lease port's ownership contract, which the Redis adapter runs like the in-memory fake.
testImplementation testFixtures(project(':application-core'))
// RedisReadinessGroupPostProcessorTest boots a real actuator health context: the readiness group
// and its membership validation are what the post-processor exists to keep bootable.
testImplementation 'org.springframework.boot:spring-boot-starter-actuator'
@@ -49,6 +51,8 @@ dependencies {
// validation, tag selection, TLS mapping and no-skip enforcement. The leaf names the classes each
// of its lanes exists to run. Sentinel and TLS are qualified by redis-runtime and redis-sdk.
redisTopologyLane {
requiredClasses 'standalone', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest'
requiredClasses 'cluster', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest'
requiredClasses 'standalone', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest',
'LiveRedisDistributedLeaseContractTest'
requiredClasses 'cluster', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest',
'LiveRedisDistributedLeaseContractTest'
}
@@ -0,0 +1,179 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
import java.util.function.BiFunction;
/**
* One Lua program the semantic adapters run by digest: load once, {@code EVALSHA} after, and load
* again exactly once when the server says it no longer has it.
*
* <p>A server forgets its scripts on restart, on {@code SCRIPT FLUSH}, and on failover to a replica
* that never saw the load. The only signal is a {@code NOSCRIPT} reply, and it does not always
* arrive as Lettuce's {@code RedisNoScriptException}: through some proxies and wrapped driver paths
* it is a plain command failure whose message starts with {@code NOSCRIPT}. Four hand-written
* copies of this helper disagreed about that — one checked the message, three only the type — so a
* lease, a rate limit or an idempotency claim failed on a reply the cache recovered from.
*
* <p>The reply decoding the three array-returning programs share lives here too ({@link #number},
* {@link #text}): a Lua integer arrives as a {@code Long}, a status or a string as bytes, and each
* program used to carry its own copy of the conversion.
*/
public final class RegisteredLuaScript {
private final byte[] source;
private final AtomicReference<String> digest = new AtomicReference<>();
/**
* Creates the program.
*
* @param source the Lua source, which never changes for the life of this object
*/
public RegisteredLuaScript(String source) {
this.source =
Objects.requireNonNull(source, "source must be non-null").getBytes(StandardCharsets.UTF_8);
}
/**
* Runs the program on one key and returns its array reply.
*
* @param commands the commands of a borrowed SCRIPT lease
* @param key the single key the program touches
* @param arguments the program's arguments
* @return the reply values
*/
public CompletionStage<List<Object>> evaluateForList(
SemanticRedisCommands commands, byte[] key, List<byte[]> arguments) {
return run(
commands, (loaded, server) -> server.evaluateRegisteredForList(loaded, key, arguments));
}
/**
* Runs the program on one key and returns its integer reply.
*
* @param commands the commands of a borrowed lease
* @param key the single key the program touches
* @param arguments the program's arguments
* @return the integer reply
*/
public CompletionStage<Long> evaluateForLong(
SemanticRedisCommands commands, byte[] key, List<byte[]> arguments) {
return run(
commands, (loaded, server) -> server.evaluateRegisteredForLong(loaded, key, arguments));
}
private <R> CompletionStage<R> run(
SemanticRedisCommands commands,
BiFunction<String, SemanticRedisCommands, CompletionStage<R>> evaluation) {
return digest(commands)
.thenCompose(loaded -> evaluation.apply(loaded, commands))
.handle(
(reply, failure) -> {
if (failure == null) {
return CompletableFuture.completedFuture(reply);
}
if (!scriptMissing(failure)) {
return CompletableFuture.<R>failedFuture(failure);
}
// Once. A server that forgets a script it was just given is not going to remember it
// on the third try, and a loop here would hide that.
digest.set(null);
return digest(commands).thenCompose(loaded -> evaluation.apply(loaded, commands));
})
.thenCompose(stage -> stage);
}
private CompletionStage<String> digest(SemanticRedisCommands commands) {
String cached = digest.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return commands
.loadScript(source)
.thenApply(
loaded -> {
digest.set(loaded);
return loaded;
});
}
/**
* Reports whether a failure is the server saying it does not have the script.
*
* @param failure the failure, possibly wrapped by the future that carried it
* @return {@code true} for a {@code NOSCRIPT} reply, typed or not
*/
static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException
|| (cause.getMessage() != null && cause.getMessage().startsWith("NOSCRIPT"));
}
/**
* Reads an integer element of a program's reply.
*
* @param value the element: a {@code Long}, or bytes carrying digits
* @return the number, {@code 0} for an empty element
* @throws IllegalStateException when the element is neither
*/
public static long number(Object value) {
if (value instanceof Number n) {
return n.longValue();
}
if (value instanceof byte[] bytes) {
String text = new String(bytes, StandardCharsets.UTF_8).strip();
return text.isEmpty() ? 0L : Long.parseLong(text);
}
throw new IllegalStateException(
"a registered program answered with an unexpected value type: "
+ (value == null ? "null" : value.getClass().getName()));
}
/**
* Reads a string element of a program's reply.
*
* @param value the element: bytes, or anything else printed as-is
* @return the text, empty for {@code null}
*/
public static String text(Object value) {
if (value instanceof byte[] bytes) {
return new String(bytes, StandardCharsets.UTF_8);
}
return value == null ? "" : String.valueOf(value);
}
/**
* Checks that a program's array reply has the shape it promises.
*
* @param reply the reply
* @param size the number of elements the program returns
* @param program the program's name, for the failure message
* @return the reply
* @throws IllegalStateException when the reply is absent or short
*/
public static List<Object> requireShape(List<Object> reply, int size, String program) {
if (reply == null || reply.size() < size) {
throw new IllegalStateException(
"the "
+ program
+ " program answered with "
+ (reply == null ? "nothing" : reply.size() + " values")
+ "; "
+ size
+ " were expected");
}
return reply;
}
}
@@ -0,0 +1,168 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLaneUnavailableException;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import java.time.Duration;
import java.util.Objects;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;
/**
* One semantic adapter call on Redis: borrow a lane, send, wait a bounded time, and turn every way
* that can fail into one of two answers the caller can act on.
*
* <p>The two answers are the whole point, and they are not "success" and "failure":
*
* <ul>
* <li><b>not sent</b> — nothing can have happened: the runtime refused a lease before any command
* existed, or the call failed before it {@linkplain Session#markSent() marked} the write as
* handed to the driver. The caller may treat the operation as unavailable and retry it.
* <li><b>unknown</b> — the command may have run. A timeout, a lost reply, an interrupted wait:
* the caller must not be told "failed", because retrying an effect that already landed is how
* it happens twice.
* </ul>
*
* <p>Sixteen hand-written copies of this frame — borrow, {@code .get(timeout)}, catch {@code
* InterruptedException}, catch the runtime's refusal, catch everything else — lived in the four
* adapters, and the difference between their two answers was re-derived in each. Every failure is
* reported to {@link RedisSemanticFailureLogger} except an interrupt, which is the caller's own
* doing.
*/
public final class SemanticRedisCall {
private final RedisRuntimeOwner owner;
private final RedisLane lane;
private final Duration timeout;
private final String capability;
/**
* Creates the call frame for one capability.
*
* @param owner the runtime owner leases come from
* @param lane the lane this capability's calls run on
* @param timeout the ceiling on each awaited reply
* @param capability the capability name the failure log carries
*/
public SemanticRedisCall(
RedisRuntimeOwner owner, RedisLane lane, Duration timeout, String capability) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.lane = Objects.requireNonNull(lane, "lane must be non-null");
this.timeout = Objects.requireNonNull(timeout, "timeout must be non-null");
this.capability = Objects.requireNonNull(capability, "capability must be non-null");
}
/**
* Runs a call whose command may take effect as soon as it is sent.
*
* <p>For the registered programs: the call counts as sent from the start, so anything but the
* runtime's own refusal — a connection that could not be opened included — is an unknown outcome.
* A caller told "unavailable" after a failure it cannot rule out having reached the server would
* retry an effect that may already have landed.
*
* @param operation the semantic operation, for the failure log
* @param body what to send, and how to read the reply
* @param notSent the answer when nothing can have happened
* @param unknown the answer when the command may have run
* @param <R> the answer type
* @return the body's answer, or one of the two failure answers
*/
public <R> R effect(String operation, Body<R> body, Supplier<R> notSent, Supplier<R> unknown) {
return call(operation, body, notSent, unknown, true);
}
/**
* Runs a call that decides for itself when its effect was handed to the driver.
*
* @param operation the semantic operation, for the failure log
* @param body what to send, and how to read the reply; calls {@link Session#markSent()} before
* the command whose loss would leave the outcome unknown
* @param notSent the answer when nothing can have happened
* @param unknown the answer when the command may have run
* @param <R> the answer type
* @return the body's answer, or one of the two failure answers
*/
public <R> R run(String operation, Body<R> body, Supplier<R> notSent, Supplier<R> unknown) {
return call(operation, body, notSent, unknown, false);
}
private <R> R call(
String operation,
Body<R> body,
Supplier<R> notSent,
Supplier<R> unknown,
boolean sentFromStart) {
Session session = new Session();
session.sent = sentFromStart;
try (RedisLease lease = owner.borrow(lane)) {
session.lease = lease;
return body.apply(session);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return session.sent ? unknown.get() : notSent.get();
} catch (RedisLaneUnavailableException refused) {
RedisSemanticFailureLogger.report(capability, operation, refused);
return notSent.get();
} catch (Exception failure) {
RedisSemanticFailureLogger.report(capability, operation, failure);
return session.sent ? unknown.get() : notSent.get();
}
}
/** What a call sends, given the borrowed connection. */
@FunctionalInterface
public interface Body<R> {
/**
* Sends and reads.
*
* @param session the borrowed connection and its bounded wait
* @return the answer
* @throws Exception any failure, classified by the frame
*/
R apply(Session session) throws Exception;
}
/** The borrowed connection, for the duration of one call. */
public final class Session {
private RedisLease lease;
private boolean sent;
private Session() {}
/**
* Returns the commands of the borrowed connection.
*
* @return the commands
*/
public SemanticRedisCommands commands() {
return lease.commands();
}
/**
* Waits for a reply, no longer than the call's timeout.
*
* @param reply the pending reply
* @param <V> the reply type
* @return the reply
* @throws Exception the reply's failure, a timeout, or an interrupt
*/
public <V> V await(CompletionStage<V> reply) throws Exception {
return reply.toCompletableFuture().get(timeout.toNanos(), TimeUnit.NANOSECONDS);
}
/**
* Records that the command whose loss leaves the outcome unknown is about to be sent.
*
* <p>A failure before this — a refused lease, a failed read that precedes the write — wrote
* nothing.
*/
public void markSent() {
sent = true;
}
}
}
@@ -1,13 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.cache;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/** Atomic cache mutations that cannot be expressed as one ordinary Redis command. */
final class CacheScripts {
@@ -25,10 +22,11 @@ final class CacheScripts {
return 1
""";
private final AtomicReference<String> replaceIfObservedDigest = new AtomicReference<>();
private final RegisteredLuaScript replaceIfObserved =
new RegisteredLuaScript(REPLACE_IF_OBSERVED);
CompletionStage<Boolean> replaceIfObserved(
RedisCommandGateway gateway,
SemanticRedisCommands commands,
byte[] key,
String observation,
byte[] replacement,
@@ -38,51 +36,8 @@ final class CacheScripts {
observation.getBytes(StandardCharsets.US_ASCII),
replacement,
Long.toString(ttlMillis).getBytes(StandardCharsets.US_ASCII));
return digest(gateway)
.thenCompose(
loaded ->
gateway
.evaluateRegisteredForLong(loaded, key, arguments)
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, key, arguments, failure))
.thenCompose(stage -> stage))
return replaceIfObserved
.evaluateForLong(commands, key, arguments)
.thenApply(applied -> applied != null && applied == 1L);
}
private CompletionStage<String> digest(RedisCommandGateway gateway) {
String cached = replaceIfObservedDigest.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return gateway
.loadScript(REPLACE_IF_OBSERVED.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
replaceIfObservedDigest.set(loaded);
return loaded;
});
}
private CompletionStage<Long> reload(
RedisCommandGateway gateway, byte[] key, List<byte[]> arguments, Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
replaceIfObservedDigest.set(null);
return digest(gateway)
.thenCompose(loaded -> gateway.evaluateRegisteredForLong(loaded, key, arguments));
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException
|| (cause.getMessage() != null && cause.getMessage().startsWith("NOSCRIPT"));
}
}
@@ -1,11 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.cache;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.cache.AuthoritativeAbsence;
import dev.caskeleton.application.cache.CacheInvalidationOutcome;
import dev.caskeleton.application.cache.CacheLookup;
@@ -19,7 +18,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
import java.util.function.Function;
/**
@@ -54,7 +52,7 @@ import java.util.function.Function;
*/
public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V> {
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final CacheKeys keys;
@@ -72,8 +70,6 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
private final Duration negativeTtl;
private final Duration commandTimeout;
private final CacheScripts scripts = new CacheScripts();
/**
@@ -101,7 +97,12 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
Duration hardTtl,
Duration negativeTtl,
Duration commandTimeout) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.REGULAR,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"cache");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.keyDigest = Objects.requireNonNull(keyDigest, "key digest must be non-null");
this.encoder = Objects.requireNonNull(encoder, "encoder must be non-null");
@@ -110,8 +111,6 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
this.softTtl = Objects.requireNonNull(softTtl, "soft TTL must be non-null");
this.hardTtl = Objects.requireNonNull(hardTtl, "hard TTL must be non-null");
this.negativeTtl = Objects.requireNonNull(negativeTtl, "negative TTL must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
if (softTtl.compareTo(hardTtl) > 0) {
throw new IllegalArgumentException(
"the soft TTL must not exceed the hard TTL: an entry cannot stop being fresh after it has"
@@ -123,27 +122,23 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
public CacheLookup<V> lookup(K key) {
Objects.requireNonNull(key, "key must be non-null");
Instant now = clock.instant();
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
resolveGeneration(lease, now);
byte[] stored =
lease
.gateway()
.get(keys.entryKey(keyDigest.apply(key)))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (stored == null) {
return new CacheLookup.Miss<>(
CacheLookup.MissReason.ABSENT, CacheWriteCondition.unavailable());
}
return interpret(stored, now);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return unavailable();
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "lookup", failure);
// Degraded, not broken. The caller loads from the source and carries on.
return unavailable();
}
// A read changed nothing, whether or not it reached the server: degraded, not broken. The
// caller
// loads from the source and carries on.
return call.run(
"lookup",
session -> {
resolveGeneration(session, now);
byte[] stored =
session.await(session.commands().get(keys.entryKey(keyDigest.apply(key))));
if (stored == null) {
return new CacheLookup.Miss<>(
CacheLookup.MissReason.ABSENT, CacheWriteCondition.unavailable());
}
return interpret(stored, now);
},
this::unavailable,
this::unavailable);
}
private CacheLookup<V> interpret(byte[] stored, Instant now) {
@@ -223,98 +218,70 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
Instant now = clock.instant();
Duration effectiveSoft = softTtl.compareTo(ttl) > 0 ? ttl : softTtl;
byte[] physicalKey = keys.entryKey(keyDigest.apply(key));
// Whether the write command itself was handed to the driver. A failure before that point —
// lane refusal, connection, the generation read — wrote nothing.
boolean sent = false;
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
resolveGeneration(lease, now);
CacheEnvelope envelope =
new CacheEnvelope(
CacheEnvelope.CURRENT_SCHEMA_VERSION,
metadata.sourceRevision(),
keys.generation(),
now.plus(effectiveSoft),
now.plus(ttl),
absence,
payload);
Boolean applied;
sent = true;
if (metadata.intent() == CacheRecordIntent.ONLY_IF_OBSERVED) {
// Compare and replacement are one server-side execution. A GET followed by SET would let a
// concurrent writer land between them and then be overwritten by this stale source load.
applied =
scripts
.replaceIfObserved(
lease.gateway(),
physicalKey,
metadata.observedToken().value(),
envelope.encode(),
ttl.toMillis())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
} else {
applied =
lease
.gateway()
.set(
physicalKey,
envelope.encode(),
presenceOf(metadata.intent()),
// The physical TTL is the hard expiry and nothing else.
new dev.caskeleton.adapter.outbound.cache.redis.sdk.api.operations.Expiration
.After(ttl))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
}
return Boolean.TRUE.equals(applied)
? CacheRecordOutcome.RECORDED
: CacheRecordOutcome.NOT_RECORDED_CONDITION;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return sent ? CacheRecordOutcome.INDETERMINATE : CacheRecordOutcome.DEGRADED_UNAVAILABLE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "record", failure);
return sent ? CacheRecordOutcome.INDETERMINATE : CacheRecordOutcome.DEGRADED_UNAVAILABLE;
}
// The write is marked sent only when the write command itself is handed to the driver. A
// failure before that point — lane refusal, connection, the generation read — wrote nothing.
return call.run(
"record",
session -> {
resolveGeneration(session, now);
CacheEnvelope envelope =
new CacheEnvelope(
CacheEnvelope.CURRENT_SCHEMA_VERSION,
metadata.sourceRevision(),
keys.generation(),
now.plus(effectiveSoft),
now.plus(ttl),
absence,
payload);
session.markSent();
Boolean applied =
metadata.intent() == CacheRecordIntent.ONLY_IF_OBSERVED
// Compare and replacement are one server-side execution. A GET followed by SET
// would let a concurrent writer land between them and then be overwritten by
// this stale source load.
? session.await(
scripts.replaceIfObserved(
session.commands(),
physicalKey,
metadata.observedToken().value(),
envelope.encode(),
ttl.toMillis()))
// The physical TTL is the hard expiry and nothing else.
: session.await(
session
.commands()
.set(physicalKey, envelope.encode(), presenceOf(metadata.intent()), ttl));
return Boolean.TRUE.equals(applied)
? CacheRecordOutcome.RECORDED
: CacheRecordOutcome.NOT_RECORDED_CONDITION;
},
() -> CacheRecordOutcome.DEGRADED_UNAVAILABLE,
() -> CacheRecordOutcome.INDETERMINATE);
}
private static dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence
private static dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence
presenceOf(CacheRecordIntent intent) {
return intent == CacheRecordIntent.ONLY_IF_ABSENT
? dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence.IF_ABSENT
: dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence.ALWAYS;
? dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence.IF_ABSENT
: dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence.ALWAYS;
}
@Override
public CacheInvalidationOutcome invalidate(K key) {
Objects.requireNonNull(key, "key must be non-null");
boolean sent = false;
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
byte[] physicalKey = keys.entryKey(keyDigest.apply(key));
sent = true;
byte[] removed =
lease
.gateway()
.getAndDelete(physicalKey)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return removed == null
? CacheInvalidationOutcome.ALREADY_ABSENT
: CacheInvalidationOutcome.INVALIDATED;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return invalidationFailure(sent);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "invalidate", failure);
return invalidationFailure(sent);
}
}
// A lost reply to a sent delete or generation bump may have applied it.
private static CacheInvalidationOutcome invalidationFailure(boolean sent) {
return sent
? CacheInvalidationOutcome.INDETERMINATE
: CacheInvalidationOutcome.DEGRADED_UNAVAILABLE;
return call.run(
"invalidate",
session -> {
byte[] physicalKey = keys.entryKey(keyDigest.apply(key));
session.markSent();
byte[] removed = session.await(session.commands().getAndDelete(physicalKey));
return removed == null
? CacheInvalidationOutcome.ALREADY_ABSENT
: CacheInvalidationOutcome.INVALIDATED;
},
() -> CacheInvalidationOutcome.DEGRADED_UNAVAILABLE,
// A lost reply to a sent delete may have applied it.
() -> CacheInvalidationOutcome.INDETERMINATE);
}
@Override
@@ -323,24 +290,17 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
// a server that is answering everything else at the same time, and the SDK blocks KEYS for
// exactly that reason. Bumping the generation makes every older entry fail the generation
// check on read and expire on its own schedule.
boolean sent = false;
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
sent = true;
Long generation =
lease
.gateway()
.incrementBy(keys.generationKey(), 1)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
keys.observeGeneration(generation, clock.instant());
return CacheInvalidationOutcome.INVALIDATED;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return invalidationFailure(sent);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "invalidate-region", failure);
return invalidationFailure(sent);
}
return call.run(
"invalidate-region",
session -> {
session.markSent();
Long generation = session.await(session.commands().incrementBy(keys.generationKey(), 1));
keys.observeGeneration(generation, clock.instant());
return CacheInvalidationOutcome.INVALIDATED;
},
() -> CacheInvalidationOutcome.DEGRADED_UNAVAILABLE,
// A lost reply to a sent generation bump may have applied it.
() -> CacheInvalidationOutcome.INDETERMINATE);
}
/**
@@ -352,16 +312,11 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
* the current value and creates the counter at 0 if it is absent, which is both idempotent and
* the same operation on every instance.
*/
private void resolveGeneration(RedisLease lease, Instant now) throws Exception {
private void resolveGeneration(SemanticRedisCall.Session session, Instant now) throws Exception {
if (!keys.shouldRefreshGeneration(now, softTtl)) {
return;
}
Long current =
lease
.gateway()
.incrementBy(keys.generationKey(), 0)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
Long current = session.await(session.commands().incrementBy(keys.generationKey(), 0));
keys.observeGeneration(current == null ? 0L : current, now);
}
@@ -1,8 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.cache.RedisCacheRegionAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.cache.CacheRegionPort;
import dev.caskeleton.application.outbound.SecretSourcePort;
import java.time.Clock;
@@ -24,7 +24,7 @@ class RedisCacheConfig {
* The semantic cache region for the default binding.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param secretSource resolves the key-digest material
* @param clock the clock expiries are measured against
@@ -36,18 +36,18 @@ class RedisCacheConfig {
havingValue = "redis")
CacheRegionPort<String, byte[]> redisDefaultCacheRegion(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
SecretSourcePort secretSource,
Clock clock) {
RedisCapabilitySettings.Cache cache = capabilities.getCache();
cache.validate();
RedisKeys.KeyDigest digest =
RedisKeys.KeyDigest.of(secretSource, cache.getKeyHmacSecretReference(), "cache", sdk);
RedisKeys.KeyDigest.of(secretSource, cache.getKeyHmacSecretReference(), "cache", redis);
return new RedisCacheRegionAdapter<>(
owner,
new RedisCacheRegionAdapter.CacheKeys(
RedisKeys.namespaceOf(sdk), cache.getSemanticRegion(), cache.getKeyVersion()),
RedisKeys.namespaceOf(redis), cache.getSemanticRegion(), cache.getKeyVersion()),
digest::of,
value -> value,
stored -> stored,
@@ -1,8 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.outbound.SecretSourcePort;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
@@ -26,16 +26,17 @@ import org.springframework.context.annotation.Import;
* itself. With the switch off this module contributes no bean at all.
*
* <p>This class is the composition point only: it holds the switch, binds the settings once,
* bridges the secret backend into the SDK, and imports one configuration per capability. It used to
* hold all four capabilities plus rate-limit policy compilation and the key digest — 376 lines, in
* a leaf whose Notification platform had already been split into nine focused configurations. The
* decomposition pattern existed; this was simply where it had not been applied (BOOT-007).
* bridges the secret backend into the Redis runtime, and imports one configuration per capability.
* It used to hold all four capabilities plus rate-limit policy compilation and the key digest — 376
* lines, in a leaf whose Notification platform had already been split into nine focused
* configurations. The decomposition pattern existed; this was simply where it had not been applied
* (BOOT-007).
*
* <p>The namespace comes from {@code app.redis.namespace} for every capability. That is the change
* that makes the ACL pattern meaningful: one prefix, {@code {environment}:{service}:{domain}}, that
* the deployment's {@code ~} pattern can actually fence.
*/
@AutoConfiguration(after = RedisSdkAutoConfiguration.class)
@AutoConfiguration(after = RedisRuntimeAutoConfiguration.class)
@EnableConfigurationProperties(RedisCapabilitySettings.class)
// The global switch, not a role selector. A role selector says which capability composes; it
// never says Redis exists.
@@ -52,29 +53,40 @@ import org.springframework.context.annotation.Import;
public class RedisCapabilityConfig {
/**
* Bridges the deployment's configured secret backend into the Redis SDK.
* Bridges the deployment's configured secret backend into the Redis runtime.
*
* <p>Without it the SDK falls back to reading the process environment directly, which quietly
* <p>Without it the runtime falls back to reading the process environment directly, which quietly
* bypasses whichever backend {@code ca-skeleton.secret-source.strategy} selected — so a
* deployment using a secret manager would resolve its Redis credential from an environment
* variable that is not supposed to hold it.
*
* @param secretSource the configured backend
* @return the SDK's view of it
* @return the runtime's view of it
*/
@Bean
RedisSdkAutoConfiguration.RedisSecretSource redisSdkSecretSource(SecretSourcePort secretSource) {
RedisRuntimeAutoConfiguration.RedisSecretSource redisSecretSource(SecretSourcePort secretSource) {
return secretSource::resolve;
}
/**
* The production secrets of the Redis roles this deployment selected, for the composition root's
* secret guard — which checks them without knowing which Redis roles exist.
*
* @return the contribution
*/
@Bean
RedisProductionSecrets redisProductionSecrets() {
return new RedisProductionSecrets();
}
@Bean
@ConditionalOnMissingBean(RedisSemanticScriptAclProbe.class)
RedisSemanticScriptAclProbe redisSemanticScriptAclProbe(
RedisRuntimeOwner owner, RedisCapabilitySettings capabilities, RedisSdkSettings sdk) {
RedisRuntimeOwner owner, RedisCapabilitySettings capabilities, RedisRuntimeSettings redis) {
byte[] probeKey =
(RedisKeys.namespaceOf(sdk).prefix() + ":probe:{semantic-script}:acl")
(RedisKeys.namespaceOf(redis).prefix() + ":probe:{semantic-script}:acl")
.getBytes(java.nio.charset.StandardCharsets.UTF_8);
return new RedisSemanticScriptAclProbe(
owner, capabilities, probeKey, sdk.getTimeout().getScript());
owner, capabilities, probeKey, redis.getTimeout().getScript());
}
}
@@ -0,0 +1,95 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRequirement;
import java.util.List;
import org.springframework.core.env.Environment;
/**
* The Redis roles, their selectors, and what each one requires.
*
* <p>Session, idempotency, rate limiting and leases produce a wrong answer when Redis is gone, not
* a slow one: a replayed payment, an unenforced quota, two holders of a lease. A deployment that
* selected any of them gates its readiness on Redis. The cache is a role too, but not a correctness
* one — its outage is degradation — so it needs its production secrets and nothing else.
*
* <p>This table used to be two: the selectors in {@code redis-runtime}, which therefore hard-coded
* selector keys of a module built on top of it, and a prefix switch in the composition root's
* secret guard. It is one now, here, with the capabilities it describes. The runtime is told only
* whether Redis is required ({@link RedisCorrectnessRequirement}, {@code
* META-INF/spring.factories}), and the secret guard only which secrets ({@link
* RedisProductionSecrets}).
*/
public final class RedisCorrectnessRoleSelectors implements RedisCorrectnessRequirement {
/**
* One role.
*
* @param selector the property that selects the role's provider
* @param fallback the selector's value when the deployment set none
* @param selecting the value that selects Redis
* @param correctness whether serving without Redis would give wrong answers
* @param scripted whether the role runs registered programs on the SCRIPT lane
* @param productionSecrets the secrets the role needs under the {@code prod} profile
*/
record Role(
String selector,
String fallback,
String selecting,
boolean correctness,
boolean scripted,
List<String> productionSecrets) {
boolean selected(Environment environment) {
return selecting.equalsIgnoreCase(environment.getProperty(selector, fallback));
}
}
/** Every Redis role this module composes. */
static final List<Role> ROLES =
List.of(
new Role(
"ca-skeleton.capabilities.cache.bindings.default",
"disabled",
"redis",
false,
false,
List.of("APP_CACHE_REDIS_PASSWORD", "APP_CACHE_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.security.auth-mode",
"jwt",
"redis-session",
true,
false,
List.of("APP_SESSION_REDIS_PASSWORD", "APP_SESSION_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.capabilities.idempotency.provider",
"disabled",
"redis",
true,
true,
List.of("APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.capabilities.rate-limit.provider",
"disabled",
"redis",
true,
true,
List.of("APP_RATE_LIMIT_REDIS_PASSWORD", "APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.capabilities.lease.provider",
"disabled",
"redis",
true,
true,
List.of("APP_LEASE_REDIS_KEY_HMAC_SECRET")));
@Override
public boolean required(Environment environment) {
return ROLES.stream().anyMatch(role -> role.correctness() && role.selected(environment));
}
@Override
public boolean requiresScriptLane(Environment environment) {
return ROLES.stream().anyMatch(role -> role.scripted() && role.selected(environment));
}
}
@@ -2,8 +2,8 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.IdempotencyScripts;
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.RedisIdempotencyStoreAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import dev.caskeleton.application.idempotency.IdempotencyStorePort;
@@ -23,7 +23,7 @@ class RedisIdempotencyConfig {
* The owner-safe request-replay store.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param clock the clock lease deadlines are measured against
* @return the store port
@@ -34,7 +34,7 @@ class RedisIdempotencyConfig {
havingValue = "redis")
IdempotencyStorePort redisIdempotencyStore(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
Clock clock) {
RedisCapabilitySettings.Idempotency idempotency = capabilities.getIdempotency();
@@ -51,7 +51,7 @@ class RedisIdempotencyConfig {
return new RedisIdempotencyStoreAdapter(
owner,
new RedisIdempotencyStoreAdapter.IdempotencyKeys(
RedisKeys.namespaceOf(sdk), idempotency.getKeyVersion()),
RedisKeys.namespaceOf(redis), idempotency.getKeyVersion()),
new IdempotencyScripts(),
clock,
idempotency.getCommandTimeout());
@@ -1,7 +1,7 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import dev.caskeleton.application.outbound.SecretReference;
import dev.caskeleton.application.outbound.SecretSourcePort;
@@ -20,7 +20,7 @@ final class RedisKeys {
private RedisKeys() {}
/** The deployment's key namespace: {@code {environment}:{service}:{domain}}. */
static RedisNamespace namespaceOf(RedisSdkSettings settings) {
static RedisNamespace namespaceOf(RedisRuntimeSettings settings) {
return new RedisNamespace(
settings.getNamespace().getEnvironment(),
settings.getNamespace().getService(),
@@ -38,7 +38,10 @@ final class RedisKeys {
record KeyDigest(javax.crypto.Mac prototype) {
static KeyDigest of(
SecretSourcePort secretSource, String reference, String capability, RedisSdkSettings sdk) {
SecretSourcePort secretSource,
String reference,
String capability,
RedisRuntimeSettings redis) {
String name = secretName(reference, capability);
String material =
secretSource
@@ -61,11 +64,11 @@ final class RedisKeys {
// one-for-one onto the harder one.
(material
+ '|'
+ sdk.getNamespace().getEnvironment()
+ redis.getNamespace().getEnvironment()
+ ':'
+ sdk.getNamespace().getService()
+ redis.getNamespace().getService()
+ ':'
+ sdk.getNamespace().getDomain())
+ redis.getNamespace().getDomain())
.getBytes(StandardCharsets.UTF_8),
"HmacSHA256"));
return new KeyDigest(mac);
@@ -2,8 +2,8 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.lease.LeaseScripts;
import dev.caskeleton.adapter.outbound.cache.redis.lease.RedisDistributedLeaseAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.lease.DistributedLeasePort;
import java.time.Clock;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -18,7 +18,7 @@ class RedisLeaseConfig {
* The distributed lease port. Efficiency only — it never supplies fencing.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param clock the wall clock used for reporting instants
* @return the lease port
@@ -27,14 +27,14 @@ class RedisLeaseConfig {
@ConditionalOnProperty(name = "ca-skeleton.capabilities.lease.provider", havingValue = "redis")
DistributedLeasePort redisDistributedLeasePort(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
Clock clock) {
RedisCapabilitySettings.Lease lease = capabilities.getLease();
return new RedisDistributedLeaseAdapter(
owner,
new RedisDistributedLeaseAdapter.LeaseKeys(
RedisKeys.namespaceOf(sdk), lease.getKeyVersion()),
RedisKeys.namespaceOf(redis), lease.getKeyVersion()),
new LeaseScripts(),
clock,
System::nanoTime,
@@ -0,0 +1,24 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.support.startup.RequiredProductionSecrets;
import java.util.List;
import org.springframework.core.env.Environment;
/**
* The production secrets of the Redis roles this deployment selected.
*
* <p>A bean of this module's composition, so it exists only while {@code app.redis.enabled} is
* true: with Redis off nothing Redis-shaped is created, and demanding its credentials would fail a
* deployment over an adapter it never asked for. With Redis on, each selected role contributes its
* own secrets — a deployment that runs Redis for its cache owes nothing to the session store.
*/
public final class RedisProductionSecrets implements RequiredProductionSecrets {
@Override
public List<String> requiredSecrets(Environment environment) {
return RedisCorrectnessRoleSelectors.ROLES.stream()
.filter(role -> role.selected(environment))
.flatMap(role -> role.productionSecrets().stream())
.toList();
}
}
@@ -1,15 +1,15 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitKeys;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitScripts;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RedisEdgeRateLimitAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import dev.caskeleton.shared.ratelimit.EdgeRateLimitPort;
import dev.caskeleton.shared.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.shared.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Clock;
import java.time.Duration;
@@ -37,7 +37,7 @@ class RedisRateLimitConfig {
* The provider-neutral edge rate limiter, backed by Redis.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param clock the local clock used for caller deadlines and response reset instants
* @param environment where the HTTP boundary's default policy id is read from
@@ -49,7 +49,7 @@ class RedisRateLimitConfig {
havingValue = "redis")
EdgeRateLimitPort redisEdgeRateLimitPort(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
Clock clock,
Environment environment) {
@@ -60,7 +60,7 @@ class RedisRateLimitConfig {
String defaultPolicyId = environment.getProperty(DEFAULT_POLICY_ID, "api-default");
return new RedisEdgeRateLimitAdapter(
owner,
new RateLimitKeys(RedisKeys.namespaceOf(sdk), rateLimit.getKeyVersion()),
new RateLimitKeys(RedisKeys.namespaceOf(redis), rateLimit.getKeyVersion()),
policiesOf(rateLimit, defaultPolicyId),
new RateLimitScripts(),
clock,
@@ -1,6 +1,6 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.support.startup.ReadinessGroup;
import dev.caskeleton.adapter.outbound.support.startup.StartupOrder;
import org.springframework.boot.EnvironmentPostProcessor;
@@ -1,8 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
@@ -63,13 +63,13 @@ final class RedisSemanticScriptAclProbe implements SmartInitializingSingleton {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
String digest =
lease
.gateway()
.commands()
.loadScript(PROBE_SCRIPT)
.toCompletableFuture()
.get(timeout.toNanos(), TimeUnit.NANOSECONDS);
List<Object> reply =
lease
.gateway()
.commands()
.evaluateRegisteredForList(digest, probeKey, List.of())
.toCompletableFuture()
.get(timeout.toNanos(), TimeUnit.NANOSECONDS);
@@ -1,15 +1,11 @@
package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/**
* The idempotency record's state machine, one atomic program per transition.
@@ -186,122 +182,86 @@ public final class IdempotencyScripts {
mine .. '|' .. tostring(redis.call('PTTL', KEYS[1]))}
""";
private final Map<String, AtomicReference<String>> digests =
Map.of(
"claim", new AtomicReference<>(),
"transition", new AtomicReference<>(),
"release", new AtomicReference<>(),
"inspect", new AtomicReference<>());
private final RegisteredLuaScript claim = new RegisteredLuaScript(CLAIM);
private final RegisteredLuaScript transition = new RegisteredLuaScript(TRANSITION);
private final RegisteredLuaScript release = new RegisteredLuaScript(RELEASE);
private final RegisteredLuaScript inspect = new RegisteredLuaScript(INSPECT);
CompletionStage<Reply> claim(RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "claim", CLAIM, key, arguments);
CompletionStage<Reply> claim(SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(claim, commands, key, arguments);
}
CompletionStage<Reply> transition(
RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "transition", TRANSITION, key, arguments);
SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(transition, commands, key, arguments);
}
CompletionStage<Reply> release(RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "release", RELEASE, key, arguments);
CompletionStage<Reply> release(
SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(release, commands, key, arguments);
}
CompletionStage<Reply> inspect(RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "inspect", INSPECT, key, arguments);
CompletionStage<Reply> inspect(
SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(inspect, commands, key, arguments);
}
private CompletionStage<Reply> run(
RedisCommandGateway gateway, String name, String source, byte[] key, List<String> arguments) {
AtomicReference<String> cache = digests.get(name);
if (cache == null) {
throw new IllegalArgumentException("unknown idempotency script: " + name);
}
private static CompletionStage<Reply> run(
RegisteredLuaScript program,
SemanticRedisCommands commands,
byte[] key,
List<String> arguments) {
List<byte[]> encoded = new ArrayList<>(arguments.size());
for (String argument : arguments) {
encoded.add(argument.getBytes(StandardCharsets.UTF_8));
}
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, encoded))
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, source, cache, key, encoded, failure))
.thenCompose(stage -> stage)
.thenApply(IdempotencyScripts::replyOf);
return program.evaluateForList(commands, key, encoded).thenApply(Reply::of);
}
private CompletionStage<List<Object>> reload(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments,
Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
cache.set(null);
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments));
}
/**
* What a program answered, parsed once.
*
* <p>The transition verdicts and, for {@code INSPECT}, the record's state. The programs speak in
* strings; the adapter speaks in this enum, so a misspelt status is a compile error rather than a
* {@code default} branch that quietly turns it into "unavailable".
*/
enum ScriptStatus {
ACQUIRED,
REPLAYED_ACQUIRE,
TAKEN_OVER,
COMPLETED_REPLAY,
IN_PROGRESS,
RECOVERY_REQUIRED,
FINGERPRINT_MISMATCH,
OWNER_OPERATION_CONFLICT,
APPLIED,
ALREADY,
ABSENT,
NOT_OWNER,
OPERATION_CONFLICT,
WRONG_STATE,
CLAIMED,
EXECUTING,
COMPLETED,
FAILED_RETRYABLE,
ABANDONED,
/** A status this adapter does not know: a newer program, or a corrupted reply. */
UNRECOGNISED;
private static CompletionStage<String> digest(
RedisCommandGateway gateway, String source, AtomicReference<String> cache) {
String cached = cache.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
static ScriptStatus of(String text) {
for (ScriptStatus status : values()) {
if (status != UNRECOGNISED && status.name().equals(text)) {
return status;
}
}
return UNRECOGNISED;
}
return gateway
.loadScript(source.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
cache.set(loaded);
return loaded;
});
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException;
}
private static Reply replyOf(List<Object> reply) {
if (reply == null || reply.size() < 6) {
throw new IllegalStateException("the idempotency program answered with an unexpected shape");
}
return new Reply(
text(reply.get(0)),
number(reply.get(1)),
number(reply.get(2)),
text(reply.get(3)),
text(reply.get(4)),
text(reply.get(5)));
}
private static long number(Object value) {
if (value instanceof Number n) {
return n.longValue();
}
String text = text(value);
return text.isBlank() ? 0L : Long.parseLong(text.strip());
}
private static String text(Object value) {
if (value instanceof byte[] bytes) {
return new String(bytes, StandardCharsets.UTF_8);
}
return value == null ? "" : String.valueOf(value);
}
/**
* One program's answer.
*
* @param status the transition verdict
* @param status the transition verdict, or the record's state for an inspection
* @param attempt the record's attempt counter
* @param revision the record's state revision after the call
* @param owner the stored owner token
@@ -309,5 +269,22 @@ public final class IdempotencyScripts {
* @param detail verdict-specific detail: a lease deadline, a TTL, or the observed state
*/
record Reply(
String status, long attempt, long revision, String owner, String payload, String detail) {}
ScriptStatus status,
long attempt,
long revision,
String owner,
String payload,
String detail) {
static Reply of(List<Object> reply) {
RegisteredLuaScript.requireShape(reply, 6, "idempotency");
return new Reply(
ScriptStatus.of(RegisteredLuaScript.text(reply.get(0))),
RegisteredLuaScript.number(reply.get(1)),
RegisteredLuaScript.number(reply.get(2)),
RegisteredLuaScript.text(reply.get(3)),
RegisteredLuaScript.text(reply.get(4)),
RegisteredLuaScript.text(reply.get(5)));
}
}
}
@@ -1,12 +1,11 @@
package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.IdempotencyScripts.ScriptStatus;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.idempotency.IdempotencyClaimAttempt;
import dev.caskeleton.application.idempotency.IdempotencyClaimOutcome;
import dev.caskeleton.application.idempotency.IdempotencyClaimRequest;
@@ -30,9 +29,10 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.TimeUnit;
import java.util.function.Predicate;
/**
* The owner-safe request-replay store, on Redis.
@@ -57,7 +57,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
private static final SecureRandom RANDOM = new SecureRandom();
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final IdempotencyKeys keys;
@@ -65,8 +65,6 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
private final Clock clock;
private final Duration commandTimeout;
/**
* Creates the adapter.
*
@@ -82,12 +80,15 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
IdempotencyScripts scripts,
Clock clock,
Duration commandTimeout) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.SCRIPT,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"idempotency");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.scripts = Objects.requireNonNull(scripts, "scripts must be non-null");
this.clock = Objects.requireNonNull(clock, "clock must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
}
@Override
@@ -109,61 +110,52 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
public IdempotencyClaimOutcome claim(IdempotencyClaimRequest request) {
Objects.requireNonNull(request, "request must be non-null");
Instant now = clock.instant();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.claim(
lease.gateway(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.claimAttempt().operationId().value(),
request.requestFingerprint().hex(),
request.responseCodecId(),
Integer.toString(request.policyRevision()),
Long.toString(request.processingLeaseTtl().toMillis()),
Long.toString(request.replayTtl().toMillis())))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return claimOutcomeOf(request, reply, now);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "claim", failure);
// A refusal before the script was sent — a saturated or closing lane — claimed nothing, so
// the caller may treat it as unavailable. Only a call that may have run is indeterminate.
return notSent(failure)
? new IdempotencyClaimOutcome.Unavailable()
: new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "claim", failure);
return new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId());
}
// A refusal before the script was sent — a saturated or closing lane — claimed nothing, so the
// caller may treat it as unavailable. Only a call that may have run is indeterminate.
return call.effect(
"claim",
session ->
claimOutcomeOf(
request,
session.await(
scripts.claim(
session.commands(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.claimAttempt().operationId().value(),
request.requestFingerprint().hex(),
request.responseCodecId(),
Integer.toString(request.policyRevision()),
Long.toString(request.processingLeaseTtl().toMillis()),
Long.toString(request.replayTtl().toMillis())))),
now),
IdempotencyClaimOutcome.Unavailable::new,
() -> new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId()));
}
private IdempotencyClaimOutcome claimOutcomeOf(
IdempotencyClaimRequest request, IdempotencyScripts.Reply reply, Instant now) {
return switch (reply.status()) {
case "ACQUIRED" ->
case ACQUIRED ->
new IdempotencyClaimOutcome.Acquired(
ownerOf(request, reply), leaseUntil(reply, now, request));
case "REPLAYED_ACQUIRE" ->
case REPLAYED_ACQUIRE ->
new IdempotencyClaimOutcome.ReplayedAcquire(
ownerOf(request, reply), leaseUntil(reply, now, request));
case "TAKEN_OVER" ->
case TAKEN_OVER ->
new IdempotencyClaimOutcome.TakenOverClaimed(
ownerOf(request, reply), leaseUntil(reply, now, request));
case "COMPLETED_REPLAY" ->
case COMPLETED_REPLAY ->
new IdempotencyClaimOutcome.CompletedReplay(
new StoredResponse(reply.payload()),
now.plusMillis(Math.max(1, parseLong(reply.detail()))));
case "IN_PROGRESS" ->
case IN_PROGRESS ->
new IdempotencyClaimOutcome.InProgress(
Duration.ofMillis(Math.max(1, parseLong(reply.detail()))), reply.attempt());
case "RECOVERY_REQUIRED" -> new IdempotencyClaimOutcome.RecoveryRequired(reply.attempt());
case "FINGERPRINT_MISMATCH" -> new IdempotencyClaimOutcome.FingerprintMismatch();
case "OWNER_OPERATION_CONFLICT" -> new IdempotencyClaimOutcome.OwnerOperationConflict();
case RECOVERY_REQUIRED -> new IdempotencyClaimOutcome.RecoveryRequired(reply.attempt());
case FINGERPRINT_MISMATCH -> new IdempotencyClaimOutcome.FingerprintMismatch();
case OWNER_OPERATION_CONFLICT -> new IdempotencyClaimOutcome.OwnerOperationConflict();
default -> new IdempotencyClaimOutcome.Unavailable();
};
}
@@ -174,17 +166,14 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
return transition(
ownerHandle,
operationId,
"CLAIMED",
"EXECUTING",
"",
"",
"",
IdempotencyStartOutcome.STARTED,
IdempotencyStartOutcome.ALREADY_STARTED_SAME_OPERATION,
IdempotencyStartOutcome.ABSENT,
IdempotencyStartOutcome.NOT_OWNER,
IdempotencyStartOutcome.NOT_CLAIMED,
IdempotencyStartOutcome.OPERATION_CONFLICT,
new Transition("CLAIMED", "EXECUTING", "", "", ""),
Map.of(
ScriptStatus.APPLIED, IdempotencyStartOutcome.STARTED,
ScriptStatus.ALREADY, IdempotencyStartOutcome.ALREADY_STARTED_SAME_OPERATION,
ScriptStatus.ABSENT, IdempotencyStartOutcome.ABSENT,
ScriptStatus.NOT_OWNER, IdempotencyStartOutcome.NOT_OWNER,
ScriptStatus.WRONG_STATE, IdempotencyStartOutcome.NOT_CLAIMED,
ScriptStatus.OPERATION_CONFLICT, IdempotencyStartOutcome.OPERATION_CONFLICT),
IdempotencyStartOutcome.INDETERMINATE,
IdempotencyStartOutcome.UNAVAILABLE,
IdempotencyStartOutcome::carriesOwner);
@@ -197,17 +186,15 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
return transition(
ownerHandle,
operationId,
"EXECUTING",
"EXECUTING",
"",
Long.toString(processingLeaseTtl.toMillis()),
"",
IdempotencyRenewOutcome.RENEWED,
IdempotencyRenewOutcome.ALREADY_RENEWED_SAME_OPERATION,
IdempotencyRenewOutcome.ABSENT,
IdempotencyRenewOutcome.NOT_OWNER,
IdempotencyRenewOutcome.NOT_IN_PROGRESS,
IdempotencyRenewOutcome.OPERATION_CONFLICT,
new Transition(
"EXECUTING", "EXECUTING", "", Long.toString(processingLeaseTtl.toMillis()), ""),
Map.of(
ScriptStatus.APPLIED, IdempotencyRenewOutcome.RENEWED,
ScriptStatus.ALREADY, IdempotencyRenewOutcome.ALREADY_RENEWED_SAME_OPERATION,
ScriptStatus.ABSENT, IdempotencyRenewOutcome.ABSENT,
ScriptStatus.NOT_OWNER, IdempotencyRenewOutcome.NOT_OWNER,
ScriptStatus.WRONG_STATE, IdempotencyRenewOutcome.NOT_IN_PROGRESS,
ScriptStatus.OPERATION_CONFLICT, IdempotencyRenewOutcome.OPERATION_CONFLICT),
IdempotencyRenewOutcome.INDETERMINATE,
IdempotencyRenewOutcome.UNAVAILABLE,
IdempotencyRenewOutcome::carriesOwner);
@@ -221,51 +208,40 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
OperationId operationId) {
Objects.requireNonNull(response, "response must be non-null");
Objects.requireNonNull(replayTtl, "replay TTL must be non-null");
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.transition(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
"EXECUTING",
"COMPLETED",
response.payload(),
"",
Long.toString(replayTtl.toMillis())))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch (reply.status()) {
case "APPLIED" -> IdempotencyCompleteOutcome.COMPLETED;
case "ALREADY" ->
// The same owner completing twice. Whether it is the same result decides whether this
// is an idempotent repeat or a contradiction the caller has to see.
reply.payload().equals(response.payload())
? IdempotencyCompleteOutcome.ALREADY_COMPLETED_SAME_RESULT
: IdempotencyCompleteOutcome.RESPONSE_CONFLICT;
case "ABSENT" -> IdempotencyCompleteOutcome.ABSENT;
case "NOT_OWNER" -> IdempotencyCompleteOutcome.NOT_OWNER;
case "OPERATION_CONFLICT" -> IdempotencyCompleteOutcome.OPERATION_CONFLICT;
case "WRONG_STATE" -> IdempotencyCompleteOutcome.NOT_IN_PROGRESS;
default -> IdempotencyCompleteOutcome.UNAVAILABLE;
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyCompleteOutcome.INDETERMINATE;
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "complete", failure);
return notSent(failure)
? IdempotencyCompleteOutcome.UNAVAILABLE
: IdempotencyCompleteOutcome.INDETERMINATE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "complete", failure);
// The effect may have been recorded. A caller told INDETERMINATE inspects; one told
// UNAVAILABLE might retry the whole operation and duplicate it.
return IdempotencyCompleteOutcome.INDETERMINATE;
}
return call.effect(
"complete",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.transition(
session.commands(),
keys.recordKey(ownerHandle.scope()),
new Transition(
"EXECUTING",
"COMPLETED",
response.payload(),
"",
Long.toString(replayTtl.toMillis()))
.arguments(ownerHandle, operationId)));
return switch (reply.status()) {
case APPLIED -> IdempotencyCompleteOutcome.COMPLETED;
case ALREADY ->
// The same owner completing twice. Whether it is the same result decides whether
// this is an idempotent repeat or a contradiction the caller has to see.
reply.payload().equals(response.payload())
? IdempotencyCompleteOutcome.ALREADY_COMPLETED_SAME_RESULT
: IdempotencyCompleteOutcome.RESPONSE_CONFLICT;
case ABSENT -> IdempotencyCompleteOutcome.ABSENT;
case NOT_OWNER -> IdempotencyCompleteOutcome.NOT_OWNER;
case OPERATION_CONFLICT -> IdempotencyCompleteOutcome.OPERATION_CONFLICT;
case WRONG_STATE -> IdempotencyCompleteOutcome.NOT_IN_PROGRESS;
default -> IdempotencyCompleteOutcome.UNAVAILABLE;
};
},
() -> IdempotencyCompleteOutcome.UNAVAILABLE,
// The effect may have been recorded. A caller told INDETERMINATE inspects; one told
// UNAVAILABLE might retry the whole operation and duplicate it.
() -> IdempotencyCompleteOutcome.INDETERMINATE);
}
@Override
@@ -280,122 +256,98 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
// whether anybody may retry. NO_EFFECT_RETRYABLE releases the operation for another attempt;
// EFFECT_UNKNOWN_ABANDONED does not, because retrying an unknown effect is how it happens
// twice.
String target =
disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE
? "FAILED_RETRYABLE"
: "ABANDONED";
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.transition(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
"EXECUTING",
target,
"",
"",
Long.toString(retention.toMillis())))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch (reply.status()) {
case "APPLIED" ->
disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE
? IdempotencyFailOutcome.MARKED_RETRYABLE
: IdempotencyFailOutcome.MARKED_ABANDONED;
case "ALREADY" -> IdempotencyFailOutcome.ALREADY_MARKED_SAME_OPERATION;
case "ABSENT" -> IdempotencyFailOutcome.ABSENT;
case "NOT_OWNER" -> IdempotencyFailOutcome.NOT_OWNER;
case "OPERATION_CONFLICT" -> IdempotencyFailOutcome.OPERATION_CONFLICT;
case "WRONG_STATE" -> IdempotencyFailOutcome.NOT_IN_PROGRESS;
default -> IdempotencyFailOutcome.UNAVAILABLE;
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyFailOutcome.INDETERMINATE;
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "mark-failed", failure);
return notSent(failure)
? IdempotencyFailOutcome.UNAVAILABLE
: IdempotencyFailOutcome.INDETERMINATE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "mark-failed", failure);
return IdempotencyFailOutcome.INDETERMINATE;
}
boolean retryable = disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE;
Transition transition =
new Transition(
"EXECUTING",
retryable ? "FAILED_RETRYABLE" : "ABANDONED",
"",
"",
Long.toString(retention.toMillis()));
return call.effect(
"mark-failed",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.transition(
session.commands(),
keys.recordKey(ownerHandle.scope()),
transition.arguments(ownerHandle, operationId)));
return switch (reply.status()) {
case APPLIED ->
retryable
? IdempotencyFailOutcome.MARKED_RETRYABLE
: IdempotencyFailOutcome.MARKED_ABANDONED;
case ALREADY -> IdempotencyFailOutcome.ALREADY_MARKED_SAME_OPERATION;
case ABSENT -> IdempotencyFailOutcome.ABSENT;
case NOT_OWNER -> IdempotencyFailOutcome.NOT_OWNER;
case OPERATION_CONFLICT -> IdempotencyFailOutcome.OPERATION_CONFLICT;
case WRONG_STATE -> IdempotencyFailOutcome.NOT_IN_PROGRESS;
default -> IdempotencyFailOutcome.UNAVAILABLE;
};
},
() -> IdempotencyFailOutcome.UNAVAILABLE,
() -> IdempotencyFailOutcome.INDETERMINATE);
}
@Override
public IdempotencyReleaseOutcome releaseBeforeExecution(
IdempotencyOwner ownerHandle, OperationId operationId) {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.release(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value()))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch (reply.status()) {
case "APPLIED" -> IdempotencyReleaseOutcome.RELEASED_BEFORE_EXECUTION;
case "ABSENT" -> IdempotencyReleaseOutcome.ALREADY_RELEASED_SAME_OPERATION;
case "NOT_OWNER" -> IdempotencyReleaseOutcome.NOT_OWNER;
case "OPERATION_CONFLICT" -> IdempotencyReleaseOutcome.OPERATION_CONFLICT;
case "WRONG_STATE" -> IdempotencyReleaseOutcome.EXECUTION_ALREADY_STARTED;
default -> IdempotencyReleaseOutcome.UNAVAILABLE;
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyReleaseOutcome.INDETERMINATE;
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "release-before-execution", failure);
return notSent(failure)
? IdempotencyReleaseOutcome.UNAVAILABLE
: IdempotencyReleaseOutcome.INDETERMINATE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "release-before-execution", failure);
return IdempotencyReleaseOutcome.INDETERMINATE;
}
return call.effect(
"release-before-execution",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.release(
session.commands(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value())));
return switch (reply.status()) {
case APPLIED -> IdempotencyReleaseOutcome.RELEASED_BEFORE_EXECUTION;
case ABSENT -> IdempotencyReleaseOutcome.ALREADY_RELEASED_SAME_OPERATION;
case NOT_OWNER -> IdempotencyReleaseOutcome.NOT_OWNER;
case OPERATION_CONFLICT -> IdempotencyReleaseOutcome.OPERATION_CONFLICT;
case WRONG_STATE -> IdempotencyReleaseOutcome.EXECUTION_ALREADY_STARTED;
default -> IdempotencyReleaseOutcome.UNAVAILABLE;
};
},
() -> IdempotencyReleaseOutcome.UNAVAILABLE,
() -> IdempotencyReleaseOutcome.INDETERMINATE);
}
@Override
public IdempotencyInspection inspect(IdempotencyInspectionRequest request) {
Objects.requireNonNull(request, "request must be non-null");
Instant now = clock.instant();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.inspect(
lease.gateway(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.requestFingerprint().hex(),
request.claimAttempt().operationId().value()))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return inspectionOf(request, reply, now);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "inspect", failure);
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE);
}
// A read: whether or not it reached the server, it changed nothing, so every failure is the
// same "unavailable".
return call.effect(
"inspect",
session ->
inspectionOf(
request,
session.await(
scripts.inspect(
session.commands(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.requestFingerprint().hex(),
request.claimAttempt().operationId().value()))),
now),
() -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE),
() -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE));
}
private IdempotencyInspection inspectionOf(
IdempotencyInspectionRequest request, IdempotencyScripts.Reply reply, Instant now) {
if ("ABSENT".equals(reply.status())) {
if (reply.status() == ScriptStatus.ABSENT) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABSENT);
}
if ("FINGERPRINT_MISMATCH".equals(reply.status())) {
if (reply.status() == ScriptStatus.FINGERPRINT_MISMATCH) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FINGERPRINT_MISMATCH);
}
String[] detail = reply.detail().split("\\|", 2);
@@ -412,17 +364,17 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
reply.revision(),
request.claimAttempt().operationId());
return switch (reply.status()) {
case "COMPLETED" ->
case COMPLETED ->
new IdempotencyInspection(
IdempotencyInspectionOutcome.COMPLETED_REPLAY,
Optional.empty(),
Optional.empty(),
Optional.of(new StoredResponse(reply.payload())),
Optional.of(now.plusMillis(Math.max(1, ttlMillis))));
case "FAILED_RETRYABLE" ->
case FAILED_RETRYABLE ->
IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FAILED_RETRYABLE);
case "ABANDONED" -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED);
case "CLAIMED" ->
case ABANDONED -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED);
case CLAIMED ->
"MINE".equals(ownership)
? new IdempotencyInspection(
IdempotencyInspectionOutcome.CLAIMED_SAME_OPERATION,
@@ -431,7 +383,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
Optional.empty(),
Optional.empty())
: IdempotencyInspection.outcome(IdempotencyInspectionOutcome.IN_PROGRESS_OTHER);
case "EXECUTING" ->
case EXECUTING ->
"MINE".equals(ownership)
? new IdempotencyInspection(
IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION,
@@ -444,77 +396,63 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
};
}
private <O extends Enum<O>> IdempotencyMutationResult<O> transition(
IdempotencyOwner ownerHandle,
OperationId operationId,
String fromState,
String toState,
String payload,
String leaseUntil,
String ttlMillis,
O applied,
O already,
O absent,
O notOwner,
O wrongState,
O operationConflict,
O indeterminate,
O unavailable,
java.util.function.Predicate<O> carriesOwner) {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.transition(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
fromState,
toState,
payload,
leaseUntil,
ttlMillis))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
O outcome =
switch (reply.status()) {
case "APPLIED" -> applied;
case "ALREADY" -> already;
case "ABSENT" -> absent;
case "NOT_OWNER" -> notOwner;
case "OPERATION_CONFLICT" -> operationConflict;
case "WRONG_STATE" -> wrongState;
default -> indeterminate;
};
return new IdempotencyMutationResult<>(
outcome,
carriesOwner.test(outcome)
? new IdempotencyOwner(
ownerHandle.scope(),
ownerHandle.ownerToken(),
reply.attempt(),
reply.revision(),
ownerHandle.claimOperationId())
: null,
carriesOwner);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new IdempotencyMutationResult<>(indeterminate, null, carriesOwner);
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "transition", failure);
return new IdempotencyMutationResult<>(
notSent(failure) ? unavailable : indeterminate, null, carriesOwner);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "transition", failure);
return new IdempotencyMutationResult<>(indeterminate, null, carriesOwner);
/**
* One owner+revision compare-and-set, as the transition program takes it.
*
* @param fromState the state the record must be in
* @param toState the state it moves to
* @param payload the response to store, empty for none
* @param leaseMillis a new processing lease, empty to keep the current one
* @param ttlMillis a new record TTL, empty to keep the current one
*/
private record Transition(
String fromState, String toState, String payload, String leaseMillis, String ttlMillis) {
List<String> arguments(IdempotencyOwner ownerHandle, OperationId operationId) {
return List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
fromState,
toState,
payload,
leaseMillis,
ttlMillis);
}
}
/** A typed runtime refusal raised before any command existed — nothing reached Redis. */
private static boolean notSent(RedisOperationException failure) {
return !failure.metadata().ambiguousExecution();
private <O extends Enum<O>> IdempotencyMutationResult<O> transition(
IdempotencyOwner ownerHandle,
OperationId operationId,
Transition transition,
Map<ScriptStatus, O> outcomes,
O indeterminate,
O unavailable,
Predicate<O> carriesOwner) {
return call.effect(
"transition",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.transition(
session.commands(),
keys.recordKey(ownerHandle.scope()),
transition.arguments(ownerHandle, operationId)));
O outcome = outcomes.getOrDefault(reply.status(), indeterminate);
return new IdempotencyMutationResult<>(
outcome,
carriesOwner.test(outcome)
? new IdempotencyOwner(
ownerHandle.scope(),
ownerHandle.ownerToken(),
reply.attempt(),
reply.revision(),
ownerHandle.claimOperationId())
: null,
carriesOwner);
},
() -> new IdempotencyMutationResult<>(unavailable, null, carriesOwner),
() -> new IdempotencyMutationResult<>(indeterminate, null, carriesOwner));
}
private static IdempotencyOwner ownerOf(
@@ -1,7 +1,7 @@
package dev.caskeleton.adapter.outbound.cache.redis.keyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisKeyRules;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisKeyRules;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
@@ -1,13 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/**
* The four owner-checked lease programs.
@@ -80,107 +77,27 @@ public final class LeaseScripts {
return {1, redis.call('PTTL', KEYS[1]), existing}
""";
private final AtomicReference<String> acquireDigest = new AtomicReference<>();
private final AtomicReference<String> renewDigest = new AtomicReference<>();
private final AtomicReference<String> releaseDigest = new AtomicReference<>();
private final AtomicReference<String> inspectDigest = new AtomicReference<>();
private final RegisteredLuaScript acquire = new RegisteredLuaScript(ACQUIRE);
private final RegisteredLuaScript renew = new RegisteredLuaScript(RENEW);
private final RegisteredLuaScript release = new RegisteredLuaScript(RELEASE);
private final RegisteredLuaScript inspect = new RegisteredLuaScript(INSPECT);
CompletionStage<Reply> acquire(
RedisCommandGateway gateway, byte[] key, String ownership, long ttlMillis) {
return run(gateway, ACQUIRE, acquireDigest, key, args(ownership, ttlMillis));
SemanticRedisCommands commands, byte[] key, String ownership, long ttlMillis) {
return acquire.evaluateForList(commands, key, args(ownership, ttlMillis)).thenApply(Reply::of);
}
CompletionStage<Reply> renew(
RedisCommandGateway gateway, byte[] key, String ownership, long ttlMillis) {
return run(gateway, RENEW, renewDigest, key, args(ownership, ttlMillis));
SemanticRedisCommands commands, byte[] key, String ownership, long ttlMillis) {
return renew.evaluateForList(commands, key, args(ownership, ttlMillis)).thenApply(Reply::of);
}
CompletionStage<Reply> release(RedisCommandGateway gateway, byte[] key, String ownership) {
return run(gateway, RELEASE, releaseDigest, key, args(ownership, 0));
CompletionStage<Reply> release(SemanticRedisCommands commands, byte[] key, String ownership) {
return release.evaluateForList(commands, key, args(ownership, 0)).thenApply(Reply::of);
}
CompletionStage<Reply> inspect(RedisCommandGateway gateway, byte[] key, String ownership) {
return run(gateway, INSPECT, inspectDigest, key, args(ownership, 0));
}
private CompletionStage<Reply> run(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments) {
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments))
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, source, cache, key, arguments, failure))
.thenCompose(stage -> stage)
.thenApply(LeaseScripts::replyOf);
}
private CompletionStage<List<Object>> reload(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments,
Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
cache.set(null);
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments));
}
private static CompletionStage<String> digest(
RedisCommandGateway gateway, String source, AtomicReference<String> cache) {
String cached = cache.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return gateway
.loadScript(source.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
cache.set(loaded);
return loaded;
});
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException;
}
private static Reply replyOf(List<Object> reply) {
if (reply == null || reply.size() < 3) {
throw new IllegalStateException("the lease program answered with an unexpected shape");
}
return new Reply(asLong(reply.get(0)), asLong(reply.get(1)), asText(reply.get(2)));
}
private static long asLong(Object value) {
if (value instanceof Number number) {
return number.longValue();
}
if (value instanceof byte[] bytes) {
return Long.parseLong(new String(bytes, StandardCharsets.UTF_8).strip());
}
throw new IllegalStateException("the lease program answered with an unexpected value type");
}
private static String asText(Object value) {
if (value instanceof byte[] bytes) {
return new String(bytes, StandardCharsets.UTF_8);
}
return value == null ? "" : String.valueOf(value);
CompletionStage<Reply> inspect(SemanticRedisCommands commands, byte[] key, String ownership) {
return inspect.evaluateForList(commands, key, args(ownership, 0)).thenApply(Reply::of);
}
private static List<byte[]> args(String ownership, long ttlMillis) {
@@ -197,5 +114,14 @@ public final class LeaseScripts {
* @param remainingMillis the server's remaining TTL, diagnostic only
* @param holder the stored ownership string, empty when absent
*/
record Reply(long status, long remainingMillis, String holder) {}
record Reply(long status, long remainingMillis, String holder) {
static Reply of(List<Object> reply) {
RegisteredLuaScript.requireShape(reply, 3, "lease");
return new Reply(
RegisteredLuaScript.number(reply.get(0)),
RegisteredLuaScript.number(reply.get(1)),
RegisteredLuaScript.text(reply.get(2)));
}
}
}
@@ -1,12 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.DistributedLeasePort;
import dev.caskeleton.application.lease.LeaseAcquireOutcome;
import dev.caskeleton.application.lease.LeaseAttempt;
@@ -24,7 +22,6 @@ import java.time.Duration;
import java.time.Instant;
import java.util.Base64;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
import java.util.function.LongSupplier;
/**
@@ -47,7 +44,7 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
private static final SecureRandom RANDOM = new SecureRandom();
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final LeaseKeys keys;
@@ -57,8 +54,6 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
private final LongSupplier nanoTime;
private final Duration commandTimeout;
private final Duration contentionRetryAfter;
private final Duration driftBudget;
@@ -84,13 +79,16 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
Duration commandTimeout,
Duration contentionRetryAfter,
Duration driftBudget) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.SCRIPT,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"lease");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.scripts = Objects.requireNonNull(scripts, "scripts must be non-null");
this.clock = Objects.requireNonNull(clock, "clock must be non-null");
this.nanoTime = Objects.requireNonNull(nanoTime, "monotonic source must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
this.contentionRetryAfter =
Objects.requireNonNull(contentionRetryAfter, "contention retry-after must be non-null");
this.driftBudget = Objects.requireNonNull(driftBudget, "drift budget must be non-null");
@@ -148,43 +146,39 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
Duration validity = localValidityOf(request.leaseTtl());
String ownership = ownershipOf(request.attempt());
long startedAt = nanoTime.getAsLong();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.acquire(
lease.gateway(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership,
request.leaseTtl().toMillis())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch ((int) reply.status()) {
case 1 -> new LeaseAcquireOutcome.Acquired(handle(request, ownership, validity, startedAt));
case 2 ->
// The same owner and operation already hold it. This is a retry whose first reply was
// lost, not a second acquisition, and answering "contended" would make a caller back
// off from a lease it already owns. The server did not re-grant the TTL, so the
// handle gets what is left of it, not a fresh one.
new LeaseAcquireOutcome.ReplayedSameOperation(
handle(request, ownership, observedValidityOf(reply.remainingMillis()), startedAt));
default -> contendedOrConflicting(request, reply);
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "acquire", failure);
// Refused before anything was sent: nothing can have been taken.
return notSent(failure)
? new LeaseAcquireOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND)
: new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "acquire", failure);
// An acquire whose outcome is unknown may have taken the lease. Reporting it as a clean
// failure would let the caller retry under a new attempt and hold it twice; Indeterminate
// tells them to inspect with the same attempt instead.
return new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId());
}
return call.effect(
"acquire",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.acquire(
session.commands(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership,
request.leaseTtl().toMillis()));
return switch ((int) reply.status()) {
case 1 ->
new LeaseAcquireOutcome.Acquired(handle(request, ownership, validity, startedAt));
case 2 ->
// The same owner and operation already hold it. This is a retry whose first reply
// was lost, not a second acquisition, and answering "contended" would make a caller
// back off from a lease it already owns. The server did not re-grant the TTL, so
// the handle gets what is left of it, not a fresh one.
new LeaseAcquireOutcome.ReplayedSameOperation(
handle(
request,
ownership,
observedValidityOf(reply.remainingMillis()),
startedAt));
default -> contendedOrConflicting(request, reply);
};
},
// Refused before anything was sent: nothing can have been taken.
() -> new LeaseAcquireOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
// An acquire whose outcome is unknown may have taken the lease. Reporting it as a clean
// failure would let the caller retry under a new attempt and hold it twice; Indeterminate
// tells them to inspect with the same attempt instead.
() -> new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId()));
}
private LeaseAcquireOutcome contendedOrConflicting(
@@ -208,43 +202,36 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
Objects.requireNonNull(request, "request must be non-null");
String ownership = ownershipOf(request.attempt());
long startedAt = nanoTime.getAsLong();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.inspect(
lease.gateway(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (reply.status() == 1) {
return new LeaseInspectionOutcome.Owned(
new RedisLeaseHandle(
request.purpose(),
request.resourceDigest(),
request.attempt(),
ownership,
observedValidityOf(reply.remainingMillis()),
startedAt));
}
if (reply.status() == 0) {
return new LeaseInspectionOutcome.Absent();
}
return reply.holder().startsWith(request.attempt().ownerToken() + ":")
? new LeaseInspectionOutcome.OwnerOperationConflict()
: new LeaseInspectionOutcome.NotOwner();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "inspect", failure);
return notSent(failure)
? new LeaseInspectionOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND)
: new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "inspect", failure);
return new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId());
}
return call.effect(
"inspect",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.inspect(
session.commands(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership));
if (reply.status() == 1) {
return new LeaseInspectionOutcome.Owned(
new RedisLeaseHandle(
request.purpose(),
request.resourceDigest(),
request.attempt(),
ownership,
observedValidityOf(reply.remainingMillis()),
startedAt));
}
if (reply.status() == 0) {
return new LeaseInspectionOutcome.Absent();
}
return reply.holder().startsWith(request.attempt().ownerToken() + ":")
? new LeaseInspectionOutcome.OwnerOperationConflict()
: new LeaseInspectionOutcome.NotOwner();
},
() ->
new LeaseInspectionOutcome.Unavailable(
LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId()));
}
private RedisLeaseHandle handle(
@@ -262,11 +249,6 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
return attempt.ownerToken() + ":" + attempt.operationId();
}
/** A typed runtime refusal raised before any command existed — nothing reached Redis. */
private static boolean notSent(RedisOperationException failure) {
return !failure.metadata().ambiguousExecution();
}
/** A held lease, whose validity is its own to track. */
private final class RedisLeaseHandle implements LeaseHandle {
@@ -340,85 +322,65 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
// Before the round trip, for the reason tryAcquire gives.
Duration validity = localValidityOf(leaseTtl);
long startedAt = nanoTime.getAsLong();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.renew(
lease.gateway(),
keys.leaseKey(purpose, resourceDigest),
ownership,
leaseTtl.toMillis())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (reply.status() == 1) {
// The renewed budget is shortened by the drift allowance for the same reason the first
// one was: a renew does not make the two clocks agree.
grantedValidity = validity;
grantedAtNanos = startedAt;
return new LeaseRenewOutcome.Renewed(remainingValidity());
}
state = LeaseState.LOST;
return reply.status() == 0
? new LeaseRenewOutcome.Absent()
: new LeaseRenewOutcome.NotOwner();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "renew", failure);
if (notSent(failure)) {
return call.effect(
"renew",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.renew(
session.commands(),
keys.leaseKey(purpose, resourceDigest),
ownership,
leaseTtl.toMillis()));
if (reply.status() == 1) {
// The renewed budget is shortened by the drift allowance for the same reason the
// first one was: a renew does not make the two clocks agree.
grantedValidity = validity;
grantedAtNanos = startedAt;
return new LeaseRenewOutcome.Renewed(remainingValidity());
}
state = LeaseState.LOST;
return reply.status() == 0
? new LeaseRenewOutcome.Absent()
: new LeaseRenewOutcome.NotOwner();
},
// Nothing reached the server, so the lease is exactly what it was: still held, on the
// budget it already had.
return new LeaseRenewOutcome.Unavailable(
LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND);
}
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "renew", failure);
// A renew whose outcome is unknown must not extend the local budget. Leaving the handle in
// UNKNOWN is what keeps a caller from acting on validity it cannot demonstrate.
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
}
() -> new LeaseRenewOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> {
// A renew whose outcome is unknown must not extend the local budget. Leaving the handle
// in UNKNOWN is what keeps a caller from acting on validity it cannot demonstrate.
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
});
}
@Override
public LeaseReleaseOutcome release() {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.release(lease.gateway(), keys.leaseKey(purpose, resourceDigest), ownership)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (reply.status() == 1) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.Released();
}
if (reply.status() == 0) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.AlreadyAbsent();
}
state = LeaseState.LOST;
return new LeaseReleaseOutcome.NotOwner();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "release", failure);
if (notSent(failure)) {
return new LeaseReleaseOutcome.Unavailable(
LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND);
}
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "release", failure);
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
}
return call.effect(
"release",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.release(
session.commands(), keys.leaseKey(purpose, resourceDigest), ownership));
if (reply.status() == 1) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.Released();
}
if (reply.status() == 0) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.AlreadyAbsent();
}
state = LeaseState.LOST;
return new LeaseReleaseOutcome.NotOwner();
},
() ->
new LeaseReleaseOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> {
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
});
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
public enum RateLimitAlgorithm {
FIXED_WINDOW,
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import java.time.Duration;
import java.util.Objects;
@@ -27,7 +27,7 @@ public record RateLimitEvaluationDedupPolicy(
"disabled evaluation dedup must not allocate TTL, entries, or stored bytes");
}
} else {
RateLimitBounds.positiveDuration(timeToLive, "timeToLive", MAXIMUM_TIME_TO_LIVE);
RateLimitPolicyBounds.positiveDuration(timeToLive, "timeToLive", MAXIMUM_TIME_TO_LIVE);
if (maximumEntries < 1 || maximumEntries > MAXIMUM_ENTRIES) {
throw new IllegalArgumentException("maximumEntries must be in 1.." + MAXIMUM_ENTRIES);
}
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
/** V1 deliberately does not claim fail-open or local fallback semantics. */
public enum RateLimitFailurePolicy {
@@ -1,8 +1,7 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.util.Objects;
/**
@@ -1,5 +1,6 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Duration;
import java.util.Objects;
@@ -36,18 +37,20 @@ public record RateLimitPolicy(
}
public RateLimitPolicy {
RateLimitBounds.policyId(policyId);
RateLimitBounds.policyRevision(policyRevision);
RateLimitPolicyBounds.policyId(policyId);
RateLimitPolicyBounds.policyRevision(policyRevision);
Objects.requireNonNull(algorithm, "algorithm must not be null");
Objects.requireNonNull(parameters, "parameters must not be null");
if (maximumCost <= 0 || maximumCost > RateParameters.MAXIMUM_EXACT_INTEGER) {
throw new IllegalArgumentException(
"maximumCost must be positive and within Lua's exact integer range");
}
RateLimitBounds.positiveDuration(
cleanupGrace, "cleanupGrace", RateLimitBounds.MAXIMUM_CLEANUP_GRACE);
RateLimitBounds.nonNegativeDuration(
maximumClockRegression, "maximumClockRegression", RateLimitBounds.MAXIMUM_CLOCK_REGRESSION);
RateLimitPolicyBounds.positiveDuration(
cleanupGrace, "cleanupGrace", RateLimitPolicyBounds.MAXIMUM_CLEANUP_GRACE);
RateLimitPolicyBounds.nonNegativeDuration(
maximumClockRegression,
"maximumClockRegression",
RateLimitPolicyBounds.MAXIMUM_CLOCK_REGRESSION);
Objects.requireNonNull(failurePolicy, "failurePolicy must not be null");
Objects.requireNonNull(evaluationDedupPolicy, "evaluationDedupPolicy must not be null");
if (failurePolicy != RateLimitFailurePolicy.FAIL_CLOSED) {
@@ -0,0 +1,70 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import java.time.Duration;
import java.util.Objects;
import java.util.regex.Pattern;
/**
* The bounds a Redis rate-limit policy is validated against.
*
* <p>The policy is this adapter's configuration, not a shared contract, so its bounds live with it.
* The identifier grammars match the ones {@code shared-contract} applies to a request, because a
* request names the policy by the same identifier.
*/
final class RateLimitPolicyBounds {
static final Duration MAXIMUM_CLEANUP_GRACE = Duration.ofDays(1);
static final Duration MAXIMUM_CLOCK_REGRESSION = Duration.ofHours(1);
private static final Pattern POLICY_ID = Pattern.compile("[a-z][a-z0-9-]{0,62}");
private static final Pattern POLICY_REVISION = Pattern.compile("[A-Za-z0-9][A-Za-z0-9._-]{0,63}");
private RateLimitPolicyBounds() {}
static String policyId(String value) {
return boundedIdentifier(value, "policyId", POLICY_ID);
}
static String policyRevision(String value) {
return boundedIdentifier(value, "policyRevision", POLICY_REVISION);
}
static Duration positiveDuration(Duration value, String field, Duration maximum) {
return duration(value, field, false, maximum);
}
static Duration nonNegativeDuration(Duration value, String field, Duration maximum) {
return duration(value, field, true, maximum);
}
private static String boundedIdentifier(String value, String field, Pattern pattern) {
Objects.requireNonNull(value, field + " must not be null");
if (!pattern.matcher(value).matches()) {
throw new IllegalArgumentException(field + " has an invalid bounded representation");
}
return value;
}
private static Duration duration(
Duration value, String field, boolean zeroAllowed, Duration maximum) {
Objects.requireNonNull(value, field + " must not be null");
if (value.isNegative() || (!zeroAllowed && value.isZero())) {
throw new IllegalArgumentException(
field + (zeroAllowed ? " must not be negative" : " must be positive"));
}
if (value.compareTo(maximum) > 0) {
throw new IllegalArgumentException(field + " exceeds its maximum duration of " + maximum);
}
long milliseconds;
try {
milliseconds = value.toMillis();
} catch (ArithmeticException exception) {
throw new IllegalArgumentException(
field + " exceeds the supported milliseconds range", exception);
}
if (!Duration.ofMillis(milliseconds).equals(value)) {
throw new IllegalArgumentException(field + " must use whole milliseconds");
}
return value;
}
}
@@ -1,16 +1,13 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/**
* The atomic programs that make one rate-limit decision one round trip.
@@ -152,46 +149,43 @@ public final class RateLimitScripts {
return {1, math.floor(tokens), resetAfter}
""";
private final AtomicReference<String> fixedWindowDigest = new AtomicReference<>();
private final RegisteredLuaScript fixedWindow = new RegisteredLuaScript(FIXED_WINDOW);
private final AtomicReference<String> slidingCounterDigest = new AtomicReference<>();
private final RegisteredLuaScript slidingCounter = new RegisteredLuaScript(SLIDING_COUNTER);
private final AtomicReference<String> tokenBucketDigest = new AtomicReference<>();
private final RegisteredLuaScript tokenBucket = new RegisteredLuaScript(TOKEN_BUCKET);
/**
* Evaluates one request atomically.
*
* @param gateway the driver seam of a borrowed lease
* @param commands the commands of a borrowed SCRIPT lease
* @param key the rendered counter key
* @param policy the policy to apply
* @param cost the request's cost
* @return the evaluation
*/
public CompletionStage<Evaluation> evaluate(
RedisCommandGateway gateway, byte[] key, RateLimitPolicy policy, long cost) {
Objects.requireNonNull(gateway, "gateway must be non-null");
SemanticRedisCommands commands, byte[] key, RateLimitPolicy policy, long cost) {
Objects.requireNonNull(commands, "commands must be non-null");
Objects.requireNonNull(policy, "policy must be non-null");
long stateTtlMillis = stateTtlMillis(policy);
return switch (policy.parameters()) {
case RateParameters.FixedWindow window ->
run(
gateway,
FIXED_WINDOW,
fixedWindowDigest,
fixedWindow,
commands,
key,
arguments(window.limit(), window.window().toMillis(), cost, stateTtlMillis));
case RateParameters.SlidingCounter sliding ->
run(
gateway,
SLIDING_COUNTER,
slidingCounterDigest,
slidingCounter,
commands,
key,
arguments(sliding.limit(), sliding.window().toMillis(), cost, stateTtlMillis));
case RateParameters.TokenBucket bucket ->
run(
gateway,
TOKEN_BUCKET,
tokenBucketDigest,
tokenBucket,
commands,
key,
arguments(
bucket.capacity(),
@@ -222,82 +216,22 @@ public final class RateLimitScripts {
};
}
private CompletionStage<Evaluation> run(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
private static CompletionStage<Evaluation> run(
RegisteredLuaScript program,
SemanticRedisCommands commands,
byte[] key,
List<byte[]> arguments) {
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments))
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, source, cache, key, arguments, failure))
.thenCompose(stage -> stage)
return program
.evaluateForList(commands, key, arguments)
.thenApply(RateLimitScripts::evaluationOf);
}
private CompletionStage<List<Object>> reload(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments,
Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
cache.set(null);
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments));
}
private static CompletionStage<String> digest(
RedisCommandGateway gateway, String source, AtomicReference<String> cache) {
String cached = cache.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return gateway
.loadScript(source.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
cache.set(loaded);
return loaded;
});
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException;
}
private static Evaluation evaluationOf(List<Object> reply) {
if (reply == null || reply.size() < 3) {
throw new IllegalStateException(
"the rate limit program answered with "
+ (reply == null ? "nothing" : reply.size())
+ " values; three were expected");
}
return new Evaluation(asLong(reply.get(0)) == 1L, asLong(reply.get(1)), asLong(reply.get(2)));
}
private static long asLong(Object value) {
if (value instanceof Number number) {
return number.longValue();
}
if (value instanceof byte[] bytes) {
return Long.parseLong(new String(bytes, StandardCharsets.UTF_8).strip());
}
throw new IllegalStateException(
"the rate limit program answered with an unexpected value type: "
+ (value == null ? "null" : value.getClass().getName()));
RegisteredLuaScript.requireShape(reply, 3, "rate limit");
return new Evaluation(
RegisteredLuaScript.number(reply.get(0)) == 1L,
RegisteredLuaScript.number(reply.get(1)),
RegisteredLuaScript.number(reply.get(2)));
}
private static List<byte[]> arguments(long... values) {
@@ -1,14 +1,11 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.shared.ratelimit.EdgeRateLimitPort;
import dev.caskeleton.shared.ratelimit.RateLimitDecision;
import dev.caskeleton.shared.ratelimit.RateLimitOutcome;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitRequest;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Clock;
@@ -17,7 +14,6 @@ import java.time.Instant;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
/**
* The provider-neutral edge rate limit, on Redis.
@@ -38,7 +34,7 @@ import java.util.concurrent.TimeUnit;
*/
public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final RateLimitKeys keys;
@@ -48,8 +44,6 @@ public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
private final Clock clock;
private final Duration commandTimeout;
private final Duration failureRetryAfter;
/**
@@ -71,13 +65,16 @@ public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
Clock clock,
Duration commandTimeout,
Duration failureRetryAfter) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.SCRIPT,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"rate-limit");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.policies = Map.copyOf(Objects.requireNonNull(policies, "policies must be non-null"));
this.scripts = Objects.requireNonNull(scripts, "scripts must be non-null");
this.clock = Objects.requireNonNull(clock, "clock must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
this.failureRetryAfter =
Objects.requireNonNull(failureRetryAfter, "failure retry-after must be non-null");
}
@@ -106,34 +103,24 @@ public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
RateLimitOutcome.UnavailableCategory.ADMISSION_REJECTED);
}
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
RateLimitScripts.Evaluation evaluation =
scripts
.evaluate(
lease.gateway(),
keys.counterKey(policy, request.subjectDigest()),
policy,
request.cost())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return new RateLimitOutcome.Evaluated(decisionOf(policy, evaluation, now));
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return unavailable(policy, RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED);
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("rate-limit", "evaluate", failure);
// The distinction that matters: a command the guard refused never reached Redis and consumed
// no budget, while a command that may have run has consumed one the caller will never know
// about. Reporting them the same way would make a retry either free or double-charged.
return unavailable(
policy,
failure.metadata().ambiguousExecution()
? RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED
: RateLimitOutcome.UnavailableCategory.UNAVAILABLE_BEFORE_SEND);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("rate-limit", "evaluate", failure);
return unavailable(policy, RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED);
}
// The distinction that matters: a command refused before it was sent consumed no budget, while
// one that may have run has consumed one the caller will never know about. Reporting them the
// same way would make a retry either free or double-charged.
return call.effect(
"evaluate",
session ->
new RateLimitOutcome.Evaluated(
decisionOf(
policy,
session.await(
scripts.evaluate(
session.commands(),
keys.counterKey(policy, request.subjectDigest()),
policy,
request.cost())),
now)),
() -> unavailable(policy, RateLimitOutcome.UnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> unavailable(policy, RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED));
}
private RateLimitOutcome unavailable(
@@ -1,2 +1,6 @@
org.springframework.boot.EnvironmentPostProcessor=\
dev.caskeleton.adapter.outbound.cache.redis.capability.RedisReadinessGroupPostProcessor
# Which roles need Redis for correctness. The runtime asks; this module owns the selectors.
dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRequirement=\
dev.caskeleton.adapter.outbound.cache.redis.capability.RedisCorrectnessRoleSelectors
@@ -1,17 +1,17 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisCredentialRole;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisAccount;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.io.IOException;
import java.time.Duration;
import java.util.ArrayList;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
@@ -34,7 +34,7 @@ public final class LiveRedisRuntime {
*/
public static RedisRuntimeOwner open(RedisNamespace namespace, boolean separateScriptAccount) {
RedisTopologyEndpoint endpoint = RedisTopologyEndpoint.fromSystemProperties();
RedisSdkSettings settings = new RedisSdkSettings();
RedisRuntimeSettings settings = new RedisRuntimeSettings();
settings.setEnabled(true);
settings.setMode(endpoint.mode());
settings.setNodes(new ArrayList<>(List.of(endpoint.host() + ":" + endpoint.port())));
@@ -42,18 +42,18 @@ public final class LiveRedisRuntime {
settings.getNamespace().setService(namespace.service());
settings.getNamespace().setDomain(namespace.domain());
Map<RedisCredentialRole, RedisCredentials> accounts = new EnumMap<>(RedisCredentialRole.class);
Map<RedisAccount, RedisCredentials> accounts = new java.util.LinkedHashMap<>();
accounts.put(
RedisCredentialRole.APPLICATION,
RedisAccount.APPLICATION,
new RedisCredentials(
endpoint.username(),
endpoint.password().isBlank() ? "fixture-application" : endpoint.password()));
if (separateScriptAccount) {
accounts.put(
RedisCredentialRole.ADVANCED,
RedisAccount.ADVANCED,
new RedisCredentials("ca-skeleton-application-advanced", "fixture-advanced"));
}
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 4);
}
@@ -7,15 +7,18 @@ import dev.caskeleton.adapter.outbound.cache.redis.idempotency.IdempotencyScript
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.RedisIdempotencyStoreAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.lease.LeaseScripts;
import dev.caskeleton.adapter.outbound.cache.redis.lease.RedisDistributedLeaseAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitKeys;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitScripts;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RedisEdgeRateLimitAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.cache.CacheLookup;
import dev.caskeleton.application.cache.CacheRecordIntent;
import dev.caskeleton.application.cache.CacheRecordMetadata;
@@ -30,10 +33,7 @@ import dev.caskeleton.application.lease.LeaseAcquireOutcome;
import dev.caskeleton.application.lease.LeaseAttempt;
import dev.caskeleton.application.lease.LeaseRequest;
import dev.caskeleton.application.transaction.OperationId;
import dev.caskeleton.shared.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.shared.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.shared.ratelimit.RateLimitOutcome;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitRequest;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.nio.charset.StandardCharsets;
@@ -254,7 +254,7 @@ class LiveRedisSemanticPortsTest {
private static long fieldCount(RedisRuntimeOwner runtime, byte[] key) throws Exception {
try (RedisLease lease = runtime.borrow(RedisConnectionKind.REGULAR)) {
return lease.gateway().hashSize(key).toCompletableFuture().get(2, TimeUnit.SECONDS);
return lease.driver().commands().hlen(key).toCompletableFuture().get(2, TimeUnit.SECONDS);
}
}
@@ -0,0 +1,118 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class RegisteredLuaScriptTest {
private static final byte[] KEY = "prod:svc:shared:probe".getBytes(StandardCharsets.UTF_8);
@Test
void aProgramIsLoadedOnceAndThenRunByDigest() {
// given
ScriptedServer server = new ScriptedServer();
RegisteredLuaScript program = new RegisteredLuaScript("return 1");
// when
program.evaluateForLong(server.commands(), KEY, List.of()).toCompletableFuture().join();
program.evaluateForLong(server.commands(), KEY, List.of()).toCompletableFuture().join();
// then
assertThat(server.calls).containsExactly("load", "eval:digest-1", "eval:digest-1");
}
@Test
@DisplayName("NOSCRIPT 타입 응답이면 다시 올린 뒤 정확히 한 번만 재실행한다")
void aForgottenProgramIsReloadedAndRetriedExactlyOnce() {
// given
ScriptedServer server = new ScriptedServer();
server.failNext(new io.lettuce.core.RedisNoScriptException("NOSCRIPT No matching script"));
RegisteredLuaScript program = new RegisteredLuaScript("return 1");
// when
program.evaluateForLong(server.commands(), KEY, List.of()).toCompletableFuture().join();
// then
assertThat(server.calls).containsExactly("load", "eval:digest-1", "load", "eval:digest-2");
}
@Test
void aFailureThatIsNotNoScriptIsNeitherReloadedNorRetried() {
// given
ScriptedServer server = new ScriptedServer();
server.failNext(new io.lettuce.core.RedisCommandExecutionException("NOPERM denied"));
RegisteredLuaScript program = new RegisteredLuaScript("return 1");
// when
Throwable failure =
catchThrowable(
() ->
program
.evaluateForLong(server.commands(), KEY, List.of())
.toCompletableFuture()
.join());
// then
assertThat(failure)
.hasRootCauseInstanceOf(io.lettuce.core.RedisCommandExecutionException.class)
.hasRootCauseMessage("NOPERM denied");
}
@Test
void aShortReplyIsRefusedWithTheProgramsName() {
// when
Throwable failure =
catchThrowable(() -> RegisteredLuaScript.requireShape(List.of(1L), 3, "lease"));
// then
assertThat(failure)
.isInstanceOf(IllegalStateException.class)
.hasMessage("the lease program answered with 1 values; 3 were expected");
}
/** Counts loads and evaluations, and fails an evaluation on request. */
private static final class ScriptedServer {
private final List<String> calls = new ArrayList<>();
private final Deque<RuntimeException> failures = new ArrayDeque<>();
private int loads;
void failNext(RuntimeException failure) {
failures.add(failure);
}
SemanticRedisCommands commands() {
return (SemanticRedisCommands)
Proxy.newProxyInstance(
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
switch (method.getName()) {
case "loadScript" -> {
calls.add("load");
loads++;
yield CompletableFuture.completedFuture("digest-" + loads);
}
case "evaluateRegisteredForLong" -> {
calls.add("eval:" + arguments[0]);
RuntimeException failure = failures.poll();
yield failure == null
? CompletableFuture.completedFuture(1L)
: CompletableFuture.failedFuture(failure);
}
default -> throw new UnsupportedOperationException(method.getName());
});
}
}
}
@@ -2,13 +2,15 @@ package dev.caskeleton.adapter.outbound.cache.redis.cache;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.cache.AuthoritativeAbsence;
import dev.caskeleton.application.cache.CacheInvalidationOutcome;
import dev.caskeleton.application.cache.CacheLookup;
@@ -21,7 +23,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import org.junit.jupiter.api.DisplayName;
@@ -39,14 +40,14 @@ class RedisCacheRegionAdapterTest {
private static final Instant T0 = Instant.parse("2026-08-10T12:00:00Z");
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final RedisCacheRegionAdapter.CacheKeys keys =
new RedisCacheRegionAdapter.CacheKeys(
new RedisNamespace("prod", "ca-skeleton", "shared"), "orders", 1);
private RedisCacheRegionAdapter<String, String> cache(Instant now) {
return cache(now, new StubClient(gateway.gateway()));
return cache(now, StubRedisRuntimeClient.serving(gateway));
}
private RedisCacheRegionAdapter<String, String> cache(Instant now, RedisRuntimeClient client) {
@@ -55,7 +56,7 @@ class RedisCacheRegionAdapterTest {
private RedisCacheRegionAdapter<String, String> cache(
Instant now, RedisRuntimeClient client, RedisCacheRegionAdapter.CacheKeys cacheKeys) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 4);
}
@@ -224,9 +225,9 @@ class RedisCacheRegionAdapterTest {
new RedisNamespace("prod", "ca-skeleton", "shared"), "orders-shared", 1);
RedisCacheRegionAdapter<String, String> first =
cache(T0, new StubClient(gateway.gateway()), firstKeys);
cache(T0, StubRedisRuntimeClient.serving(gateway), firstKeys);
RedisCacheRegionAdapter<String, String> second =
cache(T0, new StubClient(gateway.gateway()), secondKeys);
cache(T0, StubRedisRuntimeClient.serving(gateway), secondKeys);
second.record("order-1", "payload", upsert());
assertThat(second.lookup("order-1")).isInstanceOf(CacheLookup.Hit.class);
@@ -240,7 +241,7 @@ class RedisCacheRegionAdapterTest {
// The same process state (secondKeys) is reused with a later clock. Once the positive soft TTL
// elapses it must sample the server generation again and stop serving the old region entry.
RedisCacheRegionAdapter<String, String> secondAfterRecheck =
cache(T0.plusSeconds(31), new StubClient(gateway.gateway()), secondKeys);
cache(T0.plusSeconds(31), StubRedisRuntimeClient.serving(gateway), secondKeys);
CacheLookup<String> lookup = secondAfterRecheck.lookup("order-1");
assertThat(lookup).isInstanceOf(CacheLookup.Miss.class);
@@ -329,7 +330,8 @@ class RedisCacheRegionAdapterTest {
@DisplayName("보낸 뒤 응답을 잃은 SET은 적용됐을 수 있으므로 INDETERMINATE다")
void aWriteWhoseReplyWasLostIsIndeterminate() {
// given
RedisCacheRegionAdapter<String, String> cache = cache(T0, new StubClient(losingReplyOf("set")));
RedisCacheRegionAdapter<String, String> cache =
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("set")));
// when
CacheRecordOutcome outcome = cache.record("order-1", "payload", upsert());
@@ -343,7 +345,7 @@ class RedisCacheRegionAdapterTest {
void aWriteThatFailedBeforeItsSetWasSentDegrades() {
// given
RedisCacheRegionAdapter<String, String> cache =
cache(T0, new StubClient(losingReplyOf("incrementBy")));
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("incrementBy")));
// when
CacheRecordOutcome outcome = cache.record("order-1", "payload", upsert());
@@ -357,7 +359,7 @@ class RedisCacheRegionAdapterTest {
void anInvalidationWhoseReplyWasLostIsIndeterminate() {
// given
RedisCacheRegionAdapter<String, String> cache =
cache(T0, new StubClient(losingReplyOf("getAndDelete")));
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("getAndDelete")));
// when
CacheInvalidationOutcome outcome = cache.invalidate("order-1");
@@ -371,7 +373,7 @@ class RedisCacheRegionAdapterTest {
void aRegionInvalidationWhoseReplyWasLostIsIndeterminate() {
// given
RedisCacheRegionAdapter<String, String> cache =
cache(T0, new StubClient(losingReplyOf("incrementBy")));
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("incrementBy")));
// when
CacheInvalidationOutcome outcome = cache.invalidateRegion();
@@ -381,12 +383,12 @@ class RedisCacheRegionAdapterTest {
}
/** The in-memory gateway, except that one command's reply is lost after it was sent. */
private RedisCommandGateway losingReplyOf(String command) {
RedisCommandGateway real = gateway.gateway();
return (RedisCommandGateway)
private SemanticRedisCommands losingReplyOf(String command) {
SemanticRedisCommands real = gateway;
return (SemanticRedisCommands)
Proxy.newProxyInstance(
RedisCommandGateway.class.getClassLoader(),
new Class<?>[] {RedisCommandGateway.class},
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
method.getName().equals(command)
? CompletableFuture.failedFuture(new RuntimeException("reply lost"))
@@ -410,14 +412,11 @@ class RedisCacheRegionAdapterTest {
private void writeRaw(String key, byte[] stored) {
try {
gateway
.gateway()
.set(
keys.entryKey("digest-" + key),
stored,
dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence
.ALWAYS,
new dev.caskeleton.adapter.outbound.cache.redis.sdk.api.operations.Expiration.After(
Duration.ofMinutes(10)))
dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence.ALWAYS,
Duration.ofMinutes(10))
.toCompletableFuture()
.join();
} catch (RuntimeException failure) {
@@ -425,36 +424,6 @@ class RedisCacheRegionAdapterTest {
}
}
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
private static final class BrokenClient implements RedisRuntimeClient {
@Override
@@ -463,8 +432,7 @@ class RedisCacheRegionAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -5,8 +5,8 @@ import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.LiveRedisRuntime;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
@@ -2,7 +2,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.outbound.SecretSourcePort;
import java.time.Clock;
import java.util.ArrayList;
@@ -3,8 +3,8 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.Mockito.mock;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.application.cache.CacheRegionPort;
import dev.caskeleton.application.idempotency.IdempotencyStorePort;
@@ -40,7 +40,7 @@ class RedisCapabilityCompositionTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(RedisSdkAutoConfiguration.class))
.withConfiguration(AutoConfigurations.of(RedisRuntimeAutoConfiguration.class))
.withBean(
"compositionOnlyRedisSemanticScriptAclProbe",
RedisSemanticScriptAclProbe.class,
@@ -100,7 +100,7 @@ class RedisCapabilityCompositionTest {
// Every call would answer "unknown policy", which the port reports as a deployment error per
// request rather than once, at the only moment anybody is looking.
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(RedisSdkAutoConfiguration.class))
.withConfiguration(AutoConfigurations.of(RedisRuntimeAutoConfiguration.class))
.withUserConfiguration(RedisCapabilityConfig.class, Support.class)
.withPropertyValues(
"app.redis.enabled=true",
@@ -170,7 +170,7 @@ class RedisCapabilityCompositionTest {
void theSwitchOffLeavesNoRedisBeanWhateverTheRolesSay() {
new ApplicationContextRunner()
.withConfiguration(
AutoConfigurations.of(RedisSdkAutoConfiguration.class, RedisCapabilityConfig.class))
AutoConfigurations.of(RedisRuntimeAutoConfiguration.class, RedisCapabilityConfig.class))
.withUserConfiguration(Support.class)
.withPropertyValues(
"app.redis.enabled=false",
@@ -0,0 +1,80 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import java.util.List;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
import org.springframework.mock.env.MockEnvironment;
/**
* Which production secrets each selected Redis role needs — the rule the composition root's secret
* guard used to spell out itself, one Redis role prefix at a time.
*/
class RedisProductionSecretsTest {
private final RedisProductionSecrets secrets = new RedisProductionSecrets();
static Stream<Arguments> selectedRoles() {
return Stream.of(
Arguments.of(
"ca-skeleton.capabilities.cache.bindings.default",
"redis",
List.of("APP_CACHE_REDIS_PASSWORD", "APP_CACHE_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.security.auth-mode",
"redis-session",
List.of("APP_SESSION_REDIS_PASSWORD", "APP_SESSION_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.capabilities.idempotency.provider",
"redis",
List.of("APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.capabilities.rate-limit.provider",
"redis",
List.of("APP_RATE_LIMIT_REDIS_PASSWORD", "APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.capabilities.lease.provider",
"redis",
List.of("APP_LEASE_REDIS_KEY_HMAC_SECRET")));
}
@ParameterizedTest(name = "{0}={1}")
@MethodSource("selectedRoles")
@DisplayName("선택된 Redis 역할은 자기 production secret만 요구한다")
void aSelectedRoleRequiresExactlyItsOwnSecrets(
String selector, String value, List<String> expected) {
// given
MockEnvironment environment = new MockEnvironment().withProperty(selector, value);
// when
List<String> required = secrets.requiredSecrets(environment);
// then
assertThat(required).containsExactlyElementsOf(expected);
}
@Test
@DisplayName("Redis가 켜져 있어도 역할이 선택되지 않았으면 역할 secret을 요구하지 않는다")
void noSelectedRoleRequiresNoRoleSecret() {
assertThat(secrets.requiredSecrets(new MockEnvironment())).isEmpty();
}
@Test
void aRoleSelectingAnotherProviderRequiresNothingOfRedis() {
// given
MockEnvironment environment =
new MockEnvironment()
.withProperty("ca-skeleton.capabilities.rate-limit.provider", "disabled");
// when
List<String> required = secrets.requiredSecrets(environment);
// then
assertThat(required).isEmpty();
}
}
@@ -2,7 +2,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.support.startup.ReadinessGroup;
import java.io.IOException;
import java.util.ArrayList;
@@ -148,7 +148,10 @@ class RedisReadinessGroupPostProcessorTest {
@Test
@DisplayName("every correctness selector makes the post-processor append Redis readiness")
void eachCorrectnessSelectorAppendsRedisReadiness() throws IOException {
for (Map.Entry<String, String> selector : RedisCorrectnessRoles.selectors().entrySet()) {
for (RedisCorrectnessRoleSelectors.Role role :
RedisCorrectnessRoleSelectors.ROLES.stream()
.filter(RedisCorrectnessRoleSelectors.Role::correctness)
.toList()) {
StandardEnvironment environment = new StandardEnvironment();
environment
.getPropertySources()
@@ -160,14 +163,14 @@ class RedisReadinessGroupPostProcessorTest {
shippedReadinessInclude(),
"app.redis.enabled",
"true",
selector.getKey(),
selector.getValue())));
role.selector(),
role.selecting())));
new RedisReadinessGroupPostProcessor()
.postProcessEnvironment(environment, new SpringApplication());
assertThat(environment.getProperty(ReadinessGroup.INCLUDE_PROPERTY))
.as("%s=%s", selector.getKey(), selector.getValue())
.as("%s=%s", role.selector(), role.selecting())
.contains("readinessState", RedisCorrectnessRoles.REQUIRED_HEALTH_CONTRIBUTOR);
}
}
@@ -180,7 +183,7 @@ class RedisReadinessGroupPostProcessorTest {
HealthContributorAutoConfiguration.class,
AvailabilityHealthContributorAutoConfiguration.class,
HealthEndpointAutoConfiguration.class,
dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration.class
dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration.class
})
static class HealthContext {
@@ -190,7 +193,7 @@ class RedisReadinessGroupPostProcessorTest {
}
@Bean
dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration
dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration
.RedisSecretSource
stubSecretSource() {
// Supplies the credential the enabled cases require, without putting one in the process
@@ -5,17 +5,18 @@ import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.atomic.AtomicInteger;
@@ -104,7 +105,7 @@ class RedisSemanticScriptAclProbeTest {
.hasMessageContaining("SCRIPT LOAD/EVALSHA is unavailable");
}
private static RedisRuntimeOwner owner(RedisCommandGateway gateway, AtomicInteger opened) {
private static RedisRuntimeOwner owner(SemanticRedisCommands gateway, AtomicInteger opened) {
RedisRuntimeClient client =
new RedisRuntimeClient() {
@Override
@@ -113,15 +114,21 @@ class RedisSemanticScriptAclProbeTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, Optional<byte[]> routingKey) {
opened.incrementAndGet();
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
public SemanticRedisCommands commands() {
return gateway;
}
@Override
public dev.caskeleton.adapter.outbound.cache.redis.runtime.connection
.RedisDriverConnection
driver() {
throw new UnsupportedOperationException();
}
@Override
public boolean open() {
return true;
@@ -135,18 +142,18 @@ class RedisSemanticScriptAclProbeTest {
@Override
public void close() {}
};
EnumMap<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 1);
}
return new RedisRuntimeOwner(client, limits, Duration.ofSeconds(1), Duration.ofSeconds(1));
}
private static RedisCommandGateway gateway(boolean denyScripts) {
return (RedisCommandGateway)
private static SemanticRedisCommands gateway(boolean denyScripts) {
return (SemanticRedisCommands)
Proxy.newProxyInstance(
RedisCommandGateway.class.getClassLoader(),
new Class<?>[] {RedisCommandGateway.class},
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
switch (method.getName()) {
case "loadScript" ->
@@ -169,12 +176,12 @@ class RedisSemanticScriptAclProbeTest {
* <p>Redis checks a script's inner commands against the caller's ACL when they run, so a program
* that calls the denied command fails with {@code NOPERM} and one that does not call it succeeds.
*/
private static RedisCommandGateway gatewayDenying(String command) {
private static SemanticRedisCommands gatewayDenying(String command) {
AtomicReference<String> loaded = new AtomicReference<>("");
return (RedisCommandGateway)
return (SemanticRedisCommands)
Proxy.newProxyInstance(
RedisCommandGateway.class.getClassLoader(),
new Class<?>[] {RedisCommandGateway.class},
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
switch (method.getName()) {
case "loadScript" -> {
@@ -1,29 +0,0 @@
package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.lang.reflect.Field;
import java.util.Map;
import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.Test;
/** Pins the script-digest cache so request threads never mutate a shared map structure. */
class IdempotencyScriptsConcurrencyContractTest {
@Test
void digestSlotsArePreallocatedAndStructurallyImmutable() throws Exception {
IdempotencyScripts scripts = new IdempotencyScripts();
Field field = IdempotencyScripts.class.getDeclaredField("digests");
field.setAccessible(true);
@SuppressWarnings("unchecked")
Map<String, AtomicReference<String>> digests =
(Map<String, AtomicReference<String>>) field.get(scripts);
assertThat(digests).containsOnlyKeys("claim", "transition", "release", "inspect");
assertThat(digests.values()).allSatisfy(slot -> assertThat(slot.get()).isNull());
assertThatThrownBy(() -> digests.put("runtime-added", new AtomicReference<>()))
.isInstanceOf(UnsupportedOperationException.class);
}
}
@@ -2,13 +2,14 @@ package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.idempotency.IdempotencyClaimAttempt;
import dev.caskeleton.application.idempotency.IdempotencyClaimOutcome;
import dev.caskeleton.application.idempotency.IdempotencyClaimRequest;
@@ -29,7 +30,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.Map;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
@@ -62,9 +62,10 @@ class RedisIdempotencyStoreAdapterTest {
private static final OperationId OTHER_OPERATION = new OperationId("operation-bbbbbbbbbb");
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final RedisIdempotencyStoreAdapter store = store(T0, new StubClient(gateway.gateway()));
private final RedisIdempotencyStoreAdapter store =
store(T0, StubRedisRuntimeClient.serving(gateway));
private RedisIdempotencyStoreAdapter store(Instant now, RedisRuntimeClient client) {
return store(now, owner(client, 4, Duration.ofSeconds(1)));
@@ -72,7 +73,7 @@ class RedisIdempotencyStoreAdapterTest {
private static RedisRuntimeOwner owner(
RedisRuntimeClient client, int connectionsPerLane, Duration acquireTimeout) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, connectionsPerLane);
}
@@ -83,7 +84,7 @@ class RedisIdempotencyStoreAdapterTest {
* An owner with one script connection and almost no patience, so holding it saturates the lane.
*/
private RedisRuntimeOwner narrowOwner() {
return owner(new StubClient(gateway.gateway()), 1, Duration.ofMillis(10));
return owner(StubRedisRuntimeClient.serving(gateway), 1, Duration.ofMillis(10));
}
private RedisIdempotencyStoreAdapter store(Instant now, RedisRuntimeOwner owner) {
@@ -264,7 +265,7 @@ class RedisIdempotencyStoreAdapterTest {
// The first holder went away. Advancing the Redis fixture clock, not the caller JVM clock,
// expires the distributed processing lease.
gateway.advance(Duration.ofSeconds(60));
RedisIdempotencyStoreAdapter later = store(T0, new StubClient(gateway.gateway()));
RedisIdempotencyStoreAdapter later = store(T0, StubRedisRuntimeClient.serving(gateway));
IdempotencyClaimOutcome outcome =
later.claim(
new IdempotencyClaimRequest(
@@ -394,36 +395,6 @@ class RedisIdempotencyStoreAdapterTest {
return store.markExecutionStarted(owner, OPERATION).owner().orElseThrow();
}
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
private static final class BrokenClient implements RedisRuntimeClient {
@Override
@@ -432,8 +403,7 @@ class RedisIdempotencyStoreAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -0,0 +1,53 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.atomic.AtomicBoolean;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class LeaseScriptsTest {
private static final byte[] KEY = "prod:svc:shared:lease:v1:p:r".getBytes(StandardCharsets.UTF_8);
@Test
@DisplayName("NOSCRIPT가 예외 타입이 아니라 메시지로만 와도 lease 프로그램을 다시 올리고 한 번 재실행한다")
void aProgramTheServerForgotIsReloadedEvenWhenOnlyTheMessageSaysNoScript() {
// given
SemanticRedisCommands server = forgettingOnce(new InMemorySemanticRedisCommands());
LeaseScripts scripts = new LeaseScripts();
// when
LeaseScripts.Reply reply =
scripts.acquire(server, KEY, "owner:operation", 30_000).toCompletableFuture().join();
// then
assertThat(reply.status()).isEqualTo(1L);
}
/**
* A server that has lost every loaded script once, and says so the way a proxy or a wrapped
* driver error does: a generic command failure whose message starts with {@code NOSCRIPT}.
*/
private static SemanticRedisCommands forgettingOnce(SemanticRedisCommands delegate) {
AtomicBoolean forgotten = new AtomicBoolean();
return (SemanticRedisCommands)
Proxy.newProxyInstance(
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) -> {
if (method.getName().startsWith("evaluateRegistered")
&& forgotten.compareAndSet(false, true)) {
return CompletableFuture.failedFuture(
new io.lettuce.core.RedisCommandExecutionException(
"NOSCRIPT No matching script. Please use EVAL."));
}
return method.invoke(delegate, arguments);
});
}
}
@@ -0,0 +1,65 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.LiveRedisRuntime;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.DistributedLeasePort;
import dev.caskeleton.application.lease.testkit.DistributedLeaseContract;
import java.time.Clock;
import java.time.Duration;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Tag;
/**
* The Redis adapter, against a real server under the deployment's advanced account, held to the
* same ownership contract as the fake.
*
* <p>The owner check is Lua on the server; only a real server proves the programs compare what the
* fake's emulation says they compare. Time passes for real here, so the lease is short.
*/
@Tag("redis-topology")
@Tag("lane-standalone")
@Tag("lane-cluster")
class LiveRedisDistributedLeaseContractTest extends DistributedLeaseContract {
private static final RedisNamespace NAMESPACE = new RedisNamespace("prod", "order", "shared");
private RedisRuntimeOwner owner;
@AfterEach
void closeOwner() {
if (owner != null) {
owner.close();
owner = null;
}
}
@Override
protected DistributedLeasePort newPort() {
owner = LiveRedisRuntime.open(NAMESPACE, true);
return new RedisDistributedLeaseAdapter(
owner,
new RedisDistributedLeaseAdapter.LeaseKeys(NAMESPACE, 1),
new LeaseScripts(),
Clock.systemUTC(),
System::nanoTime,
Duration.ofSeconds(2),
Duration.ofMillis(50),
Duration.ZERO);
}
@Override
protected Duration leaseTtl() {
return Duration.ofMillis(400);
}
@Override
protected void elapse(Duration duration) {
try {
Thread.sleep(duration.toMillis());
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new IllegalStateException("interrupted while letting the lease expire", interrupted);
}
}
}
@@ -3,13 +3,14 @@ package dev.caskeleton.adapter.outbound.cache.redis.lease;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.LeaseAcquireOutcome;
import dev.caskeleton.application.lease.LeaseAttempt;
import dev.caskeleton.application.lease.LeaseHandle;
@@ -24,7 +25,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicLong;
@@ -56,11 +56,12 @@ class RedisDistributedLeaseAdapterTest {
private static final String OPERATION_B = "operation-bbbbbbbbbb";
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final AtomicLong nanos = new AtomicLong();
private final RedisDistributedLeaseAdapter adapter = adapter(new StubClient(gateway.gateway()));
private final RedisDistributedLeaseAdapter adapter =
adapter(StubRedisRuntimeClient.serving(gateway));
private RedisDistributedLeaseAdapter adapter(RedisRuntimeClient client) {
return adapter(client, Duration.ZERO);
@@ -72,7 +73,7 @@ class RedisDistributedLeaseAdapterTest {
private static RedisRuntimeOwner owner(
RedisRuntimeClient client, int connectionsPerLane, Duration acquireTimeout) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, connectionsPerLane);
}
@@ -83,7 +84,7 @@ class RedisDistributedLeaseAdapterTest {
* An owner with one script connection and almost no patience, so holding it saturates the lane.
*/
private RedisRuntimeOwner narrowOwner() {
return owner(new StubClient(gateway.gateway()), 1, Duration.ofMillis(10));
return owner(StubRedisRuntimeClient.serving(gateway), 1, Duration.ofMillis(10));
}
private RedisDistributedLeaseAdapter adapter(RedisRuntimeOwner owner, Duration driftBudget) {
@@ -179,7 +180,7 @@ class RedisDistributedLeaseAdapterTest {
assertThat(acquired).isInstanceOf(LeaseAcquireOutcome.Acquired.class);
RedisDistributedLeaseAdapter recovering =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseInspectionOutcome inspection =
recovering.inspect(new LeaseInspectionRequest(PURPOSE, RESOURCE, attempt));
@@ -374,7 +375,7 @@ class RedisDistributedLeaseAdapterTest {
void aTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis() {
// given
RedisDistributedLeaseAdapter drifted =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseAttempt attempt = drifted.newAttempt(OPERATION_A);
// when
@@ -392,7 +393,7 @@ class RedisDistributedLeaseAdapterTest {
void aTtlWithinTheDriftBudgetLeavesTheResourceFree() {
// given
RedisDistributedLeaseAdapter drifted =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseAttempt attempt = drifted.newAttempt(OPERATION_A);
// when
@@ -409,7 +410,7 @@ class RedisDistributedLeaseAdapterTest {
void aRenewTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis() {
// given
RedisDistributedLeaseAdapter drifted =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseHandle handle =
((LeaseAcquireOutcome.Acquired)
drifted.tryAcquire(
@@ -436,36 +437,6 @@ class RedisDistributedLeaseAdapterTest {
assertThat(first.ownerToken()).hasSizeGreaterThanOrEqualTo(16);
}
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
private static final class BrokenClient implements RedisRuntimeClient {
@Override
@@ -474,8 +445,7 @@ class RedisDistributedLeaseAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -0,0 +1,45 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.DistributedLeasePort;
import dev.caskeleton.application.lease.testkit.DistributedLeaseContract;
import java.time.Clock;
import java.time.Duration;
import java.util.Map;
import java.util.concurrent.atomic.AtomicLong;
/** The Redis adapter, over the runtime's in-memory commands, held to the port's contract. */
class RedisDistributedLeaseContractTest extends DistributedLeaseContract {
private final InMemorySemanticRedisCommands server = new InMemorySemanticRedisCommands();
private final AtomicLong nanos = new AtomicLong();
@Override
protected DistributedLeasePort newPort() {
return new RedisDistributedLeaseAdapter(
new RedisRuntimeOwner(
StubRedisRuntimeClient.serving(server),
Map.of(RedisConnectionKind.REGULAR, 4, RedisConnectionKind.SCRIPT, 4),
Duration.ofSeconds(1),
Duration.ofSeconds(1)),
new RedisDistributedLeaseAdapter.LeaseKeys(
new RedisNamespace("prod", "ca-skeleton", "shared"), 1),
new LeaseScripts(),
Clock.systemUTC(),
nanos::get,
Duration.ofSeconds(2),
Duration.ofMillis(50),
Duration.ZERO);
}
@Override
protected void elapse(Duration duration) {
server.advance(duration);
nanos.addAndGet(duration.toNanos());
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -1,8 +1,9 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Duration;
import org.junit.jupiter.api.Test;
@@ -2,26 +2,22 @@ package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.shared.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.shared.ratelimit.RateLimitDecision;
import dev.caskeleton.shared.ratelimit.RateLimitEvaluationDedupPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.shared.ratelimit.RateLimitOutcome;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitRequest;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.Map;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -47,18 +43,18 @@ class RedisEdgeRateLimitAdapterTest {
private static final String EVALUATION_ID = "ev1:AAAAAAAAAAAAAAAAAAAAAA";
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final RateLimitKeys keys =
new RateLimitKeys(new RedisNamespace("prod", "ca-skeleton", "shared"), 1);
private RedisEdgeRateLimitAdapter adapter(RateLimitPolicy policy, Clock clock) {
return adapter(policy, clock, new StubClient(gateway.gateway()));
return adapter(policy, clock, StubRedisRuntimeClient.serving(gateway));
}
private RedisEdgeRateLimitAdapter adapter(
RateLimitPolicy policy, Clock clock, RedisRuntimeClient client) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 4);
}
@@ -269,35 +265,6 @@ class RedisEdgeRateLimitAdapterTest {
}
/** Hands out the shared in-memory gateway; the owner's pooling makes it one logical server. */
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
/** A server that cannot be reached at all. */
private static final class BrokenClient implements RedisRuntimeClient {
@@ -308,8 +275,7 @@ class RedisEdgeRateLimitAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -580,8 +580,8 @@ holder 가 락을 잡을 수 있다.
`spring.jpa.open-in-view`가 암묵 기본값일 때 WARN 만 찍을 뿐 명시적으로 `true`로 설정한 배포는
막지 못한다. WARN 은 놓치기 쉬우므로, resolved 값이 `true`면 운영자가 실제 설정한
`APP_DATASOURCE_OPEN_IN_VIEW` 키를 메시지에 담아 부팅을 실패시킨다.
- **읽기만 하고 re-bind 하지 않으며, 부재 값은 Spring 기본에 맡긴다.** `SmartInitializingSingleton`
으로 한 번만 검사하고, 값이 *없으면* Spring Boot 기본(이 스켈레톤은 `application.yml`에서 OSIV off
- **읽기만 하고 re-bind 하지 않으며, 부재 값은 Spring 기본에 맡긴다.** `StartupRule`로 위반만
돌려주고 support의 `StartupRuleRunner`가 모든 싱글톤 생성 후 한 번 실행하며, 값이 *없으면* Spring Boot 기본(이 스켈레톤은 `application.yml`에서 OSIV off
가 기본)에 맡기며 *있는 `true`*만 거부한다.
### JpaDangerousConfigurationGuard (ddl-auto)
@@ -2,55 +2,53 @@ package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.runtime.RuntimeProfileSnapshot;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import org.springframework.beans.factory.SmartInitializingSingleton;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.ArrayList;
import java.util.List;
import org.springframework.core.env.Environment;
/**
* Keeps the Flyway prod safety nets on; raises PROFILE_MISMATCH (exit 71) when an override
* re-enables a forbidden option. See README for the design rationale.
*/
class FlywayProdSafetyValidator implements SmartInitializingSingleton {
class FlywayProdSafetyValidator implements StartupRule {
static final String BASELINE_ON_MIGRATE_KEY = "spring.flyway.baseline-on-migrate";
static final String OUT_OF_ORDER_KEY = "spring.flyway.out-of-order";
static final String CLEAN_DISABLED_KEY = "spring.flyway.clean-disabled";
private final Environment environment;
public FlywayProdSafetyValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.PROFILE_CHECK;
}
@Override
public void afterSingletonsInstantiated() {
public String summary() {
return "prod profile forbids these Flyway options (feature-migration-startup-contract D2/D4)";
}
@Override
public String remedy() {
return "partial-schema recovery goes through runbook://migration/manual-recovery, never an"
+ " in-prod Flyway repair.";
}
@Override
public List<String> violations(Environment environment) {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return;
return List.of();
}
StartupValidationContext violations =
StartupValidationContext.forPhase(StartupPhase.PROFILE_CHECK);
if (isTrue(BASELINE_ON_MIGRATE_KEY)) {
violations.reject(
BASELINE_ON_MIGRATE_KEY + "=true (removes the missing-migration safety net)");
List<String> violations = new ArrayList<>();
if (Boolean.parseBoolean(environment.getProperty(BASELINE_ON_MIGRATE_KEY))) {
violations.add(BASELINE_ON_MIGRATE_KEY + "=true (removes the missing-migration safety net)");
}
if (isTrue(OUT_OF_ORDER_KEY)) {
violations.reject(OUT_OF_ORDER_KEY + "=true (breaks migration ordering consistency)");
if (Boolean.parseBoolean(environment.getProperty(OUT_OF_ORDER_KEY))) {
violations.add(OUT_OF_ORDER_KEY + "=true (breaks migration ordering consistency)");
}
if (isFalse(CLEAN_DISABLED_KEY)) {
violations.reject(CLEAN_DISABLED_KEY + "=false (re-arms destructive Flyway clean)");
String cleanDisabled = environment.getProperty(CLEAN_DISABLED_KEY);
if (cleanDisabled != null && "false".equalsIgnoreCase(cleanDisabled.trim())) {
violations.add(CLEAN_DISABLED_KEY + "=false (re-arms destructive Flyway clean)");
}
violations.failIfViolated(
"prod profile forbids these Flyway options (feature-migration-startup-contract D2/D4)",
"partial-schema recovery goes through runbook://migration/manual-recovery, never an"
+ " in-prod Flyway repair.");
}
private boolean isTrue(String key) {
return Boolean.parseBoolean(environment.getProperty(key));
}
private boolean isFalse(String key) {
String value = environment.getProperty(key);
return value != null && "false".equalsIgnoreCase(value.trim());
return violations;
}
}
@@ -1,19 +1,19 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import java.time.temporal.ChronoUnit;
import org.springframework.beans.factory.SmartInitializingSingleton;
import java.util.List;
import org.springframework.boot.convert.DurationStyle;
import org.springframework.core.env.Environment;
/**
* Fail-fast startup guard for HikariCP inter-knob constraints. Reads (never re-binds) resolved
* Spring properties as a {@link SmartInitializingSingleton}; an absent property is skipped. See
* README for the design rationale.
* Spring properties as a {@link StartupRule}; an absent property is skipped. See README for the
* design rationale.
*/
class HikariPoolConstraintValidator implements SmartInitializingSingleton {
class HikariPoolConstraintValidator implements StartupRule {
static final String CONNECTION_TIMEOUT_KEY = "spring.datasource.hikari.connection-timeout";
static final String VALIDATION_TIMEOUT_KEY = "spring.datasource.hikari.validation-timeout";
@@ -29,14 +29,18 @@ class HikariPoolConstraintValidator implements SmartInitializingSingleton {
static final String MAX_LIFETIME_ENV_KEY = "APP_DATASOURCE_POOL_MAX_LIFETIME";
static final String ENV_KEY_PENDING = "env key pending feature-env-driven-runtime-configuration";
private final Environment environment;
public HikariPoolConstraintValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.ENV_VALIDATION;
}
@Override
public void afterSingletonsInstantiated() {
public String summary() {
return "invalid HikariCP configuration (feature-database-connection-pool-contract D2/D4/D5/D7)";
}
@Override
public List<String> violations(Environment environment) {
StartupValidationContext violations =
StartupValidationContext.forPhase(StartupPhase.ENV_VALIDATION);
@@ -56,14 +60,17 @@ class HikariPoolConstraintValidator implements SmartInitializingSingleton {
}
Long connectionTimeout =
parseMillis(CONNECTION_TIMEOUT_KEY, environment.getProperty(CONNECTION_TIMEOUT_KEY));
parseMillis(
CONNECTION_TIMEOUT_KEY, environment.getProperty(CONNECTION_TIMEOUT_KEY), violations);
Long validationTimeout =
parseMillis(VALIDATION_TIMEOUT_KEY, environment.getProperty(VALIDATION_TIMEOUT_KEY));
parseMillis(
VALIDATION_TIMEOUT_KEY, environment.getProperty(VALIDATION_TIMEOUT_KEY), violations);
Long keepaliveTime =
parseMillis(KEEPALIVE_TIME_KEY, environment.getProperty(KEEPALIVE_TIME_KEY));
Long maxLifetime = parseMillis(MAX_LIFETIME_KEY, environment.getProperty(MAX_LIFETIME_KEY));
parseMillis(KEEPALIVE_TIME_KEY, environment.getProperty(KEEPALIVE_TIME_KEY), violations);
Long maxLifetime =
parseMillis(MAX_LIFETIME_KEY, environment.getProperty(MAX_LIFETIME_KEY), violations);
Long leakDetection =
parseMillis(LEAK_DETECTION_KEY, environment.getProperty(LEAK_DETECTION_KEY));
parseMillis(LEAK_DETECTION_KEY, environment.getProperty(LEAK_DETECTION_KEY), violations);
if (connectionTimeout != null && connectionTimeout < 250L) {
violations.reject(
@@ -120,28 +127,30 @@ class HikariPoolConstraintValidator implements SmartInitializingSingleton {
+ leakDetection);
}
violations.failIfViolated(
"invalid HikariCP configuration (feature-database-connection-pool-contract D2/D4/D5/D7)");
return violations.violations();
}
/**
* Parses the same plain-millisecond, simple Duration ({@code 5s}) and ISO-8601 ({@code PT5S})
* syntax that Spring Boot accepts for Duration-bound properties. A present invalid value is a
* startup error, never an absent-property fallback.
* startup error, never an absent-property fallback: it is recorded as a violation, and the
* constraints that would read it are skipped.
*
* @return the parsed milliseconds, or {@code null} when absent
*/
private static Long parseMillis(String propertyKey, String raw) {
private static Long parseMillis(
String propertyKey, String raw, StartupValidationContext violations) {
if (raw == null || raw.isBlank()) {
return null;
}
try {
return DurationStyle.detectAndParse(raw.trim(), ChronoUnit.MILLIS).toMillis();
} catch (IllegalArgumentException | ArithmeticException e) {
throw StartupFailures.envValidation(
violations.reject(
propertyKey
+ " must be a valid duration (plain milliseconds, simple duration such as 5s, "
+ "or ISO-8601 such as PT5S)");
return null;
}
}
}
@@ -58,36 +58,34 @@ class JpaStartupAutoConfiguration {
/** Env-validation (exit 78): datasource connection env present before migration runs. */
@Bean
RequiredEnvironmentValidator requiredEnvironmentValidator(Environment environment) {
return new RequiredEnvironmentValidator(environment);
RequiredEnvironmentValidator requiredEnvironmentValidator() {
return new RequiredEnvironmentValidator();
}
/** Profile check (exit 71): forbidden Flyway options stay off under the prod profile. */
@Bean
FlywayProdSafetyValidator flywayProdSafetyValidator(Environment environment) {
return new FlywayProdSafetyValidator(environment);
FlywayProdSafetyValidator flywayProdSafetyValidator() {
return new FlywayProdSafetyValidator();
}
@Bean
OpenInViewSafetyValidator openInViewSafetyValidator(Environment environment) {
return new OpenInViewSafetyValidator(environment);
OpenInViewSafetyValidator openInViewSafetyValidator() {
return new OpenInViewSafetyValidator();
}
@Bean
PostgreSqlTransportSecurityValidator postgreSqlTransportSecurityValidator(
Environment environment) {
return new PostgreSqlTransportSecurityValidator(environment);
PostgreSqlTransportSecurityValidator postgreSqlTransportSecurityValidator() {
return new PostgreSqlTransportSecurityValidator();
}
@Bean
PersistenceVendorProdSafetyValidator persistenceVendorProdSafetyValidator(
Environment environment) {
return new PersistenceVendorProdSafetyValidator(environment);
PersistenceVendorProdSafetyValidator persistenceVendorProdSafetyValidator() {
return new PersistenceVendorProdSafetyValidator();
}
@Bean
HikariPoolConstraintValidator hikariPoolConstraintValidator(Environment environment) {
return new HikariPoolConstraintValidator(environment);
HikariPoolConstraintValidator hikariPoolConstraintValidator() {
return new HikariPoolConstraintValidator();
}
/** The datasource product and version validator. */
@@ -1,7 +1,8 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import org.springframework.beans.factory.SmartInitializingSingleton;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.List;
import org.springframework.core.env.Environment;
/**
@@ -10,32 +11,35 @@ import org.springframework.core.env.Environment;
* to Spring Boot's default and only a present {@code true} is rejected. See README for the design
* rationale.
*/
class OpenInViewSafetyValidator implements SmartInitializingSingleton {
class OpenInViewSafetyValidator implements StartupRule {
static final String OPEN_IN_VIEW_KEY = "spring.jpa.open-in-view";
static final String ENV_KEY = "APP_DATASOURCE_OPEN_IN_VIEW";
private final Environment environment;
public OpenInViewSafetyValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.ENV_VALIDATION;
}
@Override
public void afterSingletonsInstantiated() {
public String summary() {
return ENV_KEY
+ " ("
+ OPEN_IN_VIEW_KEY
+ ") must be false (feature-persistence-failure-baseline D2 — OSIV off baseline)";
}
@Override
public List<String> violations(Environment environment) {
Boolean openInView = environment.getProperty(OPEN_IN_VIEW_KEY, Boolean.class);
if (Boolean.TRUE.equals(openInView)) {
throw StartupFailures.envValidation(
ENV_KEY
+ " ("
+ OPEN_IN_VIEW_KEY
+ ") must be false "
+ "(feature-persistence-failure-baseline D2 — OSIV off baseline): "
+ "open-in-view keeps the Hibernate session open through view rendering, "
+ "so a lazy association touched in the presentation layer issues a DB query "
+ "there, violating the layer boundary. Set "
+ ENV_KEY
+ "=false.");
if (!Boolean.TRUE.equals(openInView)) {
return List.of();
}
return List.of(
"open-in-view keeps the Hibernate session open through view rendering, "
+ "so a lazy association touched in the presentation layer issues a DB query "
+ "there, violating the layer boundary. Set "
+ ENV_KEY
+ "=false.");
}
}
@@ -1,9 +1,10 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.runtime.RuntimeProfileSnapshot;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.List;
import java.util.Locale;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.core.env.Environment;
/**
@@ -30,7 +31,7 @@ import org.springframework.core.env.Environment;
* <p>Scoped to H2 by name rather than asserting "must be PostgreSQL", so a fork that adds a third
* production-grade vendor is not blocked by this validator.
*/
final class PersistenceVendorProdSafetyValidator implements SmartInitializingSingleton {
final class PersistenceVendorProdSafetyValidator implements StartupRule {
static final String VENDOR_KEY = "ca-skeleton.persistence.vendor";
static final String JDBC_URL_KEY = "spring.datasource.url";
@@ -39,32 +40,34 @@ final class PersistenceVendorProdSafetyValidator implements SmartInitializingSin
private static final String H2_VENDOR = "h2";
private static final String H2_URL_PREFIX = "jdbc:h2:";
private final Environment environment;
public PersistenceVendorProdSafetyValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.PROFILE_CHECK;
}
@Override
public void afterSingletonsInstantiated() {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return;
}
public String summary() {
return "prod profile forbids the in-memory local datastore";
}
@Override
public List<String> violations(Environment environment) {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return List.of();
}
String vendor = normalized(environment.getProperty(VENDOR_KEY));
if (H2_VENDOR.equals(vendor)) {
throw StartupFailures.profileMismatch(
return List.of(
"prod profile forbids "
+ VENDOR_KEY
+ "=h2: the H2 composition is the in-memory local datastore and loses every write"
+ " when the process restarts");
}
String jdbcUrl = normalized(environment.getProperty(JDBC_URL_KEY));
// The URL is never echoed back — it can carry credentials, endpoints and database names
// (same reason as PostgreSqlTransportSecurityValidator).
if (jdbcUrl != null && jdbcUrl.startsWith(H2_URL_PREFIX)) {
throw StartupFailures.profileMismatch(
return List.of(
"prod profile forbids an H2 datasource: "
+ JDBC_URL_ENV_KEY
+ " ("
@@ -72,6 +75,7 @@ final class PersistenceVendorProdSafetyValidator implements SmartInitializingSin
+ ") resolves to a jdbc:h2: URL, which is the in-memory local datastore and also"
+ " bypasses the prod PostgreSQL TLS check");
}
return List.of();
}
private static String normalized(String value) {
@@ -1,13 +1,13 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.runtime.RuntimeProfileSnapshot;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.core.env.Environment;
/**
@@ -16,7 +16,7 @@ import org.springframework.core.env.Environment;
* <p>The validator never includes a JDBC URL in its failure because URLs can carry credentials,
* endpoints, and database names.
*/
final class PostgreSqlTransportSecurityValidator implements SmartInitializingSingleton {
final class PostgreSqlTransportSecurityValidator implements StartupRule {
static final String JDBC_URL_KEY = "spring.datasource.url";
static final String JDBC_URL_ENV_KEY = "APP_DATASOURCE_URL";
@@ -27,36 +27,38 @@ final class PostgreSqlTransportSecurityValidator implements SmartInitializingSin
private static final String VERIFY_FULL = "verify-full";
private static final Pattern URL_SSLMODE = Pattern.compile("(?i)(?:[?&])sslmode=([^&]*)");
private final Environment environment;
public PostgreSqlTransportSecurityValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.PROFILE_CHECK;
}
@Override
public void afterSingletonsInstantiated() {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return;
}
public String summary() {
return "prod PostgreSQL transport security is not verified";
}
@Override
public List<String> violations(Environment environment) {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return List.of();
}
String jdbcUrl = environment.getProperty(JDBC_URL_KEY);
if (jdbcUrl == null || !jdbcUrl.trim().toLowerCase(Locale.ROOT).startsWith(POSTGRESQL_PREFIX)) {
return;
return List.of();
}
List<String> urlModes = urlSslModes(jdbcUrl);
String propertyMode = normalized(environment.getProperty(HIKARI_SSLMODE_KEY));
// The first finding only, as before: each one makes the next meaningless.
if (urlModes.size() > 1) {
reject("prod PostgreSQL transport has ambiguous duplicate sslmode declarations");
return List.of("prod PostgreSQL transport has ambiguous duplicate sslmode declarations");
}
String urlMode = urlModes.isEmpty() ? null : urlModes.getFirst();
if (urlMode != null && propertyMode != null && !urlMode.equals(propertyMode)) {
reject("prod PostgreSQL transport has conflicting sslmode declarations");
return List.of("prod PostgreSQL transport has conflicting sslmode declarations");
}
String effectiveMode = propertyMode != null ? propertyMode : urlMode;
if (!VERIFY_FULL.equals(effectiveMode)) {
reject(
return List.of(
"prod PostgreSQL transport requires pgJDBC sslmode=verify-full through "
+ JDBC_URL_ENV_KEY
+ " ("
@@ -64,6 +66,7 @@ final class PostgreSqlTransportSecurityValidator implements SmartInitializingSin
+ ") or "
+ HIKARI_SSLMODE_KEY);
}
return List.of();
}
private static List<String> urlSslModes(String jdbcUrl) {
@@ -78,8 +81,4 @@ final class PostgreSqlTransportSecurityValidator implements SmartInitializingSin
private static String normalized(String value) {
return value == null ? null : value.trim().toLowerCase(Locale.ROOT);
}
private static void reject(String message) {
throw StartupFailures.profileMismatch(message);
}
}
@@ -1,9 +1,9 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.List;
import java.util.Map;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.core.env.Environment;
/**
@@ -11,37 +11,36 @@ import org.springframework.core.env.Environment;
* migration fails with an opaque driver error. Absent or blank counts as missing. See README for
* the design rationale.
*/
class RequiredEnvironmentValidator implements SmartInitializingSingleton {
class RequiredEnvironmentValidator implements StartupRule {
/** Spring property key → operator-facing env key (named in the failure message). */
static final Map<String, String> REQUIRED_DATASOURCE_ENV =
Map.of(
"spring.datasource.url", "APP_DATASOURCE_URL",
"spring.datasource.username", "APP_DATASOURCE_USERNAME",
"spring.datasource.driver-class-name", "APP_DATASOURCE_DRIVER");
private final Environment environment;
public RequiredEnvironmentValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.ENV_VALIDATION;
}
@Override
public void afterSingletonsInstantiated() {
StartupValidationContext missing =
StartupValidationContext.forPhase(StartupPhase.ENV_VALIDATION);
public String summary() {
return "required datasource environment is missing or blank — a Flyway migration"
+ " cannot run without it";
}
@Override
public List<String> violations(Environment environment) {
// Sorted for a stable, deterministic message regardless of map iteration order.
REQUIRED_DATASOURCE_ENV.entrySet().stream()
return REQUIRED_DATASOURCE_ENV.entrySet().stream()
.sorted(Map.Entry.comparingByValue())
.forEach(
.filter(
entry -> {
String value = environment.getProperty(entry.getKey());
if (value == null || value.isBlank()) {
missing.reject(entry.getValue() + " (" + entry.getKey() + ")");
}
});
missing.failIfViolated(
"required datasource environment is missing or blank — a Flyway migration"
+ " cannot run without it");
return value == null || value.isBlank();
})
.map(entry -> entry.getValue() + " (" + entry.getKey() + ")")
.toList();
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.assertj.AssertableApplicationContext;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
@@ -21,7 +22,8 @@ import org.springframework.core.env.Environment;
class FlywayProdSafetyValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@Test
void prodProfileWithPinnedSafeDefaultsStartsCleanly() {
@@ -110,7 +112,7 @@ class FlywayProdSafetyValidatorTest {
static class ValidatorConfig {
@Bean
FlywayProdSafetyValidator flywayProdSafetyValidator(Environment environment) {
return new FlywayProdSafetyValidator(environment);
return new FlywayProdSafetyValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
@@ -18,7 +19,8 @@ import org.springframework.core.env.Environment;
class HikariPoolConstraintValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
// --- D2 / HIKARI-CFG-C1: connection-timeout >= 250 ---
@@ -265,7 +267,7 @@ class HikariPoolConstraintValidatorTest {
static class ValidatorConfig {
@Bean
HikariPoolConstraintValidator hikariPoolConstraintValidator(Environment environment) {
return new HikariPoolConstraintValidator(environment);
return new HikariPoolConstraintValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
@@ -19,7 +20,8 @@ import org.springframework.core.env.Environment;
class OpenInViewSafetyValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@Test
void openInViewTrueFailsStartupNamingTheAppKey() {
@@ -71,7 +73,7 @@ class OpenInViewSafetyValidatorTest {
static class ValidatorConfig {
@Bean
OpenInViewSafetyValidator openInViewSafetyValidator(Environment environment) {
return new OpenInViewSafetyValidator(environment);
return new OpenInViewSafetyValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import java.io.PrintWriter;
import java.io.StringWriter;
import org.junit.jupiter.api.Test;
@@ -20,7 +21,8 @@ class PersistenceVendorProdSafetyValidatorTest {
private static final String H2_URL = "jdbc:h2:mem:ca_skeleton;MODE=PostgreSQL";
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@ParameterizedTest
@ValueSource(strings = {"h2", "H2", " h2 "})
@@ -100,7 +102,7 @@ class PersistenceVendorProdSafetyValidatorTest {
@Bean
PersistenceVendorProdSafetyValidator validator(Environment environment) {
return new PersistenceVendorProdSafetyValidator(environment);
return new PersistenceVendorProdSafetyValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import java.io.PrintWriter;
import java.io.StringWriter;
import org.junit.jupiter.api.Test;
@@ -17,7 +18,8 @@ import org.springframework.core.env.Environment;
class PostgreSqlTransportSecurityValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@ParameterizedTest
@ValueSource(
@@ -102,7 +104,7 @@ class PostgreSqlTransportSecurityValidatorTest {
@Bean
PostgreSqlTransportSecurityValidator postgreSqlTransportSecurityValidator(
Environment environment) {
return new PostgreSqlTransportSecurityValidator(environment);
return new PostgreSqlTransportSecurityValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.assertj.AssertableApplicationContext;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
@@ -20,7 +21,8 @@ import org.springframework.core.env.Environment;
class RequiredEnvironmentValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@Test
void allDatasourceEnvPresentStartsCleanly() {
@@ -80,7 +82,7 @@ class RequiredEnvironmentValidatorTest {
static class ValidatorConfig {
@Bean
RequiredEnvironmentValidator requiredEnvironmentValidator(Environment environment) {
return new RequiredEnvironmentValidator(environment);
return new RequiredEnvironmentValidator();
}
}
}
@@ -1,6 +1,6 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.api;
package dev.caskeleton.adapter.outbound.cache.redis.runtime;
/** Redis deployment topology the SDK is bound to. */
/** Redis deployment topology the runtime's client is bound to. */
public enum RedisDeploymentMode {
/** Single primary, optional replicas, any database index. */
STANDALONE,
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.cluster;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.cluster;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
@@ -0,0 +1,91 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.command;
import io.lettuce.core.RedisFuture;
import io.lettuce.core.ScriptOutputType;
import io.lettuce.core.SetArgs;
import io.lettuce.core.cluster.api.async.RedisClusterAsyncCommands;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.CompletionStage;
/**
* {@link SemanticRedisCommands} on a Lettuce connection.
*
* <p>Bound to {@code byte[]} keys and values: rendering and encoding happened in the caller, so
* nothing here can reinterpret a key or pick a codec.
*/
public final class LettuceSemanticRedisCommands implements SemanticRedisCommands {
private static final String OK = "OK";
private final RedisClusterAsyncCommands<byte[], byte[]> commands;
/**
* Creates the commands over a connection's asynchronous surface.
*
* @param commands the standalone or slot-routing asynchronous commands of one connection
*/
public LettuceSemanticRedisCommands(RedisClusterAsyncCommands<byte[], byte[]> commands) {
this.commands = Objects.requireNonNull(commands, "commands must be non-null");
}
@Override
public CompletionStage<byte[]> get(byte[] key) {
return commands.get(key);
}
@Override
public CompletionStage<Boolean> set(
byte[] key, byte[] value, WritePresence presence, Duration ttl) {
Objects.requireNonNull(ttl, "ttl must be non-null");
if (ttl.isZero() || ttl.isNegative()) {
throw new IllegalArgumentException("ttl must be positive");
}
SetArgs arguments =
switch (presence) {
case IF_ABSENT -> new SetArgs().nx();
case IF_PRESENT -> new SetArgs().xx();
case ALWAYS -> new SetArgs();
};
return commands.set(key, value, arguments.px(ttl)).thenApply(OK::equals);
}
@Override
public CompletionStage<byte[]> getAndDelete(byte[] key) {
return commands.getdel(key);
}
@Override
public CompletionStage<Long> incrementBy(byte[] key, long delta) {
return commands.incrby(key, delta);
}
@Override
public CompletionStage<String> ping() {
return commands.ping();
}
@Override
public CompletionStage<String> loadScript(byte[] source) {
return commands.scriptLoad(source);
}
@Override
public CompletionStage<List<Object>> evaluateRegisteredForList(
String digest, byte[] key, List<byte[]> arguments) {
return commands
.<List<Object>>evalsha(
digest, ScriptOutputType.MULTI, new byte[][] {key}, arguments.toArray(byte[][]::new))
.thenApply(reply -> reply == null ? List.of() : reply);
}
@Override
public CompletionStage<Long> evaluateRegisteredForLong(
String digest, byte[] key, List<byte[]> arguments) {
RedisFuture<Long> reply =
commands.evalsha(
digest, ScriptOutputType.INTEGER, new byte[][] {key}, arguments.toArray(byte[][]::new));
return reply;
}
}
@@ -0,0 +1,96 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.command;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.CompletionStage;
/**
* The commands the runtime's own consumers send: the semantic adapters in {@code cache-redis} and
* the health contributor.
*
* <p>Eight commands and no more. The runtime used to hand every lane a gateway carrying the typed
* SDK's whole surface — about 118 commands, raw and admin paths included — so a leaf that needed a
* cache read and a script call compiled against streams, geo and cluster admin. The rest of that
* surface is the typed SDK's own ({@code redis-sdk}), which extends this interface rather than the
* runtime carrying it on the SDK's behalf.
*
* <p>Keys and values are already rendered and encoded. Nothing here picks a codec or a key.
*/
public interface SemanticRedisCommands {
/**
* Reads a value.
*
* @param key the rendered key
* @return the stored bytes, {@code null} when the key does not exist
*/
CompletionStage<byte[]> get(byte[] key);
/**
* Writes a value with an existence condition and a relative expiry, as one command.
*
* @param key the rendered key
* @param value the encoded value
* @param presence the existence condition
* @param ttl the positive time to live the write carries
* @return whether the write was applied
*/
CompletionStage<Boolean> set(byte[] key, byte[] value, WritePresence presence, Duration ttl);
/**
* Reads and removes a value as one command.
*
* @param key the rendered key
* @return the removed bytes, {@code null} when the key did not exist
*/
CompletionStage<byte[]> getAndDelete(byte[] key);
/**
* Increments an integer counter without touching its expiry.
*
* @param key the rendered key
* @param delta the increment
* @return the value after the increment
*/
CompletionStage<Long> incrementBy(byte[] key, long delta);
/**
* Sends a keyless liveness round trip.
*
* <p>Keyless on purpose: a probe that touched a key would be subject to the ACL key pattern and
* report "unhealthy" for reasons that have nothing to do with reachability.
*
* @return the server's reply
*/
CompletionStage<String> ping();
/**
* Registers a script and returns its digest.
*
* @param source the script source
* @return the digest the server assigned
*/
CompletionStage<String> loadScript(byte[] source);
/**
* Evaluates a registered single-key script whose reply is an array.
*
* @param digest the loaded script digest
* @param key the single key the script touches
* @param arguments the script arguments
* @return the reply values
*/
CompletionStage<List<Object>> evaluateRegisteredForList(
String digest, byte[] key, List<byte[]> arguments);
/**
* Evaluates a registered single-key script whose reply is an integer.
*
* @param digest the loaded script digest
* @param key the single key the script touches
* @param arguments the script arguments
* @return the integer reply
*/
CompletionStage<Long> evaluateRegisteredForLong(
String digest, byte[] key, List<byte[]> arguments);
}
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.command;
/**
* The existence condition a {@code SET} carries.
@@ -0,0 +1,30 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisAccount;
import java.util.Objects;
/**
* An account another module's lanes authenticate as, and where its credential comes from.
*
* <p>Declared as a bean by the module (or the service) that composes the lanes. {@link
* RedisRuntimeAutoConfiguration} resolves the reference through the same secret source as its own
* accounts, before any client exists, and builds a client authenticated as it. A reference that
* does not resolve fails startup rather than the first command.
*
* @param account the account
* @param credentialReference the credential reference, in the runtime's {@code secret://} form
*/
public record RedisAccountContribution(RedisAccount account, String credentialReference) {
public RedisAccountContribution {
Objects.requireNonNull(account, "account must be non-null");
if (RedisAccount.APPLICATION.equals(account) || RedisAccount.ADVANCED.equals(account)) {
throw new IllegalArgumentException(
"the " + account + " account is the runtime's own and is configured in app.redis");
}
if (credentialReference == null || credentialReference.isBlank()) {
throw new IllegalArgumentException(
"the " + account + " account needs a credential reference");
}
}
}
@@ -0,0 +1,30 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import org.springframework.core.env.Environment;
/**
* A module's answer to "does this deployment need Redis for correctness?".
*
* <p>Registered under this interface's name in {@code META-INF/spring.factories} by the module that
* owns the roles, and read through {@link RedisCorrectnessRoles}. Implementations need a public
* no-argument constructor and must decide from the environment alone: they run before any bean
* exists.
*/
public interface RedisCorrectnessRequirement {
/**
* Reports whether a role this module owns selected Redis for correctness.
*
* @param environment the resolved environment
* @return {@code true} when readiness must gate on Redis
*/
boolean required(Environment environment);
/**
* Reports whether such a role runs registered scripts on the SCRIPT lane.
*
* @param environment the resolved environment
* @return {@code true} when the SCRIPT lane carries a correctness role
*/
boolean requiresScriptLane(Environment environment);
}
@@ -0,0 +1,65 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import java.util.List;
import org.springframework.core.env.Environment;
import org.springframework.core.io.support.SpringFactoriesLoader;
/**
* Whether this deployment needs Redis for <em>correctness</em> rather than for speed.
*
* <p>A role such as idempotency or rate limiting produces a wrong answer when Redis is gone, not a
* slow one, so a deployment that selected one gates its readiness on Redis. A cache does not — its
* outage is degradation.
*
* <p>The runtime does not know which roles exist or how they are selected: that belongs to the
* modules that implement them (for the semantic ports, {@code cache-redis}). Each such module
* registers a {@link RedisCorrectnessRequirement} in {@code META-INF/spring.factories}, and this
* class only asks them. Environment post-processors run before any bean exists, and the readiness
* group must be decided there, so a factories entry rather than a bean is the one mechanism both
* readers can use.
*
* <p>The question is asked in two places that must never disagree: the condition that creates the
* {@code redisRequired} contributor, and the post-processor that lets the readiness group name it.
* When those drifted apart every Redis-off deployment failed at startup with {@code Included health
* contributor 'redisRequired' in group 'readiness' does not exist}. One predicate, two readers.
*/
public final class RedisCorrectnessRoles {
/** The bean name of the readiness-gating health contributor. */
public static final String REQUIRED_HEALTH_CONTRIBUTOR = "redisRequired";
/** The bean name of the degradation-only health contributor. */
public static final String OPTIONAL_HEALTH_CONTRIBUTOR = "redisOptional";
private RedisCorrectnessRoles() {
throw new AssertionError("RedisCorrectnessRoles is a constant holder");
}
/**
* Reports whether any registered module needs Redis for correctness in this environment.
*
* @param environment the resolved environment
* @return {@code true} when readiness must gate on Redis
*/
public static boolean anySelected(Environment environment) {
return requirements().stream().anyMatch(requirement -> requirement.required(environment));
}
/**
* Reports whether a correctness role that runs registered scripts is selected, so the SCRIPT lane
* — which authenticates as the advanced account — has to be probed as well.
*
* @param environment the resolved environment
* @return {@code true} when the SCRIPT lane carries a correctness role
*/
public static boolean anyScriptRoleSelected(Environment environment) {
return requirements().stream()
.anyMatch(requirement -> requirement.requiresScriptLane(environment));
}
private static List<RedisCorrectnessRequirement> requirements() {
return SpringFactoriesLoader.forDefaultResourceLocation(
RedisCorrectnessRoles.class.getClassLoader())
.load(RedisCorrectnessRequirement.class);
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import java.util.Objects;
import java.util.Optional;
@@ -1,9 +1,9 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisCommandRejectedException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLaneUnavailableException;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.LinkedHashMap;
@@ -87,25 +87,25 @@ public final class RedisHealthContributor {
// A round trip, not a flag. `isOpen()` on a driver connection reports what the client
// believes, which stays true for as long as it takes TCP to notice — the window in which a
// health check is most likely to be wrong is exactly the window it exists to catch.
reply = lease.gateway().ping().toCompletableFuture().get(nanos(), TimeUnit.NANOSECONDS);
reply = lease.commands().ping().toCompletableFuture().get(nanos(), TimeUnit.NANOSECONDS);
}
if (scriptProbeKey.isPresent()) {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
String digest =
lease
.gateway()
.commands()
.loadScript(SCRIPT_PROBE)
.toCompletableFuture()
.get(nanos(), TimeUnit.NANOSECONDS);
lease
.gateway()
.commands()
.evaluateRegisteredForLong(digest, scriptProbeKey.get(), List.of())
.toCompletableFuture()
.get(nanos(), TimeUnit.NANOSECONDS);
}
}
return new RedisHealth(true, detail("reachable", String.valueOf(reply)));
} catch (RedisCommandRejectedException refused) {
} catch (RedisLaneUnavailableException refused) {
// A refusal is raised before any command exists: either shutdown began, or the lane is full.
return owner.state() != RedisRuntimeOwner.State.OPEN
? shuttingDown()
@@ -0,0 +1,25 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import java.util.Objects;
/**
* A lane another module composes on the runtime, and its connection ceiling.
*
* <p>Declared as a bean by the module (or the service) that uses the lane; {@link
* RedisRuntimeAutoConfiguration} pools and drains it with the runtime's own lanes. The runtime
* knows nothing about a contributed lane beyond its account and ceiling.
*
* @param lane the lane
* @param maximumConnections how many connections the lane may hold at once
*/
public record RedisLaneContribution(RedisLane lane, int maximumConnections) {
public RedisLaneContribution {
Objects.requireNonNull(lane, "lane must be non-null");
if (maximumConnections < 1) {
throw new IllegalArgumentException(
"connection lane " + lane.name() + " needs a positive ceiling");
}
}
}
@@ -1,13 +1,14 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisCredentialRole;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisAccount;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.nio.charset.StandardCharsets;
import java.util.EnumMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
@@ -34,7 +35,7 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
* The Redis composition root, and the only place Redis settings come into existence.
*
* <p>{@code app.redis.enabled} is the whole switch. While it is false this class contributes
* nothing, and because {@link RedisSdkSettings} is registered here rather than by the
* nothing, and because {@link RedisRuntimeSettings} is registered here rather than by the
* application-wide {@code @ConfigurationPropertiesScan}, "contributes nothing" is literal: the
* properties are not bound, the cross-field rules are not run, no credential is resolved, and no
* policy resource, TLS material, client, connection or thread is created. A deployment that does
@@ -43,7 +44,7 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
*
* <p>While it is true the order is fixed and entirely local: bind, validate, then build. Validation
* runs at context refresh, before anything can reach the network, which is what makes {@link
* RedisSdkSettings#validate()} the fail-fast its own documentation claims — until this class
* RedisRuntimeSettings#validate()} the fail-fast its own documentation claims — until this class
* existed the method had no production caller at all.
*
* <p>Roles — cache, session, idempotency, rate limiting, leases — select <em>which</em> Redis
@@ -56,9 +57,9 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
// Without it the bean is created and silently left at its defaults, which is worse than not
// binding at all: validation would pass on settings nobody configured.
@EnableConfigurationProperties
public class RedisSdkAutoConfiguration {
public class RedisRuntimeAutoConfiguration {
private static final Logger LOG = LoggerFactory.getLogger(RedisSdkAutoConfiguration.class);
private static final Logger LOG = LoggerFactory.getLogger(RedisRuntimeAutoConfiguration.class);
/**
* The status an optional Redis reports when it is unreachable.
@@ -82,15 +83,15 @@ public class RedisSdkAutoConfiguration {
*/
@Bean
@ConfigurationProperties(prefix = "app.redis")
public RedisSdkSettings redisSdkSettings() {
return new RedisSdkSettings();
public RedisRuntimeSettings redisRuntimeSettings() {
return new RedisRuntimeSettings();
}
/**
* Runs the cross-field rules once the binder has populated the settings.
*
* <p>Spring binds {@code @ConfigurationProperties} after the factory method returns, so the
* validation cannot live inside {@link #redisSdkSettings()}. A {@code
* validation cannot live inside {@link #redisRuntimeSettings()}. A {@code
* ConfigurationPropertiesBindHandlerAdvisor}-free way to get the same fail-fast is a bean that
* depends on the settings: it is created during refresh, before any Redis client would be, and an
* exception here stops the context.
@@ -99,10 +100,11 @@ public class RedisSdkAutoConfiguration {
* @return the validation outcome, kept as a bean so warnings are inspectable in tests
*/
@Bean
public RedisSdkSettingsValidation redisSdkSettingsValidation(RedisSdkSettings settings) {
public RedisRuntimeSettingsValidation redisRuntimeSettingsValidation(
RedisRuntimeSettings settings) {
List<String> warnings = settings.validate();
warnings.forEach(warning -> LOG.warn("Redis SDK configuration warning: {}", warning));
return new RedisSdkSettingsValidation(warnings);
warnings.forEach(warning -> LOG.warn("Redis configuration warning: {}", warning));
return new RedisRuntimeSettingsValidation(warnings);
}
/**
@@ -114,58 +116,60 @@ public class RedisSdkAutoConfiguration {
*
* @param settings the validated settings
* @param secretSource resolves a secret name to its value
* @param contributedAccounts accounts a module composing lanes on the runtime asked for
* @param validation ordered after validation so a malformed setting is reported first
* @return the resolved credentials
*/
@Bean
public RedisResolvedCredentials redisResolvedCredentials(
RedisSdkSettings settings,
RedisRuntimeSettings settings,
ObjectProvider<RedisSecretSource> secretSource,
RedisSdkSettingsValidation validation) {
ObjectProvider<RedisAccountContribution> contributedAccounts,
RedisRuntimeSettingsValidation validation) {
RedisCredentialResolver resolver =
new RedisCredentialResolver(
name -> secretSource.getIfAvailable(() -> environmentSecretSource()).resolve(name));
Map<RedisCredentialRole, RedisCredentialResolver.RedisCredentials> accounts =
new EnumMap<>(RedisCredentialRole.class);
// Every configured role is resolved, not only the application one. A deployment that named an
// advanced or pub/sub account and got a client that silently authenticated as the application
// account has the privilege separation it configured on paper and nowhere else.
Map<RedisAccount, RedisCredentialResolver.RedisCredentials> accounts = new LinkedHashMap<>();
// Every configured account is resolved, not only the application one. A deployment that named
// an advanced account and got a client that silently authenticated as the application account
// has the privilege separation it configured on paper and nowhere else.
put(
accounts,
RedisCredentialRole.APPLICATION,
RedisAccount.APPLICATION,
resolver.resolve("application", settings.getAuthentication().getCredentialReference()));
put(
accounts,
RedisCredentialRole.ADVANCED,
RedisAccount.ADVANCED,
resolver.resolve(
"advanced", settings.getAuthentication().getAdvancedCredentialReference()));
put(
accounts,
RedisCredentialRole.PUBSUB,
resolver.resolve("pub/sub", settings.getAuthentication().getPubsubCredentialReference()));
if (settings.getAdmin().isEnabled()) {
put(
accounts,
RedisCredentialRole.ADMIN,
resolver.resolve("admin", settings.getAdmin().getCredentialReference()));
}
// A module that composes lanes on the runtime (the typed SDK's admin plane) names its own
// account; the runtime resolves it exactly like its own, before any client exists.
contributedAccounts
.orderedStream()
.forEach(
contribution ->
put(
accounts,
contribution.account(),
resolver.resolve(
contribution.account().name(), contribution.credentialReference())));
Optional<RedisCredentialResolver.RedisCredentials> sentinel =
settings.getMode()
== dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode.SENTINEL
== dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode.SENTINEL
? resolver.resolve("sentinel", settings.getSentinel().getCredentialReference())
: Optional.empty();
LOG.info(
"Redis accounts resolved for roles {}{}",
"Redis accounts resolved: {}{}",
accounts.keySet(),
sentinel.isPresent() ? " plus the Sentinel control account" : "");
return new RedisResolvedCredentials(accounts, sentinel);
}
private static void put(
Map<RedisCredentialRole, RedisCredentialResolver.RedisCredentials> accounts,
RedisCredentialRole role,
Map<RedisAccount, RedisCredentialResolver.RedisCredentials> accounts,
RedisAccount account,
Optional<RedisCredentialResolver.RedisCredentials> resolved) {
resolved.ifPresent(credentials -> accounts.put(role, credentials));
resolved.ifPresent(credentials -> accounts.put(account, credentials));
}
private static RedisSecretSource environmentSecretSource() {
@@ -183,7 +187,7 @@ public class RedisSdkAutoConfiguration {
*/
@Bean
public RedisRuntimeClient redisRuntimeClient(
RedisSdkSettings settings,
RedisRuntimeSettings settings,
RedisResolvedCredentials credentials,
ResourceLoader resourceLoader) {
return new RedisTopologyClientFactory(
@@ -224,20 +228,33 @@ public class RedisSdkAutoConfiguration {
* <p>Destroyed by Spring, and destroyed before the client bean it wraps because it depends on it
* — which is the order shutdown needs: connections drain and close, then the event loop stops.
*
* <p>The runtime's own lanes take their ceilings from the settings. A module that composes
* further lanes on the runtime contributes their ceilings as {@link RedisLaneContribution} beans;
* the runtime pools and drains those exactly like its own, and knows nothing else about them.
*
* @param client the runtime client
* @param settings the validated settings
* @param contributedLanes lanes other modules compose on the runtime
* @return the lifecycle owner
*/
@Bean(destroyMethod = "close")
public RedisRuntimeOwner redisRuntimeOwner(RedisRuntimeClient client, RedisSdkSettings settings) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
public RedisRuntimeOwner redisRuntimeOwner(
RedisRuntimeClient client,
RedisRuntimeSettings settings,
ObjectProvider<RedisLaneContribution> contributedLanes) {
Map<RedisLane, Integer> limits = new LinkedHashMap<>();
limits.put(RedisConnectionKind.REGULAR, settings.getCapacity().getMaximumInFlightCommands());
limits.put(RedisConnectionKind.BLOCKING, settings.getBlocking().getMaxConnections());
limits.put(RedisConnectionKind.TRANSACTION, settings.getTransaction().getMaxConnections());
limits.put(RedisConnectionKind.SCRIPT, settings.getCapacity().getMaximumScriptConnections());
limits.put(
RedisConnectionKind.PUBSUB, Math.max(1, settings.getPubsub().getBufferCapacity() / 64));
limits.put(RedisConnectionKind.ADMIN, settings.getAdmin().isEnabled() ? 2 : 1);
contributedLanes
.orderedStream()
.forEach(
contribution -> {
if (limits.putIfAbsent(contribution.lane(), contribution.maximumConnections())
!= null) {
throw new IllegalStateException(
"Redis lane " + contribution.lane().name() + " was composed twice");
}
});
return new RedisRuntimeOwner(
client,
limits,
@@ -257,7 +274,7 @@ public class RedisSdkAutoConfiguration {
* @return the contributor
*/
@Bean(RedisCorrectnessRoles.OPTIONAL_HEALTH_CONTRIBUTOR)
public HealthIndicator redisOptional(RedisRuntimeOwner owner, RedisSdkSettings settings) {
public HealthIndicator redisOptional(RedisRuntimeOwner owner, RedisRuntimeSettings settings) {
RedisHealthContributor contributor =
new RedisHealthContributor(owner, settings.getTimeout().getFast());
return () -> {
@@ -291,7 +308,7 @@ public class RedisSdkAutoConfiguration {
@Bean(RedisCorrectnessRoles.REQUIRED_HEALTH_CONTRIBUTOR)
@Conditional(RedisCorrectnessRoleBound.class)
public HealthIndicator redisRequired(
RedisRuntimeOwner owner, RedisSdkSettings settings, Environment environment) {
RedisRuntimeOwner owner, RedisRuntimeSettings settings, Environment environment) {
Optional<byte[]> scriptProbeKey =
RedisCorrectnessRoles.anyScriptRoleSelected(environment)
? Optional.of(
@@ -331,17 +348,17 @@ public class RedisSdkAutoConfiguration {
}
/**
* The account resolved for each role the configuration named.
* The credentials resolved for each account the configuration named.
*
* <p>A role that is absent from {@code accounts} has no account of its own and runs on the
* application client. That is a deployment decision, taken by not configuring one, rather than a
* default the SDK picks.
* <p>An account that is absent from {@code accounts} has no credentials of its own and its lanes
* run on the application client. That is a deployment decision, taken by not configuring one,
* rather than a default the runtime picks.
*
* @param accounts the resolved account per configured role
* @param accounts the resolved credentials per configured account
* @param sentinel the Sentinel control account, on a Sentinel deployment
*/
public record RedisResolvedCredentials(
Map<RedisCredentialRole, RedisCredentialResolver.RedisCredentials> accounts,
Map<RedisAccount, RedisCredentialResolver.RedisCredentials> accounts,
Optional<RedisCredentialResolver.RedisCredentials> sentinel) {
public RedisResolvedCredentials {
@@ -367,9 +384,9 @@ public class RedisSdkAutoConfiguration {
*
* @param warnings settings that are within the guardrails but worth an operator's attention
*/
public record RedisSdkSettingsValidation(List<String> warnings) {
public record RedisRuntimeSettingsValidation(List<String> warnings) {
public RedisSdkSettingsValidation {
public RedisRuntimeSettingsValidation {
warnings = List.copyOf(warnings);
}
}
@@ -1,13 +1,17 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisKeyRules;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisKeyRules;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
/**
* Typed configuration for the Redis SDK, bound from {@code app.redis.*}.
* Typed configuration for the Redis runtime, bound from {@code app.redis.*}.
*
* <p>Topology, accounts, TLS, lifecycle and the ceilings of the runtime's own lanes. The typed
* SDK's lanes (blocking, transaction, admin) are not configured here: a module that composes lanes
* on the runtime brings their limits and accounts with it.
*
* <p>Defaults are the skeleton guardrails from the design. Validation is fail-closed and runs at
* startup: a setting that would make a guardrail meaningless — a non-zero database on Cluster, an
@@ -15,12 +19,12 @@ import java.util.List;
* degrading quietly at the first request.
*
* <p>This class carries no {@code @ConfigurationProperties} annotation on purpose. It is registered
* and bound only by {@link RedisSdkAutoConfiguration}, which exists only while {@code
* and bound only by {@link RedisRuntimeAutoConfiguration}, which exists only while {@code
* app.redis.enabled} is true. Annotating the class would put it back inside the application-wide
* {@code @ConfigurationPropertiesScan}, and a Redis-free deployment would once again bind Redis
* configuration — the exact defect this arrangement removes.
*/
public class RedisSdkSettings {
public class RedisRuntimeSettings {
/** Hard ceiling above which a configured timeout is a startup failure. */
public static final Duration MAXIMUM_TIMEOUT = Duration.ofSeconds(30);
@@ -34,16 +38,12 @@ public class RedisSdkSettings {
private int database;
private final Namespace namespace = new Namespace();
private final Timeouts timeout = new Timeouts();
private final Blocking blocking = new Blocking();
private final Transaction transaction = new Transaction();
private final Authentication authentication = new Authentication();
private final Sentinel sentinel = new Sentinel();
private final Tls tls = new Tls();
private final Lifecycle lifecycle = new Lifecycle();
private final Cluster cluster = new Cluster();
private final Capacity capacity = new Capacity();
private final PubSub pubsub = new PubSub();
private final Admin admin = new Admin();
/**
* Validates every cross-field rule.
@@ -66,9 +66,6 @@ public class RedisSdkSettings {
validateTimeout("fast", timeout.getFast(), warnings);
validateTimeout("script", timeout.getScript(), warnings);
validateTimeout("batch", timeout.getBatch(), warnings);
if (blocking.getMaxConnections() < 1 || transaction.getMaxConnections() < 1) {
throw new IllegalStateException("dedicated connection lanes need a positive ceiling");
}
if (mode == RedisDeploymentMode.SENTINEL
&& (sentinel.getMasterName() == null || sentinel.getMasterName().isBlank())) {
throw new IllegalStateException(
@@ -95,13 +92,6 @@ public class RedisSdkSettings {
lifecycle.validate();
capacity.validate();
cluster.validate();
pubsub.validate();
if (admin.isEnabled()
&& (admin.getCredentialReference() == null || admin.getCredentialReference().isBlank())) {
throw new IllegalStateException(
"app.redis.admin.credential-reference is required when app.redis.admin.enabled=true: the"
+ " admin plane authenticates as its own account");
}
// Last, deliberately. A deployment with both a structural mistake and a missing credential
// should be told about the structural one first: it is the cheaper thing to be wrong about,
// and reporting "no credential" for a configuration that could never have connected anyway
@@ -194,40 +184,11 @@ public class RedisSdkSettings {
}
}
/** Blocking lane ceilings. */
public static class Blocking {
private int maxConnections = 32;
public int getMaxConnections() {
return maxConnections;
}
public void setMaxConnections(int maxConnections) {
this.maxConnections = maxConnections;
}
}
/** Transaction lane ceilings. */
public static class Transaction {
private int maxConnections = 16;
public int getMaxConnections() {
return maxConnections;
}
public void setMaxConnections(int maxConnections) {
this.maxConnections = maxConnections;
}
}
/** Application authentication material, carried as references rather than values. */
public static class Authentication {
private String credentialReference;
private String advancedCredentialReference;
private String pubsubCredentialReference;
private boolean anonymousAccessAccepted;
void validate(List<String> warnings) {
@@ -289,14 +250,6 @@ public class RedisSdkSettings {
public void setAdvancedCredentialReference(String advancedCredentialReference) {
this.advancedCredentialReference = advancedCredentialReference;
}
public String getPubsubCredentialReference() {
return pubsubCredentialReference;
}
public void setPubsubCredentialReference(String pubsubCredentialReference) {
this.pubsubCredentialReference = pubsubCredentialReference;
}
}
/** Sentinel discovery. */
@@ -545,49 +498,6 @@ public class RedisSdkSettings {
}
}
/** Subscription delivery. */
public static class PubSub {
private int bufferCapacity = 1_024;
void validate() {
if (bufferCapacity < 1) {
throw new IllegalStateException("the pub/sub buffer capacity must be positive");
}
}
public int getBufferCapacity() {
return bufferCapacity;
}
public void setBufferCapacity(int bufferCapacity) {
this.bufferCapacity = bufferCapacity;
}
}
/** Isolated admin plane exposure. */
public static class Admin {
private boolean enabled;
private String credentialReference;
public boolean isEnabled() {
return enabled;
}
public void setEnabled(boolean enabled) {
this.enabled = enabled;
}
public String getCredentialReference() {
return credentialReference;
}
public void setCredentialReference(String credentialReference) {
this.credentialReference = credentialReference;
}
}
public boolean isEnabled() {
return enabled;
}
@@ -628,18 +538,6 @@ public class RedisSdkSettings {
return timeout;
}
public Blocking getBlocking() {
return blocking;
}
public Transaction getTransaction() {
return transaction;
}
public Admin getAdmin() {
return admin;
}
public Authentication getAuthentication() {
return authentication;
}
@@ -663,8 +561,4 @@ public class RedisSdkSettings {
public Capacity getCapacity() {
return capacity;
}
public PubSub getPubsub() {
return pubsub;
}
}
@@ -0,0 +1,66 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
/**
* Routes each lane to the client that authenticated as the lane's account.
*
* <p>Only created when a deployment configured more than one account. Its whole behaviour is a
* lookup: the accounts were decided at composition, and a lane cannot change the account it runs as
* after the connection exists.
*/
final class AccountRoutingRuntimeClient implements RedisRuntimeClient {
private final Map<RedisAccount, RedisRuntimeClient> byAccount;
AccountRoutingRuntimeClient(Map<RedisAccount, RedisRuntimeClient> byAccount) {
this.byAccount = new LinkedHashMap<>(byAccount);
}
@Override
public RedisDeploymentMode mode() {
return byAccount.get(RedisAccount.APPLICATION).mode();
}
@Override
public RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey) {
return delegate(lane).openLane(lane, routingKey);
}
private RedisRuntimeClient delegate(RedisLane lane) {
RedisRuntimeClient client = byAccount.get(lane.account());
// Falling back to the application account is the documented behaviour of an unconfigured
// account, not a failure: a deployment with one account is the common case.
return client == null ? byAccount.get(RedisAccount.APPLICATION) : client;
}
@Override
public void close() {
// Distinct instances only, and the application client last: it is the one every unconfigured
// account fell back to, so closing it first would tear out lanes still being drained.
Set<RedisRuntimeClient> remaining = new LinkedHashSet<>(byAccount.values());
RedisRuntimeClient application = byAccount.get(RedisAccount.APPLICATION);
remaining.remove(application);
RuntimeException first = null;
for (RedisRuntimeClient client : remaining) {
try {
client.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
}
try {
application.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
if (first != null) {
throw first;
}
}
}
@@ -0,0 +1,84 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.cluster.RedisSlotCalculator;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.cluster.RedisClusterClient;
import io.lettuce.core.cluster.api.StatefulRedisClusterConnection;
import io.lettuce.core.cluster.models.partitions.RedisClusterNode;
import io.lettuce.core.codec.ByteArrayCodec;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
/** Cluster: lanes route by slot, a lane pinned to its key's owner runs on that node alone. */
final class ClusterRuntimeClient implements RedisRuntimeClient {
private static final RedisSlotCalculator SLOTS = new RedisSlotCalculator();
private final RedisClusterClient client;
private final SharedClientResources resources;
private final ShutdownBudget shutdown;
ClusterRuntimeClient(
RedisClusterClient client, SharedClientResources resources, ShutdownBudget shutdown) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
}
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.CLUSTER;
}
@Override
public RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey) {
StatefulRedisClusterConnection<byte[], byte[]> connection =
client.connect(ByteArrayCodec.INSTANCE);
if (!lane.pinnedToKeyOwner()) {
return new LaneConnection(
connection, RedisDriverConnection.slotRouting(connection.async()), connection::isOpen);
}
try {
// A Cluster transaction runs on one node. The slot-routing connection cannot own the window
// — its queued commands would be spread across nodes — so the lane is pinned to the node
// that owns the routing key's slot, and every key in the window is proved to share that slot
// before anything is queued.
byte[] key =
routingKey.orElseThrow(
() ->
new IllegalStateException(
"a Cluster lane pinned to its key's owner needs a routing key: the window"
+ " runs on one node, and which node that is can only be decided from a"
+ " key or an explicit slot tag."));
int slot = SLOTS.applyAsInt(new String(key, StandardCharsets.UTF_8));
RedisClusterNode owner = client.getPartitions().getMasterBySlot(slot);
if (owner == null) {
throw new IllegalStateException(
"no Cluster node currently owns slot "
+ slot
+ "; the topology is incomplete and a transaction opened against it would run"
+ " somewhere the keys do not live");
}
StatefulRedisConnection<byte[], byte[]> node = connection.getConnection(owner.getNodeId());
// The parent is closed on release; closing it releases the node connection with it.
return new LaneConnection(
connection, RedisDriverConnection.singleNode(node.async()), node::isOpen);
} catch (RuntimeException failure) {
connection.close();
throw failure;
}
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
resources.release(shutdown);
}
}
}
@@ -0,0 +1,37 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.LettuceSemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.util.function.BooleanSupplier;
/**
* One open connection: what closes it, what runs over it, and how to ask whether it still works.
*
* @param connection what {@link #close()} closes — on a pinned Cluster lane the parent connection,
* which releases the node connection with it
* @param driver the driver surface commands are sent on
* @param openCheck whether the driver still reports the connection open
*/
record LaneConnection(
AutoCloseable connection, RedisDriverConnection driver, BooleanSupplier openCheck)
implements RedisRuntimeClient.RedisLaneConnection {
@Override
public SemanticRedisCommands commands() {
return new LettuceSemanticRedisCommands(driver.commands());
}
@Override
public boolean open() {
return openCheck.getAsBoolean();
}
@Override
public void close() {
try {
connection.close();
} catch (Exception failure) {
throw new IllegalStateException("a Redis lane connection could not be closed", failure);
}
}
}
@@ -0,0 +1,46 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import java.util.Objects;
import java.util.regex.Pattern;
/**
* The Redis account a connection authenticates as.
*
* <p>Redis ACLs authenticate a named user, and the privileges that user carries are the only
* privileges the connection has for its whole life. So "which account" is a property of the
* connection, not of the command: a client authenticated as one account cannot run some commands as
* a less privileged one. A deployment that grants its application account {@code EVALSHA} so that
* the rate limiter works has granted it to every code path that can reach a regular connection;
* separate accounts keep the scripting grant on the connections that run scripts.
*
* <p>The runtime names the two accounts its own lanes use. A module that composes further lanes on
* top of the runtime — the typed SDK's admin plane — names its own account and contributes it
* through {@code RedisAccountContribution}; the runtime does not need to know it exists. An account
* with no configured credential is served by the application client, which collapses to the
* single-account deployment most services start from.
*
* @param name a short lowercase identifier, used in logs
*/
public record RedisAccount(String name) {
// First: the constants below are built by the constructor that reads it.
private static final Pattern NAME = Pattern.compile("[a-z][a-z0-9-]{0,31}");
/** Ordinary data commands. The one account every deployment configures. */
public static final RedisAccount APPLICATION = new RedisAccount("application");
/** Registered-script execution: {@code SCRIPT LOAD} and {@code EVALSHA}. */
public static final RedisAccount ADVANCED = new RedisAccount("advanced");
public RedisAccount {
Objects.requireNonNull(name, "account name must be non-null");
if (!NAME.matcher(name).matches()) {
throw new IllegalArgumentException("account name must be a short lowercase identifier");
}
}
@Override
public String toString() {
return name;
}
}
@@ -0,0 +1,29 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
/**
* The runtime's own lanes: the ones its semantic consumers and its health contributor use.
*
* <p>Two, because the runtime's consumers need two account/behaviour combinations: ordinary
* commands on the application account, and registered scripts on the advanced account. Blocking,
* transaction and admin lanes belong to the typed SDK, which contributes them itself.
*/
public enum RedisConnectionKind implements RedisLane {
/** Ordinary non-blocking commands on a shared, thread-safe connection. */
REGULAR(RedisAccount.APPLICATION.name()),
/**
* Registered-script execution, which needs the scripting grants ordinary traffic must not have.
*/
SCRIPT(RedisAccount.ADVANCED.name());
// The name rather than the record: an enum constant's state must be deeply immutable.
private final String account;
RedisConnectionKind(String account) {
this.account = account;
}
@Override
public RedisAccount account() {
return new RedisAccount(account);
}
}
@@ -0,0 +1,49 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import io.lettuce.core.api.async.RedisAsyncCommands;
import io.lettuce.core.cluster.api.async.RedisClusterAsyncCommands;
import java.util.Objects;
import java.util.Optional;
/**
* The driver surface of one borrowed connection, for a module that speaks more of Redis than the
* runtime's semantic commands.
*
* <p>The typed SDK builds its own gateway over this. The runtime does not carry the SDK's command
* surface; it carries the connection, and the SDK brings the commands.
*
* @param commands the asynchronous commands every data command lives on: standalone, or
* slot-routing on Cluster
* @param transactional the same connection's single-node surface, which is the only one that can
* own a {@code MULTI}/{@code EXEC} window; empty on a slot-routing Cluster connection
*/
public record RedisDriverConnection(
RedisClusterAsyncCommands<byte[], byte[]> commands,
Optional<RedisAsyncCommands<byte[], byte[]>> transactional) {
public RedisDriverConnection {
Objects.requireNonNull(commands, "commands must be non-null");
Objects.requireNonNull(transactional, "transactional must be non-null");
}
/**
* A single-node connection, which can own a transaction window.
*
* @param commands the node's asynchronous commands
* @return the driver connection
*/
public static RedisDriverConnection singleNode(RedisAsyncCommands<byte[], byte[]> commands) {
return new RedisDriverConnection(commands, Optional.of(commands));
}
/**
* A slot-routing Cluster connection, which cannot own a transaction window.
*
* @param commands the slot-routing asynchronous commands
* @return the driver connection
*/
public static RedisDriverConnection slotRouting(
RedisClusterAsyncCommands<byte[], byte[]> commands) {
return new RedisDriverConnection(commands, Optional.empty());
}
}
@@ -0,0 +1,45 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
/**
* A bounded pool of connections that share an account and a connection behaviour.
*
* <p>Lanes exist because their failure modes are incompatible. A script needs grants ordinary
* traffic must not have; a blocking command holds its connection for the whole block; a transaction
* owns its connection between {@code MULTI} and {@code EXEC}. Sharing one pool turns any of these
* into a stall of everything else.
*
* <p>The runtime defines the lanes its own consumers use ({@link RedisConnectionKind}). A module
* that needs another — the typed SDK's blocking, transaction and admin lanes — implements this
* interface and contributes a limit for it; the runtime pools and drains it like its own.
* Implementations must be singletons with value identity (an enum constant), because the lane is
* the pool's key.
*/
public interface RedisLane {
/**
* Returns the lane's name, for logs and refusals.
*
* @return the name
*/
String name();
/**
* Returns the account this lane's connections authenticate as.
*
* @return the account
*/
RedisAccount account();
/**
* Reports whether a connection must be pinned to the node that owns the caller's routing key.
*
* <p>Only meaningful on Cluster, where a transaction runs entirely on one node: the slot-routing
* connection every other lane uses cannot own the window. Topologies with a single owner ignore
* it.
*
* @return {@code true} when a connection is opened against the routing key's owning node
*/
default boolean pinnedToKeyOwner() {
return false;
}
}
@@ -0,0 +1,38 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import java.util.Objects;
/**
* No connection could be lent: the lane stayed full for the acquire timeout, the wait was
* interrupted, or the runtime is shutting down.
*
* <p>Always raised before any command exists, so nothing reached Redis. A caller may treat it as
* "unavailable" rather than as a write that might have landed — the distinction every semantic
* adapter reports to its own callers.
*/
public final class RedisLaneUnavailableException extends RuntimeException {
private static final long serialVersionUID = 1L;
private final String lane;
/**
* Creates the failure.
*
* @param lane the lane that could not lend a connection
* @param reason a fixed, payload-free reason
*/
public RedisLaneUnavailableException(String lane, String reason) {
super(Objects.requireNonNull(reason, "reason must be non-null"));
this.lane = Objects.requireNonNull(lane, "lane must be non-null");
}
/**
* Returns the lane that refused.
*
* @return the lane name
*/
public String lane() {
return lane;
}
}
@@ -1,13 +1,9 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
/**
* A borrowed connection, typed by what the caller actually needs.
*
* <p>The predecessor handed out {@code Object} and left the caller to cast. That is not only
* awkward — it meant the type system could not tell a caller holding a live connection from one
* holding a returned lease, and returning was a counter decrement that never closed anything.
* A borrowed connection.
*
* <p>Two things a caller must know how to do. Returning is mandatory, which is why this is {@link
* AutoCloseable} and every lane is bounded. Invalidating is for the case a pooled connection cannot
@@ -21,21 +17,29 @@ public interface RedisLease extends AutoCloseable {
*
* @return the lane
*/
RedisConnectionKind kind();
RedisLane lane();
/**
* Returns the gateway bound to this connection.
* Returns the runtime's semantic commands over this connection.
*
* @return the driver seam
* @return the commands
* @throws IllegalStateException when the lease has already been returned
*/
RedisCommandGateway gateway();
SemanticRedisCommands commands();
/**
* Returns the driver surface of this connection, for a module that brings its own commands.
*
* @return the driver connection
* @throws IllegalStateException when the lease has already been returned
*/
RedisDriverConnection driver();
/**
* Marks the connection unfit for reuse, so returning it closes it instead of pooling it.
*
* <p>Call this whenever cleanup did not complete: a failed {@code DISCARD}, an abandoned
* subscription, any path that leaves connection-scoped state behind.
* <p>Call this whenever cleanup did not complete: a failed {@code DISCARD}, a window that may
* still be open, any path that leaves connection-scoped state behind.
*/
void invalidate();
@@ -0,0 +1,85 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.util.Optional;
/**
* The driver client for one deployment, and the only thing that knows which topology it is.
*
* <p>Everything above this interface is topology-agnostic: a caller asks for a lane and gets a
* connection. Which client produced it — standalone, Sentinel-resolving, or slot-routing — is
* settled once, at composition, by the strategy that matched the configured mode.
*
* <p>Opening a lane is separate from borrowing one. This creates a connection; the owner decides
* whether the caller is allowed to hold one.
*/
public interface RedisRuntimeClient extends AutoCloseable {
/**
* Returns the deployment mode this client was built for.
*
* @return the bound mode
*/
RedisDeploymentMode mode();
/**
* Opens a connection for a lane that needs no routing decision.
*
* @param lane the lane
* @return the open lane
*/
default RedisLaneConnection openLane(RedisLane lane) {
return openLane(lane, Optional.empty());
}
/**
* Opens a connection for a lane.
*
* <p>The routing key exists for a lane {@linkplain RedisLane#pinnedToKeyOwner() pinned to its
* key's owner}: on Cluster such a connection is opened against the node that owns the key rather
* than the slot-routing connection every other lane uses. Topologies with a single owner ignore
* it.
*
* @param lane the lane
* @param routingKey a key whose slot decides which node the lane is pinned to
* @return the open lane
*/
RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey);
/**
* Shuts the client and its event loop down, after every lane has been closed.
*
* <p>Shutting the client down first would abort in-flight commands the drain was waiting for.
*/
@Override
void close();
/** One open connection and what can be sent over it. */
interface RedisLaneConnection extends AutoCloseable {
/**
* Returns the runtime's semantic commands over this connection.
*
* @return the commands
*/
SemanticRedisCommands commands();
/**
* Returns the driver surface of this connection, for a module that brings its own commands.
*
* @return the driver connection
*/
RedisDriverConnection driver();
/**
* Reports whether the connection is currently usable.
*
* @return {@code true} while the driver reports it open
*/
boolean open();
@Override
void close();
}
}
@@ -1,15 +1,12 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.command.CommandAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisCommandRejectedException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisFailureMetadata;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.time.Duration;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.EnumMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
@@ -52,10 +49,10 @@ public final class RedisRuntimeOwner implements AutoCloseable {
}
private final RedisRuntimeClient client;
private final Map<RedisConnectionKind, Integer> limits;
private final Map<RedisConnectionKind, Deque<RedisRuntimeClient.RedisLaneConnection>> idle;
private final Map<RedisConnectionKind, Integer> outstanding;
private final Map<RedisConnectionKind, Semaphore> permits;
private final Map<RedisLane, Integer> limits;
private final Map<RedisLane, Deque<RedisRuntimeClient.RedisLaneConnection>> idle;
private final Map<RedisLane, Integer> outstanding;
private final Map<RedisLane, Semaphore> permits;
private final Duration acquireTimeout;
private final Duration drainTimeout;
private final AtomicReference<State> state = new AtomicReference<>(State.OPEN);
@@ -65,13 +62,15 @@ public final class RedisRuntimeOwner implements AutoCloseable {
* Creates the owner.
*
* @param client the topology client whose connections this owns
* @param limits per-lane maximum connections, each held by at most one lease at a time
* @param limits per-lane maximum connections, each held by at most one lease at a time. Every
* lane a caller may borrow is named here; the runtime's own {@link RedisConnectionKind} lanes
* are required, and a module that composes further lanes contributes their limits
* @param acquireTimeout how long a borrow waits for a returned connection when its lane is full
* @param drainTimeout how long shutdown waits for outstanding leases
*/
public RedisRuntimeOwner(
RedisRuntimeClient client,
Map<RedisConnectionKind, Integer> limits,
Map<? extends RedisLane, Integer> limits,
Duration acquireTimeout,
Duration drainTimeout) {
this.client = Objects.requireNonNull(client, "client must be non-null");
@@ -79,21 +78,27 @@ public final class RedisRuntimeOwner implements AutoCloseable {
Objects.requireNonNull(acquireTimeout, "acquire timeout must be non-null");
this.drainTimeout = Objects.requireNonNull(drainTimeout, "drain timeout must be non-null");
Objects.requireNonNull(limits, "limits must be non-null");
Map<RedisConnectionKind, Integer> configured = new EnumMap<>(RedisConnectionKind.class);
Map<RedisConnectionKind, Deque<RedisRuntimeClient.RedisLaneConnection>> pools =
new EnumMap<>(RedisConnectionKind.class);
Map<RedisConnectionKind, Integer> counters = new EnumMap<>(RedisConnectionKind.class);
Map<RedisConnectionKind, Semaphore> lanes = new EnumMap<>(RedisConnectionKind.class);
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
Integer limit = limits.get(kind);
if (limit == null || limit < 1) {
if (!limits.containsKey(kind)) {
throw new IllegalArgumentException("connection lane " + kind + " needs a positive limit");
}
configured.put(kind, limit);
pools.put(kind, new ArrayDeque<>());
counters.put(kind, 0);
}
Map<RedisLane, Integer> configured = new LinkedHashMap<>();
Map<RedisLane, Deque<RedisRuntimeClient.RedisLaneConnection>> pools = new LinkedHashMap<>();
Map<RedisLane, Integer> counters = new LinkedHashMap<>();
Map<RedisLane, Semaphore> lanes = new LinkedHashMap<>();
for (Map.Entry<? extends RedisLane, Integer> entry : limits.entrySet()) {
RedisLane lane = Objects.requireNonNull(entry.getKey(), "lane must be non-null");
Integer limit = entry.getValue();
if (limit == null || limit < 1) {
throw new IllegalArgumentException(
"connection lane " + lane.name() + " needs a positive limit");
}
configured.put(lane, limit);
pools.put(lane, new ArrayDeque<>());
counters.put(lane, 0);
// Fair, so a burst is served in arrival order rather than starving the earliest waiter.
lanes.put(kind, new Semaphore(limit, true));
lanes.put(lane, new Semaphore(limit, true));
}
this.limits = Map.copyOf(configured);
this.idle = pools;
@@ -115,10 +120,10 @@ public final class RedisRuntimeOwner implements AutoCloseable {
*
* @param kind the lane
* @return the lease, which must be closed
* @throws RedisCommandRejectedException when the lane stayed full for the acquire timeout or the
* @throws RedisLaneUnavailableException when the lane stayed full for the acquire timeout or the
* owner is closing
*/
public RedisLease borrow(RedisConnectionKind kind) {
public RedisLease borrow(RedisLane kind) {
return borrow(kind, Optional.empty());
}
@@ -133,14 +138,21 @@ public final class RedisRuntimeOwner implements AutoCloseable {
* @param kind the lane
* @param routingKey a key whose slot decides the node, on topologies that have more than one
* @return the lease, which must be closed
* @throws RedisCommandRejectedException when the lane stayed full for the acquire timeout or the
* @throws RedisLaneUnavailableException when the lane stayed full for the acquire timeout or the
* owner is closing
* @throws IllegalArgumentException when no limit was configured for the lane
*/
public RedisLease borrow(RedisConnectionKind kind, Optional<byte[]> routingKey) {
public RedisLease borrow(RedisLane kind, Optional<byte[]> routingKey) {
Objects.requireNonNull(kind, "connection kind must be non-null");
Objects.requireNonNull(routingKey, "routing key must be non-null");
if (!permits.containsKey(kind)) {
throw new IllegalArgumentException(
"connection lane "
+ kind.name()
+ " was never composed; the module that uses it contributes its limit");
}
if (state.get() != State.OPEN) {
throw notAccepting();
throw notAccepting(kind);
}
// The limit is the lane's connection count: a lease holds one connection for one round trip,
// so a burst above it waits for a returned connection instead of being refused against a
@@ -153,12 +165,13 @@ public final class RedisRuntimeOwner implements AutoCloseable {
admitted = lane.tryAcquire(acquireTimeout.toNanos(), TimeUnit.NANOSECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw reject("interrupted while waiting for a connection on lane " + kind);
throw reject(kind, "interrupted while waiting for a connection on lane " + kind.name());
}
if (!admitted) {
throw reject(
kind,
"connection lane "
+ kind
+ kind.name()
+ " reached its limit of "
+ limits.get(kind)
+ " and no connection was returned within "
@@ -167,7 +180,7 @@ public final class RedisRuntimeOwner implements AutoCloseable {
synchronized (monitor) {
if (state.get() != State.OPEN) {
lane.release();
throw notAccepting();
throw notAccepting(kind);
}
outstanding.put(kind, outstanding.get(kind) + 1);
}
@@ -198,9 +211,7 @@ public final class RedisRuntimeOwner implements AutoCloseable {
}
private void release(
RedisConnectionKind kind,
RedisRuntimeClient.RedisLaneConnection connection,
boolean reusable) {
RedisLane kind, RedisRuntimeClient.RedisLaneConnection connection, boolean reusable) {
boolean drained;
synchronized (monitor) {
outstanding.put(kind, outstanding.get(kind) - 1);
@@ -273,8 +284,9 @@ public final class RedisRuntimeOwner implements AutoCloseable {
}
}
private RedisCommandRejectedException notAccepting() {
private RedisLaneUnavailableException notAccepting(RedisLane lane) {
return reject(
lane,
"the Redis runtime is "
+ state.get()
+ " and is not accepting new work; a lease taken during shutdown would either be"
@@ -283,10 +295,8 @@ public final class RedisRuntimeOwner implements AutoCloseable {
// Every refusal here happens before a command exists, so it is always "not sent": a caller may
// treat it as unavailable rather than as a write that might have landed.
private RedisCommandRejectedException reject(String reason) {
return new RedisCommandRejectedException(
reason,
RedisFailureMetadata.notSent("CONNECTION", CommandAccess.NONE, false, client.mode()));
private static RedisLaneUnavailableException reject(RedisLane lane, String reason) {
return new RedisLaneUnavailableException(lane.name(), reason);
}
/**
@@ -295,7 +305,7 @@ public final class RedisRuntimeOwner implements AutoCloseable {
* @param kind the lane
* @return the outstanding count
*/
public int outstanding(RedisConnectionKind kind) {
public int outstanding(RedisLane kind) {
synchronized (monitor) {
return outstanding.get(Objects.requireNonNull(kind, "connection kind must be non-null"));
}
@@ -313,31 +323,39 @@ public final class RedisRuntimeOwner implements AutoCloseable {
/** A borrowed connection, typed, returned once, and invalidatable. */
public final class Lease implements RedisLease {
private final RedisConnectionKind kind;
private final RedisLane kind;
private final RedisRuntimeClient.RedisLaneConnection connection;
private boolean reusable;
private boolean closed;
private Lease(
RedisConnectionKind kind,
RedisRuntimeClient.RedisLaneConnection connection,
boolean reusable) {
RedisLane kind, RedisRuntimeClient.RedisLaneConnection connection, boolean reusable) {
this.kind = kind;
this.connection = connection;
this.reusable = reusable;
}
@Override
public RedisConnectionKind kind() {
public RedisLane lane() {
return kind;
}
@Override
public RedisCommandGateway gateway() {
public SemanticRedisCommands commands() {
requireOpen();
return connection.commands();
}
@Override
public RedisDriverConnection driver() {
requireOpen();
return connection.driver();
}
private void requireOpen() {
if (closed) {
throw new IllegalStateException("this Redis lease was already returned");
}
return connection.gateway();
}
@Override
@@ -1,13 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.cluster.RedisSlotCalculator;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.LettuceRedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import io.lettuce.core.ClientOptions;
import io.lettuce.core.RedisClient;
import io.lettuce.core.RedisCredentialsProvider;
@@ -15,29 +10,20 @@ import io.lettuce.core.RedisURI;
import io.lettuce.core.SocketOptions;
import io.lettuce.core.SslOptions;
import io.lettuce.core.TimeoutOptions;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.cluster.ClusterClientOptions;
import io.lettuce.core.cluster.ClusterTopologyRefreshOptions;
import io.lettuce.core.cluster.RedisClusterClient;
import io.lettuce.core.cluster.api.StatefulRedisClusterConnection;
import io.lettuce.core.cluster.models.partitions.RedisClusterNode;
import io.lettuce.core.codec.ByteArrayCodec;
import io.lettuce.core.resource.ClientResources;
import io.lettuce.core.resource.DefaultClientResources;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.EnumMap;
import java.util.LinkedHashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
/**
* Builds the clients the configured topology and the configured accounts call for.
@@ -46,7 +32,7 @@ import java.util.concurrent.atomic.AtomicInteger;
* them. A deployment that declares Sentinel and gets a standalone client would work — until the
* first promotion, at which point it would keep writing to a server that is no longer the primary.
* So the mode picks the strategy and a mode whose prerequisites are missing fails at {@link
* RedisSdkSettings#validate()}, before this class is ever reached.
* RedisRuntimeSettings#validate()}, before this class is ever reached.
*
* <p>Orthogonally to the topology, a deployment may authenticate different lanes as different Redis
* accounts. That cannot be expressed on one client: an ACL user is bound at authentication and
@@ -62,11 +48,9 @@ import java.util.concurrent.atomic.AtomicInteger;
*/
public final class RedisTopologyClientFactory {
private static final RedisSlotCalculator SLOTS = new RedisSlotCalculator();
private final RedisRuntimeSettings settings;
private final RedisSdkSettings settings;
private final Map<RedisCredentialRole, RedisCredentials> credentials;
private final Map<RedisAccount, RedisCredentials> credentials;
private final Optional<RedisCredentials> sentinelCredentials;
@@ -98,13 +82,14 @@ public final class RedisTopologyClientFactory {
* Creates the factory.
*
* @param settings the validated settings
* @param credentials the resolved account for each configured role
* @param credentials the resolved credentials of each configured account; the application
* account's may be absent (anonymous access), every other account named here gets a client
* @param sentinelCredentials the resolved Sentinel control account, when one is configured
* @param tlsMaterial opens configured TLS material
*/
public RedisTopologyClientFactory(
RedisSdkSettings settings,
Map<RedisCredentialRole, RedisCredentials> credentials,
RedisRuntimeSettings settings,
Map<RedisAccount, RedisCredentials> credentials,
Optional<RedisCredentials> sentinelCredentials,
TlsMaterialSource tlsMaterial) {
this.settings = Objects.requireNonNull(settings, "settings must be non-null");
@@ -123,24 +108,24 @@ public final class RedisTopologyClientFactory {
public RedisRuntimeClient create() {
// One event-loop group for every account, not one per account. `ClientResources` carries
// `max(2, cores)` IO threads plus a computation pool and a timer; a deployment with an
// application, an advanced and a pub/sub account used to get three of each, so an eight-core
// application, an advanced and an admin account used to get three of each, so an eight-core
// pod ran twenty-four IO threads to talk to one Redis. The accounts differ in who they
// authenticate as, which is a property of the connection, not of the threads that carry it.
SharedClientResources shared = new SharedClientResources(resources());
Map<RedisCredentialRole, RedisRuntimeClient> byRole = new EnumMap<>(RedisCredentialRole.class);
Map<RedisAccount, RedisRuntimeClient> byAccount = new LinkedHashMap<>();
List<RedisRuntimeClient> created = new ArrayList<>();
try {
RedisRuntimeClient application =
clientFor(Optional.ofNullable(credentials.get(RedisCredentialRole.APPLICATION)), shared);
byRole.put(RedisCredentialRole.APPLICATION, application);
clientFor(Optional.ofNullable(credentials.get(RedisAccount.APPLICATION)), shared);
byAccount.put(RedisAccount.APPLICATION, application);
created.add(application);
for (RedisCredentialRole role : RedisCredentialRole.values()) {
if (role == RedisCredentialRole.APPLICATION || !credentials.containsKey(role)) {
for (Map.Entry<RedisAccount, RedisCredentials> account : credentials.entrySet()) {
if (account.getKey().equals(RedisAccount.APPLICATION)) {
continue;
}
RedisRuntimeClient client = clientFor(Optional.of(credentials.get(role)), shared);
RedisRuntimeClient client = clientFor(Optional.of(account.getValue()), shared);
created.add(client);
byRole.put(role, client);
byAccount.put(account.getKey(), client);
}
} catch (RuntimeException failure) {
// A half-built set would leak the event loops of the clients that did get created. Closing
@@ -149,9 +134,9 @@ public final class RedisTopologyClientFactory {
shared.shutdownAfterFailedBuild(shutdown());
throw failure;
}
return byRole.size() == 1
? byRole.get(RedisCredentialRole.APPLICATION)
: new RoleRoutingRuntimeClient(byRole);
return byAccount.size() == 1
? byAccount.get(RedisAccount.APPLICATION)
: new AccountRoutingRuntimeClient(byAccount);
}
private static void closeQuietly(RedisRuntimeClient client) {
@@ -326,7 +311,7 @@ public final class RedisTopologyClientFactory {
private SslOptions sslOptions() {
SslOptions.Builder ssl = SslOptions.builder().jdkSslProvider();
RedisSdkSettings.Tls tls = settings.getTls();
RedisRuntimeSettings.Tls tls = settings.getTls();
if (tls.getTrustMaterialResource() != null && !tls.getTrustMaterialResource().isBlank()) {
ssl.trustManager(material("trust material", tls.getTrustMaterialResource()));
}
@@ -370,288 +355,12 @@ public final class RedisTopologyClientFactory {
return () -> tlsMaterial.open(location);
}
/**
* One {@link ClientResources} shared by every account, stopped by the last client to let go.
*
* <p>Lettuce treats whoever passes resources to {@code RedisClient.create} as their owner and
* {@code client.shutdown()} deliberately leaves them running, so somebody has to stop them. With
* one group per account that owner was obvious and wasteful; with one group for all of them the
* ownership is shared, and a hold count is the smallest thing that still guarantees the loops are
* stopped exactly once, after the last client that was using them.
*/
private static final class SharedClientResources {
private final ClientResources resources;
private final AtomicInteger holds = new AtomicInteger();
private final AtomicBoolean stopped = new AtomicBoolean();
private SharedClientResources(ClientResources resources) {
this.resources = resources;
}
/** Takes a hold and returns the group to hand to a driver client. */
private ClientResources acquire() {
holds.incrementAndGet();
return resources;
}
/** Releases one hold, stopping the loops when it was the last one. */
private void release(ShutdownBudget shutdown) {
if (holds.decrementAndGet() == 0) {
stop(shutdown);
}
}
/**
* Stops the loops after a build that did not finish.
*
* <p>Unconditional, not "when nothing holds it": a hold is taken before the driver client that
* would release it exists, so a failure between those two points leaves a hold nobody can give
* back. {@link #stop} is idempotent, so the clients that were built and closed normally having
* already stopped the group costs nothing here.
*/
private void shutdownAfterFailedBuild(ShutdownBudget shutdown) {
stop(shutdown);
}
private void stop(ShutdownBudget shutdown) {
if (stopped.compareAndSet(false, true)) {
shutdown.await(
resources.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS));
}
}
}
/** Standalone and Sentinel share a client type; only how the URI resolves differs. */
private static final class StandaloneRuntimeClient implements RedisRuntimeClient {
private final RedisClient client;
private final SharedClientResources resources;
private final RedisDeploymentMode mode;
private final ShutdownBudget shutdown;
private StandaloneRuntimeClient(
RedisClient client,
SharedClientResources resources,
ShutdownBudget shutdown,
RedisDeploymentMode mode) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
this.mode = mode;
}
@Override
public RedisDeploymentMode mode() {
return mode;
}
@Override
public RedisLaneConnection openLane(RedisConnectionKind kind, Optional<byte[]> routingKey) {
// A single server owns every key, so a routing key carries no information here.
StatefulRedisConnection<byte[], byte[]> connection = client.connect(ByteArrayCodec.INSTANCE);
return new LaneConnection(
connection, new LettuceRedisCommandGateway(connection.async()), connection::isOpen);
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
// After the client, never before: the resources are the threads the shutdown runs on. And
// awaited, not fired — shutdown() returns a future, so ignoring it means returning while
// the event loop is still running and reporting a clean stop that has not happened. The
// group is shared across accounts, so only the last client to release actually stops it.
resources.release(shutdown);
}
}
}
/** Cluster: data lanes route by slot, the transaction lane is pinned to the slot's owner. */
private static final class ClusterRuntimeClient implements RedisRuntimeClient {
private final RedisClusterClient client;
private final SharedClientResources resources;
private final ShutdownBudget shutdown;
private ClusterRuntimeClient(
RedisClusterClient client, SharedClientResources resources, ShutdownBudget shutdown) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
}
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.CLUSTER;
}
@Override
public RedisLaneConnection openLane(RedisConnectionKind kind, Optional<byte[]> routingKey) {
StatefulRedisClusterConnection<byte[], byte[]> connection =
client.connect(ByteArrayCodec.INSTANCE);
if (kind != RedisConnectionKind.TRANSACTION) {
return new LaneConnection(
connection, new LettuceRedisCommandGateway(connection.async()), connection::isOpen);
}
try {
// A Cluster transaction runs on one node. The slot-routing connection cannot own the
// window — its queued commands would be spread across nodes — so the lane is pinned to the
// node that owns the routing key's slot, and every key in the window is proved to share
// that slot before anything is queued.
byte[] key =
routingKey.orElseThrow(
() ->
new IllegalStateException(
"a Cluster transaction lane needs a routing key: the window runs on one"
+ " node, and which node that is can only be decided from a key or an"
+ " explicit slot tag."));
int slot = SLOTS.applyAsInt(new String(key, StandardCharsets.UTF_8));
RedisClusterNode owner = client.getPartitions().getMasterBySlot(slot);
if (owner == null) {
throw new IllegalStateException(
"no Cluster node currently owns slot "
+ slot
+ "; the topology is incomplete and a transaction opened against it would run"
+ " somewhere the keys do not live");
}
StatefulRedisConnection<byte[], byte[]> node = connection.getConnection(owner.getNodeId());
// The parent is closed on release; closing it releases the node connection with it.
return new LaneConnection(
connection, new LettuceRedisCommandGateway(node.async()), node::isOpen);
} catch (RuntimeException failure) {
connection.close();
throw failure;
}
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
resources.release(shutdown);
}
}
}
/**
* Routes each lane to the client that authenticated as the lane's account.
*
* <p>Only created when a deployment configured more than one account. Its whole behaviour is a
* lookup: the roles were decided at composition, and a lane cannot change the account it runs as
* after the connection exists.
*/
private static final class RoleRoutingRuntimeClient implements RedisRuntimeClient {
private final Map<RedisCredentialRole, RedisRuntimeClient> byRole;
private RoleRoutingRuntimeClient(Map<RedisCredentialRole, RedisRuntimeClient> byRole) {
this.byRole = new EnumMap<>(byRole);
}
@Override
public RedisDeploymentMode mode() {
return byRole.get(RedisCredentialRole.APPLICATION).mode();
}
@Override
public RedisLaneConnection openLane(RedisConnectionKind kind, Optional<byte[]> routingKey) {
return delegate(kind).openLane(kind, routingKey);
}
private RedisRuntimeClient delegate(RedisConnectionKind kind) {
RedisRuntimeClient client = byRole.get(kind.credentialRole());
// Falling back to the application account is the documented behaviour of an unconfigured
// role, not a failure: a deployment with one account is the common case.
return client == null ? byRole.get(RedisCredentialRole.APPLICATION) : client;
}
@Override
public void close() {
// Distinct instances only, and the application client last: it is the one every unconfigured
// role fell back to, so closing it first would tear out lanes still being drained.
Set<RedisRuntimeClient> remaining = new LinkedHashSet<>(byRole.values());
RedisRuntimeClient application = byRole.get(RedisCredentialRole.APPLICATION);
remaining.remove(application);
RuntimeException first = null;
for (RedisRuntimeClient client : remaining) {
try {
client.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
}
try {
application.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
if (first != null) {
throw first;
}
}
}
private record LaneConnection(
AutoCloseable connection,
RedisCommandGateway gateway,
java.util.function.BooleanSupplier openCheck)
implements RedisRuntimeClient.RedisLaneConnection {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return openCheck.getAsBoolean();
}
@Override
public void close() {
try {
connection.close();
} catch (Exception failure) {
throw new IllegalStateException("a Redis lane connection could not be closed", failure);
}
}
}
private ShutdownBudget shutdown() {
return new ShutdownBudget(
settings.getLifecycle().getShutdownQuietPeriod(),
settings.getLifecycle().getShutdownTimeout());
}
/**
* How long a client is given to stop, and the wait that makes stopping observable.
*
* @param quietPeriod the window in which new work must stop arriving
* @param timeout the total budget
*/
private record ShutdownBudget(Duration quietPeriod, Duration timeout) {
void await(java.util.concurrent.Future<?> pending) {
try {
pending.get(timeout.toMillis() + quietPeriod.toMillis(), MILLISECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
} catch (java.util.concurrent.ExecutionException
| java.util.concurrent.TimeoutException failure) {
// Shutdown is best effort past its own budget; what it must not do is claim to be done.
LOG.warn("Redis client resources did not shut down within {}", timeout, failure);
}
}
}
private static final org.slf4j.Logger LOG =
org.slf4j.LoggerFactory.getLogger(RedisTopologyClientFactory.class);
@@ -0,0 +1,60 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import io.lettuce.core.resource.ClientResources;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
/**
* One {@link ClientResources} shared by every account, stopped by the last client to let go.
*
* <p>Lettuce treats whoever passes resources to {@code RedisClient.create} as their owner and
* {@code client.shutdown()} deliberately leaves them running, so somebody has to stop them. With
* one group per account that owner was obvious and wasteful; with one group for all of them the
* ownership is shared, and a hold count is the smallest thing that still guarantees the loops are
* stopped exactly once, after the last client that was using them.
*/
final class SharedClientResources {
private final ClientResources resources;
private final AtomicInteger holds = new AtomicInteger();
private final AtomicBoolean stopped = new AtomicBoolean();
SharedClientResources(ClientResources resources) {
this.resources = resources;
}
/** Takes a hold and returns the group to hand to a driver client. */
ClientResources acquire() {
holds.incrementAndGet();
return resources;
}
/** Releases one hold, stopping the loops when it was the last one. */
void release(ShutdownBudget shutdown) {
if (holds.decrementAndGet() == 0) {
stop(shutdown);
}
}
/**
* Stops the loops after a build that did not finish.
*
* <p>Unconditional, not "when nothing holds it": a hold is taken before the driver client that
* would release it exists, so a failure between those two points leaves a hold nobody can give
* back. {@link #stop} is idempotent, so the clients that were built and closed normally having
* already stopped the group costs nothing here.
*/
void shutdownAfterFailedBuild(ShutdownBudget shutdown) {
stop(shutdown);
}
private void stop(ShutdownBudget shutdown) {
if (stopped.compareAndSet(false, true)) {
shutdown.await(
resources.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS));
}
}
}
@@ -0,0 +1,32 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import java.time.Duration;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeoutException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* How long a client is given to stop, and the wait that makes stopping observable.
*
* @param quietPeriod the window in which new work must stop arriving
* @param timeout the total budget
*/
record ShutdownBudget(Duration quietPeriod, Duration timeout) {
private static final Logger LOG = LoggerFactory.getLogger(ShutdownBudget.class);
void await(Future<?> pending) {
try {
pending.get(timeout.toMillis() + quietPeriod.toMillis(), MILLISECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
} catch (ExecutionException | TimeoutException failure) {
// Shutdown is best effort past its own budget; what it must not do is claim to be done.
LOG.warn("Redis client resources did not shut down within {}", timeout, failure);
}
}
}
@@ -0,0 +1,56 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import io.lettuce.core.RedisClient;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.codec.ByteArrayCodec;
import java.util.Optional;
/** Standalone and Sentinel share a client type; only how the URI resolves differs. */
final class StandaloneRuntimeClient implements RedisRuntimeClient {
private final RedisClient client;
private final SharedClientResources resources;
private final ShutdownBudget shutdown;
private final RedisDeploymentMode mode;
StandaloneRuntimeClient(
RedisClient client,
SharedClientResources resources,
ShutdownBudget shutdown,
RedisDeploymentMode mode) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
this.mode = mode;
}
@Override
public RedisDeploymentMode mode() {
return mode;
}
@Override
public RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey) {
// A single server owns every key, so a routing key carries no information here.
StatefulRedisConnection<byte[], byte[]> connection = client.connect(ByteArrayCodec.INSTANCE);
return new LaneConnection(
connection, RedisDriverConnection.singleNode(connection.async()), connection::isOpen);
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
// After the client, never before: the resources are the threads the shutdown runs on. And
// awaited, not fired — shutdown() returns a future, so ignoring it means returning while the
// event loop is still running and reporting a clean stop that has not happened. The group is
// shared across accounts, so only the last client to release actually stops it.
resources.release(shutdown);
}
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.key;
import java.util.Locale;
import java.util.Objects;
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.key;
/**
* Structural key prefix that isolates an environment, a service, and a domain.
@@ -1,86 +0,0 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
import java.util.Map;
import java.util.Set;
import org.springframework.core.env.Environment;
/**
* The roles that need Redis for <em>correctness</em> rather than for speed.
*
* <p>Session, idempotency, rate limiting and leases all produce a wrong answer when Redis is gone,
* not a slow one: a replayed payment, an unenforced quota, two holders of a lease. Serving traffic
* without them is worse than not serving it, so a deployment that selected any of them gates its
* readiness on Redis. A cache does not appear here — a cache outage is degradation, and taking the
* pod out of service during it removes capacity from a system that is already slower than usual.
*
* <p>This holder exists because that question is asked in two places that must never disagree: the
* condition that decides whether the {@code redisRequired} health contributor is created, and the
* environment post-processor that decides whether the readiness group may name it. When those two
* drifted apart the result was not a subtle mismatch — Boot refuses to start a health group naming
* a contributor that does not exist, so <em>every</em> Redis-off deployment failed at startup with
* {@code Included health contributor 'redisRequired' in group 'readiness' does not exist}. One
* constant, two readers.
*/
public final class RedisCorrectnessRoles {
/** The bean name of the readiness-gating health contributor. */
public static final String REQUIRED_HEALTH_CONTRIBUTOR = "redisRequired";
/** The bean name of the degradation-only health contributor. */
public static final String OPTIONAL_HEALTH_CONTRIBUTOR = "redisOptional";
/** Role selector property to the value that selects Redis for correctness. */
private static final Map<String, String> SELECTORS =
Map.of(
"ca-skeleton.security.auth-mode", "redis-session",
"ca-skeleton.capabilities.idempotency.provider", "redis",
"ca-skeleton.capabilities.rate-limit.provider", "redis",
"ca-skeleton.capabilities.lease.provider", "redis");
/**
* The roles among {@link #SELECTORS} whose Redis programs run on the SCRIPT lane, which
* authenticates as the advanced account. Session is absent: it issues plain commands.
*/
private static final Set<String> SCRIPT_SELECTORS =
Set.of(
"ca-skeleton.capabilities.idempotency.provider",
"ca-skeleton.capabilities.rate-limit.provider",
"ca-skeleton.capabilities.lease.provider");
private RedisCorrectnessRoles() {
throw new AssertionError("RedisCorrectnessRoles is a constant holder");
}
/**
* Reports whether any correctness role selected Redis.
*
* @param environment the environment to read selectors from
* @return {@code true} when at least one correctness role is bound to Redis
*/
public static boolean anySelected(Environment environment) {
return SELECTORS.entrySet().stream()
.anyMatch(role -> role.getValue().equalsIgnoreCase(environment.getProperty(role.getKey())));
}
/**
* Reports whether a correctness role that runs registered scripts selected Redis.
*
* @param environment the environment to read selectors from
* @return {@code true} when the SCRIPT lane carries a correctness role
*/
public static boolean anyScriptRoleSelected(Environment environment) {
return SCRIPT_SELECTORS.stream()
.anyMatch(
selector ->
SELECTORS.get(selector).equalsIgnoreCase(environment.getProperty(selector)));
}
/**
* Returns the selector properties and the values that select Redis, for diagnostics.
*
* @return the selector map
*/
public static Map<String, String> selectors() {
return SELECTORS;
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.command.RedisCommandDescriptor;
import java.util.Objects;
/**
* Connection lane a command must run on.
*
* <p>The lanes exist because their failure modes are incompatible. A blocking command holds its
* connection for the whole block; a transaction owns its connection between {@code MULTI} and
* {@code EXEC}; a subscribed connection cannot run ordinary commands at all; and admin traffic runs
* under a different account. Sharing one pool between them turns any of these into a stall of
* everything else.
*
* <p>A lane also decides <em>which account</em> the command authenticates as — see {@link
* #credentialRole()}. That is not a second concern bolted on: the reason blocking, scripting, admin
* and subscription traffic are separated at all is that each needs a different combination of
* connection behaviour and privilege, and deriving both from one enum is what keeps a command from
* running on the right pool under the wrong account.
*/
public enum RedisConnectionKind {
/** Ordinary non-blocking commands on a shared, thread-safe connection. */
REGULAR,
/** Blocking commands on a dedicated bounded pool. */
BLOCKING,
/** One exclusive connection per optimistic transaction. */
TRANSACTION,
/**
* Registered-script execution, which needs the scripting grants ordinary traffic must not have.
*/
SCRIPT,
/** Subscription lifecycle only. */
PUBSUB,
/** Read-only diagnostics under the admin account. */
ADMIN;
/**
* Returns the credential role this lane authenticates as.
*
* <p>Least privilege only means something if the accounts differ. The application account runs
* ordinary data commands and must not be able to execute a script; the advanced account can, and
* exists so that a compromised request path cannot reach {@code EVALSHA}; admin is read-only
* diagnostics on its own connection. A deployment that configures no separate account for a role
* falls back to the application account, which is a deliberate choice it makes rather than one
* the SDK makes silently — {@code RedisSdkSettings} warns about it at startup.
*
* @return the role whose credentials this lane's connection authenticates with
*/
public RedisCredentialRole credentialRole() {
return switch (this) {
case REGULAR, BLOCKING, TRANSACTION -> RedisCredentialRole.APPLICATION;
case SCRIPT -> RedisCredentialRole.ADVANCED;
case PUBSUB -> RedisCredentialRole.PUBSUB;
case ADMIN -> RedisCredentialRole.ADMIN;
};
}
/**
* Selects the lane a descriptor must run on.
*
* @param descriptor the command descriptor
* @return the required lane
*/
public static RedisConnectionKind forCommand(RedisCommandDescriptor descriptor) {
Objects.requireNonNull(descriptor, "descriptor must be non-null");
if (descriptor.blocking()) {
return BLOCKING;
}
return switch (descriptor.access()) {
case ADMIN_READONLY -> ADMIN;
case APPLICATION, APPLICATION_ADVANCED, RAW_GATEWAY, EXTENSION -> REGULAR;
case NONE -> throw new IllegalArgumentException("a blocked command has no connection lane");
};
}
}
@@ -1,30 +0,0 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
/**
* The Redis account a connection authenticates as.
*
* <p>Redis 6 ACLs authenticate a named user, and the privileges that user carries are the only
* privileges the connection has for its whole life. So "which account" is a property of the
* connection, not of the command — a single client authenticated as one account cannot run some
* commands as a less privileged one.
*
* <p>That is why the roles here exist and why they are separate clients rather than a field on a
* request. A deployment that grants its application account {@code EVALSHA} so that the rate
* limiter works has granted it to every code path that can reach a regular connection, including
* the ones that only ever meant to read a cache entry. Splitting the roles keeps the scripting
* grant on the connections that run scripts.
*
* <p>A role with no configured credential reference is served by the application client. That
* collapses back to the single-account deployment most templates start from, without the SDK
* pretending an account exists that does not.
*/
public enum RedisCredentialRole {
/** Ordinary data commands. The one role every deployment configures. */
APPLICATION,
/** Registered-script execution: {@code SCRIPT LOAD} and {@code EVALSHA} only. */
ADVANCED,
/** Subscription traffic, whose channel patterns are granted separately from keys. */
PUBSUB,
/** Read-only diagnostics, on its own connection so its grants never reach request paths. */
ADMIN
}
@@ -1,83 +0,0 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import java.util.Optional;
/**
* The driver client for one deployment, and the only thing that knows which topology it is.
*
* <p>Everything above this interface is topology-agnostic: an operation asks for a lane and gets a
* {@link RedisCommandGateway}. Which client produced it — standalone, Sentinel-resolving, or
* slot-routing — is settled once, at composition, by the strategy that matched the configured mode.
* That is what keeps "the SDK behaves the same on every topology" a property of the code rather
* than a claim in a document.
*
* <p>Opening a lane is separate from borrowing one. This creates a connection; the registry decides
* whether the caller is allowed to hold one.
*/
public interface RedisRuntimeClient extends AutoCloseable {
/**
* Returns the deployment mode this client was built for.
*
* @return the bound mode
*/
RedisDeploymentMode mode();
/**
* Opens a connection for a lane that needs no routing decision.
*
* @param kind the lane
* @return the open lane
*/
default RedisLaneConnection openLane(RedisConnectionKind kind) {
return openLane(kind, Optional.empty());
}
/**
* Opens a connection for a lane and returns the gateway over it.
*
* <p>The routing key exists for one case, and it is not an optimisation: a Cluster transaction
* runs entirely on one node, so the lane has to be opened against the node that owns the keys
* rather than against the slot-routing connection every other lane uses. Which node that is
* cannot be known from the lane alone — only a key can say — so the caller supplies one.
* Topologies with a single owner ignore it.
*
* @param kind the lane
* @param routingKey a key whose slot decides which node the lane is pinned to, where the topology
* has more than one
* @return the open lane
*/
RedisLaneConnection openLane(RedisConnectionKind kind, Optional<byte[]> routingKey);
/**
* Shuts the client and its event loop down.
*
* <p>Called after every lane has been closed. Shutting the client down first would abort
* in-flight commands that the drain was still waiting for.
*/
@Override
void close();
/** One open connection and the gateway bound to it. */
interface RedisLaneConnection extends AutoCloseable {
/**
* Returns the gateway over this connection.
*
* @return the driver seam
*/
RedisCommandGateway gateway();
/**
* Reports whether the connection is currently usable.
*
* @return {@code true} while the driver reports it open
*/
boolean open();
@Override
void close();
}
}
@@ -1,71 +0,0 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations;
import java.util.List;
import java.util.concurrent.CompletionStage;
import java.util.function.BiConsumer;
/**
* The narrow driver surface subscriptions are written against.
*
* <p>A subscription is not a command with a reply: it occupies its connection for as long as it
* lives. It therefore has its own seam, bound to a connection borrowed from {@code
* RedisConnectionKind.PUBSUB}, so a long-lived listener can never sit on the lane ordinary commands
* share.
*/
public interface RedisPubSubGateway {
/**
* Publishes to a channel.
*
* @param channel the rendered channel
* @param message the encoded message
* @return how many subscribers received it
*/
CompletionStage<Long> publish(byte[] channel, byte[] message);
/**
* Publishes to a shard channel.
*
* @param channel the rendered channel
* @param message the encoded message
* @return how many subscribers received it
*/
CompletionStage<Long> publishSharded(byte[] channel, byte[] message);
/**
* Starts a subscription.
*
* @param targets the rendered channels or patterns
* @param kind whether the targets are channels, patterns, or shard channels
* @param listener receives the rendered channel and the raw message
* @return a handle that stops the subscription
*/
RedisSubscriptionHandle subscribe(
List<String> targets, SubscriptionKind kind, BiConsumer<String, byte[]> listener);
/** What a set of subscription targets means. */
enum SubscriptionKind {
/** Exact channel names. */
CHANNEL,
/** Glob patterns, which are R2 because their fan-out is unbounded. */
PATTERN,
/** Shard channels, available from Redis 7.0. */
SHARD
}
/** A live subscription. */
interface RedisSubscriptionHandle extends AutoCloseable {
/**
* Reports whether the subscription is still delivering.
*
* @return {@code true} until it is closed
*/
boolean active();
@Override
void close();
}
}

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