Configuration#

soda's configuration surface is small: one bus-type switch + a set of Redis options + one thread pool. This page covers how to configure them, where they go, and the three easiest pitfalls. For the complete key-by-key list see Configuration Reference.

Where configuration goes#

soda uses Spring Boot's standard mechanism: application.yml (or .properties), with profiles for per-environment isolation.

# application.yml — shared by all environments
soda:
  event:
    bus-type: simple          # write it explicitly, don't rely on the default

scoda:
  ddd:
    cqrs:
      async:
        core-pool-size: 8

# application-prod.yml — production overrides
soda:
  event:
    bus-type: redis
    redis:
      host: ${SODA_REDIS_HOST}
      password: ${SODA_REDIS_PASSWORD}

Minimal usable configuration#

Three situations — pick the one that matches yours:

Single instance / development / testing: in-process bus#

soda:
  event:
    bus-type: simple

Done. No Redis needed; events are dispatched synchronously inside one JVM.

Production / multiple instances: Redis event bus#

soda:
  event:
    bus-type: redis
    redis:
      host: ${SODA_REDIS_HOST}
      port: 6379
      password: ${SODA_REDIS_PASSWORD}
      database: 0
      topic: soda-events

Prerequisites:

• The soda-event-redis dependency is on the classpath (see Installation)
• The project has a usable RedisTemplate / StringRedisTemplate (Spring Data Redis auto-configuration provides one)

Configure nothing#

It runs, but don't.

With bus-type unset, SimpleEventBusAutoConfiguration's matchIfMissing = true activates the in-process bus. The behavior is correct, but the intent is unclear — six months later nobody knows whether Simple was the plan or the key was simply forgotten.

Redis bus options worth tuning#

The defaults get you through development; for production, look at these:

Idempotency#

Redis Stream is at-least-once delivery — the same event may be consumed more than once. Recommended for cross-service scenarios:

soda:
  event:
    redis:
      stream:
        idempotency:
          enabled: true
          redis-key-prefix: soda-events-idempotency
          expire-time: 86400          # seconds, default 24 hours

With it on, the consumer first checks the eventId's processing state: SUCCESS / PROCESSING are skipped outright, FAILED is allowed to retry.

Async thread pool#

CQRS's async exits (sendAsyncCommand and friends) run on a dedicated thread pool:

scoda:
  ddd:
    cqrs:
      async:
        core-pool-size: 8
        max-pool-size: 16
        queue-capacity: 100
        thread-name-prefix: cqrs-async-

When the queue fills up, the rejection policy is run on the caller's thread (no tasks are dropped, but the calling thread blocks). So when queue-capacity is saturated, Web request threads get stuck along with it. For production:

• Don't set queue-capacity too large — the queue is a buffer, not a warehouse
• Monitor the pool's active count and queue depth
• To take over completely, define your own Executor bean named cqrsAsyncExecutor

The three most common misconfigurations#

Configuration validation#

EventProperties carries @Validated, so misconfigurations fail at startup instead of surfacing at runtime:

A Binding to target ... failed line in the startup log is this layer catching it — fix the key/value as the message suggests.

Next steps#

• Type, default, and validation rule of every key: Configuration Reference
• How the bus and aspect get wired up: Event Bus & Aspect
• How to replace the default implementations: Extension Points