Usage quotas¶
A quota, such as ten thousand verifications a month on a plan, counts the meter that billing uses. It counts quickly into a cache and is corrected slowly from the index. The records stay the source of truth.
Quotas are designed, not built. extensions.quotas.enabled renders nothing, and no usage consumer or reconciler ships.
A quota is not burst rate limiting. A limit of fifty requests a second is decided before the request is served, from an authoritative counter, in the gateway's rate-limit service. A quota is a monthly total that tolerates seconds of lag and agrees with the invoice.
Quotas need stream mode. Without a stream a second consumer has nothing to read.
The five slots¶
| # | slot | what it does | whose |
|---|---|---|---|
| 1 | catalogue | the same meter: as billing |
the application's |
| 2 | usage consumer | a second durable consumer: dedupes by record id and increments tenant:meter:period, success outcomes only |
planned here, run by the application |
| 3 | decision | the gateway's external authorisation or application middleware reads one key and joins the tenant's plan | the application's |
| 4 | reconciler | an hourly CronJob copies exact rollups from the index into the cache | planned here, run by the application |
| 5 | denial | a refusal is an async action in the catalogue |
the application's |
flowchart TB
N[("JetStream")] --> U["usage consumer"]
U --> VK[("counter cache")]
PLAN[("plan table")] --> GW["decision point"]
GW --> VK
REC["reconciler, hourly"] --> PG[("index rollups")]
REC --> VK
GW -- "refusal is a record" --> R["receiver"]Fail open¶
A cold cache has no counter, which reads as zero use. The decision point serves the request and records that it decided without a count. The next hourly reconciliation restores the exact number.
Quotas are a commercial control, not a security one.
What to watch¶
| signal | meaning |
|---|---|
| usage consumer lag | quotas are decided on stale counts; it is separate from the writer's lag |
| reconciler drift | a growing drift means the consumer misses records |
| denials | a sudden rise is an attack or a misconfigured plan |
To enable quotas, see enable usage quotas.