NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #4682 most downloaded on Packagist
Async-first NATS + JetStream client for PHP 8.2+
Latest stable
v2.28.0
Last release 19 days ago
03 Nov 2026
Ships fairly regularly
a new release about every 3 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
8 months old
67 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
[feature] New NatsOptions::$resendJetStreamPublishOnReconnect (default false): a JetStream publish() that carries a $msgId writes its frame once more
[feature] New NatsOptions::$resendJetStreamPublishOnReconnect (default false): a JetStream publish() that
carries a $msgId writes its frame once more on the new connection when the connection it went out on is replaced -
a reconnect, or a lame-duck failover - before its PubAck came (#249). Such a publish used to wait out the rest of its
request timeout on the new connection and throw a TimeoutException (outcome unknown) whenever the server that took
the frame, the stream's leader, went down with the connection: nothing sent it again, though the client had already
failed over and the Nats-Msg-Id makes a second copy harmless. Measured in ideaconnect/symfony-nats-messenger#95 on
a three-server cluster (nats-server 2.15.1, requestTimeoutMs 10 s): the retry publish of a failed handler ended
after 10.3 s with the timeout and the worker exited, while the same frame published again on the recovered connection
was stored at once.
With the option on, the request behind the publish remembers the connection generation its frame went out on. Once
the reconnect is over and that generation has moved, it writes the same frame (subject, payload, headers and the same
reply subject on the replayed reply inbox) on the new connection, within its own timeout, and whichever reply comes
first resolves the publish: the stream answers a copy it already stored with a PubAck whose duplicate is true. At
most once per publish attempt; a reconnect after that second write writes nothing more. Only a replaced connection
triggers it, never a slow reply (a second publish after a plain timeout misfired in the measurements: a slow leader
answered it with a 409, and with the whole cluster down the wait doubled). A 409 duplicate message id is in process
(ApiErrCode::STREAM_DUPLICATE_MESSAGE_CONFLICT, err_code 10158, NATS 2.11+) answering the second frame is not the
outcome: the first frame is still being stored, so the publish keeps waiting for its ack and ends with the
TimeoutException when none comes; answering a frame written once it still fails the publish as before. The second
write is logged at info (NATS request sent again on the new connection, with the subject and both generations,
never the payload). A publish whose own read notices the lost connection with waitForReconnect: false still fails at
once, and with reconnect off nothing changes. Publishes without a $msgId, plain requests, JetStream API calls,
atomic batches and Key/Value or Object Store writes are never sent again.
Off by default because of two limits, documented with the option: the stream's duplicate_window must be longer
than the request timeout (the 2-minute default is), and on a NATS 2.10 cluster a new stream leader can take a publish
before it has applied what the old leader replicated, so a copy may be stored twice there (read from the server
source; 2.15.1 applies first, and the release that changed it is not pinned down).
[bugfix] A publish, a JetStream ack()/nak()/term()/inProgress() or a request made after the server had
closed the connection, while nothing read the socket, no longer goes into the closed socket (#252). The connection
reads the socket only while an operation waits for a reply, so a close the server sends meanwhile (a restart, a
rolling upgrade, a failover, docker stop) stayed unread, and a write that waits for no reply was still taken by
the socket and reached no server: the publish resolved and its message was lost; an ack() was lost and the message
came back after its ack_wait and was handled again. A request's frame was lost the same way, and the request waited
for its reply on the recovered connection until its timeout. Measured in ideaconnect/symfony-nats-messenger#98 on a
three-server cluster (nats-server 2.15.1, the worker's server stopped with docker stop while a handler ran): the
ACK of a handled message, before 1 of 1 still pending after the run, now 0; the Symfony retry copy of a failed one
(a JetStream publish), before a TimeoutException after 10.7 s that ended the worker, now stored at once.
Before such a write the connection now asks the transport whether the server has closed the socket, and handles a
yes as a write that failed there (#244, #215): a publish hands its frame to the reconnect buffer and resolves, the
frame going out on the new connection after the subscription replay; a request recovers and writes again within its
budget. With reconnect off the write fails with Reconnect is disabled (the found close its previous) instead of
resolving with the frame lost. The question is new, optional Transport\PeerCloseAwareTransportInterface::peerClosed(),
which both built-in transports implement with a peek at the socket: it reads nothing, does not wait and takes about
half a microsecond. A custom transport without it is written to as before.
The peek sees a close with nothing left unread before it. A close behind bytes not read yet - a frame the server sent
just before stopping, or over TLS the close_notify alert the server sends ahead of its close - is still found only
by the next read, as before; so is a WebSocket server's Close frame.
[docs] New PeerClosedBeforeWriteTest (18 cases, #252): a publish (plain, with headers, an ack(), a nak(), a
header block segment, each waiting and not waiting for a reconnect) into a session the server closed unread goes out
once on the new connection after the replay, nothing into the closed socket; a request is sent on the new connection
and gets its reply well before its timeout; with reconnect off both fail at once; an open socket is asked once per
write; AmpSocketTransport and WebSocketTransport answer false with no socket, on an idle one and while bytes wait
(which the next read still gets), and true once the peer has closed; a close behind unread bytes, over TCP and over
TLS, is left for the next read; and end to end on a real socket an ack published after the server closed the
connection reaches the server on the next one. 14 cases fail without the check. tests/Support/PeerClosingTransport.php
closes a scripted session unread; tests/Support/LoopbackNatsServer.php now accepts one connection after another
and records what was published on each.
[docs] New JetStreamPublishResendOnReconnectTest (22 cases, #249) over ReconnectingTransport: a publish whose
connection drops right after its HPUB went out sends the same frame on the new session and returns its ack (stored
now, or a duplicate) well before its timeout, logged without the payload; a lame-duck failover does the same, and so
does a publish waiting behind the application's own read loop as the connection drops. When both copies are
answered in one read, the first ack resolves the publish and the second is ignored. A second write that fails,
and fails again after its own reconnect, is logged as a warning and leaves the publish to its deadline; a logger
that throws on the second write's record changes nothing. Guards: without a msgId (with other headers or none),
with the option off or with waitForReconnect: false nothing is written again and the publish ends as before; a
counter increment and a scheduled publish, the other JetStream requests with headers, are never written again
either (a second increment would count twice); a publish with an invalid subject is refused before it subscribes its
reply inbox or writes anything; a batch request with nothing left to send writes nothing; a
slow ack without a reconnect gets no second write; a 10158 answering the second frame leaves the publish waiting for
the first frame's ack, or ending with the timeout, while one answering a frame written once still fails it, and so
does another error answering the second frame; the second write never extends the timeout; and a second reconnect
after it writes no third copy. 12 of the 22 fail with the resend disabled; the other 10 are guards. The counter,
scheduled-publish and invalid-subject cases kill the three mutants a local Infection run on the changed lines found
escaping, and NatsOptionsTest now checks the option's default (off), whose flip no test caught.
[docs] Four mutants of the #214 change that no unit test killed are now covered (#247). CI's Mutation job never
sees them: its 20 s budget per mutant skips them as too slow. A local diff-mode run with a 300 s budget found them.
PullConsumerStatusInTheChunkOfAConnectionEndingFrameTest (now 18 cases): a routine status (404, 408,
409 Leadership Change, 503) or a 423 ahead of a 409 Consumer Deleted in the chunk of a fatal -ERR does not
hide the 409. onError gets it once, and the run pulls nothing on the new connection. A classification that
stopped at the first routine status, or after a 423, pulled on there.PullConsumerPinRetentionTest: a single 423 in the retire phase makes the group acquire its next pin serially.
In the existing case, the second pull's own 423 restarted the serial acquisition too, so a 423 that dropped the
pin without restarting it went unnoticed. A 423 delayed past a newer pin leaves the group pipelining: the #208
tests checked only that the pin stays.Each new test was checked against a hand-mutated copy of JetStreamContext loaded with auto_prepend_file: each
mutant fails the new test aimed at it, while every existing test of both classes passes on it. No production code
changed.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
An infinite pull consumer run (pullConsumer()->handle()) now ends on a terminal pull status that arrives in the same read as a frame that ends the con
Patch release.
An infinite pull consumer run (pullConsumer()->handle()) now ends on a terminal pull status that arrives in the same read as a frame that ends the connection (#214).
Since 2.23.0 (#210), an infinite run outlives a fatal -ERR such as Stale Connection, or a PONG the socket would not take, once the reconnect has reopened the connection. It hands what its pulls held to your handler and goes on. A pull status read in the same chunk as that frame was dropped with the pulls, unread. That chunk is what a process blocked long enough to draw Stale Connection finds when the consumer is deleted meanwhile, because nats-server answers every waiting pull with 409 Consumer Deleted. The 409 never reached onError, and the run kept polling. On the deleted consumer each pull then got a 503, which the run treats as routine and reports once. So the application heard of a server outage, not of a deleted consumer, and the run never ended. The same 409 read on its own already ended the run.
Now each pull that brought no message is classified the way the retire phase classifies an empty pull, once every pull's messages have gone to the handler:
onError gets the status once, what the overflow holds goes to the handler, and handle() returns the count. Nothing is pulled on the new connection.423 drops the pin that request sent (#208), and the group acquires its pin serially again.409 Leadership Change, 503), or none, changes nothing. The run pulls on as after an EOF.Who should upgrade: anyone running infinite pull consumers on a server where consumers can be deleted while the process stalls, for example under a long garbage collection or a blocking call. There are no API changes.
handle(), with the 409 delivered to onError once. Code that relied on the run going on must start it again, as it already did for a 409 read on its own.onError.codecov/patch 100%: every changed line is covered (47 of 47). Total coverage 99.05%.PullConsumerStatusInTheChunkOfAConnectionEndingFrameTest, 13 cases over a reconnecting scripted server. 7 of them fail on 2.27.1. The other 6 are guards that pass on both.The full record is in the CHANGELOG.
[bugfix] A pull status read in the same chunk as a frame that ends the connection reaches onError (#214). Since
2.23.0 (#210) an infinite run goes on past a fatal -ERR (Stale Connection, say) or a PONG the socket would
not take once the reconnect has reopened the connection, handing what its pulls held to the handler. The read that
meets the frame routes what its chunk brought before it throws, so a status from that chunk is on its pull by then,
and the pulls used to leave the run with it unread: a terminal 409 Consumer Deleted, which nats-server sends every
waiting pull as the consumer goes and which a process blocked long enough to draw Stale Connection finds in the
socket next to the -ERR, never reached onError, and the run pulled on, on a deleted consumer meeting the
no-responders path (a 503, routine, reported once) and never ending. The same status read on its own, before an
EOF, ended the run. Now, once every pull's messages have gone to the handler, each pull that brought no message is
classified in issue order as the retire phase classifies an empty retire: a terminal status ends the run as it ends
it there (the inbox closed first, #211, then onError once, what the overflow holds handed over, the count
returned, no pull on the new connection), a 423 drops the pin the request sent (#208), the group acquiring its pin
serially again, and a routine status, or none, changes nothing. A pull that brought messages keeps its status
unclassified, as in the retire phase. Both paths share the classification (isRoutineEmptyRetireOfAnInfiniteRun(),
dropsThePinA423Rejected()) and the end on a terminal status (reportTerminalStatus()), so that they keep in step.
Found by the review of #210 (2.23.0).[docs] New PullConsumerStatusInTheChunkOfAConnectionEndingFrameTest (13 cases, #214) over ReconnectingTransport
seen through WatchedTransport: a 409 in the chunk of a fatal -ERR, with the reconnect done within the read and
outlasting its wait, reaches onError once and ends the run with no pull on the new connection; what the pulls held
goes to the handler before the status goes to onError, and what the overflow took during the hand-over after it; a
rejection of the inbox while the run closes it, or during that overflow's hand-over, ends the run with the
rejection; a 423 there makes the next pull go out without the pin and the group acquire its pin serially again; and,
as guards, a routine status (404, 408, 409 Leadership Change, 503) leaves the run going, a pull that brought a
message keeps its 409 unclassified, and a stop() during the hand-over keeps its precedence. 7 fail on 2.27.1.Patch release, with upgrade notes: read "Before upgrading".
Patch release, with upgrade notes: read "Before upgrading".
A plain publish whose write is the first to notice a lost connection no longer waits for the reconnect (#244).
Up to now such a publish ran the whole reconnect loop in the caller's fiber, with no budget or cancellation, and wrote the frame again once the loop was over. At the default policy (10 attempts, 100 ms doubling to 10 s) that is about 100 s for a server that does not come back. A second publisher whose write failed meanwhile joined the same wait. Through the Symfony Messenger transport, a plain ack() that met an outage returned after 103 s, while one issued a moment later, once the heartbeat had noticed, returned in under a millisecond.
The frame now goes to the reconnect buffer, as a publish made during a reconnect always did, and the publish resolves once the frame is accepted there. The reconnect runs on its own and flushes the frame after the subscription replay. This covers publish(), publishWithHeaders(), a JetStream ack(), nak(), term() and inProgress(), respond(), service replies, and the intermediates of an atomic batch.
Disconnected listener can neither take its room in the buffer nor close the connection first.Reconnected listener used to let such a drain close the connection before the publish's retry.Who should upgrade: anyone who publishes or acks fire-and-forget with reconnect on. A worker whose ack met a dead socket was stuck for the whole reconnect.
errorListener (Reconnect exhausted: N bytes of buffered publishes were discarded) and the Closed event, not through the publish. It used to fail with Reconnect attempts exhausted. A resolved ack() never meant the server recorded it: use ackSync() for that.reconnectBufferSize: 0, or a full buffer, the publish fails at once with Connection is not open, the write's error as its previous one, and the reconnect goes on.disconnect() stays lossy. A disconnect() during the reconnect discards the accepted frame without a report, as it discards every buffered publish. A write that fails after you closed and reopened the connection now fails the publish, instead of being written to the new connection.flush() after the publish. It waits for the reconnect within requestTimeoutMs when waitForReconnect is on.publishGuarded(), the pull consumer engine's publish, keeps its inline recovery.Reconnect is disabled.ackSync() and JetStream publishes keep their bounded request path.codecov/patch: every modified coverable line is covered. Total coverage 98.98%.FailedPublishWriteTest, 41 cases over the scripted reconnecting server, plus a live test: a plain ack() whose write meets a severed socket resolves while dials are refused, and the server records it once the connection is back. The six comparison cases from the issue's review pass against the implementation.OperationTakesItsQueuedMessageTest, a 0.5 s bound measured at 0.518 s under coverage in random order). That test passes in isolation under coverage, and the rerun, the PR run and main's run passed.The full record is in the CHANGELOG.
A plain publish whose write is the first to notice a lost connection no longer waits for the reconnect (#244). This
covers publish(), publishWithHeaders(), a JetStream ack(), nak(), term() and inProgress(), respond(), a
service's replies, flow-control replies and the intermediate messages of an atomic batch. Read these before upgrading:
Reconnect attempts exhausted when the reconnect gave up.errorListener (Reconnect exhausted: N bytes of buffered publishes were discarded) and the Closed event, not from the publish. A resolved ack() never meant the server
recorded the ack: use ackSync() for that, or a JetStream publish for a PubAck.Connection is not open,
the write's error as its previous one: buffering disabled (reconnectBufferSize: 0), or the buffer full. The
reconnect still goes on. A producer that relied on the inline wait to slow down now meets that limit. To wait for
the frame to go out, call flush(), which waits for the reconnect within requestTimeoutMs when
waitForReconnect is on.disconnect() stays lossy. A disconnect() during the reconnect discards the accepted frame without a report,
as it discards every buffered publish. The frame is never sent on a later connection. Such a publish used to fail.
The same holds for a write that fails after you closed and reopened the connection: the publish now fails with its
write's error and nothing is sent on the new connection, where the frame used to be written to it.ack() met the dead socket used to return only
after the reconnect. Code that relied on that, in tests too, calls flush() after the publish.publishGuarded(), the pull consumer engine's internal publish, keeps the inline recovery and retry: its guard must
run again after the subscription replay. With reconnect off, a failed write still fails the publish with Reconnect is disabled. Requests, ackSync() and JetStream publishes keep their bounded request path.
[bugfix] A fire-and-forget publish whose write failed on a connection still reported Open ran the whole reconnect
loop inline (#244). writePublishFrame() called recoverConnection() in the caller's fiber, with no budget or
cancellation, and wrote the frame again once the loop was over. With the defaults (10 attempts, 100 ms doubling to
10 s) that is about 100 s for a server that does not come back, and a second publisher whose write failed meanwhile
joined the same wait. The same frame published a moment later, once the heartbeat had noticed the loss, was
buffered at once. Measured through idct/symfony-nats-messenger (ideaconnect/symfony-nats-messenger#81): an ack()
that met the outage returned after 103 s, one issued during the reconnect in under a millisecond.
The failed frame now goes to the reconnect buffer, and the recovery runs in a fiber of its own. The frame is
accepted, or refused, inside the recovery's claim: right after the recovery owns the connection and has left Open,
before it calls a listener or the logger, closes the socket or dials. Decided in the publisher instead, the decision
came after the Disconnected listener, which could fill the buffer first or close the connection. A write that
fails while another recovery runs puts its frame into that recovery's buffer without waiting for it. The other states
are routed explicitly. Closed, being closed, or closed and reopened since the write began: the publish fails with
its write's error, a raw stream error wrapped in a TransportClosedException. Draining: the frame goes to the socket
the drain holds, within its budget. Open on a newer connection: one direct retry. A connect() of your own dialling:
the frame is refused. A drain that waits for the reconnect now finds the frame sent, where a slow Reconnected
listener used to let the drain close the connection before the retry.
[docs] New FailedPublishWriteTest (41 cases, #244) over ReconnectingTransport, with the recovery's dial held
where the publish must be done first. It covers the publish, an HPUB, a JetStream ack() and a header block
segment, each with and without waiting for a reconnect, resolving while the dial is held, then sent once after
CONNECT and the replay. The other cases: a second failed write, and one failing while another fiber's recovery
runs, joining that recovery's buffer; a Disconnected listener that publishes or closes; the buffer disabled, an
exact fit, one byte short, full, and a segment larger than the buffer; persistent and partial flush failures and an
ambiguous one; authentication failure; slow and throwing listeners and loggers; a close before the recovery claims
the connection; what the recovery's fiber finds when it runs; the one tick a frame buffered that way yields; a sealed
flush; a drain waiting for the reconnect and one already under way; an atomic batch committed behind its buffered
intermediates, or failed when they do not fit. The close and claim cases use the new
tests/Support/HeldFailingWriteTransport.php, which holds a write back and fails it when the test says.[docs] New live test JetStreamIntegrationTest::testAPlainAckWhoseWriteMeetsTheDeadSocketReachesTheRestoredServer:
a plain ack() whose write meets a severed socket resolves while dials are refused, and the consumer has nothing
waiting for an ack once a flush returns after the reconnect.[docs] Restaged for the new contract: the NatsConnectionTest failed-publish cases (ordering now by admission;
the #144 handler test fails its write once; the others wait for Open), CloseIntentTest (a disconnect discards the
accepted frame; a late write after a reopen fails; new: a write failing during a disconnect is wrapped),
OperationReadReconnectTest and PullConsumerReconnectTest (a handler or onError that publishes on the dead
connection waits for the reconnect with flush()). The ReconnectedListenerTest cases that pin the retry after the
reconnect now use publishGuarded(), which keeps it.A subscription-limit failure is now a SubscriptionLimitException, a new final subclass of ConnectionException (#242).
Minor release.
A subscription-limit failure is now a SubscriptionLimitException, a new final subclass of ConnectionException (#242).
The server answers a SUB beyond the connection's limit with -ERR 'maximum subscriptions exceeded'. The client used to report that, and the errors it builds for a reply inbox the -ERR dropped, as a plain ConnectionException. A caller could tell the limit apart only by matching the message. The client now builds the typed error in every place it built a limit error:
-ERR, whether it throws it or hands it to the error listener (the heartbeat, a reconnect's replay and the other reporting reads);SUB the new server rejected for it.The type tells the reason, not the connection's state. The server sends the same -ERR when it refuses a SUB and keeps the connection open, and when an account's limit is lowered and it closes the connection about 20 ms later.
Who should upgrade: anyone who handles the subscription limit, such as symfony-nats-messenger, whose next release turns it into Symfony's TransportException (ideaconnect/symfony-nats-messenger#76).
catch (ConnectionException) and catch (NatsThrowable) matches, and the messages are unchanged. Only code that compares the exact class name sees the difference.JetStreamException. When the subscribe reported the rejection, the typed error is its previous one.-ERR included.codecov/patch 100%: every changed line is covered. Total coverage 98.98%.SubscriptionLimitExceptionTest, 6 cases. 3 of them fail on 2.26.8; the other 3 are guards.JetStreamInboxRejectionTest and MuxInboxRejectionTest now assert the type of every limit error they produce. 24 of their cases fail on 2.26.8's source.max_subscriptions 1 and 2.The full record is in the CHANGELOG.
SubscriptionLimitException. It extends ConnectionException, so every
catch (ConnectionException) and catch (NatsThrowable) still catches it, and its message is unchanged. Only code
that compares the exact class name, such as $e::class === ConnectionException::class, sees the difference.[feature] New IDCT\NATS\Exception\SubscriptionLimitException, a final subclass of ConnectionException, for the
connection's subscription limit (#242). A caller could recognise the server's -ERR 'maximum subscriptions exceeded'
only by matching exception text, since the one classifier, NatsClient::isSubscriptionLimitError(), is internal and
takes the bare -ERR. The client now builds the typed error wherever it built a plain ConnectionException for the
limit: the read that meets the -ERR (Server sent error frame: ..., thrown, or handed to the error listener by the
heartbeat, a reconnect's replay and the other reading loops that report it); a request whose shared reply inbox was
dropped for it; a pull fetch or batched Direct Get whose reply inbox was dropped for it; and a guarded subscribe
whose replayed SUB the new server rejected for it. The type tells the reason, not the connection's state: the
server sends the same -ERR when it refuses a SUB beyond the limit, keeping the connection open, and when an
account's limit is lowered below what the connection holds, closing the connection about 20 ms later. And since the
-ERR names no subscription, an error about a reply inbox still says the server may have rejected it. A pull
consumer run keeps failing with a JetStreamException; when the subscribe itself reported the rejection, the typed
error is its previous one. Other server errors keep the plain class. Asked for by
ideaconnect/symfony-nats-messenger#76, which turns the limit into Symfony's TransportException for its pulls.[docs] New SubscriptionLimitExceptionTest (6 cases, #242) over SubscriptionLimitServer: the operation whose read
meets the limit -ERR fails with the typed error, the heartbeat's read hands the listener the same type, the -ERR
of a server that closes the connection behind it is typed the same while the EOF still ends the connection, and three
other server errors keep the plain class (guards). JetStreamInboxRejectionTest and MuxInboxRejectionTest now
assert the type of every limit error they produce, the typed previous error of a fetch and a pull consumer run whose
replayed inbox was rejected, and the plain class of a permissions violation and a fatal -ERR;
ExceptionHierarchyTest asserts the new class is a ConnectionException and a NatsThrowable.When a maximum subscriptions exceeded -ERR drops the shared reply inbox, its UNSUB is now written only on the connection the inbox was dropped on (#19
Patch release.
When a maximum subscriptions exceeded -ERR drops the shared reply inbox, its UNSUB is now written only on the connection the inbox was dropped on (#193).
The client releases a dropped inbox because the -ERR may have been another subscription's, in which case the server still holds the inbox. Up to now, that pending release survived a reconnect. Two things followed:
UNSUB again on the new connection, which never held it.UNSUB after the one the replay writes.A reconnect now forgets the old connection's pending releases, as it already did for JetStream's guarded inboxes (#175). An UNSUB the replay writes settles that inbox's release, so it isn't written again.
Who should upgrade: anyone who wants the wire free of redundant UNSUBs after reconnects at the subscription limit. The server ignores an UNSUB for a sid it doesn't hold, so nothing was lost or held. There are no API changes.
-ERR and still held by the server is released by the next request's install, ahead of the new SUB, or by a drain (#213).codecov/patch 100%: every changed line is covered. Total coverage 99.05%.MuxReleaseAcrossReconnectTest, 11 cases over a server that enforces a subscription limit. 8 of them fail on 2.26.5.testAPullConsumerRunEndedByATerminalStatusHandsOverWhatALaterPullReceivedAfterIt (#211). The PR run of the same commit passed.The full record is in the CHANGELOG.
[bugfix] The UNSUB a dropped shared reply inbox owes is written only on the connection it was dropped on (#193).
A mux dropped for a maximum subscriptions exceeded -ERR is queued for release, since the -ERR may have been
another subscription's and the server may still hold it, and the next request's install (or a drain, #213) writes
its UNSUB ahead of the new SUB. The queue outlived a reconnect: a mux dropped on a connection then lost was
released again on the new one, which never held it, and a replayed mux the new server rejected got a second UNSUB
after the one the replay writes. connectOnce() now forgets the old connection's mux releases, as it does the
guarded inboxes' (#175), and finishReplayWindow() takes the sid whose UNSUB it writes off the mux list. The
release on the same connection is unchanged. The server ignores an UNSUB for a sid it does not hold, so this only
removes wasted bytes. Found by the review of #175 (2.19.0).[docs] New MuxReleaseAcrossReconnectTest (11 cases, #193) over SubscriptionLimitServer: a mux dropped and its
connection lost, a replayed mux the new server rejects, the same after the first SUB's write fails (each through
request() and requestMany()), a drain after each, and the same-connection release kept for the next install and
for a drain (guards). 8 fail on 2.26.5.A chunk that a custom transport hands over late now stays on the connection its read started on (#205). "Late" means after that connection was replace
Patch release.
A chunk that a custom transport hands over late now stays on the connection its read started on (#205). "Late" means after that connection was replaced by a reconnect, or closed. The chunk is parsed with that connection's parser and dispatched as that connection's frames.
Before, the late bytes went into the new connection's parser and were treated as the new server's:
PING was answered on the new connection;PONG, or a late reply, could confirm the new connection's reply inbox;INFO replaced the new server's info;PING was swallowed and never answered.Now the whole late chunk follows the rule the client already applies to the rest of a lame-duck chunk (#182):
PING, PONG and INFO are not applied to the new connection;-ERR is reported as the old server's.If the late chunk ends in corrupt bytes, the client still reports the parse failure and delivers the messages ahead of them. It does not start or join a recovery of the new connection. The heartbeat's read follows the same rules.
Who should upgrade: anyone with their own TransportInterface implementation whose readLine() can complete after close() and a new connect(). The built-in AmpSocketTransport and WebSocketTransport can't, because their close() ends a pending read. There are no API changes.
TransportInterface::readLine() docblock: a read belongs to the connection it started on. End pending reads when close() ends that connection. Never return one connection's bytes from a read started on another. Start each connect() with fresh buffers. The client's new handling covers a late read, but it can't separate bytes that a read started on the new connection receives from the old one.codecov/patch 100%: every changed line is covered. Total coverage 99.05%.LateTransportReadTest, 35 cases over a transport that holds a read across a reconnect, 31 of which fail on 2.26.5.dispatchFrames() ignore the passed origin. One more variant passes the whole unit suite: the recovery guard checking the generation alone, without the close count. It differs only after a terminal close, where recovery cannot run, so that half of the guard is kept as defensive code.The full record is in the CHANGELOG.
[bugfix] A chunk a custom transport hands over after the connection its read started on was replaced, or closed,
is parsed with that connection's parser and dispatched as that connection's (#205). The read used to push it into
the parser that was current when it returned, the new connection's, and dispatch it as the new connection's: the old
server's PING was answered there, its PONG or a late reply could confirm the new connection's reply inbox, its
INFO replaced the new server's info, and a partial frame left the new parser expecting payload, so the new server's
own PING was taken as payload and never answered. readChunk() and the heartbeat's read now capture the parser,
the connection generation and the terminal-close count before they read, and dispatchFrames() takes that origin, so
the #182 rule for the old server's frames covers the whole chunk: its messages go to the subscriptions the reconnect
replayed, its control frames are not applied, its -ERR is reported as the old server's. A corrupt late chunk still
reports its parse failure and delivers the messages ahead of it, but starts or joins no recovery of the new
connection, and a heartbeat tick whose connection was replaced while its PING was written does not read the new
socket. The built-in transports cannot complete a read that late (their close() ends it); the
TransportInterface::readLine() docblock now says a read belongs to the connection it started on. Found by the
review of #191.[docs] New LateTransportReadTest (35 cases, #205), over a transport that holds a read's chunk across a
reconnect: through your read, an operation's and the heartbeat's (with and without its tick's generation), a late
PING and half MSG, a late chunk finishing the old parser's message, a late PONG or reply not confirming the new
inbox, a late INFO and -ERR, a late corrupt chunk, a terminal close alone, an unchanged connection (guard), a
corrupt late chunk not joining the new connection's recovery, and an obsolete heartbeat tick. 31 fail on 2.26.5.A lame-duck failover whose reconnect is refused authentication now reports the refusal once to the errorListener and the error log (#201). Before, the
Patch release.
A lame-duck failover whose reconnect is refused authentication now reports the refusal once to the errorListener and the error log (#201). Before, the reconnect reported the AuthenticationException and then the failover reported the same object again, so metrics or alerting built on the listener counted it twice. This happened on both failover paths: inline for your own read, and in the failover's own fiber for an operation's read (#191). It also happened when the failover joined another fiber's recovery.
Who should upgrade: anyone who counts or alerts on errorListener reports and connects with credentials the servers may refuse during a lame-duck failover. There are no API changes.
Closed event, its error and the stop after a refusal are unchanged. The event still carries the refusal, and the connection does not retry after it.codecov/patch 100%: every changed line is covered. Total coverage 99.04%.LameDuckAuthenticationReportingTest, 16 cases, 12 of which fail on 2.26.5.ConnectionException, and moving the report out of the reconnect instead.The full record is in the CHANGELOG.
[bugfix] A lame-duck failover whose reconnect is refused authentication reports the refusal once through the
error listener and the asynchronous error log, also when it joins another fiber's recovery (#201). performRecovery()
reports a refusal before it rethrows it, and both failover catches - inline for your own read, and in the failover's
own fiber for an operation's read (#191, 2.21.0) - reported it again, so metrics or alerting built on the listener
counted it twice. They now go through one helper that leaves an AuthenticationException alone and reports
everything else, so "Reconnect attempts exhausted", which recovery does not report itself, is still reported once.
The Closed event, its error and the fail-fast stop after a refusal are unchanged. Found by the review of #191.[docs] New LameDuckAuthenticationReportingTest (16 cases, #201): the inline and own-fiber failover refused,
with normal, throwing-listener and throwing-logger reporting; both paths joining a heartbeat recovery whose dial is
held; exhaustion still reported once; a refusal outside lame duck still reported once and thrown; two separate
refusals with identical messages each reported. 12 fail on 2.26.5.Your own processIncoming() or readIncoming() that is already waiting, on the socket or for the read slot, now wakes when another fiber's read stops a
Patch release.
Your own processIncoming() or readIncoming() that is already waiting, on the socket or for the read slot, now wakes when another fiber's read stops a subscription at a handler failure (#199). The woken read returns zero frames. Your next call continues the stopped subscription before it reads, and throws that subscription's next handler failure if there is one. Before this, the rest of that subscription waited for the server's next bytes or for your read's own cancellation. On an idle connection that meant the server's next PING, two minutes away by default.
Who should upgrade: anyone who runs two of your own reads at once, or a read loop next to operations under handlerErrorsFailOperations: true whose handlers await. There are no API changes.
codecov/patch 100%: every changed line is covered. Total coverage 99.04%.StoppedSubscriptionReadWakeupTest, 19 cases, 12 of which fail on 2.26.3. The boundary test that pinned the old behaviour is inverted.The full record is in the CHANGELOG.
[bugfix] Your own read already waiting - processIncoming() or readIncoming() on the socket, or for the read
slot - is woken when another fiber's read stops a subscription at a handler failure, and returns zero frames (#199).
Since 2.20.0 (#186) your read continues such a subscription before it reads, but only once, at its start: one
already waiting stayed waiting, so the rest of that subscription waited for the server's next bytes (on an idle
connection its next PING, two minutes away by default) or for the read's own cancellation. It takes two of your
reads at once, or an operation under handlerErrorsFailOperations: true whose read is held up in a handler that
awaits while your read loop waits. A stop now fires a one-shot, connection-level wake-up that only your reads'
slot wait and socket read take, right before they wait: a woken read returns IncomingChunkResult(0, false) (0 from
processIncoming()), its transport read cancelled with nothing consumed, and your next call continues the stopped
subscription before it reads, throwing its next handler failure if there is one. Keep reading after both an
exception and a zero-frame result. Your cancellation still wins when both fire, with its own reason; operations'
reads, recovery and failover are unchanged, and a fired wake-up is never reused, so an idle loop does not spin. This
was a documented boundary of #186 (readIncoming()'s docblock), now removed. Found by the interleavings review of
#186 (2.20.0).[docs] New StoppedSubscriptionReadWakeupTest (19 cases, #199): your read on the socket or waiting for the slot
woken by a stop from your own held-up read or a poll, by a handler failure or an escaped overflow, through both read
APIs; an unrelated operation keeping the socket; both of your waiters woken by one stop; no reuse of a fired wake-up;
your cancellation's reason winning in either firing order; the default reporting mode not waking your read. 12 fail
on 2.26.3. HandlerFailureInYourOwnReadTest::testAMarkSetWhileYourOtherReadWaitsOnTheSocketWaitsForTheServersNextBytes,
which pinned the old boundary, becomes testAMarkSetWhileYourOtherReadWaitsOnTheSocketWakesItBeforeTheServersNextBytes.What's fixed (#203). An operation that a DiscoveredServers or LameDuck listener starts and does not await now waits for the lame-duck failover and run
Patch release.
What's fixed (#203). An operation that a DiscoveredServers or LameDuck listener starts and does not await now waits for the lame-duck failover and runs on the new server. This holds whichever read brought the lame-duck INFO. Before, the outcome depended on that read:
request(), a processIncoming(), connect() or drain() failed at once with Connection is not open.processIncoming() the listener started read the leaving socket first. The client's own close of that socket was then reported as Socket closed by peer (EOF).Who should upgrade: anyone whose LameDuck or DiscoveredServers listener starts operations without awaiting them. There are no API changes.
Reconnected listener. With waitForReconnect: false it is refused at once.codecov/patch 100%: every changed line is covered. Total coverage 99.04%.ListenerOperationFailoverTest, 53 cases, 37 of which fail on 2.26.3.The full record is in the CHANGELOG.
[bugfix] An operation a DiscoveredServers or LameDuck listener started and did not await failed at once or read
the leaving socket, depending on which read brought the lame-duck INFO (#203). When your own read brought it, the
failover ran inline in the listener's fiber, which became the recovery fiber, and every operation called from that
fiber was taken for one issued inside the recovery, which the #145 guard refuses: a request(), a
processIncoming(), connect(), drain() and the rest failed with Connection is not open although nothing
inside the recovery awaited them (a queued drain() hit the same false self-join rejection). Each operation now records
when it is called whether it is issued inside the recovery, and only then is refused; one issued before waits for
the failover within its own timeout and runs on the new server. When an operation's read brought the INFO, the
failover started in a fiber of its own after the listener returned, and a processIncoming() the listener started
read the leaving socket first: the client's own close of it was reported as Socket closed by peer (EOF). A read
made while such a failover is leaving the connection now waits for the failover's completion (#202's boundary,
not the Reconnected listener) within its cancellation and wake-up, and returns 0 without reading either socket;
waitForReconnect: false refuses it at once, a mark for an older connection does not hold up the new one, and a
drain's flush still reads the connection it drains. Timeouts, cancellations, event order and exception messages are
unchanged. Not changed: the failover still starts once these listeners return, so an operation a listener awaits
runs on the leaving server; and a listener inside a recovery that awaits a future kept from before it, whose
operation waits for that recovery, still waits with it (a request() until its timeout). Found by the review of
#191 (2.21.0).[docs] New ListenerOperationFailoverTest (53 cases, #203): side operations started from both listeners on both
failover paths, directly and wrapped in async(); the ten other entry points, connect() and drain() included;
waiting disabled; a side request's and a side read's own cancellation and deadline while the failover's dial is held;
a side read returning while the Reconnected listener is held. 37 of them fail on 2.26.3.
NatsConnectionInternalsTest::testAwaitOpenConnectionWaitsAgainWhenAnotherReconnectFollows passes false for the
operation's provenance, the new second argument of awaitOpenConnection().Fixed: a pull consumer run (pullConsumer()->handle(), finite or infinite) no longer ends when its read meets an -ERR the server keeps the connection o
Patch release.
Fixed: a pull consumer run (pullConsumer()->handle(), finite or infinite) no longer ends when its read meets an -ERR the server keeps the connection open for (#209). That covers:
maximum subscriptions exceeded, for example when your application subscribes beyond the subscription limit, a Key/Value watch does, or a first request() sets up its reply inboxInvalid Publish SubjectPermissions Violation such as ... for Publish with Reply of ...Such an -ERR answers some other SUB or PUB on the connection, never the run's own. It used to end the run, an infinite one included, with ConnectionException: Server sent error frame: ..., an error that names neither the consumer nor what it answered, so the run had to be started again. The run now reports it to the errorListener and the logger (NATS connection error: Server sent error frame: ...) and goes on, keeping its partial batch.
Who should upgrade: anyone running pull consumers on a connection that can reach its subscription limit, or that publishes with reply subjects it may lack permission for. There are no API changes.
handle(), for these errors. Code that restarted a run after handle() threw that ConnectionException for such an -ERR won't see it there any more.handle() still fails, now always with the JetStreamException that names the inbox, also when the run's own read is the one that meets the -ERR.handlerErrorsFailOperations, an overflow under slowConsumerErrorsFailOperations and a fatal -ERR still end the run, including when they arrive in the same chunk as such an -ERR.-ERR.codecov/patch 100%: every changed line is covered. Total coverage 99.04%.PullConsumerServerErrorTest, 27 cases, 21 of which fail on 2.26.2, and OperationServerErrorReportingTest, 17 cases.The full record is in the CHANGELOG.
pullConsumer()->handle(), finite or infinite) no longer ends when its read meets an -ERR the
server keeps the connection open for (maximum subscriptions exceeded, Invalid Publish Subject, a Permissions Violation such as ... for Publish with Reply of ...): it reports it to the errorListener and the logger and
goes on (#209). Code that restarted a run after handle() threw ConnectionException: Server sent error frame: ...
for such an -ERR will no longer see it there; watch the error listener instead. The run's own reply inbox rejected
still fails handle(), now always with the JetStreamException naming the inbox.[bugfix] A pull consumer run ended when its read met an -ERR the server keeps the connection open for, such as
maximum subscriptions exceeded for an application's subscribe() beyond the subscription limit, a Key/Value
watch or the shared reply inbox of a first request() (#209). The run's only SUB is its guarded reply inbox,
whose rejection is tied to it in the dispatch whichever read meets it, and a denied PUB of the run draws a
recoverable -ERR, so such an -ERR was never the run's: it ended the run, an infinite one too, with an error
naming neither the consumer nor the SUB it answered, after handing over what the pulls held. The engine's read
now reports it to the errorListener and the logger (NATS connection error: Server sent error frame: ...) and
the run goes on, its partial batch kept, in finite and infinite mode alike, as a service's run() does. The
report is queued where the -ERR is classified and sent once the chunk is dispatched, so another subscription's
handler failure under handlerErrorsFailOperations or an overflow under slowConsumerErrorsFailOperations in
the same chunk still ends the run, also from the parsed prefix of a chunk that fails to parse, and a fatal -ERR
keeps its rules. When the run's own read met the limit -ERR that rejected its own inbox, handle() used to
fail with that bare ConnectionException; it now fails with the JetStreamException naming the inbox, as README
said. Requests, fetches, batched Direct Get, queue polls and your own reads keep failing on such an -ERR. An
internal reportServerErrors flag on readIncomingForOperation() carries this; alwaysReport would also have
reported handler failures and overflows regardless of the options and delivered other subscriptions' leftovers.
Found by the review of #197 (2.22.0).[docs] New PullConsumerServerErrorTest (27 cases, #209) and OperationServerErrorReportingTest (17 cases): an
unrelated nonfatal -ERR reported while the run's partial batch is kept, finite and infinite; an application's
subscribe() beyond the limit next to a running consumer; the run's own inbox rejection with the
JetStreamException; a configured handler or overflow failure, or a fatal -ERR, in the same chunk still ending
the run; the flag's opt-in, policy, ordering, observer and fatal-precedence rules.
PullConsumerConnectionEndingFrameTest::testAnErrKeepingTheConnectionOpenStillEndsTheRun, the guard of the old
behaviour, is replaced by testAnErrKeepingTheConnectionOpenIsReportedAndTheRunContinues;
ServerErrorKeepingConnectionTest::testAnOperationsReadLeavesTheRemainderToYourNextRead gains a row for a read
with the new flag, which, unlike a serving loop's, delivers no other subscription's leftovers.What's fixed (#204): a request() or requestMany() waiting for a replacement reply inbox to be confirmed now checks the inbox before each confirmation
Patch release.
What's fixed (#204): a request() or requestMany() waiting for a replacement reply inbox to be confirmed now checks the inbox before each confirmation read, not only after one.
The bug: the wait pauses for 1 ms after a read that returned without reading. If another fiber's read dropped the inbox during that pause, through the server's renewed maximum subscriptions exceeded or a permissions violation naming the inbox, the next read went out without a wake-up. On an idle connection the request then waited out its whole timeout (Request timed out for subject ... while waiting for the reply inbox to be set up) instead of failing at once with the dropped-inbox error. A lame-duck INFO taken by that read was failed over inline, past the request's timeout.
Now: the request fails at once with the dropped-inbox or the permissions error, without another read and without being sent, as README Request/Reply describes. A later request still installs a fresh inbox.
Who should upgrade: this needs a connection at its subscription limit and another fiber's read (an application read loop, or the heartbeat) meeting the rejection inside that 1 ms window, so it is rare. Upgrade if you run near the subscription limit with concurrent reads. There are no API changes.
codecov/patch 100%: every changed line is covered. Total coverage 99.04%.MuxConfirmationPauseTest, 16 cases, 8 of which fail on 2.26.1. The tests hold the real 1 ms pause timer, so the order of events decides, not timing. Five broken variants of the fix were tried. The three that change behaviour each fail cases. The guard for a rejection in the read the request waits behind was strengthened so that dropping the check after the read also fails. The fifth, checking only after the pause, is the alternative the issue itself suggested.The full record is in the CHANGELOG.
[bugfix] A request or requestMany() waiting for a replacement reply inbox to be confirmed now checks the inbox
before each confirmation read, not only after one (#204). After a read that returned without reading, the wait
pauses for 1 ms; when another fiber's read dropped the inbox in that pause (the server's renewed maximum subscriptions exceeded, or a permissions violation naming it), the next read was made with the forgotten
confirmation fence: no wake-up, so on an idle connection the request waited out its timeout (Request timed out for subject ... while waiting for the reply inbox to be set up) instead of failing with the dropped-inbox error
at once, and a lame-duck INFO that read took was failed over inline, past the request's timeout. Now the request
fails at once with the dropped-inbox or the permissions error, without another read and without being sent, as
README Request/Reply describes; a later request still installs a fresh inbox. Needs a connection at its
subscription limit and another fiber's read meeting the rejection in a 1 ms window, hence rare. Found by the
review of #191 (2.21.0).[docs] New MuxConfirmationPauseTest (16 cases, #204): request() and requestMany() whose replacement inbox is
rejected during the confirmation pause (limit, limit then a queued lame-duck INFO, permissions) fail before
another socket read and are not sent; a replacement inbox installed by another request during the pause, left
unconfirmed or confirmed, does not adopt the original request; guards for a rejection in the read the request
waits behind (failing without another pause), a confirmation during the pause and a terminal close. The tests hold
the real 1 ms pause timer instead of relying on timing.Patch release. When the read of one of the library's operations gets a chunk that fails to parse, it now recovers the connection the way a read that m
Patch release. When the read of one of the library's operations gets a chunk that fails to parse, it now recovers the connection the way a read that met a lost socket does (#195): the recovery runs in a fiber of its own, and the operation waits for it only within its own wait. Before this fix the operation waited for the whole reconnect, in three ways:
request() with a 300 ms timeout came back only after the outage.waitForReconnect: false.A chunk fails to parse on an unknown control line, a malformed MSG/HMSG line, a frame over the bound derived from the server's max_payload, or a payload not ended by CRLF. These come from a server or proxy bug, so the case is rare. There are no API changes.
What changes:
Connection is not open, the ProtocolException as its previousProtocolException reported before the recovery starts.INFO among those frames now fails over in a fiber of its own, as from a chunk that parses, and the recovery joins it.processIncoming()/readIncoming(), a serving loop's read and the heartbeat still recover inline and wait for all of it.codecov/patch 100%: every changed line is covered. Total coverage 99.04%.CorruptChunkOperationReadTest, 9 cases, 7 of which fail on 2.26.0. Each holds the recovery's dial until the operation has returned, so the order of events decides. Three broken variants of the fix each fail at least one case.testAPullConsumerRunEndedByATerminalStatusHandsOverWhatALaterPullReceivedAfterIt (#211). That test also fails intermittently on unchanged 2.26.0 and is not touched by this release. The push run of the same commit passed it.The full record is in the CHANGELOG.
[bugfix] An operation whose read got a chunk that fails to parse ran the reconnect inline and waited for all of it
(#195): past its own deadline, past its wake-up (a reply delivered from the frames ahead of the bad bytes came back
only once the reconnect was over), and also with waitForReconnect: false. Since #178 (2.14.0) and #191 (2.21.0)
such an operation - a request(), requestMany(), a SubscriptionQueue poll, a fetch, a pull consumer, Key/Value
keys() and history(), a flush waiting for its PONG - recovers a lost socket and a lame-duck failover in a fiber
of its own and waits only within its own wait, but the parse-error path still called the recovery inline, so a
request() with a 300 ms timeout came back only after the outage. A chunk fails to parse on an unknown control
line, a malformed MSG/HMSG line, a frame over the bound derived from the server's max_payload, or a payload
not ended by CRLF: a server or proxy bug, hence rare. The read still delivers the frames ahead of the bad bytes and
reports the ProtocolException first, then recovers through the same helper as a failed read: the operation times
out at its deadline with the recovery carrying on, returns at once what those frames brought it, or with waiting
disabled fails at once with Connection is not open, the ProtocolException its previous. A lame-duck INFO
among those frames now fails over in a fiber of its own too, as from a chunk that parses, and the recovery joins
it, which removes the exception README item 9 documented. Your own processIncoming()/readIncoming(), a serving
loop's read and the heartbeat still recover inline and wait for all of it. Found by the review of #191 (2.21.0).[docs] New CorruptChunkOperationReadTest (9 cases, #195): a request whose reply is a corrupt chunk times out at
its deadline, or fails at once with waiting disabled; a reply, or a poll's message, ahead of the bad bytes returned
at once; a poll with nothing for it returning at its deadline; a lame-duck INFO ahead of the bad bytes failing over
in a fiber of its own; your own read still waiting for the whole recovery. Each holds the recovery's dial until the
operation has returned.Minor release. One of the library's operations whose read starts a reconnect, or brings the lame-duck INFO that starts a failover, is now let go as so
Minor release. One of the library's operations whose read starts a reconnect, or brings the lame-duck INFO that starts a failover, is now let go as soon as the reconnect is over (#202). It no longer waits for the Reconnected listener, or for the delivery of what the reconnect read. A slow listener, or a slow handler of a lower sid in that delivery, used to make such an operation time out although its result was already there:
SubscriptionQueue poll's message was queuedrequest()'s reply was on the new socket, and was lostack_waitUpgrading is recommended if your Reconnected listener does real work, such as re-registering state or warming caches, or if a subscription handler can await for a while. There are no API changes. What changes:
processIncoming() and readIncoming(), a serving loop's read, the heartbeat, and an operation whose write started the reconnect still wait for all of it. A deadline or a wake-up still ends only the operation's wait, and failed recoveries keep their errors.codecov/patch 100%: every changed line is covered. Total coverage 99.03%.OperationRecoveryCompletionTest, 13 cases: 8 fail on 2.25.10, and 5 are guards (joiners, an application read that still waits). Six broken variants of the fix each fail targeted cases, including the issue's mutation check: without the fallback for a skipped stale recovery, the request is parked until its deadline.The full record is in the CHANGELOG.
INFO that started a
failover, is now let go when the reconnect is over, as an operation that joined it is, instead of when the
Reconnected listener and the delivery of what the reconnect read have finished (#202). That listener and that
delivery go on in the reconnect's fiber, so the operation can return while they still run; a listener must not
count on such an operation having waited for it. Your own processIncoming() and readIncoming(), a serving
loop's read, the heartbeat and an operation whose write started the reconnect still wait for all of it.[feature] An operation whose read starts the recovery no longer loses its result to a slow Reconnected listener
or a slow handler in the delivery after the reconnect (#202). When the read of a request(), requestMany(), a
SubscriptionQueue poll, a fetch, a pull consumer or a flush() meets a lost connection (#178), or brings a
lame-duck INFO (#191), it starts the recovery in a fiber of its own and waits for it within its own timeout. It
used to wait for that fiber to end: past the reconnect itself, through the announcement of the new connection,
which runs the Reconnected listener, and the delivery of what the reconnect read, which runs the handlers in sid
order. A listener, or a handler of a lower sid, that took longer than what was left of the operation's timeout
made it time out although its message was queued or its reply was on the new socket; a request()'s reply was
then lost, and a fetch's messages came back only after ack_wait. Operations that joined the reconnect were
already let go when it was over. The read now waits for a completion of its own, settled at the same point as the
joiners' (after the handshake, the subscription replay, the reply inbox's confirmation and the flush of buffered
publishes), or when its recovery returns having done nothing (a close, a recovery already done by another fiber),
or with the recovery's error. It then looks again: a poll takes what the reconnect read for its subscription, and
a request reads its reply on the new socket. Failed recoveries keep their errors, a deadline or a wake-up still ends
only the wait, and the recovery carries on. A request's reply already queued on the shared request inbox behind a
slow handler of a lower sid still waits for that handler. Found by the review of #191 (2.21.0).[docs] New OperationRecoveryCompletionTest (13 cases, #202): a poll or a request whose read started the recovery
or the failover returns while the tail is held, joiners as guards, an application read that still waits, a listener
that recovers again after the initiating poll returned, and a skipped recovery of a replaced connection.
OperationReadReconnectLifecycleTest::testAPollThatWaitsForAllOfTheReconnectReturnsAfterTheReconnectedListener is
replaced by testAPollReturnsWhileTheReconnectedListenerStillWaits, and
testAPollFromAReconnectedListenerWhoseOwnReadFindsTheNewConnectionGoneReconnectsItAgain starts the first reconnect
with an application read, since an outer poll of the same queue could now take the one message itself.Patch release. A pinned_client pull consumer's iterator now keeps the group's pin when a run ends before its first pull retires (#208). The next handl
Patch release. A pinned_client pull consumer's iterator now keeps the group's pin when a run ends before its first pull retires (#208). The next handle() on the same iterator resends the pin, instead of waiting out the server's priority_timeout.
Upgrading is recommended for applications that call handle() again on the same iterator of a pinned_client priority group: restarting after a failure, after stop(), or after the client's drain(). There are no API changes. An application that builds a new iterator for each run starts without a pin, as before.
pinned_client group's pin only from a batch the run retired or handed to the handler.
-ERRwaitForReconnect: falsehandlerErrorsFailOperationsstop(), disconnect() or the client's drain()handle() pulled without it, and the server held that pull, and every other client of the group, until the pin's priority_timeout had passed (two minutes by default).stop() followed by handle() while the old pull's write is still completing.priority_timeout 8 s. The new live test gets it at once, under the original pin.codecov/patch 100%: every changed line is covered. Total coverage 99.03%.PullConsumerPinRetentionTest, 20 cases: the issue's 19, of which 11 fail on 2.25.9, plus a case for a run that inherited the pin and loses it to another run. Nine broken variants of the fix each fail at least one case.pinned_client consumer, with two cases: stop, and another handler failing the run. Both are served at once under the original pin; on 2.25.9 both are still waiting at the test's 10 s bound.The full record is in the CHANGELOG.
pinned_client pull consumer's iterator now remembers the group's pin as soon as a message carrying it arrives
(#208), so a later handle() on the same iterator resends it however the earlier run ended. A 423 clears only the
pin its own pull sent. A grouped run still pulls one request at a time until the first batch under its pin has
been delivered, also after receiving the pin.pinned_client pull consumer run that ended while its first pull (or the first after a 423) still held
messages left the iterator without the pin, so handle() again on the same iterator pulled without it, and the
server held that pull, and every other client of the group, until the pin's priority_timeout (two minutes by
default) had passed (#208). The pin was taken only from a batch the run retired or handed over to the handler, never
when the run ended first: a failure (a fatal -ERR, the connection lost with waitForReconnect: false, another
subscription's handler under handlerErrorsFailOperations, a rejected inbox), stop(), disconnect() or the
client's drain(). The pull-inbox router now remembers a grouped run's pin as each data message arrives, before it
routes the message, so every way a run ends keeps it, also a stop() followed by handle() while the old pull's
write is still completing. Delivery no longer takes a pin from what a pull buffered, so an old message cannot
restore a pin a 423 rejected after it arrived. A run still pulls serially until the first batch under its pin
retires (a pin received on the first message no longer lets it fan out early), and pipelines at once with a pin
inherited from an earlier run. Each pull records the pin it sent, and a 423 clears the live pin only when it is
that one, restarting serial acquisition: a 423 delayed past a newer pin, received by the same run or another run of
the iterator, leaves the newer pin alone. Against nats-server 2.12 the report measured the restart's message 7.5 s
late with priority_timeout 8 s; the new live test (priority_timeout 30 s) gets it at once, where the unchanged
code was still waiting at the test's 10 s bound. Found by the review of #197 (2.22.0).PullConsumerPinRetentionTest (20 cases, #208): the restart's first pull keeps the pin of an unretired
first pull across seven endings, with the old pull's write still completing, after a 423, against a delayed 423 of
an older run and when another run loses an inherited pin; serial re-acquisition after a 423; an old buffer not
restoring a rejected pin; frames that must not change the pin; a pinless group fanning out; an ungrouped run taking
no pin. New live JetStreamIntegrationTest::testJetStreamPinnedGroupKeepsItsPinWhenARunEndsBeforeItsFirstPullRetires
(stop, and another handler failing the run) against a pinned_client consumer.Patch release. A pull consumer's stop() or drain() now ends the run at once while it is still setting up its pull inbox during a reconnect, returning
Patch release. A pull consumer's stop() or drain() now ends the run at once while it is still setting up its pull inbox during a reconnect, returning 0. Before, the run waited for the reconnect or failed with a subscribe timeout (#198).
Upgrading is recommended for workers that may start handle() while the connection is reconnecting and get shut down meanwhile, for example a SIGTERM during a rolling restart of the NATS cluster. There are no API changes. symfony-nats-messenger, which runs with reconnect off, is not affected.
stop() and drain() end the inbox set-up at once (#198). #181 (2.17.0) made the iterator's stop() and drain() from another fiber end the engine's pump read and idle backoff at once. It missed the run's first wait: the subscribe of its pull inbox, which can wait for a reconnect, for the SUB write, and for the recovery of a failed write. A run told to stop during an outage kept waiting:
requestTimeoutMs (10 s by default), handle() failed with the subscribe's TimeoutException, although the run had been told to stop. A supervisor that treats a failed run as an error saw one.The set-up now waits with the run's stop and drain wake-ups next to its budget:
SUB not yet written is never written, one waiting for the recovery is not replayed, and one already written or replayed is followed by its UNSUB on that session. The shared reconnect carries on for other operations.This is the iterator's drain(); draining the client is unchanged.
requestTimeoutMs budget for all of it: the reconnect wait, the SUB write and the recovery of a failed write. It used to have up to two fresh requestTimeoutMs waits and an unbounded SUB write.handle() still fails with a TimeoutException. The message now reads Subscribe to "_INBOX.JS.PULL.<nuid>.*" timed out within the operation budget; it used to read ... timed out waiting for the connection to be re-established. Public subscribe() is unchanged.codecov/patch 100%: every changed line is covered. Total coverage 99.03%.PullConsumerSubscribeWakeUpTest, 28 cases: the issue's 26, of which 20 fail on 2.25.8, plus two more. They cover a latched signal that starts no subscribe, and a stop or drain that lands after the connection failed, which must not turn the failure into 0. Eight broken variants of the fix each fail at least two cases.PullConsumerWakeUpTest now expects one SUB and no UNSUB.The full record is in the CHANGELOG.
_INBOX.JS.PULL.<nuid>.*, before its first pull) now has one
requestTimeoutMs for the whole set-up: the wait for a reconnect in flight, the SUB write and the recovery of a
failed write together (#198). It used to have up to two fresh requestTimeoutMs waits for a reconnect, and a SUB
write without a bound. When that budget runs out without a stop() or drain(), handle() still fails with a
TimeoutException, now worded Subscribe to "_INBOX.JS.PULL.<nuid>.*" timed out within the operation budget (it
was ... timed out waiting for the connection to be re-established), or with the detailed JetStreamException of
an inbox rejection the server sent meanwhile. Public subscribe() is unchanged.stop() or drain() came before its engine started no longer subscribes an inbox only to release it at
once: it returns 0 without a SUB.stop() or drain() during its inbox set-up was seen only once the set-up ended (#198).
The case: a worker whose handle() starts while the connection reconnects (a run restarted during an outage, or
handle() with setIterations() in a loop) and is told to shut down meanwhile, a SIGTERM during a rolling restart of
the NATS cluster, say. #181 (2.17.0) made the iterator's stop() and drain() from another fiber end the engine's
pump read and idle backoff at once, but not the run's first wait, the subscribe of its pull inbox, which can wait for
a reconnect, the SUB write, and the recovery of a failed write. The run went on waiting: when the reconnect came
back, it subscribed the inbox on the new connection only to release it at once, and when it did not within
requestTimeoutMs (10 s by default), handle() failed with the subscribe's TimeoutException although the run had
been told to stop; a SUB write that met a dead socket after the reconnect could add a second requestTimeoutMs.
The set-up now waits with the run's stop and drain wake-ups next to its budget: either signal ends it at once, and
the run returns 0 with no pull issued, so nothing is delivered or lost. A cancelled subscribe releases what it
registered: a SUB not written yet is never written, one waiting for the recovery is not replayed on the new
connection, and one already written or replayed is followed by its UNSUB, on that session. The shared reconnect
goes on for the other operations. A signal latched before the engine starts skips the subscribe. Without a signal
the set-up still waits for the reconnect within its budget and then pulls. A rejection of the inbox the server sent
while the set-up waited (permissions, or the connection's subscription limit) still fails the run with its detailed
JetStreamException when the budget runs out, the timeout as its cause, rather than a bare timeout; with a signal
the run returns 0. A connection failure stays a failure even when a signal lands after it. This is the iterator's
drain(); draining the client is unchanged. Found by the implementation brief of #188 (2.19.0).PullConsumerSubscribeWakeUpTest (28 cases, #198): a signal while the set-up joins a recovery or recovers
a failed SUB, latched before the engine starts, outside a run, during a held Reconnected listener and during a
SUB write held before or after acceptance; recovery and a genuine timeout without a signal; a restart during the
set-up; a recorded rejection with a timeout, stop or drain; and a signal after the connection failed.
PullConsumerWakeUpTest::testAStopThenHandleAgainBeforeTheFirstRunStartedEndsItBeforeItPulls now expects one SUB
(the second run's) and no UNSUB.Patch release, test suite only: no library code changed. Two unit tests that flaked on slow runners now decide by the order of events instead of wall-
Patch release, test suite only: no library code changed. Two unit tests that flaked on slow runners now decide by the order of events instead of wall-clock bounds (#185).
Nothing changes for applications. CI reruns caused by these two tests go away, and both still catch the regressions they guard against.
OperationReadReconnectLifecycleTest::testAClosedListenerThatSuspendsWhileTheReconnectGivesUp (#185).
OperationReadWakeupTest::testOperationGetsWhatADispatchWaitingOnAPongWriteBrings (#185).
The full record is in the CHANGELOG.
[docs] Two wall-clock tests no longer flake on slow runners (#185). Both now decide by the order of events.
OperationReadReconnectLifecycleTest::testAClosedListenerThatSuspendsWhileTheReconnectGivesUp suspended its
Closed listener 0.3 s or 0.8 s against poll deadlines of 3 s and 0.3 s. It checked Closed the moment the timed-out
poll returned, but on a slow runner the three refused reconnect attempts were not over by then (Connecting). The
listener is now held on a gate the test opens. In the exhaustion case, with a 30 s deadline, the poll must still
wait once the listener has been entered and the queued work has run; let go, the poll gets the exhaustion error.
In the timeout case the listener stays held until the 0.3 s poll has returned nothing, and Connecting is allowed
at that point. Both still end Closed with the same events and dials.OperationReadWakeupTest::testOperationGetsWhatADispatchWaitingOnAPongWriteBrings required its result within
1.5 s. A runner under coverage took 2.58 s, with the hold-up ended as designed. The result now has to win a race
against a referenced timer of the operation's 3 s deadline, armed before the operation starts, which the broken
reads could not win.Both still fail on the regressions they guard against. No production code changed.
Patch release, test suite only: no library code changed. The no-spin tests can see a timer loop inside the connection's read again (#184).
Patch release, test suite only: no library code changed. The no-spin tests can see a timer loop inside the connection's read again (#184).
Nothing changes for applications. This guards the next change to the read path against the most expensive kind of regression: a wait that polls on a timer instead of parking.
ReadWakeupLifecycleTest::testTwoPollsOfOneQueueWithOneMessage and OperationReadReconnectLifecycleTest::testAnOperationParkedOnTheReconnectItStartedDoesNotSpin counted what returns to the operation and what reaches the socket. A wait that polls on a timer inside the connection does neither: polling the read slot while the application's read holds it, or polling the recovery while a reconnect backs off. Such a wait registers hundreds of timers and passed both counts. The process-wide registration count that used to catch it was dropped in 2.18.0, because leaked clients of earlier tests landed their handshake bursts in the wait.tests/Support/LoopRegistrationCounter.php, a transparent driver around the event loop's own driver that counts every registration, and bounds the registrations over its wait to fewer than 50.LoopRegistrationCounterTest (10 cases) covers the driver's forwarding and counting, the windows, and process isolation.LoopRegistrationCounterTest: 10 new cases.The full record is in the CHANGELOG.
[docs] The no-spin tests see a timer loop inside the connection's read again (#184).
ReadWakeupLifecycleTest::testTwoPollsOfOneQueueWithOneMessage and
OperationReadReconnectLifecycleTest::testAnOperationParkedOnTheReconnectItStartedDoesNotSpin counted what returns to
the operation (its looks at its result) and what reaches the socket (its reads). A wait that polls on a timer inside
the connection does neither: polling the read slot while the application's read holds it, or polling the recovery
while a reconnect backs off. It registers hundreds of timers and was invisible to both counts. The process-wide count
of event-loop registrations that used to catch it was dropped in 2.18.0, because clients earlier tests left
reconnecting landed their handshake bursts in the wait.
Both tests now run each data case in a process of its own (#[RunInSeparateProcess],
#[PreserveGlobalState(false)]). Each installs tests/Support/LoopRegistrationCounter.php first: a transparent
driver around the loop's, tests/Support/RegistrationCountingDriver.php, which counts every registration. Each test
bounds the registrations over its wait to fewer than 50, next to the existing counts: six and four on the current
code. A 1 ms loop in place of either wait registers some 900 to 1,800, and tens of thousands with no delay, also when
it runs in a detached fiber. All six such loops pass the old assertions and fail the new bound.
LoopRegistrationCounterTest (10 cases) covers the driver's forwarding and counting, the windows, and the isolation:
a fresh process and loop per case, and install() refusing a loop that has callbacks or has run. No production code
changed.
Patch release, test suite only: no library code changed. It fixes a timing flaw in one unit test that failed the post-release mutation jobs of 2.25.5.
Patch release, test suite only: no library code changed. It fixes a timing flaw in one unit test that failed the post-release mutation jobs of 2.25.5.
Nothing changes for applications. The published tag now carries a fully green CI, mutation testing included.
RetirePullInboxTest::testADrainThatNeverAsksForTheHandOverEndsItReleasedAtTheRequestTimeout no longer fails when the drain is slow to ask its participant (#227).
main and on the v2.25.5 tag before any mutant ran.1791715977, the order of the failed 2.25.5 run. Also 157 live integration tests and 49 Behat scenarios; all runnable examples pass.main with the fix (a82e5e8): covered MSI 92.77% (90% floor enforced in CI), the initial test run green.The full record is in the CHANGELOG.
[docs] RetirePullInboxTest::testADrainThatNeverAsksForTheHandOverEndsItReleasedAtTheRequestTimeout no longer
fails when the drain is slow to ask its participant. The release ends at the request timeout, at whichever comes
first of two deadlines: its own budget, or the seal of the drain's delivery, which ends the requests in flight at the
drain's budget. The drain's deadline starts first, but the test measured its 0.15 s lower bound from the release's
call. In the coverage run Infection starts with, the drain took about 55 ms to ask, and the release ended 0.145 s
after the call. That failed the post-merge mutation jobs of 2.25.5 before any mutant ran. The bound is now measured
from the drain's start. The test still fails when the release does not wait for the drain (0.002 s).Patch release, test suite only: no library code changed. The scripted reconnect server used by the unit tests now keeps the order of writes, as a sock
Patch release, test suite only: no library code changed. The scripted reconnect server used by the unit tests now keeps the order of writes, as a socket does (#192).
Nothing changes for applications. Contributors get unit coverage of backpressure and PING fences that matches what a real socket can do, and a clear way to hold an operation inside a write without holding the writes after it (see AGENTS.md).
Writes reach the scripted server in the order they were made (#192).
tests/Support/ReconnectingTransport.php let a write made during a stall reach the server before the stalled one. The connection matches PONGs to PINGs by order, so a heartbeat PING overtaking a held-up SUB + PING had its PONG taken for the held-up one's. That confirmed a guarded inbox whose SUB the server had never received, an interleaving no socket produces.A writer can be held after its bytes are accepted, without holding any other write: holdCompletionOfNextWriteContaining() on the scripted server, and tests/Support/CompletionHoldingTransport.php around any other transport. This is a delay after acceptance, as opposed to backpressure.
Three tests that relied on a write overtaking a stalled one are restaged, with their assertions kept:
Each still fails when the bug it guards against is put back.
New ReconnectingTransportWriteOrderTest (15 cases) covers the write order, sessions ending and being replaced, and the heartbeat with PINGs answered never confirming an inbox whose SUB is still held.
192192. Also 157 live integration tests and 49 Behat scenarios; all runnable examples pass.ReconnectingTransportWriteOrderTest: 15 new cases. With the write order taken out of the test double, 11 of them fail; the other 4 are guards.The full record is in the CHANGELOG.
[docs] The scripted reconnect server keeps the order of writes (#192). tests/Support/ReconnectingTransport.php
ran each write on its own and held up only the one matching a stall, so a write made during a stall reached the
session before the stalled one, which no socket does: bytes reach a server in the order they were written, and the
built-in transports hand them over in the caller's fiber. Since the connection ties PONGs to PINGs by order (2.19.0),
a heartbeat PING overtaking a held-up SUB + PING had its PONG taken for the held-up one's and confirmed a guarded
inbox whose SUB the server had not received. Each write now waits until the one before it on its session has been
accepted, and only then meets its stall or failure: a stalled write holds the later ones, and they fail when their
session ends - also one made just before the end with nothing ahead of it, which used to be recorded on the dead
session - without waiting for a head that outlives its session; a dial that succeeds ends the session it replaces, so
a new session's writes never wait for an old one's. afterWrite runs once the next write has been let through, and
the new holdCompletionOfNextWriteContaining() holds a writer whose bytes the session already has, without holding
any other write: a delay after acceptance, distinct from backpressure. The three tests that relied on a write
overtaking a stalled one are restaged on that distinction, with their assertions kept: the heartbeat-shape inbox
rejection test of #175 now runs with PINGs answered over SubscriptionLimitServer, which rejects the SUB in wire
order, holding the fetch's writer through the new tests/Support/CompletionHoldingTransport.php; the mux wait test
of #180 (four data sets) and the drain hand-over order test of #207 hold a writer's completion instead of its bytes.
New ReconnectingTransportWriteOrderTest (15 cases) covers the order, sessions ending and being replaced, and the
connection-level consequence with the heartbeat answered. No production code changed.Patch release, test suite only: no library code changed. The unit tests no longer leave clients running into the tests after them (#183).
Patch release, test suite only: no library code changed. The unit tests no longer leave clients running into the tests after them (#183).
Nothing changes for applications. Contributors get a quieter, more deterministic unit suite and a convention for new tests: register what a test starts with $this->own(...) and release it in tearDown() (see AGENTS.md).
Tests own and close what they start (#183). Some unit tests ended with their client still Open or reconnecting, or with an operation still waiting. That client's heartbeat, its reconnect attempts and its operations' 1 ms loops then kept running through the rest of the suite:
That took CPU from unrelated tests and flaked a test that counted process-wide event-loop registrations.
A test-resource scope now owns what a test starts: tests/Support/TestResourceScope.php, through the OwnsTestResources trait.
Its shutdown runs under one deadline. It stops new work, closes everything at once, and releases fixture gates only once each close intent has run. It joins every close and operation. It fails the test, naming the resource, when anything is still running.
All 97 unit classes that construct a client or connection use it.
Whole-loop cancellation is gone. The seven classes that cancelled every event-loop callback around each test, which hid the clients they left Open, now close their clients. They cancel only the heartbeat watchdogs their own tests armed.
1791624469 and 20261011. Also 157 live integration tests and 49 Behat scenarios; all runnable examples pass.TestResourceScopeTest: 15 new cases covering the scope itself.ServiceTest alone used to leave 61 referenced heartbeat timers on the event loop at the end of its run; it now leaves none.The full record is in the CHANGELOG.
[docs] Unit tests no longer leave clients running into the tests after them (#183). A test that ended with its
client Open, reconnecting, or with an operation still waiting kept that client's heartbeat, its reconnect attempts
(ten over about 43 s with the defaults, each a burst of up to 500 handshake polls on a double that answers at once)
and its operations' 1 ms loops running through the rest of the suite: CPU taken from unrelated tests, and bursts that
flaked a test counting process-wide event-loop registrations (d551d6b). The issue's review counted, in ServiceTest
alone, 66 connections still Open when their test finished, 61 with a referenced heartbeat timer. A new test-resource
scope (tests/Support/TestResourceScope.php, through the OwnsTestResources trait) owns what a test starts: every
client and connection, registered as it is constructed (weakly, so the lifetime tests still see what they drop
collected, and through the connection inside a client, which outlives the client a test drops when its method
returns), the background operations with what ends each, the fixture gates (a held dial, a stalled write, a held
handler) and the test's loop callbacks. Its shutdown, from tearDown(), runs under one deadline on a referenced
timer: it stops what starts new work, starts every disconnect at once, releases the gates only once each close
intent has run, joins each close and each owned operation, and fails the test, naming the resource, when a
connection is not Closed, an operation is still pending, a fixture is not idle or a cleanup step threw; a test that
already failed keeps its own failure and gets the cleanup report on stderr. All 97 unit classes that construct a
client or connection now register them (ReconnectScenarios delegates its $opened cleanup to the scope, which
joins the closes instead of swallowing whatever a one-second wait threw and sleeping 50 ms). The seven classes that
cancelled every event-loop callback before or after each test (JetStreamContextTest, KeyValueBucketTest,
ObjectStoreBucketTest and four mutation classes), which hid the clients they left Open, now close their clients and
cancel only the heartbeat watchdogs their own tests armed, by the ids recorded since setUp(); their timer-counting
assertions count only the test's own timers. Tests that inject a failing transport close, or a listener that
reconnects on Closed, reset it for the shutdown. TestResourceScopeTest covers the scope itself. No production code
changed.Patch release. An infinite pull consumer run that ends on a terminal status, such as 409 Consumer Deleted after a consumer is deleted and recreated un
Patch release. An infinite pull consumer run that ends on a terminal status, such as 409 Consumer Deleted after a consumer is deleted and recreated under the same name, now hands your handler what its later pulls received after that status, instead of dropping it (#211).
Upgrading is recommended for infinite pull consumers on ack_policy: none or max_deliver: 1 whose consumers can be deleted and recreated while they run. There are no API changes; the new pieces are internal.
A terminal status no longer drops what came after it (#211). The case: a consumer is deleted and recreated while the handler works on a batch.
409 Consumer Deleted sits unread on the socket.Since 2.24.3 the run hands over what the pulls behind the status hold (#187). That covered the refill's messages only when they came in the same read as the 409. When they came a read later, which is the likelier timing, they were read after the run's UNSUB and dropped.
Before it reports the status to onError, the run now closes its inbox with the release a failing run uses since 2.25.2 (NatsClient::retirePullInbox(), #212):
UNSUB and PING go out in one write.UNSUB is read into the pulls or the overflow until the PONG, within one requestTimeoutMs budget. This happens even with nothing behind the status.onError then gets the status once, and the tail is handed over and counted.The inbox's rejection observer is kept until the run's final unsubscribe. So a permissions violation read by onError or during the hand-over still ends the run with the rejection (#206).
Measured on nats-server 2.12, with the worker reading one protocol frame at a time:
handle() returns 2.onError for a terminal status, and handle()'s result, come up to one round trip later, at most requestTimeoutMs.TimeoutException warning ("Releasing the pull consumer inbox ...") when the server does not answer the release's PING in time.stop() during that round trip returns the count without calling onError. A rejection of the inbox recorded meanwhile ends the run with the rejection, and the client's drain() asking for the hand-over ends it with the hand-over; onError is not called in either case.codecov/patch 100%: every changed line is covered. Total coverage 99.03%.continue 2 → continue 1 / break at the drain/rejection checkpoint) are equivalent: either way the run reaches the loop top without issuing a pull.PullConsumerTerminalStatusInboxReleaseTest: 13 cases. 12 fail on 2.25.2, plus one declared guard.RetirePullInboxTest case for the retained rejection observer.ack_policy none and with explicit acks at max_deliver 1. It passes 5/5 and fails 3/3 on 2.25.2.The full record is in the CHANGELOG.
409 Consumer Deleted) now closes its inbox
before it calls onError (#211): onError and handle()'s result come up to one round trip later (at most
requestTimeoutMs), the handler gets what the server sent the pulls behind the status before the inbox's UNSUB,
and that counts in handle()'s result. An error listener may get a TimeoutException ("Releasing the pull consumer
inbox ...") as a warning when the server does not answer the release's PING in time. A rejection of the inbox, a
stop() or the client's drain() that comes during that round trip ends the run as it does elsewhere, onError not
called.409 Consumer Deleted waits unread on the socket; when the handler returns the run refills, and the refill reaches the recreated
consumer, which serves it at once. The engine then reads the 409 and ends the run. Since 2.24.3 it hands over what the
pulls behind the status hold (#187), which covered the refill's messages when they came in the same read as the 409;
when they came a read later, the likelier timing, they were read after the run's UNSUB and dropped: gone on a
consumer with ack_policy: none or max_deliver: 1, delivered again after ack_wait otherwise. Before it reports
the status to onError, the run now closes its inbox to new deliveries through the release a failing run uses since
2.25.2 (NatsClient::retirePullInbox(), #212): UNSUB and a PING in one write, what the server sent before the
UNSUB read into the pulls (or the overflow) until the PONG, within one requestTimeoutMs budget, whatever the
pulls' expiry and also with nothing behind the status, the routing then sealed. The run's rejection observer outlives
the routing until the run's final unsubscribe(), so that a permissions violation naming the inbox, read by
onError or during the hand-over, still ends the run with the rejection, as it does since 2.25.1 (#206). After the
release the run's lifecycle rules apply in their order: a stop() or a close that discards returns the count
delivered so far, without onError and without the tail; the client's drain() asking for the hand-over, or a
rejection of the inbox, ends the run as they do elsewhere, onError not called; otherwise onError gets the status
once, and the pulls behind it and the overflow are handed over and counted. The run never pulls again on that path,
also when the connection ended during the release. A finite run, 423 pin recovery and the routine statuses (404, 408,
503, non-terminal 409) are unchanged. Measured against nats-server 2.12 with the worker reading one frame at a time:
the handler used to get m-1 only, and now gets m-1 and m-2. Found by the review of #197 (2.22.0).Patch release. A pull consumer run that fails now closes its reply inbox before it hands what its pulls hold to your handler. The server stops serving
Patch release. A pull consumer run that fails now closes its reply inbox before it hands what its pulls hold to your handler. The server stops serving the run's pulls, so a message published during that hand-over stays in the stream for the next pull instead of being dropped (#212).
Upgrading is recommended for pull consumers on ack_policy: none or max_deliver: 1 whose runs can fail: a read or write failure, handlerErrorsFailOperations, or a rejected inbox. There are no API changes; the new pieces are internal.
A failing run releases its inbox before the hand-over (#212). Since 2.22.0 a run that fails hands its buffered messages to the handler first (#197). It released its inbox only in its finally, after that hand-over. The server knew nothing of the failure, so for as long as the hand-over lasted it kept serving the run's pulls with whatever was published meanwhile. The run dropped those messages unacked: read after its UNSUB, or as stragglers once no pull was open. A reconnect completed during the hand-over even subscribed the inbox again. On ack_policy: none or max_deliver: 1 such a message was lost; otherwise it came again after ack_wait.
The run now closes its inbox first, through a new connection-owned operation, NatsClient::retirePullInbox() (@internal):
UNSUB and a PING go out in one write. What the server sent before the UNSUB is read into the pulls until the PONG, within one requestTimeoutMs budget.drain() under way: the drain's own UNSUB and flush stand in for that write.The release then seals the inbox so nothing more reaches the run. It never throws: a timeout or failure is reported to the error listener as a warning, never in place of the run's own failure, and a stop() ends it at once.
Measured on nats-server 2.12 with ack_policy: none. A message published while the handler held the first of two buffered messages:
delivered 3, and the message was never handled.fetchNext() gets it.handle() of a failing run throws its failure up to one round trip later, at most requestTimeoutMs.TimeoutException warning ("Releasing the pull consumer inbox ...") when the server does not answer the release's PING in time.codecov/patch 100%: every changed line is covered. Total coverage 99.02%, unchanged.PullConsumerFailedRunInboxReleaseTest: 13 cases, all of which fail on 2.25.1.RetirePullInboxTest: 17 cases, covering each state and each early end of the release.ack_policy none and with explicit acks at max_deliver 1. On 2.25.1 it shows delivered 3 and the lost message.The full record is in the CHANGELOG.
handle() throws its failure up to one round trip later (at most requestTimeoutMs), and the
handler no longer gets messages the server delivers during that hand-over: they stay in the stream for the next pull.
An error listener may now get a TimeoutException ("Releasing the pull consumer inbox ...") as a warning when the
server does not answer the release's PING in time.ack_policy: none or max_deliver: 1 that message was lost, otherwise it came again after ack_wait. Measured on
nats-server 2.12 with ack_policy: none: a message published while the handler held the first of two buffered
messages left the consumer at delivered 3 and was never handled. The run now closes its inbox to new deliveries
before the hand-over, through a new connection-owned operation, NatsClient::retirePullInbox() (@internal): on an
open connection it writes UNSUB and a PING in one write and reads what the server sent before the UNSUB into the
pulls (and an infinite run's overflow) until that PING's PONG, waiting for the PONG itself rather than for the read,
within one requestTimeoutMs budget on a referenced timer; while the client's drain() is under way the drain's own
UNSUB and flush stand in for it, the run waiting for the drain to ask for its hand-over; while a reconnect is under
way, or on a closed connection, the inbox only leaves the replay. It then routes what the inbox's queue holds into the
pulls, unless a stop() or a close that discards came, and removes the inbox's local state, so nothing more reaches
the run; a guarded inbox already treated as rejected gets its owed UNSUB within the same budget. The server stops
serving the run's pulls, and what is published during the hand-over stays in the stream for the next pull. The
release costs the failing run one round trip; one that runs out of its budget (an unanswered PING, a stalled
write) or whose read fails is reported to the error listener as a warning, never in place of the run's own failure,
and a stop() ends it at once. The normal retire path, the infinite run that goes on past a frame that ended the
connection (#210), and finite batch and iteration limits are unchanged. The fence is best effort: a UNSUB whose
write timed out can still leave interest on the server until it lands. Found by the review of #197 (2.22.0).Patch release. A pull consumer whose reply inbox the server rejects while its handler runs no longer pulls again on the dead inbox; it fails with the
Patch release. A pull consumer whose reply inbox the server rejects while its handler runs no longer pulls again on the dead inbox; it fails with the rejection at once (#206).
Upgrading is recommended for pull consumers whose subscribe permissions can change at runtime (configuration reloads), and for accounts close to their subscription limit. It matters most on servers with leaf nodes or gateways, where such a pull could lose messages. There are no API changes; the new pieces are internal.
No further pull on a rejected inbox (#206). nats-server rejects a pull consumer's reply inbox mid-run in two cases. A configuration reload that withdraws the subscribe permission sends Permissions Violation for Subscription to "_INBOX.JS.PULL.<nuid>.*", leaving the connection open. A reconnect's replay of the inbox is refused when the new server is at the account's subscription limit. Whichever fiber's read met the -ERR recorded the rejection: your handler's own processIncoming(), an application's read loop while the handler or onError waited, or a failed write's recovery. The run only looked at it at the top of its loop. So the pass went on to refill the pipeline on the dead inbox and to wait for the new pull's deadline, setExpiresMs() plus a second, or for unrelated bytes to arrive. A finite run with no pull left returned its count without the error. A later pull's terminal status ended the run as if nothing had happened. The idle backoff was not woken. A pull whose write failed was retried after its recovery's replay had been rejected.
Those pulls were not harmless. With leaf nodes or gateways enabled, nats-server serves a pull younger than 2 s even when its reply subject has no local interest, so the batch went to an inbox nobody held. On a consumer with ack_policy: none or max_deliver: 1 it was lost; otherwise it came again only after ack_wait.
The run now looks at the rejection after every wait that can let another fiber run. The rejection also wakes the run's read and its idle backoff at once, and each pull is published through a guard that refuses it once the rejection is recorded, before a retry after recovery too. No new pull and no retry goes out once the run knows its inbox was rejected. The run still hands what its pulls hold to your handler first, as before any failure (#197), and then throws the rejection.
Measured on nats-server 2.12.15 with leafnodes { port: 7422 } and a consumer with ack_policy: none holding three messages. A configuration reload withdrew the permission while the handler held m-1, and another fiber read the -ERR. With 2.25.0, a pull went out right after the rejection and the server served m-2 to nobody (num_pending 1, delivered.stream_seq 2). handle() failed only when the server's next PING ended its read, about 2 s later; without that PING it would have waited for the pull's deadline. With 2.25.1, handle() throws the rejection within a millisecond, the only write after it is the inbox's UNSUB, and m-2 and m-3 stay on the consumer (num_pending 2, 5/5 runs).
setIterations()) that has delivered its last batch now throws the rejection instead of returning its count when the inbox was rejected during the run. So does a run that a later pull's terminal status, such as 409 Consumer Deleted, would have ended; that status then never reaches onError.stop() made by then still makes handle() return its count, and a handler or onError that throws still ends the run with its own exception.codecov/patch 100%).The full record is in the CHANGELOG.
onError runs, or while one of its
pulls is being written, now ends with that rejection as soon as that code returns (#206). A finite run
(setIterations()) that has delivered its last batch throws the JetStreamException instead of returning its count,
and so does a run that a later pull's terminal status, such as 409 Consumer Deleted, would have ended, whose status
then never reaches onError. A stop() made by then still makes handle() return its count, and a handler or
onError that throws still ends the run with its own exception.setExpiresMs() plus a second later (#206).
nats-server rejects the inbox mid-run when a configuration reload withdraws the subscribe permission (Permissions Violation for Subscription to "_INBOX.JS.PULL.<nuid>.*", the connection staying open), and rejects a reconnect's
replay of it when the new server is at the account's subscription limit. Whichever fiber's read met the -ERR
recorded the rejection, the handler's own processIncoming(), an application's read loop while the handler or
onError waited, or a failed write's recovery, and the engine looked at it at the top of its loop only. That pass
went on to refill the pipeline, one pull for each one retired, and to read until the new pulls' deadline; a finite
run with no pull left returned its count without the error, a later pull's terminal status ended the run as if
nothing had happened, the idle backoff (up to 500 ms) was not woken, and a pull whose write failed was retried on the
new connection after its recovery's replay had been rejected. Such pulls are not harmless: nats-server serves a
waiting pull only when its reply subject has interest, except that with leaf nodes or gateways enabled it serves one
younger than 2 s anyway, so the batch went to an inbox nobody held, lost on a consumer with ack_policy: none or
max_deliver: 1, delivered again after ack_wait otherwise. Measured on nats-server 2.12.15 with leafnodes { port: 7422 } and no leaf node connected, a pull for 3 messages whose reply subject had no subscriber left the consumer at
num_pending 0, delivered.stream_seq 3. The run now looks at the rejection again after every wait that can let
another fiber run: before each pull it retires, after a terminal status's onError and after its hand-over, and after
the issue phase. The rejection fires a wake-up of its own, which ends the pump read and the idle backoff at once, and
each pull goes out through a guarded publish whose guard refuses it before the first write, before the retry after a
failed write's recovery, once a sealed reconnect flush lets it go on, and in the writer of a publish made while the
connection drains (NatsClient::publishGuarded(), @internal). No new pull and no retry goes out once the run knows
its inbox was rejected; a pull the socket has already taken, or one already in the reconnect buffer, still does. The
run hands what its pulls hold to the handler first, as before any failure of the run (#197), a handler that fails
there being reported, and then throws the rejection. Found by the review of #197 (2.22.0).Minor release. A JetStream pull consumer can now be restarted with stop() (or drain()) and handle() in the same tick, without awaiting the run under w
Minor release. A JetStream pull consumer can now be restarted with stop() (or drain()) and handle() in the same tick, without awaiting the run under way (#189). This is what a supervisor does when it changes a consumer's settings on a signal. Before, the second handle() cleared the stop meant for the earlier run. That run went on next to the new one, with its old handler and settings, until a later stop() reached it at its pull's deadline.
Upgrading is recommended if you restart a PullConsumerIterator without awaiting the previous handle() future. That includes restarting it from inside a handler, for example on a control message. Code that awaits each run before it starts the next sees no change. There are no API changes. What changes:
stop() and drain() act on every run active when they are called, and handle() no longer resets them. Each handle() run now has its own stop/drain flags and wake-ups.stop() and handle(), the earlier run ends on its stop, its future resolving with its count, and only the new run handles messages. Whatever the earlier run holds is left undelivered, as after any stop(). That holds in its retire phase and in every hand-over: a run that fails, one that goes on past a frame that ended the connection, the client's drain(), the overflow, and a terminal status.drain() and handle(), the earlier run delivers its pulls in flight to its own handler, next to the new run, and ends without pulling again.stop() in between still all go on, sharing a priority group's pin. One stop() ends them all, now each at once; older runs used to see it only at their pull's deadline. A stop() or drain() that an older run's handler makes once a newer run is going reaches the newer run too.symfony-nats-messenger fetches with fetchBatch(), not the pull consumer iterator, so this release does not change it.
stop() or drain() followed by handle() in one tick restarts a pull consumer (#189). Measured on nats-server 2.12.15 with a durable consumer and explicit acks. A run of batch 1, depth 1 and a 30 s expiry waited on the empty stream; then came stop() and handle() in one tick, and four published messages.
stop() the first run's pull still waited on the server.The 2.17.0 advice to await a run's future before calling handle() again is withdrawn.
examples/pull-consumer-restart.php restarts a waiting pull consumer with stop() and handle() in one tick, with a new batch size, then publishes three orders. It prints OK pull-consumer-restart: the stopped run handled 0 message(s), the restarted run all 3. Against 2.24.6 it fails with expected the stopped run to end at its stop, it is still running.The full record is in the CHANGELOG.
PullConsumerIterator::stop() and drain() now act on every run active on the iterator when they are called, and
handle() no longer resets them for a run already going (#189). Code that called handle() again before the
previous run's future had resolved, which the README asked to avoid, no longer finds that run still going: after
stop() and handle() the previous run ends on its stop, its future resolving with its count, and after drain()
and handle() it delivers its pulls in flight to its own handler, next to the new run, and ends without pulling
again. The previous run's handler may still be finishing its message when the new run starts: await the previous
future first where two handlers must never run at once. Runs started on one iterator without a stop() in between
still all go on, and one stop() still ends them all, now each at once, where an older run used to see it only at
its pull's deadline; a stop() or drain() that an older run's handler makes once a newer run is going reaches the
newer run too. Code that awaits each run before starting the next sees no change.[feature] A pull consumer can be restarted with stop() (or drain()) and handle() in one tick, without awaiting
the run under way, as a supervisor that changes the consumer's settings on a signal does (#189). Every run of one
PullConsumerIterator used to read the iterator's two flags: handle() cleared them and replaced the wake-ups of
#181 before the earlier run's engine resumed, so that run lost the stop() or drain() meant for it and went on
next to the new one, on the same consumer with its old handler and settings, one more run, inbox and set of pulls on
the server with each restart, until a later stop() reached it at its pull's deadline (its expiry plus a second),
or the connection closed. A restart from the handler, or from another fiber while the handler waited, also handed
the rest of what the run held to the old handler, against the documented "a stop() leaves the rest undelivered":
in the retire phase, and in the hand-overs of a run that fails (#197), that goes on past a frame that ended the
connection (#210, then also pulling on the new connection), that the client's drain() asks (#207), and of a
run's overflow and a terminal status (#187). Each run now has its own flags and wake-ups (PullRunLifecycle,
@internal), which live as long as the run: the iterator signals every run active when stop() or drain() is
called, and forgets a run once its future has resolved. Measured on nats-server 2.12.15 with a durable consumer and
explicit acks, a run of batch 1, depth 1 and a 30 s expiry waiting on the empty stream, then stop() and handle()
in one tick and four messages published: in 2.24.6 the first run's future was still pending 3 s later, the old
handler got m-1 and m-3 and the new one m-2 and m-4, and after a final stop() the first run's pull still waited on
the server; now the first run returns 0 at once, its request dropped with the interest in its inbox, and the new
handler gets all four. The 2.17.0 advice to await a run's future before calling handle() again is withdrawn. Found
by the review of #181 (2.17.0).Patch release. requestMany(), fetchBatch() and fetchNext() no longer lose what they received when their read meets a fatal server -ERR and the reconne
Patch release. requestMany(), fetchBatch() and fetchNext() no longer lose what they received when their read meets a fatal server -ERR and the reconnect has already reopened the connection (#196).
Upgrading is recommended for applications that collect replies with requestMany() or fetch with fetchBatch() / fetchNext() with reconnect enabled, the default. There are no API changes.
A collection keeps what it received past a fatal -ERR (#196). A fatal -ERR, such as Stale Connection or User Authentication Expired, comes right before the server closes the connection. The read that meets it recovers the connection within the operation's wait before it throws the server's error (#171). requestMany() and fetchBatch() return what they received when their read fails with the connection going. They judged that by the connection's state, though, and after a quick reconnect the state was already the new connection's: Open. So they threw the -ERR and lost what they had received. A scatter-gather never saw the replies it had collected. Fetched messages, which the server counted as delivered, came again only after ack_wait, or never on a consumer without acks or with max_deliver: 1. A complete result whose chunk also brought the -ERR was lost the same way, fetchNext() included.
Both collections now ask whether the failure ended the connection, as the pull consumer engine does (#210), and return what they received. With nothing received they still throw the server's error. A failure that leaves the connection open still fails the collection: an -ERR the server keeps the connection open for, or a handler's exception with handlerErrorsFailOperations. The collection never sends its request or pull again on the new connection.
-ERR its read met; it returns what it received. The connection events (Disconnected, Reconnected) announce the reconnect.try/while/catch blocks and fetchBatch()'s visibility.The full record is in the CHANGELOG.
requestMany(), fetchBatch() or fetchNext() whose read meets a fatal server -ERR after it has received
something now returns what it received, also when the reconnect has reopened the connection by then (#196). It no
longer throws the server's error then; the connection events (Disconnected, Reconnected) announce the reconnect.
With nothing received it still throws the error.requestMany(), fetchBatch() or fetchNext() whose read met a fatal server -ERR (Stale Connection,
User Authentication Expired, ...) threw it and lost what it had received whenever the reconnect had already reopened
the connection, as a quick one does (#196). The read recovers the connection within the collection's wait before it
throws the server's error (#171), and the collection judged whether the connection was going by its state, by then
the new connection's: Open. The replies a scatter-gather had collected never reached it, and the messages a fetch had
received, which the server counted as delivered, came again only after the consumer's ack_wait, or never on a
consumer without acks or with max_deliver: 1. A complete result whose chunk also brought the -ERR was lost the
same way. The collection now asks whether that failure ended the connection, as the pull consumer engine does
(#210), and returns what it received, as it does when its read fails with the connection going any other way. A
failure that leaves the connection open (an -ERR the server keeps the connection open for, a handler's exception
with handlerErrorsFailOperations) still fails the collection, and the collection never sends its request or pull
again on the new connection.Patch release. The library now requires amphp/amp ^3.1.3, up from ^3.1 (#200). Under amp 3.1.0 to 3.1.2, a request with waitForReconnect: false lost a
Patch release. The library now requires amphp/amp ^3.1.3, up from ^3.1 (#200). Under amp 3.1.0 to 3.1.2, a request with waitForReconnect: false lost a reply that came in the same read as a server's lame-duck INFO.
Upgrading is recommended for every application whose composer.lock holds amp 3.1.0 to 3.1.2. There are no API or code changes.
INFO is no longer lost under amp 3.1.0 to 3.1.2 (#200). Before amp 3.1.3, CompositeCancellation::isRequested() and throwIfRequested() reported a part that had fired only one event-loop tick later. With waitForReconnect: false, the read that meets a lame-duck INFO asks such a composite whether the request's wake-up has fired, that is, whether its reply came in the same chunk. Under 3.1.2 the answer was no. The request failed with Connection is not open, its reply delivered and dropped, every time the reply came behind the INFO (reconnect on, a cluster to fail over to). requestMany() and fetchBatch() returned what they had received, and a SubscriptionQueue poll kept its message for the next poll. amp 3.1.3 asks the composite's parts directly. CI always resolves the newest amp, so only applications and contributors locked on an older release met it.php >=8.1, revolt/event-loop ^1 || ^0.2).composer update, or with composer update idct/php-nats-jetstream-client --with-all-dependencies (-W). Without -W, updating this package alone keeps the locked amp, and Composer stays on 2.24.4 without an error.OperationReadLameDuckFailoverTest::testWithWaitingDisabledAnOperationWhoseReadBringsTheLameDuckInfoFailsAtOnce and OperationReadReconnectLifecycleTest::testAnOperationParkedOnTheReconnectItStartedDoesNotSpin.The full record is in the CHANGELOG.
amphp/amp ^3.1.3, up from ^3.1 (#200). 3.1.3 is a patch release with the same
requirements as 3.1.2 (php >=8.1, revolt/event-loop ^1 || ^0.2). An application whose lock holds amp 3.1.0 to
3.1.2 gets this release and amp 3.1.3 with composer update, or with
composer update idct/php-nats-jetstream-client --with-all-dependencies (-W). Without -W, updating this package
alone keeps the locked amp, and Composer stays on 2.24.4 without an error.amphp/amp 3.1.0 to 3.1.2, which composer.json still allowed, a request with waiting for a reconnect
disabled lost a reply that came in the same read as a server's lame-duck INFO (#200). Before 3.1.3,
CompositeCancellation::isRequested() and throwIfRequested() reported a part that had fired only one event-loop tick
later. With waitForReconnect: false the read that met the lame-duck INFO asks such a composite whether the
request's wake-up has fired - that is, whether its reply came in the chunk - and the request then returns the reply.
Under 3.1.2 it was told no, so the request failed with Connection is not open, its reply delivered and dropped,
every time the reply came behind the INFO (reconnect on, a cluster to fail over to). requestMany() and
fetchBatch() returned what they had received, and a SubscriptionQueue poll kept its message for the next poll.
amp 3.1.3 asks the composite's parts directly, and the library now requires it. Two existing tests, which CI ran under
the newest amp only, pin this and fail under 3.1.2:
OperationReadLameDuckFailoverTest::testWithWaitingDisabledAnOperationWhoseReadBringsTheLameDuckInfoFailsAtOnce
(the reply case) and OperationReadReconnectLifecycleTest::testAnOperationParkedOnTheReconnectItStartedDoesNotSpin,
whose look counter a 3.1.2 composite never asked.Patch release. Requests now work while the client's drain() delivers. A pull consumer handler that acks with ackSync() therefore no longer processes e
Patch release. Requests now work while the client's drain() delivers. A pull consumer handler that acks with ackSync() therefore no longer processes every handed-over message twice (#213). The request that sets up the shared reply inbox also keeps to its own timeout now (#194).
Upgrading is recommended for every worker that drains its client on shutdown (SIGTERM) while a pull consumer or a subscription handler makes requests. There are no API changes.
ackSync() and other requests during drain() (#213). Since 2.24.0 the client's drain() hands what a pull consumer run holds to its handler. The connection refused every request while Draining, so ackSync() failed there and the server delivered each message again after ack_wait. Measured on nats-server 2.12.15 with the iterator's defaults: 29 of 87 messages were processed twice in one shutdown.
The drain now keeps the shared reply inbox subscribed until it has delivered everything. It also sets the inbox up for a worker that has made no request yet. Requests made during that phase go through the existing bounded request writers. This covers ackSync(), JetStream publish, Key/Value reads and writes, request() and requestMany(), from pull consumer handlers and from core subscription handlers.
The drain stays within its single budget. When delivery ends, or at the drain's deadline, any request still waiting fails with Connection is not open. Whatever is still undelivered is counted in the drain deadline exceeded report before those requests are woken.
Reply-inbox setup within the request's own budget (#194). A request whose reply inbox SUB met a dead socket waited up to another requestTimeoutMs for the reconnect, and could be sent after its deadline. It now times out with its own Request timed out for subject <subject> while waiting for the reply inbox to be set up. Requests that joined that setup no longer fail with its timeout.
ack() in a handler that may run during a drain.UNSUB of the reply inbox now comes after the requests on the wire.disconnect() ends the requests in flight as it begins, rather than once the transport's close fails their reads. A request made while that close is under way is not sent.msgId.subscribe() stays refused while Draining. So do the operations that need a subscription of their own:
fetchBatch() and fetchNext();keys() and history();pull-consumer-graceful-drain.php now acks with ackSync() and fails on 2.24.3.The full record is in the CHANGELOG.
drain() delivers (#213), which withdraws the 2.24.0 advice to ack with ack()
in a handler that may run during a drain: ackSync(), a JetStream publish, a Key/Value read or write, request()
and requestMany() made by a handler the drain runs - a pull consumer run's in its hand-over, or a core
subscription's with a message the drain delivers - now get their replies, also when the client has made no request
before. The drain keeps the shared reply inbox subscribed until its delivery phase is over, subscribes it for a
first request, and unsubscribes it at the end, so its UNSUB now follows the requests on the wire instead of
coming first. The round trips count against the drain's one budget (requestTimeoutMs).Connection is not open, whichever fiber made it: a request of another fiber is taken while the
drain delivers, but the drain does not wait for its reply, which can come too late although the server has acted on
it; give a JetStream publish made there a msgId. A request made after that phase, after a disconnect() that
interrupts the drain, or from the listener of the drain's deadline report is still refused, unsent. Subscriptions,
and what needs one of its own (fetchBatch(), fetchNext(), a pull consumer's new pulls, batched Direct Get,
Key/Value keys() and history(), an Object Store download of more than one chunk), stay refused while Draining.disconnect() now ends the requests in flight as it begins, wherever they wait, with Connection is not open,
rather than once the close of the transport fails their reads; a request made while the close is under way is not
sent.SUB meets a dead socket and a reconnect that outlasts its timeout now fails with Request timed out for subject <subject> while waiting for the reply inbox to be set up, where it used to wait up to another
requestTimeoutMs and fail with Subscribe to "_INBOX.<inbox>.*" timed out waiting for the connection to be re-established.drain() delivered failed at once with Connection is not open, so a
pull consumer handler that acked with ackSync() processed every message the drain handed over twice (#213). Since
2.24.0 the drain hands the messages a pull consumer run holds to its handler, but it unsubscribed the shared reply
inbox before delivering anything, and the connection refused every request while Draining: the handler processed
the message, its ackSync() failed, nothing reached the server, and the server delivered the message again after
ack_wait, to be processed a second time. Measured on nats-server 2.12.15 with the iterator's defaults, a producer at
20 messages a second and the worker drained 4.5 s in: 29 of 87 messages were processed twice. A handler that made a
request as part of its work (a JetStream publish, a Key/Value write) failed on its first message instead, and a core
subscription's handler whose message the drain's flush delivered could not make a request either. The drain now
keeps the reply inbox through its delivery phase and releases it afterwards, lets a request subscribe it when the
client has none, and takes requests through the bounded request writers while it delivers. One request lifetime per
connection, ended by the application's close, bounds every wait of every request: the end of the delivery phase -
everything delivered, or the deadline, which a timer enforces wherever the drain is - seals delivery, counts what is
left for the deadline report, and only then ends the requests still waiting, so that a run whose handler a woken
request lets go on cannot hide what it held, and the drain still closes within its budget. A write that fails while
the drain holds the connection is neither retried nor followed by a reconnect.SUB held up by
backpressure, or the reconnect its failed write started, could keep the request waiting past its own timeout and
its caller's cancellation (#194). The set-up now runs within the request's budget, through the bounded writer of the
guarded inboxes; a request that joined the set-up is no longer failed with the other request's timeout when that
request stops waiting: the abandoned SUB is followed by an UNSUB once it is out, and the joiner subscribes the
inbox itself within its own budget. The UNSUBs owed for muxes dropped before are taken in the step that writes
them, so a set-up that never writes leaves them owed for the next one.Patch release. An infinite JetStream pull consumer run (PullConsumerIterator::handle() without setIterations()) no longer drops messages it has receiv
Patch release. An infinite JetStream pull consumer run (PullConsumerIterator::handle() without setIterations()) no longer drops messages it has received when the connection reconnects (#187). Before, the run threw its pulls in flight away at a reconnect together with what they held, and dropped every message none of its pulls had room for. The server counted those messages as delivered, so they came again only after ack_wait, or never on a consumer with ack_policy: none or max_deliver: 1.
Upgrading is recommended for every infinite pull consumer worker that runs with reconnect enabled, the default. There are no API changes.
ack() ran.Stale Connection close) still serves the requests the run issued before the reconnect once the reconnect has subscribed the run's inbox again, and a pull written during the outage goes out from the reconnect buffer afterwards. What none of the run's pulls has room for is now held for the handler, in arrival order, behind what the pulls hold. Measured on nats-server 2.12.15 with the worker's socket closed while the server stayed up (batch 1, depth 1, ack_policy: none): after the reconnect the consumer held two waiting requests and the worker received m-1 and m-2. With 2.24.2 the handler got only m-1; with 2.24.3 it gets both.409 Consumer Deleted, or a stale-pin 423, that a pull got before the reconnect is ignored once the run has ended that pull, also when the reconnect happened in the handler of an earlier pull; it used to end the run through onError, or drop a pinned group's pin. The iterator's drain() across a reconnect now delivers what the pulls in flight had received.setBatching() times setDepth() before the run pulls again, and the result of handle() counts them. The run issues no new pull while it holds such messages.409 Consumer Deleted, say) now hands over what the pulls behind the one it ended hold before handle() resolves; those messages used to be left unacked.stop(), disconnect() and a client drain() whose budget runs out still leave the rest undelivered. The iterator's drain(), the client's drain() within its budget and a run that fails hand it over, and the drain's drain deadline exceeded report counts it.setIterations()) are unchanged: they keep their exact count and drop a message past their last pull's batch, as fetchBatch() does. symfony-nats-messenger fetches with fetchBatch() and is not affected.The full record is in the CHANGELOG.
PullConsumerIterator::handle() run (no setIterations()) now hands its handler every message the
server sends it, also more than its pulls in flight asked for (#187). After a reconnect the server can hold more of
the run's pull requests than the run counts: a server that outlived the connection serves the requests the run
issued before the reconnect once the reconnect has subscribed the run's inbox again, and a pull written during the
outage goes out from the reconnect buffer afterwards. Those messages used to be dropped; they now reach the handler
in arrival order, behind what the run's pulls hold, and count in the result of handle(), so that across a
reconnect a handler can get more messages than setBatching() times setDepth(). The run issues no new pull while
it holds such messages. A terminal pull status (409 Consumer Deleted, say) now also hands over what the pulls
behind the one it ended hold before handle() resolves, where those messages used to be left unacked. stop(),
disconnect() and a drain() whose budget runs out still leave the rest undelivered, and a finite run keeps its
exact count and still drops a message past its last pull's batch.PullConsumerIterator::handle() ends its pulls in flight once the connection's reconnect count
moves, so that it pulls again on the new connection at once (#120), and it dropped them with what they held: a
message the reconnect's own delivery gave a pull while a lower subscription's handler held the engine's read up,
and the answer to a pull the engine had issued on the new connection before it saw a reconnect that the handler's
own ack() ran. It also dropped as a straggler every message none of its pulls in flight had room for, which a
server that outlived the connection sends for the requests the run issued before the reconnect, or wrote from the
reconnect buffer during it. The handler never got such a message; the server delivered it again only after
ack_wait, or never on a consumer with ack_policy: none or max_deliver: 1. Measured on nats-server 2.12.15 with
the worker's socket closed while the server stayed up, an infinite run of batch 1 and depth 1 on a consumer with
ack_policy: none: after the reconnect the consumer held two waiting requests, the worker received m-1 and m-2, and
the handler got only m-1, the consumer's ack_floor at 2. The run now ends its pulls instead of dropping them: what
they received goes to the handler in issue order before any pull goes out, a pull that received nothing leaves
without its status being classified, and what no pull has room for is held for the handler in arrival order, behind
the pulls, wherever the run goes on or ends (the iterator's and the client's drain(), a failure, a terminal
status, a frame that ended the connection), and counted in the drain's deadline report. The run checks the
reconnect count again after every wait, the handler's included, so that a status the old connection brought a pull
still to be retired neither ends the run through onError nor drops a group's pin, and a pull issued after a
reconnect the handler ran is not ended with the old ones; it never does while the client's drain() is under way,
which still gets what the pulls held. The iterator's drain() across a reconnect now delivers what the pulls in
flight had received. Found by the review of #178 (2.14.0), and of #210 (2.23.0).Fixes JetStream batch operations exceeding their own timeout during reconnect and inbox setup (#188).
Fixes JetStream batch operations exceeding their own timeout during reconnect and inbox setup (#188).
fetchBatch() and fetchNext() now share one expiresMs + 1000 ms budget across SUB, reconnect, PUB, collection and cleanup. An empty fetch ends with the usual JetStreamException code 408; a longer fetch can wait beyond the global requestTimeoutMs.Verified with 3,141 unit tests, 150 integration tests, 48 Behat scenarios, PHPStan and formatting checks.
expiresMs + 1000 ms, including inbox SUB, failed-write
recovery, PUB and collection. An empty fetch whose own budget expires reports the usual
JetStreamException('No messages received within timeout', 408) instead of a global subscribe
timeout. A longer fetch may wait past requestTimeoutMs. Direct Get includes setup in its
initial no-progress interval and renews that interval when replies arrive, even during a pending
PUB; the multi-subject helper keeps a separate interval for each chunk (#188).fetchBatch(), fetchNext(), directGetBatch() and directGetLastForSubjects()
setup and failed PUB recovery by their own budgets, including inline write backpressure.
Batch requests do not enter the reconnect buffer; a retry checks its inbox and remaining budget.
Completed replies wake a pending publication, and late failed writes recover without resending (#188).When a request's PUB/HPUB write discovers a lost connection, recovery now respects the request's original timeout, caller cancellation, and waitForRec
Patch release fixing #215.
When a request's PUB/HPUB write discovers a lost connection, recovery now respects the request's original timeout, caller cancellation, and waitForReconnect: false. Previously, the request waited for the entire reconnect and could be sent after its caller had given up.
request(), requestWithHeaders() and requestMany() use a bounded write path, including inline socket backpressure, with at most one retry.requestMany() throws TimeoutException if its send cannot complete within the budget. After a successful send, collection expiry still returns the replies collected, possibly none.An already-started transport write can finish after timeout or cancellation; neither guarantees that the server did not act on the request.
Validation on PHP 8.5: 56 new regression cases; full E2E with 3,101 unit tests, 149 integration tests and 48 Behat scenarios; PHPStan level 8 and coding style checks. The release stamp also passed the codec and request tests (83 cases).
See the changelog for details.
waitForReconnect: false while the connection recovers (#215).
requestMany() throws TimeoutException when its budget expires before the send completes;
after a successful send, its collection timeout still returns the replies collected, possibly none.
A transport write already in progress can finish after cancellation or timeout; neither guarantees
that the server did not act on the request.request(), requestWithHeaders() and requestMany() PUB/HPUB writes and their
single recover-and-retry within the request's original budget, including inline socket backpressure.
Recovery continues independently after the request ends; expired requests are neither buffered
nor retried later. Each attempt rechecks the budget, connection state and shared reply inbox before
writing, so an inbox rejected or dropped during recovery cannot receive a retry (#215).Minor release. The client's drain() now hands a JetStream pull consumer run the messages its pulls hold, waits for the handler while the acks go out,
Minor release. The client's drain() now hands a JetStream pull consumer run the messages its pulls hold, waits for the handler while the acks go out, and then closes the connection; PullConsumerIterator::handle() then resolves with its count (#207). Before, the drain closed the connection under the run: those messages were lost on a consumer without acks and came again after ack_wait otherwise. disconnect() now discards what a run holds wherever the run is, as it discards the connection's own queue.
Upgrading is recommended if you shut pull consumer workers down with the client's drain(), for example from a SIGTERM handler. There are no API changes. What changes when the application closes a connection that a pull consumer run uses:
drain(): once its flush is done, it asks each run to hand every pull in flight to the handler, in order, while the connection is Draining, and waits for that, the handler included, within its budget (requestTimeoutMs). The run then ends and handle() resolves with its count instead of failing with Connection is not open. What the budget leaves is discarded and named in the drain's drain deadline exceeded report. While the client drains, a run issues no new pull.ack(), nak(), term() and inProgress() go out. Requests do not: the connection refuses them while it is Draining, so ackSync(), a JetStream publish or a Key/Value write fails there with Connection is not open. A handler that may run during a drain should ack with ack().onError or errorListener that awaits the client's drain() holds that drain for its whole budget, as a core subscription's handler does, since the drain waits for the run that waits for it. Stop or drain the iterator there and drain the client once handle() has resolved, or call drain() without awaiting it.disconnect(), from the handler or another fiber, now also ends the hand-over of a pull the run retires, before the next message. The rest of the pull used to reach the handler after the close, every ack failing. With explicit acks the rest is now delivered again after ack_wait and processed once rather than twice; on a consumer without acks or with max_deliver: 1 it is lost, as in the hand-over before a failing run since 2.22.0. handle() still fails after a disconnect(), except where the client's drain() had already asked the run for its hand-over, or a finite run has no pull left to issue.A worker that drains the iterator and awaits handle() before it closes the connection sees no change. symfony-nats-messenger fetches with fetchBatch(), not the pull consumer iterator, and works with this release unchanged.
drain() dropped what a pull consumer run's pulls held (#207). The engine hands a pull's messages to the handler only when the pull completes (its batch full, a status from the server, or its deadline), and the drain delivered only the connection's own queues before it closed the connection under the run. Measured on nats-server 2.12.15 with ack_wait 3 s, the stream holding m-1 and m-2, and drain() called 1 s into an infinite run of batch 3. With 2.23.0 the handler got nothing and handle() threw Connection is not open. With ack_policy: none both messages were gone, and with explicit acks both came again after ack_wait. With 2.24.0 the handler gets m-1 and m-2 while the connection is Draining, both acks reach the server (ack_floor 2, nothing pending), and handle() returns 2.disconnect() discards what a pull consumer run holds also while the run hands over a pull it retires (#207). This matches what it does to the hand-over before a run fails and to the connection's own queue (nats.go Close() parity). Measured on the same server, with the handler awaiting disconnect() on m-1 of a batch-2 pull: with 2.23.0, m-2 reached the handler on the closed connection, its ack failing, and with explicit acks it was delivered again after ack_wait; with 2.24.0, m-2 is not handed over and is delivered again once.examples/pull-consumer-graceful-drain.php: a pull consumer worker shut down with drain() while its pull holds three messages. It prints OK pull-consumer-graceful-drain: drain() handed the 3 message(s) the pull held to the handler and waited for their acks (ack floor 3). Against 2.23.0 it fails with handle() failed after the drain, the handler having got 0 message(s): Connection is not open.The full record is in the CHANGELOG.
PullConsumerIterator::handle(), now follows the connection's own rule when the
application closes the connection (#207): the client's drain() hands over what the run's pulls hold, and
disconnect() discards it, wherever the run is. Once its flush is done, drain() asks each run to hand every pull in
flight to the handler, in order, while the connection is Draining, so that the handler's acks still go out, and waits
for that, the handler included, within its budget (requestTimeoutMs); the run then ends and handle() resolves with
its count, as after the iterator's drain(), where it used to fail with Connection is not open, the handler having
got none of those messages. A drain() can therefore take as long as such a handler, up to its budget, before it
closes the connection; when the budget runs out first, the rest is discarded and counted in its
drain deadline exceeded report, and handle() still resolves with what was handed over, unless the run was writing
a pull as the drain closed the connection, which fails it with that write's error. Only the acks the handler publishes
go out during that hand-over (ack(), nak(), term(), inProgress()): the connection refuses requests while it is
Draining, so ackSync(), a JetStream publish or a Key/Value write fails there at once with Connection is not open;
a handler that may run during a drain acks with ack(). A handler, an onError or an errorListener that awaits the
client's drain() while the run calls it holds that drain for its whole budget, as a core subscription's handler that
awaits it does, since the drain waits for the very run that waits for it, and the rest of the pull is then discarded:
stop or drain the iterator there and drain the client once handle() has resolved, or call the client's drain()
from another fiber or without awaiting it. While the client drains, a run issues no new pull. A disconnect(), from
the handler or from another fiber, now also ends the hand-over of a pull the run retires, before the next message,
where the rest of the pull used to reach the handler after the close had returned, every ack failing: on a consumer
with acks that rest is delivered again after ack_wait and processed once, rather than twice, and on a consumer
without acks (ack_policy: none) or with max_deliver: 1 it is lost, as the hand-over before a run fails loses it
since 2.22.0. handle() still fails after a disconnect(), with Connection is not open or the error of the read or
write that met the close, except where the client's drain() had already asked the run for its hand-over, or where a
finite run has no pull left to issue: it then resolves with its count. A worker that drains the iterator and awaits
handle() before it closes the connection sees no change.[bugfix] disconnect() discards what a pull consumer run's pulls hold also while the run hands over a pull it
retires (#207), as it discards it in the hand-over before a run fails since 2.22.0 and as it discards what the
connection itself has received and not delivered (nats.go Close() parity): the handler gets no message after the
close, whether the handler or another fiber called disconnect(), and the rest of the pull stays unacked. The retire
phase used to hand a full pull over whole, the handler running on the Closed connection after disconnect() had
returned, every ack failing, so that with explicit acks those messages were processed and then delivered again. Every
delivery of a run now checks the same signal before each message, the connection's own
(NatsConnection::isDiscardingUndelivered(), @internal): a disconnect() under way or done, or a drain() once
its budget has run out (from its drain deadline exceeded report on, also while it closes the connection), discards;
a drain() within its budget hands over. A pull whose messages the close discards still counts as one that brought
messages, so that the run goes on to meet the close and handle() fails as before, rather than end as if the stream
were exhausted. Measured on nats-server 2.12.15 with ack_wait 3 s and a run of batch 2 and depth 1 whose pull holds
m-1 and m-2, the handler awaiting disconnect() on m-1: in 2.23.0 m-2 reached the handler on the Closed connection,
its ack failing, and with explicit acks the server delivered it again after ack_wait (num_delivered 2); with
ack_policy: none it was processed after disconnect() had returned. Now m-2 is not handed over: with explicit acks
it is delivered again after ack_wait, once, and with ack_policy: none it is lost (ack_floor 2).[bugfix] The client's drain() dropped what a pull consumer run's pulls held, and did not wait for a handler that
was handing a pull over (#207). The engine behind PullConsumerIterator::handle() hands a pull's messages to the
handler only when the pull completes (its batch full, a status from the server, or its deadline), and the drain
delivered only the connection's own queues: it unsubscribed the run's inbox, read until the PONG of its flush and
closed the connection under the run, whose read then failed and handed nothing over, since the drain had set the close
intent (#197), and handle() threw Connection is not open. A worker that drained its client on SIGTERM, without
draining the iterator first, so lost those messages on a consumer without acks and got them again after ack_wait
otherwise; a pull that a message filled during the drain's flush was handed over while the drain closed the
connection, the later messages reaching the handler on the Closed connection with their acks failing; and a run that
went on while the drain flushed wrote its next pull onto the inbox the drain had unsubscribed. The run is now a drain
participant (DrainParticipant, @internal), registered once its inbox is subscribed: once its flush is done, the
drain asks each run to hand every pull in flight over, in issue order, while the connection is Draining, the request
waking a run that waits in its pump read or its idle backoff, and waits for those hand-overs within its single budget,
the drain deadline exceeded report counting what a run still holds when the budget runs out, which the run then
discards, also while the drain closes the connection, rather than hand it over. The run then ends with its count, and
it issues no pull while the connection is Draining. A drain without a connection to drain, or whose flush a
disconnect() cut short, asks no run, whose read then fails and discards what it holds, as before; a drain that first
waited for a reconnect still gets what the pulls held before the connection dropped. Measured on nats-server 2.12.15
with ack_wait 3 s, the stream holding m-1 and m-2, and the client's drain() called 1 s into an infinite run of
batch 3 and depth 1: in 2.23.0 the handler got nothing and handle() threw Connection is not open; with
ack_policy: none the consumer then had both as delivered and acknowledged (ack_floor 2), the messages gone, and
with explicit acks both came again after ack_wait (num_delivered 2). The handler now gets m-1 and m-2 while the
connection is Draining, drain() returns once that is done, and handle() returns 2; with explicit acks both acks
reach the server (ack_floor 2, num_ack_pending 0) and nothing comes again.Minor release. An infinite JetStream pull consumer run, PullConsumerIterator::handle() without setIterations(), now goes on after the server ends the
Minor release. An infinite JetStream pull consumer run, PullConsumerIterator::handle() without setIterations(), now goes on after the server ends the connection with a fatal -ERR such as Stale Connection or User Authentication Expired, once the reconnect has reopened it, as it already went on after a lost connection (#210). Before, handle() threw the server's error while the connection was open again, and a worker stopped consuming until something started it again.
Upgrading is recommended if you run long-lived pull consumers with reconnect on: workers whose handlers sometimes block the event loop for longer than a few of the server's ping intervals (the server then sends Stale Connection), and consumers using short-lived JWTs that jwtProvider renews on every reconnect (each expiry sent User Authentication Expired). There are no API changes. What changes for an infinite run with reconnect on and waitForReconnect enabled (the defaults):
errorListener and to the logger (NATS connection error: Server sent error frame: 'Stale Connection') instead of out of handle().handle(). A handler that throws there ends the run with its own exception.A finite run still ends with the server's error, and so does an infinite run with reconnect off or waitForReconnect: false, or whose connection you are closing. An infinite run whose reconnect gives up ends as it does after a lost connection.
symfony-nats-messenger fetches with fetchBatch(), not the pull consumer iterator, and works with this release unchanged.
-ERR or a failed PONG even when the reconnect had reopened the connection (#210). The read that met such a frame recovered the connection and threw the frame's error once the reconnect was done, and the engine took that as the end of the run, where after an EOF it pulls again on the new connection. Such a run now goes on as after a lost connection. Measured on nats-server 2.12 with ping_interval: "1s" and ping_max: 1: an infinite run whose handler blocked the process for 3.5 s. With 2.22.0, handle() threw Server sent error frame: 'Stale Connection' right after the Reconnected event, and the messages published afterwards were never consumed. With 2.23.0 the error reaches the error listener, the run consumes those messages on the new connection, and nothing is left pending.-ERR as the failure of an infinite run with reconnect on were moved to reconnect off (one to waitForReconnect: false), so they keep testing what they tested. On the changed lines, Infection generated 71 mutants: 34 killed, 4 timed out, 26 skipped as too slow and 7 escaped. Four of the escaped ones reset idle counters that the reconnect resets again, one changes a condition with no observable effect, and two only change whether a pull is issued during a slow reconnect, which is the open issue #187.The full record is in the CHANGELOG.
PullConsumerIterator::handle() without setIterations(), with reconnect on
and waitForReconnect enabled (the defaults), now goes on after a fatal -ERR (Stale Connection,
User Authentication Expired, ...) or a server PING whose PONG the socket would not take, once the reconnect has
reopened the connection, as it goes on after a lost connection (#210). The frame's error goes to the error listener
and the logger, and handle() no longer throws it: a worker that restarted its consumer when handle() failed with
Server sent error frame: 'Stale Connection' finds the run still going. What the pulls held when the connection ended
reaches the handler as part of the run and counts in the result of handle(), and a handler that throws there ends
the run with its own exception, where 2.22.0 reported it and threw the frame's error. A finite run still ends with the
frame's error, and so does an infinite one with reconnect off or waitForReconnect: false, whose connection the
application is closing, or whose reconnect gave up, or whose new server refused the credentials, while the read that
met the frame was still waiting for it. A reconnect that gives up only after that read stopped waiting, as one against
a server that stays down does with the default options (ten attempts whose backoffs alone add up to about 43 s, where
that read waits at most the run's expiry plus one second), ends the run as after a lost connection: the frame's error
goes to the error listener first, and handle() then throws Reconnect attempts exhausted.[bugfix] An infinite pull consumer run ended on a fatal -ERR or a PONG the socket would not take even when the
reconnect had reopened the connection, where it goes on after an EOF (#210). The pump read that met such a frame
recovered the connection and threw the frame's error once the reconnect was done (#171), and the engine took that as
the end of the run: it handed over what its pulls held (#197) and handle() failed with
Server sent error frame: 'Stale Connection' while the connection was Open on the new socket, so a worker stopped
consuming until something started it again. A server sends Stale Connection to a client that left its PINGs
unanswered for a few intervals (a handler that blocks the event loop with synchronous work, a paused process), and
User Authentication Expired when a user JWT expires, which jwtProvider renews on every reconnect, so every expiry
ended such a consumer. Such a run now goes on, as after a lost connection: the frame's error goes to the error
listener and the logger, since nothing else says why the server closed the connection; what the pulls held goes to the
handler in issue order as a delivery of the run, counted in its total, with stop() and a close of the application's
ending it and a pinned group's pin captured from it; and the run pulls again on the new connection, once the reconnect
is done, or, when the read's own wait ended first, once its next read has waited for the reconnect. A finite run,
reconnect off, waitForReconnect: false, a reconnect that gave up while the read was still waiting for it and a close
of the application's still end the run with the frame's error, and so does any failure that leaves the connection
open; a reconnect that gives up later ends the run as after an EOF, with Reconnect attempts exhausted. Measured on
nats-server 2.12 with ping_interval: "1s" and ping_max: 1: an infinite run of batch 1 and depth 1 whose handler
blocked the process for 3.5 s on m-1 (usleep()), the client's own heartbeat off. The server logged
Stale Client Connection - Closing; in 2.22.0, handle() threw Server sent error frame: 'Stale Connection' right
after the Reconnected event, 3.5 s into the run, with ack_policy explicit and none alike, and m-2 and m-3,
published once the client had reconnected, were never consumed (num_pending 2). The run now reports that error to
the error listener, gets m-2 and m-3 on the new connection, and handle() returns 3 when the handler stops it on m-3
(num_pending 0, num_ack_pending 0 with explicit acks). With the process blocked by a timer while the run's pull
(batch 3) held m-1, 2.22.0 handed m-1 over before it threw; the run now hands it over as part of the run and goes on
to m-2 and m-3. A handler that acks m-1 only after blocking still loses that ack to the closed socket, as before: the
server redelivers m-1 after ack_wait.Minor release. A JetStream pull consumer run, PullConsumerIterator::handle(), that ends with an error now hands its handler the messages its pulls had
Minor release. A JetStream pull consumer run, PullConsumerIterator::handle(), that ends with an error now hands its handler the messages its pulls had already received before it throws (#197). Before, those messages were dropped with the run: the server counted them as delivered, so they came again only after ack_wait, and never on a consumer with ack_policy: none or max_deliver: 1.
Upgrading is recommended if you run pull consumers with setBatching() above 1 and reconnect off, waitForReconnect: false, or a consumer without acks. There are no API changes. What changes for a run that ends with an error (its read or a pull's write failing because the connection is going, a fatal -ERR, the server rejecting its reply inbox, or a failure handlerErrorsFailOperations or slowConsumerErrorsFailOperations makes the read's own):
handle() then throws the same error as before.handle().stop() still leaves those messages unhandled, and so does closing the connection yourself with disconnect() or the client's drain(): drain the iterator and await handle() before you close the connection.symfony-nats-messenger fetches with fetchBatch(), not the pull consumer iterator, and works with this release unchanged.
stop() checked before each message, and then throws its error unchanged, as fetchBatch() returns its partial batch since 2.21.0. On nats-server 2.12 with reconnect off, the client's TCP connection cut while a pull held the stream's two messages: on a consumer with ack_policy: none 2.21.0 lost both for good; 2.22.0 hands both to the handler before handle() throws Reconnect is disabled. An infinite run that goes on through a reconnect still discards what its pulls held at the reconnect; that is #187.The full record is in the CHANGELOG.
PullConsumerIterator::handle(), that ends with an error now runs the handler for the
messages its pulls had received before it throws (#197): when its read fails because the connection is going (lost
with waitForReconnect: false, a reconnect that gave up, reconnect off, a fatal -ERR whether or not the reconnect
reopened the connection), when a pull's write fails, when the server rejects its reply inbox, or when its read fails
for a reason handlerErrorsFailOperations or slowConsumerErrorsFailOperations makes the read's own. handle()
still throws the same error, once the handler has run. On a closed connection the handler's ack fails; a handler that
throws during that delivery, as one that lets its failed ack out does, ends it, and its exception goes to the error
listener and the logger instead of out of handle(). A stop() still leaves those messages unhandled, and so does
closing the connection yourself, with disconnect() or the client's drain(), which discards them as before: drain
the iterator and await handle() before you close the connection. A handler that throws at any other time still ends
the run at once with its own exception.[bugfix] A pull consumer run that ended with a failure of its own read or of a pull's write dropped the messages its
pulls in flight had received (#197). The engine behind PullConsumerIterator::handle() hands a pull's messages to the
handler only when it retires the pull (its batch full, a status from the server, or its deadline), so a pull holds
messages the server counted as delivered and the handler has not seen, with setBatching(10) on a stream that
trickles most of the time. A run whose read failed with the connection going, which it does with
waitForReconnect: false once the connection is lost (#178) or failed over from a server in lame duck mode (#191),
when the reconnect gives up, with reconnect off and on a fatal -ERR, ended with that error and dropped them, finite
and infinite runs alike, and so did a run whose pull's write failed while an earlier pull held messages
(depth above 1), whose reply inbox the server rejected, or whose read failed for a reason
handlerErrorsFailOperations or slowConsumerErrorsFailOperations makes its own: the server redelivered those
messages only after ack_wait, and never under ack_policy: none or max_deliver: 1. Such a run now hands the
handler what its pulls received, in issue order, with stop() checked before each message as when it retires a pull,
and then throws that error unchanged, as fetchBatch() returns its partial batch since 2.21.0. A run the application
ends by closing the connection, with disconnect() or the client's drain(), still hands nothing over: the close
discards those messages, as disconnect() discards what the connection received and has not delivered, rather than
run the handler after the close has returned, with every ack failing, and a close made during that delivery ends it as
a stop() does. That covers only the hand-over before the run fails: a pull the run retires normally is still handed
over whole, as before, also when the handler or another fiber closes the connection meanwhile, since the connection's
drain() lets acks out while it is Draining. A handler that throws during that delivery ends it and is reported to
the error listener and the logger, the run's own failure being the one thrown, and a message read while the handler
runs goes to a pull still to be handed over, when one is left open, rather than being dropped with the buffer being
handed over; with none left it is dropped, unacked, and comes again only after ack_wait, or never under
ack_policy: none or max_deliver: 1. Measured on nats-server 2.12 with reconnect off: a run of batch 3 and depth 1
whose pull had received the stream's two messages, the client's TCP connection then cut through a proxy while the
server stayed up. On a consumer with ack_policy: none the handler never saw them, and the server had them as
delivered and acknowledged (ack_floor 2, nothing pending): they were gone. With explicit acks they came back only as
redeliveries after ack_wait (num_delivered 2). The handler now gets both before handle() throws
Reconnect is disabled. With explicit acks its acks fail on the closed connection and the server redelivers both
after ack_wait: a handler that catches the failed ack gets both, and one that lets it out, as a bare
$js->ack($msg)->await() does, gets the first, the failure going to the error listener. A disconnect() or drain()
of the connection while the pull held them handed nothing over, in 2.21.0 and now alike, the messages then lost or
redelivered as above. A graceful server shutdown was not affected: the server answers the waiting pull with
409 Server Shutdown before it closes the connection, which retires the pull. Over the unit suite's scripted server
the same holds with waiting disabled, a reconnect that gave up, a lame-duck failover with waiting disabled, and a
fatal -ERR whose reconnect reopened the connection. An infinite run that goes on through a reconnect still discards
what its pulls held at the reconnect (#187).Minor release. One of the library's operations whose own read brings a server's lame-duck INFO now waits for the failover only within its own deadline
Minor release. One of the library's operations whose own read brings a server's lame-duck INFO now waits for the failover only within its own deadline (#191). Before, the failover ran inline in that read, so a request() waiting for its reply, a SubscriptionQueue poll, a fetch or a flush() waited for the whole failover, dials, handshake, subscription replay and backoff included, before it met its own timeout.
Upgrading is recommended if you run a NATS cluster with rolling restarts or upgrades (a server put into lame duck mode sends that INFO) and connect with more than one server in the pool. There are no API changes. A few behaviours change, all listed in the upgrade notes of the CHANGELOG:
waitForReconnect: false the operation fails at once with Connection is not open, unless what it waits for came in the same read.INFO are delivered by that read before the failover leaves the connection. A publish from one of their handlers is buffered and goes to the new server.requestMany() or a JetStream fetchBatch() whose read fails because the connection is going now returns what it has received instead of throwing; it throws only when it has received nothing.Your own processIncoming() and readIncoming(), a serving loop's read and the heartbeat still run the failover inline. symfony-nats-messenger connects with reconnect off, so no failover runs there; its get() now receives the partial batch when the connection drops in the middle of a fetch.
INFO overran its deadline by the whole failover (#191). The read now starts the failover in a fiber of its own and waits for it only within the operation's deadline and wake-up, as a read that meets a lost connection does since 2.14.0 (#178). The rest of the chunk the INFO came in is still the leaving server's (#182): its PING and INFO are dropped, its -ERR is reported, and its PONG still completes the leaving connection's slot, so a flush() whose PONG came behind the INFO succeeds. On nats-server 2.12, with the second server's dial hanging until connectTimeoutMs, a request() with a 300 ms timeout whose read brought the INFO returned after 3.29 s; it now times out after 0.30 s with the failover under way.requestMany() or a JetStream fetchBatch() whose read failed because the connection was going threw away what it had received. This happened with waitForReconnect: false when the connection was lost or failed over, with any setting when the reconnect gave up, and with reconnect off when the connection dropped. A fetched message the server counted as delivered was redelivered only after the ack wait, or never on a consumer without acks. They now return the replies or the partial batch, as requestMany() already did when the connection closed and fetchBatch() when the heartbeats stopped.DiscoveredServers or LameDuck listener was suspended. It now fails over only the connection the INFO came on, inline or in a fiber of its own.The full record is in the CHANGELOG.
INFO (a request() or
requestMany(), a SubscriptionQueue poll, a JetStream fetch or pull consumer, Key/Value keys() or history(),
a flush() or rtt() waiting for its PONG) no longer waits for the whole failover: it waits within its own
timeout, and with waitForReconnect: false fails at once with Connection is not open while the failover runs on,
unless what it waits for came in the same read (#191). Your own processIncoming() and readIncoming(), a serving
loop's read and the heartbeat still run the failover inline. The messages read with the INFO, those ahead of it
included, are now delivered by the operation's read, with its rules for a handler that throws or a full queue,
before the failover leaves the connection: unless a handler, or the error listener a report of that read goes to,
awaits, ahead of the failover's Disconnected event. What such a handler starts runs once the failover has begun,
since a publish and an operation each run in a fiber of their own: a publish is buffered and goes to the new server
once the subscriptions are replayed, and an operation waits for the failover within its timeout, or with
waitForReconnect: false fails at once with Connection is not open. Both used to run on the new server directly,
the failover having run first.requestMany() or a JetStream fetchBatch() whose read fails because the connection is going (lost or being failed
over with waitForReconnect: false, a reconnect that gave up, or reconnect off) now returns what it has received
instead of throwing; it throws only when it has received nothing. Code that took that exception to mean that nothing
was delivered now gets the partial result.[bugfix] A requestMany() or a JetStream fetchBatch() whose read fails because the connection is going returns
the replies or the partial batch it has received, as requestMany() does when the connection closes and
fetchBatch() when the heartbeats stop, rather than throw and lose them: a fetched message the server counted as
delivered was redelivered only after the ack wait, or never on a consumer without acks. Such a read fails with
waitForReconnect: false once the connection is lost (#178) or is being failed over from a server in lame duck mode
(#191), with any setting when the reconnect gives up, and with reconnect off when the connection drops, the
configuration of symfony-nats-messenger, whose get() fetches. With nothing received, or for a failure that leaves
the connection open (a full queue, a handler's own), they still throw. Up to 2.20.0 a lame-duck failover ran inline
and the collection went on once it was over, though a fetchBatch() whose failover gave up threw at its next read all
the same.[bugfix] An operation whose own read brought a lame-duck INFO overran its deadline by the whole failover (#191).
The failover (#47) ran inline in the dispatch of the INFO, in the read's own fiber, and nothing bounded it: the
dials, the handshake, the subscription replay and any backoff between attempts. The read now starts the failover in a
fiber of its own and waits for it only within the operation's deadline and wake-up, as a read that meets a lost
connection does since 2.14.0 (#178): the operation times out at its deadline, or returns what a delivery brings
meanwhile, and the failover carries on, reports its failure through the error listener, as the inline failover does,
and announces the new connection when it is over. Only a read whose chunk holds bytes behind the INFO that fail to
parse still runs the failover inline, as it recovers the corrupt stream right after. The rest of the chunk the INFO
came in is still the leaving server's (#182), now from the moment the failover is started: its PING and INFO are
dropped, its -ERR is reported, and its PONG still completes the leaving connection's slot, so a flush() whose
PONG came behind the INFO succeeds, with waitForReconnect: false as well. Verified on nats-server 2.12 with two
servers, the second paused so that its dial hung until connectTimeoutMs (1 s), and the first put into lame duck mode
with SIGUSR2: a request() with a 300 ms timeout whose read brought the INFO returned after 3.29 s, once the
failover had reached the second server; it now times out after 0.30 s with the failover under way, and the second
server's connection is announced 3.17 s after the LameDuck event, as before.[bugfix] A lame-duck failover no longer fails over a connection that a reconnect opened while a DiscoveredServers
or LameDuck listener of the INFO was suspended (#191). It took the connection that was current once the listeners
had returned: a LameDuck listener that awaited a flush() on a connection that had just died let the flush's failed
write reconnect, and the failover then failed the new connection over as well, a second reconnect for nothing. It now
fails over only the connection the INFO came on, whether it runs inline (your own read, a serving loop's, the
heartbeat's) or in a fiber of its own (an operation's read).Minor release. Your own processIncoming() or readIncoming() now first continues the subscriptions whose delivery an earlier read stopped at a handler
Minor release. Your own processIncoming() or readIncoming() now first continues the subscriptions whose delivery an earlier read stopped at a handler that threw, before it reads the socket (#186). Before, the failing subscription's later messages stayed queued until the server sent anything, on an otherwise idle connection its next PING, two minutes away by default, and a disconnect() meanwhile discarded them.
Upgrading is recommended if your application runs its own processIncoming() or readIncoming() loop that catches a handler's exception and reads on. There are no API changes. Two behaviours change for such a loop: after a handler failure its next read runs the stopped subscription's handlers, or throws their next failure, at once, instead of blocking on an idle socket; and a loop whose connection drops now delivers that remainder, and throws its next failure, before it notices the drop, where with reconnect off those messages used to be discarded. A read whose cancellation has already fired still continues the remainder before it throws CancelledException. symfony-nats-messenger never calls these reads and works with this release unchanged.
processIncoming() or readIncoming() went straight to the socket, so on an otherwise idle connection those messages, and the subscription's next failure, waited for the server's next PING, two minutes away by default, and a disconnect() meanwhile discarded them. Your own read now continues the subscriptions a held handler failure stopped before it reads, in sid order, and then any that a read inside one of those handlers or another fiber's delivery stops meanwhile, with its own rules: a handler that throws there is thrown, one failure per read; otherwise the read reads as before, and its result still counts only what it took off the wire. Only what a handler failure stopped is continued. A subscription whose delivery is under way in another fiber is left to it, a disconnect() already under way when the read starts still discards what is queued, and a reconnect started while one of those handlers awaits is waited for before the new socket is read. A read already waiting on the socket is not woken when another fiber's read stops a subscription; that remainder waits for your next read.s2 and s3 1 ms after the one write that carried them behind a failing s1, where 2.19.0 left them waiting 3.0 s for the next publish.The full record is in the CHANGELOG.
processIncoming() or readIncoming(), now first continues the subscriptions whose delivery an
earlier read stopped at a handler that threw, before it reads the socket (#186): their later messages are
delivered with nothing new on the wire, and when one of those handlers throws too, the read throws its exception
without reading. A processIncoming() that used to block on an idle socket after a handler failure now runs those
handlers, or throws their next failure, at once. The read then goes on as before, and its result still counts only
what it read from the socket. It continues what any read stopped that way, an operation's read under
handlerErrorsFailOperations: true included; the reads of the library's operations, a serving loop, the
heartbeat, a reconnect and a drain are unchanged.CancelledException.[bugfix] The rest of a subscription whose handler threw in your own read waited in the client's memory until the
server sent anything (#186). Since 2.13.0 (#177) such a read delivers the other subscriptions' messages and leaves
the failing subscription's later messages queued for the next pass, but your next processIncoming() or
readIncoming() went straight to the socket and delivered them only once a chunk arrived: on an otherwise idle
connection the server's next PING, by default two minutes away, a disconnect() meanwhile discarding them, and
the subscription's next failure reached the application just as late. Your own read now delivers that remainder
before it reads, in sid order, and then any that a read made in one of those handlers, or another fiber's
delivery, stops meanwhile, with its own rules: a handler that throws there is thrown, one failure per read, and a
second failing subscription is reported. Otherwise the read goes on to read as before, and its result still counts
what it read. Only what a handler failure stopped is continued: the later subscriptions of a delivery held up in
another fiber's handler still wait for that delivery, unless a handler failure had already stopped one of them,
which is continued whole, in order, the messages that delivery brought for it included; a subscription whose
delivery is under way in another fiber is left to it; and a disconnect() already under way when the read starts
still discards what is queued, while a pass already running when a disconnect() begins goes on to the other
stopped subscriptions, as any pass under way does. When a handler that runs there awaits while the connection
drops, the read waits for the reconnect before it touches the new socket, as a serving loop's read does. Verified
on nats-server 2.12 with a catch-and-continue loop and one raw write carrying slow:s1, s2, s3 and jobs:j1:
s2 and s3 reached their handler 1 ms after the write, where on 2.19.0 they waited 3.0 s, until the next
publish.Minor release. A JetStream pull fetch, the pull consumer and Direct Get now learn at once that the server rejected their inbox subscription for the co
Minor release. A JetStream pull fetch, the pull consumer and Direct Get now learn at once that the server rejected their inbox subscription for the connection's subscription limit, whichever read meets the -ERR (#175). Before, when another read took the -ERR (in practice the heartbeat's while the SUB write was blocked), a fetch waited out its expiry and returned as an empty pull, and the pull consumer kept issuing pulls that ended at their deadlines.
Upgrading is recommended if your connections run near their subscription limit. There are no API changes for callers; one internal subscribe variant was added. On the wire, each JetStream inbox SUB (pull fetch, pull consumer, Direct Get batch) is now followed by a PING in the same write, and a reconnect replays it with one. symfony-nats-messenger 5.4.1's transport works with this release unchanged (its functional scenarios and examples pass); one of its unit tests counts PING frames as connection checks and sees the new fence PINGs, so it needs adjusting when the messenger moves to this version (symfony-nats-messenger #75).
fetchBatch(), fetchNext()), the pull consumer run and the batched Direct Get subscribe a reply inbox of their own; a maximum subscriptions exceeded for that SUB names no subject, so when another read met it (the heartbeat's while the SUB write was held up, an application's processIncoming() loop's) the operation never learnt of it. The inboxes now carry the shared reply inbox's rule: a PING behind the SUB confirms them, as does a delivery; a limit -ERR read before that, by whichever fiber, treats every unconfirmed inbox as rejected, and the fetch and the Direct Get batch fail at once with a ConnectionException naming the inbox and the limit, the pull consumer run through its fail-fast latch. An own read meeting the -ERR still fails with the server's error, as before. A reconnect replays a guarded inbox under the same rule, also one whose own SUB write failed. Several inboxes unconfirmed at once (two fetches, a fetch and the reply inbox) cannot be told apart and are all treated as rejected, as the reply inbox already is. Callers that catch only JetStreamException around a fetch or a Direct Get batch now see a ConnectionException at the limit, on a connection that stays open. New internal API: subscribeGuarded() and isSubscriptionLimitError() on NatsClient.max_subscriptions: 3 and AmpSocketTransport, an application loop holding the socket and the fetch's SUB write held up for 0.5 s, the fetch failed 0.501 s in, as soon as its write completed, where it reported an empty pull after 2.504 s before; the connection stayed open and a retry with a free slot got the message.The full record is in the CHANGELOG.
[bugfix] A JetStream pull fetch (fetchBatch(), fetchNext()), a pull consumer run (PullConsumerIterator::handle())
or a batched Direct Get (directGetBatch(), directGetLastForSubjects()) whose reply-inbox SUB the server rejected
for the connection's subscription limit learnt of it only when its own read met the -ERR 'maximum subscriptions exceeded' (#175). When another fiber's read took it - the heartbeat's while the SUB write was held up, an
application's processIncoming() loop's - the -ERR, which names no subject, was reported to the error listener and
nothing else happened: the fetch waited out its expiry plus a second and reported an empty pull (JetStreamException
408, No messages received within timeout), which callers treat as no messages; the Direct Get batch reported a
stalled batch after the same wait; the pull engine, whose rejection handler the connection called only for an -ERR
naming its subject, retired pull after pull at their deadlines. Measured through symfony-nats-messenger on 2.10.3: an
empty batch after 1.6 s, the connection open, the -ERR only on the listener. The inboxes now get the shared reply
inbox's rule, generalised (NatsConnection::subscribeGuarded(), @internal, exposed on NatsClient): a PING is
written behind the inbox's SUB in the same write, and the inbox counts as held by the server once that PING's
PONG or a delivery on it arrives; a limit -ERR read before that, by whichever fiber, drops the inbox, writes its
UNSUB (the -ERR may have been another SUB's, and the server then still holds the inbox) and tells the operation,
which fails at once: the fetch and the Direct Get batch with a ConnectionException naming the inbox and the limit
(JetStream pull fetch failed: the server may have rejected its reply-inbox subscription "_INBOX.JS.FETCH.<nuid>" because the connection is at its subscription limit (maximum subscriptions exceeded). A retry subscribes a new one.),
the pull engine through its fail-fast latch (#167), whose JetStreamException now says the limit when that is the
cause. A reconnect replays such an inbox with a PING behind it again, with the same consequence, also when the
inbox's own SUB write failed and the reconnect it started replays it: the subscribe then reports the rejection,
not a closed connection, and the replay writes the inbox's UNSUB. As for the shared reply inbox, several inboxes
unconfirmed at once - two fetches, a fetch and the reply inbox - cannot be told apart by the -ERR, so each is
treated as rejected and each operation fails; an operation whose own read meets the -ERR still fails with the
server's error, as before; a subscribe() of the application's beyond the limit behaves as before. A permissions
violation naming a fetch's or a Direct Get's inbox now fails the call at once as well, quoting it, where the call
waited out its deadline. markSubscriptionUnbounded() and onSubscriptionRejected() leave a sid that is no longer
registered alone, so a rejection read between the SUB write and those calls leaves nothing behind. Callers that
catch only JetStreamException around a fetch or a Direct Get batch, treating an empty result as routine, now see a
ConnectionException at the subscription limit, on a connection that stays open.
Verified on nats-server 2.12 with max_subscriptions: 3: with an application loop reading and the SUB write held
up for 0.5 s, the fetch failed as soon as the write completed (0.50 s after it was issued) and a retry with a free
slot got the stored message, where it reported an empty pull after 2.50 s.Minor release. Frames read behind a lame-duck INFO in the same chunk are no longer applied to the connection the failover opened (#182). Before, the o
Minor release. Frames read behind a lame-duck INFO in the same chunk are no longer applied to the connection the failover opened (#182). Before, the old server's PING was answered on the new connection, a stale INFO or PONG was applied to it, and an -ERR failed the read or dropped the replayed reply inbox although the failover had succeeded.
Upgrading is recommended if your clients fail over on lame-duck mode (reconnect enabled, more than one server in the pool). There are no API changes. symfony-nats-messenger 5.4.1 works with this release unchanged.
INFO, and the dispatch went on with the rest of the chunk afterwards: a PING got its PONG on the new connection; a stale INFO overwrote the new server's info and a second lame-duck INFO started a second failover; a PONG, or a late reply of the old server on the reply inbox, confirmed the replayed reply inbox before the new server had answered anything; an -ERR dropped the still unconfirmed inbox or fired a replayed subscription's rejection handler and failed the read; when the failover failed, or the LameDuck listener closed the connection itself, the PONG written on the closed transport failed the read with The connection is gone. The dispatch now records the connection it reads for and, once that connection is replaced or ended, treats the rest of the chunk as the old server's: PING, PONG and INFO are dropped, an -ERR is reported through the error listener as The server the connection left sent an error frame: ... and not applied, and messages are still queued and delivered, a reply on the reply inbox without counting as the new server's confirmation of it. README Reconnect Behavior gained an item on the lame-duck failover and on this rule.PONG on the second connection, the stale server id, the second dial, the inbox kept on a stale confirmation, the read failing with the stale -ERR or with the closed transport. Against two real nats-server instances put into lame-duck mode with the ldm signal, the failover and a request on the second server succeed; the server sends the lame-duck INFO alone in its chunk, so the coalesced orders are covered by the scripted transports.CountingCancellation for a request, CountingBuffer for a queue poll): the CPU bounds had failed the Mutation job under Xdebug coverage on the shared runners with the code correct, while a real spin stayed under them locally; the look counts are 0 to 6 on the current code and in the hundreds or thousands on spinning mutants. A process-wide count of event-loop registrations was tried as well and dropped, since reconnect attempts of clients that earlier tests leave behind register their 500 handshake polls in a burst. Dev-only.The full record is in the CHANGELOG.
[bugfix] A PING, PONG, INFO, -ERR or reply-inbox MSG read in the same chunk as a lame-duck INFO,
behind it, was handled on the connection the lame-duck failover had just opened (#182). The failover (#47) runs
inline in the dispatch of the INFO, and the dispatch then went on with the rest of the chunk as if nothing had
happened: the old server's PING was answered with a PONG written on the new connection; a stale INFO
overwrote the new server's info, and a second lame-duck INFO started a second failover, since the lame-duck flag
had been reset for the new connection; a PONG completed the new connection's oldest PONG slot - the fence behind
the replayed reply-inbox SUB - and so confirmed the replayed inbox before the new server had answered anything,
as a late reply of the old server on that inbox did; an -ERR was applied to the new connection (maximum subscriptions exceeded dropped the replayed, still unconfirmed inbox, a permissions violation naming a subject
fired the replayed subscription's rejection handler) and failed the read with Server sent error frame although
the failover had succeeded. The dispatch now checks before each frame whether the chunk's connection is gone,
replaced or ended, and handles the rest of the chunk for the connection it was read on: its messages are still
queued for their subscriptions, which the failover replayed, though a late reply on the request inbox no longer
counts as the new server's confirmation of the replayed inbox; its PING, PONG and INFO are dropped; its
-ERR is reported through the error listener (The server the connection left sent an error frame: ...) and
neither applied nor thrown. When the connection ends instead - the failover failed, or the LameDuck listener
closed the connection itself - the chunk's PING is not answered on the closed transport either: the read returns
what it read, and the next one fails with the closed connection, instead of the read failing with the PONG write's
error. Nothing changes without a failover (reconnect disabled, or a pool of one): the chunk is handled as before.
Found by the review of the read wake-up (#174, 2.12.0).[docs] OperationReadReconnectLifecycleTest::testAnOperationParkedOnTheReconnectItStartedDoesNotSpin no longer
bounds the CPU time of the second an operation spends parked on the reconnect its read started, which depended on
the environment: under Xdebug with coverage on a busy CI runner the second's own cost (three refused dials with
their exceptions and listener calls, GC) reached the 0.15 s bound, while the same seeds passed elsewhere, and a 1 ms
poll cost less than the bound on a fast machine. It counts how often the operation looks for its result instead,
which a spin would do about a thousand times in that second and a parked operation not at all: the poll's buffer is
swapped for a new CountingBuffer test double, which counts how often next() checks it, and the request gets a
CountingCancellation as its cancellation. A process-wide count of the callbacks the event loop registers in that
second was tried as well and dropped: the reconnect attempts of clients that earlier tests leave behind register
their 500 handshake polls in a burst. The socket-read and dial counts stay. Dev-only, no library change.[docs] ReadWakeupLifecycleTest::testTwoPollsOfOneQueueWithOneMessage no longer bounds the CPU time of the 2 s
that two polls of one queue spend on one message, the poll the delivery wakes finding nothing and waiting on to its
timeout, which depended on the environment the same way: in the Infection initial run for 2.17.0, under Xdebug with
coverage on the shared runner, the wait's own cost reached 0.82 s against the 0.5 s bound, while the four unit jobs
of the same run passed it. It counts how often the two polls check the queue's buffer instead, with the same
CountingBuffer in place of the buffer the polls share: six when no wait ends at once (one check each as the polls
start, two each when the message comes), and two per pause of a millisecond, close to a thousand or more over the
wait, for a woken poll whose next wait ended at once again and again, which the socket-read count does not see when
the read returns before it reads. The bound is 60; the other assertions stay. Dev-only, no library change.Minor release. PullConsumerIterator::stop() and drain() called from another fiber now end the pull engine's wait at once (#181). Before, a stop or dra
Minor release. PullConsumerIterator::stop() and drain() called from another fiber now end the pull engine's wait at once (#181). Before, a stop or drain requested while the engine waited on the socket for a pull, or sat out its idle backoff, took effect only when that wait ended: at the earliest pull deadline, up to the pull expiry plus a second, 31 s with the defaults.
Upgrading is recommended if you stop or drain a pull consumer from a signal handler's timer, a supervisor or another fiber. There are no API changes. symfony-nats-messenger 5.4.1 works with this release unchanged.
handle() run now gives the engine a wake-up per flag, which stop() and drain() fire; the engine composes a wake-up into its waits while its flag is still unset, so a latched flag never makes a later wait end early. stop() ends the run at once, and a stop() that lands while a pull of a generation is being written no longer writes the rest of the generation; drain() stops issuing new pulls at once and still lets the in-flight pulls complete, as before. The reviews found that Amp fires a DeferredCancellation as it is destructed, so a second handle() on the same iterator would have fired the previous run's wake-ups: the engine therefore decides by the wake-up itself, not by the flag, and such an orphaned run goes on as before this release instead of spinning. Start the next run only once the previous run's future has resolved; the runs share the stop and drain flags.handle() returned 1 ms after a stop() from a timer, where it returned at the server's 10 s pull expiry before.The full record is in the CHANGELOG.
[bugfix] A PullConsumerIterator::stop() or drain() from another fiber - a signal handler's timer, a supervisor -
while the pull engine waited on the socket for its in-flight pulls, or in its idle backoff, was seen only when that
wait ended on its own (#181): at the earliest pull's deadline, its expiry plus a second (4 s with the default 3 s
expiry, 31 s with a 30 s one), or at the end of the backoff, up to 500 ms. A call from inside the handler was
unaffected. Each handle() run now gives the engine two one-shot wake-ups, one per flag, which stop() and drain()
fire right after setting their flag; the engine's pump read and idle backoff wait with each wake-up while it has not
fired, so the wait ends at once and the flag is seen at the top of the loop. stop() ends the run at once, with the
pull inbox released as on every exit, and a stop() that lands while a pull of a generation is written ends the
generation there: no further pull is written for a run about to end. drain() wakes the engine once, so it stops
issuing pulls at once and, with nothing in flight, returns at once; the pulls in flight still complete, or reach
their deadline, and their messages are delivered first, as before. A fired wake-up is never composed into a later
wait, whatever fired it, so nothing spins: a latched drain does not end the reads that follow it; a run started
again gets fresh wake-ups, so a stop in an earlier run cannot end a wait of the next; and a run still active when
handle() is called again on the same iterator, its wake-ups replaced and fired by Amp as they are destructed, goes
on as before #181, waiting to its pulls' deadlines until the shared flags end it. Start the next run only once the
previous run's future has resolved: the runs share the stop/drain flags, so a handle() while a run is active
clears a stop() that run has not seen yet. The internal PullPipelineControl carries the wake-ups as
stopInterruption() and drainInterruption(), optional in its constructor.Minor release. A request() or requestMany() waiting on the shared reply inbox now fails at once when that inbox is dropped or rejected by an -ERR that
Minor release. A request() or requestMany() waiting on the shared reply inbox now fails at once when that inbox is dropped or rejected by an -ERR that another fiber's read brings (#180). Before, a request whose read was parked on the socket at that moment noticed the drop only with the server's next bytes or at its deadline.
Upgrading is recommended if your connections run near their subscription limit, or if requests run beside a processIncoming() loop. There are no API changes. symfony-nats-messenger 5.4.1 works with this release unchanged.
maximum subscriptions exceeded before the inbox is confirmed drops it, and a permissions violation naming it rejects it; both happen inline in the frame's dispatch. A request notices either at its next look, and a request whose read was parked on the socket when another fiber's read brought the -ERR had nothing to wake it: it waited for the server's next bytes or its deadline. Each request's wake-up is now registered with its waiter on the inbox, and dropping or rejecting the inbox fires them all, ending the request's read and also its wait for the read slot while another operation's read (a poll's, a flush's) holds the socket: the request fails at once with the documented error, or returns a reply delivered by then; requestMany() with replies collected returns them. A terminal close while a request waits for its reply now ends the request at its next look with Connection is not open, the message its next read would have given it; this is the exit of a request a rejection woke right before an error listener answered the -ERR with disconnect().max_subscriptions: 2 and AmpSocketTransport, the request failed as soon as the -ERR was read.The full record is in the CHANGELOG.
[bugfix] A request() or requestMany() whose read was parked on the socket when another fiber's read brought the
-ERR that drops or rejects the shared reply inbox - maximum subscriptions exceeded before the server was known to
hold the inbox, or a permissions violation naming it - noticed the drop only with the server's next bytes or at its
deadline (#180). The client drops the inbox inline in the dispatch of that -ERR, and since 2.12.0 a request's read is
woken by its own reply alone, so nothing ended the read; the shape arises when the other fiber's dispatch is held up
ahead of the -ERR, as it is while it awaits the write of the PONG for a server PING in the same chunk (socket
backpressure): the read slot is free by then, the request's read takes it, and the -ERR drops the inbox under it. A
request that looked while another operation's read - a poll's, a flush's - held the socket, and so waited at its own
wait for the read slot rather than in a read, noticed the drop only once that read ended. The connection now fires
every waiting request's wake-up when it drops or rejects the inbox, whichever fiber's read meets the -ERR, and the
wake-up ends every wait the request makes, its read and its wait for the read slot alike: the request looks again at
once, failing with the dropped-inbox error or the permissions error, returning a reply delivered by then, or, for a
requestMany() with replies collected, returning them. A terminal close while a request waits for its reply ends the
request at its next look with Connection is not open, as a read still waiting fails on its own: this is the exit of a
request a rejection woke right before an error listener answered the -ERR with disconnect(), which resets the
rejection latch; such a request would otherwise have looked every millisecond until its deadline and ended with a
timeout. Nothing else is woken: polls, fetches, consumers and your own reads are not involved.Minor release. An operation that reads the socket while it waits for a result of its own now takes what is already queued for its own subscription bef
Minor release. An operation that reads the socket while it waits for a result of its own now takes what is already queued for its own subscription before it reads (#179). A handler of yours that polls a SubscriptionQueue for a message that arrived in the same chunk, behind the message it handles, gets it at once; before, that message waited for the handler to return and the poll timed out. Likewise an operation whose message another fiber's read had queued behind a handler that awaits an HTTP or database call now gets it at once, rather than when that handler returns.
Upgrading is recommended if your handlers poll, fetch or consume beside the subscription they handle, or if your handlers await slow calls while other fibers poll, fetch or consume. There are no API changes; one note from 2.12.0 is reversed, below. symfony-nats-messenger 5.4.1 works with this release unchanged.
SubscriptionQueue poll, fetchBatch()/fetchNext(), directGetBatch(), the pull consumer and Key/Value keys()/history() take their subscription's queued messages first. The only reorder is of the operation's own subscription ahead of other subscriptions' messages queued with it; its messages go into a buffer the operation reads, not to a handler of yours, so no handler invocations between your subscriptions change order. The take covers what another fiber's read has already queued when the operation looks: a poll whose own read brings the chunk still runs the handler ahead of its message first, and while a reconnect is under way the operation waits for it first, within its timeout, then takes what is queued. A sid whose delivery is under way is left to that delivery; during a disconnect() the queued messages are the close's to discard; an own-subscription overflow under SlowConsumerPolicy::Error met by the take fails the operation; a poll concurrent with unsubscribe() may still return a message received before the UNSUB. request()/requestMany() and your own reads are unchanged.The full record is in the CHANGELOG.
SubscriptionQueue poll,
fetchBatch()/fetchNext(), directGetBatch(), the pull consumer, or Key/Value keys()/history() - now
takes what is already queued for its own subscription before it reads or waits for another fiber's read (#179).
This reverses the 2.12.0 note that "an operation gets its message once the in-order delivery reaches it, so a
handler ahead of it that outlasts the operation's deadline still makes it time out": an operation now returns at
once what an earlier or a concurrent read has already queued for it, even while a handler ahead of it, in another
fiber, is still running. In particular this is what lets a user handler poll a SubscriptionQueue of its own for
a message delivered in the same chunk: the handler's own message is ahead of the queue's in that chunk, the
queue's message is queued behind the handler's delivery, and the poll now takes it from inside the handler instead
of reading the socket and timing out. The reorder is only ever of the operation's own subscription ahead of
another subscription's message queued with it; order within a subscription, and between the other subscriptions,
is unchanged, and NATS guarantees order only within a subscription. request() and requestMany(), whose replies
share one inbox, are unchanged, and so are your own processIncoming() and readIncoming().unsubscribe() may still return a message the connection received before
the UNSUB went out.[bugfix] A handler that polled a SubscriptionQueue of its own for a message delivered in the same chunk waited
out its whole timeout, and the message reached the queue only once the handler returned (#179). The chunk held the
handler's own message ahead of the queue's; the in-order delivery was suspended inside the handler, so the queued
message was not delivered until the handler returned, and the poll read the socket with it already queued and
returned null (or [], or a fetch's expiry) at its deadline. The same shape without a handler - an operation
whose message was queued behind a delivery held up in another fiber's awaiting handler - got it, since 2.12.0, only
when that delivery reached it. An operation's read now takes what is already queued for its own subscription first,
before it reads or waits for another fiber's read, delivering that one subscription with the read's own rules (its
own overflow or failing handler still fails it) and returning so the operation looks again; the other
subscriptions' queued messages stay in order for the delivery under way. It is skipped while that subscription's own
delivery is under way further up the stack, and while a disconnect() is closing the connection.Minor release. An operation whose own read is the first to meet a lost connection now waits for the reconnect only within its own deadline, and return
Minor release. An operation whose own read is the first to meet a lost connection now waits for the reconnect only within its own deadline, and returns as soon as its result arrives during the outage (#178). Before, that read ran the whole reconnect itself: a poll with a 1 s timeout returned only once the server was back, 6.65 s into a 3.5 s outage, and a request whose reply a held-up delivery brought 50 ms after the drop returned it after the outage.
Upgrading is recommended if your application can lose its connection while a poll, request, fetch or pull consumer is the only reader. There are no API changes; the documented wait of such an operation changes, below. symfony-nats-messenger 5.4.1 works with this release unchanged.
request()/requestMany(), SubscriptionQueue polls, fetchBatch()/fetchNext(), directGetBatch(), the pull consumer, Key/Value keys()/history(), flush() and rtt() whose own read is the first to notice a lost connection now start the reconnect on its own fiber and wait for it as they wait for one another fiber started: within their timeout, and not at all with waitForReconnect: false, where they fail at once with Connection is not open. An operation that times out before the reconnect gives up no longer sees Reconnect attempts exhausted; the Closed event carries it. Your own processIncoming() and readIncoming(), a serving loop's read and the heartbeat still run the reconnect themselves and wait for all of it.flush(), rtt() and drainSubscription() fail earlier. A flush whose own read meets the drop fails with Connection lost before the server answered the PING as soon as the reconnect's first attempt clears the pong slots, rather than after the reconnect; a drainSubscription() whose flush does resolves then, its subscription removed, while the reconnect runs on.The full record is in the CHANGELOG.
request() or
requestMany(), a SubscriptionQueue poll, fetchBatch(), fetchNext() or directGetBatch(), a pull
consumer, Key/Value keys() or history(): every operation that reads for a result of its own - no longer waits
for the whole reconnect it starts: it waits within its own timeout, as it does for a reconnect another fiber
runs, and with waitForReconnect: false it fails at once with Connection is not open, the read's error as its
previous (#178). A flush(), rtt() or drainSubscription() whose own read is the first to notice fails with
Connection lost before the server answered the PING as soon as the reconnect's first attempt ends the old
connection's PONGs, or at once with Connection is not open when waiting is disabled, and
drainSubscription() then reports that and removes the subscription while the reconnect runs on. Code that
relied on such an operation returning only once the connection was back - polling in a loop and taking the next
successful result for the reconnect, say - now sees it time out or fail during the outage, with the reconnect
still under way; the connection events say when the connection is back, and with waiting enabled the next
operation waits for the reconnect within its own timeout, as before. A reconnect that gives up while nothing
waits for it any more is announced by its Closed event and the log: an operation that timed out before the
reconnect gave up does not see Reconnect attempts exhausted, and the exception of a drainSubscription() flush
that used to report it now reports the lost PONG. With waitForReconnect: false the reconnect such an
operation started advances only while something awaits on the event loop, as one the heartbeat starts always
did: a synchronous application that only ever issues operations failing on the spot has to keep awaiting
something for the connection to come back. Your own processIncoming() and readIncoming(), a serving loop's
read and the heartbeat still run the reconnect themselves and wait for all of it.[bugfix] An operation whose own read was the one on the socket when the connection dropped waited for the whole
reconnect, however long it took, before it returned (#178). readChunk()'s failed-read path ran the reconnect
inline in the operation's fiber, so neither the operation's deadline nor its wake-up (#174) could end the wait:
with the server down for 2 s and a 1 s deadline, SubscriptionQueue::next() and request() returned after 2 s,
although a delivery still under way had brought their result 50 ms into the outage, and a fetchBatch() or a
pull consumer's read did the same. On a real server, where a poll's read is often the only one on the socket, a
next() with a 1 s timeout returned only once the server was back. Such a read now starts the reconnect in a
fiber of its own, like a failed control write does, and waits for it within the operation's deadline and wake-up:
the operation returns what a delivery brings during the outage, or times out at its deadline, and the reconnect
carries on, announces the new connection once it is over and fails on its own terms when it gives up. With
waitForReconnect: false the operation fails at once with Connection is not open, the read's error as its
previous, as one whose control write noticed the loss does, instead of waiting for the reconnect first. A
reconnect another fiber already runs is still joined within the same wait, your own read still runs the reconnect
itself, and a listener called during the reconnect is still refused an operation that would wait on it.Minor release. A read that throws a subscription handler's exception now delivers the other subscriptions' messages behind it first (#177). Before, th
Minor release. A read that throws a subscription handler's exception now delivers the other subscriptions' messages behind it first (#177). Before, the exception ended the whole delivery, and everything the read had queued behind the failing message, for every subscription, waited for the next read that received bytes from the server. An operation in another fiber whose result was among those messages got no wake-up and waited for its deadline: on a real server next() returned nothing after 3 s with its message queued the whole time, and request() timed out. Both now get their result at once.
Upgrading is recommended if your subscription handlers can throw and you read the connection from more than one fiber, or poll, request or fetch beside a processIncoming() loop. There are no API changes; one documented behaviour of your own read changes, below. symfony-nats-messenger 5.4.1 works with this release unchanged.
processIncoming() and readIncoming() still throw a handler's exception, and still stop delivering to the subscription whose handler threw: its later messages stay queued, in order, for the next read that delivers, which throws again if that message's handler throws, so each failing message still surfaces as its own exception. The messages of the other subscriptions behind the failing one are now delivered, in subscription order, before the exception reaches you. Code that assumed nothing behind a throwing handler ran before it saw the exception sees those handlers run first, and a handler that awaits among them delays the exception.errorListener and logged at error level, as a second frame failure or a second overflow in one read already was. Register an errorListener or a logger to see it.handlerErrorsFailOperations: true. An operation's read that meets another subscription's throwing handler still fails the operation with that exception, as the option promises, but delivers the other subscriptions' messages behind it first. A service's request read behind a poisoned message is answered by that read.next() returned its message in 1 ms where it returned nothing at 2.98 s before, and request() its reply in 3 ms where it timed out at 3 s.The full record is in the CHANGELOG.
processIncoming() or readIncoming(), now delivers the messages it brought for the other
subscriptions before it throws a handler's exception; only the failing subscription's own later messages stay
queued, until the next read that receives anything (or a serving loop's read) continues with them: on an
otherwise idle connection that is the server's next PING, by default two minutes away. Under
handlerErrorsFailOperations: true an operation's read does the same before it fails the operation, and a
handler's CancelledException no longer ends the operation's wait when the operation's own result arrived in
the same read behind it: the result is delivered first and the operation completes with it. A second
subscription whose handler throws in the same read has its exception passed to the errorListener and logged
at error level, since one read throws one exception; it used to be thrown by the next read that received
bytes, so without an errorListener or a logger it is now seen nowhere. Code that relied on nothing behind a
throwing handler being delivered until it read again now sees those handlers run within the read that throws,
and a handler behind the failing one that awaits, or an errorListener that awaits while a second failure of
the same read is reported, delays the exception by as long.[bugfix] A message left queued by a handler that threw in another fiber's read waited for the next read
that received bytes (#177). The application's processIncoming() read a chunk holding a message whose handler
threw and, behind it, the message an operation waited for; the delivery stopped at the failing handler, and
nothing delivered the rest until the server sent more, so SubscriptionQueue::next(), fetchAll(),
request(), requestMany() and fetchBatch() waited out their whole deadline with their result queued the
whole time, and the pipelined pull consumer re-pulled at every expiry with its message queued the whole time;
on a real server, which pings only every two minutes, that is the whole deadline every time. A read that
throws a handler's exception now delivers everything else it queued first: the other subscriptions' messages,
in sid order, so the operation's wake-up fires as usual and it returns its result at once. The failing
subscription's later messages still stay queued, in order, for the next read that receives anything: your own
read then throws again if the next handler throws, so each failure of that subscription reaches you one read
at a time, and an operation's or a background read that delivers them reports the failure instead. A serving
loop's read, as Service::run() makes, still delivers what an earlier or a concurrent read has queued and not
reached: the later sids of a delivery that another fiber's handler holds up, awaiting, and the rest of a
subscription whose handler threw.Minor release. Every operation that reads the socket while it waits for a result of its own now gets that result as soon as it is delivered, by whiche
Minor release. Every operation that reads the socket while it waits for a result of its own now gets that result as soon as it is delivered, by whichever fiber's read (#174). A SubscriptionQueue poll looks at its queue before every read, and every such read now carries a wake-up: a delivery to the operation's subscription, its reply or its PONG ends the read wherever it waits, and the operation looks again. Before, a result that reached the operation while its read waited came back only with the server's next bytes or at the operation's deadline: the whole deadline on a real server, which pings only every two minutes.
Upgrading is recommended if any of your code reads the connection from more than one fiber at a time, such as a processIncoming() loop beside polls, requests, fetches or a pull consumer, or if your subscription handlers await HTTP or database calls. There are no API changes. Custom transports have one rule to check, below. symfony-nats-messenger 5.4.1 works with this release unchanged.
TransportInterface::readLine() must keep every byte it has not returned when its cancellation ends it, a partial frame included. The connection now cancels a read not only at a deadline but also to wake an operation whose result another fiber delivered meanwhile, and then reads on. The built-in transports do this, and the rule always held in practice, since every non-blocking poll and the heartbeat cancel their reads after a short bound. A transport that lost bytes on cancellation would now corrupt the stream in normal operation.flush() fails earlier after a drop. A flush(), rtt() or drain flush whose PING went out before the connection dropped fails with Connection lost before the server answered the PING as soon as the reconnect's first attempt clears the pong slots, rather than once the reconnect is over or at the flush's deadline.SubscriptionQueue::next() with a timeout, and fetchAll() with a limit and a timeout, read, found nothing, paused 1 ms and read again, and looked at the queue only right after their own read. A message that another fiber's read delivered during the pause stayed in the queue while the poll's next read waited on the socket until the timeout. They now look at the queue before every further read. next() has worked this way since 1.0.0, fetchAll() since 2.0.0.fetchAll() and a full queue. fetchAll() also takes such messages when they do not complete the call. Its next read used to find the queue as that delivery left it; when the delivery had filled the queue, the messages that read brought overflowed it, so messages were dropped, or under SlowConsumerPolicy::Error the call failed with a SlowConsumerException.SubscriptionQueue polls, request()/requestMany(), fetchBatch()/fetchNext(), directGetBatch(), the pull consumer and Key/Value keys()/history() got such a result only with the server's next bytes or at their deadline. It happened in three ways: the delivery was still under way when the read started, held up in another subscription's handler that awaits an HTTP or database call, or in the write of the PONG a server PING ahead of the message is owed; it came in the few event-loop hops between the operation's check and the start of its read; or it came with the reconnect the read waited for. On a real server the first case costs the whole deadline and the third about two seconds. An operation's read now ends, without reading, as soon as anything is delivered to its subscription, or its reply comes, wherever the read waits: on the socket, behind another fiber's read, or for a reconnect. The operation then looks again.flush(), rtt(), the drain flushes and the confirmation of the reply inbox end their read as soon as their PONG is in, also when the read that took it was held up before it reached the PONG.processIncoming() and readIncoming(), have no wake-up: they read until the server sends something or their cancellation fires.The full record is in the CHANGELOG.
TransportInterface::readLine() must keep every byte it has not returned when its
cancellation ends it, a partial frame included: the connection cancels a read not only at a deadline but also to
wake an operation whose result another fiber delivered meanwhile, and then reads on (#174). The built-in transports
do, and the rule always held in practice, since every non-blocking poll and the heartbeat cancel their reads after
a short bound. A transport that lost bytes on cancellation would now corrupt the stream in normal operation.[bugfix] An operation that reads the socket while it waits for a result of its own, a SubscriptionQueue poll,
fetchBatch()/fetchNext(), directGetBatch(), the pull consumer or Key/Value keys()/history(), got a result
that another fiber's read delivered only with the server's next bytes or at its deadline when that delivery reached
it while the operation's read was already waiting (#174). That happened in three ways: the delivery was still under
way when the read started, held up in the handler of another subscription that awaits an HTTP or database call, say,
or in the write of the PONG a server PING ahead of the message is owed; it came in the few event-loop hops between
the operation's check and the start of its read; or it came with the reconnect the read waited for. On a real server
the first costs the whole deadline, the server pinging only every two minutes, and the third about two seconds. An
operation's read now ends without reading as soon as anything is delivered to the operation's subscription,
wherever the read waits: on the socket, whose read it cancels, behind another fiber's read, or for a reconnect; the
operation then looks again. Application reads, processIncoming() and readIncoming(), are unchanged, and so is
the order of deliveries: an operation gets its message once the in-order delivery reaches it, so a handler ahead of
it that outlasts the operation's deadline still makes it time out.[bugfix] request() and requestMany() got a reply that another fiber's read delivered only with the server's
next bytes or at their timeout in the same three cases (#174). Their replies come on the one reply inbox every
request shares, so their read ends on their own reply instead, as the waiter that takes it fires: another request's
reply does not end it. A request cancelled right after its reply arrived throws the caller's own cancellation, with
its reason.[bugfix] flush(), rtt(), the flushes of drain() and drainSubscription() and the confirmation of the reply
inbox end their read as soon as their PONG is in, whichever fiber's read took it, also when that read's dispatch
had to wait before it reached the PONG, for the write of the PONG it owed the server for a PING ahead of it, say
(#174). They used to wait for the server's next bytes or their deadline. A flush whose PING went out before the
connection dropped fails with Connection lost before the server answered the PING as soon as the reconnect's
first attempt clears the pong slots, rather than once the reconnect is over or at the flush's deadline.[bugfix] An operation's read that waited for a reconnect looks again before it reads the new socket, whether or
not the reconnect delivered anything to it (#174). The pipelined pull consumer, which re-issues the pulls the old
server forgot once it sees the reconnect, used to read the new socket first and re-pull only at the lost pull's
deadline, its expiry plus a second.[bugfix] SubscriptionQueue::next() with a timeout, and fetchAll() with a limit and a timeout, returned a
message that another fiber's read delivered while they paused between reads (an application's
processIncoming() loop, say) only once the timeout ran out (#174). They started another read before they
looked at the queue, and that read waited on the socket, with the message already there, for the server's
next bytes or the whole timeout. They now take what arrived before they read again. next() had this shape
since 1.0.0, fetchAll() since 2.0.0.[bugfix] SubscriptionQueue::fetchAll() also takes what such a read delivered during its pause when that
does not complete the call, so its own next read has the queue's whole buffer (#174). When that delivery had
filled the queue, the messages the next read brought overflowed it: they or the earlier ones were dropped, or
under SlowConsumerPolicy::Error the call failed with a SlowConsumerException.[bugfix] The pipelined pull engine behind PullConsumerIterator::handle() handed over a batch that another
fiber's read delivered while the engine waited for the write of a pull request (an application's
processIncoming() loop, say, with the socket under backpressure) only at that pull's deadline, its expiry
plus 1 s, or with the server's next bytes. It looked at its oldest pull only before it issued pulls, and
then read with that pull's batch already there. It now looks again before it reads. The review of #174
found this; the engine had the same shape since it arrived in 2.7.0.[docs] The E2E job runs the unit suite once instead of twice, and the Docker fixtures do less background
work (#176). The job no longer runs the unit suite inside composer test:e2e: its coverage step runs it right
after, together with the integration suite, and the Unit + Static jobs run it on PHP 8.2 to 8.5. The skipped
pass took about 3 minutes and gave the timing flakes in #176 one more place to hit. scripts/run-tests-e2e.sh
gained SKIP_UNIT_TESTS for this; without it the local flow is unchanged. The compose servers no longer
run with debug and trace logging (-DV), which wrote every inbound payload through Docker's log pipeline
and was never read, and their healthchecks probe every 30 s instead of every 2 s (nothing reads the health
status; readiness comes from scripts/wait-for-nats-services.sh). That script now also waits for the
WebSocket server (nats-ws, monitoring port 18229), which it had left out. The unused workflow_dispatch
input integration-repeat-count is gone: no job read it. Dev-only, no library change.[docs] Timing-bound tests no longer depend on how fast the runner is or how late a timer fires (#176).
About 100 unit tests and 11 integration tests bounded elapsed time close to what they measured, or relied on
a timer firing in time, so a busy CI runner could fail them although the code was fine. Several did; the rest
were found before they could, by checking how much room each bound left. They now decide by the order
of events or by which of two timers fires first, measure from the event that matters (a dial is stopped by its
own refused attempt, through a new StopsDialOnRefusalConnector test double, and timed from that stop), count
idle sleeps instead of timing chunked reads (a new LoopTickCountingTransport
test double), or keep their bounds far from what the broken behavior takes. Each changed test still fails when
its bug is put back. The integration suite's recoverable client no longer gives a connection up after one late
PONG, which made a busy NATS container add a reconnect. Two WaitForReconnectTest tests that could no longer
fail since 2.10.0 were reworked so they can. Dev-only, no library change.Minor release. A subscription handler that throws no longer fails an unrelated operation (#173).
Minor release. A subscription handler that throws no longer fails an unrelated operation (#173).
Operations that read the socket while they wait for a result of their own deliver messages for every subscription on the connection. When one of those messages went to a handler that threw, the operation failed with that handler's exception, even when its own result had already arrived. The failure is now reported through the error listener, the rest of the read is delivered, and the operation completes, as another subscription's overflow has been under SlowConsumerPolicy::Error since 2.9.0. A new option, handlerErrorsFailOperations, brings back the old way operations failed.
This changes what operations throw, so read the upgrade notes first. symfony-nats-messenger 5.4.1 works with this release unchanged.
request(), flush(), rtt(), a JetStream call or a SubscriptionQueue poll now gets the result instead. With no errorListener and no logger the failure is visible nowhere: register an errorListener, or set handlerErrorsFailOperations: true to have operations fail as before.processIncoming() and readIncoming() still throw a handler's exception. The messages behind the one whose handler threw, for any subscription, stay queued until a read receives more from the server or a service's run() loop delivers them, so an operation in another fiber whose result is among them waits for that and can time out, as before. Catch inside the handler what it can handle.SubscriptionQueue's or a fetch's, never a handler you pass to subscribe(), to a push or ordered consumer, or to a watch.-ERR that fails a read but leaves the connection open (maximum subscriptions exceeded, Invalid Publish Subject, or a permissions violation other than for a publish to or a subscription to a subject) still fails the operation whose read meets it: it names no subscription, and it is often the answer to what the operation itself sent. Invalid Subject and a permissions violation for a publish to or a subscription to a subject still fail no read: they are only reported, as before.handlerErrorsFailOperations: true, an operation fails with another subscription's handler exception, as before this release, and a handler's CancelledException can again end an operation's wait early: the operation stops waiting or times out, and the exception is not reported. The fix to the delivery after a reconnect applies either way.NatsOptions::$handlerErrorsFailOperations (default false): set true to have operations fail with another subscription's handler exception, as before this release. Service::run() and the background reads report a handler's failure either way, and the delivery after a reconnect delivers the messages behind a failing handler either way.Operations and another subscription's handler failure (#173). An operation used to fail with the exception of whichever handler its read delivered to:
request() made inside a service endpoint failed with it, so the endpoint answered its requester with a HANDLER_ERROR reply and kept the other handler's message as its last_error;CancelledException made a request() take it for the end of its own wait: the request read on with its reply left undelivered, and timed out.This covers request(), requestMany() and what is built on them (JetStream publish, ackSync(), stream and consumer management, Key/Value and Object Store calls), flush(), rtt(), fetchBatch()/fetchNext(), directGetBatch(), pull consumers, Key/Value keys() and history(), SubscriptionQueue polling, and a request waiting for its reply inbox to be confirmed.
Delivery after a reconnect. It reported the first handler that threw, but stopped there and left the messages behind it queued. An operation whose own read ran the reconnect then waited for a result that had already arrived: a SubscriptionQueue poll returned nothing once its timeout ended, and a fetch discarded what was queued for it when it unsubscribed. It now delivers the rest as well, reporting any other handler that throws, whatever handlerErrorsFailOperations says.
The full record is in the CHANGELOG.
errorListener and no logger it is visible nowhere: register an errorListener, or set
handlerErrorsFailOperations: true to have operations fail as before. Code that caught another
subscription's handler exception from request(), flush(), rtt(), a JetStream call or a
SubscriptionQueue poll now gets the operation's result instead. processIncoming() and readIncoming()
still throw it.[feature] NatsOptions::$handlerErrorsFailOperations (default false): set true to have operations fail
as before the first change below: a subscription handler that throws fails whichever operation's read
delivered to it, and a handler's CancelledException can end an operation's wait early. Service::run()
and the background reads report it either way, and the second change below applies either way.[bugfix] An operation that reads the socket while it waits for a result of its own no longer fails with
another subscription's handler exception (#173). It used to throw the exception of whichever handler its
read delivered to, even when its own result had arrived: a request() made inside a service endpoint failed
with it, so the endpoint answered its requester with a HANDLER_ERROR reply and kept the other handler's
message as its last_error; a JetStream publish could fail after the server had stored the message, so a
retry stored it twice unless it carried the same message id within the stream's duplicate window; and the
messages behind the failing one waited for another read. A handler that threw
a CancelledException made a request() take it for the end of its own wait: the request read on with its
reply left undelivered and timed out. Now the failure is reported through the error listener, logged at
error level, the rest of the read is delivered, and the operation completes. This covers request(),
requestMany() and what is built on them (JetStream publish, ackSync(), stream and consumer management,
Key/Value and Object Store calls), flush(), rtt(), fetchBatch()/fetchNext(), directGetBatch(),
pull consumers (consumePipelined()), Key/Value keys() and history(), and SubscriptionQueue polling,
as well as a request waiting for its reply inbox to be confirmed. A handler of the operation's own
subscription that throws still fails it; that is only ever a subscription the library makes for the
operation, such as a SubscriptionQueue's or a fetch's. processIncoming() / readIncoming(), the reads an
application makes itself, still throw. An -ERR that fails a read but leaves the connection open, such as
maximum subscriptions exceeded, still fails the operation whose read meets it: it names no subscription,
and it is often the answer to what the operation itself sent. handlerErrorsFailOperations restores the old behavior. The README's new Handler Failures
section describes the whole behavior.[bugfix] The delivery after a reconnect stopped at the first handler that threw: it reported the failure
and left the messages behind it queued, for every subscription. An operation whose own read ran the
reconnect, such as a SubscriptionQueue poll or a fetch, then waited for the server's next bytes for a result
that had already arrived: a poll returned nothing once its timeout ended, and a fetch discarded what was
queued for it when it unsubscribed. The delivery now delivers the rest as well, reporting any other handler
that throws, whatever handlerErrorsFailOperations says (#173).Patch release. It fixes a regression from 2.10.1: an -ERR the server sends while keeping the connection open ended a healthy connection. Examples are
Patch release. It fixes a regression from 2.10.1: an -ERR the server sends while keeping the connection open ended a healthy connection. Examples are maximum subscriptions exceeded and a permissions violation for a publish with a reply subject. It also fixes the bugs found while reviewing that fix, in reconnect announcements, the request reply inbox, drains, services and INFO handling.
Upgrading is recommended for everyone on 2.10.1 or 2.10.2, which have the regression, and for anyone on 2.10.0 or earlier, since most of the other fixes are for long-standing bugs. symfony-nats-messenger 5.4.1 requires it. Read the upgrade notes first. Several fixes change when connection listeners are called and what the error listener receives.
-ERRs that keep the connection open. maximum subscriptions exceeded, Invalid Publish Subject and permissions violations other than ... for Publish to ... and ... for Subscription to ... no longer end the connection. The read that brought one fails with it, as in 2.10.0, and no Disconnected, Reconnected or Closed follows. The 2.10.1 note now covers only an -ERR the server closes the connection after, such as Stale Connection.
run() and the flushes of drain(), drainSubscription() and a service's drain() report such an -ERR to the error listener and carry on. Watch that listener, not Closed, for these errors.Drains past such an -ERR. drain() and drainSubscription() now read on past it to their PONG.
drain() waits out its budget, where it used to end at the -ERR.drainSubscription() runs the reconnect itself. With reconnect on, it returns only once that reconnect ends, past requestTimeoutMs if need be. 2.10.1 and 2.10.2 waited for that reconnect only within the budget.Reply inbox at the subscription limit. Once the server rejects the shared reply inbox of request()/requestMany() for the subscription limit, requests fail fast until a slot is free. Each attempt costs a round trip and nothing throttles them, so a caller that retries should pause between attempts.
Transport doubles. The write that subscribes the reply inbox now ends with a PING (SUB _INBOX.<inbox>.* <sid>\r\nPING\r\n). A test double must answer every PING, not only a write that is exactly PING\r\n.
When Reconnected is announced. A reconnect now announces the new connection once it is over, not from inside it.
disconnect() and drain() no longer wait for a listener that is still running.Reconnected call always finds the connection Open. A connection lost before the listener was told is not announced.Publish retry against a drain. A drain() that waited for a reconnect can now close the connection before a publish() is retried, if that publish's failed write ran the reconnect. This happens while the Reconnected listener, or a logger that suspends as it records the event, is still busy. That publish then fails and is not sent. An error from this library's own write is thrown as is. A built-in transport's raw stream error is wrapped in a TransportClosedException ("Transport is not connected").
Closed with reconnect off. The Closed event of a lost connection now carries the error that ended it and is logged at warning level. A failed read is therefore logged twice.
Services. A service's run() now reports what its reads used to swallow, to the error listener and at error level. That includes another subscription's handler that throws, once per failure. A handler's CancelledException no longer stops the service.
Header names. NatsHeaders::fromWireBlock() and fromWireBlockMulti() declare their keys as int|string, since a header named 1 comes back as an int key. Static analysis now reports two kinds of code:
strtolower($name) in a loop over the map; under strict types that call already threw a TypeError whenever a publisher sent such a header;SerializerInterface::decode().Cast such keys to string there. NatsHeaders::get() takes the map as it is.
First INFO. A first INFO that is valid JSON but not an object fails the connect, as broken JSON does, with INFO payload is not a JSON object. With reconnect off, connect() fails with that message. With reconnect on (the default), it first retries like any failed first dial, then fails with Reconnect attempts exhausted, carrying that error as its previous exception.
-ERR handling (2.10.1 regression). An -ERR the server keeps the connection open for fails the read again and leaves the connection open. A fatal -ERR read together with one still ends it.drain() and drainSubscription() no longer lose the messages behind an -ERR that keeps the connection open. That loss is long-standing and was in 2.10.0 as well.drain() waited out its whole budget (requestTimeoutMs, 10 s by default) against a healthy server when another fiber's read took its PONG. That happened with an application's processIncoming() loop, a service's run(), or a request() issued just before it in the same tick. flush(), rtt(), drainSubscription() and a service's drain() had a narrower race of the same kind, and rtt() then reported the wait as the round trip.drain() has unsubscribed its inbox.Reconnected listener, or from a Connected listener after a failed first connect(), could hang or wait out its timeout when the new connection was already gone, and the connection stayed Open on the dead socket. It now reconnects again.
drain() no longer waits for a slow listener.Closed of a drain() called from that listener now opens a new connection. It used to fail with Recovery was aborted before the connection opened.publish() whose failed write ran the reconnect is retried according to the state it then finds.run() reported nothing when another subscription's handler threw, left the rest of that read queued, and stopped silently on a handler's CancelledException. It now reports the failure and delivers the rest.
drain() reads on to its PONG.1 no longer breaks an endpoint with a TypeError.INFO. An async INFO that is valid JSON but not an object, such as INFO 1 or INFO [1], is reported as malformed and the last server info is kept. It used to fail the read, or to replace the server info with defaults.Closed event now says why (#172).The full record is in the CHANGELOG.
-ERR the server keeps the connection open for no longer ends the connection: maximum subscriptions exceeded, Invalid Publish Subject and any Permissions Violation other than ... for Publish to ... and
... for Subscription to ..., which the client still only reports. The read that brought it fails with it
at once, as in 2.10.0, and no Disconnected, Reconnected or Closed follows, so the 2.10.1 note now
holds only for an -ERR the server closes the connection after (Stale Connection, Authorization Violation, ...). The heartbeat, a reconnect's replay, a service's run() and the flushes of drain(),
drainSubscription() and a service's drain() report it to the error listener instead and carry on:
watch that listener, not Closed, for these errors.-ERR the flushes of drain() and drainSubscription() read on to their PONG, so a
server that then goes silent makes drain() wait out its budget, where it used to end at the -ERR. When
the server closes the connection after it instead, drainSubscription()'s flush runs the reconnect itself,
and with reconnect on the call returns only once that reconnect ends, past requestTimeoutMs if need be;
2.10.1 and 2.10.2 waited for the reconnect only within that budget.request() and requestMany() for the subscription
limit, requests fail fast until a slot is free, and the connection stays open: one already sent whose own
read meets the -ERR fails with it, any other with a ConnectionException saying request/reply failed: the server may have rejected the shared reply-inbox subscription .... Each request subscribes the inbox
again and is sent only once the server has taken it, so every attempt costs a round trip and nothing
throttles them: a caller that retries should pause between attempts.SUB _INBOX.<inbox>.* <sid>\r\nPING\r\n).
A transport double that answers only a write that is exactly PING\r\n, as one scripted for flush()
often does, leaves it unanswered, so the PONG it sends for the next flush(), rtt() or drain()
answers that PING instead, and the call times out. Such a double should answer every PING.Reconnected, or Connected when it completed a failed first
connect()) once it is over. Operations that waited for it, a joined connect() and a drain()
included, go on without waiting for the listener, and disconnect() and drain() no longer wait for one
still running: once they have closed the connection, what it calls fails with Connection is not open. An
operation the listener calls that finds the new connection gone reconnects again: the listener hears
Disconnected and Reconnected (or Closed) while that call is still running, the Reconnected
delivered from the event loop, so handlers can get the new connection's messages first. Do not hold a lock
across an await on the same connection in a listener: a call nested in it may need that lock.drain() that waited for a reconnect can therefore close the connection before a publish() whose
failed write ran that reconnect is retried, while the listener, or a logger that suspends as it records
the Reconnected, is still busy. That publish then fails with the error of its write and is not sent,
where the retry used to come first; a built-in transport's raw stream error is wrapped in a
TransportClosedException.Reconnected call always
finds the connection Open. One closed, being closed, replaced or lost before the listener was told it
opened is not announced, and when it was lost, neither is its loss, though a Closed still is. The logger
still records every transition.Closed event of a lost connection now carries the error that ended it and is
logged at warning level instead of info, so a failed read is logged twice: as the read's error and with
the Closed event.run() now reports what its reads used to swallow, to the error listener and at error level:
another subscription's handler that throws, once per failure (a handler failing on every message is logged
for every message), and an -ERR the server keeps the connection open for. A handler's
CancelledException no longer stops the service: only run()'s own timeout or cancellation does, or a
connection closed for good. A handler awaiting the cancellation passed to run() reports its
CancelledException when that cancellation stops the service.NatsHeaders::fromWireBlock() and fromWireBlockMulti() declare their keys as int|string, since a header
name that is a decimal integer, such as 1, comes back as an int key. Static analysis now reports code
that hands such a key to a function taking a string, and code that passes the whole map where string keys
are declared, such as Symfony Messenger's SerializerInterface::decode(): cast such keys to string there.
NatsHeaders::get() takes the map as it is.INFO that is valid JSON but not an object (INFO 1, INFO [1]) fails the connect as broken JSON
does, saying INFO payload is not a JSON object.[bugfix] Since 2.10.1 an -ERR the server keeps the connection open for ended the connection, unless the
client only reports it, as it does Invalid Subject, Permissions Violation for Publish to ... and ... for Subscription to .... So maximum subscriptions exceeded, Invalid Publish Subject and any other
Permissions Violation, such as ... for Publish with Reply of ..., closed a healthy connection, or with
reconnect on reconnected it; after a rejected SUB, every reconnect attempt replayed that SUB and failed
again, until the reconnect gave up and closed the connection. Such an -ERR fails the read that brought
it, as before 2.10.1, and leaves the connection open (when an account's subscription limit is lowered
below what a client holds, the server closes the connection after maximum subscriptions exceeded anyway,
and the EOF ends it). Only an -ERR the server closes the connection after (Stale Connection,
Authorization Violation, Maximum Payload Violation, ...) and a PONG the socket would not take end the
connection, and nothing else a frame raises does. Such a failure also outranks any other met in the same
read, so a fatal -ERR read together with a rejected SUB's still ends the connection.[bugfix] A reconnect whose replayed SUB the server rejected for exceeding the maximum subscriptions
failed, and so did every attempt after it, until the reconnect gave up and closed the connection. Any
failure of the replay that does not end the connection is now reported to the error listener instead, and
the reconnect completes; one that ends it still fails the attempt. A rejection read ahead of a line that
does not parse is reported as well, though that attempt fails on the parse error. A rejection that arrives
after the replay's short poll fails the read that brings it instead, and the connection stays open.[bugfix] The flushes of drain() and drainSubscription() ended at an -ERR the server keeps the
connection open for, and the messages the server sent behind it, up to the PONG, were lost without a
count: drain() closed the socket with them unread and reported only the -ERR, and drainSubscription()
removed the subscription, so a later read dropped them as an unknown sid's. A long-standing bug, in 2.10.0
as well; on 2.10.1 and 2.10.2 drainSubscription() also ended the connection, since such an -ERR did
there. Both flushes now report such an -ERR to the error listener and read on to their PONG within the
same budget, also when a line that does not parse follows the -ERR in the same read. A fatal -ERR and a
PONG the socket would not take still end the flush at once, and flush() and rtt() still fail with
such an -ERR.[bugfix] A drain() waited out its whole budget (requestTimeoutMs, 10 s by default) against a healthy
server while another fiber read the connection, such as an application's processIncoming() loop or a
service's run(): that fiber's read took the PONG of the drain's flush before the flush first read, and
the flush then waited for that fiber's next read, on a socket with nothing more to come. Every flush - that
of drain(), flush(), rtt(), drainSubscription() or a service's drain() - also had a narrower
window: another fiber's read could take the PONG just before the flush's own read started, which then
waited on the idle socket until the budget ran out, and the call returned only then, rtt() reporting that
wait as the round trip. A drain() issued right after a request(), in the same tick, met it against a
server that answered at once. A flush now looks for its PONG before every read, and its read looks again
before it takes the socket.[bugfix] The shared reply inbox of request() and requestMany() was recorded only once the write of
its SUB had returned. When that write found the socket dead, the reconnect it started replayed the SUB,
and a permissions rejection read during that replay missed the latch of 2.7.1 (#167): the request and
every later one waited out their timeouts instead of failing at once with the permissions error. And when
a terminal close came while the write was under way and the write completed all the same (a narrow race,
since the shipped transports fail such a write when the socket closes), the closed connection's inbox
stayed recorded: after a new connect() every request was sent with a reply subject nobody held there
and timed out. The inbox is now recorded before its SUB is written, so whichever read meets the server's
answer finds it. A request joins a set-up still under way instead of trusting the recorded inbox, and a
set-up whose write fails without the connection coming back in time is rolled back. A terminal close
during the set-up fails the request without sending it (with Connection was closed while the reply inbox was being set up when the write completed anyway), and a request after a new connect() neither waits
for a set-up left from the closed connection nor reuses its inbox.[bugfix] The shared reply inbox of request() and requestMany() stayed dead once the server rejected
its SUB with maximum subscriptions exceeded, an -ERR that names no subject and leaves the connection
open. In 2.10.0 the request that met the rejection failed with it, and every later one was sent with a
reply subject nobody held and waited out its whole timeout (requestMany() returned nothing), even after
a slot freed up, until the connection closed for good. 2.10.1 and 2.10.2 ended the connection on that
-ERR instead, and with reconnect on every attempt replayed the inbox's SUB into the same limit until the
reconnect gave up. The SUB now goes out with a PING right behind it, and the inbox counts as confirmed
once that PING's PONG arrives, which the server sends only after its answer to the SUB, or once a reply
arrives on it. That -ERR arriving before then drops the inbox: the requests waiting on it fail at once,
a requestMany() that has collected replies returns them, and the next request subscribes a new inbox,
in the same write as an UNSUB of the dropped one. Until a new inbox is confirmed, a request waits for that
before it is sent, so while the limit holds requests fail fast without reaching the responder, and once a
slot is free they work again, with no reconnect. A reconnect whose replay of the inbox is rejected works
the same way, and a confirmed inbox stays in place when another subscription is rejected: the requests in
flight on it are not failed with the dropped-inbox error, though one whose own read brings that -ERR
fails with it, as any read does. Another subscription's -ERR that arrives while the inbox's SUB still
waits behind earlier writes, or before its PONG, drops an inbox the server takes after all; the next
request's UNSUB gives its slot back.[bugfix] A request whose reply inbox was still being subscribed when a drain() began was sent all the
same, after the drain's UNSUB of that inbox: the responder ran it, though no reply could come back, and the
request failed with Connection is not open once the drain closed the connection. A drain() that begins
while a request subscribes the inbox, or waits for the server to take it, now fails the request with
Connection is not open without sending it, as one issued during the drain does.[bugfix] An async INFO whose payload is valid JSON but not an object was not treated as malformed.
INFO 1 failed the read with a TypeError, which 2.10.1 and 2.10.2 also took for a connection failure
and ended the connection with, and INFO [1] replaced the server info with defaults (no server id, no
headers support), after which every publish with headers was refused. Such an INFO is now reported to
the error listener as malformed, as broken JSON is, and the last server info is kept. A first INFO like
that fails the connect as broken JSON does, saying INFO payload is not a JSON object, where a number
failed it with a ConnectionException wrapping a TypeError and an array connected with the default info.[bugfix] An operation called from a Reconnected listener - or from the Connected listener of a failed
initial connect that a reconnect completed - that found the new connection gone already joined the
reconnect that had announced it, which was still waiting for the listener to return. A read meeting EOF or
a fatal -ERR, a flush() or a subscribe() waited out its timeout; a publish(), a request(), a
lame-duck failover and a read without a cancellation never returned. The connection then stayed Open on the
dead socket, and a failure another fiber or the heartbeat noticed while the listener ran was lost the same
way, the heartbeat stopping for good. The new connection is now announced once the reconnect is over, as a
direct connect already was: such an operation reconnects again, as it would anywhere else, and an
announcement made while another Connected or Reconnected listener call runs is delivered from the
event loop, so that the calls do not nest one level deeper with every connection a server drops. A
publish() whose failed write ran the reconnect is retried by the state it then finds: buffered behind a
reconnect or lame-duck failover the listener left in flight (it used to fail, its frame lost, or go to the
connection the server was about to close); written to the connection a drain() is still flushing; or,
when the connection was closed meanwhile, failing with the error of its write, a built-in transport's raw
stream error wrapped in a TransportClosedException ("Transport is not connected").[bugfix] A drain() that waited for a reconnect also waited for a slow Reconnected listener, past its
budget. A supervisor that reconnects on the Closed of a drain() called from that listener was refused
with Recovery was aborted before the connection opened, the reconnect still waiting for the listener; it
now opens a new connection, as documented. And a close the listener makes takes over what the reconnect
read, even while the close is still under way as the listener returns: drain() delivers it and
disconnect() discards it, where it used to be delivered during the close. A read that receives anything
during the close still delivers it with what it received, as any read does.[bugfix] A connect() that joined a failed first dial waited for the Connected listener of the
reconnect that completed the dial, so a listener waiting for that connect() waited out its own timeout;
it now resumes when the listener starts, as on a direct connect. When that listener lets the new
connection die and returns with the next reconnect in flight, the connect() that dialled now fails with
Connect was aborted before the connection opened while those that joined it succeed, as on a direct
connect, where both used to report success on the dead socket.[bugfix] With reconnect off, a connection the heartbeat gave up on (unanswered PINGs, a failed PING
write, the socket closing or breaking during its read) closed without saying why: Reconnect is disabled
and its cause (#172) reached only an operation that joined the recovery. The Closed event now carries
the cause, so that the connection listener and the log learn it. The reason for unanswered PINGs reads
"the last PING" when maxPingsOut is 1, and says that the heartbeat allows no unanswered PING when it is 0.[bugfix] A service's run() swallowed the exception of a handler that threw while its loop read, another
subscription's on the same connection: nothing reported it, the loop backed off 20 ms, and the messages that
read brought behind the failing one, for any subscription, stayed queued until the server sent something
else. A request read behind it waited up to the heartbeat interval, and was lost when the service stopped
first, and a subscription failing on two or more messages per read starved the service's endpoints for
good. A handler that threw a CancelledException stopped the service, silently. Such a failure is now
reported to the error listener, the rest of the read is delivered, and the loop reads on without backing
off, as drain() treats a throwing handler. An -ERR the server keeps the connection open for is reported
the same way, also one read ahead of a line that does not parse; the loop used to swallow it too. The
loop's read also delivers what another read left queued - another fiber's that stopped at a throwing
handler, or the delivery after a reconnect - instead of leaving it for the server's next bytes, except
while a disconnect() is closing the connection, which discards it. A read that receives anything during
the close, the loop's or any other, still delivers it with what it received. A known limitation remains:
the read of an operation, such as a request() an endpoint handler makes, still fails with another
subscription's handler exception, and the endpoint then answers its requester with a HANDLER_ERROR reply.[bugfix] A service's drain() swallowed what its flush met, such as another subscription's handler that
threw, and returned before the PONG that confirms the server has processed the UNSUBs. The flush now
reports it to the error listener and reads on to that PONG.[bugfix] A service endpoint's request validator that threw escaped the endpoint into the read that
delivered the request: the requester got no reply, the endpoint counted no error, and the read failed with
the exception, which a service's run() swallowed. Such a validator is now answered like a handler that
throws: a HANDLER_ERROR reply without the exception's text, an error counted with the text as
last_error, and request_error and request_end for the observers. A ServiceError it throws is sent as
chosen, as a handler's is.[bugfix] A request header whose name is a decimal integer, such as 1, which any requester can send,
made a service endpoint throw a TypeError into the read that delivered the request, and the request went
unanswered, whenever the endpoint had an observer or its handler threw: NatsHeaders::fromWireBlock()
returns such a name as an int key, as PHP stores such array keys, and the endpoint lowercased it under
strict types. The endpoint now answers such a request like any other. fromWireBlock() and
fromWireBlockMulti() now declare their keys as int|string, so static analysis reports such a call in
your code too.Patch release. One fix: with reconnect off, Reconnect is disabled now says why the connection ended.
Patch release. One fix: with reconnect off, Reconnect is disabled now says why the connection ended.
Upgrading is recommended for anyone who runs with reconnect off, such as symfony-nats-messenger, which manages its own connections. Without it, the error that ended the connection was lost.
Reconnect is disabled now carries the error that ended the connection as its previous exception (getPrevious()). Its message and code are unchanged.With reconnect off, Reconnect is disabled did not say why the connection ended (#172). The operator saw what reads like a configuration problem and had nothing to go on. The error that ended the connection is now chained as its previous exception:
ProtocolException of a stream that could not be parsed;-ERR such as Stale Connection;The server did not answer the last 2 PINGs, its PING write failing, or the socket closing or breaking during its read.That holds for the operation that failed and for any operation that joined the recovery. The message is unchanged, so code that matches it keeps working.
The gates are PHPStan level 8, 2352 unit tests (with data sets), 149 live integration tests, 48 Behat scenarios, and every runnable example executed against a live server. Combined statement coverage is 99.23% (97% floor enforced in CI). Infection covered MSI is 94% over 7367 mutants (90% floor enforced in CI). The 10 new tests all fail on the old code. Mutation testing on the changed lines killed 24 of 26 mutants, and one more errored. The one survivor removes a catch block in the parse-failure path that this release does not change. The full record is in the CHANGELOG.
Patch release. One fix for what happens when the server closes a connection with a fatal -ERR, found while fixing symfony-nats-messenger's lost-connec
Patch release. One fix for what happens when the server closes a connection with a fatal -ERR, found while fixing symfony-nats-messenger's lost-connection bug: the operation that reads the error is now the only one to fail, instead of leaving the connection Open for the next operation to fail on as well.
Upgrading is recommended for anyone whose process can sit idle between operations - a PHP web app in worker mode between requests, a daemon between batches - since a server drops a client that stops answering its pings with -ERR 'Stale Connection'.
-ERR from the server, the connection is no longer left Open: with reconnect off it is Closed by the time the read that met the -ERR throws, and with reconnect on that read first waits for the reconnect within its own timeout (a processIncoming() without a cancellation waits for the whole reconnect, as it already did after a failed read). The read still throws the same ConnectionException (Server sent error frame: ...). The same holds for a server PING whose PONG the socket would not take; that read still throws the socket's own error.-ERR from the server - the error it sends right before it closes the connection, such as Stale Connection for a client that stopped answering its pings - failed the operation that read it but left the connection Open (#171). The next operation then wrote into the socket the server had closed and failed as well: with reconnect off with Reconnect is disabled, with reconnect on only after waiting out its whole timeout, since its request had gone to the dead socket. Such a frame, and a PONG the socket would not take, now ends the connection like a failed read: it reconnects, or with reconnect off closes for good, and the read that met it fails with the server's error once the connection is Closed or, with reconnect on, once the reconnect is done or the read's own timeout runs out (not waiting at all with waitForReconnect: false). The heartbeat's read does the same. A full subscription queue still does not end the connection.PHPStan level 8, 2342 unit tests (with data sets), 149 live integration tests, 48 Behat scenarios and every runnable example executed against a live server, 99.23% combined statement coverage (97% floor enforced in CI) and 94% Infection covered MSI over 7367 mutants (90% floor enforced in CI). Every part of the fix has a test that fails when that part alone is reverted, and mutation testing on the changed lines killed all 14 mutants (one by a test added for it). The fix was also verified through symfony-nats-messenger against nats-server 2.12 configured to drop idle clients. The full record is in the CHANGELOG.
-ERR from the server, the connection is no longer left Open: with reconnect off it is
Closed by the time the read that met the -ERR throws, and with reconnect on that read first waits for
the reconnect within its own timeout (a processIncoming() without a cancellation waits for the whole
reconnect, as it already did after a failed read). The read still throws the same
ConnectionException (Server sent error frame: ...). The same holds for a server PING whose PONG the
socket would not take; that read still throws the socket's own error.[bugfix] A fatal -ERR from the server - the error it sends right before it closes the connection,
such as Stale Connection for a client that stopped answering its pings - failed the operation that
read it but left the connection Open (#171). The next operation then wrote into the socket the server had
closed and failed as well: with reconnect off with Reconnect is disabled, with reconnect on only after
waiting out its whole timeout, since its request had gone to the dead socket. A synchronous application
that sat idle for a few minutes - between requests in a worker-mode runtime, say - met this on its next
two calls. Such a frame, and a PONG the socket would not take, now ends the connection like a failed
read: it reconnects, or with reconnect off closes for good, and the read that met it fails with the
server's error once the connection is Closed or, with reconnect on, once the reconnect is done or the
read's own timeout runs out (not waiting at all with waitForReconnect: false). The heartbeat's read
does the same. A full subscription queue still does not end the connection.Minor release. Two fixes for what happens when a socket dies or a close interrupts a reconnect, both found while reviewing symfony-nats-messenger's re
Minor release. Two fixes for what happens when a socket dies or a close interrupts a reconnect, both found while reviewing symfony-nats-messenger's reconnect support: a subscribe(), flush() or rtt() whose write finds the socket dead now reconnects instead of throwing the socket's raw error, and a close now stops a reconnect's dial and waits for what it stopped, so a connect() after it dials afresh.
Upgrading is recommended for anyone running with reconnects on (the default), anyone consuming JetStream with fetches (a fetch subscribes its inbox first, so it was the most common victim of the first bug), and anyone who closes and reopens a connection. Read the upgrade notes first: some operations throw different exceptions after a dead socket.
subscribe(), flush() or rtt() whose write finds the socket dead no longer throws the socket's own error (for example Amp\ByteStream\StreamException): it starts the reconnect and waits for it within its own timeout, as it waits for a reconnect already in flight. subscribe() then returns; flush() and rtt() throw a ConnectionException (Connection lost before the server answered the PING). A wait that runs out throws a TimeoutException, and with reconnect off they throw a ConnectionException (Reconnect is disabled). Code that caught the transport's exception there should catch those instead.unsubscribe() no longer throws when its write finds the socket dead.disconnect() and drain() now return only once the reconnect or connect() they stopped has ended. With the built-in transports that is at once; a custom transport that implements only TransportInterface can hold them up to connectTimeoutMs. Implement CancellableDialTransportInterface to let a close stop its dial.[feature] CancellableDialTransportInterface, a transport whose dial can be stopped: its connect() takes a cancellation that fires when the application closes the connection while a connect or a reconnect is dialling. Both built-in transports implement it.subscribe(), flush() or rtt() whose write found the socket dead failed with the socket's raw error and left the connection Open on it, so every operation that wrote a control frame failed the same way until the heartbeat noticed. After a server restart the application had not seen yet, a JetStream fetch threw "Broken pipe", and a queue consumer built on it exited. Such a write is now a connection failure, as a failed publish write already was.disconnect() or drain() during a reconnect that was dialling left that reconnect running after they returned: they cut its backoff short but not its dial, which with Amp's retry pauses takes some 6 s against a refused port. A connect() issued after the close failed with Recovery was aborted before the connection opened, and in a synchronous application, which never gave the reconnect the event-loop time to end, every later connect() did. A close now stops the dial, Amp's retry pauses included, and waits for what it stopped before it returns. A connect() racing the close still fails at once.disconnect(), which discards them, or beside drain()'s own delivery. It now leaves them to the close.PHPStan level 8, 2332 unit tests (with data sets), 149 live integration tests, 48 Behat scenarios and 45 runnable examples executed against a live server, 99.11% unit and 99.23% combined statement coverage (95% and 97% floors enforced in CI) and 94.2% Infection covered MSI over 7353 mutants (90% floor enforced in CI). Every fix has a test that fails when the fix alone is reverted, and mutation testing on the changed lines left only equivalent mutants alive (listed in the message of the commit that pins the rest). Both fixes were also verified through symfony-nats-messenger against a live server. The full record is in the CHANGELOG.
subscribe(), flush() or rtt() whose write finds the socket dead no longer throws the socket's own
error (for example Amp\ByteStream\StreamException): it starts the reconnect and waits for it within
its own timeout, as it waits for a reconnect already in flight. subscribe() then returns; flush()
and rtt() throw a ConnectionException (Connection lost before the server answered the PING). A wait
that runs out throws a TimeoutException, and with reconnect off they throw a ConnectionException
(Reconnect is disabled). Code that caught the transport's exception there should catch those instead.unsubscribe() no longer throws when its write finds the socket dead.disconnect() and drain() now return only once the reconnect or connect() they stopped has ended.
With the built-in transports that is at once; a custom transport that implements only
TransportInterface can hold them up to connectTimeoutMs. Implement CancellableDialTransportInterface
to let a close stop its dial.[feature] CancellableDialTransportInterface, a transport whose dial can be stopped: its connect()
takes a cancellation that fires when the application closes the connection while a connect or a
reconnect is dialling. Both built-in transports implement it. A custom transport that implements only
TransportInterface works as before, and a close waits for its dial to end, up to connectTimeoutMs.[bugfix] A subscribe(), flush() or rtt() whose write found the socket dead failed with the
socket's own error (for example Amp\ByteStream\StreamException "Broken pipe") and left the connection
Open on that socket, so every operation that wrote a control frame failed the same way until the
heartbeat noticed. A JetStream fetch subscribes its inbox first: after a server restart the application
had not seen yet, a fetch threw "Broken pipe", and a consumer built on it exited. Such a write is now a
connection failure, as a failed publish write already was. The connection reconnects, and the operation
waits for it within its own timeout, the way it waits for a reconnect already in flight; a
subscribe() then runs on the new connection, while a flush() or rtt() fails anyway, with
Connection lost before the server answered the PING, since what it was to confirm went to the dead
connection. With reconnect off the connection closes for good and the operation fails with
Reconnect is disabled; with waitForReconnect: false it fails at once with Connection is not open.
unsubscribe() no longer throws on a dead socket either - the server dropped the subscription with the
connection - as it already did not on a connection that is not open, and the next operation that needs
the socket reconnects.
[bugfix] disconnect() or drain() during a reconnect that was dialling left that reconnect running
after they returned: they cut its backoff short but not its dial, which with Amp's retry pauses takes
some 6 s against a refused port. A connect() issued after the close met the stopped reconnect still
winding down and failed with Recovery was aborted before the connection opened. In a synchronous
application the reconnect never got the event-loop time to end, so every later connect() failed that
way and the connection could not be reopened until the process restarted (found while reviewing
symfony-nats-messenger PR #45, where a transport's close() then broke every later dispatch). A close
now stops the dial - Amp's retry pauses included, for a transport that implements
CancellableDialTransportInterface - and waits, bounded by connectTimeoutMs, for the reconnect or
connect() it stopped to end before it returns, so a connect() issued after it dials afresh. A
connect() racing the close still fails at once. A reconnect attempt that finds a close came while it
was closing the previous socket no longer dials.
[bugfix] A reconnect that a close stopped delivered the messages queued on the connection on its way
out: after disconnect(), which discards them, or beside drain()'s own delivery and past the rules it
keeps. It now leaves them to the close.
Minor release. Operations now wait for a reconnect that is already in flight instead of failing at once, which also lets a synchronous worker drive a
Minor release. Operations now wait for a reconnect that is already in flight instead of failing at once, which also lets a synchronous worker drive a reconnect the heartbeat started. Plus the outcome of several review rounds over drain(), drainSubscription(), SlowConsumerPolicy::Error and the read path, most of them cases where a message could be lost, a reconnect could stall, or a process could freeze.
Upgrading is recommended for anyone running with reconnects on (the default), anyone using drain() or drainSubscription(), SlowConsumerPolicy::Error, or a processIncoming() loop next to other fibers. Read the upgrade notes first: an operation that waits for a reconnect fails with a different exception when the wait runs out.
TimeoutException (for example Subscribe to "orders" timed out waiting for the connection to be re-established), where it used to fail at once with Connection is not open. TimeoutException is not a ConnectionException, so a catch (ConnectionException) around subscribe(), flush(), rtt(), request(), requestWithHeaders() or requestMany() no longer catches that case.processIncoming() and readIncoming() without a Cancellation now wait for a reconnect in flight to end, and for another fiber's socket read to end, instead of returning or failing at once. Pass a Cancellation to bound them.SubscriptionQueue::fetch(), and next() without a timeout, return null during a reconnect instead of throwing; next() and fetchAll() with a timeout wait for the reconnect within it.drain() now emits ConnectionEvent::Closed, so a listener that reconnects on every Closed now also reconnects after a graceful drain().SlowConsumerPolicy::Error, an overflow that an operation's read runs into is reported through the error listener, logged at error level, instead of failing that operation. Register an errorListener, or set slowConsumerErrorsFailOperations: true to have operations fail as before.[feature] NatsOptions::$waitForReconnect (default true). While a reconnect is in flight, requests, subscribe(), flush(), rtt(), drain(), drainSubscription() and the reads (processIncoming(), readIncoming(), SubscriptionQueue polling) wait for it within their own timeout, then run on the new connection. Set false to fail fast again.[feature] SlowConsumerException, a ConnectionException that names the subscription whose queue overflowed, so a subscriber that fell behind can be told apart from a failed connection.[feature] NatsOptions::$slowConsumerErrorsFailOperations (default false) restores the previous behavior, where an overflow of any subscription failed whichever operation's read ran into it.Reconnects:
SlowConsumerPolicy::Error, a subscriber that could not keep up made the connection close for good on its next reconnect: the first message after the re-subscription overflowed its queue and failed every attempt. The overflow is now reported and the reconnect carries on.processIncoming() whose read failed while another fiber was already reconnecting waited for the whole reconnect, ignoring its own timeout. It now gives up at its own deadline.drain() called from a Reconnected listener waited out its whole budget: the read that started the reconnect held the socket read until it was over.disconnect() during a reconnect now cuts its backoff short and wins over a connect() that is still dialling, and a failure is tied to the connection it happened on, so it cannot tear down a connection the application has since reopened.Freezes and lost messages:
processIncoming() or readIncoming() loop could freeze the process at 100% CPU while another fiber held the socket read (a request waiting for its reply, the heartbeat): the call returned 0 at once without ever letting the event loop run. It now waits for that read.drain() during a reconnect threw without closing anything, so the reconnect could reopen the connection being shut down; it now waits for the reconnect within its budget, bounds its backlog pass by the same budget, and reports what it discards.drainSubscription() could leave the subscription alive on the server, dropped messages already received while reconnecting or during drain(), lost messages still in flight when a handler threw inside its flush, and could hang on a stalled socket. All fixed.SlowConsumerPolicy::Error, an operation no longer fails with another subscription's overflow: a request() failed although its reply had arrived, and a fetch discarded what it had collected. A SubscriptionQueue's polling buffer follows the same rules, and a read delivers everything else before it throws.keys() and history() could return a cut-short list as if complete (under the default DropOldest) when one read brought more records than the pending limit.SubscriptionQueue::fetchAll() failing on its own overflow lost the messages it had taken; subscribeQueue() could throw while replaying early messages and leave the subscription feeding a queue nobody held.Close and drain lifecycle, and reporting:
drain() emits one Closed event once it is over, and every close is announced once. connect() is refused while a drain runs, because its teardown would close a connection opened meanwhile.-ERR, a malformed async INFO, an overflow) is reported once the whole chunk is queued, so an error listener that reads on the connection no longer reorders messages. A fatal -ERR outranks an overflow met earlier in the same read.PHPStan level 8, 2304 unit tests (with data sets), 149 live integration tests, 48 Behat scenarios, 45 runnable examples executed against a live server, 99.29% unit statement coverage (95% unit and 97% combined floors enforced in CI) and ~94.5% Infection covered MSI (90% floor enforced in CI). Every fix has a test that fails when the fix alone is reverted. The full per-change record is in the CHANGELOG.
waitForReconnect below) fails with a
TimeoutException, for example Subscribe to "orders" timed out waiting for the connection to be re-established, where it used to fail at once with Connection is not open. TimeoutException is not
a ConnectionException, so a catch (ConnectionException) around subscribe(), flush(), rtt(),
request(), requestWithHeaders() or requestMany() no longer catches that case.processIncoming() and readIncoming() without a Cancellation now wait for a reconnect in flight to
end, and for another fiber's socket read to end, instead of returning or failing at once. Pass a
Cancellation to bound them.SubscriptionQueue::fetch(), and next() without a timeout, return null during a reconnect instead of
throwing Connection is not open; next() and fetchAll() with a timeout wait for the reconnect within
it. A reconnect that gives up still throws its error.drain() now emits ConnectionEvent::Closed, so a listener that reconnects on every Closed now also
reconnects after a graceful drain().SlowConsumerPolicy::Error, an overflow that an operation's read runs into is reported through
the error listener, logged at error level, instead of failing that operation. With no errorListener
and no logger it is visible nowhere: register an errorListener, or set
slowConsumerErrorsFailOperations: true to have operations fail as before.[feature] NatsOptions::$waitForReconnect (default true). While a reconnect is in flight,
request(), requestWithHeaders(), requestMany(), subscribe(), flush(), rtt(), drain(),
drainSubscription() and the reads - processIncoming() / readIncoming() and SubscriptionQueue
polling - wait for it instead of failing at once with Connection is not open, then run on the new
connection. An operation waits within its own timeout; a read within the Cancellation passed to it,
and without one until the reconnect ends. A reconnect that gives up surfaces its own error (e.g.
Reconnect attempts exhausted). Operations still fail at once when no reconnect is in flight, and
when called from a connection/error listener while the reconnect is in flight (it runs inside the
reconnect, which waits for it). Set false to fail
fast again, except that drain() then closes the connection and throws, and drainSubscription()
delivers what already arrived and removes the subscription.[feature] SlowConsumerException, thrown under SlowConsumerPolicy::Error when a message arrives
for a subscription whose queue is full, carries the subscription's sid. It extends
ConnectionException, which the overflow was thrown as before, with the same message, so existing
handlers still catch it; a caller can now tell a subscriber that fell behind from a failed connection.[feature] NatsOptions::$slowConsumerErrorsFailOperations (default false): set true to keep the
behavior from before the change below, where under SlowConsumerPolicy::Error an overflow of any
subscription fails whichever operation's read ran into it. An overflow of a SubscriptionQueue's
polling buffer that is thrown is then also reported, as it was before. Service::run() reports
overflows either way.[bugfix] Under SlowConsumerPolicy::Error, an operation that reads the socket while it waits for a
result of its own no longer fails with another subscription's overflow. It used to throw the overflow
(a ConnectionException) of whichever subscription's queue its read happened to overflow: a request()
failed although its reply had arrived (a retry could repeat the work, a JetStream publish could be
stored twice), a fetch discarded the messages it had collected (redelivered late, or lost with
max_deliver=1), and which operation failed was down to chance. Now the overflow is reported through
the error listener and the operation completes. This covers request(), requestMany() and what is
built on them (JetStream publish, ackSync(), stream and consumer management, Key/Value and Object
Store calls), flush(), rtt(), fetchBatch()/fetchNext(), directGetBatch(), pull consumers
(consumePipelined()), Key/Value keys() and history(), and SubscriptionQueue polling;
Service::run(), which used to swallow the overflow without reporting it, now reports it. An overflow
of the operation's own subscription (a SubscriptionQueue's) still fails it, once the rest of the read
is delivered, and processIncoming() / readIncoming(), the reads an application makes itself, still
throw. slowConsumerErrorsFailOperations restores the old behavior. A reported overflow is logged at
error level. The README's new Slow Consumers section describes the whole behavior.[bugfix] The same now holds for a SubscriptionQueue's own polling buffer, which fills when the
application does not poll the queue: under SlowConsumerPolicy::Error its overflow is a
SlowConsumerException naming the queue's subscription - it was a plain NatsException, so a
catch (ConnectionException) now catches it too - thrown to the application's own read and reported
when another operation or a background read runs into it. It used to be thrown from whichever read
delivered the message, so a request() failed although its reply had arrived, and it cut that
delivery short: the messages behind it, for other subscriptions too - an operation's reply among them -
waited for the next read, and drain() discarded them at its deadline. They are now delivered in the
same pass. It used to be reported as well as thrown, logged at debug level; now each overflow reaches
the application once, and a reported one is logged at error level like any other overflow under
Error (with slowConsumerErrorsFailOperations, one that is thrown is still reported as well).[bugfix] drain() now emits ConnectionEvent::Closed when it closes the connection - once, after
the drain is over, so a Closed listener can connect() again straight away. It used to close the
connection without any event; nats.go likewise calls its closed handler after Drain(). When
something else closed the connection during the drain - a reconnect that gave up, or disconnect() -
that path's Closed is the only one. A listener that reconnects on every Closed now also does so
after drain(), as it already did after disconnect(). Every close is now announced once:
disconnect() of a connection already closed and announced (after drain(), after a reconnect that
gave up, a second disconnect()) closes it again without a second Closed event. The same holds when
a disconnect() - or a drain() running out of time - comes while a connect or reconnect that gave up
is still closing the socket (a TLS or WebSocket close takes a while): that path's Closed, with its
error, is the only one. A disconnect() there used to announce the close a second time.[bugfix] A synchronous application could leave a reconnect stalled until the process restarted.
A reconnect only advances while something waits on the event loop, and awaiting an operation that
fails at once never lets the loop run its dials and backoff timers. So when the heartbeat started a
reconnect in the background (a hung server, a dropped connection noticed between operations), a
queue worker or daemon whose operations all failed that way stayed Connecting and failed every
operation from then on. With waitForReconnect the first operation waits and so drives the
reconnect. A publish buffered during a reconnect now also yields one event-loop tick, so a process that
only publishes moves the reconnect along, one tick per publish.[bugfix] A request, pull fetch or processIncoming() whose socket read failed - or brought a corrupt
chunk - while another fiber (typically the heartbeat) was already reconnecting waited for the whole
reconnect, ignoring its own timeout - up to the full backoff schedule during a long outage. It now
gives up at its own deadline while the reconnect carries on.[bugfix] One timeout now covers a whole request: the request timeout (and requestMany()'s total
timeout) starts when the request is issued, so the wait for a reconnect, the reply-inbox set-up and the
publish all count against it, and the reply wait gets what is left. It used to start only after the
publish. A request with a
non-positive timeout is now rejected before anything is published.[bugfix] flush() and rtt() honor the single requestTimeoutMs budget they document: the PING
write and the PONG wait used to get a full budget each, so a backpressured flush could take twice
as long. rtt() does not count a wait for a reconnect as round-trip time.[bugfix] drain() during a reconnect threw Connection is not open without closing anything, so
the reconnect could reopen - with every subscription replayed - the connection the application was
shutting down, and the publishes buffered during the outage were lost when it fell back to
disconnect(). drain() now waits for the reconnect within its budget, so those publishes are
flushed before the drain. If the budget runs out it stops the reconnect at once, bounds its backlog
pass by the same budget, and reports the buffered publishes it discards through the error listener;
connect() is refused (Cannot connect: drain in progress) until the drain is over, because the
drain's teardown would close a connection opened meanwhile. When it cannot wait (waitForReconnect
disabled, or called from a connection/error listener) it closes the connection, reports what it
discards - the buffered publishes and the messages received but not yet delivered - and throws
Cannot drain while reconnecting: the connection was closed instead, matching nats.go's Drain().[bugfix] drainSubscription() could leave the subscription alive on the server. When the
connection was lost during its flush, the reconnect re-subscribed the sid and drainSubscription()
then removed it only locally: the server kept delivering to a sid nothing handles, and for a queue
group that member silently took its share of the group's messages. A subscription being drained is
no longer re-subscribed.[bugfix] A subscription removed while a reconnect was between re-subscribing and going live -
unsubscribe() and drainSubscription() can then only remove it locally - stayed subscribed on the
server, with the same effect. It is now unsubscribed on the new connection before that goes live, and
so is an auto-unsubscribe max armed in that window, which used to leave the server delivering past
the max.[bugfix] drainSubscription() while reconnecting, or during drain(), dropped the messages already
received for the subscription without delivering or reporting them. While reconnecting it now waits for
the reconnect within its budget, like flush(), and drains on the new connection - so it also delivers
what the server sends on a subscription the reconnect had already re-subscribed before its UNSUB lands;
when it cannot wait (waitForReconnect disabled, a listener inside the reconnect, the budget spent) it
delivers what arrived. During a drain() it leaves the subscription to the drain, whose flush may still
bring messages for it: removing it at once dropped those. Its UNSUB write is bounded by its budget like
drain()'s writes; a peer that stopped reading held it forever. A handler that throws during it is
reported through the error listener and delivery goes on, like in drain(): a handler failing inside
its flush was swallowed without a trace,
and one failing in its final delivery made it throw and keep the subscription. When a delivery for the
subscription is already under way - a handler draining its own subscription included - that delivery
now hands over the messages queued behind it and then removes the subscription; the handler that
drained itself used to lose them. An UNSUB that fails because the connection just dropped no longer
makes it throw and keep the subscription: it still delivers and removes it. A second call for a sid
that is already being drained now resolves at once, instead of sending a second UNSUB.[bugfix] disconnect() during a reconnect let the reconnect run on until its current backoff delay
ended, so a connect() right after the close joined it and failed with Recovery was aborted before the connection opened, and a close during the backoff after the last attempt was reported as
Reconnect attempts exhausted with a second Closed event. Closing now cuts the backoff short, so a
reconnect waiting between attempts stops at once (an attempt already dialling finishes first), and it
stops without reporting exhaustion - also when its attempt then fails authentication, which used to
announce the close a second time. A connect() issued while such a reconnect is still winding down
now fails at once instead of waiting for it: it could never open the connection, and when the
connect() came from a Closed listener that the reconnect itself was waiting on, the wait never
ended.[bugfix] disconnect() while connect() was still dialling, or retrying a failed first dial
(retryOnFailedInitialConnect), was overridden: the dial went Open behind the announced close, with
close intent still set, so nothing would recover that connection later. connect() now fails with
Connect was aborted before the connection opened, and the retries' backoff is cut short. A
disconnect() during the last retry, whose dial then failed too, no longer makes connect() report
that dial's error and announce the close a second time.[bugfix] A read, write or heartbeat that failed on a connection the application had since closed and
reopened - for example from an error listener that reconnects - started a reconnect of the new,
healthy connection. Failures are now tied to the connection they happened on.[bugfix] drain() whose connection died while it waited for its flush PONG read the dead socket
until its budget ran out; it now ends the flush at once. A server PING answered during a drain is
bounded by the drain budget like the drain's own writes, so a stalled socket cannot hold it past it.[bugfix] A publish issued while disconnect() was closing the connection during a reconnect was
accepted into the reconnect buffer and reported success, then discarded silently. Publishes are
refused once a close is under way.[bugfix] A reconnect the server refused to authenticate discarded the publishes buffered during the
outage without reporting them. It now reports them as an exhausted reconnect does (Reconnect failed authentication: N bytes of buffered publishes were discarded).[bugfix] A logger that threw while an exhausted reconnect reported the publishes it discarded
aborted the cleanup: the connection kept its subscriptions and no Closed event was emitted. A
logger that threw on a reconnect's "attempt failed" line ended the reconnect, leaving the connection
Connecting for good, and one that threw while a lifecycle event was logged kept that event from the
connection listener. A logger that threw on a failed read skipped the reconnect: the connection stayed
Open on a dead socket and every later read failed with the logger's exception. And one that threw on
an error the heartbeat's own read picked up (a fatal -ERR, a corrupt stream) escaped into the event
loop. All of these are now contained.[bugfix] Under SlowConsumerPolicy::Error, a subscriber that could not keep up made the connection
close for good on its next reconnect. With its queue full - nothing delivers while a reconnect runs -
the first message the server sent after the reconnect re-subscribed it overflowed the queue, and the
overflow failed the attempt like a fatal server error; every attempt failed the same way until the
reconnect gave up, closed the connection and discarded the queued messages. The overflow now drops
that message and is reported through the error listener, as the policy says, and the reconnect carries
on; a fatal -ERR in the same read still fails the attempt. An overflow among the frames read just
before a corrupt one was not reported at all; it is now.[bugfix] The flushes of drain() and drainSubscription() ended early when one of their reads
overflowed a subscription's queue under SlowConsumerPolicy::Error, or when a handler threw while they
delivered, and the messages still in flight were then lost without a trace: drain() closed the socket
on them, and for drainSubscription() they arrived after the subscription was removed. The overflow or
the handler's failure is reported through the error listener and the flush reads on to its PONG.[bugfix] Under SlowConsumerPolicy::Error, the application's own read that met a subscription's
overflow and then a fatal -ERR threw the overflow and only reported the -ERR, so the caller took a
failed connection for a subscriber that fell behind. The -ERR is now thrown and the overflow reported.[bugfix] Under SlowConsumerPolicy::Error, a read that ended in a corrupt frame could lose an
overflow: a second overflow in that read replaced the first, which was then neither thrown nor
reported - as did the failure of a connection that could not recover from that frame. Each overflow now
reaches the application once.[bugfix] Under SlowConsumerPolicy::Error, an error listener that reacted to an overflow by reading on
the connection - drainSubscription($error->sid), say - could have messages delivered out of order: the
overflow was reported before the rest of its read was queued, and the listener's read delivered the
next read's messages ahead of it. An overflow is now reported once its read is queued.[bugfix] A handler that threw while the heartbeat's own read delivered was swallowed without a trace,
and the messages behind it waited for the next read. A handler that threw while a reconnect's handshake
delivered (the server had sent a frame right behind its PONG) failed that reconnect attempt. Both are
now reported through the error listener, and delivery goes on.[bugfix] SubscriptionQueue::fetchAll() that failed - on an overflow of its own subscription under
SlowConsumerPolicy::Error, say - lost the messages it had already taken from the queue's buffer:
neither returned nor counted. They are now put back, in order, for the next call.[bugfix] subscribeQueue() threw when the messages that arrived before its queue existed did not fit
in it under SlowConsumerPolicy::Error: the rest of those messages were lost, and the subscription stayed
registered, feeding a queue nobody held. The overflow is now counted and reported, and the queue is
returned.[bugfix] Key/Value keys() and history() could return a cut-short list as if it were complete (under
the default DropOldest), or fail (under Error), when one read brought more records than
maxPendingMessagesPerSubscription - possible once readChunkSizeBytes is raised. Their replay
subscriptions are now exempt from that bound, like the JetStream fetch inboxes: the listing bounds
them.[bugfix] Under SlowConsumerPolicy::DropOldest and DropNewest, a message the policy discarded was
reported in the middle of the read that brought it, as were a recoverable -ERR and a malformed async
INFO: an error listener that read on the connection then had the next read's messages delivered ahead
of the rest of that one. They are now reported once the read has queued everything it read, like the
Error overflows. A logger that threw on one of these reports failed the read - under DropOldest after
the oldest message was gone but before the new one was queued, so that one was lost too - and so did one
that threw on a SubscriptionQueue's own drop report. A logger that throws on any report is now
contained, and the error listener still gets the report: a handler's failure after a reconnect and a
JetStream push consumer's status used to be kept from it.[bugfix] A processIncoming() or readIncoming() loop could freeze the process at 100% CPU. When
another fiber held the socket read - a request waiting for its reply, or the heartbeat reading the
answer to its PING (a handler that awaits something is enough to let it start) - the call returned 0
at once without handing the event loop control, so no timer or socket read ran again, that other read's
included. It now waits for that read to finish, bounded by its cancellation, and then returns 0. A
loop over SubscriptionQueue::fetch(), or next() without a timeout, spun the same way and is fixed
with it.[bugfix] A request made by a handler of a message that arrived during a reconnect timed out, and
drain() called from a Reconnected listener waited out its whole budget before closing. The read whose
failure started the reconnect held the socket read until the reconnect was over, so nothing called from
inside the reconnect could read. That read now lets go of the socket before it reconnects.[bugfix] A reconnect with a large maxReconnectAttempts crashed after about 60 attempts instead of
backing off at reconnectMaxDelayMs: reconnectDelayMs * 2^(attempt - 1) left the int range, and
casting the out-of-range float gave a garbage, possibly negative, delay that delay() rejected
("Delay must be greater than or equal to zero"; PHP 8.5 also warns that the float is not
representable as an int). The delay is now capped before the cast.It also rejects masked frames unless you pass allowMasked: true. WebSocketFrameCodec::unmask() is deprecated in favour of that parameter.
Minor release. New public API for stopping ordered consumers and watches, plus the outcome of three full review rounds against the NATS.io specification that closed 59 findings, most of them cases where a message could be lost or a consumer could stall silently.
Upgrading is recommended for anyone using KV or Object Store watches, ordered consumers, pull consumers, WebSocket transport, or drain().
[feature] JetStreamContext::stopOrderedConsumer(int $sid) stops an ordered consumer, or a KV / Object Store watch, even after automatic recreates rotated its internal subscription id, and deletes the server-side ephemeral consumer instead of leaving it to expire. A plain unsubscribe($sid) only ever worked until the first recreate, so this is now the documented way to stop any of them.[feature] KeyValueBucket::bind() resolves a mirrored bucket's read and write prefixes from STREAM.INFO. It is required on any handle that did not itself run create(), including a fresh keyValue() handle in the same process, before reads and write-through behave correctly.[feature] NatsHeaders::get() looks a header up case-insensitively, preferring an exact-case match. Publishers differ in how they canonicalize header names, so an exact-case array lookup could silently miss a header that was in fact present.[feature] ObjectStoreBucket::watch() gained an exactName parameter for watching an object whose own name contains * or >, and ObjectStoreWatchOptions gained an idleHeartbeat argument.[feature] subscribeOrderedConsumer() gained consumerOverrides and onConsumerCreated.Messages that could be lost, and flows that could stall:
onError handler the worker used to stop for good while handle() resolved normally, so it looked like a clean drain while messages piled up.fetchBatch() and directGetBatch() reply inboxes are exempt from the slow-consumer drop, so a burst of small replies no longer silently loses the head of a fetch on a max_deliver: 1 consumer.sources now attach the ADR-57 subject transforms, so sourced entries land under this bucket's prefix where reads can actually see them. Mirror buckets write through to the origin instead of publishing into a stream that ingests nothing.drain() and flush() can no longer hang forever against a stalled peer. Drain writes are bounded by the drain budget, handler publishes issued during a drain share that same budget, and drain always reaches the Closed state.Protocol and specification correctness:
RSV1 without negotiated compression, and handshakes missing the Upgrade headers or echoing an unsolicited extension all fail the connection. A fragmented PING used to splice its continuation into an in-progress data message, which corrupted the payload silently. Control-frame answers are now held as data slots, so a coalesced ping flood collapses to one pong for the newest ping and the mandatory Close echo always goes out.$SRV discovery responses serialize empty metadata as {} rather than [], which Go-based tooling rejected outright, making a metadata-less service invisible to nats micro ls.addLink() matches nats.go's guard, watch() encodes exact names, and list() falls back to a leader read on buckets without direct get.$SRV.STATS could report more errors than requests.These correct clear bugs, so they are flagged as fixes rather than breaks, but they change what a caller observes:
drain() no longer throws when a write fails against a dead socket. It reports the failure through the error listener and still closes cleanly. Previously it threw and left the connection stranded mid-drain.WebSocketFrameCodec::decode() no longer throws on a strictness violation. It returns the frames parsed before the violation and reports the violation through a new by-reference $terminal parameter, so already-decoded data is never discarded. It also rejects masked frames unless you pass allowMasked: true. WebSocketFrameCodec::unmask() is deprecated in favour of that parameter.bucket alias is always KV_-prefixed, so a bucket literally named KV_x now resolves to its own stream rather than to bucket x. An explicit name, or a bare string entry, keeps the nats.go convention of being used as-is when it already starts with KV_.create() must call bind() before its reads and writes route correctly.PHPStan level 8, 2025 unit tests, 138 live integration tests, 47 Behat scenarios, 45 runnable examples executed against a live server, ~99.4% combined statement coverage (97% floor enforced in CI) and ~94% Infection covered MSI (90% floor enforced in CI).
The full per-finding record of the three review rounds, including the ones that turned out to be regressions introduced by an earlier round's fix, is in the issues/ directory.
[feature] JetStreamContext::stopOrderedConsumer(int $sid): Future stops an ordered consumer,
or a KV / Object Store watch, even after automatic recreates rotated its internal subscription id,
and deletes the server-side ephemeral consumer instead of waiting for it to expire. A plain
unsubscribe($sid) only ever worked until the first recreate, so this is now the documented way
to stop any of them.[feature] KeyValueBucket::bind(): Future resolves a mirrored bucket's read and write prefixes
from STREAM.INFO. It is required on any handle that did not itself run create() (including a
fresh keyValue() handle in the same process) before reads and write-through work correctly.[feature] NatsHeaders::get(array $headers, string $name): ?string looks a header up
case-insensitively, preferring an exact-case match. Publishers differ in how they canonicalize
header names (nats.go canonicalizes on read), so an exact-case array lookup could silently miss.[feature] ObjectStoreBucket::watch() gained an exactName parameter for watching an object
whose own name contains * or >, and ObjectStoreWatchOptions gained an idleHeartbeat
argument to tune the watch's heartbeat interval.[feature] JetStreamContext::subscribeOrderedConsumer() gained consumerOverrides (extra
consumer configuration merged into the created instance) and onConsumerCreated (invoked once
with the initial instance's ConsumerInfo, for example to read num_pending).[docs] WebSocketFrameCodec::unmask() is deprecated. Masked server-to-client frames are now a
terminal RFC 6455 violation, so the helper has no production caller left; harnesses that decode
client-written frames should use decode(..., allowMasked: true). It still works and is still
covered by tests, and will be removed no earlier than the next major release.[bugfix] Ordered consumers (and the KV/OS watches riding on them): the disconnect-collision
deferral introduced in this release cycle now clears the heartbeat watchdog's miss latch before
returning. Without it, a WATCHDOG-triggered recreate (silent/reaped consumer) whose attempts all
burned during a reconnect window left the latch set forever - no frame can arrive on the old
inbox to clear it (the consumer was already dead and the recreate deleted it) - so every
post-reconnect watchdog tick early-returned and the watch stalled permanently with zero signal.
The watchdog now genuinely re-fires two idle intervals after the connection is Open again, as
the deferral always promised. The deferral additionally rewinds the adopt-before-await dispatch
state (consumer name, deliver inbox, expected sequence) to the pre-episode instance - when the
episode's initial delete never took effect server-side, the surviving old consumer's
post-reconnect frames pass the name filter and resume in-order delivery immediately instead of
silently feeding the watchdog until the next idle heartbeat. The rewind runs ONLY when the
episode delivered nothing: a candidate whose create succeeded with a lost reply may already
have replayed frames to the handler, and rewinding then would re-admit the survivor's copies of
stream sequences the handler already saw (duplicate ordered deliveries) - such an episode keeps
the adopted state and falls back to the exactly-once filtered-until-heartbeat recovery. And the
deferral decision is
LATCHED, not sampled: any attempt observing the connection away from Open marks the episode as a
disconnect collision, so a reconnect completing during the orphan-reap awaits can no longer flip
it into a spurious terminal "recreate failed" teardown.
[bugfix] WebSocket transport hardening to RFC 6455/7692 strictness: the handshake now requires
Upgrade: websocket / a Connection token list containing Upgrade, rejects extension
responses that were never offered (an unsolicited permessage-deflate used to silently flip
compression ON, deflating the CONNECT into a server that never negotiated it), and validates
permessage-deflate parameters against the offered no-context-takeover pair - accepting a
server-volunteered server_max_window_bits of 8..15 per RFC 7692 7.1.2.1 (in the token or
quoted-string spelling, RFC 6455 9.1), since the 15-bit raw inflater decodes any smaller-window
stream; the value-less spelling, out-of-range values, and leading zeroes are rejected per the
section 7 grammar. Frame-level: masked
server-to-client frames, fragmented/oversized control frames (a fragmented PING used to splice
its continuation into an in-progress data message - silent payload corruption), and RSV1 without
negotiated compression are now terminal protocol violations - all deferred via the #115 pattern,
so data frames decoded from the same read are delivered BEFORE the violation surfaces (an
oversized declared length, corrupt deflate payload, or fragment-bound overflow previously threw
mid-batch and discarded them). The server must also echo server_no_context_takeover when
accepting compression (RFC 7692 7.1.1.1) - this per-message-inflate codec cannot decode context
takeover - and a one-shot deferred violation surfacing on the heartbeat timer's read now
recovers the connection instead of being silently swallowed, reported through the guarded #150
emit path so a throwing user-supplied PSR-3 logger can neither skip the recovery nor escape into
the event-loop timer.
Note the contract change on the public WebSocketFrameCodec::decode(): it no longer THROWS on a
strictness violation - it reports it via a new by-ref $terminal out-param and returns the valid
frames parsed before it - and MASKED frames are rejected by default (RFC 6455 5.1 covers
server-to-client frames); pass allowMasked: true to decode client-written frames (test
harnesses, server-side use). WebSocketFrameCodec::unmask() is now @deprecated (production-dead
under the masked-frame rejection; decode(..., allowMasked: true) serves the same audience) but
retained - removing a public helper would be a bc-break.
[bugfix] A permission-rejected pull reply inbox (_INBOX.JS.PULL.<nuid>.*) now fails
handle() fast with a clear error naming the wildcard to grant, instead of polling forever with
zero signal (every retire was a silent client-side deadline) - #167's fail-fast generalized via a
per-sid subscription-rejection callback (NatsClient::onSubscriptionRejected()).
[bugfix] Caller-owned push consumers now perform the ADR-9 heartbeat gap check: each idle
heartbeat's Nats-Last-Consumer is compared against the locally delivered consumer sequence and
a mismatch is surfaced once per gap episode via the error listener AND logger (nats.go
ErrConsumerSequenceMismatch parity). Previously heartbeats kept the silence watchdog quiet while
being withheld from the handler, so an ack-none / max_deliver=1 gap was permanent, invisible loss.
The check also detects a server-side consumer REPLACEMENT (nats.go any-inequality parity): a
heartbeat reporting Nats-Last-Consumer BELOW the session's tracked max surfaces one "consumer
appears to have been replaced (sequence regressed)" error and rebases the tracker to the reported
value, and a delivered consumer sequence below the tracked max rebases it silently - so gap
detection follows the replacement instance instead of being masked by the stale high-water mark
until it passed the old maximum.
[bugfix] JetStream read resilience: directGetLastForSubjects() treats an all-miss multi_last
chunk's lone 404 as "no matches" (ADR-31) instead of discarding every other chunk's results (the
KV/OS batched enumerations could throw spuriously when keys were purged mid-enumeration), and the
KV getAll() / ObjectStore list() per-subject lookups fall back to the leader STREAM.MSG.GET
path on a Direct Get 503 (allow_direct-disabled interop buckets) exactly like get()/info().
The list() fallback queries the leader by the enumerated meta subject VERBATIM, so records
stored under non-canonical (unpadded base64url) name tokens by other clients are not silently
dropped from the fallback listing.
[bugfix] Object Store links and watch patterns: addLink()/addBucketLink() refuse any name
already held by a NON-LINK record - live or deleted tombstone alike (the exact nats.go
ErrObjectAlreadyExists guard shape; overwriting a live object silently stranded its chunks
forever, and allowing the tombstone diverged cross-client on shared buckets) - and addLink()
rejects deleted and link-to-link targets (nats.go parity); watch() base64url-encodes an
exact-name pattern into the meta-subject filter and rejects wildcard patterns loudly (they can
never match encoded name tokens - previously a wildcard watch subscribed successfully and
observed nothing), with a new exactName: true parameter to watch an object whose name itself
contains * or > (the pattern is then always encoded).
[bugfix] Headers interop: NatsHeaders::toWireBlock() emits values VERBATIM (the silent trim
mutated signature/checksum-carrying values; nats.go writes caller bytes untouched - the decoder
keeps its trim as an inbound tolerance), and the new case-insensitive NatsHeaders::get()
accessor bridges lookups against non-canonicalizing publishers.
[bugfix] Services/observability polish: endpoint names are validated against the ADR-32 token
rules at registration (previously advertised verbatim to conformant tooling);
BasicJsonSchemaValidator rejects non-empty JSON lists for "type":"object"; and JetStream
client-level errors (emitClientError() - e.g. a terminally dead ordered consumer) now reach the
PSR-3 logger as well as the error listener, so a logger-only configuration is no longer blind.
[bugfix] KV and Object Store watches are now LOSSLESS: both are rebuilt on the ordered-consumer
machinery (nats.go watcher parity), gaining consumer-sequence gap detection with automatic
recreate-from-last-revision+1 (a slow-consumer drop or reconnect window is REPLAYED instead of
becoming a silent permanent gap - ack-none watch deliveries are never redelivered on their own),
flow control, and watchdog-driven recreation of a silent/reaped consumer (which previously
surfaced an error at best - or, for the Object Store watch, hung forever with no signal: it never
requested an idle heartbeat at all; it now defaults one like KV, tunable via
ObjectStoreWatchOptions::$idleHeartbeat). A recreate before the first delivery re-applies the
watch's initial deliver policy, so a new/last_per_subject watch never replays from sequence 1.
subscribeOrderedConsumer() gained consumerOverrides and onConsumerCreated parameters, and
the new JetStreamContext::stopOrderedConsumer(int $sid) stops an ordered consumer / watch even
after recreates rotated its internal sid (a plain unsubscribe() only ever worked until the
first rotation). A watch stopped via the legacy plain unsubscribe($sid) no longer strands its
internal stop-registry entry forever: the watchdog's self-cancel tick releases the entry and
best-effort deletes the server-side ephemeral (only the CURRENT timer runs this cleanup - a
rotated-out old timer cannot release a consumer that lives on under a new sid). The cleanup
latches the stop FIRST, exactly like stopOrderedConsumer() - a recreate parked in its awaits
when the tick fires tears its fresh instance down instead of installing a consumer whose stop
handle is already gone (which would have been permanently unstoppable). And a
stopOrderedConsumer() racing an in-flight recreate whose remaining create attempts then all
fail no longer emits a spurious terminal "recreate failed" error for the deliberately stopped
consumer - the exhausted episode releases the never-adopted fresh inbox and returns silently.
[bugfix] KV buckets created with sources now attach the mandatory ADR-57 subject transforms
({src: "$KV.<src>.>", dest: "$KV.<bucket>.>"}), so sourced entries are re-subjected into the
new bucket's prefix and visible to get/getAll/keys/watch - previously they were copied under the
origin's subjects where every read path was blind to them (invisible data). Caller-supplied
transforms pass through verbatim (full-control sources, e.g. non-KV streams; the name is then not
KV_-prefixed). Mirror buckets now set mirror_direct: true and write THROUGH to the origin's
prefix (nats.go putPre parity) instead of publishing to their own subject that no stream
ingests (503); cross-domain mirrors (domain shorthand → external: {api: "$JS.<domain>.API"})
route writes via the external API prefix and reads via the origin prefix. The new
KeyValueBucket::bind() resolves the same prefixes from STREAM.INFO for handles attached to
mirror buckets created elsewhere - note this includes a FRESH keyValue() handle in the same
process (each handle is independent; only the instance that ran create() is auto-resolved).
Mirror read/write prefixes are applied only AFTER the stream create is confirmed server-side -
and, symmetrically, the stale-prefix reset in create()/bind() also happens only after the
server confirmed the new configuration, atomically with the re-apply. So a failed mirror create
can neither leave a fresh handle misdirecting writes at the origin's subjects NOR blind a
handle whose mirror the server confirmed earlier (a failed re-create leaves the last confirmed
routing intact), and no suspension window exists in which concurrent readers see half-reset
prefixes.
Also note the name-mapping rules: the bucket alias is KV_-prefixed UNCONDITIONALLY (it
explicitly declares a KV bucket, so a bucket legitimately named KV_x maps to its own backing
stream KV_KV_x), while a transform-less explicit source name, bare-string entries, and
mirror names are KV_-prefixed only when not already (nats.go stream-name idempotence) - the
previous used-as-is behavior produced invisible data; supply subject_transforms to source a
non-KV stream by its verbatim name.
[bugfix] Pipelined Object Store uploads can no longer store a silently corrupted object: the
ADR-21 503 retry inside publish() could re-order a retried chunk BEHIND later accepted chunks,
and put()/putStream() then published the meta record and reported success for an object whose
stream-order reassembly no longer matches its digest (every later read failed with a digest
mismatch). The acked stream sequences are now verified strictly increasing in chunk order; a
permuted upload aborts before the meta publish with a clear retryable error, and one seq-less
ack (a defensive case no real server produces) skips only its own neighbor pairs instead of
disabling the check for all remaining chunks. Any failed/aborted
upload additionally purges the partial NUID's chunks (nats.go purgePartial parity) - previously
they were orphaned in the stream forever, since no meta record ever referenced them.
[bugfix] The infinite pipelined pull engine no longer treats a transient 503 (no JetStream API
responder - server restarting, JS still wiring up after a reconnect, a leader election window) as
terminal. Previously the worker stopped PERMANENTLY, and with no onError configured handle()
resolved normally with the processed count - indistinguishable from a clean drain while messages
piled up in the stream. 503 is now routine-with-backoff (nats.go Consume() parity; finite/fetch
semantics unchanged); the first 503 of a streak fires onError once as an operator signal,
re-armed by the next delivery OR by any routine non-503 retire (a 404/408/non-terminal 409 or a
client-side deadline proves the JS API answers again) - i.e. one onError per no-responders
episode, so a later outage on an idle, never-delivering stream is still reported.
[bugfix] The fetchBatch() and directGetBatch() reply inboxes are now slow-consumer-exempt
like the mux (#118) and pull-pipeline (#120) inboxes. A burst of small replies above the
per-subscription pending cap (default 1024) arriving within one read chunk was silently
DropOldest-discarded: a fetch returned with its head missing (permanently lost on a
max_deliver: 1 consumer - the server counted every message as delivered), and a Direct Get
batch returned a truncated result presented as complete (its replies are never redelivered and
the 204 end-of-batch marker still arrived). Memory stays bounded by the requested batch size.
[bugfix] drain() and flush() can no longer hang forever on a backpressure-stalled peer:
transport writes suspend indefinitely when the send buffer is full (they cannot be cancelled),
and drain() cancels the heartbeat FIRST - removing the only escalation that could break such a
wedge - so its documented ~requestTimeoutMs bound was unenforceable. Drain writes are now
bounded by the drain budget (a wedged write is abandoned; the teardown's socket close fails it
out) and any drain write failure falls through to teardown, so drain() always reaches Closed.
Note the contract change: drain() no longer THROWS on a dead-socket write failure - it reports
it via the error listener and still closes cleanly (previously it threw and left the connection
stranded in Draining). The teardown closes the transport BEST-EFFORT like every other terminal
path, so a custom transport whose close() throws on an already-broken socket cannot re-strand
Draining either. Handler publishes issued while drain() delivers backlog are bounded by the
drain's REMAINING budget (not a fresh full requestTimeoutMs each), and a delivery pass stops
delivering past its head message once the budget is exhausted, reporting the dropped remainder
via the loud "drain deadline exceeded" error - previously K backlog messages whose handlers each
published against a wedged transport could extend drain() to ~K x requestTimeoutMs.
flush()'s PING write is bounded by the request timeout and surfaces a TimeoutException on a
write-side wedge. Implemented at the connection layer - TransportInterface is unchanged, so
custom transports are unaffected.
[bugfix] The WebSocket transport's ping-answer (pong) and RFC 6455 Close-echo writes are no
longer inline in the read fiber: control answers are held as data SLOTS drained by a single
writer fiber - a latest-pong slot where a newer ping's payload REPLACES a queued-but-unsent pong
(RFC 6455 5.5.3: only the most recent ping needs answering) and a dedicated OP_CLOSE echo slot
that is always flushed (RFC 6455 5.5.1 makes the echo mandatory; first Close wins), giving
constant memory with no cap that could drop answers. Inline in the read fiber, a pong write that
THREW (peer died right after coalescing [MSG][PING] into one read) discarded the
already-decoded MSG bytes from the same read - consumed from the buffer, never delivered, never
resent - and a pong write that SUSPENDED on a backpressure-stalled peer parked the entire read
path behind an outbound control frame (the same suspension class as the
WebSocketTransport::close() wedge fixed below). A coalesced ping flood now collapses to one
pong answering the NEWEST ping, and the Close echo goes out even behind 16+ coalesced pings.
[bugfix] Every $SRV discovery response (PING/INFO/STATS/SCHEMA) now serializes empty
metadata maps as JSON objects ({}) instead of arrays ([]), service-level and per-endpoint.
ADR-32 types metadata as map[string]string, and Go-based consumers (nats micro ls, nats.go
micro) hard-fail unmarshalling [] into a map - rejecting the whole discovery response, so a
metadata-less service (the default) was invisible to standard tooling. statsSnapshot() still
returns plain PHP arrays; the conversion happens only at the wire boundary.
[bugfix] Service reply-publish failures can no longer escape the endpoint callback into the
shared dispatch loop (which aborted delivery for every subscription on the connection): the
schema-validation error reply is guarded; a requester-controlled non-UTF-8 correlation header no
longer makes the JSON error reply throw at encode time (the correlation id is omitted instead -
this was remotely triggerable); connection-level reply failures are recorded on the endpoint and
swallowed; and a ServiceError code containing CR/LF is collapsed to one line like the
description instead of blowing up the header build. A request whose handler errored and whose
error-reply publish then ALSO failed counts ONE error (previously two, letting $SRV.STATS
report num_errors > num_requests) and no longer emits a late duplicate request_error
observer event with a hardcoded code contradicting the handler's own; the reply-publish failure
is counted as the request's error only when the handler itself succeeded, and the endpoint's
last_error records it in both cases.
[bugfix] WebSocketTransport::close() can no longer deadlock the client on a backpressure-stalled
peer. The best-effort RFC 6455 Close frame was written inline before the socket close; Amp's socket
write() SUSPENDS the calling fiber (it does not throw) while the write buffer is full - e.g. a peer
holding the TCP window at zero - so the try/catch never engaged, close() parked forever before
reaching the socket close, and since that close is the only thing that errors pending writes out,
every recovery/disconnect/drain path awaiting transport->close() wedged permanently (the heartbeat
had already self-cancelled once state left Open, so nothing remained to break the cycle). The Close
frame now goes out on its own fiber awaited with a 0.25 s bound: a responsive socket still sends it
before closing, and a wedged write is abandoned - the socket close then fails it out, waking its
fiber. Any other writes still queued behind a stalled buffer at that point are failed out the same
way (loudly, via their write futures) instead of being waited on - disconnect() is the documented
lossy path and drain() has already flushed and PONG-confirmed before it closes the transport.
readLine() now also pins its socket in a local for the whole read loop, so a reader resuming
inside the bounded close window cannot deref the already-nulled socket property. Plain-TCP
AmpSocketTransport was never affected (its close() does not write).
[bugfix] The pipelined pull engine no longer treats a single immediately-answered empty pull as proof
of idleness when setDepth() > 1 (#169). Retires run in issue order, so under no_wait with steady
traffic below depth*batch a tail pull that raced an already-drained stream would 404 right after a
delivering head pull - and that lone empty latched the idle drain, injecting a periodic backoff pause
and clamping the next generation to depth 1 (the effective pipeline oscillated depth->1->depth with
~10 ms stalls despite continuously delivering). The engine now counts a ROLLING streak of consecutive
empty retires across pulls (reset by any delivery, surviving the engine's continuous refill) and only
latches the idle drain once the streak spans one full pipeline width (>= setDepth()), so a
delivering pipeline keeps its full depth while a genuinely idle stream still accumulates to the latch
and backs off exactly as before. setDepth(1) (and finite setIterations() mode) keep the original
latch-on-first-empty behavior unchanged.
Patch release — four bug fixes to the request/reply mux inbox (#118) and the pull-pipelining engine (#120).
Patch release — four bug fixes to the request/reply mux inbox (#118) and the pull-pipelining engine (#120).
[bugfix] request()/requestMany() now surface a clear, catchable ConnectionException when the shared mux reply-inbox subscription _INBOX.<inbox>.* is rejected by server permissions, instead of hanging every request to a silent timeout (#167). The connection detects the async permission -ERR, drops the dead mux state (so a reconnect does not replay the rejected wildcard SUB), and fails requests fast with a message naming the _INBOX.> wildcard permission required. The in-flight request that triggers the rejection also fails fast.[bugfix] Pull consumers with a priority group under the overflow/prioritized policy now honor setDepth() instead of pulling strictly serially — those policies never emit a Nats-Pin-Id, so the grouped-and-unpinned serialization guard previously disabled pipelining for the whole run. A grouped run now pulls serially only until its first delivery, then fans out. Conversely, a pinned_client group that captured a pin and then LOST it (a 423 cleared it mid-run) now re-serializes its pin re-capture instead of racing pin-less pulls at full depth (#170).[bugfix] requestMany() no longer discards already-collected replies if the mux reply inbox is permission-rejected mid-collection: it returns the partial batch it has, and surfaces the clear permission error only when nothing was collected.Full gate: PHPStan level 8, 1746 unit tests. No public API or wire-format change.
[bugfix] request()/requestMany() now surface a clear, catchable ConnectionException when the
shared mux reply-inbox subscription _INBOX.<inbox>.* is rejected by server permissions, instead of
hanging every request to a silent timeout (#167, a follow-up to #118's muxed request inbox). An account
without subscribe permission for the reply-inbox wildcard (e.g. _INBOX.>) previously saw all
request/reply calls time out with no explanation; the connection now detects the async permission
-ERR, drops the dead mux state (so a reconnect does not replay the rejected wildcard SUB), and fails
requests fast with a message naming the wildcard permission required. The in-flight request that
triggers the rejection also fails fast rather than waiting out its full timeout.[bugfix] Pull consumers with a priority group under the overflow or prioritized policy now honor
setDepth() instead of pulling strictly serially. Those policies never emit a Nats-Pin-Id, so the
"grouped-and-unpinned" serialization guard (meant to let a pinned_client group capture its pin before
fanning out) previously held for the whole run and silently disabled pipelining. A grouped run now pulls
serially only until its first delivery, then fans out to the configured depth if no pin was captured.
Conversely, a pinned_client group that captured a pin and then LOST it (a 423 stale-pin cleared the
pin mid-run) now RE-SERIALIZES its pin re-capture - pulling one at a time until it re-pins - instead of
racing pin-less pulls at full depth, matching the bootstrap behavior (#170).[bugfix] requestMany() no longer discards already-collected replies if the mux reply inbox is
permission-rejected mid-collection (e.g. a reconnect re-SUB is rejected after some replies arrived): it
returns the partial batch it has, and surfaces the clear permission error only when nothing was collected.Pull consumer pipelining (#120). Pull consumers now keep several pull requests in flight over one long-lived pull inbox (setDepth(), default 2), issui
setDepth(), default 2), issuing the next as soon as one retires — eliminating the per-batch round-trip stall and the SUB/UNSUB churn per pull. Throughput rises from ~1 batch per RTT to overlapping pulls (a large gain on higher-latency links). Reply routing matches how a JetStream server actually delivers: status replies route by a per-pull token, while delivered messages (sent on their original subject) are matched to the oldest in-flight pull; the shared pull inbox is slow-consumer exempt so a slow handler never loses a buffered message.setDepth() controlling overlap. setBatching(1) still works and still pipelines. A consumer that relied on the old batch=1 default now fetches up to 100 messages per pull — size it against your MaxAckPending/ack_wait, or call setBatching(1) to restore one-message pulls.All existing pull-consumer semantics are preserved: stop()/drain(), the escalating idle backoff, finite setIterations(), pinned priority groups (setGroup()) + 423 stale-pin re-pull, terminal-status onError, and reconnect survival. fetchBatch()/fetchNext() are unchanged.
Full CI green including live-server E2E, integration/behat, and mutation testing (covered MSI ≥ 90%).
[feature] Pull consumers now PIPELINE their pull requests (#120). PullConsumerIterator::handle() no
longer creates a fresh inbox + SUB, publishes one pull, waits, and UNSUBs per pull. It opens ONE
long-lived pull inbox subscription _INBOX.JS.PULL.<base>.* for the whole run and keeps several pulls
in flight at once (see setDepth(), default 2), issuing the next pull as soon as one retires - so there
is no inter-batch round-trip stall and no SUB/UNSUB churn per pull. The consumer's throughput ceiling
rises from ~1 batch per RTT to overlapping pulls (a large gain on higher-latency links). Status replies
route by a per-pull token, while delivered messages (which the server sends on their original subject)
are matched to the oldest in-flight pull in order; the shared pull inbox is exempt from the slow-consumer
drop so a slow handler never loses a buffered message. All existing semantics are preserved:
stop()/drain(), the escalating
idle backoff, finite setIterations() (still serial and stop-on-any-error), pinned priority groups
(setGroup()), 423 stale-pin re-pull, terminal-status onError, and reconnect survival. The
single-shot fetchBatch()/fetchNext() primitives are unchanged.[feature] The default pull batch size is now 100 (was 1) and a new setDepth() controls pull
overlap (default 2). setBatching(1) still works and still pipelines. A consumer that relied on the
old batch=1 default now fetches up to 100 messages per pull - size it against your MaxAckPending and
ack_wait; call setBatching(1) to restore one-message pulls.info()/list()), and the client TLS-context
assembly. No public API or wire-format change; behavior is unchanged.A performance-focused minor release: three throughput/efficiency improvements to the JetStream, KV, Object Store, and request/reply paths. No breaking
A performance-focused minor release: three throughput/efficiency improvements to the JetStream, KV, Object Store, and request/reply paths. No breaking API changes (one account-permission note below).
NatsOptions::$readChunkSizeBytes (default 128 KiB, up from Amp's 8 KiB) caps a single socket read on both the TCP and WebSocket transports, so large inbound payloads (e.g. an Object Store download) arrive in far fewer chunks — dividing the per-chunk syscall + fiber-spawn + parser-push overhead ~8–32×. It raises only the maximum a read may return; small-message behavior is unchanged (#119).readIncoming() on NatsClient/NatsConnection exposes one read-and-dispatch cycle as an IncomingChunkResult (frame count plus whether bytes were consumed) — the progress signal the wait loops use. processIncoming() is unchanged (#119).request()/requestMany() now share ONE long-lived wildcard subscription _INBOX.<base>.* per connection instead of a fresh subscribe + unsubscribe per call; each request publishes reply-to _INBOX.<base>.<token> and the reply is routed back by token. This removes two control-plane frames and a server-side interest change per request — a throughput win for JetStream, KV, Object Store, and BatchPublisher, which all funnel through request(). Reply delivery, timeouts, no-responders handling, cancellation, and requestMany semantics are unchanged; a delayed/duplicate reply for a completed request can never reach a later one, and the shared reply queue is exempt from the slow-consumer drop. Permission note: the mux inbox subscribes to a wildcard under the inbox prefix, so an account permissioned to subscribe only to exact _INBOX.<...> subjects (not _INBOX.>) will have the mux subscription rejected and request/reply will time out — grant _INBOX.> subscribe permission (the same requirement as nats.go's muxed responder; see #167).keys()/listKeys() enumerate names via a headers-only last_per_subject consumer instead of downloading every value; getAll() and Object Store list() fetch every record with one batched multi_last Direct Get (ADR-31) on NATS 2.11+ (with a version-gated fallback to the per-subject fan-out), chunked by the server's 1024-result cap and by max_payload so large buckets are enumerated across several requests rather than one the server would reject.flush(), drain(), request(), requestMany(), JetStream pull-fetch and direct-get-batch, KeyValueBucket::history()/keys(), SubscriptionQueue, Service::run()) no longer pay a 1 ms idle sleep per partial socket chunk. A frame spanning N chunks previously cost ~N ms (~125 ms/MB at the old 8 KiB default); the loops now sleep only on a genuinely idle read. Delivery is byte-for-byte identical.Full CI green: PHPStan level 8, unit tests on PHP 8.2–8.5, E2E + coverage on a live NATS 2.12 server, examples, and ≥90% mutation MSI.
[feature] NatsOptions::$readChunkSizeBytes (default 128 KiB, up from Amp's 8 KiB) caps the bytes a
single transport socket read may return; both the TCP and WebSocket transports apply it via the Amp
socket's chunk size after connecting. Large inbound payloads (e.g. an ObjectStore download) now arrive
in far fewer chunks, dividing the per-chunk syscall + fiber-spawn + parser-push overhead ~8-32x. It
raises only the MAXIMUM a read may return - the socket still returns just what is available, so
small-message behavior is unchanged (#119).[feature] NatsClient::readIncoming() / NatsConnection::readIncoming() expose one read-and-dispatch
cycle as an IncomingChunkResult (the frame count PLUS whether the read consumed bytes off the wire),
the progress signal the wait loops use to decide whether to yield. processIncoming() is unchanged - it
remains the frame-count-only view of the same cycle (#119).[feature] KV keys()/listKeys() no longer download every value just to list names (#110). They now
enumerate via a last_per_subject + headers_only ephemeral consumer (the metaOnly watch path nats.go's
Keys() uses), so only the KV-Operation/Nats-Sequence headers return and DEL/PURGE tombstones are
filtered by header alone - no value body crosses the wire. Previously keys() was array_keys(getAll()),
which issued one full-value Direct Get per key. The returned set of names is unchanged (deleted keys
excluded); the order (stream-sequence order of each key's latest record) remains unspecified, as before.
Measured against a 100-key bucket with 4 KiB values: value bytes read dropped from ~423 KiB to ~13 KiB
(headers only) and the 100 per-key Direct Get requests became a single consumer.[feature] KV getAll() and Object Store list() fetch every key/object with ONE batched multi_last
Direct Get (ADR-31) instead of one Direct Get request per subject, on servers that support it (#110).
The batched path is version-gated via the new JetStreamContext::supportsBatchedDirectGet() (NATS 2.11+);
older or unparseable-version servers fall back to the unchanged per-subject Direct Get fan-out. The
subject list is split into chunks bounded by the server's 1024-result cap and by the negotiated
max_payload, so buckets with more than ~1024 keys are enumerated across several batched requests
instead of a single oversized one the server would reject. Returned data, tombstone/deleted filtering,
and 404/missing handling are identical on both paths. Measured against a 100-key bucket, getAll()
issued 1 Direct Get request instead of 100 (the value bytes it must transfer are unchanged, since it
returns the values).[feature] The read-path wait loops (flush(), drain(), request(), requestMany(),
JetStreamContext pull-fetch and direct-get-batch, KeyValueBucket::history() and keys(),
SubscriptionQueue, Service::run()) no longer pay a 1 ms idle sleep on partial-frame progress. A frame spanning N socket
chunks previously cost ~N ms (~125 ms/MB at the 8 KiB default; ObjectStore downloads were capped near
8 MB/s) because each partial read reported 0 frames and every loop treated 0 frames as "idle" and slept
1 ms - even when the rest of the payload was already in the kernel buffer. The loops now sleep 1 ms ONLY
on a genuinely idle read (an empty read, or another fiber owning the socket) and loop immediately when
bytes were consumed but no full frame completed yet. Delivery/enumeration is byte-for-byte identical;
each loop's deadline/cancellation bound, the #117 pong-slot flush semantics, #147 frame retention, #148
Connecting-window reads, and #135 parking are preserved, and a truly empty socket still yields the 1 ms
so the event loop advances and deadlines fire (#119).[feature] request()/requestMany() now share ONE long-lived muxed reply inbox per connection
instead of creating a fresh inbox subscription (SUB + UNSUB) for every call (#118). A single wildcard
subscription _INBOX.<base>.* is established lazily on the first request; each request publishes its
reply-to as _INBOX.<base>.<token> and the reply is routed back by that per-request token. This
removes two control-plane frames and a server-side interest change per request - a large throughput win
for JetStream, which funnels every API call, KV, and Object Store operation through request(). Reply
delivery, timeouts, no-responders (503) handling, cancellation, and requestMany semantics are
unchanged. A delayed or duplicate reply for a completed/timed-out request is discarded by token (it can
never reach a later request), and the shared mux queue is exempt from the slow-consumer drop so a reply
is never dropped. NOTE (permission requirement): the mux inbox subscribes to a wildcard under the inbox
prefix, so an account permissioned to subscribe only to exact _INBOX.<...> subjects (not the
_INBOX.>/_INBOX.* wildcard) will have the mux SUB rejected where per-request exact-subject inboxes
previously succeeded. Because the client does not block on the SUB's server acknowledgement, that
rejection arrives as an asynchronous -ERR (delivered to the error listener), after which every
request()/requestMany() on the connection times out (the server has no interest on the wildcard) -
a silent regression relative to the pre-mux exact-inbox path for such accounts. Grant _INBOX.>
subscribe permission (the same requirement as nats.go's muxed responder) to use this client's
request/reply on a restricted account.A hotfix for a message-loss regression introduced in v2.5.3.
A hotfix for a message-loss regression introduced in v2.5.3.
Verified: reliable under sustained CPU load (12/12, was ~2/12), full CI green (PHPStan level 8, 1611 unit, integration + behat on NATS 2.12, coverage, mutation >= 90% MSI).
Upgrade recommended for anyone on v2.5.3 using subscribeOrderedConsumer().
[bugfix] Ordered-consumer recreate no longer loses the replay under load (a regression in the
#122 deliver-inbox rotation, shipped in 2.5.3). The rotation adopted the new instance (its
client-chosen name and the reset expected-sequence) only AFTER the CONSUMER.CREATE reply, but the
server can begin delivering the replay on the rotated inbox the instant the consumer exists - and
those frames are dispatched during the create request's own read-pump, before that reply is
processed. The early replay frames were then filtered out by the not-yet-adopted consumer name and
a later one tripped a spurious gap, cascading into a recreate storm in which only the pre-gap
message was ever delivered (observed as an intermittent, load-dependent failure of the
ordered-consumer dropped-delivery recovery). The name is chosen client-side, so the instance is now
adopted BEFORE the create await; a new deterministic test pins a replay frame arriving ahead of the
create reply, and the recovery now passes reliably under sustained CPU load (#122).A correctness release resolving the remaining reconnect/JetStream/WebSocket findings from the review lineage (issues #115, #121, #122, #165, #166). Ev
A correctness release resolving the remaining reconnect/JetStream/WebSocket findings from the review lineage (issues #115, #121, #122, #165, #166). Every fix landed with a falsifiability-checked regression test and adversarial review; the tree is green on PHPStan level 8, 1610 unit tests, integration + behat against NATS 2.12, 97.9% coverage, and the >= 90% MSI mutation gate. All changes are backward-compatible bug fixes (patch release). See CHANGELOG.md for the full per-issue detail.
inactive_threshold - closing both the leak and the storm. On terminal recreate failure the subscription is torn down so "dead" is actually dead, and the watchdog timer is cancelled explicitly on rotation/teardown.Open transition indefinitely, stranding the connection in Connecting. After a bounded number of drain passes the buffer is sealed and late publishers park on a flush gate (writing directly once Open, failing loudly once Closed), so recovery reaches Open in bounded time with per-publisher and buffered-before-direct wire order preserved.readLine() and the close/protocol error surfaces on the next call. Permessage-deflate inflation is also capped to guard against a decompression-bomb OOM.history() use progress-based deadlines - a healthy-but-slow replay completes, a genuinely stalled server throws instead of silently returning a truncated prefix.stream is rejected as invalid rather than accepted as a bogus success.errorListener.publish()'s at-least-once reconnect semantics are documented.Also included: #166 (lame-duck INFO during the reconnect replay poll) was verified already fixed by the v2.5.2 same-fiber recovery guard and is now pinned by a regression test.
[bugfix] The reconnect-buffer flush no longer defers the Open flip indefinitely under sustained
publish pressure (#165, a #148 follow-up). Since #148 recovery stays Connecting until
flushReconnectBuffer() fully drains, and the flush loops so publishes buffered mid-flush still go
out in order before Open. A fiber publishing continuously re-filled the buffer during each flush
write's suspension, so the loop kept iterating and the connection could stay Connecting for the
whole outage window - subscribe()/request()/flush()/rtt()/processIncoming() all threw
"Connection is not open" and Reconnected never fired (nats.go converges here by holding the
connection mutex during the pending flush; PHP fibers have no equivalent implicit exclusion). The
flush is now bounded: after RECONNECT_FLUSH_MAX_PASSES drain passes it SEALS the buffer, so late
publishers park on a flush-done gate (then write directly once Open, or fail loudly once Closed)
instead of appending, the remaining bytes drain in one final pass, and Open flips within a bounded
number of passes. Wire ordering is unchanged: the already-buffered frames are written before the
flip, so per-publisher order and buffered-before-direct (#148) still hold, and #123 retain-on-flush-
failure / loud-exhaustion semantics are untouched.[bugfix] A WebSocket server that delivered final data frames and then gracefully closed in the
same read no longer loses those messages (#115). WebSocketTransport::processFrames() threw
TransportClosedException the instant it hit the OP_CLOSE frame, discarding the payload of every
data frame earlier in the same batch - already consumed out of the read buffer by the by-reference
WebSocketFrameCodec::decode(), so those NATS messages were gone (silently lost on core NATS;
recovered only via redelivery on JetStream). The transport now returns that accumulated data from
readLine() first and defers the close to the next readLine() via a pendingClose flag,
including on the large-frame spill path (#164) so a spilled frame's bytes are returned too. The RFC
6455 Close echo (#161) is still written when the close is first seen. Relatedly, two RFC 6455 5.4
protocol violations in the same handler now fail loudly with a ProtocolException instead of
silently degrading: a new data frame arriving mid-fragmentation (previously overwrote the partial
message) and an orphan continuation frame with no fragmented message in progress (previously
dropped). Both violations DEFER the same way as the close: any valid data decoded earlier in the
same batch is returned from readLine() first, and the ProtocolException is surfaced on the next
readLine() call - the connection still fails loudly, just after the already-decoded messages are
delivered, with no silent drop.[bugfix] The WebSocket permessage-deflate inflate path now caps the decompressed size, closing a
decompression-bomb OOM vector (#121). WebSocketFrameCodec::inflate() fed the whole compressed
payload to a single inflate_add() with no output bound, so a tiny hostile frame could inflate to
gigabytes and OOM-spike the client - inconsistent with the file's existing max-frame-size / #89
threat model. It now inflates the input in bounded slices (DEFLATE's ~1032:1 maximum ratio caps
each call's output) and throws a ProtocolException the moment the accumulated output exceeds the
cap, keeping peak allocation bounded. Legitimate payloads within the cap inflate byte-identically.[bugfix] Ordered consumers no longer orphan a live server-side ephemeral on a recreate, and a
non-current heartbeat can no longer drive a recreate storm (#122). Each recreate now ROTATES the
deliver inbox: it generates a fresh deliver subject, subscribes it (a new sid), points the new
CONSUMER.CREATE at that subject, and unsubscribes the old inbox. An orphan left by a lost
CONSUMER.CREATE reply (a timeout / connection loss where the create may still have SUCCEEDED
server-side) therefore delivers to the OLD inbox that the client no longer subscribes to, so neither
its data frames NOR its plain idle heartbeats reach the tail-gap check - the recreate storm #122
targets cannot happen - and dropping the client's interest lets the orphan's server-side
inactive_threshold reap it, so the leak self-heals. Because only the current consumer's frames
arrive on the current inbox, the tail-gap check is inherently scoped without parsing control-frame
subjects. Each recreate still chooses the consumer name client-side and best-effort-deletes any
orphaned prior attempt as a faster-cleanup nice-to-have (mirroring the #151 tolerate-any-failure
delete), and on a TERMINAL recreate failure the deliver subscription is torn down so "dead" is
actually dead. The #113 watchdog (re-armed on the rotated sid) / recreateInFlight guard,
#114/#116 recreate retry, and #155 ack-metadata tolerance are all preserved.[bugfix] A non-100 status control frame (e.g. 409 Consumer Deleted, 404, 408, 503) on a
push deliver subject is no longer forwarded to the user handler as if it were a message (#121).
handlePushControlMessage() only intercepted status 100 (idle heartbeat / flow control); other
status frames fell through and were delivered as empty "data". They are now intercepted for every
push subscription: an ordered consumer treats such a terminal status as a gone consumer and
recreates from the last in-order point, while a caller-owned push consumer surfaces a terminal
(4xx/5xx) status through the error listener as a descriptive JetStreamException instead of
silently dropping it. Status-0 data messages (including those carrying user headers) are unaffected.[bugfix] A JetStream publish ack that carries neither an error nor a stream is now rejected
with a JetStreamException instead of being accepted as a bogus PubAck('', 0) success (#121),
matching nats.go, which rejects an empty-stream ack as invalid.[bugfix] directGetBatch() and KeyValueBucket::history() no longer silently return a truncated
prefix when their bounded wait elapses before completion (#121). A Direct Get batch that never
receives its end-of-batch marker (204 / Nats-Num-Pending: 0), or a history replay that never
catches up (num_pending never reaches 0), now throws a JetStreamException reporting the
incomplete result rather than returning whatever partial data was collected as if it were complete.
Both bounds are PROGRESS-BASED (reset on each inbound frame, mirroring #153's missed-heartbeat
approach), so a healthy-but-slow large replay that keeps making progress no longer throws - only a
genuinely stalled server (no progress for the interval) does. history() gained an optional
per-call progress-timeout argument (defaulting to the previous bound).[docs] NatsConnection::publish() now documents its at-least-once, nats.go-parity semantics while
reconnecting (#121): a publish issued during a reconnect is buffered and reports success immediately
Closed event and the "Reconnect exhausted: N bytes ... discarded" async error (#123), never
through the returned Future. The related write-order note - a publish whose direct write fails is
re-sent AFTER the frames concurrent publishers buffered during the same outage - is confirmed as the
intended buffered-before-direct ordering (#148/#165), not a defect: the re-send is deliberately not
seeded into the flush so recovery success stays independent of the failing frame (#145) and the
post-recovery delivery drain runs before the retry (#144); per-publisher order is preserved. No
behavior change.A correctness-focused release resolving 23 issues from a full review of everything shipped since v2.4.0 (memory-loss risk, NATS/JetStream spec conform
A correctness-focused release resolving 23 issues from a full review of everything shipped since v2.4.0 (memory-loss risk, NATS/JetStream spec conformance, reconnect/drain semantics, and performance). Every fix landed one-by-one with a falsifiability-checked regression test and two independent adversarial review passes; the whole tree is green on PHPStan level 8, 1545 unit tests, integration + behat against NATS 2.12, 97.8% coverage, and the >= 90% MSI mutation gate.
All changes are backward-compatible bug fixes (patch release). See CHANGELOG.md for the full per-issue detail.
Connecting until the subscription replay and buffered-publish flush complete, fixing publish-order inversion, writes to a dead socket, and replay/read collisions (#148).Connected (#161).err_code, not message substrings (#154); $JS.ACK metadata parsing tolerates extra trailing tokens (#155); pull-consumer 409 handling, no_wait pacing, and idle-heartbeat validation/fail-fast are fixed (#153); KV/ObjectStore/Batch header requests surface no-responders uniformly as JetStreamException(503) (#161).max (#156); SlowConsumerPolicy::Error drops are observable without corrupting auto-unsub accounting (#159); requestMany() respects maxResponses when replies coalesce (#160).Two narrow follow-ups found during review are tracked as #165 (flush-loop liveness under sustained publish pressure) and #166 (lame-duck INFO during reconnect replay).
[bugfix] KV, Object Store, and atomic-batch header requests now share the same no-responders
exception taxonomy as every other JetStream path (#161). KeyValueBucket::publishWithHeadersAck
(every KV put/update/delete with headers), ObjectStoreBucket::publishMeta (the meta-record
rollup publish), and BatchPublisher's start and commit requests called requestWithHeaders()
directly, so on a JetStream-disabled server or an unbound subject they surfaced a bare
NatsException('No responders...') instead of the JetStreamException(503) that
JetStreamContext::jsRequest()/publish() produce - a caller catching JetStreamException
missed it. The normalization is extracted into a shared JetStreamRequest helper that all four
sites (including jsRequest()) now funnel through. Only the no-responders case is normalized; the
batch start/commit reply-shape detection and version pre-flight (#130/#138/#152) are unchanged.
[bugfix] A FAILED initial connect() that recovers via recoverConnection() (reconnect enabled)
now emits Connected for the first-ever successful handshake instead of Disconnected then
Reconnected, and no longer bumps the reconnect count for what is really an initial connect (#161).
A process whose very first dial needed one retry previously observed Disconnected -> Reconnected
for a connection that was never up and never saw Connected, so listener state machines keyed on
Connected (metrics, readiness gates) never fired. The connection state machine (#144/#145/#148)
is untouched: only which lifecycle event fires on the initial-connect recovery path changed,
gated on a new "has ever been open" flag set by markConnectionOpen().
[bugfix] On a server-initiated WebSocket Close frame the transport now writes an echo Close frame
(mirroring the received status code) before surfacing TransportClosedException, per RFC 6455
section 5.5.1 (#161). Previously the client threw without echoing, which strict intermediaries and
servers treat as an abnormal closure (1006). The echo is best-effort (write failures are ignored -
the socket may already be gone) and the TransportClosedException the connection layer relies on
to reconnect is unchanged.
[bugfix] The per-inbound-chunk pending-message drain no longer scans every live subscription
(#162), a performance regression introduced by #139. To avoid a per-message SplQueue alloc/free,
#139 began keeping each subscription's queue allocated but EMPTY for the subscription's lifetime;
drainAllPending() then iterated array_keys($this->pendingMessages) after every inbound chunk, so
the drain scan became O(all live subscriptions) plus a fresh array_keys() copy of every sid - paid
on every chunk INCLUDING each message-free heartbeat self-read (measured ~213 us/chunk at 10,000
idle subscriptions, ~0 in v2.4.0). The drain now iterates a dirty set of only the sids whose queue
actually holds a message: a sid is recorded when a message is enqueued to it and removed once its
queue drains empty, so the per-chunk cost is O(sids-with-backlog) and a message-free chunk returns
in O(1) with no allocation. #139's no-per-message-realloc win is preserved (the empty queue objects
are still retained; only the scan set changed), and delivery is byte-for-byte unchanged: per-sid
FIFO holds, and cross-sid delivery keeps the ascending-sid (registration) order of the old full-map
scan. The dispatchingSids re-entrancy guard (#112/#156), auto-unsubscribe completion (#112), and
drain()'s bounded backlog round-up (#149/#150) are unaffected - hasUndeliveredDrainBacklog() now
keys on the same dirty set, staying consistent with what the drain iterates.
[bugfix] Restore inbound hot-path throughput lost in #140 and drop the extra per-chunk read
fiber (#163). First, ProtocolParser::splitControlLine() tokenized MSG/HMSG control lines with an
explode(' ') + per-token canonical scan fast path that measured slower per line than the
preg_split('/\s+/') it replaced on a PCRE-JIT build (roughly 5-7% on typical single-space lines
and larger on non-canonical lines; JIT is on by default since PHP 7.3 and this package requires
8.2+): the canonical scan cost more than the JIT-compiled regex on typical single-space lines, and
any non-canonical line then ran preg_split() anyway. The split reverts
to preg_split('/\s+/'), which is byte-identical to the fast path for every input (the fast path
already fell back to this exact call off the canonical path), so the whitespace tolerance is
unchanged - multi-space, tab, and other whitespace runs still separate fields, pinned by the
differential fuzz and the tokenization tests - and only the speed changes. Second,
AmpSocketTransport::readLine() wrapped the socket read in its own async(), so each inbound
chunk spawned a SECOND fiber on top of processIncoming()'s read fiber; the read now runs inline
in the caller's fiber and returns an already-resolved future (mirroring the write path #136),
removing one fiber and future allocation per chunk. Read cancellation (a bounded read's timeout
still surfaces as CancelledException), EOF-to-TransportClosedException, and the empty-string
no-socket poll all still surface through the returned future exactly as before.
[bugfix] Frames the server coalesces BEHIND the handshake PONG in one TCP segment are no longer
dropped, and a frame left partly buffered at the handshake boundary no longer corrupts the stream
(#157). awaitInitialPong() returned the moment it saw the PONG, discarding every frame the parser
had already extracted after it in the same batch - an async INFO with connect_urls, a lame-duck
notice, an -ERR - so discovered cluster peers vanished with no trace. Separately, connectOnce()
then replaced the parser wholesale to couple the frame bound to the negotiated max_payload; if
the handshake segment ended mid-frame, those buffered bytes were thrown away, the next read resumed
at an arbitrary offset, parsed a bogus control line, and raised a spurious ProtocolException that
forced an unnecessary reconnect. awaitInitialPong() now hands the frames parsed behind the PONG
back to connectOnce(), which dispatches them through the normal enqueue/deliver path (an INFO
updates the discovered-server pool; a MSG reaches its handler); and the post-handshake bound change
is applied in place on the same parser (ProtocolParser::setMaxFrameSize()) instead of replacing
it, so a partial trailing frame completes cleanly on the next read. The connect-start parser reset
(#125) is preserved, so no framing state leaks across a reconnect. A lame-duck INFO coalesced behind
a RECONNECT PONG, now dispatched during connectOnce(), would ask to reconnect while a recovery was
already running on the same fiber; that re-entrant request is guarded to a no-op so the in-flight
recovery still completes instead of deadlocking on its own future.
[bugfix] Frame-dispatch errors and a discarded inbound backlog can no longer vanish silently
(#158), closing three gaps in tension with the "a drop must never be silent" principle (#134).
First, the per-chunk finally { drainAllPending(); } in processIncoming() could REPLACE the
in-flight dispatch exception: when a fatal frame (a server -ERR, a PONG-write failure) had thrown
and a handler then threw while the enqueued backlog drained, PHP propagated the finally's exception
and swallowed the fatal one, so the connection continued as if the server never errored. The drain
is now contained so a handler failure during it is routed to the error listener and the primary
dispatch exception still reaches the caller's escalation path. Second, dispatchFrames() kept only
the FIRST failure (rethrown after the loop) and dropped the second and later frame failures from the
same chunk without a trace; each suppressed failure is now emitted through the error listener (the
first is still rethrown). Third, a terminal close reached from reconnect exhaustion, an auth abort,
or reconnect being disabled cleared the parsed-but-undelivered INBOUND backlog silently, asymmetric
with the loud OUTBOUND reconnect-buffer discard (#123); such a close now emits an error naming the
count of inbound messages being discarded before releasing state (drain()'s own bounded-deadline
discard (#149) and disconnect()'s documented nats.go Close() parity path are unchanged).
[bugfix] drain() no longer silently discards the backlog of a subscription whose handler is
suspended mid-dispatch (#149). When a handler awaited inside the dispatch loop while messages
were still queued for its sid, the dispatchingSids re-entrancy guard made drain()'s final
delivery skip that sid, releaseRuntimeState() then cleared the subscription registry, and the
resumed dispatch loop broke on the missing subscription - dropping the remainder on the
documented lossless path. drain() now waits for every in-flight dispatch to finish and every
sid's queue to empty before releasing state (nats.go Drain() waits for per-subscription
delivery to complete before closing). The wait is bounded by a single overall drain budget
computed once at entry - one deadline covers BOTH the flush-wait and the backlog-wait phases, so
total drain time cannot exceed ~requestTimeoutMs (the earlier fix added a second sequential
deadline that roughly doubled worst-case drain latency). When a handler stays suspended PAST that
deadline so the remaining buffered messages cannot be delivered, drain() no longer drops them
silently: it counts the still-buffered messages and emits an error naming that count ("drain
deadline exceeded: N buffered message(s) were not delivered before close") through the error
listener before closing, so the loss is always observable (mirrors the #123/#134 observable-drop
principle).
[bugfix] drain() no longer breaks when a handler publishes during the drain (#150). A
JetStream ack, a Service reply, or NatsMessage::respond() invoked from a handler while the
connection is Draining previously threw ConnectionException ("Connection is not open"): the
publish path only wrote to the socket when Open and only buffered while a reconnect was in
flight. The unguarded final backlog delivery then propagated that exception out of drain(), so
releaseRuntimeState()/transport->close() never ran - the connection stranded in Draining
with the socket open and the delivered-but-unacked message was redelivered by the server. Now a
publish during Draining writes straight to the still-live socket (nats.go drains by publishing
then closing), and drain's final delivery is contained per pass so a handler exception is routed
to the error listener while drain() always reaches Closed. A publish after the connection has
Closed still throws (#146); pong-slot correlation (#117) and auto-unsubscribe counting (#112)
are preserved.
[bugfix] JetStream push/ordered subscriptions now run an idle-heartbeat watchdog, so a consumer
that stops delivering is no longer silently dead forever (#113). An ordered consumer, and any push
consumer the caller created with idle_heartbeat, receives a status-100 heartbeat at least every
interval while it is alive; previously nothing noticed when those heartbeats STOPPED, so a
consumer reaped after an inactive_threshold lapse, a mem_storage R1 ordered-consumer restart,
or an interest gap left the client holding a live core subscription to a deliver inbox no consumer
would ever publish to again - no data, no heartbeat, no error, forever. The sequence-gap logic
could never catch this because it only runs when a frame arrives. A monotonic watchdog now fires
when no frame (data, heartbeat, or flow-control) has arrived for two heartbeat intervals: for an
ordered consumer it triggers the same recreate path the gap logic uses (resuming from the last
in-order point via opt_start_seq), matching nats.go's ErrConsumerNotActive monitor; for a
caller-owned push consumer, which the library cannot recreate, it surfaces a descriptive
"not active" error through the error listener. The watchdog rearms on every inbound frame (so a
quiet-but-alive consumer is never falsely recreated), fires at most once per silence episode (no
recreate/error storm; a failed recreate falls back to the existing bounded-retry + error-listener
path), and holds the connection weakly and self-cancels the moment its subscription is torn down,
so it never leaks a timer or roots an abandoned connection (mirroring the #126 ping timer).
subscribeOrderedConsumer() gains an optional idleHeartbeatNs argument to tune the interval, and
KV watchers now request a default idle heartbeat too (tunable via the new
KeyWatchOptions::$idleHeartbeat), so a silent or reaped watch surfaces a "not active" error instead
of hanging forever - previously the default KV watch requested no idle heartbeat, so total silence
was indistinguishable from an idle stream and no watchdog armed. The ordered-consumer recreate is
serialized by an in-flight guard so the dispatch-handler (sequence-gap / tail-gap) and watchdog-timer
paths cannot both drive a recreate at once and orphan a transient ephemeral consumer, and a
successful recreate clears the miss latch and rebases the silence clock so the watchdog re-arms for
the new consumer - a replacement reaped again before its first heartbeat is recovered rather than
leaving the watchdog wedged. The watchdog also rebases (and neither fires nor cancels) while the
connection is mid-reconnect, so it survives a transient reconnect.
[bugfix] flush(), drain(), drainSubscription(), and rtt() now correlate PONGs to
their PINGs through a FIFO slot queue (nats.go nc.pongs parity) instead of shared booleans
that ANY PONG cleared (#117). Previously a stale PONG - one answering an earlier heartbeat
PING whose bounded self-read timed out without consuming it, or a previously timed-out flush's
PING - satisfied the wait immediately, so flush() returned before the server had processed
the writes issued after that older PING, and drain()/drainSubscription() closed or dropped
state with in-flight MSGs still unread: silent loss on the documented lossless path. A
concurrent flush timing out also cleared the shared flag, releasing sibling flushes that had
seen zero pongs. Now every outbound PING (heartbeats included, as placeholder slots) occupies
one queue position, the PONG handler completes the oldest slot (TCP preserves PING/PONG
order), a timed-out flush leaves its slot queued so its late PONG cannot release a later
waiter, and every epoch end (reconnect handshake, terminal close) errors out all parked slots
so a flush caught mid-reconnect fails fast with ConnectionException instead of idling out
its deadline against the new socket. The maxPingsOut liveness watchdog still resets on any
PONG.
[bugfix] Pull-consumer robustness (#153): the 409 pull statuses "Message Size Exceeds
MaxBytes" and "Batch Completed" are now classified as pull-completion statuses instead of
terminal errors, so an infinite consume() loop with setMaxBytes() survives an oversized
pending head message and keeps pulling (nats.go excludes ErrMaxBytesExceeded/
ErrBatchCompleted from terminal handling); genuinely terminal 409s (Consumer Deleted,
Consumer is push based) still stop the loop. Infinite mode also paces immediately answered
empty pulls - a setNoWait(true) loop against an idle consumer used to busy-poll the server
with an unthrottled 404/re-pull storm, and the non-terminal 409s re-pulled just as hot. Each
consecutive empty window now backs off with an escalating delay (10ms doubling, capped at
500ms, reset on delivery), settling an idle consumer at about 2 pulls per second.
[bugfix] Pull idle heartbeats (#153): fetchBatch()/fetchNext() now validate the ADR-13
rule idle_heartbeat <= 50% of expires client-side and reject violations (and non-positive
values) with a clear InvalidArgumentException instead of forwarding a value the server
refuses. When idle heartbeats are requested, the fetch loop now tracks frame arrivals on the
reply inbox (heartbeats included) and fails fast with a "missed idle heartbeats"
JetStreamException once two heartbeat intervals pass in silence (nats.go ErrNoHeartbeat
parity) - previously status-100 frames were discarded untracked and a dead server/route left
the fetch waiting out the full expires+grace deadline. A partial batch collected before the
silence is still returned.
[bugfix] A reconnect now stays in Connecting until the subscription replay and the
reconnect-buffer flush have completed, and flips Open (arming the ping timer) only then -
nats.go RECONNECTING parity. Previously connectOnce() flipped Open before the replay ran,
with three consequences (#148): a publish from a concurrent fiber during the replay wrote
straight to the wire ahead of the buffered earlier publishes, inverting per-publisher ordering
and breaking JetStream Nats-Expected-Last-Subject-Sequence chains; a replay-leg failure left
state = Open plus an armed ping timer on a dead socket for the whole backoff window, so user
publishes surfaced spurious write errors instead of buffering; and the replay's own poll reads
could collide with a user read admitted by the premature Open (Amp PendingReadError),
aborting an otherwise-successful attempt. Publishes issued during the replay window keep
buffering and the flush now drains in a loop, so frames appended mid-flush still go out - in
publish order - before the connection opens. The heartbeat self-read additionally re-checks the
state after its PING write, so a tick that raced into a recovery cannot read against the
recovery's socket (#148).
[bugfix] A message handler throwing during the post-recovery delivery drain no longer closes
a healthy, fully recovered connection: the exception used to escape recoverConnection() into
its callers' failure handling, so the heartbeat paths (pingTimerTick() maxPingsOut escalation
and consumeHeartbeatResponse() peer-closed recovery) flipped a SUCCESSFULLY recovered
connection to Closed on a live socket - with no Closed event and no runtime-state release -
and publish()'s write-failure retry surfaced an unrelated handler exception for a frame that
was neither written nor buffered. Handler exceptions from that drain are now contained inside
recoverConnection() and reported through the error listener (nats.go parity: handler errors
during post-reconnect delivery are async errors, not connection failures); genuine recovery
failures (exhaustion, auth, reconnect disabled) still throw unchanged (#144).
[bugfix] connect() no longer races an in-flight recovery (nats.go conn.mu parity). Calling
connect() while a recovery was mid-flight (backoff, dial, or handshake) started a second
concurrent connectOnce() chain against the same transport and parser; the recovery loop's next
attempt then closed the healthy socket the user's connect() had just established and replayed
only the pre-outage subscriptions, silently losing every subscription created on the new epoch
(a runtime repro observed 4 dials for one outage). connect() now joins the in-flight recovery
and shares its outcome, a concurrent connect() awaits the first dial instead of dialing in
parallel, and connect() during drain() throws ConnectionException
(Cannot connect: drain in progress) instead of dialing into the teardown. Re-entry semantics:
a connect() called from a connection/error listener throws ConnectionException instead of
joining - the listener runs inside the connecting/recovery fiber, so awaiting the join there
could never complete (a permanent deadlock, including when the terminal Closed event is emitted
by a failed initial connect); schedule supervision reconnects with Revolt\EventLoop::queue()
and do not await the scheduled connect from inside the listener. The in-flight connect()
deferred is now settled (and cleared) before every synchronous lifecycle emission
(Connected/Closed), so it is never pending while a listener runs - closing the deadlock at its
source in addition to the fiber guard. A dial that ends without the connection Open (a recovery or
coalesced connect aborted by a concurrent disconnect()/drain()) throws ConnectionException
("aborted before the connection opened") - for the OWNER connect() (whose owned recovery was
aborted mid-flight) exactly as for joiners, so an aborted owner no longer resolves as success on a
Closed connection. The reverse direction is guarded too: recoverConnection() ignores recovery
requests from stale failure continuations (a write/read that suspended before a terminal close and
resumed failing later) while a user connect() is dialing - but that guard now also requires the
state not be Open, so a genuine live-epoch failure while a Connected listener is still parked
starts a recovery instead of being swallowed onto a dead socket. The closing = false reset also
moved onto the fresh-dial path only, so a connect() racing a concurrent disconnect() can no
longer disarm the user's close intent and let the recovery re-open a connection the user just
closed - close intent wins and the connection stays Closed. A manual connect() after a
terminal close (exhaustion, reconnect disabled, auth failure, user close) still starts a clean
epoch exactly as before (#145).
[bugfix] Ordered consumer: a TimeoutException or ConnectionException from the best-effort
deleteConsumer() leg of a recreate (sequence-gap or heartbeat tail-gap recovery) no longer
bypasses the create-retry loop and permanently silences the consumer. Those exceptions extend
NatsException, not JetStreamException, so the delete-leg catch missed them and the failure
fell straight into the outer containment - the terminal "recreate failed" error was emitted with
zero create attempts made, and no consumer, heartbeat, or message would ever arrive on the
deliver inbox again. The delete leg now tolerates any failure (a timed-out delete may well have
succeeded server-side), so control always proceeds to the create attempts and the terminal error
is emitted only when the create leg itself is exhausted (#151).
[bugfix] The reconnect-disabled terminal path in performRecovery() now closes the transport
best-effort and releases runtime state, matching every other terminal transition to Closed
(the #127/#133 invariant). Previously the socket stayed pinned open and
subscriptions/subscriptionMeta/pendingMessages (handler closures and payload bytes)
survived the close, so a later manual connect() could deliver frames carrying the dead
epoch's sids to stale handlers. The Reconnect is disabled exception and Closed-event
semantics are unchanged. bufferFrame() additionally refuses publishes once the state is
Closed, so a publish racing a terminal path's transport-close await fails loudly with
Connection is not open instead of buffering bytes the state release would silently
discard (#146).
[bugfix] A parse failure no longer silently discards valid sibling frames from the same
chunk: ProtocolParser::push() retains frames parsed before a mid-chunk ProtocolException
(drained via takeParsedFrames(), or prepended to the next push() result), and every read
path that can hit one - processIncoming(), the heartbeat self-read, and the reconnect
subscription-replay poll - now delivers them to their handlers instead of dropping them: their
bytes are already consumed, and core NATS never resends, so they were permanently lost. The
ProtocolException surfaces through the error listener on each of those paths instead of
vanishing, and on processIncoming() the error emission and the recovery both run even when a
handler throws while the recovered frames are delivered (the handler's exception still
propagates afterwards, matching #128's containment semantics) (#147).
[bugfix] BatchPublisher::commit() now pre-flights the INFO-advertised server version and
throws UnsupportedFeatureException BEFORE anything reaches the wire when the connected server
is parseably older than 2.12 (#152). Previously the pre-2.12 detection (#130) fired only on the
reply to the batch START request - by then the old server had already durably stored the start
message as a plain publish, leaving one orphan message in the stream on the "nothing" path of an
all-or-nothing API (and a silent plain publish for a single-message batch). Version parsing is
numeric-prefix (nats.go-style): pre-releases such as 2.12.0-beta.1 count as 2.12 and proceed;
unparseable versions (proxies, custom builds) and mixed-version clusters where the JS leader is
older than the connected server still fall through to the reply-shape detection as defense in
depth. Also documents that BatchPublisher::MAX_MESSAGES = 1000 is ADR-50's server DEFAULT
batch limit, not a protocol constant - the server's error reply stays authoritative for the
configured limit.
[bugfix] JetStream errors: the API error envelope's stable err_code (ADR-1) is now parsed at
every envelope decode site and exposed via the new JetStreamException::getErrCode() accessor
(null when the envelope carried none or the error is client-side). Error-kind discrimination now
matches err_code first - createOrUpdateStream() detects "stream name already in use" by 10058
and KV createKey() detects "wrong last sequence" by 10071 - falling back to description
substrings only when err_code is absent (old servers), so server rewording no longer breaks the
create-or-update and exclusive-create semantics. The previous KV check compared getCode() to
10071 and could never match a real server rejection (those carry the HTTP-like 400). The synthetic
"Key already exists" exception now carries 400 in getCode() and 10071 in getErrCode() instead
of minting an API err_code into the transport-code slot (#154).
[bugfix] $JS.ACK reply-subject parsing now tolerates trailing tokens:
JsMessageMetadata::fromMessage() and extractStreamSequence() accept the expanded v2 form
with >= 11 tokens
instead of exactly 11 or 12, anchoring field offsets from the front and ignoring everything
after index 10 - nats.go parser parity, whose comment warns the parser must not be strict about
trailing tokens because servers may append them (the 12th, a random suffix, was itself a later
addition). A future server appending a 13th token no longer nulls out every delivery's metadata.
The exact 9-token v1 form is unchanged. Additionally, the ordered consumer's null-metadata path
is no longer a silent trapdoor: a reply subject that claims the $JS.ACK form but cannot be
parsed used to route the message to the handler with BOTH the consumer-sequence gap check and
the stale-consumer filter bypassed and zero errors emitted - the entire ordering guarantee
evaporated quietly. Such a delivery now surfaces a descriptive JetStreamException through the
error listener - once per consumer instance, re-armed on recreate, so an unparseable stream
cannot become an error storm - and the message is still delivered best-effort (at-most-once,
ordering unverified), matching the previous delivery behavior. Parse failures deliberately do
not trigger a recreate: the replacement consumer would produce the same unparseable form, and
the tolerant parser makes the branch nearly unreachable. Absent or plain (non-ack) reply
subjects keep the silent best-effort path (#155).
[bugfix] WebSocket inbound performance for large frames (#164): a single WebSocket frame larger
than 65 535 bytes (which must carry a 64-bit length) used to grow $readBuffer with a
payload-sized .= copy per 8 KiB socket read - superlinear, the #140 issue the TCP path already
fixed. Such a frame is now sized from its header (WebSocketFrameCodec::frameRequiredBytes()) and
its remaining reads accumulate in a chunk list joined exactly once by a new spanning-consume path,
so each payload byte is copied a bounded number of times regardless of how many reads it spans;
fragmented-message continuation payloads likewise collect in a list joined once at the final
fragment. Frames that fit a 7-bit or 16-bit length (<= 65 535 bytes, including every fragmented
message's per-frame payloads) are inherently bounded and keep the pre-#164 .= + batch-decode
path byte-for-byte - they are never even sized - so the small-frame and fragmented paths are
unchanged. Measured through readLine() fed exact 8 KiB reads by an in-memory socket (medians of
21 interleaved before/after process rounds, min-of-5 each, one pinned core, WSL2/PHP 8.5): a single
10 MB frame drops ~22 ms to ~7 ms (~3x); a 10 MB message fragmented into 8 KiB continuation frames
(~20 ms) and a flood of 100k 200-byte frames (~190 ms) stay at parity (within run-to-run noise).
Outbound masking is unchanged - measured allocator-bound, with no stable win on PHP 8.5 (dropping
the substr trim was within noise at 1 MB and slower at 8 KiB; PHP-level 8-byte-word masking was
~15x slower than the native whole-string XOR). Wire behavior is unchanged, pinned by the existing
decode, reassembly and fragment-bound tests plus new multi-chunk, partial-next-frame,
ping-between-fragments and read-boundary torture pins (a 64-bit-length frame and a large masked
frame in one-byte reads, and continuation-frame headers split across reads).
[bugfix] Auto-unsubscribe armed with max <= already-delivered while a backlog was still
queued no longer over-delivers exactly one message past the cap (#156). drainPendingForSid()
enforced the delivery cap only AFTER delivering each message, so when unsubscribe(sid, max) was
armed with max at or below the current delivered count while messages were still queued,
completeAutoUnsubIfSatisfied() deferred (backlog not yet drained) and the next drain dequeued and
delivered one more message before the post-delivery check fired - contradicting the #112 contract
that the handler is never invoked more than max times. The drain loop now checks the cap at the
TOP of the loop, before dequeuing/delivering, and drops the sid without invoking the handler once
more when delivered >= max (nats.go AutoUnsubscribe gates delivery, not the aftermath). The
existing post-delivery check is preserved for the #112 backlog-flush case where max > delivered
on entry.
[bugfix] SlowConsumerPolicy::Error's overflow drop is now always observable, and its
auto-unsubscribe accounting is documented and self-consistent (#159). The overflowing message is
still lost - core NATS does not resend it - but the loss was surfaced inconsistently: the
polling-queue (SubscriptionQueue) variant threw WITHOUT counting the drop through
droppedCount()/the error listener, so it did not match the observable-drop contract the
DropOldest/DropNewest paths honour (#134). The polling-queue Error variant now counts the drop via
droppedCount() and reports it through the error listener before it throws. Accounting is
deliberately unchanged: the dropped message still counts toward the auto-unsub max at intake
(receivedCounts), exactly like DropOldest/DropNewest and exactly as the server counts a message
the moment it writes it (#112). A client-side drop must NOT roll that count back - doing so would
leave receivedCounts short of the max forever, so completeAutoUnsubIfSatisfied() would never
fire and the subscription would leak (the #112 invariant). The documented, tested semantics: an
Error-policy auto-unsub can therefore complete having delivered fewer than max messages, with each
overflow surfaced loudly rather than lost silently. On the push (handler) path the overflow is
surfaced exactly once - the thrown ConnectionException is rethrown to the caller (or, for a second
frame in the same chunk, reported through the error listener) by dispatchFrames() (#158); the
connection layer no longer also emits that same exception, which would have reported it twice. The
per-subscription pending bound is message-COUNT based only; there is no byte-based bound (nats.go's
pending limits are both count- and byte-based).
[bugfix] requestMany() no longer returns more than maxResponses when replies coalesce into a
single TCP chunk (#160). The inbox collector appended every reply unconditionally while the wait
loop enforced the cap only between reads, so one processIncoming() dispatching several replies
could return more than requested. The collector now caps at maxResponses, dropping replies past
the limit; stall/total-deadline semantics for under-cap collections are unchanged.
Patch release: fixes static analysis under PHPStan 2.2.5.
Patch release: fixes static analysis under PHPStan 2.2.5.
JsMessageMetadata::fromMessage() rewritten with literal token offsets per count() branch so PHPStan 2.2.5's stricter array-shape inference can prove every access. Byte-identical $JS.ACK parsing (pinned by the existing 9/11/12-token tests).v2.5.0's code failed CI's Unit + Static jobs because CI resolves dependencies fresh and picked up PHPStan 2.2.5, while the release gate had run against an older local vendor. This release is CI-verified green across the full matrix (PHP 8.2-8.5, E2E, Examples, Mutation): all functional changes are identical to v2.5.0 - see its notes for the full changelog of the 21-issue review cycle.
[bugfix] Static analysis: JsMessageMetadata::fromMessage() rewritten with literal token
offsets per count() branch so PHPStan 2.2.5's stricter array-shape inference can prove every
access (the shared base-offset arithmetic tripped offsetAccess.notFound and failed CI's
Unit + Static jobs; CI resolves dependencies fresh and picked up 2.2.5 while the local gate
ran an older vendor). Byte-identical parsing behavior, pinned by the existing 9/11/12-token
ack-subject tests.This release closes all 21 findings of the 2026-07-11 six-dimension review (#123-#143) plus the three in-flight fixes from the previous cycle (#112, #
This release closes all 21 findings of the 2026-07-11 six-dimension review (#123-#143) plus the three in-flight fixes from the previous cycle (#112, #114, #116): every silent message-loss path found in the connection layer is fixed, the client survives abandonment and terminal closes without leaking, JetStream/KV behavior moved to spec/ADR parity, and the hot paths got measured performance work.
write() on a closed/never-connected socket throws instead of silently "succeeding" while sending nothing; recovery flips the connection off Open before its first await so concurrent publishes buffer instead of racing the dying socket (#124).-ERR); the heartbeat read now reports fatal frames instead of swallowing them (#128).subscribeQueue() buffers deliveries that arrive before the queue object exists (#129).UnsupportedFeatureException on servers without batch support instead of silently storing the batch message-by-message (#130).Closed releases runtime state; a manual connect() after reconnect exhaustion starts clean instead of resurrecting dead-epoch subscriptions as duplicate-delivering ghosts (#127).$JS.API subjects or silently read a sibling stream via direct get (#131).idle_heartbeat honored and unknown pull-request keys rejected, ordered consumers pin num_replicas: 1, KV buckets are created with deny_delete/discard: new, KV keys enforce the ADR-8 charset, HPUB is guarded by the server's headers capability, service stats report real UTC, and the README documents the NATS 2.9+ consumer-management floor (#132).SubscriptionQueue are observable via droppedCount() and the error listener; disconnect/unsubscribe backlog-discard semantics are documented (#134).pingIntervalSeconds now accepts int|float, the release's one [feature]), ~250 rotted line-number pins fixed, behat tolerates exception subclasses (#142).composer infection no longer dies at Composer's 300 s process timeout.Full details in CHANGELOG.md. All 21 fixes shipped with falsifiability-verified regression tests (each demonstrated to fail against the pre-fix code) and were gated on phpstan level 8, the unit suite, and the live integration suite against NATS 2.12.
[feature] NatsOptions::$pingIntervalSeconds now accepts int|float, so sub-second heartbeat
intervals (e.g. 0.05) are expressible; integer values keep working unchanged (backward
compatible for every existing caller) and 0 still disables the heartbeat. The underlying
timer (EventLoop::repeat()) and the heartbeat read budget already operate on floats, so no
runtime behavior changes for existing configurations. Motivation (#142): the integer floor made
1 s the minimum observable interval, forcing every ping-timer unit test to wall-clock-sleep past
it (~10 s per unit-suite run); those tests now run 50 ms intervals with the same deterministic
assertions.[bugfix] Concurrent requests no longer poll: a request waiting while another fiber owns the
socket read used to wake every 1ms (allocating a Future per wakeup), so N concurrent requests
burned O(N x 1000/s) wakeups - a KV getAll() on a large bucket became CPU-bound. Waiters now
park on their reply or on a read-slot-release signal and one of them takes over the read pump
when it frees; requestMany() waiters additionally wake per delivery so stall detection is
unchanged. Measured with 200 concurrent requests idling 300ms against a live server: CPU time
dropped from 425ms (a full core for the whole window) to 92ms (#135).[bugfix] The outbound hot path no longer stacks 2-3 async() fiber hops per message (#136):
transport write() runs inline in the caller's fiber and returns an already-resolved future
(failures still surface through the future, never as a synchronous throw, so the #124 error
contract is unchanged), and the JetStream ack/nak/term/inProgress helper returns the publish
future directly instead of wrapping a third fiber around a replyTo null-check. Publish and
request-target subjects are also memoized after first validation (bounded at 512 entries, full
reset at the cap) so repeat publishes skip the regex + per-token scan; per-request reply inboxes
are never cached. Measured against a live server: 50k serial small publishes went from ~4.5s
wall / ~4.4s CPU (~11k msg/s) to ~3.9s / ~3.8s (~13k msg/s), and a 5k serial JetStream
fetch-and-ack loop from ~1.0s wall / ~0.9s CPU (~4.9k acks/s) to ~0.5s / ~0.5s (~9.2k acks/s).[bugfix] Reconnect subscription replay no longer has a ~5ms x N-subscriptions latency floor
(#137): resubscribeAll() used to issue an awaited SUB write (plus the optional #112 UNSUB
re-arm) and then a ~5ms drain poll per sid - with verbose off the server sends nothing after a
successful SUB, so the poll always ate its full timeout serially inside the reconnect critical
section (publishes buffering, no dispatch; 500 subscriptions added ~2.5s of blackout). The
replay is now coalesced into O(1) transport writes - one buffer with every SUB (+UNSUB re-arm)
frame, byte-identical on the wire and in order - followed by a single bounded drain poll, so
prompt -ERR responses still abort the attempt exactly as before.[bugfix] BatchPublisher::commit() no longer sends each intermediate batch message as its own
awaited write (#138): per ADR-50 only the start and commit legs are request/reply, yet every
intermediate paid ~1 syscall + 2 fiber hops, so a max-size 1000-message commit burned ~998
unnecessary syscalls of pure overhead in the library's designated atomic bulk API. The
intermediates are now coalesced into bounded segments (at most 512 KiB per segment, so a
1000 x 1MB batch never concatenates into a ~1GB string) and each segment goes out as ONE
transport write - byte-identical HPUB frames, same order, same batch headers. Per-message
subject and max_payload validation now runs for the WHOLE block before any intermediate hits
the wire, and the start/commit request legs (including the #130 pre-2.12 guards) are unchanged.
Measured against a live 2.12 server: a 1000-message commit (128-byte payloads) dropped from
~55ms to ~21ms median wall time.[bugfix] JetStream push deliveries (push consumers, ordered consumers, KV watches) no longer
pay a per-message async() hop and duplicate parsing (#139): the push control-frame check runs
synchronously in the dispatch fiber instead of spawning a fiber per message (a Future allocation,
an event-loop hop, and at least one added tick of delivery latency each) and skips header parsing
entirely for header-less data messages - the overwhelmingly common delivery; the rare
flow-control/stalled acks are still sent, byte-identical. The ordered consumer reads
Nats-Last-Consumer from the control frame's already-parsed headers instead of re-parsing the
block, NATS header blocks are split with explode("\r\n") instead of preg_split (same pieces,
cheaper), and a subscription's pending-message queue is now reused across drains instead of being
freed when emptied and reallocated on the next delivery. Measured with an ordered consumer
receiving 20k small messages from a live server (window includes the 20k publishes): median wall
2.20s -> 1.95s and CPU 2.06s -> 1.80s, ~9.1k -> ~10.3k msg/s end to end.[bugfix] Inbound micro-overheads roundup (#140), behavior-identical: MSG/HMSG control lines are
tokenized with a plain explode(' ') fast path instead of preg_split('/\s+/') per message
(~5-10% of a core at 100k msg/s), falling back to the regex whenever the space-split result shows
an empty token, a wrong token count, or embedded non-space whitespace - so tab/multi-space
leniency is preserved bit-for-bit; the per-frame strtoupper() verb fold is skipped when the verb
already matches a canonical upper-case form. While a large MSG/HMSG payload is incomplete,
subsequent socket chunks accumulate in a list joined once on completion instead of growing the
buffer with a copy per 8 KiB read (measured ~2-3x constant-factor overhead on multi-MB frames).
Service endpoints no longer parse request headers (observer context / correlation id) on every
request: the context is resolved lazily and memoized, so a service with no observers and a
successful handler skips the parse entirely, while observer events and error-reply correlation
ids are unchanged.[bugfix] SubscriptionQueue slow-consumer drops are no longer silent (#134): an overflow under
DropOldest/DropNewest now reports through the client's errorListener and logger with the
same "Slow consumer on sid ..." debug-level signal the connection layer already emits for its own
queue, and a new monotonic SubscriptionQueue::droppedCount() lets polling consumers detect
delivery gaps. This matters because for subscribeQueue() consumers the connection queue drains
into this second-level queue on every processIncoming() cycle - so this is where real overflow
lands, and it previously produced no signal anywhere. The Error policy is unchanged (it already
throws).[bugfix] Resource-release roundup from the July review (#133): keyValue()/objectStore()
no longer memoize bucket wrappers - the per-name cache had no eviction (not even
deleteBucket()), so a long-lived client touching many bucket names (e.g. one per tenant)
retained one wrapper per name forever; the wrappers are all-readonly value objects, so a fresh
instance per call is behavior-equivalent. Every terminal connect/reconnect failure (failed
initial connect, exhausted or auth-aborted recovery) now closes the transport socket
best-effort, mirroring disconnect() - previously the last failed attempt's socket stayed
pinned by the transport until the client object was GC'd. BatchPublisher::commit() releases
the staged payloads once the batch is sent - a retained committed publisher (e.g. kept keyed by
batchId() to correlate acks) previously pinned up to 1000 full payloads for its lifetime; as
a consequence, count() now returns 0 after commit() (it previously kept reporting the
staged total).[bugfix] fetchBatch()/fetchNext() no longer silently drop unrecognized $pull fields: an
unknown key now throws a JetStreamException naming the offending key and the supported set, so
a typo (or a field this client does not implement) can no longer make the caller believe the
option took effect - a bug-driven behavior change treated as a bugfix. The ADR-13 idle_heartbeat
field (nanoseconds) is now an accepted pull-request field and reaches the wire (the fetch loop
already absorbs the resulting status-100 heartbeat frames). Ordered consumers additionally pin
num_replicas: 1 (ADR-17 / nats.go ordered.go parity), so an interest-retention stream's
replica count is no longer inherited by the ephemeral ordered consumer (#132).[bugfix] Spec-conformance corrections from the July review (#132): KV create() defaults now
include deny_delete: true and discard: new (ADR-8 / nats.go CreateKeyValue parity; both
stay user-overridable, discard: new expects NATS server 2.7.2+), so bucket revision history can
no longer be deleted out from under other tooling and a full bucket rejects writes instead of
silently evicting old keys. KV key validation is tightened to the ADR-8 rules (charset
[-/_=.a-zA-Z0-9], reserved _kv prefix rejected), so entries written from PHP can no longer be
unreadable via nats.go/nats.java/the nats CLI. Publishing with headers against a server whose
INFO advertises "headers": false now fails client-side with a clear ConnectionException
(nats.go ErrHeadersNotSupported parity) instead of the server killing the connection on an
unknown HPUB operation. The services framework started timestamp is now generated in UTC, so
its RFC3339 Z suffix is truthful on non-UTC hosts (ADR-32) and nats micro shows correct
uptimes.[bugfix] JetStream stream and consumer (durable) names are now validated client-side before
being interpolated into a $JS.API.* subject, rejecting empty names and names containing
spaces, tabs, CR/LF, ., *, >, / or \ (nats.go checkStreamName / checkConsumerName
parity). Previously a dotted name silently changed which API endpoint the request hit:
createConsumer('S', 'a.b') was routed by the server as the filtered-create form (consumer
"a", filter "b"), getConsumer()/deleteConsumer() for that name hit no API route at all and
surfaced a misleading 503 "subject is not bound to a stream", and directGetStreamMessage() on
a dotted stream name could be routed as DIRECT.GET.<stream>.<last_by_subject> and silently
return data from a SIBLING stream (#131).[bugfix] Atomic batch publish no longer degrades silently to non-atomic storage on servers
without batch support (pre-2.12): such a server treats Nats-Batch-* headers as opaque and
acknowledges the batch start/commit as plain publishes, and commit() previously reported
success while the "batch" had been stored message-by-message. The batch start now requires
ADR-50's zero-byte ack (a normal PubAck aborts with UnsupportedFeatureException carrying the
server version, before the remaining messages are published), and a multi-message commit ack
must carry the batch id/count. The README "Server Version Requirements" section and the
JetStreamContext::batch() docblock now describe when UnsupportedFeatureException can
actually fire per feature class (#130).[bugfix] NatsClient::subscribeQueue() no longer silently drops messages delivered between
the SUB hitting the wire and the SubscriptionQueue object being constructed: the subscription
handler is registered before the SUB write (so the sid is immediately routable, and a concurrent
read or the heartbeat self-read can dispatch for it while subscribeQueue() is still suspended),
but the handler discarded anything arriving before the queue existed. Early deliveries are now
buffered and replayed into the queue (through the normal cap and slow-consumer policy) (#129).[bugfix] An exception while handling one inbound frame no longer discards the frames already
parsed from the same chunk. The parser has consumed the bytes, so an undispatched trailing frame
was silently and permanently lost (core NATS does not resend) - e.g. a slow-consumer overflow on
one subscription (Error policy) destroyed messages for healthy sibling subscriptions delivered
in the same TCP chunk, and a failing PONG reply destroyed the messages behind the server PING.
Dispatch is now contained per frame: every frame is handled, buffered deliveries are drained,
and the first failure surfaces afterwards. The heartbeat self-read additionally reports a fatal
frame (e.g. a server -ERR) through the errorListener instead of swallowing it whole (#128).[bugfix] Every terminal transition to Closed now releases per-connection runtime state
(subscription registry and handler closures, queued messages, counters, parser bytes, reconnect
buffer) - previously only user disconnect()/drain() did. An exhausted reconnect or a
terminal auth failure left everything referenced; worse, calling connect() again on the same
instance silently believed it was subscribed (nothing was re-SUBbed) and a later automatic
recovery would resurrect the dead epoch's sids as ghost subscriptions, duplicating deliveries
into stale handler closures. Subscriptions now never survive a terminal close: re-connect()
starts from a clean slate and the application re-creates its subscriptions (nats.go parity,
documented on connect()) (#127).[bugfix] A NatsConnection abandoned without disconnect()/drain() is now garbage-collectable:
the ping timer's repeat closure previously bound $this strongly, so the event loop rooted the
whole connection graph forever - the open socket, every subscription handler closure, and all
buffers leaked per abandoned client, and the zombie timer kept PINGing and even delivering
messages to abandoned handlers (stealing queue-group deliveries from live workers). The timer
now holds the connection through a WeakReference and cancels itself once the application drops
its last reference, and a new destructor cancels the heartbeat and closes the socket
best-effort (#126).[bugfix] The reconnect handshake now starts from a clean protocol parser. Previously the new
connection's INFO/PONG bytes were fed into the parser state left by the dead connection; after a
drop mid-message-payload the pending frame swallowed each attempt's INFO as phantom payload
bytes, so every reconnect attempt failed with "Expected INFO during connect" and the client
closed permanently against a healthy server once the attempt budget was exhausted (#125).[bugfix] Transport write() on a closed/never-connected socket now throws
TransportClosedException instead of silently succeeding (both TCP and WebSocket transports).
Previously a publish, JetStream ACK, or flow-control reply racing a reconnect (or a concurrent
disconnect()) could hit the nulled socket and report success while sending nothing - a silent
message loss. The connection now also leaves the Open state before recovery's first await, so
publishes issued while the dead socket is being torn down are routed into the reconnect buffer
and replayed after the new handshake instead of racing the closing socket (#124).[bugfix] A reconnect-flush failure no longer silently destroys publishes accepted during the
reconnect window: flushReconnectBuffer() cleared the buffer before awaiting the write, so a
socket failure during the flush left the next (successful) attempt with nothing to replay while
every affected publish() had already reported success. The buffer is now cleared only after
the flush write succeeds (a partially transmitted flush may duplicate frames on the retry -
duplication beats loss, matching nats.go pending-buffer semantics), and exhausting reconnect
attempts with a non-empty buffer reports the abandoned bytes through the errorListener and
clears the buffer so a later manual connect() cannot replay frames from a dead epoch (#123).[bugfix] unsubscribe($sid, $max) (auto-unsubscribe) sent UNSUB <sid> <max> but dropped the local
handler immediately, so every message the server legitimately kept delivering up to the max was
silently discarded. The handler now stays registered until $max total messages have been received
(nats.go AutoUnsubscribe parity), a reconnect re-arms the server with the remaining allowance, and
reaching the max removes the subscription locally (#112). The accounting is anchored to messages
received (not delivered), so a message dropped by the slow-consumer policy still advances toward
the max exactly as the server counts it - without this, under the default DropOldest policy the
subscription could stall below its max forever (a permanent leak) and a reconnect would re-arm and
over-deliver live messages past the intended max. Handler delivery is separately capped at the max so
a batched-in or replayed extra frame is never over-delivered, and arming while a reconnect is in
flight now defers to recovery instead of destroying the subscription (which would have silently lost
the remaining armed deliveries).[bugfix] Subscription state no longer leaks on failure paths: unsubscribe() releases local state
even when the connection is not open or the UNSUB write fails (previously it threw first, leaking the
entry and its handler closure, and resubscribeAll() would revive dead inboxes as ghost
subscriptions), and subscribe() rolls its registry entry back when the SUB write fails.
unsubscribe() on a connection that is not open now cleans up silently instead of throwing
ConnectionException - a bug-driven behavior change treated as a bugfix (#116).[bugfix] A failed ordered-consumer recreate (after a sequence gap) is no longer silently swallowed:
the create is retried up to 3 times with backoff and a terminal failure is surfaced through the
configured errorListener, so the application learns the consumer went permanently silent instead of
waiting on dead air forever (#114). Adds NatsClient::options() exposing the client's runtime options.[docs] New nightly mutation-testing workflow (mutation-nightly.yml, 03:17 UTC daily +
manual dispatch): re-scores the whole unit-covered tree against the 90% MSI gate every day and
uploads the Infection logs as artifacts, catching mutation-score drift between pushes. The
composer infection script now disables Composer's 300 s process timeout, which killed any
full mutation run mid-flight (the full sweep takes ~30 minutes; current score: 91% covered MSI
over 5234 mutants at 100% mutation coverage).[docs] Test-suite hygiene roundup from the July review (#142), dev-only: deleted
testDirectGetBatchDelaysOnZeroFrames, whose assertions could not fail for its stated purpose
(the pacing delay was never observed) while burning ~1 s per run - the sibling
testDirectGetBatchReturnsEmptyArrayOnTimeout keeps the empty/timeout path covered; test
comments no longer pin production line numbers (several were already stale) and reference the
method or branch by name instead - deliberate per-mutant line pins in tests/Unit/Mutation
are exempt; the ping-timer unit tests use fractional 50 ms intervals instead of ~10 s of
wall-clock sleeps (see the pingIntervalSeconds entry above); the behat exception steps
compare via is_a() (instanceof semantics) instead of strict class-string equality, so
introducing a more precise exception subclass no longer breaks scenarios.[docs] The reconnect path is now exercised against a live server (#141): a new
SeveringTransport test decorator over the real AmpSocketTransport force-closes the live TCP
socket mid-session, and two new integration tests (severing mid-idle and mid-traffic) assert the
client observes the genuine EOF, reconnects, replays its subscriptions with a real SUB, and
delivers post-reconnect traffic published from a second independent client. The four scripted
"reconnect" tests that lived in the integration suite but never contacted the fixture (they ran
only against injected fakes, so they were skipped by the local unit gate) were relocated to
tests/Unit/NatsConnectionTest.php; one of them duplicated an existing unit test
(testProcessIncomingReconnectsAndResubscribesAfterReadFailure covers the identical FlakyTransport
script with stronger assertions) and was deleted instead. Dev-only - no runtime/library change.[docs] README fixes: the feature table now shows the real named arguments for KV tombstones
(delete/purge(..., tombstoneTtl:) - the documented ttl: threw "Unknown named parameter"),
and the Schedule FQCN in the scheduling note renders with single backslashes (the doubled
IDCT\\NATS\\... form inside a code span displayed literally and broke copy-paste) (#143).[docs] disconnect() and plain unsubscribe() docblocks (connection and client facade) plus
the README drain section now state that locally queued, undelivered messages are discarded
(intentional nats.go Close()/Unsubscribe() parity) and name drain()/drainSubscription()
as the lossless teardown paths (#134). No behavior change.[docs] The README "NATS Server Version Requirements" section now states the real server floor:
core NATS works against any server, but all JetStream consumer helpers use the 2.9+ named
CONSUMER.CREATE API with no fallback to the legacy DURABLE.CREATE form, so consumer
management requires NATS 2.9+ (documented in the feature table; pre-2.9 servers fail with a
generic 503, not an UnsupportedFeatureException) (#132).Patch release - test/CI and documentation only. No library or runtime change; safe drop-in for any 2.4.x user.
Patch release - test/CI and documentation only. No library or runtime change; safe drop-in for any 2.4.x user.
tests/Unit/Mutation/ raised the suite's mutation score (Covered MSI) from 75% to 93%, killing ~870 previously-surviving mutants. A dedicated mutation CI job fails the build below 90% MSI - a quality bar on top of line coverage that catches assertions which pass but don't actually pin behavior.require-dev, so composer install still works on PHP 8.2; the mutation job runs on PHP 8.3 and installs Infection itself.ideaconnect/made-in-the-eu repository.µs duration unit is left intact).Full changelog: CHANGELOG.md - compare v2.4.0...v2.4.1.
[docs] Added mutation testing with Infection (composer infection,
scripts/run-mutation.sh, infection.json5). 517 new unit tests under tests/Unit/Mutation/ raised the
suite's mutation score (Covered MSI) from 75% to 93%, killing ~870 previously-surviving mutants. CI
now enforces a strict mutation gate (a dedicated mutation job that fails the build below 90% MSI) -
a quality bar on top of line coverage that catches assertions which pass but don't actually pin behavior.
Mutation runs against the fast unit testsuite (no Docker); the remaining ~6% are mutants verified to be
equivalent (no observable behavioral difference), documented in each test's reasoning rather than chased
with meaningless assertions. Dev-only - no runtime/library change. PHP 8.2 support is unchanged:
Infection requires PHP 8.3+ and is intentionally not in require-dev, so composer install still works
on PHP 8.2; the mutation CI job runs on PHP 8.3 and installs Infection itself.[docs] Added a "PHP Support Policy" section to the README: the library follows PHP's official release
schedule, so PHP 8.2 support will be dropped by the end of 2026 (when PHP 8.2 reaches end-of-life),
raising the minimum to PHP 8.3 at that point.[docs] Pointed the "Made in the EU" badge at the renamed ideaconnect/made-in-the-eu repository.[docs] Replaced AI-style typography in the README, CHANGELOG, TESTS.md, and PHP docblocks/comments
with plain ASCII: em/en dashes become -, the ellipsis character becomes ..., and arrow / x for the
arrow and multiplication signs. Functional non-ASCII (the µs duration unit, ©, §) is left intact.Minor release: a protocol-parser leniency feature, three robustness bugfixes, and a documentation/CI push that makes every README example a runnable,
Minor release: a protocol-parser leniency feature, three robustness bugfixes, and a documentation/CI push that makes every README example a runnable, CI-verified script.
[feature] The protocol parser now recognizes operation verbs case-insensitively and accepts any whitespace (space or tab) between a verb and its arguments, aligning with the NATS wire spec. Real servers always send upper-case verbs, so this only adds leniency; argument/payload bytes are preserved verbatim. Resolves the long-standing README TODO (now removed).[bugfix] JetStream createStream() no longer rejects an empty subjects list when a non-empty sources configuration is provided — a pure aggregate/sourcing stream legitimately has no subjects of its own (the client previously only exempted mirror).[bugfix] A malformed async INFO frame can no longer throw out of the core processIncoming() read loop; the runtime INFO decode is contained (the bad update is skipped and surfaced via the error listener) so MSG frames parsed from the same chunk are still delivered. Handshake INFO is still validated strictly.[bugfix] WebSocket transport: the frame decoder no longer re-slices the entire remaining receive buffer once per frame — a read carrying many coalesced frames is decoded in O(total bytes) instead of O(frames × bytes).examples/ directory with one runnable, self-contained script per README example (42 files); every script now opens with a file-level intro docblock, and every README example heading links to its matching script ("Runnable example" pointer).scripts/run-examples.sh runs them all against dockerized NATS and reports pass/skip/fail; CI now runs every example as a required, all-must-pass gate (a dedicated examples job, with EXAMPLES_STRICT=1 treating a skipped example as a failure). All 42 examples pass against the full stack.TESTS.md — a catalogue of every unit, integration, and Behat test with a one-line description.Full changelog: CHANGELOG.md · compare v2.3.0...v2.4.0.
[feature] Protocol parser now recognizes operation verbs case-insensitively and accepts any whitespace
(space or tab) between a verb and its arguments, aligning with the NATS wire spec. Real servers always
send upper-case verbs, so this only adds leniency; argument/payload bytes are preserved verbatim. Resolves
the long-standing README TODO (which has been removed).[bugfix] JetStream: createStream() no longer rejects an empty subjects list when a non-empty
sources configuration is provided. A pure aggregate/sourcing stream legitimately has no subjects of its
own (the server allows it); the client previously only exempted mirror, so creating a sources-only
aggregate stream failed with "Stream subjects must not be empty...".[bugfix] Connection: a malformed async INFO frame is no longer allowed to throw out of the core
processIncoming() read loop. Previously a non-JSON async INFO (corruption in flight, or a non-conformant
server push) raised an uncaught JsonException that aborted the read cycle and skipped delivery of the
MSG frames parsed from the same chunk. The runtime INFO decode is now contained (the bad update is
skipped and surfaced via the error listener), mirroring the dispatch-containment principle from #97.
Handshake INFO is still validated strictly and fails the connect on bad JSON.[bugfix] WebSocket transport: the frame decoder no longer re-slices the entire remaining receive buffer
once per frame. A single read carrying many coalesced frames is now decoded in O(total bytes) instead of
O(frames x bytes) by advancing a cursor and trimming once, improving throughput under bursty high-fanout
traffic. Behavior (including the "leave an incomplete trailing frame buffered" contract) is unchanged.[docs] Added TESTS.md - a catalogue of every unit, integration, and Behat test with a one-line
description of what it verifies - linked from the README's test baseline section.[docs] Added an examples/ directory: one runnable, self-contained script per README example (42
files), plus scripts/run-examples.sh which runs them all against dockerized NATS and reports
pass/skip/fail - a gate that keeps the README examples honest. Linked from the README Usage section.[docs] Distributed Counter example now creates its backing stream with allow_direct: true (required
because counterValue() reads via Direct Get); without it the documented example threw "no responders
for $JS.API.DIRECT.GET". Prose updated accordingly.[docs] Each examples/*.php script now opens with a file-level intro docblock describing exactly what
it does and which README section it mirrors.[docs] Every example heading in the README now carries a "Runnable example" pointer linking to the
matching examples/*.php script, so each documented feature is one click from a runnable, verified file.[docs] scripts/run-examples.sh now defaults NATS_NKEY_SEED to the dev seed trusted by
build/nats/nkey.conf, so auth-standalone-nkey.php runs as a real functional test in the dev stack
instead of self-skipping. With this, all 42 examples pass against the full dockerized stack.[docs] CI now runs every example as a required gate (a dedicated examples job in
.github/workflows/ci.yml that boots the full dockerized stack and runs scripts/run-examples.sh).
The runner gained an EXAMPLES_STRICT mode (used by CI) that treats a skipped example as a failure, so
the build fails unless every example actually executes and passes.