# Hız Sınırlama

Queuety, harici API'lerin veya diğer kısıtlı kaynakların aşırı yüklenmesini önlemek için işleyici başına hız sınırlamasını destekler. Bir işleyici sınıra ulaştığında işçiler, o işleyicinin işlerini beklemede bırakır ve pencere yeniden yer açtığında alır.

## Hız sınırı ayarlama

Bir işi dağıtırken hız sınırı uygulayın:

```php
use Queuety\Queuety;

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

İki bağımsız değişken şunlardır:
1. `$max` - Pencerede izin verilen en yüksek yürütme sayısı
2. `$window` - Pencere süresi, saniye cinsinden

Dağıtım sırasında belirlenen sınır yalnızca işi dağıtan PHP sürecine kaydedilir. `wp queuety work` gibi ayrı bir süreçte çalışan işçi bu sınırı görmez. Bu nedenle süreçler arasında geçerli olması gereken sınırları aşağıda gösterildiği gibi işleyicinin `config()` yönteminde belirleyin ([#3](https://github.com/inline0/queuety/issues/3)).

## İşleyici düzeyinde hız sınırları

Her dağıtıma uygulanmaları için hız sınırlarını işleyicinin `config()` yönteminde belirleyin:

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

## Nasıl çalışır

Hız sınırları işleyici adına göre izlenir. Bir işi aldıktan sonra işçi, işleyicinin sınırını (`config()` içinden) kaydeder ve hız sınırlayıcıyı kontrol eder. İşleyici sınıra ulaşmışsa işçi, işi gecikme olmadan ve deneme hakkı harcamadan doğrudan `pending` kuyruğuna geri koyar; ardından yeniden yoklamadan önce `QUEUETY_WORKER_SLEEP` saniye bekler. `--once` ile başlatılan işçi ise çıkar.

Her işçi bellekte bir sayaç tutar ve bunu her 5 saniyede bir `queuety_logs` tablosundan yeniler; son `$window` saniyede ilgili işleyici için kaydedilen `completed` günlük girdilerini sayar. Sayım, paylaşılan günlük tablosundan (ve yapılandırılmışsa paylaşılan önbellekten) alındığı için işleyici düzeyindeki sınırlar tek bir işçide değil, tüm işçi süreçlerinde uygulanır. Başarısız yürütmeler sınıra dahil edilmez.

## Programatik erişim

Hız sınırlayıcıya doğrudan erişin:

```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()` ve `is_limited()` geçerli PHP sürecindeki sınırlayıcı üzerinde çalışır. Burada bir sınır kaydetmek, ayrı çalışan bir işçinin uyguladığı sınırı değiştirmez.

## Kullanım alanları

- **Harici API sınırları.** Hız sınırınızı API kotasına göre ayarlayın (e.g., OpenAI için dakikada 60 istek).
- **E-posta hız sınırlaması.** Kısa bir aralıkta çok fazla e-posta gönderilmesini önleyin.
- **Kaynak koruması.** Diğer işlerin kaynaklardan yoksun kalmasını önlemek için yoğun CPU kullanan işleyicileri sınırlayın.