Description

Add an optional argument to the RecoverableMessageHandlingException that allows messenger to delay the retry for longer than the configured retry if the developer already knows that it'll take longer, but should be retried.

Useful in many scenarios, the code example uses the Retry-After header that is often accompanied by a 503. Some APIs with rate limits will also include headers when a rate limit is hit for when it can be retried.
Or simply to delay the retry of this 1 message, while all other messages should adhere to the configured retry timeouts.

Example

Before:

#[AsMessageHandler]
class ExampleMessageHandler
{
    public function __invoke(ExampleMessage $message): void
    {
        try {
            (new Client())->get('http://someapi');
        } catch (ServerException $ex) {
            $retryAfter = $this->parseResponseRetryAfter($ex->getResponse());
            $this->messageBus->dispatch(new ExampleMessage(), [new DelayStamp($retryAfter)]);
        } 
    }
}

Message is interpreted as a new message, previous retries, stamps,... are discarded.

After:

#[AsMessageHandler]
class ExampleMessageHandler
{
    public function __invoke(ExampleMessage $message): void
    {
        try {
            (new Client())->get('http://someapi');
        } catch (ServerException $ex) {
            $retryAfter = $this->parseResponseRetryAfter($ex->getResponse());
            throw new RecoverableMessageHandlingException(retryAfter: $retryAfter);
        }
    }
}

Message retains all of its previous stamps etc, but a delay stamp is added when the message can be retried again that may be larger (or smaller) than the default retry time.