Skip to content

feat: let request and reply expire when the requester stops waiting - #85

Draft
GreenRover wants to merge 6 commits into
masterfrom
feature/issue-84-time-to-live
Draft

GreenRover wants to merge 6 commits into
masterfrom
feature/issue-84-time-to-live

Conversation

@GreenRover

@GreenRover GreenRover commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #84

What

The request/reply timeout now also sets the Solace time-to-live (solace_timeToLive) of the exchange:

  • Request: the requester sets the timeout as the time-to-live, kept between 1 ms and ten years. 0 would mean "never expire", and JCSMP refuses to send a time-to-live above ten years.
  • Reply: every reply built by wrap, wrapList and wrapFlux takes the request's time-to-live unchanged. That includes grouped, terminal and error replies. A request without a time-to-live gets replies without one, so a mix of old and new versions behaves as before.

A request nobody answered in time, or a reply that came too late, no longer waits on a persistent queue to be processed after the requester gave up. A reply lives at most one timeout after it was sent.

Design decisions to review

  • The reply copies the request's TTL; it does not compute a remaining time. A responder cannot know what is left. A message arrives with the TTL its sender set, and in JCSMP 10.30.2 the end of life (expiration) is derived only locally at sending and is not sent while a TTL is set (resetExpirationBinaryMeta). A remaining time would need a deadline from the requester and would depend on the clocks agreeing, for a gain of a few seconds.
  • Explicit values win, and there is no new property. A message that already carries solace_timeToLive keeps it. The sources are a request Message, additionalHeaders, a message interceptor, or copyHeadersOnWrap. To opt out per request, pass solace_timeToLive = 0L in additionalHeaders.
  • A TTL and an expiration are never set together. A message that carries solace_expiration gets no TTL added. On a wrap reply the TTL is set after additionalHeaders, so an expiration given there is seen. A message interceptor runs last and sees the TTL; one that sets solace_expiration has to remove it (documented).
  • A forwarded Solace message keeps its lifetime. The Solace binder puts solace_timeToLive and solace_expiration on every inbound message, 0 if unset. Forwarded as a request, such a message keeps that lifetime; the README says to remove both headers to get the timeout. Treating a 0 value as "no lifetime" would make the explicit opt-out solace_timeToLive = 0L indistinguishable from it.
  • Error replies of wrap take the request's TTL. additionalHeaders never applied to the error reply of a forwarded exception, and still do not.
  • No parser for the lifetime. MessageTimeToLive is the only place that reads and writes solace_timeToLive and solace_expiration. Writing is Solace-only, so a pluggable read side would buy nothing. AGENTS.md §6 names this as the one exception to "header access goes through the parser chain". The change adds no public API apart from MessageTimeToLive.
  • Behaviour change, version to decide. A request now expires on a queue with respect-ttl enabled. If an application relied on a responder working through requests after the requester gave up, it has to pass solace_timeToLive = 0L. The CHANGELOG lists this under Changed. Whether that needs a major version (AGENTS.md §4) is the maintainer's call; pom.xml is untouched. Direct messages are not affected. For a non-Solace binder, the request carries one extra solace_timeToLive header.- Expired messages go to the DMQ, if there is one. The Solace binder marks messages DMQ-eligible by default (solace_dmqEligible). Where a queue has a dead message queue, expired requests and replies collect there instead of disappearing. The library leaves solace_dmqEligible alone; the DMQ is the operator's choice.
  • A defaultHeader TTL is overridden. The binder applies the producer defaultHeader first and the message headers on top. A solace_timeToLive configured there, which is the workaround the issue names, is therefore replaced by the library's value. README and CHANGELOG point to additionalHeaders or an interceptor instead.

pom.xml is unchanged. The CHANGELOG entry is under [Unreleased]. doc/spec.yaml is deliberately unchanged: it lists user headers, and the time-to-live is a field of the Solace message.

Tests

  • RequestReplySimpleServiceTests, five tests. The mocked send answers at once, so no test waits for a timeout, and a request cannot time out before it is sent:
    • the timeout is sent as a Long time-to-live, blocking and reactive;
    • a time-to-live in additionalHeaders wins;
    • a time-to-live on the request message is kept;
    • a request that carries solace_expiration gets no time-to-live.
  • RequestReplySimpleMessageHeaderSupportServiceTests, eight tests:
    • the request's time-to-live on wrap, on the error reply, on grouped wrapList, and on every wrapFlux reply including the finishing one;
    • no time-to-live when the request has none or 0;
    • additionalHeaders win;
    • no time-to-live when additionalHeaders give an expiration.
  • MessageTimeToLiveTests: a time-to-live below 1 ms is written as 1 ms, and one above ten years (ChronoUnit.FOREVER) as ten years.
  • Negative controls: each production line was reverted on its own, and the tests that guard it failed. The results are below.
Production line broken Tests that went red
requester sets no time-to-live 2 (blocking and reactive)
reply copies no time-to-live 4 (wrap, error reply, grouped wrapList, wrapFlux)
wrap copies it before additionalHeaders 1 (expiration in additionalHeaders)
lists, fluxes and error replies copy none 3 (error reply, grouped wrapList, wrapFlux)
no 1 ms minimum 1 (MessageTimeToLiveTests)
no ten-year maximum 1 (MessageTimeToLiveTests)
an existing time-to-live overwritten 3 (additionalHeaders on request and reply, request message)
solace_expiration ignored 2 (request message, reply additionalHeaders)
0 copied as a time-to-live 1 (request that never expires)

mvn -Dgpg.skip verify: BUILD SUCCESS. 109 tests ran, with 0 failures, 0 errors and 0 skipped. The new code adds no Javadoc warnings.

A request nobody answered in time, or a reply that came too late, stayed on
a persistent queue without a time-to-live and was processed long after the
requester had given up. The request now carries the timeout as its Solace
time-to-live, and a reply what is left of it on the responder's clock.

Closes #84
A message arrives with the time-to-live its sender set, not with what is
left of it: JCSMP derives the end of life at sending and does not hand it
on while a time-to-live is set. The reply's time-to-live is therefore an
upper bound, longer by as long as the request waited to be delivered.
A responder cannot know what is left of the request's time-to-live, so
computing a remaining time bought a few seconds for clock and timestamp
logic. The reply's time-to-live is now set after the caller's headers, so
that it never lands next to an expiration the caller gave.
JCSMP refuses a time-to-live above ten years, so a caller that passed a
huge timeout to wait forever could no longer send its request. The
changelog now lists the expiry as a change in behaviour, and the README
says what an interceptor and a request forwarded from Solace get.
A request whose timeout ran out before a worker picked it up was never
sent, so verifying the send after a 100 ms timeout could fail on a busy
agent. The docs now say what a forwarded Solace message, an error reply
and a custom time-to-live parser get.
@GreenRover
GreenRover requested a review from helios57 November 21, 2026 20:08
The time-to-live parsers were public API with a single, Solace-only
implementation, while writing the lifetime is Solace-only anyway. A
parser for another binder would have read its time-to-live only to write
it into a Solace header that binder ignores.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Derive message time-to-live from the request-reply timeout

1 participant