throttle
Rate limits as an effect, per instance or shared by every instance
through PostgreSQL (ADR 0081). It builds on resilience/rate_limit's
token buckets. Promoted from the identical copies in starfleet and the
newsletter.
import throttle
import throttle/named
import throttle/shared
// The app's schema makes the table (the store names it).
let store = shared.rates () // `rates (key, units, at_ms)`
let _ = pg.execute (shared.create_table store) []
// One throttle per thing limited, each with its rate a minute.
let throttles =
[ ("login", throttle.shared 10 pool store)
, ("api", throttle.shared 120 pool store)
]
// Around the request handlers:
use <- named.with_named throttles
match named.admitted "login" client
{ Admitted -> ..., Wait(seconds) -> ... } // 429 with Retry-After
throttle: thethrottleeffect (admission key) and its handler.start per_minutekeeps its buckets in an actor of this instance;shared per_minute pool storekeeps them in the store's table, so every instance draws on one bucket per key, and falls back to its local buckets (logged once a minute) while the database fails. 0 a minute admits everything.throttle/shared: the buckets in PostgreSQL. One atomic statement takes a request's units or refuses, timed by the database's clock so instances never disagree.rates ()is the tablerateskeyed bykey;store table key_columnnames another (starfleet'sapi_rates, keyed byagent). Both names must be plain SQL names ([a-z_][a-z0-9_]*), since they are part of the statement's text.throttle/named: several throttles under one effect, each named for what it limits; a shared one keys its rows<name>:<key>, so they can share one table. A name with no throttle admits everything.
The shared buckets' tests run against PostgreSQL when LOUISE_PG_URL
names a database (native only), and skip otherwise.