Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 64 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
<?php
Expand Down Expand Up @@ -200,6 +203,66 @@ $rtt = $nc->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
<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use Thesis\Nats;

$nc = new Nats\Client(new Nats\Config(
urls: ['127.0.0.1:4222'],
noEcho: true,
inboxPrefix: '_INBOX.orders',
drainTimeout: 5,
));

dump($nc->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.<unique id>

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
<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use Thesis\Nats;

/** @var Psr\Log\LoggerInterface $logger e.g. Monolog */
$nc = new Nats\Client(Nats\Config::fromURI('nats://127.0.0.1:4222'), logger: $logger);
```

#### Reconnect

The client reconnects once the connection is lost, the way nats.go does it, and the subscriptions do not notice:
Expand Down
1 change: 1 addition & 0 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
"amphp/pipeline": "^1.2",
"amphp/socket": "^2.4",
"cuyz/valinor": "^1.15 || ^2.3",
"psr/log": "^3.0",
"revolt/event-loop": "^1.0.8",
"thesis/package-version": "^0.1.2",
"thesis/time-span": "^0.2.3"
Expand Down
138 changes: 129 additions & 9 deletions src/Client.php
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,13 @@
use Amp\Future;
use Amp\Pipeline;
use Amp\TimeoutCancellation;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Revolt\EventLoop;
use Thesis\Nats\Exception\ConnectionWasClosed;
use Thesis\Nats\Exception\DrainTimedOut;
use Thesis\Nats\Exception\RequestTimedOut;
use Thesis\Nats\Internal\ClientState;
use Thesis\Nats\Internal\Connection;
use Thesis\Nats\Internal\Hooks;
use Thesis\Nats\Internal\Id;
Expand Down Expand Up @@ -83,10 +87,17 @@ final class Client

private readonly Id\SubscriptionIdGenerator $subscriptionIdGenerator;

private ClientState $state = ClientState::Running;

/**
* @param LoggerInterface $logger gets the connection events: connected, lost, reconnected, closed, the failed
* reconnect attempts, the servers discovered, the lame duck mode and the server errors
*/
public function __construct(
private readonly Config $config,
private readonly Serializer $serializer = new ValinorSerializer(),
private readonly Encoder $encoder = new NativeEncoder(),
private readonly LoggerInterface $logger = new NullLogger(),
) {
$this->connectionFactory = Connection\SocketConnectionFactory::fromConfig($this->config);
$this->subscriptionIdGenerator = new Id\SubscriptionIdGenerator();
Expand Down Expand Up @@ -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
Expand All @@ -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(
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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);
}
Expand All @@ -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);
}
Expand Down Expand Up @@ -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);
}
Expand Down Expand Up @@ -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() ?? [],
);

Expand All @@ -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);
}
Expand All @@ -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);
}
Expand All @@ -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);
}
Expand All @@ -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<non-empty-string, mixed>
*/
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,
];
}
}
Loading
Loading