[rvowles]

Summary

Fixes across the SSE and REST clients (OKHttp, Jersey 2, Jersey 3).

Shared Jersey read loop, quiet-stream backoff and tidy-ups (latest round)

• Jersey SSE read loop in core: the connect, read and close loop the two Jersey SSE clients duplicated now lives in a new abstract BlockingStreamEdgeService in client-java-core, for any library whose connections are read by blocking. Core sees the library only through small Stream/Event interfaces, so it gains no Jersey (or other) dependency. Each JerseySSEClient is now a thin subclass that opens the stream, says what HTTP status a failure carries and closes its JAX-RS Client.
• Close interrupts every connection: close() cancels every connection task the client started, including connections a context change replaced that are still finishing, not just the current one. Finished tasks are forgotten as new connections are made.
• Backing off on streams that never send anything: a stream that stays open past the connect timeout counts as working even if it sends nothing, as a resumed stream that is up to date is quiet. Something between us and Edge (e.g. a proxy) that accepts the connection, passes nothing through and drops it once idle therefore made us reconnect every few seconds forever, with no backoff. Now, after 3 such streams in a row that sent nothing at all (StreamingConnectionTracker.MAX_QUIET_STREAMS), later ones count as a CONNECTION_FAILURE, so the normal backoff applies and grows. Any real event (including a bye) or a server-evaluated context change resets the count.
• Backoff multiplier visibility: EdgeRetryer's backoff multiplier is now volatile, so a reset made on one thread can't be lost on another.
• cancelReconnects() docs: its javadoc now says a retryer used with the streaming clients must implement it (the default does nothing), and what goes wrong if it doesn't.
• SERVER_READ_TIMEOUT deprecated: no supplied client reports it any more. It is kept, and still handled by EdgeRetryer, as other EdgeService implementations may report it.

Shared connection handling, client vs server evaluation, and failure rules

• Shared code in core: the connection, context, waiting-caller and retry bookkeeping that was copied across the three SSE clients now lives in a new StreamingConnectionTracker in client-java-core. The clients only make and read connections. Jersey now uses the same claim-then-connect model as OKHttp. A new EdgeStatus holds the HTTP status rule used by every client.
• Client-evaluated keys never wait: for client-evaluated keys, contextChange and poll only make sure the connection has started and return straight away. With streaming, init() and build().get() therefore return before features arrive. Use waitForReady() or a readiness listener if you need them. Server-evaluated contexts still wait for their own features. The REST path is unchanged.
• Only 400, 401, 403 and 404 are permanent, in every client (SSE and REST): they stop requests and, if no features had arrived, mark the repository Failed. SSE reports 400/404 as an unknown API key (API_KEY_NOT_FOUND) and 401/403 as not permitted (FAILURE), which is often a wrong URL. 429, 5xx, network errors and non-304 redirects keep readiness as it is and are retried.
• Failed only when no reconnect is coming: the repository is marked Failed only once the retryer has stopped or a library clash means retrying can't help. A brief failure at startup leaves readiness at NotReady (previously OKHttp, and in this PR Jersey, set Failed on every lost connection while still NotReady).
• Cancelling stale backoffs: EdgeRetryer.cancelReconnects() (a new default method on EdgeRetryService) interrupts a backoff in progress so it never reconnects. A server-evaluated context change that overrides a pending retry calls it. This replaces the scheduledRetries counters, and stops an old backoff holding a later reconnect up behind it on the retryer's single thread. The tracker queues a lost connection's reconnect, and cancels reconnects on a context change, while holding its lock, so a cancel can never run between a connection being released and its reconnect being queued. A cancelled backoff doesn't grow the backoff multiplier.
• Backoff reset for quiet streams: a stream that worked without sending features (e.g. a resumed one the server is up to date with) reports success once when it is lost, so the retryer's backoff resets as it does when features arrive.
• Bye backoff: after a bye, the SSE clients always wait featurehub.edge.bye-backoff-ms (default 300ms, EdgeRetryerBuilder.withByeBackoffMs()) before reconnecting, on top of featurehub.edge.server-by-reconnect-ms. A stream that says bye straight away counts as working, so without this a misbehaving server could cause a tight reconnect loop.
• Jersey threads: each connection runs on its own thread from a shared pool of daemon threads, rather than one thread per client. A new context's connection therefore starts straight away instead of queueing behind the old context's blocked read, and a client that is dropped without close() no longer leaves an idle thread behind. close() interrupts that client's connection rather than shutting a pool down. The constructor warning about context changes taking up to the read timeout has been removed.
• Jersey Errors while connecting: any Throwable is caught. A LinkageError (e.g. a library version clash) gives up without retrying and marks us failed; anything else is retried. Previously an Error left the connection pending forever and callers hung.
• Failure event with no data: OKHttp now records it in the repository, as Jersey does, rather than releasing callers as if features had arrived.
• Jersey context changes while connecting: each server-evaluated context change claims its own connection. An attempt for an earlier context that completes later is closed rather than reused.

SSE: Last-Event-ID

• All three SSE clients now record the id of the last event received and send it back as Last-Event-ID when reconnecting. Events without an id leave it unchanged.
• The id is recorded only once the event has been applied, so if applying it fails, the reconnect has the server send it again.
• When a server-evaluated context change alters the x-featurehub header, the last event id is cleared, so the new context's stream starts fresh.

SSE: context changes and reconnects

• Jersey: a context change no longer shuts down the retryer, which previously made the follow-up connection fail with RejectedExecutionException.
• Stale connections: connections replaced by a context change, or closed, are now ignored. Late events, failures and closes from them no longer update features, record ids or trigger reconnects. In OKHttp, the failure caused by cancelling the old connection previously triggered a second connection that was never closed.
• Locking: connecting, context changes and the "is this connection still current?" check share a lock.
  • A context change resets the connection and decides whether the caller must wait in one step, so a racing reconnect can't complete the change before the new context's features arrive.
  • When connecting, the client reads the context header and Last-Event-ID together and claims the connection in the same step. A reconnect that races a context change therefore can't replace the newer connection or mix one context's header with another's id.
  • A connection superseded while it was being made is cancelled. In OKHttp, close and failure release the connection before reconnecting, so a context change and a scheduled reconnect don't both connect.
  • Features and readiness futures are processed outside the lock, so listeners and future callbacks that change context can't deadlock. As a trade-off, an event that was already being applied when the context changed can still finish applying. The new context's connection then sends its own full feature set. Only the current connection releases waiting callers, so those old features never tell the new context's callers they are ready.
• Waiting callers: the list of waiting readiness futures is guarded by the lock, and futures are removed once completed.
  • Callers wait until we have features for the current context, rather than being released as soon as a connection exists. Once we have them, a reconnect (e.g. after a server bye) doesn't make callers wait for the new connection to send them again. Only a full feature set (or a failure) counts; other events, or one that fails to apply, release the callers already waiting, but later callers still wait.
  • When the current connection fails, can't be made or is closed by the server, waiting callers are released with the current readiness. They no longer wait for a reconnect that may never come, e.g. while Edge is down or after the retryer has stopped.
  • Those waiting are taken in the same locked step that gives the connection up, so a caller who starts waiting on the replacement isn't released before its features arrive.
  • An event that fails to apply releases those waiting, rather than leaving them waiting while the stream stays open.
• After close or a terminal stop: once closed, or once the retryer has stopped (e.g. a bad API key or edge.stale), a client never connects again, and context changes and polls complete immediately. Closing is checked and set under the lock, so a racing context change can't wait forever.
• OKHttp client creation: the OkHttpClient is created under a lock, so two connections being made at once can't each build (and leak) one.
• OKHttp failed connects: if the connection can't even be created (e.g. a bad URL), the client retries with backoff and releases waiting callers. An OKHttp version conflict doesn't retry, as retrying can't fix it.
• OKHttp connection never opened: a failure before the connection opened (an unresolvable host, a 5xx from a proxy, etc.) now backs off like a refused connection (about 5s, growing to the 30s cap). It was treated as a working stream dropping, which reconnects immediately by default, so the client reconnected in a tight loop: over 100,000 attempts in 3 seconds for an unresolvable host. A working stream that drops still reconnects immediately.
• Respecting the backoff: while the retryer is backing off after a lost or failed connection, a poll or context build no longer connects early (it previously skipped the backoff, and with client evaluation every newContext().build() started a new connection attempt while Edge was down). The reconnect is left to the retryer, and callers get the current readiness rather than waiting. A server-evaluated context change still connects straight away, as the new context needs its own features, and cancels the retryer's pending reconnect. Jersey makes and reads connections on daemon threads of its own rather than the retryer's, so that connection isn't held up behind the retryer's backoff.
• Streams that never worked, and quiet streams: a stream counts as working if it sent anything other than an ack or config (a bye counts), or stayed open for at least the connect timeout (minimum 1s). Losing a working stream reconnects straight away. A stream that sends nothing, or only an ack, and is dropped quickly (e.g. a proxy that accepts the connection and immediately closes it) backs off as a connection failure rather than reconnecting in a tight loop. This matters because a stream resumed with a Last-Event-ID the server is up to date with legitimately sends nothing until the server says bye or a disconnect, so a quiet stream that hits the read timeout (typically 3 minutes) or is dropped by the server reconnects straight away.
• Resuming: Last-Event-ID is only sent once we have the context's features. Otherwise the server would treat us as up to date and send nothing, and callers would wait for features that never come.
• Retryer visibility: EdgeRetryer's stopped flags are now volatile, as callers' threads read them to decide whether to wait.
• Rejected requests: in both OKHttp and Jersey, 401/403 stop the retryer as a permission failure, and 400/404 as an unknown API key. Other 4xx responses, such as 429 too many requests or 408, back off and retry rather than stopping the client for good (Jersey previously stopped on any 4xx).
• OKHttp close: a connection that was starting when the client closed no longer builds a new OkHttpClient that nothing shuts down.
• Jersey connection handling:
  • close() always stops the retryer.
  • A server bye or close now triggers a reconnect, using the bye or disconnect timing as appropriate.
  • Superseded connections are closed.
  • A context change that happens while connecting is detected, and the client reconnects with the new context. This holds even if the context changed back again in the meantime, so a connection opened with an earlier context's Last-Event-ID is never kept.
  • Any non-terminal failure to connect (refused, unresolvable, timed out, 429, 5xx, whether or not Jersey wraps it in a ProcessingException) backs off as a connection failure (starting around 5s), as OKHttp does, rather than as a read timeout capped at 30s.
  • A failed connection attempt for an earlier context no longer counts against the new context; the client connects again for the new context straight away.
  • Closing the client while it is connecting is not reported as a failure.
  • When the server rejects us (400/401/403/404), the repository is marked failed and waiting callers are released, instead of hanging.
  • A read failure on a stream that has already sent us something (e.g. it was idle for the read timeout) reconnects straight away, as OKHttp does, rather than backing off for up to 30s.
  • The current connection is claimed before it is made, so repeated polls, reconnects and builds of the same context can't queue duplicate connections.
  • A connection replaced by a context change stops as soon as its read returns, rather than reading again.
• Jersey non-blocking close: close() and context changes close the connection on a shared pool of daemon threads, and closes run concurrently rather than queueing behind each other. Closing a Jersey EventInput while another thread is reading it otherwise blocks until the read times out. close() also closes the client's JAX-RS Client, again in the background.
• Jersey API change: the protected makeEventSource() is now makeEventSource(header, lastEventId). Subclasses that override it need updating.
• Jersey 3: now reports X-SDK as Java-Jersey3 instead of Java-Jersey2.

SSE: timeouts

• The OKHttp SSE client now uses the retryer's connect and read timeouts. Previously it used OKHttp's 10-second default read timeout, so it dropped and reconnected any stream that was idle for 10 seconds.
• The default SSE read timeout (featurehub.edge.server-sse-read-timeout-ms) is now 3 minutes (180000 ms), which is what the README documents. It was previously 1800000 ms (30 minutes). This also affects the Jersey SSE clients.

REST: compression

• The Jersey 2 and 3 REST clients now request gzip/deflate and decompress responses. OKHttp already does this by default.

REST: stopping when requests are pointless

• When the server rejects the OKHttp REST client's requests (400/401/403/404), or it has been closed, it now makes no further requests. Previously it set a flag that nothing checked, so it kept polling. poll() and contextChange() return the current readiness without a request, and isStopped() reports it, so active polling stops scheduling.
• The Jersey REST clients now behave the same way: they stop on 400/401/403/404 (previously only 400/404), whether the status is returned or thrown, stop when closed, and make no further requests once stopped.
• Any other failure (429, 5xx, a network error, a non-304 redirect) is logged and leaves readiness as it is, in both OKHttp and Jersey; polling carries on. Previously both clients marked the repository Failed on these.
• OKHttp REST polling now builds its request through the protected buildRequest() hook (as the SSE client does), so subclass overrides such as extra auth headers apply.
• The polling wrapper's close() now always closes the client behind it. Previously it skipped a stopped client (after a rejection or the usage limit being reached), leaving OKHttp's thread pools to time out by themselves.

Other

• Example and POM updates. The examples' request/response payload logging is at debug (FINE) rather than INFO.
• java11_changed.txt, release_modules.txt and java17_changed.txt regenerated with detect_module_changes.sh.

Known limitations

• A Jersey or OKHttp connection replaced by a context change may still be applying an event when the change happens, and those old features can still be written to the repository. The new context's connection then sends its own full feature set, and the old features never release the new context's callers.

Follow-ups

• Jersey SSE: let a context change cancel the old connection's blocked read #59 Jersey SSE: let a context change cancel the old connection's blocked read (addressed in this PR: new connections no longer wait behind the old read)
• Move the duplicated SSE and REST client logic into a shared helper in client-java-core #60 Move the duplicated SSE and REST client logic into a shared helper in client-java-core (SSE logic addressed in this PR, including the Jersey read loop via BlockingStreamEdgeService; the REST clients only share EdgeStatus)
• EdgeRetryer: support cancelling or superseding a pending reconnect #61 EdgeRetryer: support cancelling or superseding a pending reconnect (addressed in this PR by cancelReconnects())
• Jersey REST client: close the JAX-RS Client on close() #62 Jersey REST client: close the JAX-RS Client on close()

Testing

New Spock tests cover:

• a context change while connecting
• a late reconnect after a context change
• context changes not being blocked by event processing or readiness callbacks
• Last-Event-ID preserved across reconnects and cleared on a context change
• ignoring superseded connections
• close() stopping the retryer and not blocking
• reconnect after a server bye
• OKHttp SSE timeouts
• gzip responses against a real Jersey server
• the OKHttp REST client making no further requests, and active polling stopping, after a rejection, and still being shut down when closed
• the OKHttp SSE client backing off when the connection never opened (including a 429 or 408), and reconnecting immediately when an open one drops
• callers waiting on a replacement connection not being released by the old one, and callers released when an event fails to apply
• no new OKHttp client after close, and the Jersey JAX-RS client being closed
• the Jersey REST clients stopping on 400/401/403/404 (returned or thrown) and on close
• failed connects retrying, and no reconnects after close
• duplicate Jersey connections, replaced Jersey connections stopping, and concurrent closes
• Last-Event-ID not moving past an event that failed to apply
• a replaced connection's features not releasing the new context's callers
• no connecting after the retryer stops, and callers released when the server rejects us (401/403/4xx)
• callers released when the connection is lost or can't be made, and waiting for a new connection's first features
• polls and context builds not connecting while the retryer is backing off, and a server-evaluated context change still connecting straight away
• no waiting after a reconnect once we have features
• Jersey backing off and retrying on 429/408, and reconnecting straight away when a working stream times out
• OKHttp REST polling using buildRequest()
• backing off when a stream ends before sending anything, in OKHttp and Jersey
• a server-evaluated context change during a backoff cancelling the retryer's reconnect, a cancelled reconnect never reconnecting and not holding later ones up, and the Jersey connect thread being a daemon
• StreamingConnectionTracker: client-evaluated contexts never waiting, server-evaluated contexts waiting for their features, replaced connections being ignored, the 400/404 rule, Failed only once the retryer stops, failure events with no data, abandoning a connection, and Last-Event-ID only resumed once we have features
• client-evaluated context changes not waiting, transient failures (429, 5xx, network errors) not marking us failed in SSE and REST, 401/403 stopping every client, and a library clash marking us failed without retrying
• a lost connection's reconnect being queued before a racing context change can cancel it, quiet working streams resetting the backoff, a cancelled backoff not growing the multiplier, and the bye backoff (its 300ms default, its property, it delaying the reconnect, and cancelling it)
• Jersey: an Error while connecting not leaving anyone waiting, and a new context's connection not waiting behind the old context's blocked read
• quiet resumed streams that hit the read timeout or are dropped by the server reconnecting straight away, ack-only streams that drop quickly backing off, and no Last-Event-ID before we have features
• non-feature events not marking the context as having features
• Jersey: a failed attempt for an earlier context being ignored, close while connecting not reporting a failure, 5xx/timeouts backing off as connection failures, and close interrupting its connection without shutting the shared pool down
• Jersey connections not waiting behind the retryer's backoff, connections for an earlier context (A -> B -> A) being discarded, and wrapped connection failures being recognised
• BlockingStreamEdgeService: events being applied, the failure status deciding whether we stop, close interrupting every connection task (including replaced ones), finished tasks being forgotten, client-evaluated contexts not waiting, and concurrent closes
• backing off after 3 quiet streams in a row, and a real event or a context change resetting the count

The Jersey modules gain objenesis as a test-scope dependency, so Spock can mock Jersey's SSE classes.

All module tests pass locally: core 174, OKHttp 98, Jersey 2 100, Jersey 3 100 (counting each data-driven case), and ./build_only.sh builds the whole reactor.

🤖 Generated with Claude Code