4.0.0

Queue 4.0.0 unifies single and batch consumption and adds scheduled recovery of stranded Redis claims.

Breaking changes

Consumer::receive() now always returns a list:

$messages = $consumer->receive($queue, $timeout, n: 8);
$message = $consumer->receive($queue, $timeout)[0] ?? null;

• Replace receiveBatch($queue, $timeout, $n) with receive($queue, $timeout, $n).
• Consumer\Batched is removed. Custom consumers must implement receive(Queue $queue, int $timeout, int $n = 1): array.
• Custom Connection implementations must implement setNotExists(string $key, string $value, int $ttl = 0): bool with atomic set-if-absent semantics and expiry when requested.
• Each returned message still needs its own acknowledgment. Counts below one use one; an empty list means no message was received.

Recovery and reliability

• Redis claims receive expiring heartbeats. Swoole handlers refresh them while running.
• Maintenance schedules bounded recovery with a per-queue lock and shared scan progress, including progress past live claims and wraparound under continuous arrivals.
• Missing Redis and Redis Cluster keys return null; stored empty strings remain unchanged.
• NATS retries a timed-out publish after reconnecting, retaining its message ID for server-side deduplication.

Adoption notes

The default Redis reapAfter remains 90,000 seconds (25 hours since publication). An expired heartbeat alone does not bypass this age gate. Keep the default conservative until every relevant worker heartbeats.

Recovery needs a running maintenance path. A pooled broker is swept only while idle: continuous blocking receives can prevent recovery in Appwrite's shared size-one pool. Cloud's dedicated receive connection and separate locked commands connection passed a focused Dragonfly recovery check. KubernetesJob workers do not run the Swoole heartbeat/maintenance scheduler; retain their existing recovery mechanism.

Appwrite and Cloud require coordinated consumer/test migrations and dependency updates before adoption. In particular, the currently pinned utopia-php/platform 1.0.0-rc21 does not allow queue 4.x; its dependency constraint also needs updating. This release does not update or deploy either application. See the consumer compatibility audit.

Validation

Queue and linked-platform CI passed on the merged commit. The release source also passed local queue checks (Pint, PHPStan, Rector), 183 unit tests / 437 assertions before the final test-only adjustment, and the final Redis expiry regressions on standalone Redis and Redis Cluster, including injected scheduling delays.

Queue PR · All changes since 3.0.0