feat(queue): bound the Redis broker's automatic reap sweep - #14243

Review complete. 🟡 1 medium

// packages/queue/src/Broker/Redis.php
484	            $dead = ($maxAttempts !== null && $job->getAttempts() >= $maxAttempts)
485	                || ($newerThan !== null && $job->getTimestamp() < $now - $newerThan);
486	            $moved = $this->script($this->commands, 'reclaim', [
487	                $ownerKey, "{$queue->namespace}.claims.{$queue->name}.{$pid}",
488	                "{$queue->namespace}.jobs.{$queue->name}.{$pid}", $processing,
489	                "{$queue->namespace}.stats.{$queue->name}.processing",
490	                "{$queue->namespace}." . ($dead ? 'dead' : 'queue') . ".{$queue->name}",
491	            ], [\is_string($owner) ? $owner : '', $pid, $dead ? '' : $this->retryPayload($queue, $job), $queue->jobTtl]);

This PR wires two optional constructor parameters through the Redis broker's recovery logic so reaping can park poison messages after a configurable attempt threshold and skip claims newer than a configurable age, with new E2E tests covering both paths.

One medium-severity issue remains: reapMaxAge only filters by the original claim timestamp, so a claim that keeps being requeued never crosses the age boundary and can loop indefinitely instead of being parked.

_{Reviewed commit: 828cdc3}

🟢 Tier S · Ready to merge

The incremental change only clarifies an existing comment and introduces no behavioral defect.

Adds optional maximum-attempt and maximum-age bounds to Redis broker recovery and applies them during automatic maintenance sweeps, parking exhausted claims in the dead queue. Adds real-Redis E2E coverage for age- and attempt-based parking while preserving recovery of eligible claims.

Latest changes: The newest commit clarifies that the age bound resets on requeue, while the attempt bound limits repeated handler crashes.

_{Reviewed the commits since f582b55 · Details · Comment @hansi-codes review to re-run, or mention @hansi-codes with a question.}

Security rules

No new WARNING or ERROR findings from security rules.

Posted by Checks / Rules. Re-runs update this comment in place. Rule details and baseline: .semgrep/README.md.

✨ Benchmark results

Comparing main (before) → fix/queue-reap-limits (after).

@tenki-reviewer

Review complete. 🟡 2 medium

// packages/queue/src/Broker/Redis.php
278	            $expired = $this->script($this->commands, 'expired', [$registry], [self::REAP_LIMIT]);
279	            if ($expired !== []) {
280	                $this->script($this->commands, 'recover', [$registry, "{$queue->namespace}.queue.{$queue->name}", ...$expired], [self::REAP_LIMIT]);
281	            }

// packages/queue/src/Broker/Redis.php
515	    private function retryPayload(Queue $queue, Message $job): string
516	    {
517	        $payload = [
518	            'pid' => uniqid(more_entropy: true),
519	            'queue' => $queue->name,
520	            'timestamp' => time(),
521	            'payload' => $job->getPayload(),
522	            'attempts' => $job->getAttempts() + 1,
523	        ];
524	        return $this->codec->encode($payload);

This PR extends the utopia queue Redis broker so maintain() reaps claims that exceed a configurable attempt count or publish age and parks them on a dead queue instead of requeueing, with a new E2E test covering the maxAttempts branch.

The gates are enforced only in reap() and retry() on the claim-reclaim path, while maintain()'s expired-reservation recovery pushes stranded envelopes straight back to the ready queue without touching attempts or age, and retryPayload() resets the envelope timestamp on every requeue, so a poison message can loop forever without ever being parked.

Note: one low-severity lapsed-heartbeat dead-parking edge case was verified at confidence 75 and falls just below the reporting threshold; it concerns a live worker whose heartbeat lapsed past CLAIM_TTL having its in-flight message terminal-parked when the new bounds are configured.

_{Reviewed commit: 828cdc3}

@tenki-reviewer thanks. Addressed in f582b55:

• Requeues reset the reapMaxAge clock: correct, and it's intended. retryPayload() republishes the message, and the reapAfter staleness check relies on that fresh timestamp. newerThan already behaves this way on reap() and retry(). I've updated the constructor comment and the PR description to say the age counts from the latest publish and that reapMaxAttempts is what stops a crash loop. reapMaxAge is for a backlog that was never requeued.
• Reservation recovery skips the limits: I'm leaving this as is. receive() reserves and claims inside the same call, so a reservation only exists before receive() returns, and the message has never reached a handler. It can't be what crashes the worker, so there's nothing to count as an attempt. Envelopes that fail to decode already go to poison at claim time.
• Destructuring nit: fixed. The test now uses the same [0] ?? null plus assertInstanceOf guard as the rest of the suite.

Review complete. 🟡 1 medium

💬 Inline comments (1)

• 🟡 Reservation recovery bypasses the new dead-letter bounds — Redis.php:281

This PR extends the Redis broker crash-recovery path so messages that repeatedly fail recovery or sit unclaimed too long are parked in the dead queue instead of being replayed forever. Two new optional constructor params on Broker\Redis thread through maintain() into reap(), preserving the previous unbounded behavior when left null.

_{Reviewed commit: f582b55}