skip to content
[idct]
szczecin 53.43N 14.55E ./start-project

php-nats-jetstream-client 2.27: a typed error for the subscription limit

(php, nats, release-notes) 1 min read by Bartosz Pachołek

A SUB beyond the connection's limit now fails with SubscriptionLimitException, so callers no longer have to match error messages.

idct/php-nats-jetstream-client 2.27.0 is a minor release with one change: when the server refuses a subscription because the connection reached its limit, the client now says so with a type.

The problem

NATS 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. The only way to recognise the limit was to match the message.

The change

SubscriptionLimitException is a new final subclass of ConnectionException, and the client now builds it everywhere it builds a limit error:

  • the read that meets the -ERR, whether it throws it or hands it to the error listener;
  • a request whose shared reply inbox was dropped;
  • a pull fetch or batched Direct Get whose reply inbox was dropped;
  • a guarded subscribe whose replayed SUB the new server rejected.

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.

Upgrading

Existing handlers still work. Every catch (ConnectionException) and catch (NatsThrowable) matches and the messages are unchanged; only code that compares the exact class name sees a difference.

bash
composer require idct/php-nats-jetstream-client:^2.27

Quality gates for the release: PHPStan level 8, 3659 unit tests on PHP 8.2 to 8.5, 159 live integration tests, 49 Behat scenarios, every changed line covered and 98.98% total coverage. The full record is in the changelog.