Description:

I have a proposition to perform a graceful shutdown of the messenger:consume command with Supervisor, especially useful when the Symfony application is in a Docker container.

Given a Docker image which entrypoint uses supervisord, stopping it sends a SIGTERM signal to Supervisor which sends a SIGTERM signal to the programs (the messenger:consume commands), stopping the processes immediately. The issue I see here is that it could stop a message from being processed completely by its handler, thus loosing a message per worker process.

Goal: make the messenger:consume command finish processing its current message before exiting.

Failing workarounds:

Using a bind mount for the source code and calling messenger:stop-workers implies we can't update the Docker image itself.
Calling messenger:stop-workers before shutting down the container does not work because the command returns as soon as the "signal" to stop the workers is sent, therefore Docker/Supervisor will kill the processes even if a message is currently being processed.
Editing the supervisor.conf file on the fly (e.g. using sed) to set autorestart=false and then calling supervisorctl to reread and update does not work as supervisorctl update kills and restarts the processes immediately.
And I tried a lot more of failing workarounds I just forgot about.

Example of a working solution:

Symfony 5.2 introduced the SignalableCommandInterface to allow commands to react to signals.
I created a clone of the ConsumeMessagesCommand implementing this feature:

<?php

declare(strict_types=1);

namespace App\Messenger;

use Symfony\Component\Console\Command\SignalableCommandInterface;
use Symfony\Component\Console\Input\ArrayInput;
use Symfony\Component\Console\Output\NullOutput;
use Symfony\Component\Messenger\Command\ConsumeMessagesCommand;

final class ConsumerCommand extends ConsumeMessagesCommand implements SignalableCommandInterface
{
    protected static $defaultName = 'app:messenger:consume';

    /**
     * The command will react to a SIGUSR1 signal
     */
    public function getSubscribedSignals(): array
    {
        return [
            SIGUSR1
        ];
    }

    /**
     *  When the SIGUSR1 signal is received, the `messenger:stop-workers` command is run
     */
    public function handleSignal(int $signal): void
    {
        $command = $this->getApplication()->find('messenger:stop-workers');
        $command->run(new ArrayInput([]), new NullOutput());
    }
}

This service has been based on the original command as such:

services:
    App\Messenger\ConsumerCommand:
        parent: 'console.command.messenger_consume_messages'

Only this is needed in Symfony's codebase to make it work. I tested with a message handler which loops from 0 to 30 and prints a number per second (I'm not pasting it here to avoid making this issue longer): when calling docker-compose down in the middle of a handler's execution it waits for it to finish before exiting.

Then comes the (shortened) Supervisor configuration to make use of it using the stopsignal (which signal to send to the program) and stopwaitsecs (how long is the timeout before a SIGKILL is sent):

[program:messenger-my_kafka_consumer]
command=php /var/www/html/bin/console app:messenger:consume my_transport -vvv
stopsignal=USR1
stopwaitsecs=20

About Docker, if the shutdown is specified in a CLI command, there is a -t option for both docker stop and docker-compose down commands to define a timeout between the SIGTERM and SIGKILL sent to Supervisor.
If using a docker-compose.yml file, the stop_grace_period key can be used instead.

The users would just have to set the grace period themselves depending on their message handlers, Symfony wouldn't be responsible for it. If the users don't want a graceful shutdown they just don't set a grace period nor specific signal.

Questions:

I think the messenger:consume command could implement SignalableCommandInterface, and that the Docker/Supervisor configuration suggestion could be added to the documentation.

Is this feature acceptable ?
I used SIGUSR1 but would SIGTERM be acceptable ? I can't think about any cases where someone would like to get the message processing being stop in the middle, but I may be wrong.

I'd love to make the PR myself for this, should I target a specific branch as the interface was released in 5.2 and Messenger currently requires the Console component in "^4.4|^5.0" versions ? Do you have any hints for me to write a decent test for signal handling of the command ?

Thanks for reading this long issue :-)