tadpole/rest/rate_limit

Per-bucket rate-limit state for REST: the numbers responses have reported and the waits they imply. Values come from response headers and 429 bodies only — no hardcoded table, because Discord changes buckets without notice and the headers are the only truth available.

Pure: no processes, no clock. Time enters as integer arguments; the caller owns the clock and the route -> bucket map (associate). Stability: Growing.

tadpole/rest/execute owns the bookkeeping; this module owns the arithmetic. Nothing here sleeps, sends, or remembers.

When you reach for this

Directly, almost never — unless you are writing your own executor or a test that wants exact wait math. BucketState is a public record on purpose, same status as RestRequest: plain data, nothing here is an invariant worth guarding.

wait_ms: what now_ms means

wait_ms(state, now_ms) answers “how long should the next request on this bucket hold off?”. The parameter name misleads everyone once: now_ms is NOT a clock reading. It is the time elapsed since the response that last updated this state — 0 immediately after update, and whatever the caller’s clock says after that. Tadpole never reads a clock; the caller stamps each response and subtracts.

Priority order: a 429’s retry window first (retry_after_ms minus elapsed), then a known-empty bucket (remaining == 0) counting down reset_after_ms, else 0. That final 0 is deliberate: with no headers observed, fire and accept the risk of another 429 — inventing a wait would stall buckets Discord never limited.

Route masking

route_key masks every all-digit path segment of 15+ characters to :id, producing “GET /channels/:id/messages”. That is a grouping key, not Discord’s bucket identity: it folds every channel id into one key, so pre-bucket state mixes traffic across major parameters — a wait learned on channel A gates channel B too. Discord’s real per-id bucketing is visible only in the X-RateLimit-Bucket header, which is what associate binds.

associate: re-keying

Until a response names a bucket, state lives under the masked route key. associate binds route key -> bucket id once X-RateLimit-Bucket appears; from that response on, the bucket id is the state key and lookups should prefer it. A later response naming a different bucket simply overwrites the binding — Discord reshuffles buckets sometimes. No bucket header, no change.

Failure modes

Cannot fail: no I/O, and nothing parses but what the caller already parsed. Degenerate inputs degrade instead — update with no parsed headers leaves the state untouched; a half-headered response downgrades the fields it omits to None (the response is the whole truth). Only a 429 sets the retry window; a Retry-After on any other status is ignored.

See also

• tadpole/rest/execute — the caller that juggles this state
• tadpole/rest — the header parsing that feeds update

pub type BucketState {
  BucketState(
    limit: option.Option(Int),
    remaining: option.Option(Int),
    reset_after_ms: option.Option(Float),
    retry_after_ms: option.Option(Int),
    bucket: option.Option(error.BucketId),
  )
}

pub fn associate(
  routes: dict.Dict(String, error.BucketId),
  key: String,
  response: rest.RestResponse,
) -> dict.Dict(String, error.BucketId)

pub fn new() -> BucketState

pub fn route_key(method: String, path: String) -> String

rate_limit.route_key("GET", "/channels/862474250334586890/messages")
// -> "GET /channels/:id/messages"

pub fn update(
  state: BucketState,
  response: rest.RestResponse,
) -> BucketState

pub fn wait_ms(state: BucketState, now_ms: Int) -> Int