Pomenované profily limitov

Opakovane použiteľné limity definujete raz v config/http-client-rate-limits.php a odkazujete na ne menom odkiaľkoľvek:

// config/http-client-rate-limits.php
'limiters' => [
    'github' => ['rate' => 5, 'per' => 'second'],
    'billing' => ['rate' => 100, 'per' => 'minute', 'by' => 'tenant-1', 'jitter' => 50],
],

use RoundlyConsulting\HttpClientRateLimits\Facades\RateLimits;

Http::rateLimit('github')->get('https://api.github.com/user');

// Re-key a profile per owner at the call site:
Http::rateLimit('github', by: 'acct-1')->get('https://api.github.com/user');

// The same profile outside the HTTP client:
$limit = RateLimits::profile('github');
$limit->remaining();

Odkaz na nedefinované meno vyhodí UnknownLimiterProfileException.

Kľúče profilu

Každý profil prijíma rate a per a voliteľné kľúče by, trim, max_wait, jitter a adaptive. Nenastavený kľúč — vynechaný, null alebo prázdny ('', len medzery) — má túto predvolenú hodnotu:

Profil so všetkými kľúčmi:

'limiters' => [
    'openai' => [
        'rate' => 60,          // requests allowed in the window
        'per' => 'minute',     // second | minute | hour | day
        'by' => 'openai',      // owner key
        'trim' => true,        // drop hits older than the window after each request
        'max_wait' => 10_000,  // ms: throw RateLimitExceededException above this wait
        'jitter' => 100,       // ms: up to this much random extra wait
        'adaptive' => true,    // honour Retry-After / X-RateLimit-* response headers
    ],
],

Prísne hodnoty

Každá hodnota profilu sa pri jeho načítaní číta prísne, nikdy sa neháda:

• rate, max_wait a jitter prijmú celé číslo alebo celočíselný reťazec ('5'); 'five', '5.5' či '1e3' vyhodí InvalidConfigurationException, rovnako ako záporné max_wait alebo jitter. rate pod 1 vyhodí InvalidLimitException.
• per prijme second, minute, hour alebo day (presne) alebo Timespan; preklep ako minutes či nepodporované week vyhodí InvalidTimespanException.
• by prijme reťazec; hodnota, ktorá nie je reťazec, vyhodí InvalidConfigurationException.
• trim a adaptive prijmú true/false, 1/0, on/off alebo yes/no; čokoľvek iné vyhodí InvalidConfigurationException.

Každá chyba uvádza celý kľúč, napríklad http-client-rate-limits.limiters.github.adaptive. Nenastavený kľúč použije predvolenú hodnotu z tabuľky vyššie — prázdne max_wait teda znamená žiadny strop, nikdy nie okamžité zlyhanie s limitom 0 ms.