RateLimiter
in package
A token bucket: how the bot stays under somebody else's send limit.
Every network the bot speaks on publishes one, and the penalty for breaching it is rarely just a dropped message — Twitch mutes the account for thirty minutes, Discord counts rejections toward a ban on the whole host. A busy Discord channel will happily exceed any of them, so each sender paces itself rather than finding out.
A bucket rather than a fixed delay: ordinary chat goes out immediately and only a genuine burst is slowed. The clock is injected so the behaviour can be tested without sleeping.
The defaults are a conservative chat-sized bucket and not a claim about any particular network. A caller that knows its own limit should say so — OutboundPacer passes Discord's, and a connector passes whatever its own network publishes, with the margin it wants.
Tags
Table of Contents
Properties
- $capacity : int
- $clock : callable(): float
- $per : float
- $tokens : float
- $updatedAt : float
Methods
- __construct() : mixed
- available() : float
- Tokens currently available, for logging and tests.
- retryAfter() : float
- Seconds until the next token is available; `0.0` when one is ready now.
- tryConsume() : bool
- Takes one token if any is available.
- refill() : void
Properties
$capacity read-only
private
int
$capacity
= 18
$clock
private
callable(): float
$clock
$per read-only
private
float
$per
= 30.0
$tokens
private
float
$tokens
$updatedAt
private
float
$updatedAt
Methods
__construct()
public
__construct([int $capacity = 18 ][, float $per = 30.0 ][, callable(): float|null $clock = null ]) : mixed
Parameters
- $capacity : int = 18
-
How many messages may burst.
- $per : float = 30.0
-
Over how many seconds the bucket refills.
- $clock : callable(): float|null = null
-
Defaults to
microtime(true).
available()
Tokens currently available, for logging and tests.
public
available() : float
Return values
floatretryAfter()
Seconds until the next token is available; `0.0` when one is ready now.
public
retryAfter() : float
Return values
floattryConsume()
Takes one token if any is available.
public
tryConsume() : bool
A caller is expected to size the bucket under the published limit: the bot is rarely the only thing speaking as its account, and being silenced for half an hour is a far worse failure than a message arriving a second late.
Return values
boolrefill()
private
refill() : void