From ec49f8856eac4f67a1ed8370c7fd6b4d3b118265 Mon Sep 17 00:00:00 2001 From: kafkiansky Date: Wed, 11 Nov 2026 17:25:06 +0300 Subject: [PATCH] Add connection options and state: no echo, inbox prefix, drain timeout, status, server info, PSR-3 logger - Config: noEcho (refused by servers without proto 1), inboxPrefix used by every inbox (requests, pull consumers, stream get, KV watch, object store) via Client::newInbox(), drainTimeout bounding Client::drain() (DrainTimedOut, the connection is closed anyway); uri options no_echo, inbox_prefix, drain_timeout - Client::status() returns ConnectionStatus: Disconnected, Connecting, Connected, Reconnecting, Draining - Client::serverInfo() returns the latest INFO of the current server as Nats\ServerInfo, updated by async INFO - Client takes a PSR-3 logger: connected, lost, reconnect attempts, reconnected, closed, discovered servers, lame duck mode and the errors passed to onError - Client::drain() waits for the handlers to finish the received messages before closing --- README.md | 65 ++- composer.json | 1 + src/Client.php | 138 ++++++- src/Config.php | 27 ++ src/ConnectionStatus.php | 24 ++ src/Exception/DrainTimedOut.php | 21 + src/Exception/FeatureIsNotSupported.php | 8 + src/Internal/ClientState.php | 20 + src/Internal/Connection/Connection.php | 3 +- src/Internal/Connection/ConnectionInfo.php | 41 -- src/Internal/Connection/Query.php | 8 + .../Connection/ReconnectingConnection.php | 18 +- src/Internal/Connection/SocketConnection.php | 18 +- src/Internal/Id/generateInboxId.php | 5 +- src/Internal/Rpc/Handler.php | 9 +- src/JetStream.php | 9 + src/JetStream/KeyValue/Bucket.php | 3 +- src/JetStream/ObjectStore/Store.php | 4 +- src/JetStream/PullConsumer.php | 5 +- src/JetStream/Stream.php | 3 +- src/ServerInfo.php | 94 +++++ tests/ConfigTest.php | 44 ++ tests/ConnectionOptionsTest.php | 376 ++++++++++++++++++ 23 files changed, 870 insertions(+), 74 deletions(-) create mode 100644 src/ConnectionStatus.php create mode 100644 src/Exception/DrainTimedOut.php create mode 100644 src/Internal/ClientState.php delete mode 100644 src/Internal/Connection/ConnectionInfo.php create mode 100644 src/ServerInfo.php create mode 100644 tests/ConnectionOptionsTest.php diff --git a/README.md b/README.md index e517caf..12f6acf 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ Pure non-blocking (fiber based) strictly typed full-featured PHP driver for NATS - [Authentication](#authentication) - [TLS](#tls) - [Connect and ping](#connect-and-ping) + - [Connection state and options](#connection-state-and-options) + - [Logging](#logging) - [Reconnect](#reconnect) - [Publish-Subscribe](#pub-sub) - [Queues](#queues) @@ -70,7 +72,7 @@ or `tls://`, which requires TLS (see [TLS](#tls)); `ws://` and `wss://` are reje and the credentials are percent-encoded like in any url (`p%40ss` for `p@ss`). The servers of a list are tried in a random order (in the given one with `noRandomize`, `no_randomize=true` in the uri) until one accepts the connection, see [Reconnect](#reconnect); each one may repeat the scheme and the credentials, as in nats.go (`nats://u:p@h1:4222,nats://u:p@h2:4222`): one user is sent to every server, so different credentials are rejected. The options are the snake_case names of the `Nats\Config` parameters, e.g. `connection_timeout` (seconds, fractions allowed), `request_timeout`, `verbose`, `no_responders`, `ping`, `token`, `jwt`, `nkey`, `credentials_file`, `jwt_file`, `nkey_file`, `client_name`, `allow_reconnect`, `max_reconnects` (negative for no limit), `reconnect_wait`, `reconnect_jitter`, `reconnect_buffer_size`, `no_randomize`, -and the TLS ones `tls_ca_file`, `tls_cert_file`, `tls_key_file`, `tls_key_passphrase`, `tls_verify`, `tls_server_name`, `tls_handshake_first`. +`no_echo`, `inbox_prefix`, `drain_timeout`, and the TLS ones `tls_ca_file`, `tls_cert_file`, `tls_key_file`, `tls_key_passphrase`, `tls_verify`, `tls_server_name`, `tls_handshake_first`. Userinfo without a colon is a token, as in nats.go (`nats://s3cr3t@host`), while `nats://alice:@host` is the user `alice` with an empty password, see [Authentication](#authentication): ```php @@ -173,6 +175,7 @@ so `connect()` fails with `Nats\Exception\ConnectionIsNotAvailable` that says so The client connects lazily, on the first call that needs the server. Call `connect()` to establish the connection at startup instead, so that an unavailable server or wrong credentials fail right away rather than on the first publish. `ping()` sends `PING` and waits for `PONG`: once it returns, the server has processed everything the client sent before (e.g. a subscription is active for the other clients), and it returns the round-trip time in seconds. +It is what `Flush()` is in nats.go. ```php ping(); // The subscription is active on the server now. dump("Round trip: {$rtt}s"); ``` +#### Connection state and options + +`status()` tells whether the client is `Disconnected` (not yet, or closed), `Connecting`, `Connected`, `Reconnecting` or `Draining`, see `Nats\ConnectionStatus`. +`serverInfo()` returns the INFO of the server the client is connected to (version, server id and name, cluster, JetStream, `maxPayload`, the client id the server knows this connection by, the lame duck mode, ...), +the latest one the server has sent, or null when not connected; neither of them connects. + +- `noEcho` (`no_echo=true`) keeps the messages the client publishes from its own subscriptions; it needs a server that supports it (`proto` 1, nats-server 1.2.0+), otherwise connecting fails with `Nats\Exception\FeatureIsNotSupported`. +- `inboxPrefix` (`inbox_prefix`, `_INBOX` by default) is the prefix of the reply subjects of requests and of the inboxes of JetStream, KV and Object Store consumers, e.g. for the accounts that allow the users only their own subjects. `newInbox()` makes a unique subject under it. +- `drainTimeout` (`drain_timeout`, 30 seconds by default) bounds `drain()`, which waits for the handlers to finish the messages already received: once it passes, the connection is closed anyway and `drain()` throws `Nats\Exception\DrainTimedOut`. + +```php +status()); // Nats\ConnectionStatus::Disconnected, nothing has connected yet +$nc->connect(); + +$info = $nc->serverInfo(); +dump("Connected to {$info?->serverName} {$info?->version} as client {$info?->clientId}"); + +$reply = $nc->newInbox(); // _INBOX.orders. + +try { + $nc->drain(); +} catch (Nats\Exception\DrainTimedOut) { + // The handlers did not finish in 5 seconds, the connection is closed anyway. +} +``` + +#### Logging + +The client takes a PSR-3 logger (a `Psr\Log\NullLogger` by default) and logs the connection events: connected and reconnected (info), the connection lost (warning), +every failed reconnect attempt (info), the connection closed (info, error with the reason), the servers of the cluster discovered (info), the lame duck mode (warning), +and the errors also passed to `onError()`, such as a permission violation or a slow consumer (warning). + +```php +connectionFactory = Connection\SocketConnectionFactory::fromConfig($this->config); $this->subscriptionIdGenerator = new Id\SubscriptionIdGenerator(); @@ -131,6 +142,51 @@ public function ping(?Cancellation $cancellation = null): float return $this->connection($cancellation)->ping($cancellation); } + public function status(): ConnectionStatus + { + if ($this->state === ClientState::Draining) { + return ConnectionStatus::Draining; + } + + if ($this->connection === null) { + return ConnectionStatus::Disconnected; + } + + if (!$this->activeConnection instanceof Connection\ReconnectingConnection) { + return ConnectionStatus::Connecting; + } + + return match ($this->activeConnection->state()) { + Connection\ReconnectState::Idle => ConnectionStatus::Connecting, + Connection\ReconnectState::Connected => ConnectionStatus::Connected, + Connection\ReconnectState::Reconnecting => ConnectionStatus::Reconnecting, + Connection\ReconnectState::Closed => ConnectionStatus::Disconnected, + }; + } + + /** + * Returns the INFO of the server the client is connected to, null when it is not connected. + * While reconnecting, it is the one of the lost server. It does not connect. + */ + public function serverInfo(): ?ServerInfo + { + $connection = $this->activeConnection; + + return $connection instanceof Connection\ReconnectingConnection && $connection->state() !== Connection\ReconnectState::Closed + ? $connection->info() + : null; + } + + /** + * Returns a unique subject under {@see Config::$inboxPrefix}, e.g. the reply subject of a request made by hand. + * + * @return non-empty-string + */ + public function newInbox(): string + { + return Id\generateInboxId($this->config->inboxPrefix); + } + /** * @param ?non-empty-string $domain * @throws NatsException @@ -139,8 +195,8 @@ public function jetStream(?string $domain = null, ?Cancellation $cancellation = { $info = $this->connection($cancellation)->info(); - if (!$info->supportJetstream) { - throw Exception\FeatureIsNotSupported::forJetStream($info->serverVersion); + if (!$info->jetStream) { + throw Exception\FeatureIsNotSupported::forJetStream($info->version); } return new JetStream( @@ -189,8 +245,8 @@ public function rawPublish( $connection = $this->connection($cancellation); $info = $connection->info(); - if ($message->headers !== null && \count($message->headers) > 0 && !$info->allowHeaders) { - throw Exception\FeatureIsNotSupported::forHeaders($info->serverVersion); + if ($message->headers !== null && \count($message->headers) > 0 && !$info->headers) { + throw Exception\FeatureIsNotSupported::forHeaders($info->version); } $pub = Internal\Command::pub($subject, $message, $replyTo); @@ -338,7 +394,7 @@ public function requestMany( $handler = new Rpc\RequestManyHandler($queue, $stall, $sentinel); $subscription = $this->register( - subject: $inbox = Id\generateInboxId(), + subject: $inbox = $this->newInbox(), handler: $handler, cancellation: $cancellation, max: $maxMessages, @@ -378,7 +434,7 @@ public function rawRequest( $subscribe = $this->subscribeCallback(...); $this->rpc ??= async(function () use ($subscribe): Rpc\Handler { - $handler = new Rpc\Handler(); + $handler = new Rpc\Handler($this->newInbox()); try { // The inbox subscription is shared by all requests, so the caller's cancellation must not interrupt it. @@ -551,12 +607,43 @@ public function stop(?Cancellation $cancellation = null): void /** * Unsubscribes, lets the handlers finish the messages already received and closes the connection. While reconnecting, - * unlike nats.go that fails here, it waits for the reconnect to drain over the new connection: pass a cancellation - * to bound the wait. + * unlike nats.go that fails here, it waits for the reconnect to drain over the new connection. The whole drain is + * bounded by {@see Config::$drainTimeout}, after which the connection is closed anyway, and by the cancellation. + * + * @throws DrainTimedOut */ public function drain(?Cancellation $cancellation = null): void { - $this->disconnect(static fn(Subscription $subscription) => $subscription->drain($cancellation), $cancellation); + $timeout = new TimeoutCancellation($this->config->drainTimeout); + $bounded = $cancellation !== null ? new CompositeCancellation($cancellation, $timeout) : $timeout; + + $this->state = ClientState::Draining; + + try { + $this->disconnect(static function (Subscription $subscription) use ($bounded): void { + $subscription->drain($bounded); + + // The handlers finish the messages already received before the connection is closed, as in nats.go. + try { + $subscription->awaitCompletion($bounded); + } catch (CancelledException $e) { + throw $e; + } catch (\Throwable) { + // The subscription has failed, e.g. its handler has thrown: its owner gets the error, the drain goes on. + } + }, $bounded); + } catch (CancelledException $e) { + if ($cancellation?->isRequested() !== true && $timeout->isRequested()) { + $error = DrainTimedOut::after($this->config->drainTimeout, $e); + $this->logger->warning('The client did not drain in time, the connection is closed.', ['exception' => $error]); + + throw $error; + } + + throw $e; + } finally { + $this->state = ClientState::Running; + } } public function __destruct() @@ -786,6 +873,8 @@ private function resubscriptions(): array private function disconnected(?\Throwable $reason): void { + $this->logger->warning('The connection to the nats server is lost, reconnecting.', ['exception' => $reason]); + foreach ($this->disconnectCallbacks as $callback) { EventLoop::queue($callback, $reason); } @@ -797,6 +886,8 @@ private function disconnected(?\Throwable $reason): void private function reconnected(): void { + $this->logger->info('Reconnected to the nats server.', $this->serverContext()); + foreach ($this->reconnectCallbacks as $callback) { EventLoop::queue($callback); } @@ -832,6 +923,8 @@ private function failSubscriptions(Protocol\Err $error, \Throwable $e): bool private function reportError(\Throwable $e): void { + $this->logger->warning('Nats error: {message}', ['message' => $e->getMessage(), 'exception' => $e]); + foreach ($this->errorCallbacks as $callback) { EventLoop::queue($callback, $e); } @@ -993,6 +1086,7 @@ private function connection(?Cancellation $cancellation = null): Connection\Reco $connection = new Connection\ReconnectingConnection( config: $this->config, factory: $this->connectionFactory, + logger: $this->logger, subscriptions: static fn(): array => $client->get()?->resubscriptions() ?? [], ); @@ -1014,6 +1108,8 @@ private function connection(?Cancellation $cancellation = null): Connection\Reco return; } + $self->logger->info('Nats servers discovered.', ['servers' => $event->urls]); + foreach ($self->serversDiscoveredCallbacks as $callback) { EventLoop::queue($callback, $event->urls); } @@ -1024,6 +1120,8 @@ private function connection(?Cancellation $cancellation = null): Connection\Reco return; } + $self->logger->warning('The nats server entered the lame duck mode.', $self->serverContext()); + foreach ($self->lameDuckModeCallbacks as $callback) { EventLoop::queue($callback); } @@ -1034,6 +1132,12 @@ private function connection(?Cancellation $cancellation = null): Connection\Reco ): void { $self = $client->get(); if ($self !== null) { + if ($event->reason === null) { + $self->logger->info('The connection to the nats server is closed.'); + } else { + $self->logger->error('The connection to the nats server is closed.', ['exception' => $event->reason]); + } + foreach ($self->closeCallbacks as $callback) { EventLoop::queue($callback, $event->reason); } @@ -1052,10 +1156,26 @@ private function connection(?Cancellation $cancellation = null): Connection\Reco } $this->activeConnection = $connection; + $this->logger->info('Connected to the nats server.', $this->serverContext()); return $connection; })); return $this->connection->await($cancellation); } + + /** + * @return array + */ + private function serverContext(): array + { + $info = $this->serverInfo(); + + return $info === null ? [] : [ + 'server_id' => $info->serverId, + 'server_name' => $info->serverName, + 'version' => $info->version, + 'client_id' => $info->clientId, + ]; + } } diff --git a/src/Config.php b/src/Config.php index b6cd8cf..71e4c76 100644 --- a/src/Config.php +++ b/src/Config.php @@ -4,6 +4,7 @@ namespace Thesis\Nats; +use Thesis\Nats\Exception\InvalidSubject; use Thesis\Nats\Internal\Connection\Uri; use Thesis\Nats\Internal\Validation\Validate; @@ -21,6 +22,8 @@ private const float DEFAULT_RECONNECT_WAIT = 2.0; private const float DEFAULT_RECONNECT_JITTER = 0.1; private const int DEFAULT_RECONNECT_BUFFER_SIZE = 8 * 1024 * 1024; + private const string DEFAULT_INBOX_PREFIX = '_INBOX'; + private const float DEFAULT_DRAIN_TIMEOUT = 30.0; /** * @var non-empty-string @@ -55,6 +58,9 @@ * @param bool $noRandomize whether to try the servers in the given order instead of a random one * @param ?TlsConfig $tls the TLS options, with which TLS is required; without them the connection is upgraded to TLS * only when the server requires it, verifying its certificate against the system authorities + * @param bool $noEcho whether the server keeps the messages this client publishes from its own subscriptions + * @param non-empty-string $inboxPrefix the prefix of the reply subjects of requests and of the other inboxes, see {@see Client::newInbox()} + * @param float $drainTimeout in seconds, the bound of {@see Client::drain()}, after which the connection is closed anyway * @throws \InvalidArgumentException */ public function __construct( @@ -89,6 +95,9 @@ public function __construct( public int $reconnectBufferSize = self::DEFAULT_RECONNECT_BUFFER_SIZE, public bool $noRandomize = false, public ?TlsConfig $tls = null, + public bool $noEcho = false, + public string $inboxPrefix = self::DEFAULT_INBOX_PREFIX, + public float $drainTimeout = self::DEFAULT_DRAIN_TIMEOUT, ) { Validate::duration($connectionTimeout, 'connection timeout'); @@ -129,6 +138,15 @@ public function __construct( Validate::duration($requestTimeout, 'request timeout'); } + Validate::duration($drainTimeout, 'drain timeout'); + + // The tokens of the inbox are appended to it, so it is a literal subject. + try { + Validate::publishSubject($inboxPrefix); + } catch (InvalidSubject $e) { + throw new \InvalidArgumentException("The inbox prefix is invalid: {$e->getMessage()}", previous: $e); + } + $this->version = '0.1.x'; } @@ -191,6 +209,9 @@ public static function fromURI(#[\SensitiveParameter] string $uri): self serverName: $query->tlsServerName, handshakeFirst: $query->tlsHandshakeFirst ?? false, ) : null, + noEcho: $query->noEcho ?? false, + inboxPrefix: $query->inboxPrefix ?? self::DEFAULT_INBOX_PREFIX, + drainTimeout: $query->drainTimeout ?? self::DEFAULT_DRAIN_TIMEOUT, ); } @@ -230,6 +251,9 @@ public static function fromURI(#[\SensitiveParameter] string $uri): self * server_name?: non-empty-string, * handshake_first?: bool, * }, + * no_echo?: bool, + * inbox_prefix?: non-empty-string, + * drain_timeout?: float, * } $options * @throws \InvalidArgumentException */ @@ -270,6 +294,9 @@ public static function fromArray(#[\SensitiveParameter] array $options): self serverName: $options['tls']['server_name'] ?? null, handshakeFirst: $options['tls']['handshake_first'] ?? false, ) : null, + noEcho: $options['no_echo'] ?? false, + inboxPrefix: $options['inbox_prefix'] ?? self::DEFAULT_INBOX_PREFIX, + drainTimeout: $options['drain_timeout'] ?? self::DEFAULT_DRAIN_TIMEOUT, ); } } diff --git a/src/ConnectionStatus.php b/src/ConnectionStatus.php new file mode 100644 index 0000000..c6f4e66 --- /dev/null +++ b/src/ConnectionStatus.php @@ -0,0 +1,24 @@ +version, - allowHeaders: $info->headers, - supportJetstream: $info->jetstream ?? false, - maxPayload: $info->maxPayload, - connectUrls: $info->connectUrls ?? [], - serverId: $info->serverId, - ); - } - - /** - * @param non-empty-string $serverVersion - * @param ?positive-int $maxPayload the largest message (headers and payload) the server accepts, in bytes, - * null if the server does not announce it - * @param list $connectUrls the `host:port` of the servers of the cluster the server announces - * @param ?non-empty-string $serverId - */ - public function __construct( - public string $serverVersion, - public bool $allowHeaders = false, - public bool $supportJetstream = false, - public ?int $maxPayload = null, - public array $connectUrls = [], - public ?string $serverId = null, - ) {} -} diff --git a/src/Internal/Connection/Query.php b/src/Internal/Connection/Query.php index 8167145..a377030 100644 --- a/src/Internal/Connection/Query.php +++ b/src/Internal/Connection/Query.php @@ -34,6 +34,8 @@ * @param ?non-empty-string $tlsKeyFile * @param ?non-empty-string $tlsKeyPassphrase * @param ?non-empty-string $tlsServerName + * @param ?non-empty-string $inboxPrefix + * @param ?float $drainTimeout positive and finite */ private function __construct( public ?bool $verbose = null, @@ -69,6 +71,9 @@ private function __construct( public ?bool $tlsVerify = null, public ?string $tlsServerName = null, public ?bool $tlsHandshakeFirst = null, + public ?bool $noEcho = null, + public ?string $inboxPrefix = null, + public ?float $drainTimeout = null, ) {} /** @@ -119,6 +124,9 @@ public static function parse(#[\SensitiveParameter] string $query): self tlsVerify: self::bool($options, 'tls_verify'), tlsServerName: self::string($options, 'tls_server_name'), tlsHandshakeFirst: self::bool($options, 'tls_handshake_first'), + noEcho: self::bool($options, 'no_echo'), + inboxPrefix: self::string($options, 'inbox_prefix'), + drainTimeout: self::duration($options, 'drain_timeout'), ); } diff --git a/src/Internal/Connection/ReconnectingConnection.php b/src/Internal/Connection/ReconnectingConnection.php index d70ead0..4e3def1 100644 --- a/src/Internal/Connection/ReconnectingConnection.php +++ b/src/Internal/Connection/ReconnectingConnection.php @@ -9,6 +9,8 @@ use Amp\DeferredCancellation; use Amp\DeferredFuture; use Amp\TimeoutCancellation; +use Psr\Log\LoggerInterface; +use Psr\Log\NullLogger; use Thesis\Nats\Config; use Thesis\Nats\Exception\AuthorizationViolation; use Thesis\Nats\Exception\ConnectionIsNotAvailable; @@ -19,6 +21,7 @@ use Thesis\Nats\Internal\Hooks; use Thesis\Nats\Internal\Protocol; use Thesis\Nats\NatsException; +use Thesis\Nats\ServerInfo; use function Amp\async; use function Amp\delay; @@ -37,7 +40,7 @@ final class ReconnectingConnection implements Connection private ?Connection $current = null; - private ?ConnectionInfo $info = null; + private ?ServerInfo $info = null; private readonly ServerPool $pool; @@ -63,6 +66,7 @@ public function __construct( private readonly Config $config, private readonly ConnectionFactory $factory, private readonly \Closure $subscriptions, + private readonly LoggerInterface $logger = new NullLogger(), ) { $this->hooks = new Hooks\ConcurrentProvider(); $this->pool = new ServerPool($config->urls, randomize: !$config->noRandomize, maxReconnects: $config->maxReconnects); @@ -155,11 +159,16 @@ public function ping(?Cancellation $cancellation = null): float return $this->connected()->ping($cancellation); } - public function info(): ConnectionInfo + public function info(): ServerInfo { return $this->info ?? throw new ConnectionIsNotAvailable(); } + public function state(): ReconnectState + { + return $this->state; + } + public function close(?\Throwable $reason = null): void { $this->finish($reason); @@ -271,6 +280,9 @@ private function onServerInfo(Connection $connection, Protocol\ServerInfo $info) return; } + // The update is a whole INFO, the way nats.go takes it. + $this->info = ServerInfo::fromProtocol($info); + if ($this->pool->discover($info->connectUrls ?? [])) { $this->discovered(); } @@ -358,6 +370,7 @@ private function reconnect(): void $connection = $this->factory->connect($server); } catch (\Throwable $e) { $error = $e; + $this->logger->info('Reconnecting to the nats server {server} failed.', ['server' => $server->url, 'exception' => $e]); // Credentials rejected twice in a row by the same server are not going to be accepted, as in nats.go. if ($server->failed($e) && $e instanceof AuthorizationViolation) { @@ -379,6 +392,7 @@ private function reconnect(): void $this->restore($connection); } catch (NatsException $e) { $error = $e; + $this->logger->info('Restoring the subscriptions on the nats server {server} failed.', ['server' => $server->url, 'exception' => $e]); $server->failed($e); $this->current = null; $connection->close(); diff --git a/src/Internal/Connection/SocketConnection.php b/src/Internal/Connection/SocketConnection.php index cf2bf43..6746239 100644 --- a/src/Internal/Connection/SocketConnection.php +++ b/src/Internal/Connection/SocketConnection.php @@ -17,12 +17,14 @@ use Thesis\Nats\Config; use Thesis\Nats\Exception\ConnectionIsNotAvailable; use Thesis\Nats\Exception\ConnectionWasClosed; +use Thesis\Nats\Exception\FeatureIsNotSupported; use Thesis\Nats\Exception\ServerIsNotAvailable; use Thesis\Nats\Exception\TlsHandshakeFailed; use Thesis\Nats\Exception\TlsIsNotAvailable; use Thesis\Nats\Internal\Hooks; use Thesis\Nats\Internal\Protocol; use Thesis\Nats\NatsException; +use Thesis\Nats\ServerInfo; use function Amp\async; use function Thesis\Package\version; @@ -42,7 +44,7 @@ final class SocketConnection implements Connection private readonly PingPongHandler $pingpongs; - private ?ConnectionInfo $info = null; + private ?ServerInfo $info = null; private ConnectionState $state = ConnectionState::Idle; @@ -249,11 +251,16 @@ private function handshake(Cancellation $cancellation): void $this->secure($cancellation); } + // The servers before the echo option (proto 0) would deliver the messages to their publisher anyway. + if ($this->config->noEcho && $frame->proto < Protocol\Proto::Cluster->value) { + throw FeatureIsNotSupported::forNoEcho($frame->version); + } + if ($this->state !== ConnectionState::Alive) { $this->run(); } - $this->info ??= ConnectionInfo::fromServerInfo($frame); + $this->info ??= ServerInfo::fromProtocol($frame); /** @var DeferredFuture $handshake */ $handshake = new DeferredFuture(); @@ -264,6 +271,7 @@ private function handshake(Cancellation $cancellation): void $this->connect(new Protocol\Connect( verbose: $this->config->verbose, pedantic: $this->config->pedantic, + echo: $this->config->noEcho ? false : null, tlsRequired: $this->socket->getTlsState() === TlsState::Enabled, name: $this->config->clientName, version: version(self::PACKAGE_NAME), @@ -275,8 +283,8 @@ private function handshake(Cancellation $cancellation): void sig: $keypair !== null && $frame->nonce !== null && $frame->nonce !== '' ? $keypair->sign($frame->nonce) : null, jwt: $this->credentials->jwt, // The server rejects no_responders without headers: the no responders status is a header. - noResponders: $this->config->noResponders && $this->info->allowHeaders, - headers: $this->info->allowHeaders, + noResponders: $this->config->noResponders && $this->info->headers, + headers: $this->info->headers, nkey: $keypair?->publicKey, ), $cancellation); @@ -330,7 +338,7 @@ private function closedWhileWriting(StreamException $e): ConnectionWasClosed : new ConnectionWasClosed("The connection was closed: {$e->getMessage()}", previous: $e); } - public function info(): ConnectionInfo + public function info(): ServerInfo { return $this->info ?? throw new ConnectionIsNotAvailable(); } diff --git a/src/Internal/Id/generateInboxId.php b/src/Internal/Id/generateInboxId.php index 76b55c7..b36aa22 100644 --- a/src/Internal/Id/generateInboxId.php +++ b/src/Internal/Id/generateInboxId.php @@ -6,12 +6,13 @@ /** * @internal + * @param non-empty-string $prefix * @param positive-int $length * @return non-empty-string */ -function generateInboxId(int $length = 20): string +function generateInboxId(string $prefix = '_INBOX', int $length = 20): string { $idx = generateUniqueId($length); - return "_INBOX.{$idx}"; + return "{$prefix}.{$idx}"; } diff --git a/src/Internal/Rpc/Handler.php b/src/Internal/Rpc/Handler.php index 7b2d889..ea51d10 100644 --- a/src/Internal/Rpc/Handler.php +++ b/src/Internal/Rpc/Handler.php @@ -11,7 +11,6 @@ use Thesis\Nats\Exception\ConnectionWasClosed; use Thesis\Nats\Exception\MessageNotFound; use Thesis\Nats\Exception\RequestHasNoResponders; -use Thesis\Nats\Internal\Id; use Thesis\Nats\Message; use Thesis\Nats\Status; @@ -29,10 +28,12 @@ final class Handler /** @var ?\Closure(?Cancellation=): void */ private ?\Closure $unsubscribe = null; - public function __construct() + /** + * @param non-empty-string $inbox the subject the replies come to, a token is appended to it per request + */ + public function __construct(string $inbox) { - $inboxId = Id\generateInboxId(); - $this->inboxId = "{$inboxId}."; + $this->inboxId = "{$inbox}."; } /** diff --git a/src/JetStream.php b/src/JetStream.php index 385f480..4b3b53b 100644 --- a/src/JetStream.php +++ b/src/JetStream.php @@ -48,6 +48,15 @@ public function __construct( $this->router = new Api\Router($domain); } + /** + * @internal + * @return non-empty-string + */ + public function newInbox(): string + { + return $this->nats->newInbox(); + } + /** * @param non-empty-string $subject * @throws NatsException diff --git a/src/JetStream/KeyValue/Bucket.php b/src/JetStream/KeyValue/Bucket.php index 065d5ae..1a51e6e 100644 --- a/src/JetStream/KeyValue/Bucket.php +++ b/src/JetStream/KeyValue/Bucket.php @@ -10,7 +10,6 @@ use Thesis\Nats\Exception\WrongLastSequence; use Thesis\Nats\Header; use Thesis\Nats\Headers; -use Thesis\Nats\Internal\Id; use Thesis\Nats\Internal\Validation\Validate; use Thesis\Nats\JetStream; use Thesis\Nats\JetStream\Api\AckPolicy; @@ -334,7 +333,7 @@ private function startWatch( $consumerConfig = new JetStream\Api\ConsumerConfig( description: 'kv watch consumer', deliverPolicy: $deliverPolicy, - deliverSubject: Id\generateInboxId(), + deliverSubject: $this->js->newInbox(), startSeq: $startSeq, ackPolicy: AckPolicy::None, maxDeliver: 1, diff --git a/src/JetStream/ObjectStore/Store.php b/src/JetStream/ObjectStore/Store.php index 7539838..958f025 100644 --- a/src/JetStream/ObjectStore/Store.php +++ b/src/JetStream/ObjectStore/Store.php @@ -82,7 +82,7 @@ public function get(string $name): ?StoredObject $sink = new WritableIterableStream($info->size); $this->stream->createOrUpdateConsumer(new JetStream\Api\ConsumerConfig( - deliverSubject: $id = Id\generateInboxId(), + deliverSubject: $id = $this->nats->newInbox(), filterSubject: "\$O.{$this->name}.C.{$info->nuid}", )); @@ -251,7 +251,7 @@ public function watch( ->createOrUpdateConsumer(new JetStream\Api\ConsumerConfig( description: 'object store consumer', deliverPolicy: $config->withHistory ? DeliverPolicy::LastPerSubject : DeliverPolicy::New, - deliverSubject: Id\generateInboxId(), + deliverSubject: $this->nats->newInbox(), filterSubject: "\$O.{$this->name}.M.>", )) ->push( diff --git a/src/JetStream/PullConsumer.php b/src/JetStream/PullConsumer.php index d47a9bc..54a7ca3 100644 --- a/src/JetStream/PullConsumer.php +++ b/src/JetStream/PullConsumer.php @@ -8,7 +8,6 @@ use Amp\Future; use Amp\Pipeline; use Thesis\Nats\Client; -use Thesis\Nats\Internal\Id; use Thesis\Nats\Internal\Timer; use Thesis\Nats\JetStream\Api\PullRequest; use Thesis\Nats\JetStream\Api\Router; @@ -65,7 +64,7 @@ public function fetch(FetchConfig $config, ?Cancellation $cancellation = null): ); $subscription = $this->nats->subscribe( - subject: $reply = Id\generateInboxId(), + subject: $reply = $this->nats->newInbox(), handler: $handler, cancellation: $cancellation, ); @@ -124,7 +123,7 @@ public function consume( throw new \LogicException('Priority group can only be used for priority consumer.'); } - $reply = Id\generateInboxId(); + $reply = $this->nats->newInbox(); $messageHandler = new Internal\PullMessageHandler( handler: $handler, diff --git a/src/JetStream/Stream.php b/src/JetStream/Stream.php index 9d3a277..ebdebbe 100644 --- a/src/JetStream/Stream.php +++ b/src/JetStream/Stream.php @@ -11,7 +11,6 @@ use Thesis\Nats\Exception\MessageNotFound; use Thesis\Nats\Header; use Thesis\Nats\Headers; -use Thesis\Nats\Internal\Id; use Thesis\Nats\Internal\Protocol; use Thesis\Nats\JetStream; use Thesis\Nats\Message; @@ -137,7 +136,7 @@ public function deleteConsumer(string $consumer, ?Cancellation $cancellation = n */ public function getMessages(array $subjects): iterable { - $reply = Id\generateInboxId(); + $reply = $this->nc->newInbox(); $deliveries = $this->nc->subscribeIterator($reply); diff --git a/src/ServerInfo.php b/src/ServerInfo.php new file mode 100644 index 0000000..4354fd1 --- /dev/null +++ b/src/ServerInfo.php @@ -0,0 +1,94 @@ + $connectUrls the `host:port` of the servers of the cluster the server announces + * @param bool $lameDuckMode whether the server is going to shut down + * @param ?bool $authRequired whether the server requires authentication + * @param ?bool $tlsRequired whether the server requires TLS + * @param ?bool $tlsAvailable whether the server accepts TLS without requiring it + * @param ?bool $tlsVerify whether the server requires a client certificate + * @param ?non-empty-string $go the version of Go the server was built with + * @param ?string $gitCommit the commit the server was built from + */ + public function __construct( + public string $version, + public ?string $serverId = null, + public ?string $serverName = null, + public ?string $host = null, + public ?int $port = null, + public int $proto = 0, + public bool $headers = false, + public ?int $maxPayload = null, + public bool $jetStream = false, + public ?int $clientId = null, + public ?string $clientIp = null, + public ?string $cluster = null, + public ?string $domain = null, + public array $connectUrls = [], + public bool $lameDuckMode = false, + public ?bool $authRequired = null, + public ?bool $tlsRequired = null, + public ?bool $tlsAvailable = null, + public ?bool $tlsVerify = null, + public ?string $go = null, + public ?string $gitCommit = null, + ) {} + + /** + * @internal + */ + public static function fromProtocol(Protocol\ServerInfo $info): self + { + return new self( + version: $info->version, + serverId: $info->serverId, + serverName: $info->serverName, + host: $info->host, + port: $info->port, + proto: $info->proto, + headers: $info->headers, + maxPayload: $info->maxPayload, + jetStream: $info->jetstream ?? false, + clientId: $info->clientId, + clientIp: $info->clientIp, + cluster: $info->cluster, + domain: $info->domain, + connectUrls: $info->connectUrls ?? [], + lameDuckMode: $info->ldm ?? false, + authRequired: $info->authRequired, + tlsRequired: $info->tlsRequired, + tlsAvailable: $info->tlsAvailable, + tlsVerify: $info->tlsVerify, + go: $info->go, + gitCommit: $info->gitCommit, + ); + } +} diff --git a/tests/ConfigTest.php b/tests/ConfigTest.php index b9ece10..eb896c9 100644 --- a/tests/ConfigTest.php +++ b/tests/ConfigTest.php @@ -364,6 +364,18 @@ final class ConfigTest extends TestCase new Config(urls: ['h1:4222'], tls: new TlsConfig()), ], )] + #[TestWith( + [ + 'nats://127.0.0.1:4222?no_echo=true&inbox_prefix=my.inbox&drain_timeout=2.5', + new Config(noEcho: true, inboxPrefix: 'my.inbox', drainTimeout: 2.5), + ], + )] + #[TestWith( + [ + 'nats://127.0.0.1:4222?no_echo=maybe&inbox_prefix=&drain_timeout=-1', + new Config(), + ], + )] public function testFromURI(string $uri, Config $config): void { self::assertEquals($config, Config::fromURI($uri)); @@ -542,4 +554,36 @@ public function testTlsKeyPassphraseRequiresCertificate(): void $this->expectException(\InvalidArgumentException::class); new TlsConfig(keyPassphrase: 'secret'); } + + public function testFromArrayWithConnectionOptions(): void + { + self::assertEquals( + new Config(noEcho: true, inboxPrefix: 'my.inbox', drainTimeout: 2.5), + Config::fromArray(['no_echo' => true, 'inbox_prefix' => 'my.inbox', 'drain_timeout' => 2.5]), + ); + } + + /** + * @param non-empty-string $prefix + */ + #[TestWith(['my.*'])] + #[TestWith(['my.>'])] + #[TestWith(['my inbox'])] + #[TestWith(['my..inbox'])] + #[TestWith(['my.inbox.'])] + public function testInboxPrefixMustBeLiteralSubject(string $prefix): void + { + $this->expectException(\InvalidArgumentException::class); + new Config(inboxPrefix: $prefix); + } + + #[TestWith([0.0])] + #[TestWith([-1.0])] + #[TestWith([INF])] + #[TestWith([NAN])] + public function testDrainTimeoutMustBePositive(float $timeout): void + { + $this->expectException(\InvalidArgumentException::class); + new Config(drainTimeout: $timeout); + } } diff --git a/tests/ConnectionOptionsTest.php b/tests/ConnectionOptionsTest.php new file mode 100644 index 0000000..8cb6a15 --- /dev/null +++ b/tests/ConnectionOptionsTest.php @@ -0,0 +1,376 @@ + */ + private array $clients = []; + + #[\Override] + protected function tearDown(): void + { + foreach ($this->clients as $client) { + $client->stop(); + } + + parent::tearDown(); + } + + public function testNoEchoKeepsOwnMessagesFromOwnSubscriptions(): void + { + $quiet = $this->track(new Client($this->configWith(noEcho: true))); + $other = $this->track(new Client($this->configWith())); + $subject = Id\generateUniqueId(); + + $own = $quiet->subscribeIterator($subject); + $all = $other->subscribeIterator($subject); + $quiet->ping(); + $other->ping(); + + $quiet->publish($subject, new Message('from quiet')); + $other->publish($subject, new Message('from other')); + + self::assertSame(['from quiet', 'from other'], self::take($all, 2)); + // The own message would have come first: the subscription gets the other one only. + self::assertSame(['from other'], self::take($own, 1)); + } + + public function testNoEchoIsRefusedByServerWithoutTheEchoOption(): void + { + // A server before 1.2.0 announces the original protocol, which has no echo option. + $server = listen('127.0.0.1:0'); + $address = $server->getAddress()->toString(); + self::assertNotSame('', $address); + + $future = async(static function () use ($server): void { + $socket = $server->accept(); + $socket?->write("INFO {\"version\":\"1.1.0\",\"proto\":0}\r\n"); + $socket?->read(); + }); + $future->ignore(); + + $client = $this->track(new Client(new Config(urls: [$address], allowReconnect: false, noEcho: true))); + + try { + $client->connect(); + self::fail('The server without the echo option is accepted.'); + } catch (FeatureIsNotSupported $e) { + self::assertStringContainsString('1.1.0', $e->getMessage()); + } finally { + $server->close(); + } + } + + public function testInboxPrefix(): void + { + $client = $this->track(new Client($this->configWith(inboxPrefix: 'custom.inbox'))); + $responder = $this->track(new Client($this->configWith())); + $subject = Id\generateUniqueId(); + + /** @var \ArrayObject $replySubjects */ + $replySubjects = new \ArrayObject(); + $responder->subscribe($subject, static function (Delivery $delivery) use ($replySubjects): void { + $replySubjects[] = (string) $delivery->replyTo; + $delivery->reply(new Message('pong')); + }); + $responder->ping(); + + self::assertSame('pong', $client->request($subject, new Message('ping'), timeout: 5)->message->payload); + self::assertCount(1, $replySubjects); + self::assertStringStartsWith('custom.inbox.', $replySubjects[0] ?? ''); + + $inbox = $client->newInbox(); + self::assertStringStartsWith('custom.inbox.', $inbox); + self::assertNotSame($inbox, $client->newInbox()); + } + + public function testJetStreamUsesTheInboxPrefix(): void + { + $client = $this->track(new Client($this->configWith(inboxPrefix: 'custom.inbox'))); + $js = $client->jetStream(); + $bucketName = Id\generateUniqueId(10); + $bucket = $js->createOrUpdateKeyValue(new JetStream\KeyValue\BucketConfig($bucketName)); + + try { + /** @var DeferredFuture $watched */ + $watched = new DeferredFuture(); + + // The watch consumer delivers to an inbox of the prefix. + $watcher = $bucket->watch(static function (JetStream\KeyValue\Entry $entry) use ($watched): void { + if (!$watched->isComplete()) { + $watched->complete($entry); + } + }); + $bucket->put('key', 'value'); + + self::assertSame('value', $watched->getFuture()->await(new TimeoutCancellation(5))->value); + $watcher->stop(); + } finally { + $js->deleteKeyValue($bucketName); + } + } + + public function testServerInfo(): void + { + $name = Id\generateUniqueId(); + $client = $this->clientNamed($name); + + // It does not connect. + self::assertNull($client->serverInfo()); + + $client->connect(); + $info = $client->serverInfo(); + + self::assertNotNull($info); + self::assertMatchesRegularExpression('/^\d+\.\d+\.\d+/', $info->version); + self::assertNotNull($info->serverId); + self::assertTrue($info->headers); + self::assertTrue($info->jetStream); + self::assertSame(1, $info->proto); + self::assertNotNull($info->maxPayload); + self::assertSame($this->connectionId($name), $info->clientId); + self::assertFalse($info->lameDuckMode); + + $client->stop(); + self::assertNull($client->serverInfo()); + } + + public function testServerInfoFollowsTheUpdates(): void + { + $name = Id\generateUniqueId(); + $client = $this->clientNamed($name); + + /** @var DeferredFuture $lameDuck */ + $lameDuck = new DeferredFuture(); + $client->onLameDuckMode(static fn() => $lameDuck->complete()); + $client->connect(); + + $this->lameDuck($name); + $lameDuck->getFuture()->await(new TimeoutCancellation(5)); + + self::assertTrue($client->serverInfo()?->lameDuckMode); + } + + public function testStatus(): void + { + $name = Id\generateUniqueId(); + $client = $this->clientNamed($name); + + self::assertSame(ConnectionStatus::Disconnected, $client->status()); + + $client->connect(); + self::assertSame(ConnectionStatus::Connected, $client->status()); + + /** @var DeferredFuture $disconnected */ + $disconnected = new DeferredFuture(); + $client->onDisconnect(static fn() => $disconnected->complete($client->status())); + /** @var DeferredFuture $reconnected */ + $reconnected = new DeferredFuture(); + $client->onReconnect(static fn() => $reconnected->complete($client->status())); + + $this->kick($name); + + self::assertSame(ConnectionStatus::Reconnecting, $disconnected->getFuture()->await(new TimeoutCancellation(5))); + self::assertSame(ConnectionStatus::Connected, $reconnected->getFuture()->await(new TimeoutCancellation(5))); + + $client->stop(); + self::assertSame(ConnectionStatus::Disconnected, $client->status()); + } + + public function testStatusWhileDraining(): void + { + $client = $this->track(new Client($this->configWith())); + $subject = Id\generateUniqueId(); + + /** @var DeferredFuture $handling */ + $handling = new DeferredFuture(); + $client->subscribe($subject, static function () use ($handling): void { + $handling->complete(); + delay(0.3); + }); + $client->publish($subject, new Message('slow')); + $handling->getFuture()->await(new TimeoutCancellation(5)); + + $drain = async($client->drain(...)); + + delay(0.1); + self::assertSame(ConnectionStatus::Draining, $client->status()); + + $drain->await(new TimeoutCancellation(5)); + self::assertSame(ConnectionStatus::Disconnected, $client->status()); + } + + public function testDrainTimeoutClosesTheConnectionAnyway(): void + { + $client = $this->track(new Client($this->configWith(drainTimeout: 0.3))); + $subject = Id\generateUniqueId(); + + /** @var DeferredFuture $handling */ + $handling = new DeferredFuture(); + // Longer than the drain timeout, short enough not to outlive the test by much: a handler left running + // in the event loop would otherwise act in the tests that follow. + $client->subscribe($subject, static function () use ($handling): void { + $handling->complete(); + delay(1); + }); + $client->publish($subject, new Message('stuck')); + $handling->getFuture()->await(new TimeoutCancellation(5)); + + $start = microtime(true); + + try { + $client->drain(); + self::fail('The drain stuck in a handler did not time out.'); + } catch (DrainTimedOut) { + } + + self::assertLessThan(0.9, microtime(true) - $start); + self::assertSame(ConnectionStatus::Disconnected, $client->status()); + self::assertNull($client->serverInfo()); + } + + public function testLogsConnectionEvents(): void + { + $name = Id\generateUniqueId(); + $logger = new CollectingLogger(); + $config = $this->config(); + $client = $this->track(new Client( + new Config(urls: $config->urls, user: $config->user, password: $config->password, clientName: $name, reconnectWait: 0.1), + logger: $logger, + )); + + /** @var DeferredFuture $reconnected */ + $reconnected = new DeferredFuture(); + $client->onReconnect(static fn() => $reconnected->complete()); + $client->connect(); + + $this->kick($name); + $reconnected->getFuture()->await(new TimeoutCancellation(5)); + + $client->stop(); + delay(0.01); + + self::assertSame( + [ + ['info', 'Connected to the nats server.'], + ['warning', 'The connection to the nats server is lost, reconnecting.'], + ['info', 'Reconnected to the nats server.'], + ['info', 'The connection to the nats server is closed.'], + ], + array_map(static fn(array $record): array => [$record[0], $record[1]], $logger->records->getArrayCopy()), + ); + self::assertArrayHasKey('server_id', $logger->records[0][2] ?? []); + } + + public function testLogsServerErrors(): void + { + $logger = new CollectingLogger(); + $config = $this->config(); + $client = $this->track(new Client( + new Config(urls: $config->urls, user: 'restricted', password: 'Pswd1'), + logger: $logger, + )); + + /** @var DeferredFuture<\Throwable> $error */ + $error = new DeferredFuture(); + $client->onError(static fn(\Throwable $e) => $error->complete($e)); + + // A publish outside of the permissions of the user is refused asynchronously. + $client->publish('forbidden.subject', new Message('x')); + $error->getFuture()->await(new TimeoutCancellation(5)); + + $warnings = array_values(array_filter( + $logger->records->getArrayCopy(), + static fn(array $record): bool => $record[0] === 'warning', + )); + + self::assertCount(1, $warnings); + $message = $warnings[0][2]['message'] ?? null; + self::assertIsString($message); + self::assertStringContainsString('Permissions Violation', $message); + } + + /** + * @param ?non-empty-string $inboxPrefix + */ + private function configWith(bool $noEcho = false, ?string $inboxPrefix = null, float $drainTimeout = 30.0): Config + { + $config = $this->config(); + + return new Config( + urls: $config->urls, + user: $config->user, + password: $config->password, + noEcho: $noEcho, + inboxPrefix: $inboxPrefix ?? '_INBOX', + drainTimeout: $drainTimeout, + ); + } + + private function track(Client $client): Client + { + $this->clients[] = $client; + + return $client; + } + + /** + * @param Iterator $deliveries + * @param positive-int $count + * @return list + */ + private static function take(Iterator $deliveries, int $count): array + { + $payloads = []; + + foreach ($deliveries as $delivery) { + $payloads[] = (string) $delivery->message->payload; + + if (\count($payloads) === $count) { + break; + } + } + + return $payloads; + } +} + +/** + * @internal + */ +final class CollectingLogger extends AbstractLogger +{ + /** @var \ArrayObject}> */ + public readonly \ArrayObject $records; + + public function __construct() + { + /** @var \ArrayObject}> $records */ + $records = new \ArrayObject(); + $this->records = $records; + } + + #[\Override] + public function log($level, string|\Stringable $message, array $context = []): void + { + $this->records[] = [\is_string($level) ? $level : 'unknown', (string) $message, $context]; + } +}