Download the PHP package hikuroshi/rate-budget without Composer

hikuroshi/rate-budget

A multi-key quota decision engine for RPM, TPM, and RPD-aware routing.

hikuroshi/rate-budget selects an active key within a scope such as a tenant, workspace, project, user, or guild. Each key has independent RPM, TPM, and RPD limits, so your application can safely move to another key when one key is cooling down, under token pressure, or near its daily quota.

The package is lightweight, dependency-free, and storage adapter friendly. Your application owns the state; hikuroshi/rate-budget only computes quota decisions and records reservations through the configured adapter.

Install

Core Algorithm

RPM: spacing-based cooldown.

TPM: sliding 60-second token window.

RPD: daily threshold guard.

Quick Start

Use a single key when you do not need key rotation yet.

Use multiple keys with priority when you want automatic key rotation.

API

new Quota($options = [])

Constructor options:

• store: custom storage adapter. Defaults to MemoryStore.
• estimate($req): token estimator. Defaults to $req['tokens'], numeric request, object tokens, or 1.
• now(): custom clock returning Unix milliseconds.
• id(): reservation id generator.
• windowMs: token window. Defaults to 60000.
• bufferMs: RPM/TPM safety buffer. Defaults to 1000.
• thresholdPct: RPD threshold percent. Defaults to 100.
• dayKey($now): daily bucket key. Defaults to UTC YYYY-MM-DD.
• resetAt($now): timestamp for the next daily reset. Defaults to next UTC day.

reserve($scope, $keyOrKeys, $req = null)

Selects the best key and immediately creates a reservation for RPM, TPM, and RPD accounting. $keyOrKeys can be a single key array/object or a list of keys.

Successful result:

Blocked result:

waitMs is null when the request cannot be handled by any key, for example when the estimated token count is larger than every key's TPM limit.

commit($hold, $usage = [])

Completes a reservation after the request has actually consumed provider quota.

rollback($hold)

Cancels a reservation when a request was not sent or failed before provider quota was consumed.

check($scope, $keyOrKeys, $req = null)

Runs a dry check to see which key would be selected without creating a reservation.

check() still touches storage to normalize scope/key state and prune old token hits, but it does not create a hold or consume quota.

Key Shape

Fields:

• id: stable key id.
• rpm: requests per minute.
• tpm: tokens per minute.
• rpd: requests per day.
• priority: higher value is preferred. Defaults to 0.
• enabled: set false to skip a key. Defaults to true.

Extra fields are preserved on the selected key, so you can attach provider names, encrypted key references, model names, or metadata.

Selection Rules

1. Disabled keys are skipped.
2. A key must pass RPD threshold, RPM cooldown, and TPM window checks.
3. Among allowed keys, the highest priority wins.
4. Ties prefer lower token pressure, then lower daily pressure, then key id.
5. If no key is allowed, the result returns the shortest useful waitMs.

Storage Adapter

MemoryStore is useful for one process. For multi-instance systems, implement QuotaStore with Redis, SQL, DynamoDB, Laravel cache with locks, or any transactional storage.

The mutate callback must run atomically per scope. That keeps reservations safe when many workers route requests at the same time.

Helpers

Exports:

• WINDOW_MS, BUFFER_MS, and THRESHOLD_PCT constants.
• cooldownMs()
• dailyCap()
• tokenWaitMs()
• Defaults: class wrapper for default constants.
• Limit::cooldownMs()
• Limit::dailyCap()
• Limit::tokenWaitMs()
• Quota
• QuotaManager: alias for Quota.
• MemoryStore
• QuotaStore
• QuotaResult
• KeyCheck
• Hold

Build and Test