From 77e93d89d4ddd12cae041813f137e4ccde128c18 Mon Sep 17 00:00:00 2001 From: kafkiansky Date: Tue, 17 Nov 2026 13:36:05 +0300 Subject: [PATCH] Add JetStream ordered consumer, PullConsumer::next() and consumeIterator(), ackSync(), gap detection for push consumers --- README.md | 129 ++++- src/Client.php | 108 ++-- src/Exception/ConsumerSequenceMismatch.php | 40 ++ src/Header/LastConsumer.php | 27 + src/Header/LastStream.php | 27 + src/Internal/Iter/PipelineIterator.php | 35 ++ src/JetStream.php | 20 + src/JetStream/Delivery.php | 32 +- src/JetStream/FetchConfig.php | 9 +- src/JetStream/Internal/Acks.php | 19 +- src/JetStream/Internal/Ordered/Cursor.php | 51 ++ .../Ordered/OrderedMessageHandler.php | 409 +++++++++++++++ src/JetStream/Internal/PushMessageHandler.php | 53 +- src/JetStream/OrderedConsumer.php | 143 ++++++ src/JetStream/OrderedConsumerConfig.php | 81 +++ src/JetStream/PullConsumer.php | 42 ++ src/JetStream/PushConsumer.php | 2 + src/JetStream/Stream.php | 9 + tests/JetStream/OrderedConsumerTest.php | 482 ++++++++++++++++++ tests/JetStream/PullConsumerTest.php | 141 +++++ tests/JetStream/PushConsumerTest.php | 69 +++ 21 files changed, 1877 insertions(+), 51 deletions(-) create mode 100644 src/Exception/ConsumerSequenceMismatch.php create mode 100644 src/Header/LastConsumer.php create mode 100644 src/Header/LastStream.php create mode 100644 src/JetStream/Internal/Ordered/Cursor.php create mode 100644 src/JetStream/Internal/Ordered/OrderedMessageHandler.php create mode 100644 src/JetStream/OrderedConsumer.php create mode 100644 src/JetStream/OrderedConsumerConfig.php create mode 100644 tests/JetStream/OrderedConsumerTest.php diff --git a/README.md b/README.md index 0494111..f39cd68 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,11 @@ Pure non-blocking (fiber based) strictly typed full-featured PHP driver for NATS - [Fetch Batch](#fetch-batch) - [Fetch Bytes](#fetch-bytes) - [Fetch Immediate](#fetch-immediate) + - [Next message](#next-message) + - [Acknowledgements](#acknowledgements) - [Push Consumer](#push-consumer) - [Pull Consumer](#pull-consumer) + - [Ordered Consumer](#ordered-consumer) - [Get message](#get-message) - [NATS KV](https://docs.nats.io/nats-concepts/jetstream/key-value-store) - [Store key values](#store-key-values) @@ -798,7 +801,7 @@ And you can also configure the timeout and heartbeat settings. #### Fetch Immediate -If you simply want to retrieve a batch of messages currently available in the stream, use `FetchConfig::immediate()`: +If you simply want to retrieve a batch of messages currently available in the stream, use `FetchConfig::immediate()`, optionally with the maximum number of messages to take: ```php createOrUpdateConsumer(...); $batch = $consumer ->pulling() - ->fetch(JetStream\FetchConfig::immediate()); + ->fetch(JetStream\FetchConfig::immediate(100)); foreach ($batch as $delivery) { // handle message @@ -820,6 +823,45 @@ foreach ($batch as $delivery) { } ``` +#### Next message + +`PullConsumer::next()` waits for a single message, at most `maxWait` (30 seconds by default), and returns `null` if none came in time: + +```php +pulling()->next(TimeSpan::fromSeconds(5)); + +if ($delivery !== null) { + // handle message + $delivery->ack(); +} +``` + +#### Acknowledgements + +`Delivery::ack()` sends the acknowledgement without waiting for the server. `Delivery::ackSync()` waits until the server confirms it has processed the acknowledgement, +so the message is not redelivered afterwards, and throws if the server does not confirm it, e.g. the consumer was deleted meanwhile. +`nack()`, `terminate()` and `inProgress()` complete the set. + +```php +pulling()->next(); + +$delivery?->ackSync(new TimeoutCancellation(5)); +``` + +A consumer created with `headersOnly: true` delivers the headers without the payload, `Delivery::payloadSize()` then tells the size of the stored payload (for other consumers it is the size of the payload delivered). + #### Push Consumer NATS offers two message delivery models: **pull** and **push**. Although the NATS documentation [recommends](https://docs.nats.io/nats-concepts/jetstream/consumers#dispatch-type-pull-push) the pull approach, for most PHP use cases push consumers are often preferable. @@ -897,6 +939,24 @@ $consumer = $stream->createOrUpdateConsumer(new Api\ConsumerConfig( Please refer to the push consumer configuration [documentation](https://docs.nats.io/nats-concepts/jetstream/consumers#push-specific) to understand the purpose of each parameter. +With `idleHeartbeat` set and without a `deliverGroup`, the subscription compares the heartbeats with the last message received: if the server has delivered messages +the subscription never got, e.g. dropped beyond the pending limits, a `ConsumerSequenceMismatch` is reported to `Client::onError()` once per gap. +The subscription keeps going, and the exception tells the stream sequence to read the lost messages again from: + +```php +onError(static function (\Throwable $e): void { + if ($e instanceof Nats\Exception\ConsumerSequenceMismatch) { + dump("Lost messages of {$e->consumer}, resume from {$e->streamResumeSequence}"); + } +}); +``` + #### Pull Consumer Additionally, you can use `PullConsumer::consume`. This method handles message buffering, periodically requests the server and monitors timeouts to automatically request the next message batch. @@ -990,6 +1050,71 @@ $consumer->consume( ); ``` +Messages can also be read from an iterator with `PullConsumer::consumeIterator()`: the next message is taken only once the previous one has been read. + +```php +pulling()->consumeIterator(new JetStream\PullConsumeConfig(maxMessages: 100)); + +foreach ($iterator as $delivery) { + dump($delivery->message->payload); + $delivery->ack(); + + if ($done) { + $iterator->stop(); + } +} +``` + +#### Ordered Consumer + +An ordered consumer reads a stream in order, without gaps and without acknowledgements, e.g. to replay or to inspect it. The client creates an ephemeral push consumer with flow control and heartbeats +and replaces it with a new one, starting right after the last message delivered, once a message is lost (e.g. dropped beyond the pending limits), the heartbeats stop, +the consumer is deleted or the connection is restored. The consumers are created on `consume()` and deleted when the subscription completes; a following `consume()` continues after the last message. + +```php +jetStream(); + +$consumer = $js->orderedConsumer('Orders', new JetStream\OrderedConsumerConfig( + filterSubjects: ['orders.created'], + deliverPolicy: Api\DeliverPolicy::ByStartSequence, + startSeq: 100, +)); + +$subscription = $consumer->consume( + static function (JetStream\Delivery $delivery): void { + dump($delivery->metadata?->streamSequence, $delivery->message->payload); + }, +); + +// or read them from an iterator +$consumer->stop(); + +foreach ($consumer->consumeIterator() as $delivery) { + dump($delivery->message->payload); +} +``` + +`Stream::orderedConsumer()` does the same for a stream at hand. The heartbeat interval (5 seconds by default), the inactive threshold of the server consumers, +the number of reset attempts before the subscription fails (unlimited by default) and the pending limits are set through `OrderedConsumerConfig`. +A consumer is consumed by one subscription at a time. + #### Get message ```php diff --git a/src/Client.php b/src/Client.php index c1c1d8f..8dbe71f 100644 --- a/src/Client.php +++ b/src/Client.php @@ -289,7 +289,7 @@ public function subscribeIterator( pendingLimits: $pendingLimits, ); - return self::iterate($queue, $subscription); + return Iter\PipelineIterator::fromSubscription($queue, $subscription); } /** @@ -410,7 +410,7 @@ public function requestMany( throw $e; } - return self::iterate($queue, $subscription); + return Iter\PipelineIterator::fromSubscription($queue, $subscription); } /** @@ -715,6 +715,72 @@ private function register( return $subscription; } + /** + * Subscribes one more subject into an active subscription: its messages go to the same handler, in turn with the others + * and under the same pending limits. E.g. an ordered consumer switches its deliveries to a new subject without + * replacing the subscription it handed out, while the server counts only a literal subject as an interest. + * A JetStream delivery carries the subject of the stored message, not the one subscribed, so $onReceive tells + * which deliveries came through this subject: it is called with each of them before it is queued. + * + * @internal + * @param non-empty-string $subject + * @param \Closure(Delivery): void $onReceive + * @return \Closure(?Cancellation=): void unsubscribes the subject + * @throws NatsException + * @throws \Throwable + */ + public function attach( + Subscription $subscription, + string $subject, + \Closure $onReceive, + ?Cancellation $cancellation = null, + ): \Closure { + $push = null; + foreach ($this->subscribers as $subscriber) { + if ($subscriber->subscription === $subscription) { + $push = $subscriber->push; + break; + } + } + + if ($push === null) { + throw new \LogicException('The subscription is not active.'); + } + + $subscriptionId = $this->subscriptionIdGenerator->nextId(); + + // Without the subscription: it is completed through its own subject only. + $this->subscribers[$subscriptionId] = new Subscriber( + subject: $subject, + queueGroup: null, + push: static function (Delivery $delivery) use ( + $push, + $onReceive, + ): bool { + $onReceive($delivery); + + return $push($delivery); + }, + ); + + try { + $this->sub($subject, $subscriptionId, cancellation: $cancellation); + } catch (\Throwable $e) { + unset($this->subscribers[$subscriptionId]); + + throw $e; + } + + $client = \WeakReference::create($this); + + return static function (?Cancellation $cancellation = null) use ( + $client, + $subscriptionId, + ): void { + $client->get()?->unsubscribe($subscriptionId, $cancellation); + }; + } + /** * @param non-empty-string $subject * @param callable(Delivery): void $handler @@ -921,7 +987,12 @@ private function failSubscriptions(Protocol\Err $error, \Throwable $e): bool return $failed; } - private function reportError(\Throwable $e): void + /** + * Reports an error that does not end anything to the {@see self::onError()} callbacks, e.g. one of a JetStream consumer. + * + * @internal + */ + public function reportError(\Throwable $e): void { $this->logger->warning('Nats error: {message}', ['message' => $e->getMessage(), 'exception' => $e]); @@ -1022,37 +1093,6 @@ private function closed(Connection\Connection $connection, ?\Throwable $error): } } - /** - * @param Pipeline\Queue $queue - * @return Iterator - */ - private static function iterate(Pipeline\Queue $queue, Subscription $subscription): Iterator - { - // The iterator ends the way the subscription does: cleanly after stop() or drain(), with the error - // after a failure, e.g. the connection closed by the server. Otherwise the consumer would wait forever. - $future = async(static function () use ( - $queue, - $subscription, - ): void { - try { - $subscription->awaitCompletion(); - } catch (\Throwable $e) { - if (!$queue->isComplete()) { - $queue->error($e); - } - - return; - } - - if (!$queue->isComplete()) { - $queue->complete(); - } - }); - $future->ignore(); - - return Iter\PipelineIterator::fromQueue($queue, $subscription); - } - /** * Awaits the future, returning null if it has failed: the failure has already been reported * to the caller who initiated the operation, and there is nothing to clean up. diff --git a/src/Exception/ConsumerSequenceMismatch.php b/src/Exception/ConsumerSequenceMismatch.php new file mode 100644 index 0000000..5812723 --- /dev/null +++ b/src/Exception/ConsumerSequenceMismatch.php @@ -0,0 +1,40 @@ + + */ + public static function header(): ScalarKey + { + /** + * @var ScalarKey + * @phpstan-ignore varTag.type + */ + return ScalarKey::int(self::HEADER); + } +} diff --git a/src/Header/LastStream.php b/src/Header/LastStream.php new file mode 100644 index 0000000..8f93288 --- /dev/null +++ b/src/Header/LastStream.php @@ -0,0 +1,27 @@ + + */ + public static function header(): ScalarKey + { + /** + * @var ScalarKey + * @phpstan-ignore varTag.type + */ + return ScalarKey::int(self::HEADER); + } +} diff --git a/src/Internal/Iter/PipelineIterator.php b/src/Internal/Iter/PipelineIterator.php index 00ab71c..8454665 100644 --- a/src/Internal/Iter/PipelineIterator.php +++ b/src/Internal/Iter/PipelineIterator.php @@ -38,6 +38,41 @@ public static function fromQueue( ); } + /** + * The iterator ends the way the subscription does: cleanly after stop() or drain(), with the error after a failure, + * e.g. the connection closed by the server. Otherwise the consumer would wait forever. + * + * @template E + * @param Pipeline\Queue $queue + * @return self + */ + public static function fromSubscription( + Pipeline\Queue $queue, + Subscription $subscription, + ): self { + $future = async(static function () use ( + $queue, + $subscription, + ): void { + try { + $subscription->awaitCompletion(); + } catch (\Throwable $e) { + if (!$queue->isComplete()) { + $queue->error($e); + } + + return; + } + + if (!$queue->isComplete()) { + $queue->complete(); + } + }); + $future->ignore(); + + return self::fromQueue($queue, $subscription); + } + /** * @param Pipeline\Pipeline $pipeline * @param Pipeline\Queue<*> $queue diff --git a/src/JetStream.php b/src/JetStream.php index 4b3b53b..a721d2d 100644 --- a/src/JetStream.php +++ b/src/JetStream.php @@ -268,6 +268,26 @@ public function pushConsumer(string $stream, string $consumer): JetStream\PushCo return $this->consumer($stream, $consumer)->pushing(); } + /** + * The server consumers are created once it starts consuming, see {@see JetStream\OrderedConsumer}. + * + * @param non-empty-string $stream + * @throws Exception\InvalidName + */ + public function orderedConsumer( + string $stream, + JetStream\OrderedConsumerConfig $config = new JetStream\OrderedConsumerConfig(), + ): JetStream\OrderedConsumer { + Validate::name($stream); + + return new JetStream\OrderedConsumer( + stream: $stream, + config: $config, + js: $this, + nats: $this->nats, + ); + } + /** * @param non-empty-string $stream * @param non-empty-string $consumer diff --git a/src/JetStream/Delivery.php b/src/JetStream/Delivery.php index 56e01b6..e32ebaa 100644 --- a/src/JetStream/Delivery.php +++ b/src/JetStream/Delivery.php @@ -6,6 +6,7 @@ use Amp\Cancellation; use Amp\Future; +use Thesis\Nats\Header; use Thesis\Nats\JetStream\Internal\Acks; use Thesis\Nats\Message; use Thesis\Nats\NatsException; @@ -36,14 +37,41 @@ public function __construct( ) {} /** + * The size of the message payload. A consumer with headersOnly delivers no payload, then it is the size of the stored one. + * + * @return non-negative-int + */ + public function payloadSize(): int + { + return $this->message->headers?->get(Header\MsgSize::header()) ?? \strlen($this->message->payload ?? ''); + } + + /** + * Sends the acknowledgement without waiting for the server, see {@see self::ackSync()} to wait. + * * @throws NatsException */ - public function ack(bool $sync = false, ?Cancellation $cancellation = null): void + public function ack(?Cancellation $cancellation = null): void { if (($reply = $this->replyTo) !== null) { $ack = $this->acks->ack(...); - $this->doAck(static fn() => $ack($reply, $sync, $cancellation), $cancellation); + $this->doAck(static fn() => $ack($reply, $cancellation), $cancellation); + } + } + + /** + * Acknowledges and waits until the server confirms it has processed the acknowledgement, so the message + * is not redelivered afterwards. Throws when the server does not confirm it, e.g. the consumer is deleted. + * + * @throws NatsException + */ + public function ackSync(?Cancellation $cancellation = null): void + { + if (($reply = $this->replyTo) !== null) { + $ackSync = $this->acks->ackSync(...); + + $this->doAck(static fn() => $ackSync($reply, $cancellation), $cancellation); } } diff --git a/src/JetStream/FetchConfig.php b/src/JetStream/FetchConfig.php index 52ab8c5..cf90a2d 100644 --- a/src/JetStream/FetchConfig.php +++ b/src/JetStream/FetchConfig.php @@ -17,9 +17,14 @@ public TimeSpan $heartbeat; - public static function immediate(): self + /** + * Takes the messages available right now, at most $batch, and does not wait for more. + * + * @param positive-int $batch + */ + public static function immediate(int $batch = self::DEFAULT_BATCH): self { - return new self(noWait: true); + return new self(batch: $batch, noWait: true); } /** diff --git a/src/JetStream/Internal/Acks.php b/src/JetStream/Internal/Acks.php index 0bb2c54..1ba9a88 100644 --- a/src/JetStream/Internal/Acks.php +++ b/src/JetStream/Internal/Acks.php @@ -39,14 +39,21 @@ public function __construct( /** * @param non-empty-string $replyTo */ - public function ack(string $replyTo, bool $sync = false, ?Cancellation $cancellation = null): void + public function ack(string $replyTo, ?Cancellation $cancellation = null): void { - $handler = match ($sync) { - true => $this->request, - default => $this->publish, - }; + ($this->publish)( + $replyTo, + new Message('+ACK'), + $cancellation, + ); + } - $handler( + /** + * @param non-empty-string $replyTo + */ + public function ackSync(string $replyTo, ?Cancellation $cancellation = null): void + { + ($this->request)( $replyTo, new Message('+ACK'), $cancellation, diff --git a/src/JetStream/Internal/Ordered/Cursor.php b/src/JetStream/Internal/Ordered/Cursor.php new file mode 100644 index 0000000..2f3e55c --- /dev/null +++ b/src/JetStream/Internal/Ordered/Cursor.php @@ -0,0 +1,51 @@ +consumerSequence === $this->consumerSequence + 1; + } + + public function advance(Metadata $metadata): void + { + $this->consumerSequence = max($metadata->consumerSequence, 0); + $this->streamSequence = max($metadata->streamSequence, 0); + } + + /** + * A new server consumer starts its sequence anew. + * + * @return positive-int the number of the new consumer + */ + public function nextGeneration(): int + { + $this->consumerSequence = 0; + + return ++$this->generation; + } +} diff --git a/src/JetStream/Internal/Ordered/OrderedMessageHandler.php b/src/JetStream/Internal/Ordered/OrderedMessageHandler.php new file mode 100644 index 0000000..86d4251 --- /dev/null +++ b/src/JetStream/Internal/Ordered/OrderedMessageHandler.php @@ -0,0 +1,409 @@ + the consumer being replaced */ + private ?Future $reset = null; + + private ?Subscription $subscription = null; + + /** @var \WeakMap the consumer generation each delivery came from */ + private readonly \WeakMap $generations; + + private readonly Watchdog $watchdog; + + /** Cancelled once the subscription completes: a reset waiting to retry gives up. */ + private readonly DeferredCancellation $stopped; + + /** + * @param callable(JetStreamDelivery, Subscription): void $handler + * @param non-empty-string $stream + * @param non-empty-string $namePrefix + * @param non-empty-string $inbox the deliver subjects are "." + */ + public function __construct( + private readonly mixed $handler, + private readonly Client $nc, + private readonly JetStream $js, + private readonly OrderedConsumerConfig $config, + private readonly Cursor $cursor, + private readonly string $stream, + private readonly string $namePrefix, + private readonly string $inbox, + ) { + $this->stopped = new DeferredCancellation(); + $this->generations = new \WeakMap(); + + // Two heartbeats missed in a row: the consumer is gone or the server does not deliver anymore. + $this->watchdog = new Watchdog($config->heartbeat->mul(2)); + $this->watchdog->stop(); + $this->watchdog->subscribe(fn() => $this->reset()); + } + + /** + * Creates the first consumer, its failure is thrown to the caller: the deliver subject is unsubscribed before that, + * so the client neither keeps it nor subscribes it again after a reconnect. + */ + public function start(Subscription $subscription, ?Cancellation $cancellation = null): void + { + $this->subscription = $subscription; + + $config = $this->nextConsumer(); + $this->attach($cancellation); + + try { + $this->js->createOrUpdateConsumer($this->stream, $config, $cancellation); + } catch (\Throwable $e) { + [$detach, $this->detach] = [$this->detach, null]; + + try { + $detach?->__invoke(new TimeoutCancellation(self::REQUEST_TIMEOUT)); + } catch (\Throwable) { + // The connection is gone, the server-side subscription with it. + } + + throw $e; + } + + $this->watchdog->reset(); + } + + public function __invoke(NatsDelivery $delivery, Subscription $subscription): void + { + $this->watchdog->stop(); + + $this->handle($delivery, $subscription); + + if (!$subscription->completed() && $this->reset === null) { + $this->watchdog->reset(); + } + } + + public function disconnected(): void + { + $this->watchdog->stop(); + } + + /** + * The flow control replies may have been lost with the connection, and the server would wait for them forever. + */ + public function reconnected(): void + { + $this->reset(); + } + + /** + * Called once the subscription completes: the consumer and its deliver subject are not needed anymore. + */ + public function stop(): void + { + $this->stopped->cancel(); + $this->watchdog->stop(); + $this->detach(); + $this->deleteConsumer($this->consumer); + } + + private function handle(NatsDelivery $delivery, Subscription $subscription): void + { + // Sent by a consumer already replaced. + if (($this->generations[$delivery] ?? null) !== $this->cursor->generation) { + return; + } + + $headers = $delivery->message->headers; + + if (($headers?->statusCode() ?? Status::OK) !== Status::OK) { + $description = $headers?->statusDescription(); + + if ($description?->is(Description::FlowControl) ?? false) { + $delivery->reply(new Message()); + } elseif ($description?->is(Description::IdleHeartbeat) ?? false) { + $this->heartbeat($delivery); + } elseif ($description?->is(Description::ConsumerDeleted) ?? false) { + $this->reset(); + } + + return; + } + + $jsDelivery = $this->nc->toJetStreamDelivery($delivery); + $metadata = $jsDelivery->metadata; + + if ($metadata === null) { + return; + } + + if (!$this->cursor->follows($metadata)) { + $this->reset(); + + return; + } + + $this->cursor->advance($metadata); + + ($this->handler)($jsDelivery, $subscription); + } + + private function heartbeat(NatsDelivery $heartbeat): void + { + $headers = $heartbeat->message->headers; + + // The server still waits for the reply to a flow control request: it may have been lost, reply again as nats.go does. + $stalled = $headers?->get(Header\ConsumerStalled::header()); + if ($stalled !== null && $stalled !== '') { + $this->nc->publish($stalled, new Message()); + } + + $delivered = $headers?->get(Header\LastConsumer::header()); + if ($delivered !== null && $delivered !== $this->cursor->consumerSequence) { + $this->reset(); + } + } + + /** + * Replaces the consumer in the background: messages keep coming meanwhile, the ones of the replaced consumer are ignored. + */ + private function reset(): void + { + if ($this->reset !== null || ($this->subscription?->completed() ?? true)) { + return; + } + + $this->watchdog->stop(); + + $this->reset = async(function (): void { + try { + $this->recreate(); + } catch (CancelledException) { + // The subscription has completed while waiting to retry. + } catch (\Throwable $e) { + $subscription = $this->subscription; + if ($subscription !== null && !$subscription->completed()) { + $subscription->error($e); + } + } finally { + $this->reset = null; + + if (!($this->subscription?->completed() ?? true)) { + $this->watchdog->reset(); + } + } + }); + $this->reset->ignore(); + } + + /** + * @throws CancelledException + * @throws \Throwable + */ + private function recreate(): void + { + $this->detach(); + $this->deleteConsumer($this->consumer); + + $config = $this->nextConsumer(); + $created = $this->consumer; + + $attempts = 0; + $interval = self::RESET_INITIAL_INTERVAL; + + while (!($this->subscription?->completed() ?? true)) { + try { + $this->attach(new TimeoutCancellation(self::REQUEST_TIMEOUT)); + $this->js->createOrUpdateConsumer($this->stream, $config, new TimeoutCancellation(self::REQUEST_TIMEOUT)); + } catch (StreamNotFound $e) { + // Nothing to read anymore: retrying would never end. + throw $e; + } catch (\Throwable $e) { + if ($this->config->maxResetAttempts !== null && ++$attempts >= $this->config->maxResetAttempts) { + throw $e; + } + + $this->nc->reportError($e); + + delay($interval, cancellation: $this->stopped->getCancellation()); + $interval = min($interval * 2, self::RESET_MAX_INTERVAL); + + continue; + } + + // Completed while the consumer was being created: stop() could not delete it yet. + if ($this->subscription?->completed() ?? true) { + $this->detach(); + $this->deleteConsumer($created); + } + + return; + } + } + + /** + * Switches to the next consumer before it is created: the server may deliver to it before the creation is confirmed. + */ + private function nextConsumer(): ConsumerConfig + { + $generation = $this->cursor->nextGeneration(); + $this->consumer = "{$this->namePrefix}_{$generation}"; + $this->deliverSubject = "{$this->inbox}.{$generation}"; + + $config = $this->config; + $filterSubjects = $config->filterSubjects; + + // Nothing delivered yet: start where asked, otherwise right after the last message. + if ($this->cursor->streamSequence === 0) { + $deliverPolicy = $config->deliverPolicy; + $startSeq = $deliverPolicy === DeliverPolicy::ByStartSequence ? $config->startSeq : null; + $startTime = $deliverPolicy === DeliverPolicy::ByStartTime ? $config->startTime : null; + + if ($deliverPolicy === DeliverPolicy::LastPerSubject && $filterSubjects === []) { + $filterSubjects = ['>']; + } + } else { + $deliverPolicy = DeliverPolicy::ByStartSequence; + $startSeq = $this->cursor->streamSequence + 1; + $startTime = null; + } + + return new ConsumerConfig( + name: $this->consumer, + description: 'ordered consumer', + deliverPolicy: $deliverPolicy, + deliverSubject: $this->deliverSubject, + startSeq: $startSeq, + startTime: $startTime, + ackPolicy: AckPolicy::None, + maxDeliver: 1, + filterSubject: \count($filterSubjects) === 1 ? $filterSubjects[0] : null, + flowControl: true, + idleHeartbeat: $config->heartbeat, + replayPolicy: $config->replayPolicy, + headersOnly: $config->headersOnly ? true : null, + inactiveThreshold: $config->inactiveThreshold, + replicas: 1, + memoryStorage: true, + filterSubjects: \count($filterSubjects) > 1 ? $filterSubjects : null, + metadata: $config->metadata, + ); + } + + /** + * Subscribes the deliver subject of the current consumer, once: the SUB goes before the consumer is created, + * so the server sees the interest at once. + */ + private function attach(?Cancellation $cancellation = null): void + { + if ($this->detach !== null || $this->subscription === null || $this->deliverSubject === null) { + return; + } + + $generations = $this->generations; + $generation = $this->cursor->generation; + + $this->detach = $this->nc->attach( + $this->subscription, + $this->deliverSubject, + static function (NatsDelivery $delivery) use ( + $generations, + $generation, + ): void { + $generations[$delivery] = $generation; + }, + $cancellation, + ); + } + + private function detach(): void + { + [$detach, $this->detach] = [$this->detach, null]; + + if ($detach === null) { + return; + } + + $future = async(static function () use ($detach): void { + try { + $detach(new TimeoutCancellation(self::REQUEST_TIMEOUT)); + } catch (\Throwable) { + // The connection is gone, the server-side subscription with it. + } + }); + $future->ignore(); + } + + /** + * @param ?non-empty-string $consumer + */ + private function deleteConsumer(?string $consumer): void + { + if ($consumer === null) { + return; + } + + $js = $this->js; + $stream = $this->stream; + + // Best effort: a consumer left behind is removed by the server after the inactive threshold. + $future = async(static function () use ( + $js, + $stream, + $consumer, + ): void { + try { + $js->deleteConsumer($stream, $consumer, new TimeoutCancellation(self::REQUEST_TIMEOUT)); + } catch (\Throwable) { + } + }); + $future->ignore(); + } +} diff --git a/src/JetStream/Internal/PushMessageHandler.php b/src/JetStream/Internal/PushMessageHandler.php index ae86235..9a89b51 100644 --- a/src/JetStream/Internal/PushMessageHandler.php +++ b/src/JetStream/Internal/PushMessageHandler.php @@ -7,8 +7,10 @@ use Thesis\Nats\Client; use Thesis\Nats\Delivery as NatsDelivery; use Thesis\Nats\Description; +use Thesis\Nats\Exception\ConsumerSequenceMismatch; use Thesis\Nats\Header; use Thesis\Nats\JetStream\Delivery as JetStreamDelivery; +use Thesis\Nats\JetStream\Metadata; use Thesis\Nats\Message; use Thesis\Nats\Status; use Thesis\Nats\Subscription; @@ -16,15 +18,24 @@ /** * @internal */ -final readonly class PushMessageHandler +final class PushMessageHandler { + /** The last message received, null until the first one: the heartbeats are compared with it. */ + private ?Metadata $last = null; + + /** The consumer sequence of the last gap reported. */ + private int $reported = 0; + /** * @param callable(JetStreamDelivery, Subscription): void $handler + * @param bool $sequenced whether this subscription receives every message of the consumer, i.e. it has no deliver group, + * and so a heartbeat naming a later consumer sequence than the last one received means a gap */ public function __construct( - private mixed $handler, - private Client $nc, - private Heartbeat\Watchdog $watchdog, + private readonly mixed $handler, + private readonly Client $nc, + private readonly Heartbeat\Watchdog $watchdog, + private readonly bool $sequenced = false, ) {} public function __invoke(NatsDelivery $delivery, Subscription $subscription): void @@ -60,6 +71,8 @@ private function doHandleDelivery( case [Status::Control, Description::IdleHeartbeat]: // @phpstan-ignore switch.type $stalled = $delivery->message->headers?->exists(Header\ConsumerStalled::header()) ?? false; + $this->detectGap($delivery); + if (!$stalled && $this->handler instanceof IdleListener) { $this->handler->idle(); } @@ -73,7 +86,37 @@ private function doHandleDelivery( } if ($delivery->replyTo !== null) { - ($this->handler)($this->nc->toJetStreamDelivery($delivery), $subscription); + $jsDelivery = $this->nc->toJetStreamDelivery($delivery); + $this->last = $jsDelivery->metadata; + + ($this->handler)($jsDelivery, $subscription); } } + + /** + * Like nats.go, compares the consumer sequence of the heartbeat with the last message received, but reports a gap once. + */ + private function detectGap(NatsDelivery $heartbeat): void + { + $last = $this->last; + $delivered = $heartbeat->message->headers?->get(Header\LastConsumer::header()); + + if (!$this->sequenced || $last === null || $delivered === null || $delivered <= max($last->consumerSequence, $this->reported)) { + return; + } + + /** @var positive-int $streamResumeSequence */ + $streamResumeSequence = max($last->streamSequence, 0) + 1; + + $this->nc->reportError(new ConsumerSequenceMismatch( + stream: $last->stream, + consumer: $last->consumer, + consumerSequence: max($last->consumerSequence, 0), + lastConsumerSequence: $delivered, + streamResumeSequence: $streamResumeSequence, + )); + + // The next heartbeats name the same sequence until a message comes: the gap is already reported. + $this->reported = $delivered; + } } diff --git a/src/JetStream/OrderedConsumer.php b/src/JetStream/OrderedConsumer.php new file mode 100644 index 0000000..bdf3dec --- /dev/null +++ b/src/JetStream/OrderedConsumer.php @@ -0,0 +1,143 @@ +cursor = new Ordered\Cursor(); + $this->namePrefix = $config->namePrefix ?? generateUniqueId(10); + } + + /** + * @param callable(JetStreamDelivery, Subscription): void $handler + * @throws ConsumerAlreadyConsuming + * @throws NatsException + */ + public function consume(callable $handler, ?Cancellation $cancellation = null): Subscription + { + if ($this->subscription !== null && !$this->subscription->completed()) { + throw new ConsumerAlreadyConsuming(); + } + + $inbox = $this->nats->newInbox(); + + $messageHandler = new Ordered\OrderedMessageHandler( + handler: $handler, + nc: $this->nats, + js: $this->js, + config: $this->config, + cursor: $this->cursor, + stream: $this->stream, + namePrefix: $this->namePrefix, + inbox: $inbox, + ); + + // Nothing is delivered to the inbox itself: each server consumer gets its own subject attached to this subscription. + $subscription = $this->nats->subscribe( + subject: $inbox, + handler: $messageHandler, + cancellation: $cancellation, + pendingLimits: $this->config->pendingLimits, + ); + + try { + $messageHandler->start($subscription, $cancellation); + } catch (\Throwable $e) { + // The consumer may have been created even so, e.g. when the cancellation came after the request was sent. + $messageHandler->stop(); + $subscription->stop(); + + throw $e; + } + + $unwatch = $this->nats->watchConnection($messageHandler->disconnected(...), $messageHandler->reconnected(...)); + + // Not onComplete(): it is not called when the subscription is completed from the outside, e.g. by the client. + $future = async(static function () use ( + $subscription, + $messageHandler, + $unwatch, + ): void { + try { + $subscription->awaitCompletion(); + } catch (\Throwable) { + } finally { + $unwatch(); + $messageHandler->stop(); + } + }); + $future->ignore(); + + return $this->subscription = $subscription; + } + + /** + * The same as {@see self::consume()}, but the messages are read from the iterator. + * + * @return Iterator + * @throws ConsumerAlreadyConsuming + * @throws NatsException + */ + public function consumeIterator(?Cancellation $cancellation = null): Iterator + { + /** @var Pipeline\Queue $queue */ + $queue = new Pipeline\Queue(); + + $subscription = $this->consume( + static function (JetStreamDelivery $delivery) use ($queue): void { + Iter\push($queue, $delivery); + }, + $cancellation, + ); + + return Iter\PipelineIterator::fromSubscription($queue, $subscription); + } + + public function stop(?Cancellation $cancellation = null): void + { + $this->subscription?->stop($cancellation); + } + + public function drain(?Cancellation $cancellation = null): void + { + $this->subscription?->drain($cancellation); + } +} diff --git a/src/JetStream/OrderedConsumerConfig.php b/src/JetStream/OrderedConsumerConfig.php new file mode 100644 index 0000000..45112d6 --- /dev/null +++ b/src/JetStream/OrderedConsumerConfig.php @@ -0,0 +1,81 @@ + $filterSubjects the subjects to read, all of the stream if empty + * @param DeliverPolicy $deliverPolicy where to start; once a message is delivered, a recreated consumer starts right after it + * @param ?positive-int $startSeq the first stream sequence for {@see DeliverPolicy::ByStartSequence} + * @param ?\DateTimeImmutable $startTime the first message time for {@see DeliverPolicy::ByStartTime} + * @param ?TimeSpan $heartbeat how often the server reports itself when it has nothing to deliver; a consumer missing + * two heartbeats in a row is recreated, 5 seconds by default + * @param ?TimeSpan $inactiveThreshold how long the server keeps a consumer nobody reads from, 5 minutes by default + * @param ?positive-int $maxResetAttempts how many times in a row the consumer is tried to be recreated before the subscription + * fails, null to keep trying + * @param ?array $metadata + * @param ?non-empty-string $namePrefix the prefix of the consumer names, a random one by default + * @param PendingLimits $pendingLimits the messages the handler has not taken yet; the ones beyond them are dropped, + * and the consumer is recreated from the first dropped one + * @throws InvalidName + * @throws InvalidSubject + * @throws \InvalidArgumentException + */ + public function __construct( + public array $filterSubjects = [], + public DeliverPolicy $deliverPolicy = DeliverPolicy::All, + public ?int $startSeq = null, + public ?\DateTimeImmutable $startTime = null, + public ReplayPolicy $replayPolicy = ReplayPolicy::Instant, + public bool $headersOnly = false, + ?TimeSpan $heartbeat = null, + ?TimeSpan $inactiveThreshold = null, + public ?int $maxResetAttempts = null, + public ?array $metadata = null, + public ?string $namePrefix = null, + public PendingLimits $pendingLimits = new PendingLimits(), + ) { + foreach ($this->filterSubjects as $subject) { + Validate::subscribeSubject($subject); + } + + if ($this->namePrefix !== null) { + Validate::name($this->namePrefix); + } + + if ($this->startSeq !== null) { + Validate::count($this->startSeq, 'start sequence'); + } + + if ($this->maxResetAttempts !== null) { + Validate::count($this->maxResetAttempts, 'number of reset attempts'); + } + + $this->heartbeat = $heartbeat ?? TimeSpan::fromSeconds(self::DEFAULT_HEARTBEAT_SECONDS); + $this->inactiveThreshold = $inactiveThreshold ?? TimeSpan::fromMinutes(self::DEFAULT_INACTIVE_THRESHOLD_MINUTES); + + Validate::duration($this->heartbeat->toSeconds(3), 'heartbeat'); + Validate::duration($this->inactiveThreshold->toSeconds(3), 'inactive threshold'); + } +} diff --git a/src/JetStream/PullConsumer.php b/src/JetStream/PullConsumer.php index 54a7ca3..95f975e 100644 --- a/src/JetStream/PullConsumer.php +++ b/src/JetStream/PullConsumer.php @@ -8,7 +8,9 @@ use Amp\Future; use Amp\Pipeline; use Thesis\Nats\Client; +use Thesis\Nats\Internal\Iter; use Thesis\Nats\Internal\Timer; +use Thesis\Nats\Iterator; use Thesis\Nats\JetStream\Api\PullRequest; use Thesis\Nats\JetStream\Api\Router; use Thesis\Nats\JetStream\Delivery as JetStreamDelivery; @@ -102,6 +104,46 @@ public function fetch(FetchConfig $config, ?Cancellation $cancellation = null): ); } + /** + * Waits for one message, at most $maxWait (30 seconds by default). + * + * @return ?JetStreamDelivery null if no message came in time + * @throws NatsException + */ + public function next(?TimeSpan $maxWait = null, ?Cancellation $cancellation = null): ?JetStreamDelivery + { + foreach ($this->fetch(FetchConfig::batch(1, $maxWait), $cancellation) as $delivery) { + return $delivery; + } + + return null; + } + + /** + * The same as {@see self::consume()}, but the messages are read from the iterator: the next one is taken + * from the server buffer only when the previous one has been read. + * + * @return Iterator + * @throws NatsException + */ + public function consumeIterator( + PullConsumeConfig $config = new PullConsumeConfig(), + ?Cancellation $cancellation = null, + ): Iterator { + /** @var Pipeline\Queue $queue */ + $queue = new Pipeline\Queue(); + + $subscription = $this->consume( + static function (JetStreamDelivery $delivery) use ($queue): void { + Iter\push($queue, $delivery); + }, + $config, + $cancellation, + ); + + return Iter\PipelineIterator::fromSubscription($queue, $subscription); + } + /** * @param callable(JetStreamDelivery, Subscription): void $handler * @throws NatsException diff --git a/src/JetStream/PushConsumer.php b/src/JetStream/PushConsumer.php index f192a3b..a863fae 100644 --- a/src/JetStream/PushConsumer.php +++ b/src/JetStream/PushConsumer.php @@ -50,6 +50,8 @@ public function consume( handler: $handler, nc: $this->nats, watchdog: $watchdog, + // Each subscriber of a deliver group sees a part of the consumer sequence. + sequenced: $this->info->config->deliverGroup === null, ); $subscription = $this->nats->subscribe( diff --git a/src/JetStream/Stream.php b/src/JetStream/Stream.php index ebdebbe..1ed74bc 100644 --- a/src/JetStream/Stream.php +++ b/src/JetStream/Stream.php @@ -8,6 +8,7 @@ use Thesis\Nats\Client; use Thesis\Nats\Description; use Thesis\Nats\Exception\HeadersIsInvalid; +use Thesis\Nats\Exception\InvalidName; use Thesis\Nats\Exception\MessageNotFound; use Thesis\Nats\Header; use Thesis\Nats\Headers; @@ -95,6 +96,14 @@ public function consumer(string $consumer): Consumer return $this->js->consumer($this->name, $consumer); } + /** + * @throws InvalidName + */ + public function orderedConsumer(OrderedConsumerConfig $config = new OrderedConsumerConfig()): OrderedConsumer + { + return $this->js->orderedConsumer($this->name, $config); + } + /** * @throws NatsException */ diff --git a/tests/JetStream/OrderedConsumerTest.php b/tests/JetStream/OrderedConsumerTest.php new file mode 100644 index 0000000..2ad3e79 --- /dev/null +++ b/tests/JetStream/OrderedConsumerTest.php @@ -0,0 +1,482 @@ +client()->jetStream(); + [$stream, $subject] = self::createStream($js); + + for ($i = 1; $i <= 5; ++$i) { + $js->publish("{$subject}.{$i}", new Message("m{$i}")); + } + + $consumer = $stream->orderedConsumer(); + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + $subscription = $consumer->consume(static function (JetStreamDelivery $delivery) use ($received): void { + $received[] = (string) $delivery->message->payload; + }); + + self::waitUntil(static fn(): bool => \count($received) === 5); + self::assertSame(['m1', 'm2', 'm3', 'm4', 'm5'], $received->getArrayCopy()); + self::assertCount(1, [...$js->consumerNames($stream->name)]); + + $subscription->stop(); + + self::waitUntil(static fn(): bool => [...$js->consumerNames($stream->name)] === []); + + $stream->delete(); + } + + public function testConsumeIterator(): void + { + $js = $this->client()->jetStream(); + [$stream, $subject] = self::createStream($js); + + for ($i = 1; $i <= 3; ++$i) { + $js->publish("{$subject}.x", new Message("m{$i}")); + } + + $iterator = $stream->orderedConsumer()->consumeIterator(); + + $received = []; + foreach ($iterator as $delivery) { + $received[] = $delivery->metadata?->streamSequence; + + if (\count($received) === 3) { + $iterator->stop(); + } + } + + self::assertSame([1, 2, 3], $received); + + $stream->delete(); + } + + public function testNextConsumeContinuesAfterTheLastMessage(): void + { + $js = $this->client()->jetStream(); + [$stream, $subject] = self::createStream($js); + + for ($i = 1; $i <= 3; ++$i) { + $js->publish("{$subject}.x", new Message("m{$i}")); + } + + $consumer = $stream->orderedConsumer(); + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + $handler = static function (JetStreamDelivery $delivery) use ($received): void { + $received[] = $delivery->metadata?->streamSequence; + }; + + $subscription = $consumer->consume($handler); + self::waitUntil(static fn(): bool => \count($received) === 3); + $subscription->stop(); + + $js->publish("{$subject}.x", new Message('m4')); + $js->publish("{$subject}.x", new Message('m5')); + + $subscription = $consumer->consume($handler); + self::waitUntil(static fn(): bool => \count($received) === 5); + $subscription->stop(); + + self::assertSame([1, 2, 3, 4, 5], $received->getArrayCopy()); + + $stream->delete(); + } + + public function testStartsFromTheGivenSequence(): void + { + $js = $this->client()->jetStream(); + [$stream, $subject] = self::createStream($js); + + for ($i = 1; $i <= 5; ++$i) { + $js->publish("{$subject}.x", new Message("m{$i}")); + } + + $iterator = $stream + ->orderedConsumer(new OrderedConsumerConfig( + deliverPolicy: DeliverPolicy::ByStartSequence, + startSeq: 3, + )) + ->consumeIterator(); + + $received = []; + foreach ($iterator as $delivery) { + $received[] = (string) $delivery->message->payload; + + if (\count($received) === 3) { + $iterator->stop(); + } + } + + self::assertSame(['m3', 'm4', 'm5'], $received); + + $stream->delete(); + } + + public function testFiltersSubjects(): void + { + $js = $this->client()->jetStream(); + [$stream, $subject] = self::createStream($js); + + foreach (['a', 'b', 'c', 'a', 'b'] as $i => $token) { + $js->publish("{$subject}.{$token}", new Message("{$token}{$i}")); + } + + $iterator = $stream + ->orderedConsumer(new OrderedConsumerConfig(filterSubjects: ["{$subject}.a", "{$subject}.c"])) + ->consumeIterator(); + + $received = []; + foreach ($iterator as $delivery) { + $received[] = (string) $delivery->message->payload; + + if (\count($received) === 3) { + $iterator->stop(); + } + } + + self::assertSame(['a0', 'c2', 'a3'], $received); + + $stream->delete(); + } + + public function testRecreatesTheConsumerAfterDroppedMessages(): void + { + $nc = $this->client(); + $js = $nc->jetStream(); + [$stream, $subject] = self::createStream($js); + + $count = 50; + for ($i = 1; $i <= $count; ++$i) { + $js->publish("{$subject}.x", new Message("m{$i}")); + } + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + /** @var \ArrayObject $consumers */ + $consumers = new \ArrayObject(); + + $subscription = $stream + ->orderedConsumer(new OrderedConsumerConfig( + // A dropped tail is revealed by the next heartbeat only. + heartbeat: TimeSpan::fromMilliseconds(500), + // Everything behind the slow first message is dropped but ten; a replacing consumer may drop again. + pendingLimits: new PendingLimits(messages: 10, bytes: null), + )) + ->consume(static function (JetStreamDelivery $delivery) use ($received, $consumers): void { + if ($received->count() === 0) { + delay(0.2); + } + + $received[] = $delivery->metadata->streamSequence ?? 0; + $consumers[$delivery->metadata->consumer ?? ''] = true; + }); + + self::waitUntil(static fn(): bool => \count($received) === $count, timeout: 20); + $subscription->stop(); + + self::assertSame(range(1, $count), $received->getArrayCopy()); + self::assertGreaterThan(1, \count($consumers), 'The consumer must have been recreated.'); + + $stream->delete(); + } + + public function testHeartbeatRevealsTheDroppedLastMessage(): void + { + $js = $this->client()->jetStream(); + [$stream, $subject] = self::createStream($js); + + for ($i = 1; $i <= 3; ++$i) { + $js->publish("{$subject}.x", new Message("m{$i}")); + } + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + + $subscription = $stream + ->orderedConsumer(new OrderedConsumerConfig( + heartbeat: TimeSpan::fromMilliseconds(500), + // The first message is in the handler, the second waits, the third is dropped: no message follows + // it to reveal the gap, only the heartbeat naming the third one as delivered. + pendingLimits: new PendingLimits(messages: 1, bytes: null), + )) + ->consume(static function (JetStreamDelivery $delivery) use ($received): void { + if ($received->count() === 0) { + delay(0.2); + } + + $received[] = (string) $delivery->message->payload; + }); + + self::waitUntil(static fn(): bool => \count($received) === 3); + $subscription->stop(); + + self::assertSame(['m1', 'm2', 'm3'], $received->getArrayCopy()); + + $stream->delete(); + } + + public function testRecreatesTheDeletedConsumer(): void + { + $js = $this->client()->jetStream(); + [$stream, $subject] = self::createStream($js); + + $js->publish("{$subject}.x", new Message('before')); + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + + $subscription = $stream + ->orderedConsumer(new OrderedConsumerConfig(heartbeat: TimeSpan::fromMilliseconds(500))) + ->consume(static function (JetStreamDelivery $delivery) use ($received): void { + $received[] = $delivery; + }); + + self::waitUntil(static fn(): bool => \count($received) === 1); + + $deleted = $received[0]->metadata->consumer ?? ''; + self::assertNotSame('', $deleted); + $stream->deleteConsumer($deleted); + + $js->publish("{$subject}.x", new Message('after')); + + // The heartbeats stop with the consumer: two missed ones recreate it after the last message. + self::waitUntil(static fn(): bool => \count($received) === 2); + $subscription->stop(); + + $after = $received[1] ?? self::fail('No delivery after the deletion.'); + self::assertSame('after', $after->message->payload); + self::assertSame(2, $after->metadata?->streamSequence); + self::assertNotSame($deleted, $after->metadata->consumer); + + $stream->delete(); + } + + public function testRecreatesTheConsumerAfterReconnect(): void + { + $proxy = PausableProxy::start($this->natsAddress()); + $config = $this->config(); + $nc = new Client(new Config( + urls: [$proxy->address], + user: $config->user, + password: $config->password, + reconnectWait: 0.1, + )); + $publisher = $this->client()->jetStream(); + + /** @var DeferredFuture $reconnected */ + $reconnected = new DeferredFuture(); + $nc->onReconnect(static function () use ($reconnected): void { + if (!$reconnected->isComplete()) { + $reconnected->complete(); + } + }); + + [$stream, $subject] = self::createStream($publisher); + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + + try { + $subscription = $nc + ->jetStream() + ->orderedConsumer($stream->name) + ->consume(static function (JetStreamDelivery $delivery) use ($received): void { + $received[] = $delivery; + }); + + $publisher->publish("{$subject}.x", new Message('before')); + self::waitUntil(static fn(): bool => \count($received) === 1); + + $proxy->disconnect(); + $reconnected->getFuture()->await(new TimeoutCancellation(5)); + + $publisher->publish("{$subject}.x", new Message('after')); + self::waitUntil(static fn(): bool => \count($received) === 2); + $subscription->stop(); + + self::assertSame(['before', 'after'], array_map( + static fn(JetStreamDelivery $delivery): ?string => $delivery->message->payload, + $received->getArrayCopy(), + )); + self::assertNotSame(($received[0] ?? null)?->metadata?->consumer, ($received[1] ?? null)?->metadata?->consumer); + + $stream->delete(); + } finally { + $nc->stop(); + $proxy->kill(); + } + } + + public function testReplacedOnceWithoutEcho(): void + { + $config = $this->config(); + // The client does not receive what it publishes itself: nothing may rely on it. + $nc = $this->clientWithConfig(new Config( + urls: $config->urls, + user: $config->user, + password: $config->password, + noEcho: true, + )); + $js = $nc->jetStream(); + $publisher = $this->client()->jetStream(); + [$stream, $subject] = self::createStream($publisher); + + $publisher->publish("{$subject}.x", new Message('before')); + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + $subscription = $js + ->orderedConsumer($stream->name, new OrderedConsumerConfig(heartbeat: TimeSpan::fromMilliseconds(500))) + ->consume(static function (JetStreamDelivery $delivery) use ($received): void { + $received[] = (string) $delivery->message->payload; + }); + + self::waitUntil(static fn(): bool => \count($received) === 1); + + $deleted = array_values([...$js->consumerNames($stream->name)]); + self::assertCount(1, $deleted); + $stream->deleteConsumer($deleted[0]); + + // The stream is read to the end: the replacing consumer has nothing to deliver, only heartbeats. + self::waitUntil(static fn(): bool => \count([...$js->consumerNames($stream->name)]) === 1); + $replacing = [...$js->consumerNames($stream->name)]; + self::assertNotSame($deleted, $replacing); + + delay(3); + self::assertSame($replacing, [...$js->consumerNames($stream->name)]); + + $publisher->publish("{$subject}.x", new Message('after')); + self::waitUntil(static fn(): bool => \count($received) === 2); + $subscription->stop(); + + self::assertSame(['before', 'after'], $received->getArrayCopy()); + + $stream->delete(); + } + + public function testDeletedStreamFailsTheSubscription(): void + { + $js = $this->client()->jetStream(); + [$stream] = self::createStream($js); + + $subscription = $stream + ->orderedConsumer(new OrderedConsumerConfig(heartbeat: TimeSpan::fromMilliseconds(500))) + ->consume(static function (): void {}); + + $stream->delete(); + + // The heartbeats stop with the stream, and a consumer cannot be created anymore: no endless retries. + self::expectException(StreamNotFound::class); + $subscription->awaitCompletion(new TimeoutCancellation(5)); + } + + public function testOneConsumeAtATime(): void + { + $js = $this->client()->jetStream(); + [$stream] = self::createStream($js); + + $consumer = $stream->orderedConsumer(); + $consumer->consume(static function (): void {}); + + try { + self::expectException(ConsumerAlreadyConsuming::class); + $consumer->consume(static function (): void {}); + } finally { + $consumer->stop(); + $stream->delete(); + } + } + + public function testStreamNotFound(): void + { + $nc = $this->client(); + + $js = $nc->jetStream(); + $consumer = $js->orderedConsumer(generateUniqueId(10)); + + $subscribers = new \ReflectionProperty(Client::class, 'subscribers'); + + try { + // The inbox of the requests to the JetStream API is subscribed once and kept by the client. + $js->accountInfo(); + $before = array_keys((array) $subscribers->getValue($nc)); + + for ($i = 0; $i < 3; ++$i) { + try { + $consumer->consume(static function (): void {}); + self::fail('The stream is expected not to be found.'); + } catch (StreamNotFound) { + } + } + + // Neither the subscription nor the deliver subjects of the consumers that were never created are kept. + self::assertSame($before, array_keys((array) $subscribers->getValue($nc))); + } finally { + // The client stops without waiting for anything left behind. + $nc->stop(new TimeoutCancellation(1)); + } + } + + /** + * @return array{Stream, non-empty-string} + */ + private static function createStream(JetStream $js): array + { + $subject = generateUniqueId(10); + + $stream = $js->createStream(new StreamConfig( + name: generateUniqueId(10), + subjects: ["{$subject}.*"], + )); + + return [$stream, $subject]; + } + + /** + * @param \Closure(): bool $condition + */ + private static function waitUntil(\Closure $condition, float $timeout = 5): void + { + $deadline = microtime(true) + $timeout; + + while (!$condition()) { + if (microtime(true) > $deadline) { + self::fail('The condition was not met in time.'); + } + + delay(0.01); + } + } +} diff --git a/tests/JetStream/PullConsumerTest.php b/tests/JetStream/PullConsumerTest.php index 4e04876..e4319fd 100644 --- a/tests/JetStream/PullConsumerTest.php +++ b/tests/JetStream/PullConsumerTest.php @@ -17,6 +17,7 @@ use Thesis\Nats\Exception\MaxRequestBatchExceeded; use Thesis\Nats\Exception\MaxRequestExpiresExceeded; use Thesis\Nats\Exception\MaxRequestMaxBytesExceeded; +use Thesis\Nats\Exception\RequestHasNoResponders; use Thesis\Nats\Header\StatusCode; use Thesis\Nats\Header\StatusDescription; use Thesis\Nats\Headers; @@ -270,6 +271,146 @@ private static function waitUntil(\Closure $condition): void } } + public function testNextReturnsTheMessage(): void + { + [$stream, $subject, $consumer] = $this->streamWithConsumer(); + + $this->client()->jetStream()->publish("{$subject}.x", new Message('first')); + $this->client()->jetStream()->publish("{$subject}.x", new Message('second')); + + $pulling = $consumer->pulling(); + + self::assertSame('first', $pulling->next(TimeSpan::fromSeconds(1))?->message->payload); + self::assertSame('second', $pulling->next(TimeSpan::fromSeconds(1))?->message->payload); + self::assertNull($pulling->next(TimeSpan::fromSeconds(1))); + + $stream->delete(); + } + + public function testFetchImmediateTakesAtMostTheBatch(): void + { + [$stream, $subject, $consumer] = $this->streamWithConsumer(); + + for ($i = 1; $i <= 5; ++$i) { + $this->client()->jetStream()->publish("{$subject}.x", new Message("m{$i}")); + } + + $pulling = $consumer->pulling(); + + self::assertSame(['m1', 'm2'], self::payloads($pulling->fetch(FetchConfig::immediate(2)))); + self::assertSame(['m3', 'm4', 'm5'], self::payloads($pulling->fetch(FetchConfig::immediate(10)))); + self::assertSame([], self::payloads($pulling->fetch(FetchConfig::immediate(10)))); + + $stream->delete(); + } + + public function testConsumeIterator(): void + { + [$stream, $subject, $consumer] = $this->streamWithConsumer(); + + for ($i = 1; $i <= 3; ++$i) { + $this->client()->jetStream()->publish("{$subject}.x", new Message("m{$i}")); + } + + $iterator = $consumer->pulling()->consumeIterator(); + + $received = []; + foreach ($iterator as $delivery) { + $received[] = $delivery->message->payload; + $delivery->ack(); + + if (\count($received) === 3) { + $iterator->stop(); + } + } + + self::assertSame(['m1', 'm2', 'm3'], $received); + + $stream->delete(); + } + + public function testAckSyncWaitsForTheServer(): void + { + [$stream, $subject, $consumer] = $this->streamWithConsumer(); + + $this->client()->jetStream()->publish("{$subject}.x", new Message('first')); + $this->client()->jetStream()->publish("{$subject}.x", new Message('second')); + + $pulling = $consumer->pulling(); + + $pulling->next(TimeSpan::fromSeconds(1))?->ackSync(); + + // No waiting: the server has processed the ack before confirming it. + self::assertSame(0, $consumer->actualInfo()->numAckPending); + + $delivery = $pulling->next(TimeSpan::fromSeconds(1)); + self::assertNotNull($delivery); + + $consumer->delete(); + + try { + self::expectException(RequestHasNoResponders::class); + $delivery->ackSync(new TimeoutCancellation(5)); + } finally { + $stream->delete(); + } + } + + public function testPayloadSizeOfHeadersOnlyConsumer(): void + { + [$stream, $subject] = $this->streamWithConsumer(); + + $this->client()->jetStream()->publish("{$subject}.x", new Message('hello')); + + $full = $stream->createConsumer(new ConsumerConfig(durableName: generateUniqueId(10))); + $headersOnly = $stream->createConsumer(new ConsumerConfig(durableName: generateUniqueId(10), headersOnly: true)); + + $delivery = $full->pulling()->next(TimeSpan::fromSeconds(1)); + self::assertSame('hello', $delivery?->message->payload); + self::assertSame(5, $delivery->payloadSize()); + + $delivery = $headersOnly->pulling()->next(TimeSpan::fromSeconds(1)); + self::assertNotNull($delivery); + self::assertEmpty($delivery->message->payload); + self::assertSame(5, $delivery->payloadSize()); + + $stream->delete(); + } + + /** + * @param DeliveryBatch $batch + * @return list + */ + private static function payloads(DeliveryBatch $batch): array + { + $payloads = []; + foreach ($batch as $delivery) { + $payloads[] = $delivery->message->payload; + } + + return $payloads; + } + + /** + * @return array{Stream, non-empty-string, Consumer} + */ + private function streamWithConsumer(): array + { + $js = $this->client()->jetStream(); + $subject = generateUniqueId(10); + + $stream = $js->createStream(new StreamConfig( + name: generateUniqueId(10), + subjects: ["{$subject}.*"], + )); + + $consumer = $stream->createConsumer( + new ConsumerConfig(durableName: generateUniqueId(10), ackPolicy: AckPolicy::Explicit), + ); + + return [$stream, $subject, $consumer]; + } + public function testStopFromHandlerDoesNotPullAfterwards(): void { $nc = $this->client(); diff --git a/tests/JetStream/PushConsumerTest.php b/tests/JetStream/PushConsumerTest.php index dccfb72..eb23fba 100644 --- a/tests/JetStream/PushConsumerTest.php +++ b/tests/JetStream/PushConsumerTest.php @@ -6,14 +6,17 @@ use PHPUnit\Framework\Attributes\CoversClass; use Thesis\Nats\Exception\ConsumerAlreadyConsuming; +use Thesis\Nats\Exception\ConsumerSequenceMismatch; use Thesis\Nats\JetStream\Api\AckPolicy; use Thesis\Nats\JetStream\Api\ConsumerConfig; use Thesis\Nats\JetStream\Api\StreamConfig; use Thesis\Nats\JetStream\Delivery as JetStreamDelivery; use Thesis\Nats\Message; use Thesis\Nats\NatsTestCase; +use Thesis\Nats\PendingLimits; use Thesis\Nats\Subscription; use Thesis\Time\TimeSpan; +use function Amp\delay; use function Thesis\Nats\Internal\Id\generateInboxId; use function Thesis\Nats\Internal\Id\generateUniqueId; @@ -205,4 +208,70 @@ public function testNackWithDelayDelivery(): void $stream->delete(); } + + public function testHeartbeatRevealsDroppedMessages(): void + { + $nc = $this->client(); + $js = $nc->jetStream(); + + $subject = generateUniqueId(10); + $stream = $js->createStream(new StreamConfig( + name: generateUniqueId(10), + subjects: ["{$subject}.*"], + )); + + for ($i = 1; $i <= 5; ++$i) { + $js->publish("{$subject}.x", new Message("m{$i}")); + } + + /** @var \ArrayObject $mismatches */ + $mismatches = new \ArrayObject(); + $nc->onError(static function (\Throwable $e) use ($mismatches): void { + if ($e instanceof ConsumerSequenceMismatch) { + $mismatches[] = $e; + } + }); + + $consumer = $stream->createConsumer(new ConsumerConfig( + durableName: generateUniqueId(10), + deliverSubject: generateInboxId(), + ackPolicy: AckPolicy::None, + idleHeartbeat: TimeSpan::fromMilliseconds(500), + )); + + /** @var \ArrayObject $received */ + $received = new \ArrayObject(); + $subscription = $consumer->push( + static function (JetStreamDelivery $delivery) use ($received): void { + if ($received->count() === 0) { + delay(0.2); + } + + $received[] = $delivery->metadata->consumerSequence ?? 0; + }, + // The first message is in the handler, the next one waits, the rest is dropped. + new PushConsumeConfig(pendingLimits: new PendingLimits(messages: 1, bytes: null)), + ); + + $deadline = microtime(true) + 5; + + while (\count($mismatches) === 0 && microtime(true) < $deadline) { + delay(0.05); + } + + // Every next heartbeat names the same sequence: reported once. + delay(1.2); + $subscription->stop(); + + self::assertCount(1, $mismatches); + $mismatch = $mismatches[0] ?? self::fail('No mismatch reported.'); + self::assertSame($stream->name, $mismatch->stream); + self::assertSame($consumer->name, $mismatch->consumer); + self::assertSame(5, $mismatch->lastConsumerSequence); + self::assertSame(max([0, ...$received->getArrayCopy()]), $mismatch->consumerSequence); + self::assertLessThan(5, $mismatch->consumerSequence); + self::assertSame($mismatch->consumerSequence + 1, $mismatch->streamResumeSequence); + + $stream->delete(); + } }