Feature: #110230 - Retry and park failed Messenger messages
See forge#110230
Description
A message consumed asynchronously by a Symfony Messenger worker
(
typo3 messenger:) was lost when its handler failed.
TYPO3 now provides an opt-in failure transport together with a per-transport
retry strategy, and the console commands to inspect, retry and remove the
parked messages.
The failure handling applies only to asynchronous processing by a worker. It
reacts to the
\Symfony\
of the worker, using the listeners of Symfony Messenger. A synchronous dispatch,
including the
Sync, is never affected.
Enabling the failure transport
The failure transport is disabled by default. Name the transport failed messages should be parked in:
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['failure_transport'] = 'failed';
TYPO3 ships a
failed
transport that stores the messages in the table
sys_ with the queue name
failed
, so no additional
database table is required.
A failure transport is not consumed by
messenger:, so a worker
started without a transport name still consumes the
doctrine
transport
only. Parked messages are handled with the
messenger: commands.
Per-transport failure transport
By default every transport shares the global failure transport. A transport can
use its own failure transport, or opt out of failure handling, with the option
failure_ keyed by the transport name:
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['failure_transport'] = 'failed';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['transports'] = [
// failures of the "email" transport go to a dedicated failure transport
'email' => ['failure_transport' => 'failed_email'],
// the "reporting" transport opts out of failure handling
'reporting' => ['failure_transport' => ''],
];
A transport without the option uses the global failure transport. An empty value disables the failure transport for that transport.
A failure transport must be registered as a messenger sender and tagged
messenger., so that the
messenger:
commands can operate on it:
services:
MyVendor\MyExtension\Messenger\FailedEmailTransport:
class: Symfony\Component\Messenger\Bridge\Doctrine\Transport\DoctrineTransport
factory: [ '@TYPO3\CMS\Core\Messenger\DoctrineTransportFactory', 'createTransport' ]
arguments:
$options:
queue_name: 'failed_email'
tags:
- { name: 'messenger.sender', identifier: 'failed_email' }
- { name: 'messenger.failure_transport', identifier: 'failed_email' }
To decide the failure transport of a transport at runtime, listen to the new
PSR-14 event
\TYPO3\.
It carries the name of the transport the message failed on and the failure
transport resolved from the configuration. Setting
null
disables the
failure transport for that transport:
use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Core\Messenger\Event\ResolveFailureTransportEvent;
final class RouteImportFailures
{
#[AsEventListener]
public function __invoke(ResolveFailureTransportEvent $event): void
{
if ($event->getReceiverName() === 'import') {
$event->setFailureTransportName('failed_import');
}
}
}
Retrying before parking
A transport can retry a failed message a number of times before it is sent to the failure transport. Configure a retry strategy per transport, keyed by the transport name:
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['transports']['doctrine']['retry_strategy'] = [
'max_retries' => 3,
'delay' => 1000, // milliseconds before the first retry
'multiplier' => 2, // the delay is multiplied by this for each retry
'max_delay' => 0, // maximum delay in milliseconds, 0 = no limit
];
Unlike in Symfony applications, a transport without a
retry_ is
not retried, so existing transports keep their behaviour. A failed message is
sent straight to the failure transport, if one is configured.
Console commands
Three commands operate on the failure transport:
messenger:lists the parked messages, or shows a single message when given its id.failed: show messenger:handles one or more messages again, by id or all pending messages withfailed: retry --, as received from the transport they failed on. Handlers that succeeded before are skipped. A message that succeeds is removed from the failure transport. A message that fails again is parked again with the new error, and the command exits with a failure code.force messenger:deletes the given messages from the failure transport.failed: remove
None of the commands are offered as scheduler tasks.
Impact
Asynchronous message processing no longer loses a message whose handler fails: the message is retried according to the retry strategy of its transport and, if it still fails, parked in the failure transport, where it can be inspected, retried or removed on the command line.