# Päringupiirang

Queuety toetab töötlejapõhiseid päringupiiranguid, et vältida väliste API-de või muude piiratud ressursside ülekoormamist. Kui töötleja on piirini jõudnud, jätavad töötajad selle tööd ootele ja võtavad need uuesti ette, kui ajavahemikus ruumi tekib.

## Päringupiirangu seadistamine

Rakendage töö väljasaatmisel päringupiirang:

```php
use Queuety\Queuety;

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

Argumendid on järgmised:
1. `$max` – maksimaalne täitmiste arv ajavahemikus
2. `$window` – ajavahemiku kestus sekundites

Töö väljasaatmise ajal seadistatud piirang registreeritakse ainult protsessis PHP, mis töö välja saadab. Eraldi protsessis, näiteks `wp queuety work`-is, töötav töötaja seda ei näe; seega seadistage protsesside üleselt kehtivad piirangud töötleja `config()`-is, nagu allpool näidatud ([#3](https://github.com/inline0/queuety/issues/3)).

## Töötlejataseme päringupiirangud

Seadistage päringupiirangud töötleja meetodis `config()`, et need kehtiksid iga väljasaatmise korral:

```php
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
        ];
    }
}
```

## Kuidas see töötab

Päringupiiranguid jälgitakse töötleja nime järgi. Pärast töö võtmist registreerib töötaja töötleja piirangu (meetodist `config()`) ja kontrollib päringupiirajat. Kui töötleja on piirini jõudnud, saadab töötaja töö viivitamata tagasi olekusse `pending`, kulutamata katset, ning magab enne järgmist päringut `QUEUETY_WORKER_SLEEP` sekundit. Lipuga `--once` käivitatud töötaja lõpetab selle asemel töö.

Iga töötaja hoiab mälus loendurit ja värskendab seda iga 5 sekundi järel tabelist `queuety_logs`, loendades töötleja kirjeid `completed` viimase `$window` sekundi jooksul. Kuna loendus põhineb jagatud logitabelil (ja seadistatud jagatud vahemälul), kehtivad töötlejataseme piirangud kõigis töötajaprotsessides, mitte ainult ühes töötajas. Ebaõnnestunud täitmisi piirangu hulka ei arvestata.

## Programmiliselt kasutamine

Kasutage päringupiirajat otse:

```php
$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()` ja `is_limited()` rakenduvad praeguse PHP protsessi piirajale. Siin piirangu registreerimine ei muuda eraldi töötava töötaja jõustatavat piirangut.

## Kasutusjuhud

- **Välise API piirangud.** Seadke päringupiirang vastavusse API kvoodiga (nt e.g., OpenAI 60 RPM).
- **E-kirjade piiramine.** Vältige lühikese aja jooksul liiga paljude e-kirjade saatmist.
- **Ressursside kaitse.** Piirake protsessorimahukaid töötlejaid, et need ei jätaks teisi töid ressursita.