Add failWhen method to ThrottlesExceptions job middleware (#56180)

* feat: add failWhen method to throttles exceptions job middleware

* test: add test for failWhen method

* test: adjust expectation

Author: michaeldzjap

src/Illuminate/Queue/Middleware/ThrottlesExceptions.php

@@ -64,6 +64,13 @@ class ThrottlesExceptions
      */
     protected array $deleteWhenCallbacks = [];
 
+    /**
+     * The callbacks that determine if the job should be failed.
+     *
+     * @var callable[]
+     */
+    protected array $failWhenCallbacks = [];
+
     /**
      * The prefix of the rate limiter key.
      *
@@ -122,6 +129,10 @@ public function handle($job, $next)
                 return $job->delete();
             }
 
+            if ($this->shouldFail($throwable)) {
+                return $job->fail($throwable);
+            }
+
             $this->limiter->hit($jobKey, $this->decaySeconds);
 
             return $job->release($this->retryAfterMinutes * 60);
@@ -156,6 +167,21 @@ public function deleteWhen(callable|string $callback)
         return $this;
     }
 
+    /**
+     * Add a callback that should determine if the job should be failed.
+     *
+     * @param  callable|string  $callback
+     * @return $this
+     */
+    public function failWhen(callable|string $callback)
+    {
+        $this->failWhenCallbacks[] = is_string($callback)
+            ? fn (Throwable $e) => $e instanceof $callback
+            : $callback;
+
+        return $this;
+    }
+
     /**
      * Run the skip / delete callbacks to determine if the job should be deleted for the given exception.
      *
@@ -173,6 +199,23 @@ protected function shouldDelete(Throwable $throwable): bool
         return false;
     }
 
+    /**
+     * Run the skip / fail callbacks to determine if the job should be failed for the given exception.
+     *
+     * @param  Throwable  $throwable
+     * @return bool
+     */
+    protected function shouldFail(Throwable $throwable): bool
+    {
+        foreach ($this->failWhenCallbacks as $callback) {
+            if (call_user_func($callback, $throwable)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Set the prefix of the rate limiter key.
      *

src/Illuminate/Queue/Middleware/ThrottlesExceptionsWithRedis.php

@@ -62,6 +62,10 @@ public function handle($job, $next)
                 return $job->delete();
             }
 
+            if ($this->shouldFail($throwable)) {
+                return $job->fail($throwable);
+            }
+
             $this->limiter->acquire();
 
             return $job->release($this->retryAfterMinutes * 60);

tests/Integration/Queue/ThrottlesExceptionsTest.php

@@ -45,6 +45,11 @@ public function testCircuitCanSkipJob()
         $this->assertJobWasDeleted(CircuitBreakerSkipJob::class);
     }
 
+    public function testCircuitCanFailJob()
+    {
+        $this->assertJobWasFailed(CircuitBreakerFailedJob::class);
+    }
+
     protected function assertJobWasReleasedImmediately($class)
     {
         $class::$handled = false;
@@ -108,6 +113,27 @@ protected function assertJobWasDeleted($class)
         $this->assertTrue($class::$handled);
     }
 
+    protected function assertJobWasFailed($class)
+    {
+        $class::$handled = false;
+        $instance = new CallQueuedHandler(new Dispatcher($this->app), $this->app);
+
+        $job = m::mock(Job::class);
+
+        $job->shouldReceive('hasFailed')->once()->andReturn(true);
+        $job->shouldReceive('fail')->once();
+        $job->shouldReceive('isDeleted')->andReturn(true);
+        $job->shouldReceive('isReleased')->once()->andReturn(false);
+        $job->shouldReceive('isDeletedOrReleased')->once()->andReturn(true);
+        $job->shouldReceive('uuid')->andReturn('simple-test-uuid');
+
+        $instance->call($job, [
+            'command' => serialize($command = new $class),
+        ]);
+
+        $this->assertTrue($class::$handled);
+    }
+
     protected function assertJobRanSuccessfully($class)
     {
         $class::$handled = false;
@@ -359,6 +385,25 @@ public function middleware()
     }
 }
 
+class CircuitBreakerFailedJob
+{
+    use InteractsWithQueue, Queueable;
+
+    public static $handled = false;
+
+    public function handle()
+    {
+        static::$handled = true;
+
+        throw new Exception;
+    }
+
+    public function middleware()
+    {
+        return [(new ThrottlesExceptions(2, 10 * 60))->failWhen(Exception::class)];
+    }
+}
+
 class CircuitBreakerSuccessfulJob
 {
     use InteractsWithQueue, Queueable;