Limitação de taxa

Queuety oferece limitação de taxa por handler para evitar sobrecarregar APIs externas ou outros recursos restritos. Quando um handler atinge seu limite, os workers deixam seus jobs pendentes e os retomam quando a janela permite.

Definindo um limite de taxa

Aplique um limite de taxa ao despachar um job:

use Queuety\Queuety;

Queuety::dispatch( 'call_openai', $payload )
    ->rate_limit( 10, 60 ); // max 10 executions per 60 seconds

Os dois argumentos são:

1. $max - Número máximo de execuções permitidas na janela
2. $window - Duração da janela em segundos

Um limite definido no momento do despacho é registrado somente no processo PHP que despacha o job. Um worker executado em um processo separado, como wp queuety work, não o vê; portanto, defina os limites que precisam valer entre processos na config() do handler, como mostrado abaixo (#3).

Limites de taxa no nível do handler

Defina limites de taxa no método config() do handler para que se apliquem a cada despacho:

use Queuety\Handler;

class CallOpenAIHandler implements Handler {
    public function handle( array $payload ): void {
        // Call the API...
    }

    public function config(): array {
        return [
            'rate_limit' => [ 60, 60 ], // 60 requests per minute
        ];
    }
}

Como funciona

Os limites de taxa são rastreados por nome de handler. Após reivindicar um job, o worker registra o limite do handler (de seu config()) e verifica o limitador de taxa. Se o handler atingiu seu limite, o worker devolve o job imediatamente a pending, sem atraso e sem consumir uma tentativa; em seguida, aguarda QUEUETY_WORKER_SLEEP segundos antes de consultar novamente. Um worker iniciado com --once é encerrado.

Cada worker mantém um contador em memória e o atualiza a cada 5 segundos a partir da tabela queuety_logs, contando as entradas de log completed do handler nos últimos $window segundos. Como a contagem vem da tabela de logs compartilhada (e do cache compartilhado, quando configurado), os limites no nível do handler são aplicados em todos os processos de worker, e não apenas em um único worker. Execuções com falha não contam para o limite.

Acesso programático

Acesse diretamente o limitador de taxa:

$limiter = Queuety::rate_limiter();

// Register a rate limit
$limiter->register( 'call_openai', 60, 60 );

// Check whether a handler has reached its limit
$limited = $limiter->is_limited( 'call_openai' ); // true while the limit is reached

// Seconds until the current window resets
$wait = $limiter->time_until_available( 'call_openai' );

register() e is_limited() atuam no limitador do processo PHP atual. Registrar um limite aqui não altera o que um worker executado separadamente aplica.

Casos de uso

• Limites de API externos. Ajuste seu limite de taxa à cota do API (e.g, por exemplo, os 60 RPM de OpenAI).
• Limitação de envios de e-mail. Evite enviar e-mails demais em um curto intervalo.
• Proteção de recursos. Limite handlers que exigem muito da CPU para evitar que prejudiquem outros jobs.