Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ src/main/java/community/solace/spring/cloud/requestreply/
│ ├── logging/LoggerAutoConfiguration.java
│ └── messageinterceptor/ # Noop*Interceptor beans + MessageInterceptorAutoConfiguration
├── env/ # ${replyTopicWithWildcards|...} property source
├── util/ # MessageChunker, CheckedExceptionWrapper
├── util/ # MessageChunker, CheckedExceptionWrapper, MessageTimeToLive
└── exception/ # RequestReplyException
src/main/resources/META-INF/
├── spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports # auto-config registration
Expand Down Expand Up @@ -118,7 +118,9 @@ Invariants the wrappers must preserve:
to close the stream,
- forward a matching `applicationException` as an error reply (`errorMessage` header) which the requester
surfaces as `RemoteErrorException` (or an errored `Flux`),
- copy any headers listed in `copyHeadersOnWrap`.
- copy any headers listed in `copyHeadersOnWrap`,
- set `solace_timeToLive` on every reply, the terminal and error replies included, to the request's
time‑to‑live (see §6).

**Reply routing:** for each `bindingMapping`, `RequestReplyFunctionRegistrar` registers a
`Consumer<Message<?>>` bean named after the binding, wired to `-in-0`, delegating to
Expand Down Expand Up @@ -154,7 +156,9 @@ contexts (see §6). If a bean with the binding name already exists, do not overr
- **Header access goes through the ordered parser chain**, never by reading a hard‑coded header key inline.
To support a new binder or header convention, add a parser bean and order it with `@Order` (lower =
higher priority). Header name constants live in `SpringHeaderParser` (`totalReplies`, `replyIndex`,
`groupedMessages`, `groupedContentType`, `errorMessage`) — reuse them.
`groupedMessages`, `groupedContentType`, `errorMessage`) — reuse them. The one exception is the Solace
message lifetime (`solace_timeToLive`, `solace_expiration`): it is Solace‑only on the write side, so a
pluggable read side would buy nothing, and `MessageTimeToLive` reads and writes it directly.
- **Correlation ids** are generated as a random UUID unless the request already carries one.
- **Reply‑to uniqueness:** reply topics should be process‑unique. Use `${replyTopicWithWildcards|uuid}`
(generated once at process start) — not `${random.uuid}` (new value per reference). The requester listens
Expand All @@ -163,6 +167,14 @@ contexts (see §6). If a bean with the binding name already exists, do not overr
messages bypass dedup. The unknown/streaming growth bound is read as a **JVM system property**
`spring.cloud.stream.requestreply.dedup.maxBitsWhenUnknown` (via `Integer.getInteger`, default 100000) —
it is **not** a Spring `@ConfigurationProperties` value, so it is set with `-D`, not `application.yaml`.
- **Message time‑to‑live follows the timeout.** The requester stamps the timeout as `solace_timeToLive`; a
reply takes the request's time‑to‑live unchanged. A responder cannot know what is left of it: a message
arrives with the time‑to‑live its sender set, and JCSMP does not send the end of life (`expiration`) it
derives from it. `MessageTimeToLive` is the one place that reads and writes it, and it keeps three rules:
stay between 1 ms and ten years (Solace reads 0 as "never expire", and JCSMP refuses to send more than ten
years); never overwrite a lifetime the message already carries; and never set a time‑to‑live and
`solace_expiration` together. On a reply it is set after every other header, `additionalHeaders`
included, so that it sees a lifetime the caller set.
- **Grouping thresholds** are load‑bearing constants: flush at 1 MB, at 10 000 messages, or after the group
timeout (default 200 ms). Changing them affects broker behaviour and interop — do so deliberately and
document it.
Expand Down
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
### Added
- The request/reply timeout is now also the Solace time-to-live (`solace_timeToLive`) of the messages, so a request nobody answered in time, or a reply that comes too late, no longer waits on a persistent queue to be processed after the requester gave up. A request gets the timeout, kept between 1 ms and ten years; a reply built by the `wrap*` helpers gets the time-to-live of the request. A message that already carries `solace_timeToLive` or `solace_expiration` keeps its own lifetime, because the two must never both be set. ([#84](https://github.com/solacecommunity/spring-cloud-stream-request-reply/issues/84))

### Changed
- Requests and replies now expire on a queue that respects the time-to-live. An application that relied on a responder working through requests after the requester gave up has to pass `solace_timeToLive` = `0L` in `additionalHeaders`, which sends a request that never expires. An expired message moves to the queue's dead message queue if there is one, because the Solace binder marks messages DMQ-eligible by default. ([#84](https://github.com/solacecommunity/spring-cloud-stream-request-reply/issues/84))
- A `solace_timeToLive` in a binding's producer `defaultHeader` is now overridden by the library's time-to-live; set it in `additionalHeaders` or an interceptor instead. ([#84](https://github.com/solacecommunity/spring-cloud-stream-request-reply/issues/84))

## [6.1.5] - 2026-11-13
### Changed
- Updated spring-boot-starter-solace-client-config from 3.1.4 to 3.1.5
Expand Down
38 changes: 37 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ to the caller.
- Non‑blocking variants returning `CompletableFuture` or reactive `Flux`.
- **Request / multi‑reply**: receive zero to N answers for one request.
- Per‑request **timeouts** and automatic cleanup of in‑flight bookkeeping.
- The timeout is also the Solace **time‑to‑live** of the request and its replies, so neither waits on a queue
long after the requester gave up.
- Automatic **correlation id** generation and reply‑to routing.
- Helper methods (`wrap`, `wrapList`, `wrapFlux`) for the responder side that set the reply headers for
you and can **forward selected exceptions** back to the requester.
Expand Down Expand Up @@ -199,6 +201,39 @@ Every method takes a `Duration timeoutPeriod`. The request is sent and the reply
executor; if no (final) reply arrives in time the pending request is aborted and a `TimeoutException`
is raised. Bookkeeping for the request is always cleaned up on success, error or timeout.

### Message time‑to‑live

A request that is not answered within the timeout, and a reply that arrives after it, are of no use to
anyone. The library therefore sets the Solace time‑to‑live (`solace_timeToLive`):

- on the **request**, to the timeout, kept within what Solace accepts: a timeout below 1 ms is sent as
1 ms, because 0 means "never expire", and one above ten years as ten years, because JCSMP refuses to
send a longer one;
- on every **reply** built by the `wrap*` helpers, to the time‑to‑live of the request. A reply therefore
lives at most one timeout after it was sent. A request without a time‑to‑live gets replies without one.

A time‑to‑live you set yourself wins: on a request `Message`, in `additionalHeaders`, or copied onto the
reply with `copyHeadersOnWrap`. A time‑to‑live and an expiration must never both be set, so a message that
carries `solace_expiration` gets no time‑to‑live. To send a request that never expires, pass
`solace_timeToLive` = `0L` in `additionalHeaders`. A `solace_timeToLive` in the binding's producer
`defaultHeader` no longer applies, because the Solace binder lets a message header win over a default; set
it in `additionalHeaders` or an interceptor instead.

A message interceptor runs last and sees the time‑to‑live the library set; it may change or remove it.
An interceptor that sets `solace_expiration` has to remove `solace_timeToLive`.

A request `Message` that arrived over Solace carries `solace_timeToLive` and `solace_expiration` already,
0 if its sender set none. Sent on as a request, it keeps that lifetime instead of taking the timeout;
remove both headers to get the timeout.

`additionalHeaders` given to `wrap` apply to the replies the wrapped function returns, not to the error
reply of a forwarded exception, which always takes the request's time‑to‑live.

The broker only expires guaranteed messages, and only on a queue that respects the time‑to‑live
(`respect-ttl`). It discards an expired message, or moves it to the queue's dead message queue if there
is one: the Solace binder marks messages DMQ‑eligible by default (`solace_dmqEligible`). On a direct
message the time‑to‑live has no effect.

### Single vs. multi response

- **Single response** — you expect exactly one answer. Use `requestAndAwaitReply*` (blocking) or
Expand Down Expand Up @@ -573,7 +608,8 @@ See [`examples/customized_logging`](examples/customized_logging) for a full appl
[`examples/customized_reply_to_header_response`](examples/customized_reply_to_header_response).

Both interfaces receive the binding name so you can behave differently per binding. If you do not
provide your own, no‑op implementations are auto‑configured.
provide your own, no‑op implementations are auto‑configured. The message an interceptor receives already
carries the time‑to‑live the library set (see [Message time‑to‑live](#message-timetolive)).

### Extending to other binders

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ public interface RequestReplyService {
* @param request the request to be sent
* @param requestDestination the topic name to send the request to. Example: my.supper.topic
* @param expectedClass the class the response shall be mapped to.
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
default <Q, A> A requestAndAwaitReplyToTopic(
Expand All @@ -41,7 +41,7 @@ default <Q, A> A requestAndAwaitReplyToTopic(
* @param request the request to be sent
* @param requestDestination the topic name to send the request to. Example: my.supper.topic
* @param expectedClass the class the response shall be mapped to.
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @param additionalHeaders additional headers to be added to the request message
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
Expand All @@ -61,7 +61,7 @@ <Q, A> A requestAndAwaitReplyToTopic(
* @param request the request to be sent
* @param bindingName the message channel name to send the request to. Example: requestReplyRepliesDemoTibrv
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
default <Q, A> A requestAndAwaitReplyToBinding(
Expand All @@ -81,7 +81,7 @@ default <Q, A> A requestAndAwaitReplyToBinding(
* @param request the request to be sent
* @param bindingName the message channel name to send the request to. Example: requestReplyRepliesDemoTibrv
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @param additionalHeaders additional headers to be added to the request message
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
Expand All @@ -103,7 +103,7 @@ <Q, A> A requestAndAwaitReplyToBinding(
* @param request the request to be sent
* @param bindingName the message channel name to send the request to. Example: requestReplyRepliesDemoTibrv
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
default <Q, A> CompletableFuture<A> requestReplyToBinding(
Expand All @@ -125,7 +125,7 @@ default <Q, A> CompletableFuture<A> requestReplyToBinding(
* @param request the request to be sent
* @param bindingName the message channel name to send the request to. Example: requestReplyRepliesDemoTibrv
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @param additionalHeaders additional headers to be added to the request message
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
Expand All @@ -147,7 +147,7 @@ <Q, A> CompletableFuture<A> requestReplyToBinding(
* @param request the request to be sent
* @param requestDestination the topic name to send the request to. Example: my.supper.topic
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
default <Q, A> CompletableFuture<A> requestReplyToTopic(
Expand All @@ -169,7 +169,7 @@ default <Q, A> CompletableFuture<A> requestReplyToTopic(
* @param request the request to be sent
* @param requestDestination the topic name to send the request to. Example: my.supper.topic
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @param additionalHeaders additional headers to be added to the request message
* @return a {@link CompletableFuture} which can be used to await and retrieve the response
*/
Expand All @@ -191,7 +191,7 @@ <Q, A> CompletableFuture<A> requestReplyToTopic(
* @param request the request to be sent
* @param bindingName the message channel name to send the request to. Example: requestReplyRepliesDemoTibrv
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @return a {@link Flux} which can be used to receive responses
*/
default <Q, A> Flux<A> requestReplyToBindingReactive(
Expand All @@ -213,7 +213,7 @@ default <Q, A> Flux<A> requestReplyToBindingReactive(
* @param request the request to be sent
* @param bindingName the message channel name to send the request to. Example: requestReplyRepliesDemoTibrv
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @param additionalHeaders additional headers to be added to the request message
* @return a {@link Flux} which can be used to receive responses
*/
Expand All @@ -236,7 +236,7 @@ <Q, A> Flux<A> requestReplyToBindingReactive(
* @param request the request to be sent
* @param requestDestination the topic name to send the request to. Example: my.supper.topic
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @return a {@link Flux} which can be used to receive responses
*/
default <Q, A> Flux<A> requestReplyToTopicReactive(
Expand All @@ -258,7 +258,7 @@ default <Q, A> Flux<A> requestReplyToTopicReactive(
* @param request the request to be sent
* @param requestDestination the topic name to send the request to. Example: my.supper.topic
* @param expectedClass the class the response shall be mapped to
* @param timeoutPeriod the timeout when to give up waiting for a response
* @param timeoutPeriod the timeout when to give up waiting for a response, also set as the Solace time-to-live of the request unless it carries a lifetime of its own
* @param additionalHeaders additional headers to be added to the request message
* @return a {@link Flux} which can be used to receive responses
*/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
import org.slf4j.event.Level;

import static community.solace.spring.cloud.requestreply.util.CheckedExceptionWrapper.throwingUnchecked;
import static community.solace.spring.cloud.requestreply.util.MessageTimeToLive.setTimeToLiveIfAbsent;

/**
* The RequestReplyService takes care of asynchronous request and reply messages, relating one to the other and allowing to wrap both as a synchronous call.
Expand Down Expand Up @@ -344,6 +345,7 @@ private <Q> CompletableFuture<Void> requestReply(
messageBuilder.setHeader(header.getKey(), header.getValue());
}
}
setTimeToLiveIfAbsent(messageBuilder, timeoutPeriod);

Message<?> toSend = requestSendingInterceptor.interceptRequestSendingMessage(messageBuilder.build(), bindingName);

Expand Down
Loading
Loading