Retries e Backoff

O sistema de Queue do MUCRM possui suporte nativo para tentativas automáticas, retry inteligente, backoff progressivo e controle de falhas.

Isso evita perda de execução em casos temporários como:

Banco offline
API indisponível
Timeout
Falha de rede
Serviços externos instáveis

Como Funciona

Quando um Job lança uma exceção, o Worker automaticamente:

Incrementa as tentativas
Aguarda o tempo definido no backoff
Tenta novamente
Move para Failed Jobs caso exceda o limite

Tentativas (tries)

Você pode definir quantas vezes um Job pode tentar executar:

<?php

namespace MUCRM\shared\jobs;

use MUCRM\engine\queue\job;

class send_discord_webhook extends job
{
    public int $tries = 5;

    public function handle(): void
    {
        throw new \Exception('Discord offline');
    }
}

Nesse exemplo: 5 tentativas máximas.

Backoff

O backoff define quanto tempo o Worker aguarda antes de tentar novamente:

<?php

namespace MUCRM\shared\jobs;

use MUCRM\engine\queue\job;

class send_discord_webhook extends job
{
    public int $tries = 3;

    public array $backoff = [
        10,
        30,
        120
    ];

    public function handle(): void
    {
        throw new \Exception('API offline');
    }
}

1ª falha → retry em 10 segundos
2ª falha → retry em 30 segundos
3ª falha → retry em 120 segundos

Após exceder as tentativas: Job movido para Failed Jobs.

Valores Padrões

Todos os Jobs já possuem configuração padrão:

public int $tries = 3;

public array $backoff = [
    10,
    30,
    120
];

Você só precisa alterar quando necessário.

Exemplo Real

<?php

namespace MUCRM\shared\jobs;

use MUCRM\engine\queue\job;
use MUCRM\engine\support\log;

class SendRecoveryEmail extends Job
{
    public int $tries = 5;

    public array $backoff = [
        5,
        10,
        30,
        60,
        120
    ];

    public function handle(): void
    {
        mailer::send(
            'email@gmail.com',
            new RecoveryMail()
        );
    }

    public function failed(\Throwable $e): void
    {
        log::error(
            'Falha ao enviar email: ' .
            $e->getMessage()
        );
    }
}

Fluxo de Retry

job executa
    ↓
falhou?
 ├── NÃO → sucesso
 └── SIM
        ↓
 incrementa tentativa
        ↓
 aplica backoff
        ↓
 tenta novamente
        ↓
 excedeu tries?
 ├── NÃO → retry
 └── SIM → failed jobs

Quando Utilizar Retry

Ideal para:

Envio de emails
APIs externas
Webhooks
Integração Discord
Integração Telegram
Pagamentos
Consultas HTTP
Sincronizações

Quando NÃO Utilizar Retry

⚠️Evite retries para

Erros de lógica, validações inválidas, dados corrompidos, exceptions permanentes, falhas impossíveis de recuperar.

Boas Práticas

Utilize retries pequenos
Utilize backoff progressivo
Nunca use loops infinitos
Registre falhas importantes
Utilize o método failed()
Monitore failed jobs
Evite tempo excessivo entre retries

Exemplo de Retry Inteligente

<?php

namespace MUCRM\shared\jobs;

use MUCRM\engine\queue\job;

class SendWebhook extends Job
{
    public int $tries = 4;

    public array $backoff = [
        5,
        15,
        60,
        300
    ];

    public function handle(): void
    {
        Http::post('https://api.site.com');
    }
}

1ª tentativa → instantânea
2ª tentativa → 5 segundos
3ª tentativa → 15 segundos
4ª tentativa → 60 segundos
última tentativa → 300 segundos