Configuration Reference#

soda-core's configuration falls into two blocks:

soda.event#

EventProperties is annotated with @ConfigurationProperties(prefix = "soda.event") and @Validated, so a bad configuration throws at startup instead of surfacing at runtime.

soda.event.bus-type#

Values:

soda.event.spring#

SpringProperties is an empty class — with no configurable options at all. It is kept only for the completeness of the configuration structure.

soda.event.serialization#

Serialization settings. There are only two keys, and in 17.0.1 no code actually reads them — serialization is fully handed to the EventSerializer abstraction.

The three values of CircularReferenceHandler:

soda.event.redis#

Redis-related settings. They take effect only when soda.event.bus-type=redis.

soda.event.redis.topic#

The Redis Stream key name. Published events are written to this stream, and consumer groups pull from it.

soda.event.redis.host#

soda.event.redis.port#

soda.event.redis.password#

soda.event.redis.database#

soda.event.redis.stream#

Redis Stream consumption parameters.

soda.event.redis.stream.group-name#

The consumer group name. Multiple consumers in the same group share the message load. Created with XGROUP CREATE at startup; ignored if it already exists.

soda.event.redis.stream.consumer-name#

The consumer name. By default it appends server.port, so multiple instances on one machine don't collide.

With concurrency > 1, the actual consumer names get a suffix: consumerName-0, consumerName-1, …

soda.event.redis.stream.concurrency#

Concurrent consumer threads. One Redis Stream subscription per thread.

soda.event.redis.stream.batch-size#

Maximum entries pulled per XREADGROUP.

soda.event.redis.stream.maxlen#

Maximum stream length. Older messages get trimmed beyond it.

soda.event.redis.stream.poll-timeout#

Blocking timeout for pulls.

soda.event.redis.stream.acknowledge-timeout#

Acknowledgement timeout.

soda.event.redis.stream.max-retries#

Maximum retries on processing failure. The retry loop is for (int retryCount = 0; retryCount <= maxRetries; retryCount++), so there are maxRetries + 1 attempts in total.

soda.event.redis.stream.initial-retry-delay#

Delay before the first retry.

soda.event.redis.stream.exponential-backoff#

Whether to use exponential backoff. When enabled the delay is computed as:

private long calculateRetryDelay(int retryCount) {
    if (exponentialBackoff) {
        return (long) (initialRetryDelay * Math.pow(2, retryCount));
    }
    return initialRetryDelay;
}

With the defaults, the retry delays are 1s, 2s, 4s in sequence.

soda.event.redis.stream.dead-letter-stream#

The dead-letter stream name. Once retries are exhausted, the message is written to this stream along with the failure reason:

Map<String, String> deadLetterEntry = new HashMap<>(message.getValue().size() + 4);
deadLetterEntry.putAll(message.getValue());
deadLetterEntry.put("deadLetterReason", reason);
deadLetterEntry.put("deadLetterTimestamp", String.valueOf(System.currentTimeMillis()));
deadLetterEntry.put("originalStream", message.getStream());
deadLetterEntry.put("originalId", message.getId().getValue());

soda.event.redis.stream.idempotency.enabled#

Whether idempotency is enabled. Recommended for cross-service scenarios.

soda.event.redis.stream.idempotency.redis-key-prefix#

Redis key prefix for idempotency state. The full key is prefix:eventId.

soda.event.redis.stream.idempotency.expire-time#

Expiry for idempotency state.

soda.event.redis.stream.idempotency.retry-interval#

Retry interval for idempotency-state checks.

scoda.ddd.cqrs.async#

AsyncConfig uses the prefix scoda.ddd.cqrs.async. It is enabled by SpringBusAutoConfiguration's @EnableConfigurationProperties(AsyncConfig.class).

The pool's other parameters are hard-coded (not configurable):

Full example#

soda:
  event:
    bus-type: redis
    redis:
      topic: soda-events
      host: 127.0.0.1
      port: 6379
      password: ${REDIS_PASSWORD:}
      database: 0
      stream:
        group-name: soda-events-group
        consumer-name: soda-events-consumer
        concurrency: 2
        batch-size: 20
        maxlen: 50000
        poll-timeout: 1000
        acknowledge-timeout: 30000
        max-retries: 3
        initial-retry-delay: 1000
        exponential-backoff: true
        dead-letter-stream: soda-events-dead-letter
        idempotency:
          enabled: true
          redis-key-prefix: soda-events-idempotency
          expire-time: 86400
          retry-interval: 100

scoda:
  ddd:
    cqrs:
      async:
        core-pool-size: 16
        max-pool-size: 32
        queue-capacity: 200
        thread-name-prefix: "cqrs-async-"

Configuration quick reference#

Next steps#

• The mechanics behind each option: Event Bus & Aspect
• How to replace the framework's defaults: Extension Points
• Which settings change on upgrade: Upgrade from v16