FlowWarden Redis
Redis-backed LockService and CheckpointStore for FlowWarden Stream Core.

---

What is this?

flowwarden-redis provides Redis-backed implementations of the LockService and CheckpointStore SPIs defined in flowwarden-stream-core. It is a drop-in alternative to the default MongoDB backends shipped in the core library, useful when your Spring Boot application already runs Redis (cache, sessions, pub/sub) and you'd prefer to keep your distributed locks and Change Stream checkpoints there instead of in MongoDB.

Both the blocking and reactive Spring Data Redis stacks are supported. Auto-configuration wires the right beans automatically.

Add the dependency

Maven

<dependency>
    <groupId>io.flowwarden</groupId>
    <artifactId>flowwarden-redis</artifactId>
    <version>1.0.0-rc.1</version>
</dependency>

You'll also need flowwarden-stream-core (the SPI provider) and spring-boot-starter-data-redis (the Redis client). If you import the flowwarden-bom, version coordination is handled for you:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.flowwarden</groupId>
      <artifactId>flowwarden-bom</artifactId>
      <version>1.0.0-rc.3</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.flowwarden</groupId>
    <artifactId>flowwarden-stream-core</artifactId>
  </dependency>
  <dependency>
    <groupId>io.flowwarden</groupId>
    <artifactId>flowwarden-redis</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
  </dependency>
</dependencies>

Configure

Configure your Redis connection the standard Spring Boot way:

spring:
  data:
    redis:
      host: localhost
      port: 6379

Optional: namespace the Redis keys used by FlowWarden (defaults to fw:):

flowwarden:
  redis:
    key-prefix: "myapp:"

What gets wired

When StringRedisTemplate is on the classpath (the default whenever you include spring-boot-starter-data-redis), FlowWarden registers:

• RedisLockService as the LockService bean — replaces the default MongoLockService from the core.
• RedisCheckpointStore as the CheckpointStore bean — replaces the default MongoCheckpointStore.

Both registrations are guarded by @ConditionalOnMissingBean, so any explicit @Bean LockService or @Bean CheckpointStore you declare wins. This is the escape hatch to cohabit Mongo + Redis backends in the same app (for example: locks in Redis, checkpoints in Mongo).

Reactive variants

ReactiveRedisLockService and ReactiveRedisCheckpointStore ship in the library but are not auto-configured — Spring Boot's Redis starter creates both blocking and reactive templates whenever Lettuce is on the classpath, so there is no reliable conditional that picks one without surprising the user. Wire them explicitly when you want non-blocking Redis ops in a Spring WebFlux app:

@Bean
LockService lockService(ReactiveStringRedisTemplate t, RedisStreamCoreProperties p) {
    return new ReactiveRedisLockService(t, p.getKeyPrefix());
}

@Bean
CheckpointStore checkpointStore(ReactiveStringRedisTemplate t, RedisStreamCoreProperties p) {
    return new ReactiveRedisCheckpointStore(t, p.getKeyPrefix());
}

The user beans win over the auto-configured blocking ones automatically.

Storage layout

Key	Type	Description
{prefix}lock:{streamName}	Hash	instanceId, acquiredAt, expiresAt. TTL via PEXPIREAT to expiresAt.
{prefix}checkpoint:{streamName}	Hash	instanceId, lastSeenToken (base64 BSON), lastSeenTimestamp, lastProcessedToken (base64 BSON), lastProcessedTimestamp, metadata (JSON). No TTL.

Acquire / renew / release on locks are executed as Lua scripts to keep the compare-and-set atomic. saveSeen and saveProcessed use targeted HSET so the dual-token semantics from the core (see Checkpoint Javadoc) are preserved natively rather than via the SPI's read-modify-write default.

Compatibility

Component	Minimum	Recommended
Java	17	21
Spring Boot	3.2.x	3.2.x+
Spring Data Redis	3.2.x (via Boot BOM)	3.2.x+
Redis Server	6.0	7.x+
FlowWarden Stream Core	1.0.0-rc.3	1.0.0-rc.3+

Documentation

• FlowWarden Stream Core — the library this satellite extends.
• FlowWarden docs — full documentation.

Contributing

See CONTRIBUTING.md and the Code of Conduct.

License

Apache License 2.0 — see LICENSE.