Spring Boot Duration binding: make timeout units explicit

The checked binding

RelaySettings declares timeout as Duration. The Boot fixture starts with a 2s default, then runs with --relay.timeout=450ms. It asserts Duration.ofMillis(450), not 450 seconds or an unlabelled numeric value. The unit suffix is part of the operator contract.

A typed field prevents one common conversion error, but it does not set a safe deadline by itself. A 450-millisecond value might be too short for the target service or too long for a request budget. Startup validation should reject missing or out-of-range values; the current fixture validates non-null but does not impose a numeric timeout range.

Budget the whole operation

A connect timeout is only one stage. DNS, connection acquisition, request write, response read and retries consume the same wall-clock operation budget. Name each configured deadline and state whether it applies per attempt or across all attempts. If a retry loop can run indefinitely, a correct Duration parse does not save the service from exhaustion.

The test does not open a network connection. It checks binding, not timeout enforcement. The retry lesson covers stored due times; this setting could eventually control an adapter, but that wiring is still absent.

Checked source

record RelaySettings(@Min(1) @Max(100) int batchSize,
                     @NotNull Duration timeout) { }
// --relay.timeout=450ms binds to Duration.ofMillis(450).

Verification boundary

BootRelaySettingsTest.explicitDurationUnitBindsWithoutGuessingMilliseconds. The excerpt is shortened or a labelled design sketch; the kit contains the checked tests.

Costs and limits

The test proves one explicit unit through Boot binding. It does not test negative durations, overflow, deployed timeouts or whole-operation deadlines.

Common Mistakes

• Do not document a naked number when the unit matters.
• Do not confuse a parsed timeout with enforced cancellation.
• Do not set per-attempt timeouts without an overall budget.

Read next

Spring Boot command-line properties: test the effective value at startup, Spring Boot configuration validation: reject an unusable relay before work starts, Spring outbox retries: due time, delay cap, and attempt accounting, Spring Boot configuration properties: bind values and reject bad startup input.