RateLimiter
in package
Table of Contents
Constants
- GLOBAL_CLIENT_ID : mixed = '__global_host__'
- Pseudo client id used to key the host-wide, self-tracked request counter in the store (see {@see checkGlobalBeforeRequest()}). Never collides with a real client id, which is always a certificate SHA1 fingerprint.
Properties
- $globalRateLimitPerSecond : int
- $lockDir : string
- $maxWaitSeconds : int
- $store : RateLimitStoreInterface
- $waitMode : bool
Methods
- __construct() : mixed
- Create a RateLimiter configured with a storage backend and a handling mode for exceeded limits.
- acquireLock() : resource
- Acquire an exclusive, cross-process lock for the given client so that concurrent processes sharing the same client (e.g. the same certificate) serialize their check-send-update cycle instead of racing past each other's stale counters.
- checkBeforeRequest() : void
- Ensures the client is allowed to make the next request by enforcing per-second and per-day rate limits.
- checkGlobalBeforeRequest() : void
- Enforces a host-wide, self-tracked cap on requests per second across every certificate/client sharing this store.
- handleRateLimits() : void
- Stores remaining rate-limit counts for a client for both the one-second and 24-hour windows.
- isWaitMode() : bool
- Indicates whether the limiter is configured to wait when a rate limit is exceeded.
- releaseLock() : void
- Release a lock previously acquired with {@see acquireLock()}.
Constants
GLOBAL_CLIENT_ID
Pseudo client id used to key the host-wide, self-tracked request counter in the store (see {@see checkGlobalBeforeRequest()}). Never collides with a real client id, which is always a certificate SHA1 fingerprint.
public
mixed
GLOBAL_CLIENT_ID
= '__global_host__'
Properties
$globalRateLimitPerSecond
private
int
$globalRateLimitPerSecond
$lockDir
private
string
$lockDir
$maxWaitSeconds
private
int
$maxWaitSeconds
$store
private
RateLimitStoreInterface
$store
$waitMode
private
bool
$waitMode
Methods
__construct()
Create a RateLimiter configured with a storage backend and a handling mode for exceeded limits.
public
__construct(RateLimitStoreInterface $store[, bool $waitMode = true ][, string $lockDir = null ][, int $globalRateLimitPerSecond = 0 ][, int $maxWaitSeconds = 300 ]) : mixed
Parameters
- $store : RateLimitStoreInterface
-
storage backend for per-client rate-limit state
- $waitMode : bool = true
-
if true, the limiter will wait until the limit window resets; if false, it will throw a RateLimitExceededException when limits are exceeded
- $lockDir : string = null
-
directory used to store per-client lock files that serialize concurrent requests (defaults to the system temp directory)
- $globalRateLimitPerSecond : int = 0
-
host-wide cap on requests per second across ALL certificates/clients sharing this store, enforced by checkGlobalBeforeRequest(); 0 disables it (default, no behavior change)
- $maxWaitSeconds : int = 300
-
in wait mode, the longest this limiter will ever sleep for; a required wait beyond this (e.g. most of a day-window reset) throws RateLimitExceededException instead of blocking the caller
acquireLock()
Acquire an exclusive, cross-process lock for the given client so that concurrent processes sharing the same client (e.g. the same certificate) serialize their check-send-update cycle instead of racing past each other's stale counters.
public
acquireLock(string $clientId) : resource
The lock is released with releaseLock(); it is also released automatically by the OS if the process dies while holding it.
Parameters
- $clientId : string
-
identifier of the client to lock (used to derive the lock file name)
Return values
resource —the open, locked file handle to pass to releaseLock()
checkBeforeRequest()
Ensures the client is allowed to make the next request by enforcing per-second and per-day rate limits.
public
checkBeforeRequest(string $clientId) : void
If a window is exhausted and wait mode is enabled, pauses execution for the required seconds to clear the window; otherwise throws a RateLimitExceededException.
Parameters
- $clientId : string
-
identifier of the client whose rate limits are checked
Tags
checkGlobalBeforeRequest()
Enforces a host-wide, self-tracked cap on requests per second across every certificate/client sharing this store.
public
checkGlobalBeforeRequest() : void
Unlike checkBeforeRequest(), this does NOT rely on RB's response headers: those only ever report the remaining quota for the certificate that made the request, so a gateway-level limit shared by many certificates (e.g. per source IP or per account-holder) never shows up as an exhausted window on any single certificate — each one still has plenty of headroom while the shared limit is being blown through. This method instead counts requests this library itself has sent, in a fixed one-second bucket, and self-throttles against a configured cap.
The caller MUST serialize calls to this method across processes (see acquireLock() with GLOBAL_CLIENT_ID), since the read-increment-write cycle here is not atomic on its own.
A no-op when the cap is 0 (default): the true scope and size of RB's gateway-level limit is not documented, so this is opt-in until it has been confirmed and a sane value configured.
Tags
handleRateLimits()
Stores remaining rate-limit counts for a client for both the one-second and 24-hour windows.
public
handleRateLimits(string $clientId, int $remainingSecond, int $remainingDay, int $timestamp) : void
Parameters
- $clientId : string
-
Fingerprint identifying the client (e.g., certificate SHA1, serial+issuer).
- $remainingSecond : int
-
remaining requests in the current one-second window
- $remainingDay : int
-
remaining requests in the current 24-hour window
- $timestamp : int
-
UNIX timestamp (seconds) when the limits were observed
isWaitMode()
Indicates whether the limiter is configured to wait when a rate limit is exceeded.
public
isWaitMode() : bool
Return values
bool —true if the limiter waits until the rate-limit window expires, false otherwise
releaseLock()
Release a lock previously acquired with {@see acquireLock()}.
public
releaseLock(resource $handle) : void
Parameters
- $handle : resource
-
the file handle returned by acquireLock()