antevemus / aspecification-redis-streams
Redis Streams satellite of antevemus/aspecification: the transport and the source of its messaging hook over Redis Streams (XADD, consumer groups, XAUTOCLAIM recovery, dead letter stream), at-least-once with per-key order, over predis
Package info
github.com/antevemus-it/Antevemus.ASpecificationRedisStreams
pkg:composer/antevemus/aspecification-redis-streams
Requires
- php: ^8.2
- antevemus/aspecification: ^2.15
- predis/predis: ^2.0
Requires (Dev)
- infection/infection: ^0.31.9 || ^0.35.6
- phpunit/phpunit: ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
The Redis Streams satellite of the messaging hook of ASpecification for PHP 8.2+. RedisStreamsTransport is the broker the core's OutboxRelay sends to (one stream per message name, XADD in one round trip per batch, confirmed by the id of the entry); RedisStreamsSource is what the core's MessageConsumer reads (one consumer group per consumer, XREADGROUP with BLOCK, XACK). At least once with the inbox of the core, the order of each ordering key kept across the streams of several names, a delivery given back before the later ones of its key, a dead letter stream, the recovery of what a dead process left pending (XAUTOCLAIM), invalid deliveries never dropped, and no payload in any reason. Never Pub/Sub. Pure PHP over predis: no extension is required.
Install with composer require antevemus/aspecification-redis-streams; it needs a Redis 7.0 or later server.
Quick Start
<?php declare(strict_types=1); use Antevemus\ASpecification\Messaging\Inbox\InMemoryProcessedMessageStore; use Antevemus\ASpecification\Messaging\Message; use Antevemus\ASpecification\Messaging\MessageConsumer; use Antevemus\ASpecification\Messaging\MessageHandlerRegistry; use Antevemus\ASpecification\Messaging\MessagePublisher; use Antevemus\ASpecification\Messaging\Outbox\InMemoryMessageOutbox; use Antevemus\ASpecification\Messaging\OutboxRelay; use Antevemus\ASpecificationRedisStreams\RedisStreamsSource; use Antevemus\ASpecificationRedisStreams\RedisStreamsTransport; use Predis\Client; $redis = new Client('tcp://127.0.0.1:6379'); // The consumer group "agents" reads the stream of one message name: declare it before the relay runs. $source = new RedisStreamsSource($redis, 'agents', ['underwriting.quote_submitted.v1'], 'agents-1'); $source->declare(); // Publish into the outbox (in production, PdoMessageOutbox inside the transaction of the write)... $outbox = new InMemoryMessageOutbox(); (new MessagePublisher($outbox))->publish(new Message( 'underwriting.quote_submitted.v1', ['quote_id' => 123, 'premium' => 1250.0], orderingKey: 'quote:123', tenant: 'acme' )); // ...and relay it to Redis: an XADD to the stream aspec.underwriting.quote_submitted.v1. $relay = new OutboxRelay($outbox, new RedisStreamsTransport($redis), maxAttempts: 10); $relay->relayPending(100)->deliveredCount(); // 1 // Consume it once per consumer: the inbox absorbs a delivery that comes twice. $tasks = []; $handlers = (new MessageHandlerRegistry())->register('underwriting.quote_submitted.v1', function (Message $message) use (&$tasks): void { $tasks[] = $message->payload['quote_id']; }); $consumer = new MessageConsumer('agents', $source, $handlers, new InMemoryProcessedMessageStore()); count($consumer->consume(100, waitMs: 1000)->handledIds()); // 1 $tasks; // [123]
Documentation
The official documentation lives in docs/en (and in Portuguese, in docs/pt-BR); every PHP block of it runs in the test suite, against a real Redis.
| Page | What it covers |
|---|---|
| Installation and quick start | Composer, the requirements, the Redis server and the Quick Start. |
| Delivery, order and failures | The keys in Redis, at least once with the inbox, the order across streams, the deliveries given back, the dead letters, the recovery of a dead process, the invalid deliveries and the secrecy of the reasons. |
| RedisStreamsTopology | The prefix of the keys, the cap of the streams, the idle time of the recovery, the longest block. |
| RedisStreamsTransport | The hook out: what an entry holds, what is confirmed and what fails. |
| RedisStreamsSource | The hook in: the group and its members, receive(), ack(), reject(), deadLetters(). |
| Tests | The contract battery of the core (Writing a satellite) run against a real Redis, with its property sequence, the tests of Redis itself and the mutation testing. |
| Roadmap | What shipped and what may come. |
License
MIT, see LICENSE. Provenance in NOTICE.md; changes in CHANGELOG.md.