Redis Transport Laravel Package

Getting Started

• Install the Redis queue driver for RabbitEvents (v1.0.0) alongside rabbitevents/foundation ^10.0. If you’re still on RabbitEvents 9, stay on the 0.0.x line.
• Publish/configure the package config (typically config/rabbitevents.php). Set the Redis connection, consumer group name, and default queue. Confirm the queue names you’ll use—each queue now maps to a shared topic stream plus a direct stream rabbitevents:queue:{queue} and a failed stream {queue}.failed.
• First place to look: the queue configuration and the rabbitevents:failed command. These tell you how retries, requeues, and failures are isolated per queue.
• First use case: define a listener that handles an event, dispatch the event, and run the RabbitEvents worker for your queue (e.g., php artisan rabbitevents:listen --queue=default). Then deliberately fail a job and verify it shows up via php artisan rabbitevents:failed.

Implementation Patterns

• Per-queue retry/failure isolation: Retries, requeues, and failed messages now go to rabbitevents:queue:{queue} rather than the shared topic stream. This lets you scale consumer groups independently and prevents retry storms in one queue from affecting others.
• Failed job management: Use php artisan rabbitevents:failed to list failed messages, rabbitevents:retry {id} to retry, rabbitevents:forget {id} to delete, and rabbitevents:flush to clear. Failed messages live in {queue}.failed (generated by makeFailedQueue()).
• Requeue/reject: requeue() and reject(requeue: true) now re-deliver the message while preserving order, instead of leaving it stuck in the Pending Entries List. Use these for transient failures where you want a retry without immediately marking the job as failed.
• Retry semantics: Redis cannot delay delivery, so --sleep (default 5) is ignored—retries happen immediately. If you need backoff, implement it outside the queue (e.g., dispatch a delayed job to another queue/driver, or schedule a re-dispatch command).
• Upgrade path: After upgrading to v1.0.0, entries already in the shared stream are still delivered (legacy behavior). New retries/requeues/failures go to the direct streams. During rollout, run updated workers and monitor both the shared stream and the new direct streams until the shared stream drains.
• Monitoring: Use Redis XLEN, XINFO GROUPS, and XPENDING to monitor stream lengths, consumer group lag, and pending entries. Add rabbitevents:failed to your ops runbook.

Gotchas and Tips

• No delayed retries: --sleep is a no-op on Redis. Don’t assume Laravel’s backoff config works here. For exponential backoff, use a scheduled job or a separate delayed queue/driver.
• Pending Entries List (PEL): v1.0.0 fixes a bug where an entry could get stuck when a single read returned entries from two streams. Still, monitor PEL for stuck messages (XPENDING) and use XCLAIM if a consumer dies. The package handles requeue/reject better, but operational vigilance helps.
• Upgrade mixing: After upgrading, old retries in the shared stream will still be delivered to every consumer group (pre-1.0 behavior). This can cause duplicate processing across queues until the shared stream is drained. Plan the upgrade during low traffic or drain the shared stream first.
• Redis version: Redis Streams require Redis 5.0+. Ensure your Redis instance supports streams and consumer groups. If using a managed Redis (e.g., AWS ElastiCache), confirm stream support.
• Queue naming: Direct streams use rabbitevents:queue:{queue} and {queue}.failed. Avoid queue names with characters that could clash with Redis key conventions. If you override makeFailedQueue(), keep the naming consistent.
• Debugging: Use redis-cli to inspect streams: XLEN rabbitevents:queue:default, XINFO GROUPS rabbitevents:queue:default, XPENDING rabbitevents:queue:default <group>. Also check Laravel logs for consumer errors. rabbitevents:failed is your first stop for failed messages.
• Extension points: makeFailedQueue() can be overridden in a custom queue class if you need a different failed queue naming scheme. You can also extend the driver to add a delay mechanism (e.g., a scheduled re-dispatch) if immediate retries are unacceptable.