boxel: Skill for Claude Code

Rate-limit store

DBRateLimitStore keeps rate limits and budgets in the database, so a limit holds across every realm-server process and across a restart. Each statement is the same on Postgres and SQLite. The tests are in packages/realm-server/tests/rate-limit-store-test.ts.

Keys

A key is a string the caller composes. Build it with counterKey(...parts), for example counterKey(shareId, callerId). The parts are JSON-encoded, so two different lists of parts can never make the same key, whatever characters a part contains. A token bucket and a budget never share a count, even under the same key. A day budget and a month budget under one key are also counted separately.

Token buckets

take(key, { burst, refillPerMinute }, cost = 1):

• A key nothing has taken from yet is a full bucket of burst tokens. The bucket refills continuously at refillPerMinute and never holds more than burst.
• A take is all or nothing: one upsert takes cost tokens only when that many are there. Concurrent takes from any number of processes never admit more than the bucket holds.
• An admission returns { admitted: true, remaining }, where remaining is the whole tokens left. A refusal returns { admitted: false, retryAfterSeconds }, the time until cost tokens will have refilled. A refusal spends nothing, so a caller who keeps retrying gets in as soon as the tokens are back. The retry time comes from a second read and can be slightly stale.
• A cost larger than burst is never admitted. The refusal gives the time to refill a full bucket.
• The row stores the level at refilled_at, in epoch milliseconds from the store's clock. A process whose clock is behind the row gets no refill and does not move refilled_at or expires_at backwards, so a sweep never deletes a bucket that is still refilling.

Budgets

spend(key, { period, limit }, cost = 1) and budget(key, { period, limit }):

• period is day or month, as calendar periods in UTC. A budget resets at midnight UTC, or at midnight UTC on the first of the month.
• spend is all or nothing, like a take. An admission returns { admitted: true, used, resetsAt }, with resetsAt in epoch seconds. A refusal returns { admitted: false, retryAfterSeconds }, the time until the period turns.
• budget returns the same answer without spending anything. Use it to ask before doing the work and to show what is left.