Configuration

FlowWarden is zero-config by design. Almost everything — checkpoint behavior, retry policies, DLQ policy, deployment strategy — is configured per-stream via annotations on your @ChangeStream classes. A small number of properties exist for application-wide concerns: execution mode and backend-level defaults.

Application Properties

Property	Type	Default	Description
`flowwarden.default-mode`	`IMPERATIVE` \| `REACTIVE`	`IMPERATIVE`	Execution mode for all FlowWarden streams in the application.
`flowwarden.dlq.mongo.collection`	`String`	`_fw_dlq`	Backend-level default MongoDB collection for the Dead Letter Queue. Per-stream override via `@MongoDlqOptions(collection = ...)`.

flowwarden:
  default-mode: IMPERATIVE   # or REACTIVE
  dlq:
    mongo:
      collection: _fw_dlq    # global default; per-stream override via @MongoDlqOptions

If flowwarden.default-mode is not set, FlowWarden defaults to IMPERATIVE and logs:

INFO  FlowWardenConfigurationValidator - No 'flowwarden.default-mode' configured, defaulting to IMPERATIVE

Spring MVC applications can omit this property entirely. Spring WebFlux applications must set it to REACTIVE explicitly.

`flowwarden.dlq.mongo`

The MongoDB-backed DlqStore writes failed events to a single default collection unless a stream opts out via @MongoDlqOptions. The TTL index on expiresAt is created at startup for every collection bound to a @DeadLetterQueue-annotated stream.

Property	Type	Default	Description
`flowwarden.dlq.mongo.collection`	`String`	`_fw_dlq`	Default collection name used when a stream does not declare `@MongoDlqOptions(collection = ...)`.

This namespace is Mongo-specific. Other backends (Kafka, RabbitMQ, JDBC) ship analogous property prefixes (flowwarden.dlq.kafka.*, etc.) once their DlqStore implementations land.

ExecutionMode values

Value	Description
`IMPERATIVE`	Blocking mode. Uses Spring’s `MongoTemplate` with dedicated threads. Handler methods return `void`.
`REACTIVE`	Non-blocking mode. Uses `ReactiveMongoTemplate` and Project Reactor. Handler methods return `Mono<Void>`.

The mode is application-wide — you cannot mix imperative and reactive handlers in the same application. See Handler Signatures for the validation rules.

What is configured by annotation, not by property

Most behavior settings live on per-stream annotations, not on application.yml:

Concern	Where to configure
Resume token persistence frequency	`@Checkpoint` (`saveEveryN`, `saveIntervalSeconds`)
Retry behavior on failure	`@RetryPolicy` (`maxAttempts`, `initialDelay`, `multiplier`, `maxDelay`, `jitter`, `retryOn`, `noRetryOn`)
Dead Letter Queue policy	`@DeadLetterQueue` (`enabled`, `retentionDays`, `includeOriginalDocument`, `includeStackTrace`)
Mongo-specific DLQ collection	`@MongoDlqOptions` (`collection`) — backend companion to `@DeadLetterQueue`
Multi-instance coordination	`@ChangeStream(deploymentMode = ...)`
Server-side filtering	`@Pipeline`
Application-side filtering	`@Filter`
Custom error handling	`@OnError`
Multi-database routing	`@ChangeStream(mongoTemplateRef = ...)`

This keeps stream configuration next to the code that uses it, instead of fragmenting it between annotations and YAML.

MongoDB connection

FlowWarden uses Spring Data MongoDB’s auto-configured MongoTemplate (or ReactiveMongoTemplate). Configure the connection with standard Spring properties:

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/mydb

MongoDB must be configured as a Replica Set for Change Streams to work. This applies to development environments as well. Testcontainers provisions a single-node Replica Set automatically for tests.

Disabling FlowWarden globally

To disable all streams without removing the @EnableFlowWarden annotation, set the attribute on the annotation itself:

@SpringBootApplication
@EnableFlowWarden(enabled = false)
public class MyApplication { }

This is useful for maintenance mode or environment-specific profiles where streams should not start. See @EnableFlowWarden.

@EnableFlowWarden

Auto-configuration entry point and global on/off switch.

@ChangeStream

Per-stream attributes — the main place to configure behavior.

Handler Signatures

Mode-dependent return type rules.

Actuator

Operational endpoints and metrics.

Annotations

Runtime

SPI

Application Properties

`flowwarden.dlq.mongo`

ExecutionMode values

What is configured by annotation, not by property

MongoDB connection

Disabling FlowWarden globally

See Also

@EnableFlowWarden

@ChangeStream

Handler Signatures

Actuator

​Application Properties

​flowwarden.dlq.mongo

​ExecutionMode values

​What is configured by annotation, not by property

​MongoDB connection

​Disabling FlowWarden globally

​See Also

@EnableFlowWarden

@ChangeStream

Handler Signatures

Actuator

Application Properties

`flowwarden.dlq.mongo`

ExecutionMode values

What is configured by annotation, not by property

MongoDB connection

Disabling FlowWarden globally

See Also