Compare commits

...

38 Commits

Author SHA1 Message Date
diegosouzapw
449bb033d0 docs: add changelog fragment for #20787 2026-11-20 11:55:24 -03:00
diegosouzapw
69c4659799 docs(api): wrap a comment line in the usage contract 2026-11-20 11:41:53 -03:00
diegosouzapw
7386390a98 docs(api): narrow two statements about the usage view 2026-11-20 11:41:52 -03:00
diegosouzapw
c462690870 perf(api): keep fewer usage series in memory and drop expired ones on write 2026-11-20 11:41:51 -03:00
diegosouzapw
91fbc18468 docs(api): correct what the usage view states about retention, labels and prices 2026-11-20 11:41:44 -03:00
diegosouzapw
52d5965b62 perf(api): reuse a key's usage series for a minute and bound its window at now 2026-11-20 11:41:39 -03:00
diegosouzapw
d26695267f docs(api): say which providers count $0 in the usage view's billed cost 2026-11-20 11:41:34 -03:00
diegosouzapw
224cd6881e docs(api): name the usage route in the QUOTA_SELF_PANEL description 2026-11-20 11:41:33 -03:00
diegosouzapw
d6fea69530 feat(api): add GET /v1/me/usage with per-key usage series 2026-11-20 11:41:30 -03:00
diegosouzapw
6a2df0bacd feat(api): build per-key usage and cost series for self-service 2026-11-20 11:41:27 -03:00
diegosouzapw
78094c591a fix(api): validate the self-service key against its row and pin the e2e clock
The gate validated the key through the validation cache, which can keep
answering valid for up to a minute after a key's expiry. The gate has no other
expiry check, so it now reads the key row on every call.

The end-to-end test seeded consumption and read it back on the wall clock; an
hour or day boundary between the two would move a bucket and fail an exact
assertion. It now runs at a fixed mid-hour instant.
2026-11-20 11:15:17 -03:00
diegosouzapw
4b65b9a5f4 fix(api): derive the quota pool reference through the shared fingerprint helper
The opaque pool reference was an inline HMAC-SHA256 over the key id and the
pool id. Code scanning reads an identifier named after an API key as a
password and flags the digest as an insufficient password hash. The project
keeps every such keyed digest on opaqueTokenFingerprint, so the derivation
moves there. The reference becomes "qpr_" plus 32 hex characters (128 bits);
no reference has been issued yet, so nothing depends on the previous form.
2026-11-20 11:06:35 -03:00
diegosouzapw
457acfaebc docs: add changelog fragment for #20767 2026-11-20 07:44:22 -03:00
diegosouzapw
501a583ca6 docs(api): correct three statements about the quota view and pin a fresh reading
The two figures derived from other keys are what enforcement applies to the
key, not something it tells the key. Refusals before the route are examples,
not a closed list. The comment on the account lookup said null where the code
returns an empty list. The end-to-end test now also asserts the account bar is
ok, so a silent upstream refresh would fail it.
2026-11-20 07:43:21 -03:00
diegosouzapw
8f5539151f docs(api): say what the quota view shows, exactly 2026-11-20 07:26:28 -03:00
diegosouzapw
56d48d5663 fix(api): limit account bars to connections the key may use 2026-11-20 07:22:08 -03:00
diegosouzapw
dff04a8134 test(api): run the quota view end to end on real rows 2026-11-20 07:17:14 -03:00
diegosouzapw
5b4efabf48 test(api): type the injected key store in the self-service gate test 2026-11-20 06:50:38 -03:00
diegosouzapw
d0e38ce62b docs(api): tighten the self-service quota API wording and pin its headers 2026-11-20 06:45:59 -03:00
diegosouzapw
32e98b5e09 refactor(api): keep the self-service gate fixed and inject only its key store 2026-11-20 06:44:27 -03:00
diegosouzapw
348cce66b1 docs(api): describe QUOTA_SELF_PANEL by what this change delivers 2026-11-20 06:43:09 -03:00
diegosouzapw
84063acff2 feat(api): add GET /v1/me/quota/{provider} for API key holders 2026-11-20 06:30:50 -03:00
diegosouzapw
b80a5f08d4 test(api): pin unknown block state when the quota store fails to load 2026-11-20 06:17:21 -03:00
diegosouzapw
28283eda0b fix(api): warn once when the public API origin setting is not an http(s) origin 2026-11-20 06:12:58 -03:00
diegosouzapw
4df35faf05 refactor(api): share one quota-store load between the quota view builders 2026-11-20 06:12:40 -03:00
diegosouzapw
b15c7b443a feat(api): report the public API origin to key holders 2026-11-20 05:57:42 -03:00
diegosouzapw
25d2aafc56 feat(api): report schedule windows and per-model caps in the self-service quota view 2026-11-20 05:48:57 -03:00
diegosouzapw
523ef28ded test(api): give the default-lookup test its own data directory 2026-11-20 05:43:17 -03:00
diegosouzapw
a5233debd8 test(api): run the quota view's default account lookup against a fresh cache 2026-11-20 05:36:37 -03:00
diegosouzapw
cf97c2b9ee fix(api): keep operator-named windows out of the quota view and flag reset readings
Model windows are listed only for providers with a plan-window mapping
(claude, anthropic, codex), whose other cache keys are model or surface
names. Other providers can key their cache by operator-chosen names or
upstream key and limit ids, so their model windows are now empty.

A cached reading whose reset time is already before the view's clock is
reported as stale, with its numbers kept. The builder now receives that
clock from the view.

A failed account lookup is still reported as unavailable, and now leaves
a warning in the server log.
2026-11-20 05:36:23 -03:00
diegosouzapw
840ff8ff8f feat(api): add per-account percent windows to the self-service quota view 2026-11-20 05:20:28 -03:00
diegosouzapw
3290609d6e test(api): pin that the quota view never carries another key's id 2026-11-20 05:15:09 -03:00
diegosouzapw
2930fdbb4c feat(api): build the self-service quota view for a key's pools 2026-11-20 05:08:06 -03:00
diegosouzapw
7f37df27cb fix(api): make the pool ref input unambiguous and pin nested stripping 2026-11-20 05:00:11 -03:00
diegosouzapw
7f17d1e52e feat(api): define the self-service quota contract and the opaque pool ref 2026-11-20 04:52:03 -03:00
diegosouzapw
401c55d26d refactor(api): extract the quota key model listing into a shared helper 2026-11-20 01:25:42 -03:00
diegosouzapw
ff18b6a7c2 fix(api): drop the address lockout from the self-service auth gate 2026-11-20 01:17:32 -03:00
diegosouzapw
516c76684b feat(api): add QUOTA_SELF_PANEL flag and the self-service auth gate 2026-11-20 01:00:40 -03:00
47 changed files with 5819 additions and 53 deletions

View File

@@ -978,6 +978,14 @@ NEXT_PUBLIC_BASE_URL=http://localhost:20128
# Do not include /v1; if included accidentally it will be normalized away.
# OMNIROUTE_PUBLIC_BASE_URL=http://192.168.0.15:20128
# Origin of the inference API as key holders reach it, reported by
# GET /v1/me/quota/{provider}. Set it when the API is served from a different
# origin than the dashboard, for example behind API_PORT. Falls back to
# OMNIROUTE_PUBLIC_BASE_URL; with neither set the API reports no base URL.
# An invalid value yields no base URL and does not fall back to
# OMNIROUTE_PUBLIC_BASE_URL.
# OMNIROUTE_PUBLIC_API_BASE_URL=https://api.example.com
# Absolute provider plugin manifest URL advertised to sidecar clients.
# Used by: open-sse/config/providerPluginManifestUrl.ts. When unset, OmniRoute
# derives the URL from request origin or HOST/PORT using OMNIROUTE_PUBLIC_PROTOCOL.

View File

@@ -0,0 +1 @@
- **feat(api):** self-service quota API for API key holders, off by default behind the new `QUOTA_SELF_PANEL` feature flag. `GET /v1/me/quota/{provider}` returns the quota-share pools the key is allocated in for that provider, with the key's fair share and consumption per window, the schedule windows and per-model caps it is under, and its expiry. Account bars and per-model windows need the `self:account-quota` scope and a provider the key's settings share, and only cover connections the key may use. A number that cannot be read is reported as unavailable or `null`, never as zero. Pool display names and schedule labels are shown to key holders as the administrator wrote them. The key needs the `self:usage` scope and is read from headers only. New optional `OMNIROUTE_PUBLIC_API_BASE_URL` sets the API origin reported to key holders ([#20767](https://github.com/cheaper-inference/OmniRoute/pull/20767)).

View File

@@ -0,0 +1 @@
- **feat(api):** `GET /v1/me/usage?range=1d|7d|30d|90d` returns the usage and cost series of an API key's own requests: totals, one entry per UTC day, per day and model, per provider-and-model pair (the 50 with the most requests) and per provider. Each entry carries the billed cost, where flat-rate subscriptions count $0, next to the list price. The range defaults to `30d`, and `coverage` reports the window and the operator's raw usage-history retention setting. Rows are selected by the calling key's id only, and a built series is reused for 60 seconds per key and range, with at most 64 kept in memory. The route shares the `QUOTA_SELF_PANEL` feature flag, the `self:usage` scope and the header-only authentication of `GET /v1/me/quota/{provider}` ([#20787](https://github.com/cheaper-inference/OmniRoute/pull/20787))

View File

@@ -15999,6 +15999,80 @@ paths:
description: The key lacks the self:usage scope
"500":
description: Status could not be built
/api/v1/me/quota/{provider}:
get:
tags:
- V1 Me
summary: "GET me › quota"
description: >-
Self-service quota view for the calling API key (also served at /v1/me/quota/{provider}):
the key's position in the Quota Share pools of one provider, plus the schedule windows
and per-model caps it is under. Off unless the `QUOTA_SELF_PANEL` feature flag is on
(a request that reaches the route gets 404 otherwise). Authenticate with `Authorization: Bearer <key>` or `x-api-key: <key>`;
the key is never read from the query string or a cookie. Requires scope `self:usage`.
Account-level readings (`total`, `accounts[].dimensions[].account`, `modelWindows`) are
included only with scope `self:account-quota` and only for providers in the key's
`sharedQuotaProviders` setting. Account bars and model windows are further limited to
the connections the key may use when it has a list of allowed connections. Pools are
identified by an opaque per-key `ref`. The pool's display name and schedule labels are
returned as the administrator wrote them. No pool id, connection id or account identity
is returned. A key outside every pool of the provider gets 200 with `pools: []`. Every
response of this route carries `Cache-Control: no-store`; a refusal before the route runs,
for example by the client API policy or the IP filter, does not.
security:
- BearerAuth: []
- XApiKeyAuth: []
parameters:
- name: provider
in: path
required: true
description: >-
Provider id or registry alias (for example `claude`, `anthropic`, `cc`, `codex`).
Trimmed and lower-cased; must then match `^[a-z0-9][a-z0-9._-]{0,63}$`.
schema:
type: string
responses:
"200":
description: Quota view for the calling key
headers:
Cache-Control:
schema:
type: string
enum: [no-store]
content:
application/json:
schema:
$ref: "#/components/schemas/SelfQuotaView"
"400":
description: Invalid provider
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Missing or invalid API key, or the server's environment key
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"403":
description: The key lacks the self:usage scope
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: The QUOTA_SELF_PANEL feature flag is off
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: The quota view could not be built (fixed message, no detail)
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/me/sessions:
get:
tags:
@@ -16124,6 +16198,86 @@ paths:
success: { type: boolean }
"404":
description: Session not found
/api/v1/me/usage:
get:
tags:
- V1 Me
summary: "GET me › usage"
description: >-
Usage and cost series of the calling API key's own requests (also served at
/v1/me/usage): totals, one entry per UTC day, per day and model, per model and per
provider. Rows are selected by the calling key's id. The key name is never matched and
rows without a key id are never counted. Off unless the `QUOTA_SELF_PANEL` feature flag
is on (a request that reaches the route gets 404 otherwise). Authenticate with
`Authorization: Bearer <key>` or `x-api-key: <key>`; the key is never read from the query
string or a cookie. Requires scope `self:usage`. The key is checked before `range`.
Provider and model are returned as recorded. A combo request whose every target was
refused is recorded with the routing label as provider (the combo name, `auto` or
`combo`) and the model string the client sent. `costUsd` is the billed cost, where
flat-rate subscription providers count $0. `listPriceUsd` prices the same usage at list
price, subscriptions included. A request whose model has no price row counts its stored
cost (reported by the provider or calculated when recorded); only a request with neither
counts 0, with no marker, so a total can be partial. A built series is reused for 60
seconds per key and range; `generatedAt` gives its age. Every response
of this route carries `Cache-Control: no-store`; a refusal before the route runs, for
example by the client API policy or the IP filter, does not.
security:
- BearerAuth: []
- XApiKeyAuth: []
parameters:
- name: range
in: query
required: false
description: >-
Window ending when the series is built. The set stops at `90d` to bound the cost of
a call. The view reads raw usage history only, never the daily summaries. Any other
value, an empty value or a repeated parameter is a 400.
schema:
type: string
enum: [1d, 7d, 30d, 90d]
default: 30d
responses:
"200":
description: Usage series of the calling key
headers:
Cache-Control:
schema:
type: string
enum: [no-store]
content:
application/json:
schema:
$ref: "#/components/schemas/SelfUsageSeries"
"400":
description: Invalid range
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Missing or invalid API key, or the server's environment key
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"403":
description: The key lacks the self:usage scope
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: The QUOTA_SELF_PANEL feature flag is off
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: The usage series could not be built (fixed message, no detail)
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/models/{model}:
get:
tags:
@@ -17293,7 +17447,7 @@ components:
type: apiKey
in: header
name: x-api-key
description: Inference API key sent in the x-api-key header (accepted by /v1/me/status).
description: Inference API key sent in the x-api-key header (accepted by /v1/me/status, /v1/me/quota/{provider} and /v1/me/usage).
ManagementSessionAuth:
type: apiKey
in: cookie
@@ -19443,6 +19597,419 @@ components:
$ref: "#/components/schemas/ApiKeySelfServiceAccountQuota"
accountQuota:
$ref: "#/components/schemas/ApiKeySelfServiceAccountQuota"
SelfQuotaStatus:
type: string
enum: [ok, stale, unavailable]
SelfQuotaWindow:
type: string
enum: ["5h", hourly, daily, weekly, monthly]
SelfQuotaBar:
type: object
additionalProperties: false
required: [used, status]
properties:
used:
type: [number, "null"]
status:
$ref: "#/components/schemas/SelfQuotaStatus"
reason:
type: string
resetAt:
type: [string, "null"]
SelfQuotaShare:
type: object
additionalProperties: false
required: [fairShare, consumed, remaining, status]
properties:
fairShare:
type: number
consumed:
type: [number, "null"]
remaining:
type: [number, "null"]
description: >-
The part of `fairShare` the key has not used, floored at 0. Not a guarantee: the
pool can be exhausted first, and the allocation's `cap` is not taken into account.
status:
$ref: "#/components/schemas/SelfQuotaStatus"
reason:
type: string
SelfQuotaSharedDimension:
type: object
description: Pool bucket of a countable unit; `limit` is the plan limit times the pool's accounts.
additionalProperties: false
required: [unit, window, limit, yourShare]
properties:
unit:
type: string
enum: [requests, tokens, usd]
window:
$ref: "#/components/schemas/SelfQuotaWindow"
limit:
type: number
total:
$ref: "#/components/schemas/SelfQuotaBar"
yourShare:
$ref: "#/components/schemas/SelfQuotaShare"
SelfQuotaAccountDimension:
type: object
description: A `percent` window of one account; `limit` is the plan limit.
additionalProperties: false
required: [unit, window, limit, yourShare]
properties:
unit:
type: string
enum: [percent]
window:
$ref: "#/components/schemas/SelfQuotaWindow"
limit:
type: number
account:
$ref: "#/components/schemas/SelfQuotaBar"
yourShare:
$ref: "#/components/schemas/SelfQuotaShare"
SelfQuotaAccount:
type: object
additionalProperties: false
required: [slot, label, dimensions]
properties:
slot:
type: integer
minimum: 1
label:
type: string
description: Neutral label by pool order ("Account 1", ...).
dimensions:
type: array
items:
$ref: "#/components/schemas/SelfQuotaAccountDimension"
modelWindows:
type: object
additionalProperties: false
required: [status, windows]
properties:
status:
$ref: "#/components/schemas/SelfQuotaStatus"
reason:
type: string
windows:
type: array
items:
type: object
additionalProperties: false
required: [label, usedPercent, resetAt]
properties:
label:
type: string
usedPercent:
type: number
resetAt:
type: [string, "null"]
SelfQuotaPool:
type: object
additionalProperties: false
required:
[ref, name, provider, borrowMode, policy, weight, cap, accountVisible, dimensions, accounts]
properties:
ref:
type: string
description: >-
Opaque reference to the pool, bound to the calling key and derived with the server's
API-key secret. Do not persist it: it changes if that secret is rotated.
name:
type: string
description: The pool's display name, as the administrator wrote it.
provider:
type: string
borrowMode:
type: string
enum: [saturation]
policy:
type: string
enum: [hard, soft, burst]
weight:
type: number
description: The weight the quota gate applies (equal split when every weight is 0).
cap:
type: [object, "null"]
additionalProperties: false
required: [unit, value]
properties:
unit:
type: string
enum: [percent, requests, tokens, usd]
value:
type: number
accountVisible:
type: boolean
dimensions:
type: array
items:
$ref: "#/components/schemas/SelfQuotaSharedDimension"
accounts:
type: array
items:
$ref: "#/components/schemas/SelfQuotaAccount"
SelfQuotaBlocks:
type: object
additionalProperties: false
required: [schedules, modelCaps]
properties:
schedules:
type: array
items:
type: object
additionalProperties: false
required: [pool, state, reason, label, retryAfterSeconds, reserves, budget]
properties:
pool:
type: string
description: The pool's `ref`.
state:
type: string
enum: [open, closed]
reason:
type: [string, "null"]
enum: [blackout, outside-window, null]
label:
type: [string, "null"]
description: The schedule's label, as the administrator wrote it.
retryAfterSeconds:
type: [number, "null"]
reserves:
type: array
items:
type: object
additionalProperties: false
required: [window, percent]
properties:
window:
type: string
enum: ["5h", hourly, daily, weekly, monthly, any]
percent:
type: number
budget:
type: [object, "null"]
additionalProperties: false
required: [unit, window, exhausted]
properties:
unit:
type: string
enum: [requests, tokens, usd]
window:
$ref: "#/components/schemas/SelfQuotaWindow"
exhausted:
type: [boolean, "null"]
modelCaps:
type: array
items:
type: object
additionalProperties: false
required: [pool, model, unit, window, cap, consumed, reached]
properties:
pool:
type: string
description: The pool's `ref`.
model:
type: string
unit:
type: string
enum: [percent, requests, tokens, usd]
window:
type: string
enum: [hourly]
cap:
type: number
consumed:
type: [number, "null"]
reached:
type: [boolean, "null"]
SelfQuotaView:
type: object
description: >-
Self-service quota view of one API key for one provider. Optional fields are omitted
when absent, never sent as null unless the field is nullable.
additionalProperties: false
required: [provider, generatedAt, pools, availableModels, expiresAt, apiBaseUrl, blocks]
properties:
provider:
type: string
generatedAt:
type: string
format: date-time
pools:
type: array
items:
$ref: "#/components/schemas/SelfQuotaPool"
availableModels:
type: array
description: The `qtSd/` model ids the key sees in /v1/models.
items:
type: string
expiresAt:
type: [string, "null"]
apiBaseUrl:
type: [string, "null"]
description: Configured public API origin, never the request's origin.
blocks:
$ref: "#/components/schemas/SelfQuotaBlocks"
SelfUsageSeries:
type: object
description: >-
Usage and cost series of one API key. Days are UTC days. Every cost is summed row by row
and rounded to 6 decimals. `costUsd` is the billed cost, where flat-rate subscription
providers count $0. `listPriceUsd` is the same usage priced at list price,
subscriptions included. A request whose model has no price row counts its stored cost,
and only a request with neither counts 0, with no marker.
additionalProperties: false
required: [range, generatedAt, coverage, summary, daily, dailyByModel, byModel, byProvider]
properties:
range:
type: string
enum: [1d, 7d, 30d, 90d]
generatedAt:
type: string
format: date-time
coverage:
type: object
additionalProperties: false
required: [from, to, retentionDays, truncatedByRetention]
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
retentionDays:
type: number
description: The operator's raw usage-history retention setting, in days.
truncatedByRetention:
type: boolean
description: >-
True when the requested range is longer than the retention setting. It compares
the two numbers and does not check whether rows are actually missing.
summary:
type: object
additionalProperties: false
required:
[
requests,
promptTokens,
completionTokens,
totalTokens,
costUsd,
listPriceUsd,
successfulRequests,
successRatePct,
uniqueModels,
avgLatencyMs,
firstRequest,
lastRequest,
]
properties:
requests: { type: number }
promptTokens: { type: number }
completionTokens: { type: number }
totalTokens: { type: number }
costUsd: { type: number }
listPriceUsd: { type: number }
successfulRequests: { type: number }
successRatePct: { type: number }
uniqueModels:
type: number
description: Distinct model names as recorded, every spelling counted.
avgLatencyMs: { type: number }
firstRequest: { type: [string, "null"], format: date-time }
lastRequest: { type: [string, "null"], format: date-time }
daily:
type: array
items:
type: object
additionalProperties: false
required:
[date, requests, promptTokens, completionTokens, totalTokens, costUsd, listPriceUsd]
properties:
date: { type: string, format: date }
requests: { type: number }
promptTokens: { type: number }
completionTokens: { type: number }
totalTokens: { type: number }
costUsd: { type: number }
listPriceUsd: { type: number }
dailyByModel:
type: array
items:
type: object
additionalProperties: false
required: [date, model, totalTokens, costUsd, listPriceUsd]
properties:
date: { type: string, format: date }
model: { type: string }
totalTokens: { type: number }
costUsd: { type: number }
listPriceUsd: { type: number }
byModel:
type: array
description: >-
The 50 provider-and-model pairs with the most requests. With more pairs the entries
do not add up to `summary`.
items:
type: object
additionalProperties: false
required:
[
model,
provider,
requests,
promptTokens,
completionTokens,
totalTokens,
costUsd,
listPriceUsd,
avgLatencyMs,
successRatePct,
lastUsed,
]
properties:
model: { type: string }
provider: { type: string }
requests: { type: number }
promptTokens: { type: number }
completionTokens: { type: number }
totalTokens: { type: number }
costUsd: { type: number }
listPriceUsd: { type: number }
avgLatencyMs: { type: number }
successRatePct: { type: number }
lastUsed: { type: [string, "null"], format: date-time }
byProvider:
type: array
items:
type: object
additionalProperties: false
required:
[
provider,
requests,
promptTokens,
completionTokens,
totalTokens,
costUsd,
listPriceUsd,
avgLatencyMs,
successRatePct,
]
properties:
provider: { type: string }
requests: { type: number }
promptTokens: { type: number }
completionTokens: { type: number }
totalTokens: { type: number }
costUsd: { type: number }
listPriceUsd: { type: number }
avgLatencyMs: { type: number }
successRatePct: { type: number }
ApiKey:
type: object
properties:

View File

@@ -370,6 +370,7 @@ OmniRoute provides a two-layer defense: request-side injection scanning and resp
| `NEXT_PUBLIC_APP_URL` | _(unset)_ | `src/shared/services/cloudSyncScheduler.ts` | Legacy fallback for `NEXT_PUBLIC_BASE_URL`. |
| `NEXT_PUBLIC_PORT` | _(unset — falls back to `PORT`)_ | `src/shared/hooks/useDisplayBaseUrl.ts` | Client-side fallback port for display URLs when no origin is known (SSR/tests); read before `PORT`. |
| `OMNIROUTE_PUBLIC_BASE_URL` | _(unset)_ | Public-origin resolver, image URLs | Highest-priority browser-facing OmniRoute origin used for public URL generation and non-dashboard browser-origin validation. Set this when OpenWebUI or another relay reaches OmniRoute by an internal URL but the user's browser must fetch generated media from a LAN, tunnel, or public origin. Do **not** include `/v1`. |
| `OMNIROUTE_PUBLIC_API_BASE_URL` | _(unset)_ | `src/server/origin/publicApiBaseUrl.ts` | Origin of the inference API as key holders reach it, reported by `GET /v1/me/quota/{provider}`. Set it when the API is served from a different origin than the dashboard, for example behind `API_PORT`. Falls back to `OMNIROUTE_PUBLIC_BASE_URL`; with neither set the API reports no base URL. An invalid value yields no base URL and does not fall back to `OMNIROUTE_PUBLIC_BASE_URL`. |
| `OMNIROUTE_PROVIDER_MANIFEST_URL` | _(unset)_ | `open-sse/config/providerPluginManifestUrl.ts` | Absolute provider plugin manifest URL advertised to sidecar clients. When unset, OmniRoute derives `/api/v1/provider-plugin-manifest` from request origin or HOST/PORT. |
| `OMNIROUTE_PUBLIC_PROTOCOL` | `http` | `open-sse/config/providerPluginManifestUrl.ts` | Protocol used when deriving the provider plugin manifest URL from HOST/PORT without a request origin. Set to `https` behind a TLS-terminating public proxy when no explicit `OMNIROUTE_PROVIDER_MANIFEST_URL` is set. |
| `OMNIROUTE_TRUST_PROXY` | _(unset)_ | `src/server/origin/publicOrigin.ts` | Optional trust mode for forwarded public-origin headers. Unset = do not trust `Forwarded` / `X-Forwarded-*` for security decisions. `true` / `loopback` trusts forwarded host/proto only from a token-stamped loopback proxy. `private` / `lan` also trusts private-LAN proxy peers, lets the `API_PORT` bridge keep such a peer's `X-Forwarded-For`, and lets LOCAL_ONLY routes accept a private-network client that such a proxy reports (never a Cloudflare-tunnel request, a loopback-only chain, or the loopback-only CLI-token gate). Prefer explicit `NEXT_PUBLIC_BASE_URL` in production. |

View File

@@ -46,10 +46,10 @@ A boolean flag is considered **enabled** when its effective value is `"true"`,
## Flag Catalog
126 flags across 6 categories. **Default** is the definition default — the value
127 flags across 6 categories. **Default** is the definition default — the value
used when neither a DB override nor an environment variable is present.
### Security (12)
### Security (13)
| Key | Type | Default | Description |
| --------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -65,6 +65,7 @@ used when neither a DB override nor an environment variable is present.
| `AUTH_LOG_INCLUDE_ACCOUNT_ID` | boolean | `false` | Include account prefix in AUTH log lines (e.g. "Using <provider> account: abc12345..."). Disabled by default so account identifiers are redacted from shared/multi-tenant process logs. Independent from Debug Mode; flipping Debug Mode does not reveal this. |
| `OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN` | boolean | `false` | When OIDC is enabled, disable password login so users can only authenticate via OIDC Single Sign-On. When disabled (default), both password login and OIDC are available. |
| `API_KEY_AUDIT_CLIENT_DETAILS_ENABLED` | boolean | `false` | Record the caller's IP address and user-agent on the `api_key.auth.touch` audit-log rows written for successful API-key metadata and discovery reads (#17982). Off by default: those rows still record which key was used, when, and on which path, without IP or user-agent. |
| `QUOTA_SELF_PANEL` | boolean | `false` | Let an API key read its own quota-share position and usage: enables `GET /v1/me/quota/{provider}` and `GET /v1/me/usage` for keys with the `self:usage` scope. Pool names and schedule labels are shown to those keys as written. Off by default: those routes answer 404. |
### Network (32)
@@ -289,10 +290,10 @@ Returns every flag with its effective value, source, and a summary.
"requiresRestart": false,
"warningLevel": "caution",
},
// ... all 126 flags
// ... all 127 flags
],
"summary": {
"total": 126,
"total": 127,
"active": 0,
"inactive": 0,
"overriddenByDb": 0,

View File

@@ -279,6 +279,168 @@ The page hooks:
---
## Self-Service Quota API (opt-in)
`GET /api/v1/me/quota/{provider}` (also served at `/v1/me/quota/{provider}`) lets an API key
holder read, with their own key, how much of a shared subscription is theirs and what is
blocking them. The route is a thin shell over `src/server/selfService/quotaHandler.ts`; the view
is built by `src/lib/quota/selfView.ts` and its response contract is
`src/shared/schemas/selfQuota.ts` (`SelfQuotaView` in `docs/openapi.yaml`).
### Enabling and authentication
- Feature flag `QUOTA_SELF_PANEL`, default `false`. While it is off, a request that reaches the
route gets 404. With `REQUIRE_API_KEY=true`, the client API policy refuses a missing or invalid
key with 401 before the route runs, whatever the flag. A request with no key but a signed-in
dashboard session passes that policy and gets the route's own answer. The flag resolves like
every other flag (dashboard or REST override, then the environment variable of the same name);
see [`FEATURE_FLAGS.md`](../reference/FEATURE_FLAGS.md).
- Each pool's display name and each schedule's label are returned to the pool's key holders
exactly as the administrator wrote them. Before turning the flag on, check that they are fit to
be read by those key holders.
- The key is read from headers only: `Authorization: Bearer <key>` or `x-api-key: <key>`. When
both are sent, the first one that validates is used. A key in the query string or a cookie is
ignored. The server's environment key is refused (401).
- The key needs the `self:usage` scope (403 without it).
- The provider segment is trimmed, lower-cased and checked against
`^[a-z0-9][a-z0-9._-]{0,63}$` (400 otherwise), then resolved through the provider registry,
so an alias such as `cc` reads the `claude` pools. `claude` and `anthropic` read the same pools.
### What each visibility shows
| Visibility | Requires | Fields |
| ------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Own share | `self:usage` | `pools[]` (ref, name, provider, policy, weight, cap), `dimensions[].yourShare`, `accounts[]` with `yourShare`, `blocks`, `availableModels`, `expiresAt`, `apiBaseUrl` |
| Account level | `self:usage` + `self:account-quota`, and the provider in the key's `sharedQuotaProviders` | adds `dimensions[].total`, `accounts[].dimensions[].account` and `accounts[].modelWindows` |
- `sharedQuotaProviders` is a per-key setting (`PUT /api/keys/[id]/self-service`): `null`, the
default, means every provider the key reaches; `[]` means none. Each pool's `accountVisible`
says which visibility applied to it.
- Account bars and model windows are shown only for accounts whose connection the key may use.
When the key has a list of allowed connections, an account outside it keeps its `Account N`
entry without `account` or `modelWindows`. An empty list means no restriction, as for
`/v1/me/status`. The pool total (`dimensions[].total`) does not depend on that list.
- Two figures shown with `self:usage` alone come from other keys' use. A schedule budget's
`exhausted` reflects the consumption of every key under that schedule. In a pool whose weights
are all zero, the key's `weight` is `100 / number of members`. Both are what enforcement
applies to the key.
- A pool is identified only by `ref`, an opaque value bound to the calling key. Its display name
(`name`) is included as the administrator wrote it. A `ref` is derived from the key and the
pool with the server's API-key secret (`API_KEY_SECRET`). Clients must not persist it: it
changes if that secret is rotated.
- Accounts are listed as `Account 1`, `Account 2`, … in pool order. No pool id, connection id,
account e-mail or account name is returned, and the response goes through the contract schema,
which drops any field outside it.
- Countable units (`requests`, `tokens`, `usd`) are reported as the pool bucket the quota gate
enforces: `limit` = plan limit × accounts in the pool, `fairShare` = weight / 100 × `limit`
(equal split when every weight is 0), `consumed` = the key's own counter in the quota store,
`remaining` = `fairShare` − `consumed`, floored at 0.
- `blocks.schedules` lists the key's schedule windows (`open`/`closed`, `blackout` or
`outside-window`, `retryAfterSeconds`, reserve floors, and whether the window's budget is
spent); `blocks.modelCaps` lists its per-model hourly caps with consumption.
- A key outside every pool of the provider gets 200 with `pools: []`; `availableModels` (the
`qtSd/` ids the key sees in `/v1/models`), `expiresAt` and `apiBaseUrl` are still filled.
- `apiBaseUrl` is `OMNIROUTE_PUBLIC_API_BASE_URL`, then `OMNIROUTE_PUBLIC_BASE_URL`, else
`null`. It is never the request's own origin.
### `status` and `reason`
| `status` | Meaning |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ok` | A current reading. |
| `stale` | A cached account reading marked stale, or one whose reset time has passed since it was read. Numbers are kept. One model window whose reset time has passed marks the whole `modelWindows` group `stale`. |
| `unavailable` | No reading; the numbers are `null`, never `0`. `reason` says why. |
| `reason` | When |
| --------------------------------- | --------------------------------------------------------------------------- |
| `store_unavailable` | The quota store could not be read. |
| `percent_attribution_unavailable` | The key's own share of a `percent` window (see Limitations). |
| `window_not_reported` | The provider-limits cache has no reading for that plan window. |
| `connection_lookup_failed` | The account's connection could not be read. |
| `not_supported` | OmniRoute cannot read usage limits for the account's provider. |
| `fetch_failed` | No cached reading was usable and the provider-limits refresh failed. |
| `not_available` | The reading carries no usage windows, or the account has no reading at all. |
When the quota store cannot be read, the store-backed fields of `blocks` (a schedule budget's
`exhausted`, a model cap's `consumed` and `reached`) are `null` as well.
### Errors
Every response of this route, success or error, carries `Cache-Control: no-store`. A refusal
that happens before the route runs does not carry it, for example the client API policy's 401
or the IP filter's 403. Errors of the route use the standard error body with a fixed message: 400 (invalid
provider), 401 (missing or invalid key), 403 (missing `self:usage`), 404 (flag off) and 500
(`Failed to build quota view`). The 500 covers any failure once the request reaches the route,
including the key lookup itself; its cause is logged on the server and never returned.
### Limitations
- `remaining` is the part of the key's fair share it has not used. It is not a guarantee. A key
may still be served beyond it while the pool has room. Once the pool's total reaches `limit`,
every key of the pool is refused, whatever its own `remaining`, and a key without
`self:account-quota` cannot see that total.
- `remaining` does not take the allocation's absolute `cap` into account. Enforcement refuses the
key once its own consumption in a window of the cap's unit reaches the cap's value.
- The account-level bar comes from the provider-limits cache and can lag the enforcement
decision by a few minutes. A reading whose reset time has passed is reported as `stale`.
- Per-model windows (`modelWindows`) are reported only for providers that have a plan-window
mapping: Claude and Codex today. For other providers `modelWindows` is still present when
account data is shown, with an empty `windows` list.
- The key's own share of a `percent` window is reported as `unavailable`
(`percent_attribution_unavailable`) for now.
- Reserve floors of a schedule are not evaluated by the view: a schedule can show as `open`
while a request is refused with reason `schedule-reserve`.
- When two pools of the same key share a connection, enforcement applies one of them, and the
view lists both.
- There is no per-address limit on failed key attempts: behind a reverse proxy callers can share
one address (it depends on whether forwarded client addresses are trusted), so a lockout could
deny the route to every key holder. With `REQUIRE_API_KEY=true`, an invalid key is refused by
the client API policy before the route runs, with that policy's 401 body instead of this
route's.
### Usage series (`GET /api/v1/me/usage`)
`GET /api/v1/me/usage?range=<range>` (also served at `/v1/me/usage`) returns the usage and cost
of the calling key's own requests: totals, one entry per UTC day, per day and model, per model
and per provider. It shares the flag, the authentication rules, the `self:usage` scope,
`Cache-Control: no-store` and the error behavior of the quota route above. The key is checked
before `range`. Errors are 400 (`Invalid range`), 401, 403, 404 and 500 (`Failed to build usage`).
- `range` is one of `1d`, `7d`, `30d` (the default) or `90d`. Any other value, an empty value or
a repeated parameter is a 400. The set stops at `90d` to bound the cost of a call. The view
reads raw usage history only, never the daily summaries, which carry no key.
- Rows are selected by the calling key's id. The key name column is never matched, and rows
recorded without a key id are never counted.
- Building a series runs five grouped queries over the key's rows in the window. The built
series is reused for 60 seconds per key and range, and a reused call runs none. Its
`generatedAt` gives its age.
- The window ends when the series is built. A row stamped later, for example by clock skew, is
not counted.
- `coverage.retentionDays` is the operator's raw usage-history retention setting
(`retention.usageHistory` in the database settings). `coverage.truncatedByRetention` is true
when the requested range is longer than that setting. It compares the two numbers and does not
check whether rows are actually missing.
- Provider and model are returned as recorded for the key's own requests. A combo request whose
every target was refused is recorded with the routing label as provider (the combo name, `auto`
or `combo`) and the model string the client sent. Other refused requests, for example by an
open circuit breaker, a model cooldown or a quota-parked skip, keep the target provider and
model.
- Besides counts and costs, the response carries average latency, success rates and the times of
the first and last request.
- `byModel` lists the 50 provider-and-model pairs with the most requests. With more pairs its
entries do not add up to `summary`, and `summary.uniqueModels` counts every recorded model
spelling.
- Two costs are reported. `costUsd` is the billed cost, as the usage analytics show it.
Flat-rate subscription providers, such as the Claude Code plan, count $0 there. `listPriceUsd`
is the same usage priced at list price, subscriptions included. A request whose model has no
price row counts its stored cost: a cost the provider reported, or one calculated when the
request was recorded. Only a request with neither counts 0, with no marker, so a total can be
partial.
- The response contract is `src/shared/schemas/selfUsage.ts` (`SelfUsageSeries` in
`docs/openapi.yaml`).
---
## Environment Variables
| Variable | Default | Description |

View File

@@ -2,12 +2,8 @@
* GET /api/quota/keys/[id]/models
*
* Returns the `qtSd/` virtual model IDs that a given API key would see in
* /v1/models, by reusing the SAME catalog.ts approach:
* resolveQuotaKeyScope(key.allowedQuotas) → scope.poolSlugs
* filterModelsToQuotaPools(candidates, scope.poolSlugs)
*
* Candidates are the combo names from getCombos() mapped to { id: combo.name }
* (same shape catalog.ts passes to filterModelsToQuotaPools).
* /v1/models, through the shared listQuotaKeyModels helper
* (src/lib/quota/quotaKeyModels.ts), which reuses the catalog.ts approach.
*
* Auth: requireManagementAuth (management-gated, not quota-key-gated).
* Error sanitization: buildErrorBody (Hard Rule #12).
@@ -20,9 +16,7 @@ import { NextResponse } from "next/server";
import { buildErrorBody } from "@omniroute/open-sse/utils/error";
import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
import { getApiKeyById } from "@/lib/db/apiKeys";
import { getCombos } from "@/lib/db/combos";
import { resolveQuotaKeyScope } from "@/lib/quota/quotaKey";
import { filterModelsToQuotaPools } from "@/lib/quota/quotaCombos";
import { listQuotaKeyModels } from "@/lib/quota/quotaKeyModels";
export const dynamic = "force-dynamic";
@@ -44,22 +38,7 @@ export async function GET(request: Request, { params }: RouteParams): Promise<Re
? ((key as Record<string, unknown>).allowedQuotas as string[])
: [];
const scope = await resolveQuotaKeyScope(allowedQuotas);
// Build the candidate list from all combo names — same shape catalog.ts uses:
// objects with an `id` field (combo.name) passed to filterModelsToQuotaPools.
let allCombos: Awaited<ReturnType<typeof getCombos>> = [];
try {
allCombos = await getCombos();
} catch {
// DB unavailable — treat as empty combo list; models will be [].
}
const candidates = allCombos
.filter((c) => typeof c.name === "string" && c.name.length > 0)
.map((c) => ({ id: c.name as string }));
const models = filterModelsToQuotaPools(candidates, scope.poolSlugs).map((m) => m.id);
const models = await listQuotaKeyModels(allowedQuotas);
return NextResponse.json({ models });
} catch (err) {

View File

@@ -0,0 +1,18 @@
/**
* GET /api/v1/me/quota/{provider} (also reachable as /v1/me/quota/{provider}).
*
* Thin shell over handleSelfQuotaGet (src/server/selfService/quotaHandler.ts): the API key holder
* reads their own position in the quota-share pools of one provider. Off unless the
* QUOTA_SELF_PANEL feature flag is on; the key is read from headers only.
*/
import { handleSelfQuotaGet } from "@/server/selfService/quotaHandler";
export const dynamic = "force-dynamic";
export async function GET(
request: Request,
{ params }: { params: Promise<{ provider: string }> }
): Promise<Response> {
const { provider } = await params;
return handleSelfQuotaGet(request, provider);
}

View File

@@ -0,0 +1,14 @@
/**
* GET /api/v1/me/usage (also reachable as /v1/me/usage).
*
* Thin shell over handleSelfUsageGet (src/server/selfService/usageHandler.ts): the API key holder
* reads the usage and cost series of their own key. Off unless the QUOTA_SELF_PANEL feature flag
* is on; the key is read from headers only.
*/
import { handleSelfUsageGet } from "@/server/selfService/usageHandler";
export const dynamic = "force-dynamic";
export async function GET(request: Request): Promise<Response> {
return handleSelfUsageGet(request);
}

View File

@@ -82,6 +82,20 @@ export function getModelCap(poolId: string, apiKeyId: string, model: string): Mo
.get(poolId, apiKeyId, model);
return row ? rowToModelCap(row) : null;
}
/** Caps of one key in one pool, ordered by model. */
export function listModelCapsForApiKey(poolId: string, apiKeyId: string): ModelCap[] {
return getDb()
.prepare<ModelCapRow>(
`SELECT pool_id, api_key_id, model, cap_value, cap_unit
FROM quota_allocation_model_caps
WHERE pool_id = ? AND api_key_id = ?
ORDER BY model`
)
.all(poolId, apiKeyId)
.map(rowToModelCap);
}
export function setModelCap(cap: ModelCap): void {
getDb()
.prepare(

View File

@@ -0,0 +1,38 @@
/**
* db/usageAnalytics/apiKeyScope.ts — the usage source a single API key may read about itself
* (GET /v1/me/usage).
*
* This is the only place the per-key filter of the self-service usage view is written. Rows are
* selected by the calling key's id, passed as a bound parameter, and by nothing else: the
* `api_key_name` column is never matched, so a row of another key whose name happens to equal
* the caller's id stays out. Rows without a key id (NULL or empty, written before keys were
* recorded) never equal a non-empty id, so they are never attributed to the caller. With a key
* filter, `buildUnifiedSource` reads `usage_history` only, never the daily summaries (which carry
* no key).
*/
import { buildUnifiedSource, type UnifiedSourceResult } from "./sources";
export interface ApiKeyOwnedSourceOptions {
/** Id of the calling key, as stored in `usage_history.api_key_id`. Must be non-empty. */
apiKeyId: string;
/** ISO-8601 lower bound of the window, or null for every stored row. */
sinceIso: string | null;
/** ISO-8601 upper bound (inclusive), or null for no bound. Rows stamped later are left out. */
untilIso: string | null;
/** YYYY-MM-DD raw-retention boundary, required by the source builder. */
rawCutoffDate: string;
}
export function buildApiKeyOwnedSource(opts: ApiKeyOwnedSourceOptions): UnifiedSourceResult {
if (typeof opts.apiKeyId !== "string" || opts.apiKeyId.trim() === "") {
throw new Error("buildApiKeyOwnedSource: apiKeyId is required");
}
return buildUnifiedSource({
sinceIso: opts.sinceIso,
untilIso: opts.untilIso,
rawCutoffDate: opts.rawCutoffDate,
apiKeyWhere: "api_key_id = @ownerApiKeyId",
apiKeyParams: { ownerApiKeyId: opts.apiKeyId },
});
}

View File

@@ -0,0 +1,53 @@
/**
* The `qtSd/` virtual model IDs an API key would see in /v1/models, using the
* same approach as catalog.ts:
* resolveQuotaKeyScope(allowedQuotas) → scope.poolSlugs
* filterModelsToQuotaPools(candidates, scope.poolSlugs)
*
* Candidates are the combo names from getCombos() mapped to { id: combo.name }
* (the shape catalog.ts passes to filterModelsToQuotaPools).
*
* Defaults are loaded with dynamic import() so tests can inject `deps`.
*/
export interface QuotaKeyModelsDeps {
resolveQuotaKeyScope?: (allowedQuotas: string[]) => Promise<{ poolSlugs: string[] }>;
getCombos?: () => Promise<Array<{ name?: unknown }>>;
}
async function defaultResolveQuotaKeyScope(
allowedQuotas: string[]
): Promise<{ poolSlugs: string[] }> {
const { resolveQuotaKeyScope } = await import("@/lib/quota/quotaKey");
return resolveQuotaKeyScope(allowedQuotas);
}
async function defaultGetCombos(): Promise<Array<{ name?: unknown }>> {
const { getCombos } = await import("@/lib/db/combos");
return getCombos();
}
/** Same algorithm /v1/models uses for a quota key; a failed combo read yields []. */
export async function listQuotaKeyModels(
allowedQuotas: string[] | null | undefined,
deps: QuotaKeyModelsDeps = {}
): Promise<string[]> {
const resolveScope = deps.resolveQuotaKeyScope ?? defaultResolveQuotaKeyScope;
const readCombos = deps.getCombos ?? defaultGetCombos;
const scope = await resolveScope(Array.isArray(allowedQuotas) ? allowedQuotas : []);
let allCombos: Array<{ name?: unknown }> = [];
try {
allCombos = await readCombos();
} catch {
// DB unavailable — treat as an empty combo list; models will be [].
}
const candidates = allCombos
.filter((c) => typeof c.name === "string" && c.name.length > 0)
.map((c) => ({ id: c.name as string }));
const { filterModelsToQuotaPools } = await import("@/lib/quota/quotaCombos");
return filterModelsToQuotaPools(candidates, scope.poolSlugs).map((m) => m.id);
}

View File

@@ -0,0 +1,29 @@
import { opaqueTokenFingerprint } from "@omniroute/open-sse/utils/opaqueTokenFingerprint.ts";
const POOL_REF_PREFIX = "qpr_";
const POOL_REF_CONTEXT = "quota-pool-ref:v1";
const POOL_REF_LENGTH = 32;
/**
* Opaque, per-key reference to a quota pool.
*
* "qpr_" + first 32 hex chars (128 bits) of HMAC-SHA256(secret,
* JSON.stringify(["quota-pool-ref:v1", apiKeyId, poolId])). The JSON array encoding keeps the
* boundary between the two ids unambiguous whatever characters they contain. The ref is bound to
* the key (the ref given to key A does not resolve for key B) and cannot be computed or confirmed
* without the server secret. Throws on an empty secret.
*
* The keyed digest goes through opaqueTokenFingerprint, the project's single helper for fast
* digests of identifiers and high-entropy tokens: this derives a reference from two ids, it does
* not store or verify a password.
*/
export function buildPoolRef(apiKeyId: string, poolId: string, secret: string): string {
if (!secret) {
throw new Error("buildPoolRef requires a non-empty secret");
}
const digest = opaqueTokenFingerprint(JSON.stringify([POOL_REF_CONTEXT, apiKeyId, poolId]), {
key: secret,
length: POOL_REF_LENGTH,
});
return `${POOL_REF_PREFIX}${digest}`;
}

440
src/lib/quota/selfView.ts Normal file
View File

@@ -0,0 +1,440 @@
/**
* selfView.ts — the self-service quota view of one API key for one provider.
*
* Read-only. Lists the quota-share pools the key is allocated in for the provider and, for each
* countable plan dimension (requests / tokens / usd), the key's share of the pool bucket with the
* same numbers the quota gate (enforce.ts) uses:
* limit = plan limit × number of pool connections
* fairShare = effectiveWeight / 100 × limit (equal split when every weight in the pool is 0)
* consumed = store.peek(apiKeyId, { poolId, unit, window })
* Placeholder dimensions (limit not above Number.EPSILON) are skipped, as the gate skips them.
*
* `accounts[]` (selfViewAccounts.ts) lists one neutral entry per pool connection with the
* `percent` dimensions. Account-level readings come from resolveAccountQuotaEntries (the cached
* provider-limits snapshot behind /v1/me/status, sharing its refresh tracker and 60 s floor), and
* are asked for only when the pool's `accountVisible` is true, only for the pool's own non-empty
* connection ids, and never with an empty list (which would mean every active connection).
*
* `blocks` (selfViewBlocks.ts) lists the schedule windows and per-model caps the key is under,
* each naming its pool only by `ref`. `availableModels` is the list of `qtSd/` model ids the key
* would see in /v1/models (listQuotaKeyModels; a failed lookup is an empty list) and `expiresAt`
* is the key's own expiry, passed in by the caller. `apiBaseUrl` is the configured public API
* origin (resolvePublicApiBaseUrl), never the request's origin.
*
* A failed quota-store read is reported as `status: "unavailable"` with `consumed`/`remaining`
* null, never as zero. Database reads of allocations and pools are not caught: a failure there
* propagates to the caller instead of being reported as "no pools". The connection-provider and
* plan lookups handle their own errors and answer "unknown"; a pool whose provider cannot be
* resolved that way is left out of the answer.
*
* The result goes through selfQuotaResponseSchema.parse(), so no pool id, connection id or
* account identity leaves this module. The builder reads no request or header, and no
* environment variable itself: the pool-ref secret comes in through `deps.secret`, and the
* default `resolvePublicApiBaseUrl` reads only the two public-origin variables it documents.
*/
import { hasSelfAccountQuotaScope, hasSelfUsageScope } from "@/shared/constants/selfServiceScopes";
import { createLogger } from "@/shared/utils/logger";
import {
selfQuotaResponseSchema,
type SelfQuotaPool,
type SelfQuotaResponse,
type SelfQuotaShare,
type SelfQuotaSharedDimension,
} from "@/shared/schemas/selfQuota";
import {
defaultQuotaRefreshTracker,
isProviderShared,
resolveAccountQuotaEntries,
} from "@/lib/usage/apiKeySelfServiceAccounts";
import type { PoolAllocation, QuotaPool } from "@/lib/db/quotaPools";
import { PolicySchema, type Policy, type QuotaDimension } from "./dimensions";
import { buildPoolRef } from "./selfPoolRef";
import { buildSelfViewAccounts } from "./selfViewAccounts";
import { buildSelfViewBlocks } from "./selfViewBlocks";
import { loadViewStore, readViewStore, type ViewStore } from "./selfViewStore";
import type {
AccountQuotaEntryLike,
QuotaSelfViewDeps,
QuotaSelfViewInput,
SelfViewPoolContext,
} from "./selfViewTypes";
type CountableUnit = SelfQuotaSharedDimension["unit"];
type CountableDimension = QuotaDimension & { unit: CountableUnit };
type CoreDeps = Required<
Pick<
QuotaSelfViewDeps,
| "now"
| "listAllocationsForApiKey"
| "getPool"
| "resolveConnectionProvider"
| "resolvePlan"
| "getQuotaStore"
| "resolveAccountQuotaEntries"
| "listEnabledSchedules"
| "listModelCapsForApiKey"
| "listQuotaKeyModels"
| "resolvePublicApiBaseUrl"
>
> & { secret: string };
const log = createLogger("quota:self-view");
const COUNTABLE_UNITS: ReadonlySet<string> = new Set<CountableUnit>(["requests", "tokens", "usd"]);
const CLAUDE_FAMILY: ReadonlySet<string> = new Set(["claude", "anthropic"]);
const UNKNOWN_PROVIDER = "unknown";
const STORE_UNAVAILABLE = "store_unavailable";
const DEFAULT_DEPS_LOADERS: Array<{
keys: Array<keyof CoreDeps>;
load: () => Promise<Partial<CoreDeps>>;
}> = [
{
keys: ["listAllocationsForApiKey", "getPool"],
load: async () => {
const m = await import("@/lib/db/quotaPools");
return { listAllocationsForApiKey: m.listAllocationsForApiKey, getPool: m.getPool };
},
},
{
keys: ["resolveConnectionProvider"],
load: async () => ({
resolveConnectionProvider: (await import("./connectionProvider")).resolveConnectionProvider,
}),
},
{
keys: ["resolvePlan"],
load: async () => {
const { resolvePlan } = await import("./planResolver");
return { resolvePlan: (connectionId, provider) => resolvePlan(connectionId, provider) };
},
},
{
keys: ["getQuotaStore"],
load: async () => ({ getQuotaStore: (await import("./QuotaStore")).getQuotaStore }),
},
{
// Same sources and process-wide refresh tracker as /v1/me/status, so the 60 s refresh
// floor per connection holds across both routes.
keys: ["resolveAccountQuotaEntries"],
load: async () => {
const [providers, limitsCache, limits] = await Promise.all([
import("@/lib/db/providers"),
import("@/lib/db/providerLimits"),
import("@/lib/usage/providerLimits"),
]);
return {
resolveAccountQuotaEntries: (metadata) =>
resolveAccountQuotaEntries(metadata, {
now: Date.now,
getProviderConnectionById: providers.getProviderConnectionById,
getProviderConnections: providers.getProviderConnections,
getProviderLimitsCache: limitsCache.getProviderLimitsCache,
fetchAndPersistProviderLimits: limits.fetchAndPersistProviderLimits,
quotaRefreshTracker: defaultQuotaRefreshTracker,
}),
};
},
},
{
keys: ["listEnabledSchedules"],
load: async () => ({
listEnabledSchedules: (await import("@/lib/db/quotaSchedules")).listEnabledSchedules,
}),
},
{
keys: ["listModelCapsForApiKey"],
load: async () => ({
listModelCapsForApiKey: (await import("@/lib/db/quotaModelCaps")).listModelCapsForApiKey,
}),
},
{
keys: ["listQuotaKeyModels"],
load: async () => {
const { listQuotaKeyModels } = await import("./quotaKeyModels");
return { listQuotaKeyModels: (allowedQuotas) => listQuotaKeyModels(allowedQuotas) };
},
},
{
keys: ["resolvePublicApiBaseUrl"],
load: async () => {
const { resolvePublicApiBaseUrl } = await import("@/server/origin/publicApiBaseUrl");
return { resolvePublicApiBaseUrl: () => resolvePublicApiBaseUrl() };
},
},
];
async function normalizeDeps(deps: QuotaSelfViewDeps): Promise<CoreDeps> {
if (!deps.secret) throw new Error("missing_pool_ref_secret");
const resolved: Partial<CoreDeps> = { now: Date.now };
for (const loader of DEFAULT_DEPS_LOADERS) {
if (loader.keys.some((key) => deps[key] === undefined)) {
Object.assign(resolved, await loader.load());
}
}
for (const [key, value] of Object.entries(deps)) {
if (value !== undefined) (resolved as Record<string, unknown>)[key] = value;
}
return resolved as CoreDeps;
}
/** Same provider, or both in the claude/anthropic family (as saturationSignals treats them). */
function sameProviderFamily(a: string, b: string): boolean {
return a === b || (CLAUDE_FAMILY.has(a) && CLAUDE_FAMILY.has(b));
}
/** The weight the gate applies: the key's own, or an equal split when all weights are 0. */
function gateEffectiveWeight(pool: QuotaPool, allocation: PoolAllocation): number {
const allocations = Array.isArray(pool.allocations) ? pool.allocations : [];
const totalWeight = allocations.reduce(
(sum, a) => sum + (Number.isFinite(a.weight) ? a.weight : 0),
0
);
if (totalWeight > 0) return allocation.weight;
return allocations.length > 0 ? 100 / allocations.length : 0;
}
async function resolvePoolContext(
input: QuotaSelfViewInput,
deps: CoreDeps,
poolId: string,
allocation: PoolAllocation
): Promise<SelfViewPoolContext | null> {
const pool = deps.getPool(poolId);
if (!pool) return null;
const connectionProvider = await deps.resolveConnectionProvider(pool.connectionId);
const plan = deps.resolvePlan(pool.connectionId, connectionProvider);
const provider = String(
connectionProvider !== UNKNOWN_PROVIDER ? connectionProvider : plan.provider
).toLowerCase();
if (!provider || provider === UNKNOWN_PROVIDER) return null;
if (!sameProviderFamily(provider, input.provider)) return null;
const connectionIds = pool.connectionIds?.length ? pool.connectionIds : [pool.connectionId];
const accountVisible =
hasSelfAccountQuotaScope(input.scopes) &&
isProviderShared(provider, input.sharedQuotaProviders);
return {
pool,
allocation,
provider,
ref: buildPoolRef(input.apiKeyId, pool.id, deps.secret),
plan,
effectiveWeight: gateEffectiveWeight(pool, allocation),
connectionIds,
accountVisible,
accountConnectionIds: accountConnectionIdsOf(
connectionIds,
accountVisible,
input.allowedConnections
),
};
}
/**
* The pool connections whose account data the key may see: none without account visibility,
* otherwise the pool's connections, limited to the key's allowed connections when it has any
* (an absent or empty list is no restriction, as in /v1/me/status).
*/
function accountConnectionIdsOf(
connectionIds: string[],
accountVisible: boolean,
allowedConnections: string[] | undefined
): string[] {
if (!accountVisible) return [];
const allowed = (allowedConnections ?? []).filter((id) => typeof id === "string" && id);
if (allowed.length === 0) return connectionIds;
const allowedSet = new Set(allowed);
return connectionIds.filter((id) => allowedSet.has(id));
}
/** The key's pools for the provider, in creation order (then name). */
async function resolvePoolContexts(
input: QuotaSelfViewInput,
deps: CoreDeps
): Promise<SelfViewPoolContext[]> {
const contexts: SelfViewPoolContext[] = [];
const seen = new Set<string>();
for (const { poolId, allocation } of deps.listAllocationsForApiKey(input.apiKeyId)) {
if (seen.has(poolId)) continue;
seen.add(poolId);
const context = await resolvePoolContext(input, deps, poolId, allocation);
if (context) contexts.push(context);
}
return contexts.sort(
(a, b) =>
compareText(a.pool.createdAt, b.pool.createdAt) || compareText(a.pool.name, b.pool.name)
);
}
function compareText(a: string | undefined, b: string | undefined): number {
const left = a ?? "";
const right = b ?? "";
return left < right ? -1 : left > right ? 1 : 0;
}
function isCountableDimension(dim: QuotaDimension): dim is CountableDimension {
return COUNTABLE_UNITS.has(dim.unit) && dim.limit > Number.EPSILON;
}
async function buildSharedDimension(
ctx: SelfViewPoolContext,
dim: CountableDimension,
store: ViewStore | null,
apiKeyId: string
): Promise<SelfQuotaSharedDimension> {
const limit = dim.limit * ctx.connectionIds.length;
const fairShare = (ctx.effectiveWeight / 100) * limit;
const key = { poolId: ctx.pool.id, unit: dim.unit, window: dim.window };
const consumed = await readViewStore(store ? () => store.peek(apiKeyId, key) : null);
const yourShare: SelfQuotaShare =
consumed === null
? {
fairShare,
consumed: null,
remaining: null,
status: "unavailable",
reason: STORE_UNAVAILABLE,
}
: { fairShare, consumed, remaining: Math.max(0, fairShare - consumed), status: "ok" };
const dimension: SelfQuotaSharedDimension = {
unit: dim.unit,
window: dim.window,
limit,
yourShare,
};
if (ctx.accountVisible) {
const used = await readViewStore(
store ? () => store.poolConsumedTotal(ctx.pool.id, key) : null
);
dimension.total =
used === null
? { used: null, status: "unavailable", reason: STORE_UNAVAILABLE }
: { used, status: "ok" };
}
return dimension;
}
/** Unknown policies are reported as "hard", the policy the fair-share engine applies to them. */
function gatePolicy(policy: Policy): Policy {
return PolicySchema.safeParse(policy).success ? policy : "hard";
}
function allocationCap(allocation: PoolAllocation): SelfQuotaPool["cap"] {
const { capUnit, capValue } = allocation;
if (capUnit === undefined || capValue === undefined || !Number.isFinite(capValue)) return null;
return { unit: capUnit, value: capValue };
}
/**
* Account entries for the pool connections the key may see (`accountConnectionIds`). Null when
* the key has no account visibility for the pool. An empty list when its allowed connections
* exclude every pool connection, or when the lookup fails (those accounts are reported
* unavailable, with a server-side warning: the error stays in the log, never in the view). Never called with an empty id list: resolveAccountQuotaEntries would read every active
* connection.
*/
async function resolvePoolAccountEntries(
ctx: SelfViewPoolContext,
input: QuotaSelfViewInput,
deps: CoreDeps
): Promise<AccountQuotaEntryLike[] | null> {
if (!ctx.accountVisible) return null;
const allowedConnections = ctx.accountConnectionIds.filter((id) => typeof id === "string" && id);
if (allowedConnections.length === 0) return [];
try {
return await deps.resolveAccountQuotaEntries({
allowedConnections,
sharedQuotaProviders: input.sharedQuotaProviders,
});
} catch (err) {
log.warn(
{ err: (err as Error)?.message, poolId: ctx.pool.id },
"self-service quota view: account lookup failed"
);
return [];
}
}
async function buildPoolView(
ctx: SelfViewPoolContext,
store: ViewStore | null,
input: QuotaSelfViewInput,
deps: CoreDeps
): Promise<SelfQuotaPool> {
const dimensions: SelfQuotaSharedDimension[] = [];
for (const dim of ctx.plan.dimensions ?? []) {
if (!isCountableDimension(dim)) continue;
dimensions.push(await buildSharedDimension(ctx, dim, store, input.apiKeyId));
}
return {
ref: ctx.ref,
name: ctx.pool.name,
provider: ctx.provider,
borrowMode: "saturation",
policy: gatePolicy(ctx.allocation.policy),
weight: ctx.effectiveWeight,
cap: allocationCap(ctx.allocation),
accountVisible: ctx.accountVisible,
dimensions,
accounts: buildSelfViewAccounts(
ctx,
await resolvePoolAccountEntries(ctx, input, deps),
deps.now()
),
};
}
/** The key's `qtSd/` model ids; a failed lookup is an empty list and a server-side warning. */
async function resolveAvailableModels(
input: QuotaSelfViewInput,
deps: CoreDeps
): Promise<string[]> {
try {
return await deps.listQuotaKeyModels(input.allowedQuotas);
} catch (err) {
log.warn(
{ err: (err as Error)?.message },
"self-service quota view: available models lookup failed"
);
return [];
}
}
/**
* Build the self-service quota view of `input.apiKeyId` for `input.provider`.
* Throws `missing_self_usage_scope` when the key lacks self:usage and `missing_pool_ref_secret`
* when `deps.secret` is empty.
*/
export async function buildQuotaSelfView(
input: QuotaSelfViewInput,
rawDeps: QuotaSelfViewDeps = {}
): Promise<SelfQuotaResponse> {
if (!hasSelfUsageScope(input.scopes)) throw new Error("missing_self_usage_scope");
const deps = await normalizeDeps(rawDeps);
const contexts = await resolvePoolContexts(input, deps);
// Loaded once per view: the blocks builder gets this same instance (or null).
const store = contexts.length > 0 ? await loadViewStore(deps.getQuotaStore) : null;
const pools: SelfQuotaPool[] = [];
for (const ctx of contexts) {
pools.push(await buildPoolView(ctx, store, input, deps));
}
return selfQuotaResponseSchema.parse({
provider: input.provider,
generatedAt: new Date(deps.now()).toISOString(),
pools,
availableModels: await resolveAvailableModels(input, deps),
expiresAt: input.expiresAt,
apiBaseUrl: deps.resolvePublicApiBaseUrl(),
blocks: await buildSelfViewBlocks(input.apiKeyId, contexts, {
...deps,
getQuotaStore: async () => store,
}),
});
}

View File

@@ -0,0 +1,179 @@
/**
* selfViewAccounts.ts — the `accounts[]` part of the self-service quota view.
*
* One neutral entry per connection of the pool, in the pool's own order: "Account 1",
* "Account 2", … No connection id, account e-mail, account name or provider account identifier
* is copied into the result; an entry reason outside the fixed set is replaced by
* "not_available".
*
* Each `percent` plan dimension (limit above Number.EPSILON) becomes one account dimension with
* the plan limit of ONE account. The key's own share of it is not attributed yet, so `yourShare`
* is always `unavailable` / `percent_attribution_unavailable` with null numbers.
*
* Account-level data (the `account` bar and `modelWindows`) comes only from the cached
* provider-limits entries the caller passes in (`entries`); `entries === null` means the key may
* not see account data, and those fields are omitted. They are also omitted for a pool
* connection outside `ctx.accountConnectionIds` (one the key may not use); its entry stays.
* A window the cache does not report is `unavailable` / `window_not_reported`, never 0. A stale cached reading, or one whose `resetAt`
* is already before `now` (the window reset since it was read), is `stale` with its numbers kept.
*
* Model windows are listed only for providers in PLAN_WINDOW_CACHE_KEYS, whose other cache keys
* are model or surface names. Other providers can key their cache by operator-chosen names or
* upstream key/limit ids, so none of their labels is copied: their `windows` is empty.
*/
import type {
SelfQuotaAccount,
SelfQuotaAccountDimension,
SelfQuotaBar,
SelfQuotaStatus,
} from "@/shared/schemas/selfQuota";
import type { QuotaDimension } from "./dimensions";
import type { AccountQuotaEntryLike, SelfViewPoolContext } from "./selfViewTypes";
type CachedWindow = NonNullable<AccountQuotaEntryLike["quotas"]>[string];
type PercentDimension = QuotaDimension & { unit: "percent" };
type ModelWindows = NonNullable<SelfQuotaAccount["modelWindows"]>;
const NOT_AVAILABLE = "not_available";
const WINDOW_NOT_REPORTED = "window_not_reported";
const PERCENT_ATTRIBUTION_UNAVAILABLE = "percent_attribution_unavailable";
/** Reasons resolveAccountQuotaEntries emits; anything else is reported as not_available. */
const KNOWN_ENTRY_REASONS: ReadonlySet<string> = new Set([
"connection_lookup_failed",
"not_supported",
"fetch_failed",
NOT_AVAILABLE,
]);
/** Provider-limits cache key of each plan window, per provider. */
const PLAN_WINDOW_CACHE_KEYS: Readonly<Record<string, Partial<Record<string, string>>>> = {
claude: { "5h": "session (5h)", weekly: "weekly (7d)" },
anthropic: { "5h": "session (5h)", weekly: "weekly (7d)" },
codex: { "5h": "session", weekly: "weekly" },
};
/** The entry's state: a fixed reason when it carries no readings, else ok/stale. */
type EntryState =
| { status: "unavailable"; reason: string }
| { status: SelfQuotaStatus; quotas: NonNullable<AccountQuotaEntryLike["quotas"]> };
function entryState(entry: AccountQuotaEntryLike | undefined): EntryState {
if (!entry) return { status: "unavailable", reason: NOT_AVAILABLE };
if (entry.available === false) {
const reason =
entry.reason && KNOWN_ENTRY_REASONS.has(entry.reason) ? entry.reason : NOT_AVAILABLE;
return { status: "unavailable", reason };
}
return { status: entry.stale ? "stale" : "ok", quotas: entry.quotas ?? {} };
}
function cachedWindow(
provider: string,
window: string,
quotas: NonNullable<AccountQuotaEntryLike["quotas"]>
): CachedWindow | null {
const key = PLAN_WINDOW_CACHE_KEYS[provider]?.[window];
if (!key || !Object.prototype.hasOwnProperty.call(quotas, key)) return null;
const reading = quotas[key];
return reading && Number.isFinite(reading.usedPercentage) ? reading : null;
}
/** "stale" when the reading's window already reset before `now`; an unparseable time is ignored. */
function readingStatus(
status: SelfQuotaStatus,
resetAt: string | null | undefined,
now: number
): SelfQuotaStatus {
if (status !== "ok" || !resetAt) return status;
const resetMs = Date.parse(resetAt);
return Number.isFinite(resetMs) && resetMs < now ? "stale" : status;
}
function accountBar(
provider: string,
dim: PercentDimension,
state: EntryState,
now: number
): SelfQuotaBar {
if (!("quotas" in state)) return { used: null, status: "unavailable", reason: state.reason };
const reading = cachedWindow(provider, dim.window, state.quotas);
if (!reading) return { used: null, status: "unavailable", reason: WINDOW_NOT_REPORTED };
return {
used: (reading.usedPercentage / 100) * dim.limit,
status: readingStatus(state.status, reading.resetAt, now),
resetAt: reading.resetAt ?? null,
};
}
function modelWindowsOf(provider: string, state: EntryState, now: number): ModelWindows {
if (!("quotas" in state)) return { status: "unavailable", reason: state.reason, windows: [] };
const mapping = Object.prototype.hasOwnProperty.call(PLAN_WINDOW_CACHE_KEYS, provider)
? PLAN_WINDOW_CACHE_KEYS[provider]
: null;
if (!mapping) return { status: state.status, windows: [] };
const planKeys = new Set(Object.values(mapping));
const windows: ModelWindows["windows"] = [];
let status = state.status;
for (const [label, reading] of Object.entries(state.quotas)) {
if (planKeys.has(label) || !reading || !Number.isFinite(reading.usedPercentage)) continue;
windows.push({ label, usedPercent: reading.usedPercentage, resetAt: reading.resetAt ?? null });
status = readingStatus(status, reading.resetAt, now);
}
return { status, windows };
}
function accountDimension(
ctx: SelfViewPoolContext,
dim: PercentDimension,
state: EntryState | null,
now: number
): SelfQuotaAccountDimension {
const dimension: SelfQuotaAccountDimension = {
unit: "percent",
window: dim.window,
limit: dim.limit,
yourShare: {
fairShare: (ctx.effectiveWeight / 100) * dim.limit,
consumed: null,
remaining: null,
status: "unavailable",
reason: PERCENT_ATTRIBUTION_UNAVAILABLE,
},
};
if (state) dimension.account = accountBar(ctx.provider, dim, state, now);
return dimension;
}
function isPercentDimension(dim: QuotaDimension): dim is PercentDimension {
return dim.unit === "percent" && dim.limit > Number.EPSILON;
}
/** entries = null when account data is hidden for this key; `now` is the view's clock (ms). */
export function buildSelfViewAccounts(
ctx: SelfViewPoolContext,
entries: AccountQuotaEntryLike[] | null,
now: number
): SelfQuotaAccount[] {
const visibleConnections = new Set(ctx.accountConnectionIds);
const byConnection = new Map<string, AccountQuotaEntryLike>();
for (const entry of entries ?? []) {
if (visibleConnections.has(entry.connectionId) && !byConnection.has(entry.connectionId)) {
byConnection.set(entry.connectionId, entry);
}
}
const percentDimensions = (ctx.plan.dimensions ?? []).filter(isPercentDimension);
return ctx.connectionIds.map((connectionId, index) => {
const visible = entries !== null && visibleConnections.has(connectionId);
const state = visible ? entryState(byConnection.get(connectionId)) : null;
const account: SelfQuotaAccount = {
slot: index + 1,
label: `Account ${index + 1}`,
dimensions: percentDimensions.map((dim) => accountDimension(ctx, dim, state, now)),
};
if (state) account.modelWindows = modelWindowsOf(ctx.provider, state, now);
return account;
});
}

View File

@@ -0,0 +1,159 @@
/**
* selfViewBlocks.ts — the `blocks` part of the self-service quota view: what the quota gate
* (enforce.ts) would currently hold the key to, per pool, besides the fair-share buckets.
*
* Schedules: the pool's enabled schedules resolved at `now` exactly as the gate resolves them.
* A pool without schedules (or with only blackout rows, none active) gets no entry. A closed
* window reports why and, when an allow window is configured, the seconds until it reopens. An
* open window reports its reserve floors and, when it carries a budget, whether OmniRoute's own
* consumption in the schedule bucket (`scheduleBucketPoolId`) has reached it.
*
* Model caps: the key's own per-model caps in the pool (placeholders at or below
* Number.EPSILON are skipped, as the gate skips them), with the key's consumption in the
* per-model bucket the gate reads ("<poolId>:model:<model>", hourly).
*
* A store that fails to load and a failed or non-finite store read are `null` (never zero, never
* "not reached"; selfViewStore.ts). Inside a view build the store comes from selfView.ts, which
* loads it once for both builders. A failed schedule or cap lookup leaves that pool without
* those entries, which is also what the gate does with it (listSchedules and the gate's cap read
* both fail open); the error is logged here.
*
* Every entry names its pool only by the opaque `ref`. The schedule label (text the pool
* administrator wrote, shown to key holders as written) and the cap's model name are the only
* free text copied.
*/
import { createLogger } from "@/shared/utils/logger";
import type { SelfQuotaBlocks } from "@/shared/schemas/selfQuota";
import type { ModelCap } from "@/lib/db/quotaModelCaps";
import { resolveActiveSchedule, scheduleBucketPoolId, type QuotaSchedule } from "./schedules";
import { loadViewStore, readViewStore, type ViewStore } from "./selfViewStore";
import type { SelfViewPoolContext } from "./selfViewTypes";
type ScheduleBlock = SelfQuotaBlocks["schedules"][number];
type ModelCapBlock = SelfQuotaBlocks["modelCaps"][number];
interface SelfViewBlocksDeps {
now: () => number;
listEnabledSchedules: (poolId: string) => QuotaSchedule[];
listModelCapsForApiKey: (poolId: string, apiKeyId: string) => ModelCap[];
/** May answer null: selfView.ts hands over the store it already loaded, or null if it failed. */
getQuotaStore: () => Promise<ViewStore | null>;
}
const log = createLogger("quota:self-view");
/** A lookup's rows, or [] (with a server-side warning) when it throws. */
function readRows<T>(ctx: SelfViewPoolContext, what: string, read: () => T[]): T[] {
try {
const rows = read();
return Array.isArray(rows) ? rows : [];
} catch (err) {
log.warn(
{ err: (err as Error)?.message, poolId: ctx.pool.id },
`self-service quota view: ${what} lookup failed`
);
return [];
}
}
async function scheduleBudget(
ctx: SelfViewPoolContext,
schedule: QuotaSchedule,
store: ViewStore | null
): Promise<ScheduleBlock["budget"]> {
const { budgetValue, budgetUnit, budgetWindow } = schedule;
if (budgetValue === undefined || budgetUnit === undefined) return null;
const key = {
poolId: scheduleBucketPoolId(ctx.pool.id, schedule.id),
unit: budgetUnit,
window: budgetWindow,
};
const consumed = await readViewStore(
store ? () => store.poolConsumedTotal(ctx.pool.id, key) : null
);
return {
unit: budgetUnit,
window: budgetWindow,
exhausted: consumed === null ? null : consumed >= budgetValue,
};
}
async function scheduleBlock(
ctx: SelfViewPoolContext,
deps: SelfViewBlocksDeps,
store: ViewStore | null
): Promise<ScheduleBlock | null> {
const schedules = readRows(ctx, "schedule", () => deps.listEnabledSchedules(ctx.pool.id));
const verdict = resolveActiveSchedule(schedules, deps.now());
if (verdict.kind === "unscheduled") return null;
if (verdict.kind === "closed") {
return {
pool: ctx.ref,
state: "closed",
reason: verdict.reason,
label: verdict.schedule?.label ?? null,
retryAfterSeconds: verdict.retryAfterSeconds ?? null,
reserves: [],
budget: null,
};
}
const { schedule } = verdict;
return {
pool: ctx.ref,
state: "open",
reason: null,
label: schedule.label ?? null,
retryAfterSeconds: null,
reserves: schedule.reserves.map(({ window, percent }) => ({ window, percent })),
budget: await scheduleBudget(ctx, schedule, store),
};
}
async function modelCapBlocks(
apiKeyId: string,
ctx: SelfViewPoolContext,
deps: SelfViewBlocksDeps,
store: ViewStore | null
): Promise<ModelCapBlock[]> {
const caps = readRows(ctx, "model cap", () => deps.listModelCapsForApiKey(ctx.pool.id, apiKeyId));
const blocks: ModelCapBlock[] = [];
for (const cap of caps) {
// Only this key's real caps: placeholders are not enforced by the gate.
if (cap.apiKeyId !== apiKeyId) continue;
if (!Number.isFinite(cap.capValue) || cap.capValue <= Number.EPSILON) continue;
const key = {
poolId: `${ctx.pool.id}:model:${cap.model}`,
unit: cap.capUnit,
window: "hourly" as const,
};
const consumed = await readViewStore(store ? () => store.peek(apiKeyId, key) : null);
blocks.push({
pool: ctx.ref,
model: cap.model,
unit: cap.capUnit,
window: "hourly",
cap: cap.capValue,
consumed,
reached: consumed === null ? null : consumed >= cap.capValue,
});
}
return blocks;
}
/** The schedule windows and per-model caps the key is under, pool by pool, in pool order. */
export async function buildSelfViewBlocks(
apiKeyId: string,
pools: SelfViewPoolContext[],
deps: SelfViewBlocksDeps
): Promise<SelfQuotaBlocks> {
const blocks: SelfQuotaBlocks = { schedules: [], modelCaps: [] };
if (pools.length === 0) return blocks;
const store = await loadViewStore(deps.getQuotaStore);
for (const ctx of pools) {
const schedule = await scheduleBlock(ctx, deps, store);
if (schedule) blocks.schedules.push(schedule);
blocks.modelCaps.push(...(await modelCapBlocks(apiKeyId, ctx, deps, store)));
}
return blocks;
}

View File

@@ -0,0 +1,41 @@
/**
* selfViewStore.ts — quota-store access shared by the self-service quota view builders
* (selfView.ts and selfViewBlocks.ts). A leaf module: it imports neither builder.
*
* The one rule both builders rely on: a store that fails to load, a read that throws and a read
* that returns a non-finite number all become `null`, never zero.
*/
import { createLogger } from "@/shared/utils/logger";
import type { QuotaStore } from "./types";
/** The two read-only store methods the view uses. */
export type ViewStore = Pick<QuotaStore, "peek" | "poolConsumedTotal">;
const log = createLogger("quota:self-view");
/**
* The quota store, or null when it cannot be loaded (one server-side warning) or when the loader
* already answers null (a store the caller loaded before and found unavailable).
*/
export async function loadViewStore(
getQuotaStore: () => Promise<ViewStore | null>
): Promise<ViewStore | null> {
try {
return (await getQuotaStore()) ?? null;
} catch (err) {
log.warn({ err: (err as Error)?.message }, "self-service quota view: quota store unavailable");
return null;
}
}
/** A store read as a number, or null when the store is missing, throws or returns non-finite. */
export async function readViewStore(read: (() => Promise<number>) | null): Promise<number | null> {
if (!read) return null;
try {
const value = await read();
return Number.isFinite(value) ? value : null;
} catch {
return null;
}
}

View File

@@ -0,0 +1,78 @@
/**
* Types shared by the self-service quota view builders (selfView.ts and its sibling modules).
*
* Kept in a types-only module so the builders can share them without importing each other.
*/
import type { PoolAllocation, QuotaPool } from "@/lib/db/quotaPools";
import type { ModelCap } from "@/lib/db/quotaModelCaps";
import type { ProviderPlan } from "./dimensions";
import type { QuotaSchedule } from "./schedules";
import type { QuotaStore } from "./types";
/** One entry of resolveAccountQuotaEntries, reduced to the fields the view reads. */
export interface AccountQuotaEntryLike {
connectionId: string;
available?: false;
reason?: string;
stale?: boolean;
quotas?: Record<
string,
{ usedPercentage: number; remainingPercentage: number; resetAt: string | null }
>;
}
export interface QuotaSelfViewInput {
apiKeyId: string;
scopes: string[];
allowedQuotas: string[];
expiresAt: string | null;
sharedQuotaProviders: string[] | null;
/**
* The connections the key may use, read as /v1/me/status reads them: an absent or empty list
* is no restriction, otherwise only these ids. Account data of other connections is not shown.
*/
allowedConnections?: string[];
/** Lowercased provider id from the request path. */
provider: string;
}
/**
* Dependencies of buildQuotaSelfView. Every data source is injectable; omitted ones are loaded
* with dynamic import(). `secret` (the server secret used for pool refs) has no default: the
* caller passes it, so the builder never reads the environment.
*/
export interface QuotaSelfViewDeps {
now?: () => number;
secret?: string;
listAllocationsForApiKey?: (
apiKeyId: string
) => Array<{ poolId: string; allocation: PoolAllocation }>;
getPool?: (poolId: string) => QuotaPool | null;
resolveConnectionProvider?: (connectionId: string) => Promise<string>;
resolvePlan?: (connectionId: string, provider: string) => ProviderPlan;
getQuotaStore?: () => Promise<Pick<QuotaStore, "peek" | "poolConsumedTotal">>;
resolveAccountQuotaEntries?: (m: {
allowedConnections: string[];
sharedQuotaProviders: string[] | null;
}) => Promise<AccountQuotaEntryLike[]>;
listEnabledSchedules?: (poolId: string) => QuotaSchedule[];
listModelCapsForApiKey?: (poolId: string, apiKeyId: string) => ModelCap[];
listQuotaKeyModels?: (allowedQuotas: string[]) => Promise<string[]>;
resolvePublicApiBaseUrl?: () => string | null;
}
/** A pool the key is allocated in, resolved for one provider. Internal ids stay here. */
export interface SelfViewPoolContext {
pool: QuotaPool;
allocation: PoolAllocation;
provider: string;
ref: string;
plan: ProviderPlan;
/** The weight the quota gate applies (equal split when every weight in the pool is 0). */
effectiveWeight: number;
connectionIds: string[];
accountVisible: boolean;
/** The pool connections whose account data this key may see (empty when none). */
accountConnectionIds: string[];
}

View File

@@ -166,7 +166,10 @@ async function listReachableConnections(
return connections;
}
function isProviderShared(provider: string, sharedQuotaProviders: string[] | null | undefined) {
export function isProviderShared(
provider: string,
sharedQuotaProviders: string[] | null | undefined
) {
if (sharedQuotaProviders === null || sharedQuotaProviders === undefined) return true;
return sharedQuotaProviders.includes(provider);
}

View File

@@ -0,0 +1,327 @@
/**
* GET /v1/me/usage — usage and cost series of the calling API key over a closed window.
*
* Every query reads the source of `buildApiKeyOwnedSource` (rows whose `api_key_id` is the
* calling key's id, nothing else). Days are UTC days, as SQLite's DATE() reads the stored
* ISO-8601 UTC timestamps. The window runs from `now - range` to `now`, both from the injected
* clock, so a row stamped after `now` is not counted. Five grouped queries run per build;
* apiKeySelfServiceUsageCache.ts reuses a built series for 60 seconds.
*
* Two costs are reported side by side, both summed row by row and rounded by `roundCost`:
* - `costUsd`: the billed cost, as the usage analytics show it by default. Flat-rate
* subscription providers (see flatRateProviders.ts, e.g. the Claude Code plan) count $0, so
* a pool on such an account shows no billed cost.
* - `listPriceUsd`: the same usage priced at list price, subscriptions included.
* A row whose model has no price row counts its stored cost (reported by the provider or
* calculated when recorded). Only a row with neither counts 0, with no marker.
*
* Provider and model are returned as recorded for the key's own requests (a combo request whose
* every target was refused carries the routing label as provider and the client's model
* string). `retentionDays` is the operator's raw usage-history retention setting
* (`retention.usageHistory`). The reused queries also return `uniqueAccounts`, `uniqueApiKeys`,
* `serviceTier` and the raw cost inputs; they are read here and never copied into the result.
* No SQL lives in this module.
*/
import { getUserDatabaseSettings } from "@/lib/db/databaseSettings";
import {
getDailyCostRows,
getDailyUsage,
getModelUsageRows,
getProviderUsageRows,
getUsageSummary,
type DailyCostRow,
type DailyUsageRow,
type ModelUsageRow,
type ProviderUsageRow,
type UsageSummaryRow,
} from "@/lib/db/usageAnalytics";
import { buildApiKeyOwnedSource } from "@/lib/db/usageAnalytics/apiKeyScope";
import { hasSelfUsageScope } from "@/shared/constants/selfServiceScopes";
import type { SelfUsageRange, SelfUsageResponse } from "@/shared/schemas/selfUsage";
import { toNumber } from "@/shared/utils/numeric";
import {
computeUsageRowCost,
roundCost,
toStringValue,
type PricingResolutionContext,
} from "./analyticsPricing";
import { computeCostFromPricing, normalizeModelName } from "./costCalculator";
const DAY_MS = 86_400_000;
const RANGE_DAYS: Record<SelfUsageRange, number> = { "1d": 1, "7d": 7, "30d": 30, "90d": 90 };
/** Fallback for a missing or invalid setting only. The stored setting is what applies. */
const DEFAULT_RETENTION_DAYS = 30;
const BY_MODEL_LIMIT = 50;
const MISSING_SCOPE_ERROR = "missing_self_usage_scope";
type PriceRow = (row: object, flatRateAsZero: boolean) => number;
type PricingByProvider = Record<string, Record<string, Record<string, unknown>>>;
export interface SelfServiceUsageDeps {
now?: () => number;
retentionDays?: () => number;
queries?: {
summary: typeof getUsageSummary;
daily: typeof getDailyUsage;
dailyCost: typeof getDailyCostRows;
models: typeof getModelUsageRows;
providers: typeof getProviderUsageRows;
};
/** Cost of one query row; the default wraps computeUsageRowCost with the stored pricing. */
priceRow?: PriceRow;
}
const DEFAULT_QUERIES: NonNullable<SelfServiceUsageDeps["queries"]> = {
summary: getUsageSummary,
daily: getDailyUsage,
dailyCost: getDailyCostRows,
models: getModelUsageRows,
providers: getProviderUsageRows,
};
interface Money {
costUsd: number;
listPriceUsd: number;
}
type Totals = SelfUsageResponse["summary"];
type DailyByModel = SelfUsageResponse["dailyByModel"][number];
const zeroMoney = (): Money => ({ costUsd: 0, listPriceUsd: 0 });
function addMoney(target: Money, add: Money): Money {
target.costUsd += add.costUsd;
target.listPriceUsd += add.listPriceUsd;
return target;
}
function roundMoney(money: Money | undefined): Money {
return {
costUsd: roundCost(money?.costUsd ?? 0),
listPriceUsd: roundCost(money?.listPriceUsd ?? 0),
};
}
function priceBoth(priceRow: PriceRow, row: object): Money {
return { costUsd: priceRow(row, true), listPriceUsd: priceRow(row, false) };
}
function percent(part: number, total: number): number {
return total > 0 ? Number(((part / total) * 100).toFixed(2)) : 0;
}
function readRetentionDays(): number {
const days = Number(getUserDatabaseSettings().retention?.usageHistory ?? DEFAULT_RETENTION_DAYS);
return Number.isFinite(days) && days > 0 ? days : DEFAULT_RETENTION_DAYS;
}
function resolveWindow(range: SelfUsageRange, nowMs: number, retentionDays: number) {
const days = RANGE_DAYS[range];
const from = new Date(nowMs - days * DAY_MS).toISOString();
const to = new Date(nowMs).toISOString();
return {
sinceIso: from,
untilIso: to,
rawCutoffDate: new Date(nowMs - retentionDays * DAY_MS).toISOString().slice(0, 10),
coverage: { from, to, retentionDays, truncatedByRetention: days > retentionDays },
};
}
/** Lower-cases provider and model keys of the stored pricing, as the analytics route does. */
function lowerCasePricing(raw: unknown): PricingByProvider {
const pricing: PricingByProvider = {};
for (const [provider, models] of Object.entries((raw ?? {}) as PricingByProvider)) {
const lowered: Record<string, Record<string, unknown>> = {};
for (const [model, row] of Object.entries(models ?? {})) lowered[model.toLowerCase()] = row;
pricing[provider.toLowerCase()] = lowered;
}
return pricing;
}
async function loadPricer(): Promise<PriceRow> {
const { getPricing } = await import("@/lib/db/settings");
const { PROVIDER_ID_TO_ALIAS } = await import("@omniroute/open-sse/config/providerModels");
const pricingByProvider = lowerCasePricing(await getPricing());
const context: PricingResolutionContext = {
cache: new Map(),
reverseAlias: { ...PROVIDER_ID_TO_ALIAS },
};
return (row, flatRateAsZero) =>
computeUsageRowCost(
row,
pricingByProvider,
PROVIDER_ID_TO_ALIAS,
normalizeModelName,
computeCostFromPricing,
flatRateAsZero,
context
);
}
/** Prices the day x provider x model rows once and spreads the cost over every series. */
function priceCostRows(rows: DailyCostRow[], priceRow: PriceRow) {
const total = zeroMoney();
const byDate = new Map<string, Money>();
const byProvider = new Map<string, Money>();
const byDateModel = new Map<string, DailyByModel>();
for (const row of rows) {
const date = toStringValue(row.date);
if (!date) continue;
const money = priceBoth(priceRow, row);
addMoney(total, money);
byDate.set(date, addMoney(byDate.get(date) ?? zeroMoney(), money));
const provider = toStringValue(row.provider);
byProvider.set(provider, addMoney(byProvider.get(provider) ?? zeroMoney(), money));
const model = normalizeModelName(toStringValue(row.model));
const key = JSON.stringify([date, model]);
const entry = byDateModel.get(key) ?? { date, model, totalTokens: 0, ...zeroMoney() };
entry.totalTokens += toNumber(row.promptTokens) + toNumber(row.completionTokens);
byDateModel.set(key, addMoney(entry, money) as DailyByModel);
}
const dailyByModel = [...byDateModel.values()].map((entry) => ({
...entry,
...roundMoney(entry),
}));
return { total, byDate, byProvider, dailyByModel };
}
function buildSummary(row: UsageSummaryRow, total: Money): Totals {
const requests = toNumber(row?.totalRequests);
const successfulRequests = toNumber(row?.successfulRequests);
return {
requests,
promptTokens: toNumber(row?.promptTokens),
completionTokens: toNumber(row?.completionTokens),
totalTokens: toNumber(row?.totalTokens),
...roundMoney(total),
successfulRequests,
successRatePct: percent(successfulRequests, requests),
uniqueModels: toNumber(row?.uniqueModels),
avgLatencyMs: Math.round(toNumber(row?.avgLatencyMs)),
firstRequest: toStringValue(row?.firstRequest) || null,
lastRequest: toStringValue(row?.lastRequest) || null,
};
}
function buildDaily(rows: DailyUsageRow[], costByDate: Map<string, Money>) {
return rows.map((row) => ({
date: toStringValue(row.date),
requests: toNumber(row.requests),
promptTokens: toNumber(row.promptTokens),
completionTokens: toNumber(row.completionTokens),
totalTokens: toNumber(row.totalTokens),
...roundMoney(costByDate.get(toStringValue(row.date))),
}));
}
/** Merges the per-day model rows by provider and model name: the 50 pairs with most requests. */
function buildByModel(rows: ModelUsageRow[], priceRow: PriceRow) {
type Entry = Money & {
model: string;
provider: string;
requests: number;
promptTokens: number;
completionTokens: number;
totalTokens: number;
latencyWeighted: number;
successfulRequests: number;
lastUsed: string;
};
const merged = new Map<string, Entry>();
for (const row of rows) {
const model = normalizeModelName(toStringValue(row.model));
const provider = toStringValue(row.provider);
const key = JSON.stringify([provider, model]);
const entry: Entry = merged.get(key) ?? {
model,
provider,
requests: 0,
promptTokens: 0,
completionTokens: 0,
totalTokens: 0,
latencyWeighted: 0,
successfulRequests: 0,
lastUsed: "",
...zeroMoney(),
};
const requests = toNumber(row.requests);
entry.requests += requests;
entry.promptTokens += toNumber(row.promptTokens);
entry.completionTokens += toNumber(row.completionTokens);
entry.totalTokens += toNumber(row.totalTokens);
entry.latencyWeighted += toNumber(row.avgLatencyMs) * requests;
entry.successfulRequests += toNumber(row.successfulRequests);
const lastUsed = toStringValue(row.lastUsed);
if (lastUsed > entry.lastUsed) entry.lastUsed = lastUsed;
merged.set(key, addMoney(entry, priceBoth(priceRow, row)) as Entry);
}
return [...merged.values()]
.sort((left, right) => right.requests - left.requests)
.slice(0, BY_MODEL_LIMIT)
.map((entry) => ({
model: entry.model,
provider: entry.provider,
requests: entry.requests,
promptTokens: entry.promptTokens,
completionTokens: entry.completionTokens,
totalTokens: entry.totalTokens,
...roundMoney(entry),
avgLatencyMs: entry.requests > 0 ? Math.round(entry.latencyWeighted / entry.requests) : 0,
successRatePct: percent(entry.successfulRequests, entry.requests),
lastUsed: entry.lastUsed || null,
}));
}
function buildByProvider(rows: ProviderUsageRow[], costByProvider: Map<string, Money>) {
return rows.map((row) => {
const provider = toStringValue(row.provider);
const requests = toNumber(row.requests);
return {
provider,
requests,
promptTokens: toNumber(row.promptTokens),
completionTokens: toNumber(row.completionTokens),
totalTokens: toNumber(row.totalTokens),
...roundMoney(costByProvider.get(provider)),
avgLatencyMs: Math.round(toNumber(row.avgLatencyMs)),
successRatePct: percent(toNumber(row.successfulRequests), requests),
};
});
}
/**
* Builds the usage view of one key. Throws `missing_self_usage_scope` when the key lacks
* `self:usage`. The caller parses the result with `selfUsageResponseSchema`.
*/
export async function buildApiKeySelfServiceUsage(
key: { id: string; scopes: string[] },
range: SelfUsageRange,
deps: SelfServiceUsageDeps = {}
): Promise<SelfUsageResponse> {
if (!hasSelfUsageScope(key.scopes)) throw new Error(MISSING_SCOPE_ERROR);
const nowMs = (deps.now ?? Date.now)();
const window = resolveWindow(range, nowMs, (deps.retentionDays ?? readRetentionDays)());
const { unifiedSource, unifiedParams } = buildApiKeyOwnedSource({
apiKeyId: key.id,
sinceIso: window.sinceIso,
untilIso: window.untilIso,
rawCutoffDate: window.rawCutoffDate,
});
const queries = deps.queries ?? DEFAULT_QUERIES;
const priceRow = deps.priceRow ?? (await loadPricer());
const costs = priceCostRows(queries.dailyCost(unifiedSource, unifiedParams), priceRow);
return {
range,
generatedAt: window.coverage.to,
coverage: window.coverage,
summary: buildSummary(queries.summary(unifiedSource, unifiedParams), costs.total),
daily: buildDaily(queries.daily(unifiedSource, unifiedParams), costs.byDate),
dailyByModel: costs.dailyByModel,
byModel: buildByModel(queries.models(unifiedSource, unifiedParams), priceRow),
byProvider: buildByProvider(queries.providers(unifiedSource, unifiedParams), costs.byProvider),
};
}

View File

@@ -0,0 +1,100 @@
/**
* GET /v1/me/usage — short in-process reuse of a key's built usage series.
*
* Building a series runs five grouped aggregates over the calling key's rows on the synchronous
* database driver, so a key holder reloading a page would otherwise block the event loop on
* every reload. A built series is reused for 60 seconds per (key id, range).
*
* - The entry key is the calling key's id and the validated range, nothing else from the request.
* One key's series is never served to another key.
* - The scope check runs before the lookup, and the route's authentication gate runs before this
* function, so a key that loses `self:usage` or is revoked is refused on its next request.
* - Concurrent requests for the same key and range share one build. A failed build is not kept:
* every request waiting on it gets the same failure, and the next request builds again.
* - The reused object is exactly what the build returned, `generatedAt` included, so a client can
* see the age of the data.
* - Memory stays bounded: a series can take about a megabyte (50 models over 90 days), so at most
* 64 are kept, and storing a new one first drops every entry that has already expired.
*/
import { boundedMap } from "@/lib/quota/boundedMap";
import { hasSelfUsageScope } from "@/shared/constants/selfServiceScopes";
import type { SelfUsageRange, SelfUsageResponse } from "@/shared/schemas/selfUsage";
import { buildApiKeySelfServiceUsage, type SelfServiceUsageDeps } from "./apiKeySelfServiceUsage";
const USAGE_CACHE_TTL_MS = 60_000;
const USAGE_CACHE_MAX_ENTRIES = 64;
const MISSING_SCOPE_ERROR = "missing_self_usage_scope";
export interface SelfServiceUsageCache {
/**
* Returns the series cached under `key` until `ttlMs` after it was built, or builds and caches
* it. Concurrent callers share one build; a failed one is dropped.
*/
memoize(
key: string,
nowMs: number,
build: () => Promise<SelfUsageResponse>
): Promise<SelfUsageResponse>;
/** Entries currently held, expired ones not yet dropped included (diagnostics). */
readonly size: number;
}
/**
* Bounded (`ttl` policy of boundedMap): past `maxEntries`, expired then oldest entries go. Each
* store also drops every entry already expired at that moment, so stale series do not wait for
* a read of the same key or for the cap.
*/
export function createSelfServiceUsageCache({
ttlMs = USAGE_CACHE_TTL_MS,
maxEntries = USAGE_CACHE_MAX_ENTRIES,
}: { ttlMs?: number; maxEntries?: number } = {}): SelfServiceUsageCache {
const entries = boundedMap<Promise<SelfUsageResponse>>(
"self-service:usage",
maxEntries,
"ttl",
ttlMs
);
/** boundedMap.get drops an entry that has expired at `nowMs`; keys() lists expired ones too. */
function dropExpired(nowMs: number): void {
for (const stored of [...entries.keys()]) entries.get(stored, nowMs);
}
return {
memoize(key, nowMs, build) {
const hit = entries.get(key, nowMs);
if (hit) return hit;
dropExpired(nowMs);
const value = (async () => build())();
entries.set(key, value, nowMs);
value.catch(() => {
if (entries.get(key, nowMs) === value) entries.delete(key);
});
return value;
},
get size() {
return entries.size;
},
};
}
const defaultSelfServiceUsageCache = createSelfServiceUsageCache();
export type SelfServiceUsageCachedDeps = SelfServiceUsageDeps & { cache?: SelfServiceUsageCache };
/**
* The usage series of one key, reused for 60 seconds per (key id, range). Throws
* `missing_self_usage_scope`, before any lookup, when the key lacks `self:usage`.
*/
export async function getApiKeySelfServiceUsage(
key: { id: string; scopes: string[] },
range: SelfUsageRange,
deps: SelfServiceUsageCachedDeps = {}
): Promise<SelfUsageResponse> {
if (!hasSelfUsageScope(key.scopes)) throw new Error(MISSING_SCOPE_ERROR);
const { cache = defaultSelfServiceUsageCache, ...buildDeps } = deps;
const nowMs = (deps.now ?? Date.now)();
return cache.memoize(JSON.stringify([key.id, range]), nowMs, () =>
buildApiKeySelfServiceUsage(key, range, { ...buildDeps, now: () => nowMs })
);
}

View File

@@ -0,0 +1,72 @@
/**
* The origin of the inference API as key holders reach it, reported by the self-service quota
* endpoint (GET /v1/me/quota/{provider}).
*
* Order: OMNIROUTE_PUBLIC_API_BASE_URL, then OMNIROUTE_PUBLIC_BASE_URL, then null. Never the
* request's own origin, and never NEXT_PUBLIC_BASE_URL: its documented default
* (http://localhost:20128) would be handed out as a public URL. A set but invalid
* OMNIROUTE_PUBLIC_API_BASE_URL yields null rather than the dashboard origin, so an operator who
* configured a separate API origin is never silently given the other one; that case is logged
* once per process (the variable name only, never its value). Values are reduced to scheme, host
* and port (normalizeOrigin: http/https only, lowercased, credentials dropped).
*/
import { createLogger } from "@/shared/utils/logger";
import { normalizeOrigin } from "./publicOrigin";
/** The only two variables this resolver reads (a whole NodeJS.ProcessEnv fits too). */
interface PublicApiBaseUrlEnv {
OMNIROUTE_PUBLIC_API_BASE_URL?: string;
OMNIROUTE_PUBLIC_BASE_URL?: string;
}
/** Whether the invalid-API-origin warning was already logged, and where it goes. */
interface InvalidApiOriginNotice {
warned: boolean;
log: { warn: (fields: Record<string, unknown>, message: string) => void };
}
/** Process-wide: the warning is logged at most once, not on every request. */
const PROCESS_NOTICE: InvalidApiOriginNotice = {
warned: false,
log: createLogger("public-api-base-url"),
};
function warnInvalidApiOrigin(notice: InvalidApiOriginNotice): void {
if (notice.warned) return;
notice.warned = true;
notice.log.warn(
{ variable: "OMNIROUTE_PUBLIC_API_BASE_URL" },
"OMNIROUTE_PUBLIC_API_BASE_URL is set but is not an http(s) origin; no public API base URL is reported"
);
}
function originOrNull(value: string): string | null {
try {
return normalizeOrigin(value);
} catch {
return null;
}
}
/**
* Resolve the public API origin from `env`. The default reads exactly the two variables above
* from process.env, so callers (and tests) can pass their own values instead. `notice` holds the
* warn-once state for an invalid API origin (process-wide by default).
*/
export function resolvePublicApiBaseUrl(
env: PublicApiBaseUrlEnv = {
OMNIROUTE_PUBLIC_API_BASE_URL: process.env.OMNIROUTE_PUBLIC_API_BASE_URL,
OMNIROUTE_PUBLIC_BASE_URL: process.env.OMNIROUTE_PUBLIC_BASE_URL,
},
notice: InvalidApiOriginNotice = PROCESS_NOTICE
): string | null {
const apiValue = env.OMNIROUTE_PUBLIC_API_BASE_URL?.trim();
if (apiValue) {
const apiOrigin = originOrNull(apiValue);
if (apiOrigin === null) warnInvalidApiOrigin(notice);
return apiOrigin;
}
const publicOrigin = env.OMNIROUTE_PUBLIC_BASE_URL?.trim();
return publicOrigin ? originOrNull(publicOrigin) : null;
}

View File

@@ -0,0 +1,122 @@
/**
* Authentication gate of the self-service routes (`/v1/me/quota/{provider}` and `/v1/me/usage`).
* Checks run in a fixed order: feature flag, header credentials, key validation, key metadata,
* scope. Callers can replace only the key store the gate reads; the checks themselves are not
* injectable.
*
* There is no per-address attempt limit here: behind a reverse proxy callers can share one
* address (it depends on whether forwarded client addresses are trusted), so a lockout could let
* any client deny the API to every key holder.
*/
import { buildErrorBody } from "@omniroute/open-sse/utils/error";
import { hasSelfUsageScope } from "@/shared/constants/selfServiceScopes";
import { isFeatureFlagEnabled } from "@/shared/utils/featureFlags";
const SELF_SERVICE_FLAG = "QUOTA_SELF_PANEL";
const INVALID_KEY_MESSAGE = "Valid API key required";
export interface SelfServiceKey {
id: string;
name: string;
scopes: string[];
allowedQuotas: string[];
/** As stored on the key: an empty list means no restriction. */
allowedConnections: string[];
expiresAt: string | null;
}
// The optional `undefined` members let `if (!auth.ok) return auth.response;` narrow under the
// repository's `strict: false` compiler settings.
export type SelfServiceAuth =
| { ok: true; key: SelfServiceKey; response?: undefined }
| { ok: false; response: Response; key?: undefined };
type KeyMetadata = {
id: string;
name: string;
scopes?: string[] | null;
allowedQuotas?: string[] | null;
allowedConnections?: string[] | null;
expiresAt?: string | null;
};
export type SelfServiceKeyStore = Pick<
typeof import("@/lib/db/apiKeys"),
"validateApiKey" | "getApiKeyMetadata"
>;
export function selfServiceJson(
body: unknown,
status = 200,
headers: Record<string, string> = {}
): Response {
return Response.json(body, { status, headers: { ...headers, "Cache-Control": "no-store" } });
}
export function selfServiceError(
status: number,
message: string,
headers: Record<string, string> = {}
): Response {
return selfServiceJson(buildErrorBody(status, message), status, headers);
}
function refuse(status: number, message: string): SelfServiceAuth {
return { ok: false, response: selfServiceError(status, message) };
}
/** Header credentials in the order they are tried: Bearer token, then `x-api-key`. */
function readCredentialCandidates(request: Request): string[] {
const authorization = request.headers.get("Authorization") ?? "";
const bearer = authorization.match(/^Bearer\s+(.+)$/i)?.[1]?.trim();
const xApiKey = request.headers.get("x-api-key")?.trim();
return [...new Set([bearer, xApiKey].filter((value): value is string => Boolean(value)))];
}
/**
* The first candidate the key store accepts, or null when none validates. The key row is read
* on every call (`bypassCache`): the validation cache would keep answering "valid" for up to a
* minute after a key's expiry, and this gate has no other expiry check.
*/
async function findValidCandidate(store: SelfServiceKeyStore, candidates: string[]) {
for (const candidate of candidates) {
if (await store.validateApiKey(candidate, { bypassCache: true })) return candidate;
}
return null;
}
function toSelfServiceKey(metadata: KeyMetadata): SelfServiceKey {
return {
id: metadata.id,
name: metadata.name,
scopes: Array.isArray(metadata.scopes) ? [...metadata.scopes] : [],
allowedQuotas: Array.isArray(metadata.allowedQuotas) ? [...metadata.allowedQuotas] : [],
allowedConnections: Array.isArray(metadata.allowedConnections)
? [...metadata.allowedConnections]
: [],
expiresAt: metadata.expiresAt ?? null,
};
}
/** `keyStore` defaults to the API key table in `src/lib/db/apiKeys.ts`. */
export async function authenticateSelfServiceRequest(
request: Request,
keyStore?: SelfServiceKeyStore
): Promise<SelfServiceAuth> {
if (!isFeatureFlagEnabled(SELF_SERVICE_FLAG)) return refuse(404, "Not found");
const candidates = readCredentialCandidates(request);
if (candidates.length === 0) return refuse(401, INVALID_KEY_MESSAGE);
const store: SelfServiceKeyStore = keyStore ?? (await import("@/lib/db/apiKeys"));
const apiKey = await findValidCandidate(store, candidates);
if (!apiKey) return refuse(401, INVALID_KEY_MESSAGE);
const metadata = await store.getApiKeyMetadata(apiKey);
if (!metadata || metadata.id === "env-key") return refuse(401, INVALID_KEY_MESSAGE);
if (!hasSelfUsageScope(metadata.scopes)) {
return refuse(403, "API key lacks the self:usage scope");
}
return { ok: true, key: toSelfServiceKey(metadata) };
}

View File

@@ -0,0 +1,91 @@
/**
* GET /api/v1/me/quota/{provider}: the self-service quota view of the calling API key.
*
* Flow: authenticate (flag, header key, self:usage) → validate the provider segment →
* resolve its registry alias → build the view → `selfQuotaResponseSchema.parse()` as the last
* step, so only contract fields reach the wire. A key outside every pool of the provider gets
* 200 with `pools: []`.
*
* Any failure after the gate is reached (the gate itself, the settings lookup, the server secret,
* the builder, the final parse) is one fixed 500 message; the real error is logged here, once,
* and never reaches the body or a header. Every response of this handler carries
* `Cache-Control: no-store`.
*/
import { z } from "zod";
import { getApiKeySelfServiceSettings } from "@/lib/db/apiKeySelfServiceSettings";
import { buildQuotaSelfView } from "@/lib/quota/selfView";
import type { QuotaSelfViewInput } from "@/lib/quota/selfViewTypes";
import { resolveProviderId } from "@/shared/constants/providers";
import { selfQuotaResponseSchema } from "@/shared/schemas/selfQuota";
import { getApiKeySecret } from "@/shared/utils/apiKey";
import { createLogger } from "@/shared/utils/logger";
import {
authenticateSelfServiceRequest,
selfServiceError,
selfServiceJson,
type SelfServiceKey,
type SelfServiceKeyStore,
} from "./auth";
const log = createLogger("self-service:quota");
const BUILD_FAILED_MESSAGE = "Failed to build quota view";
const MISSING_SCOPE_ERROR = "missing_self_usage_scope";
const providerSegmentSchema = z
.string()
.trim()
.toLowerCase()
.regex(/^[a-z0-9][a-z0-9._-]{0,63}$/);
/** The gate itself is fixed; only the key store it reads can be replaced. */
export interface SelfQuotaHandlerDeps {
buildView?: typeof buildQuotaSelfView;
keyStore?: SelfServiceKeyStore;
}
function toViewInput(key: SelfServiceKey, provider: string): QuotaSelfViewInput {
return {
apiKeyId: key.id,
scopes: key.scopes,
allowedQuotas: key.allowedQuotas,
allowedConnections: key.allowedConnections,
expiresAt: key.expiresAt,
sharedQuotaProviders: getApiKeySelfServiceSettings(key.id).sharedQuotaProviders,
provider,
};
}
function failureResponse(err: unknown): Response {
if (err instanceof Error && err.message === MISSING_SCOPE_ERROR) {
return selfServiceError(403, "API key lacks the self:usage scope");
}
log.error(
{ err: err instanceof Error ? err.message : String(err) },
"self-service quota view: request failed"
);
return selfServiceError(500, BUILD_FAILED_MESSAGE);
}
export async function handleSelfQuotaGet(
request: Request,
rawProvider: string,
deps: SelfQuotaHandlerDeps = {}
): Promise<Response> {
const buildView = deps.buildView ?? buildQuotaSelfView;
try {
const auth = await authenticateSelfServiceRequest(request, deps.keyStore);
if (!auth.ok) return auth.response;
const segment = providerSegmentSchema.safeParse(rawProvider);
if (!segment.success) return selfServiceError(400, "Invalid provider");
const provider = resolveProviderId(segment.data).toLowerCase();
const view = await buildView(toViewInput(auth.key, provider), { secret: getApiKeySecret() });
return selfServiceJson(selfQuotaResponseSchema.parse(view));
} catch (err) {
return failureResponse(err);
}
}

View File

@@ -0,0 +1,70 @@
/**
* GET /api/v1/me/usage: the usage and cost series of the calling API key.
*
* Flow: authenticate (flag, header key, self:usage) → validate `range` (closed set, default
* `30d`) → read the series of the key's own rows (built, or reused for 60 seconds per key id
* and range by getApiKeySelfServiceUsage) → `selfUsageResponseSchema.parse()` as the last step,
* so only contract fields reach the wire. Authentication runs first, so a caller
* without a valid key learns nothing from the range check.
*
* Any failure after the request reaches the handler (the gate itself, the builder, the final
* parse) is one fixed 500 message; the real error is logged here, once, and never reaches the
* body or a header. Every response of this handler carries `Cache-Control: no-store`.
*/
import { getApiKeySelfServiceUsage } from "@/lib/usage/apiKeySelfServiceUsageCache";
import { selfUsageQuerySchema, selfUsageResponseSchema } from "@/shared/schemas/selfUsage";
import { createLogger } from "@/shared/utils/logger";
import {
authenticateSelfServiceRequest,
selfServiceError,
selfServiceJson,
type SelfServiceKeyStore,
} from "./auth";
const log = createLogger("self-service:usage");
const BUILD_FAILED_MESSAGE = "Failed to build usage";
const MISSING_SCOPE_ERROR = "missing_self_usage_scope";
/** The gate itself is fixed; only the key store it reads can be replaced. */
export interface SelfUsageHandlerDeps {
buildUsage?: typeof getApiKeySelfServiceUsage;
keyStore?: SelfServiceKeyStore;
}
/** `range` as sent: absent, one value, or every value when repeated (which fails the enum). */
function readRangeQuery(request: Request): { range?: string | string[] } {
const values = new URL(request.url).searchParams.getAll("range");
return { range: values.length > 1 ? values : values[0] };
}
function failureResponse(err: unknown): Response {
if (err instanceof Error && err.message === MISSING_SCOPE_ERROR) {
return selfServiceError(403, "API key lacks the self:usage scope");
}
log.error(
{ err: err instanceof Error ? err.message : String(err) },
"self-service usage: request failed"
);
return selfServiceError(500, BUILD_FAILED_MESSAGE);
}
export async function handleSelfUsageGet(
request: Request,
deps: SelfUsageHandlerDeps = {}
): Promise<Response> {
const buildUsage = deps.buildUsage ?? getApiKeySelfServiceUsage;
try {
const auth = await authenticateSelfServiceRequest(request, deps.keyStore);
if (!auth.ok) return auth.response;
const query = selfUsageQuerySchema.safeParse(readRangeQuery(request));
if (!query.success) return selfServiceError(400, "Invalid range");
const usage = await buildUsage({ id: auth.key.id, scopes: auth.key.scopes }, query.data.range);
return selfServiceJson(selfUsageResponseSchema.parse(usage));
} catch (err) {
return failureResponse(err);
}
}

View File

@@ -3,6 +3,7 @@ import { SEARCH_FEATURE_FLAG_DEFINITIONS } from "./searchFeatureFlagDefinitions"
import { FAL_NATIVE_ENABLED_FLAG } from "./featureFlagDefinitionsFal";
import { CODE_ASSIST_LEGACY_TIER_FLAG } from "./featureFlagDefinitionsCodeAssist";
import { SYSTEM_ONE_FEATURE_FLAG_DEFINITIONS } from "./featureFlagDefinitionsSystemOne";
import { QUOTA_SELF_PANEL_FLAG } from "./featureFlagDefinitionsQuotaSelf";
import {
PII_RESPONSE_SANITIZATION_MODE_FLAG,
PII_REVERSIBLE_VAULT_FLAG,
@@ -1430,4 +1431,5 @@ export const FEATURE_FLAG_DEFINITIONS: FeatureFlagDefinition[] = [
...SEARCH_FEATURE_FLAG_DEFINITIONS,
CODE_ASSIST_LEGACY_TIER_FLAG,
...SYSTEM_ONE_FEATURE_FLAG_DEFINITIONS,
QUOTA_SELF_PANEL_FLAG,
];

View File

@@ -0,0 +1,15 @@
import type { FeatureFlagDefinition } from "./featureFlagTypes";
/** Kept in its own module so the definitions registry stays under the file-size cap. */
export const QUOTA_SELF_PANEL_FLAG: FeatureFlagDefinition = {
key: "QUOTA_SELF_PANEL",
label: "Quota Share: Self-Service API",
description:
"Let an API key read its own quota-share position and usage: enables GET /v1/me/quota/{provider} and GET /v1/me/usage for keys with the self:usage scope. Pool names and schedule labels are shown to those keys as written. Off by default: those routes answer 404.",
descriptionI18nKey: "featureFlagQuotaSelfPanelDescription",
category: "security",
defaultValue: "false",
type: "boolean",
requiresRestart: false,
warningLevel: "caution",
};

View File

@@ -0,0 +1,132 @@
/**
* Response contract of the self-service quota endpoint (GET /api/v1/me/quota/[provider]).
*
* The response always goes through `selfQuotaResponseSchema.parse()`, which drops any key
* outside this contract (no pool or connection ids, no account e-mail or name).
*
* `reason` values: store_unavailable, percent_attribution_unavailable, window_not_reported,
* plus the ones resolveAccountQuotaEntries already emits (connection_lookup_failed,
* not_supported, fetch_failed, not_available).
*/
import { z } from "zod";
import { PolicySchema, QuotaUnitSchema, QuotaWindowSchema } from "@/lib/quota/dimensions";
export const selfQuotaStatusSchema = z.enum(["ok", "stale", "unavailable"]);
const bar = z.object({
used: z.number().nullable(),
status: selfQuotaStatusSchema,
reason: z.string().optional(),
resetAt: z.string().nullable().optional(),
});
const share = z.object({
fairShare: z.number(),
consumed: z.number().nullable(),
remaining: z.number().nullable(),
status: selfQuotaStatusSchema,
reason: z.string().optional(),
});
// Pool bucket; limit = plan limit x accounts.
const sharedDimension = z.object({
unit: z.enum(["requests", "tokens", "usd"]),
window: QuotaWindowSchema,
limit: z.number(),
total: bar.optional(),
yourShare: share,
});
// One account; limit = plan limit.
const accountDimension = z.object({
unit: z.literal("percent"),
window: QuotaWindowSchema,
limit: z.number(),
account: bar.optional(),
yourShare: share,
});
const account = z.object({
slot: z.number().int().positive(),
label: z.string(), // "Account 1", by pool order
dimensions: z.array(accountDimension),
modelWindows: z
.object({
status: selfQuotaStatusSchema,
reason: z.string().optional(),
windows: z.array(
z.object({ label: z.string(), usedPercent: z.number(), resetAt: z.string().nullable() })
),
})
.optional(),
});
const pool = z.object({
ref: z.string(),
name: z.string(),
provider: z.string(),
borrowMode: z.literal("saturation"),
policy: PolicySchema,
weight: z.number() /* the weight the gate uses */,
cap: z.object({ unit: QuotaUnitSchema, value: z.number() }).nullable(),
accountVisible: z.boolean(),
dimensions: z.array(sharedDimension),
accounts: z.array(account),
});
const blocks = z.object({
schedules: z.array(
z.object({
pool: z.string(),
state: z.enum(["open", "closed"]),
reason: z.enum(["blackout", "outside-window"]).nullable(),
label: z.string().nullable(),
retryAfterSeconds: z.number().nullable(),
reserves: z.array(
z.object({
window: z.union([QuotaWindowSchema, z.literal("any")]),
percent: z.number(),
})
),
budget: z
.object({
unit: z.enum(["requests", "tokens", "usd"]),
window: QuotaWindowSchema,
exhausted: z.boolean().nullable(),
})
.nullable(),
})
),
modelCaps: z.array(
z.object({
pool: z.string(),
model: z.string(),
unit: QuotaUnitSchema,
window: z.literal("hourly"),
cap: z.number(),
consumed: z.number().nullable(),
reached: z.boolean().nullable(),
})
),
});
export const selfQuotaResponseSchema = z.object({
provider: z.string(),
generatedAt: z.string(),
pools: z.array(pool),
availableModels: z.array(z.string()),
expiresAt: z.string().nullable(),
apiBaseUrl: z.string().nullable(),
blocks,
});
export type SelfQuotaStatus = z.infer<typeof selfQuotaStatusSchema>;
export type SelfQuotaBar = z.infer<typeof bar>;
export type SelfQuotaShare = z.infer<typeof share>;
export type SelfQuotaSharedDimension = z.infer<typeof sharedDimension>;
export type SelfQuotaAccountDimension = z.infer<typeof accountDimension>;
export type SelfQuotaAccount = z.infer<typeof account>;
export type SelfQuotaPool = z.infer<typeof pool>;
export type SelfQuotaBlocks = z.infer<typeof blocks>;
export type SelfQuotaResponse = z.infer<typeof selfQuotaResponseSchema>;

View File

@@ -0,0 +1,91 @@
/**
* Query and response contract of the self-service usage endpoint (GET /api/v1/me/usage).
*
* The response always goes through `selfUsageResponseSchema.parse()`, which drops any key
* outside this contract. It carries the provider and model of the calling key's own requests as
* recorded, counts, costs, average latency, success rates, dates and the retention setting. No
* connection, account, other key or request id is part of it. A combo request whose every target
* was refused is recorded with the routing label as provider (the combo name, `auto` or `combo`)
* and the model string the client sent. Other refused requests (open circuit breaker, model
* cooldown, quota-parked skip) keep the target provider and model.
*
* `costUsd` is the billed cost, where flat-rate subscription providers count $0. `listPriceUsd`
* is the same usage priced at list price, subscriptions included. A request whose model has no
* price row counts its stored cost (reported by the provider or calculated when recorded). Only
* a request with neither counts 0, with no marker, so a total can be partial.
*
* `coverage.retentionDays` is the operator's raw usage-history retention setting.
* `truncatedByRetention` compares the requested range with it and does not check whether rows
* are actually missing. `byModel` keeps the 50 provider-and-model pairs with the most requests,
* so with more pairs it does not add up to `summary`. `summary.uniqueModels` counts every
* recorded model spelling.
*/
import { z } from "zod";
/**
* Closed set of windows. It stops at `90d` to bound the cost of a call. The per-key source reads
* raw usage history only, never the daily summaries (which carry no key).
*/
export const SELF_USAGE_RANGES = ["1d", "7d", "30d", "90d"] as const;
export type SelfUsageRange = (typeof SELF_USAGE_RANGES)[number];
export const selfUsageQuerySchema = z.object({
range: z.enum(SELF_USAGE_RANGES).default("30d"),
});
const money = { costUsd: z.number(), listPriceUsd: z.number() };
const counts = {
requests: z.number(),
promptTokens: z.number(),
completionTokens: z.number(),
totalTokens: z.number(),
};
export const selfUsageResponseSchema = z.object({
range: z.enum(SELF_USAGE_RANGES),
generatedAt: z.string(),
coverage: z.object({
from: z.string(),
to: z.string(),
retentionDays: z.number(),
truncatedByRetention: z.boolean(),
}),
summary: z.object({
...counts,
...money,
successfulRequests: z.number(),
successRatePct: z.number(),
uniqueModels: z.number(),
avgLatencyMs: z.number(),
firstRequest: z.string().nullable(),
lastRequest: z.string().nullable(),
}),
daily: z.array(z.object({ date: z.string(), ...counts, ...money })),
dailyByModel: z.array(
z.object({ date: z.string(), model: z.string(), totalTokens: z.number(), ...money })
),
// The 50 provider-and-model pairs with the most requests.
byModel: z.array(
z.object({
model: z.string(),
provider: z.string(),
...counts,
...money,
avgLatencyMs: z.number(),
successRatePct: z.number(),
lastUsed: z.string().nullable(),
})
),
byProvider: z.array(
z.object({
provider: z.string(),
...counts,
...money,
avgLatencyMs: z.number(),
successRatePct: z.number(),
})
),
});
export type SelfUsageResponse = z.infer<typeof selfUsageResponseSchema>;

View File

@@ -5,7 +5,8 @@ if (!process.env.API_KEY_SECRET) {
console.error("[SECURITY] API_KEY_SECRET is not set. API key CRC validation is disabled.");
}
function getApiKeySecret(): string {
/** The server's API-key secret; throws when it is unset or blank. */
export function getApiKeySecret(): string {
const secret = process.env.API_KEY_SECRET;
if (!secret || secret.trim() === "") {
throw new Error(

View File

@@ -0,0 +1,453 @@
// Per-key usage and cost series for GET /v1/me/usage: the owned SQL source and the builder.
// The builder runs here with injected queries, clock, retention and pricer. Importing the
// modules still opens the database, so the file uses a temporary DATA_DIR of its own, set
// before any import that can open it.
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-self-usage-builder-"));
process.env.DATA_DIR = TEST_DATA_DIR;
const core = await import("../../src/lib/db/core.ts");
const { buildApiKeyOwnedSource } = await import("../../src/lib/db/usageAnalytics/apiKeyScope.ts");
const { buildApiKeySelfServiceUsage } =
await import("../../src/lib/usage/apiKeySelfServiceUsage.ts");
const { createSelfServiceUsageCache, getApiKeySelfServiceUsage } =
await import("../../src/lib/usage/apiKeySelfServiceUsageCache.ts");
const { selfUsageResponseSchema } = await import("../../src/shared/schemas/selfUsage.ts");
type SelfServiceUsageDeps =
import("../../src/lib/usage/apiKeySelfServiceUsage.ts").SelfServiceUsageDeps;
test.after(() => {
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
const NOW = Date.parse("2026-05-27T15:30:00.000Z");
const KEY = { id: "key-a", scopes: ["self:usage"] };
const COST_FIELDS = {
cacheReadTokens: 0,
cacheCreationTokens: 0,
reasoningTokens: 0,
storedCost: 0,
isAggregated: 0,
costCacheReadTokens: 0,
costCacheCreationTokens: 0,
costReasoningTokens: 0,
};
/** One day x provider x model slice, in the shapes of the cost and per-model queries. */
function slice(
date: string,
provider: string,
model: string,
requests: number,
prompt: number,
completion: number
) {
const tokens = {
promptTokens: prompt,
completionTokens: completion,
costPromptTokens: prompt,
costCompletionTokens: completion,
};
return {
cost: { date, provider, model, serviceTier: "standard", ...COST_FIELDS, ...tokens },
model: {
model,
provider,
serviceTier: "standard",
requests,
...COST_FIELDS,
...tokens,
totalTokens: prompt + completion,
avgLatencyMs: 100,
successfulRequests: requests,
lastUsed: `${date}T10:00:00.000Z`,
},
};
}
const SLICES = [
slice("2026-05-26", "claude", "claude-sonnet-5", 2, 1500, 700),
slice("2026-05-27", "claude", "claude-sonnet-5", 1, 500, 300),
slice("2026-05-27", "openai", "gpt-5", 1, 1000, 500),
];
const SUMMARY = {
estimatedRequests: 0,
unknownEvidenceRequests: 0,
totalRequests: 4,
promptTokens: 3000,
completionTokens: 1500,
totalTokens: 4500,
uniqueModels: 2,
uniqueAccounts: 1,
uniqueApiKeys: 1,
successfulRequests: 4,
avgLatencyMs: 100,
firstRequest: "2026-05-26T10:00:00.000Z",
lastRequest: "2026-05-27T10:00:00.000Z",
};
const EMPTY_SUMMARY = {
...SUMMARY,
totalRequests: 0,
promptTokens: 0,
completionTokens: 0,
totalTokens: 0,
uniqueModels: 0,
uniqueAccounts: 0,
uniqueApiKeys: 0,
successfulRequests: 0,
avgLatencyMs: 0,
firstRequest: "",
lastRequest: "",
};
const DAILY = [
{ date: "2026-05-26", requests: 2, promptTokens: 1500, completionTokens: 700, totalTokens: 2200 },
{ date: "2026-05-27", requests: 2, promptTokens: 1500, completionTokens: 800, totalTokens: 2300 },
];
const PROVIDERS = [
{
provider: "claude",
requests: 3,
promptTokens: 2000,
completionTokens: 1000,
totalTokens: 3000,
avgLatencyMs: 100,
successfulRequests: 3,
},
{
provider: "openai",
requests: 1,
promptTokens: 1000,
completionTokens: 500,
totalTokens: 1500,
avgLatencyMs: 100,
successfulRequests: 1,
},
];
type Queries = NonNullable<SelfServiceUsageDeps["queries"]>;
function deps(over: { empty?: boolean; seen?: Array<[string, Record<string, string>]> } = {}) {
const record = (name: string, params: Record<string, string>) => over.seen?.push([name, params]);
const queries: Queries = {
summary: (_source, params) => {
record("summary", params);
return over.empty ? EMPTY_SUMMARY : SUMMARY;
},
daily: (_source, params) => {
record("daily", params);
return over.empty ? [] : DAILY;
},
dailyCost: (_source, params) => {
record("dailyCost", params);
return over.empty ? [] : SLICES.map((s) => s.cost);
},
models: (_source, params) => {
record("models", params);
return over.empty ? [] : SLICES.map((s) => s.model);
},
providers: (_source, params) => {
record("providers", params);
return over.empty ? [] : PROVIDERS;
},
};
return {
now: () => NOW,
retentionDays: () => 30,
queries,
priceRow: (row: object, flat: boolean) =>
((flat ? 1 : 2) * (row as { promptTokens: number }).promptTokens) / 1000,
} satisfies SelfServiceUsageDeps;
}
test("the owned source filters by api_key_id only and never reads the daily summaries", () => {
const { unifiedSource, unifiedParams } = buildApiKeyOwnedSource({
apiKeyId: "key-a",
sinceIso: "2020-01-01T00:00:00.000Z",
untilIso: "2026-05-27T15:30:00.000Z",
rawCutoffDate: "2026-04-27",
});
assert.match(unifiedSource, /api_key_id = @ownerApiKeyId/);
// The name column is selected, but never compared to anything.
assert.doesNotMatch(unifiedSource, /api_key_name\s*(=|IN\b|LIKE\b)/i);
assert.ok(!unifiedSource.includes("daily_usage_summary"));
assert.deepEqual(
[unifiedParams.ownerApiKeyId, unifiedParams.since, unifiedParams.until],
["key-a", "2020-01-01T00:00:00.000Z", "2026-05-27T15:30:00.000Z"]
);
assert.match(unifiedSource, /timestamp <= @until/);
// The key id is a bound parameter: it never appears in the SQL text.
assert.ok(!unifiedSource.includes("key-a"));
});
test("the owned source refuses an empty key id instead of matching legacy rows", () => {
for (const apiKeyId of ["", " "]) {
assert.throws(() =>
buildApiKeyOwnedSource({
apiKeyId,
sinceIso: null,
untilIso: null,
rawCutoffDate: "2026-04-27",
})
);
}
});
test("totals, daily series and breakdowns add up, with billed cost next to list price", async () => {
const out = await buildApiKeySelfServiceUsage(KEY, "7d", deps());
assert.deepEqual(
[out.summary.requests, out.summary.totalTokens, out.summary.costUsd, out.summary.listPriceUsd],
[4, 4500, 3, 6]
);
assert.equal(
out.daily.reduce((s, d) => s + d.costUsd, 0),
3
);
assert.deepEqual(
out.daily.map((d) => [d.date, d.requests, d.costUsd, d.listPriceUsd]),
[
["2026-05-26", 2, 1.5, 3],
["2026-05-27", 2, 1.5, 3],
]
);
assert.deepEqual(
out.byModel.map((m) => [m.model, m.requests, m.costUsd]),
[
["claude-sonnet-5", 3, 2],
["gpt-5", 1, 1],
]
);
assert.equal(out.byModel[0].lastUsed, "2026-05-27T10:00:00.000Z");
assert.deepEqual(
out.byProvider.map((p) => [p.provider, p.costUsd, p.listPriceUsd]),
[
["claude", 2, 4],
["openai", 1, 2],
]
);
assert.equal(out.dailyByModel.length, 3);
assert.deepEqual(
[out.summary.successRatePct, out.summary.firstRequest],
[100, SUMMARY.firstRequest]
);
assert.doesNotThrow(() => selfUsageResponseSchema.parse(out));
});
test("every query reads the same owned source, bounded by the window's start and now", async () => {
const seen: Array<[string, Record<string, string>]> = [];
await buildApiKeySelfServiceUsage(KEY, "7d", deps({ seen }));
assert.deepEqual(seen.map(([name]) => name).sort(), [
"daily",
"dailyCost",
"models",
"providers",
"summary",
]);
for (const [, params] of seen) {
assert.deepEqual(params, {
since: new Date(NOW - 7 * 86_400_000).toISOString(),
until: new Date(NOW).toISOString(),
ownerApiKeyId: "key-a",
});
}
});
test("coverage states the window and whether retention cuts it short", async () => {
const long = await buildApiKeySelfServiceUsage(KEY, "90d", deps());
assert.deepEqual([long.coverage.retentionDays, long.coverage.truncatedByRetention], [30, true]);
assert.equal(long.coverage.from, new Date(NOW - 90 * 86_400_000).toISOString());
assert.equal(long.coverage.to, new Date(NOW).toISOString());
assert.equal(long.generatedAt, new Date(NOW).toISOString());
const short = await buildApiKeySelfServiceUsage(KEY, "7d", deps());
assert.equal(short.coverage.truncatedByRetention, false);
});
test("a key with no usage gets zeros and empty series; a key without the scope is refused", async () => {
const empty = await buildApiKeySelfServiceUsage(KEY, "30d", deps({ empty: true }));
assert.deepEqual(
[
empty.summary.requests,
empty.summary.costUsd,
empty.daily.length,
empty.byModel.length,
empty.summary.firstRequest,
empty.summary.successRatePct,
],
[0, 0, 0, 0, null, 0]
);
assert.doesNotThrow(() => selfUsageResponseSchema.parse(empty));
await assert.rejects(
buildApiKeySelfServiceUsage({ id: "k", scopes: [] }, "30d", deps()),
/missing_self_usage_scope/
);
});
test("account and key columns of the reused queries never reach the result", async () => {
const out = await buildApiKeySelfServiceUsage(KEY, "7d", deps());
const text = JSON.stringify(selfUsageResponseSchema.parse(out));
for (const leak of ["uniqueAccounts", "uniqueApiKeys", "serviceTier", "storedCost", "key-a"]) {
assert.ok(!text.includes(leak), `leaked: ${leak}`);
}
});
// ---------------------------------------------------------------------------
// Reuse of a built series (getApiKeySelfServiceUsage): 60 seconds per (key id, range).
/** Deps whose summary depends on the queried key id, with a clock and a build counter. */
function reuseDeps(options: { failFirst?: boolean; maxEntries?: number } = {}) {
const state = { t: NOW, builds: 0, failures: options.failFirst ? 1 : 0 };
const base = deps();
const queries: Queries = {
...base.queries,
summary: (_source, params) => {
state.builds += 1;
if (state.failures > 0) {
state.failures -= 1;
throw new Error("summary failed");
}
return { ...SUMMARY, totalRequests: params.ownerApiKeyId === "key-a" ? 4 : 9 };
},
};
const cache = createSelfServiceUsageCache({ maxEntries: options.maxEntries });
return { state, deps: { ...base, now: () => state.t, queries, cache } };
}
const KEY_B = { id: "key-b", scopes: ["self:usage"] };
test("a second call within 60 s reuses the built series; after 60 s it rebuilds", async () => {
const { state, deps: d } = reuseDeps();
const first = await getApiKeySelfServiceUsage(KEY, "7d", d);
state.t = NOW + 59_999;
const second = await getApiKeySelfServiceUsage(KEY, "7d", d);
assert.equal(state.builds, 1);
assert.equal(second, first);
assert.equal(second.generatedAt, new Date(NOW).toISOString());
state.t = NOW + 60_001;
const third = await getApiKeySelfServiceUsage(KEY, "7d", d);
assert.equal(state.builds, 2);
assert.equal(third.generatedAt, new Date(NOW + 60_001).toISOString());
});
test("concurrent calls for one key and range share one build", async () => {
const { state, deps: d } = reuseDeps();
const [x, y] = await Promise.all([
getApiKeySelfServiceUsage(KEY, "30d", d),
getApiKeySelfServiceUsage(KEY, "30d", d),
]);
assert.equal(state.builds, 1);
assert.equal(x, y);
});
test("a build still in flight is shared, not started twice", async () => {
const cache = createSelfServiceUsageCache();
let starts = 0;
let finish: (value: unknown) => void = () => {};
const build = () => {
starts += 1;
return new Promise((resolve) => {
finish = resolve;
}) as ReturnType<typeof getApiKeySelfServiceUsage>;
};
const first = cache.memoize("k", NOW, build);
const second = cache.memoize("k", NOW + 1, build);
assert.equal(starts, 1);
const built = { range: "7d" };
finish(built);
assert.deepEqual([await first, await second], [built, built]);
});
test("a failed build is not kept; every waiter gets the same failure", async () => {
const { state, deps: d } = reuseDeps({ failFirst: true });
const results = await Promise.allSettled([
getApiKeySelfServiceUsage(KEY, "7d", d),
getApiKeySelfServiceUsage(KEY, "7d", d),
]);
assert.deepEqual(
results.map((r) => r.status),
["rejected", "rejected"]
);
const [r1, r2] = results as PromiseRejectedResult[];
assert.equal(r1.reason, r2.reason);
assert.equal(state.builds, 1);
const retry = await getApiKeySelfServiceUsage(KEY, "7d", d);
assert.equal(state.builds, 2);
assert.equal(retry.summary.requests, 4);
});
test("two keys never share an entry, even interleaved on the same range", async () => {
const { state, deps: d } = reuseDeps();
const seen: number[] = [];
for (const key of [KEY, KEY_B, KEY, KEY_B]) {
seen.push((await getApiKeySelfServiceUsage(key, "7d", d)).summary.requests);
}
assert.deepEqual(seen, [4, 9, 4, 9]);
assert.equal(state.builds, 2);
});
test("a different range is a different entry", async () => {
const { state, deps: d } = reuseDeps();
const week = await getApiKeySelfServiceUsage(KEY, "7d", d);
const month = await getApiKeySelfServiceUsage(KEY, "30d", d);
assert.equal(state.builds, 2);
assert.deepEqual([week.range, month.range], ["7d", "30d"]);
});
test("the scope check runs before the lookup: a cached series is never served without it", async () => {
const { state, deps: d } = reuseDeps();
await getApiKeySelfServiceUsage(KEY, "7d", d);
await assert.rejects(
getApiKeySelfServiceUsage({ id: KEY.id, scopes: [] }, "7d", d),
/missing_self_usage_scope/
);
assert.equal(state.builds, 1);
});
test("the reuse is bounded: past its cap the oldest entry is dropped", async () => {
const { state, deps: d } = reuseDeps({ maxEntries: 2 });
for (const range of ["1d", "7d", "30d"] as const) await getApiKeySelfServiceUsage(KEY, range, d);
assert.equal(state.builds, 3);
await getApiKeySelfServiceUsage(KEY, "1d", d);
assert.equal(state.builds, 4);
await getApiKeySelfServiceUsage(KEY, "30d", d);
assert.equal(state.builds, 4);
});
test("the default cap is 64 entries; past it the oldest is dropped", async () => {
const { state, deps: d } = reuseDeps();
const keyN = (n: number) => ({ id: `key-${n}`, scopes: ["self:usage"] });
for (let n = 0; n < 64; n += 1) await getApiKeySelfServiceUsage(keyN(n), "7d", d);
assert.equal(d.cache.size, 64);
await getApiKeySelfServiceUsage(keyN(0), "7d", d);
assert.equal(state.builds, 64, "64 entries fit");
for (let n = 64; n < 70; n += 1) await getApiKeySelfServiceUsage(keyN(n), "7d", d);
assert.equal(d.cache.size, 64);
await getApiKeySelfServiceUsage(keyN(69), "7d", d);
assert.equal(state.builds, 70);
await getApiKeySelfServiceUsage(keyN(0), "7d", d);
assert.equal(state.builds, 71, "the oldest entry was dropped");
});
test("storing a new entry drops an expired entry of another key", async () => {
const { state, deps: d } = reuseDeps();
await getApiKeySelfServiceUsage(KEY, "7d", d);
state.t = NOW + 30_000;
await getApiKeySelfServiceUsage(KEY_B, "30d", d);
assert.equal(d.cache.size, 2);
state.t = NOW + 60_001;
await getApiKeySelfServiceUsage(KEY_B, "1d", d);
// KEY's entry (written at NOW) has expired and is gone; KEY_B's 30d entry is still fresh.
assert.equal(d.cache.size, 2);
state.t = NOW + 90_001;
await getApiKeySelfServiceUsage(KEY_B, "90d", d);
assert.equal(d.cache.size, 2);
});

View File

@@ -0,0 +1,226 @@
// GET /api/v1/me/quota/{provider} end to end: the real handler with its default wiring against
// rows seeded through the src/lib/db modules and the quota gate's own recordConsumption. Checks
// that the view matches what was seeded and what enforcement decides, and that nothing internal
// or belonging to another key reaches the body or the headers.
import test, { mock } from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-v1-me-quota-e2e-"));
process.env.DATA_DIR = TEST_DATA_DIR;
process.env.API_KEY_SECRET = "test-secret-at-least-32-chars-long-0123456789";
const core = await import("../../../src/lib/db/core.ts");
const apiKeysDb = await import("../../../src/lib/db/apiKeys.ts");
const { createProviderConnection } = await import("../../../src/lib/db/providers.ts");
const { setProviderLimitsCache } = await import("../../../src/lib/db/providerLimits.ts");
const { upsertPlan } = await import("../../../src/lib/db/providerPlans.ts");
const { createPool } = await import("../../../src/lib/db/quotaPools.ts");
const { setModelCap } = await import("../../../src/lib/db/quotaModelCaps.ts");
const { replaceSchedules } = await import("../../../src/lib/db/quotaSchedules.ts");
const { recordConsumption, enforceQuotaShare } = await import("../../../src/lib/quota/enforce.ts");
const { handleSelfQuotaGet } = await import("../../../src/server/selfService/quotaHandler.ts");
const ACCOUNT_EMAIL = "e2e-account@example.com";
test.beforeEach(() => {
process.env.QUOTA_SELF_PANEL = "true";
});
test.after(() => {
mock.timers.reset();
delete process.env.QUOTA_SELF_PANEL;
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
/** One claude account, one pool of three keys, a budgeted schedule, caps and consumption. */
async function seed() {
const conn = (await createProviderConnection({
provider: "claude",
authType: "oauth",
name: ACCOUNT_EMAIL,
email: ACCOUNT_EMAIL,
accessToken: "test-oauth-token",
isActive: true,
testStatus: "active",
})) as { id: string };
upsertPlan(
conn.id,
"claude",
[
{ unit: "tokens", window: "daily", limit: 1000 },
{ unit: "percent", window: "5h", limit: 100 },
],
"manual"
);
const alpha = await apiKeysDb.createApiKey("e2e-key-alpha", "test-machine", ["self:usage"]);
const bravo = await apiKeysDb.createApiKey("e2e-key-bravo", "test-machine", [
"self:usage",
"self:account-quota",
]);
const charlie = await apiKeysDb.createApiKey("e2e-key-charlie", "test-machine", ["self:usage"]);
const pool = createPool({
connectionId: conn.id,
name: "E2E Pool",
allocations: [
{ apiKeyId: alpha.id, weight: 30, policy: "hard" },
{ apiKeyId: bravo.id, weight: 30, policy: "hard" },
{ apiKeyId: charlie.id, weight: 40, policy: "hard" },
],
});
setModelCap({
poolId: pool.id,
apiKeyId: alpha.id,
model: "claude-x",
capValue: 5,
capUnit: "requests",
});
setModelCap({
poolId: pool.id,
apiKeyId: charlie.id,
model: "charlie-only-model",
capValue: 9,
capUnit: "requests",
});
replaceSchedules(pool.id, [
{
label: "e2e-schedule",
days: [0, 1, 2, 3, 4, 5, 6],
startMinute: 0,
endMinute: 1440,
timezone: "UTC",
mode: "allow",
reserves: [],
budgetValue: 50,
budgetUnit: "tokens",
budgetWindow: "daily",
priority: 0,
enabled: true,
},
]);
const base = { connectionId: conn.id, provider: "claude" };
await recordConsumption({
...base,
apiKeyId: alpha.id,
model: "claude-x",
cost: { tokens: 120, requests: 1 },
});
await recordConsumption({ ...base, apiKeyId: charlie.id, cost: { tokens: 300, requests: 1 } });
setProviderLimitsCache(conn.id, {
quotas: {
"session (5h)": {
usedPercentage: 37,
remainingPercentage: 63,
resetAt: new Date(Date.now() + 3_600_000).toISOString(),
},
},
plan: "Max",
message: null,
fetchedAt: new Date().toISOString(),
source: "sync",
});
return { conn, pool, alpha, bravo, charlie };
}
// A fixed mid-hour, mid-day instant for seeding and for both tests: the hourly model-cap bucket
// and the daily token bucket cannot roll over between the seeded consumption and the read.
mock.timers.enable({ apis: ["Date"], now: Date.UTC(2026, 10, 20, 12, 30, 0) });
const seeded = await seed();
const get = (key: string, provider = "claude") =>
handleSelfQuotaGet(
new Request(`http://localhost/api/v1/me/quota/${provider}`, {
headers: { Authorization: `Bearer ${key}` },
}),
provider
);
function assertNoLeak(text: string, leaks: string[]) {
for (const leak of leaks) assert.ok(!text.includes(leak), `leaked: ${leak}`);
}
test("the default wiring reports the seeded numbers, as the gate sees them, and nothing else", async () => {
const { conn, pool, alpha, bravo, charlie } = seeded;
const res = await get(alpha.key);
const text = await res.text();
assert.equal(res.status, 200, text);
const body = JSON.parse(text);
assert.equal(body.pools.length, 1);
const [view] = body.pools;
assert.equal(view.weight, 30);
assert.deepEqual(
view.dimensions.map((d: { unit: string; window: string; limit: number }) => [
d.unit,
d.window,
d.limit,
]),
[["tokens", "daily", 1000]]
);
assert.deepEqual(view.dimensions[0].yourShare, {
fairShare: 300,
consumed: 120,
remaining: 180,
status: "ok",
});
assert.deepEqual(
body.blocks.modelCaps.map((c: { model: string; cap: number; consumed: number }) => [
c.model,
c.cap,
c.consumed,
]),
[["claude-x", 5, 1]]
);
assert.equal(body.blocks.schedules.length, 1);
assert.equal(body.blocks.schedules[0].state, "open");
assert.equal(body.blocks.schedules[0].budget.exhausted, true);
// The view says the schedule budget is spent (420 of 50 tokens): the gate blocks on it.
const gate = await enforceQuotaShare({
apiKeyId: alpha.id,
connectionId: conn.id,
provider: "claude",
model: "claude-x",
});
assert.equal(gate.kind, "block");
assert.match(String((gate as { reason?: string }).reason), /\[schedule-budget\]/);
const internal = [pool.id, conn.id, ACCOUNT_EMAIL, "e2e-account", "charlie-only-model", "Max"];
assertNoLeak(text, [...internal, bravo.id, charlie.id, "e2e-key-bravo", "e2e-key-charlie"]);
const headers = [...res.headers].map(([name, value]) => `${name}: ${value}`).sort();
assert.deepEqual(headers, ["cache-control: no-store", "content-type: application/json"]);
});
test("a key with the account scope gets the cached account bar and still no internal value", async () => {
const { conn, pool, alpha, charlie } = seeded;
const res = await get(seeded.bravo.key, "anthropic");
const text = await res.text();
assert.equal(res.status, 200, text);
const [view] = JSON.parse(text).pools;
assert.equal(view.accountVisible, true);
assert.deepEqual(view.dimensions[0].total, { used: 420, status: "ok" });
const [account] = view.accounts;
assert.equal(account.label, "Account 1");
// "ok", not "stale": the seeded reading is fresh, so the lookup made no upstream refresh.
assert.deepEqual(
[account.dimensions[0].account.used, account.dimensions[0].account.status],
[37, "ok"]
);
assertNoLeak(text, [
pool.id,
conn.id,
ACCOUNT_EMAIL,
"e2e-account",
"charlie-only-model",
"Max",
alpha.id,
charlie.id,
"e2e-key-alpha",
"e2e-key-charlie",
]);
});

View File

@@ -0,0 +1,272 @@
// GET /api/v1/me/quota/{provider}: the self-service quota view of the calling API key.
// The handler is exercised directly (with an injectable builder) against a temporary DATA_DIR
// of its own, set before any module that can open the database is imported.
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-v1-me-quota-route-"));
process.env.DATA_DIR = TEST_DATA_DIR;
const TEST_SECRET = "test-secret-at-least-32-chars-long-0123456789";
process.env.API_KEY_SECRET = TEST_SECRET;
const core = await import("../../../src/lib/db/core.ts");
const apiKeysDb = await import("../../../src/lib/db/apiKeys.ts");
const { updateApiKeySelfServiceSettings } =
await import("../../../src/lib/db/apiKeySelfServiceSettings.ts");
const { SELF_ACCOUNT_QUOTA_SCOPE, SELF_USAGE_SCOPE } =
await import("../../../src/shared/constants/selfServiceScopes.ts");
const { classifyRoute } = await import("../../../src/server/authz/classify.ts");
const {
isPublicApiRoute,
isPublicReadonlyCorsRoute,
PUBLIC_API_ROUTE_PREFIXES,
PUBLIC_API_ROUTES_EXACT,
PUBLIC_READONLY_API_ROUTES_EXACT,
PUBLIC_READONLY_CORS_API_ROUTES,
} = await import("../../../src/shared/constants/publicApiRoutes.ts");
const { handleSelfQuotaGet } = await import("../../../src/server/selfService/quotaHandler.ts");
type QuotaSelfViewInput = import("../../../src/lib/quota/selfViewTypes.ts").QuotaSelfViewInput;
type QuotaSelfViewDeps = import("../../../src/lib/quota/selfViewTypes.ts").QuotaSelfViewDeps;
type SelfQuotaHandlerDeps =
import("../../../src/server/selfService/quotaHandler.ts").SelfQuotaHandlerDeps;
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
test.after(() => {
delete process.env.QUOTA_SELF_PANEL;
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
let scoped = { id: "", key: "" };
let unscoped = { id: "", key: "" };
let accountKey = { id: "", key: "" };
test.before(async () => {
const a = await apiKeysDb.createApiKey("self-quota-scoped", "test-machine", [SELF_USAGE_SCOPE]);
const b = await apiKeysDb.createApiKey("self-quota-unscoped", "test-machine", []);
const c = await apiKeysDb.createApiKey(
"self-quota-account",
"test-machine",
[SELF_USAGE_SCOPE, SELF_ACCOUNT_QUOTA_SCOPE],
{ allowedConnections: ["conn-allowed-1"] }
);
scoped = { id: a.id, key: a.key };
unscoped = { id: b.id, key: b.key };
accountKey = { id: c.id, key: c.key };
});
test.beforeEach(() => {
process.env.QUOTA_SELF_PANEL = "true";
});
const EMPTY_VIEW = {
provider: "claude",
generatedAt: "2026-05-27T15:30:00.000Z",
pools: [],
availableModels: [],
expiresAt: null,
apiBaseUrl: null,
blocks: { schedules: [], modelCaps: [] },
};
const bearer = (k: string) => ({ Authorization: `Bearer ${k}` });
const call = (
provider: string,
headers: Record<string, string> = {},
deps: SelfQuotaHandlerDeps = {},
url = "http://localhost/api/v1/me/quota/x"
) => handleSelfQuotaGet(new Request(url, { headers }), provider, deps);
/** A builder stub that records what the handler passes in and answers EMPTY_VIEW. */
function recordingBuilder() {
const seen: { input?: QuotaSelfViewInput; deps?: QuotaSelfViewDeps } = {};
const buildView = async (input: QuotaSelfViewInput, deps?: QuotaSelfViewDeps) => {
seen.input = input;
seen.deps = deps;
return EMPTY_VIEW;
};
return { seen, buildView };
}
async function assertFixed500(res: Response, leaks: string[]) {
const text = await res.text();
assert.equal(res.status, 500);
assert.equal(res.headers.get("Cache-Control"), "no-store");
assert.equal(JSON.parse(text).error.message, "Failed to build quota view");
for (const leak of [...leaks, " at "]) assert.ok(!text.includes(leak), `leaked: ${leak}`);
for (const [name, value] of res.headers) {
for (const leak of leaks) assert.ok(!value.includes(leak), `leaked in header ${name}`);
}
}
test("both spellings are client API routes, with no public-route entry", () => {
assert.equal(classifyRoute("/v1/me/quota/claude").routeClass, "CLIENT_API");
assert.equal(classifyRoute("/api/v1/me/quota/claude").routeClass, "CLIENT_API");
// Every /api/v1/ route is reachable without a dashboard session through the existing
// "/api/v1/" prefix (its handler authenticates the key itself, as /api/v1/me/status does).
// What must hold: that prefix is the only match, there is no entry of the route's own, and
// the read-only CORS relaxation does not apply.
const quotaPath = "/api/v1/me/quota/claude";
assert.equal(isPublicApiRoute(quotaPath, "GET"), isPublicApiRoute("/api/v1/me/status", "GET"));
assert.deepEqual(
PUBLIC_API_ROUTE_PREFIXES.filter((prefix) => quotaPath.startsWith(prefix)),
["/api/v1/"]
);
const ownEntries = [
...PUBLIC_API_ROUTES_EXACT,
...PUBLIC_READONLY_API_ROUTES_EXACT,
...PUBLIC_READONLY_CORS_API_ROUTES,
].filter((route) => route.startsWith("/api/v1/me") || route.startsWith("/v1/me"));
assert.deepEqual(ownEntries, []);
assert.equal(isPublicReadonlyCorsRoute(quotaPath, "GET"), false);
});
test("flag off is 404; no key is 401; no scope is 403; a bad provider is 400", async () => {
delete process.env.QUOTA_SELF_PANEL;
const off = await call("claude", bearer(scoped.key));
assert.deepEqual([off.status, off.headers.get("Cache-Control")], [404, "no-store"]);
process.env.QUOTA_SELF_PANEL = "true";
assert.equal((await call("claude")).status, 401);
const noScope = await call("claude", bearer(unscoped.key));
assert.deepEqual([noScope.status, noScope.headers.get("Cache-Control")], [403, "no-store"]);
const bad = await call("cl aude/../x", bearer(scoped.key));
assert.deepEqual([bad.status, bad.headers.get("Cache-Control")], [400, "no-store"]);
assert.equal((await bad.json()).error.message, "Invalid provider");
});
test("the key is read from headers only, never from the query string or a cookie", async () => {
const viaQuery = await call(
"claude",
{},
{},
`http://localhost/api/v1/me/quota/claude?apiKey=${scoped.key}&key=${scoped.key}`
);
assert.equal(viaQuery.status, 401);
const viaCookie = await call("claude", { Cookie: `apiKey=${scoped.key}; auth_token=x` });
assert.equal(viaCookie.status, 401);
for (const res of [viaQuery, viaCookie]) {
assert.equal(res.headers.get("Cache-Control"), "no-store");
}
});
test("a key outside any pool gets 200 with an empty pool list and exactly the documented keys", async () => {
const res = await call("claude", bearer(scoped.key));
assert.deepEqual([res.status, res.headers.get("Cache-Control")], [200, "no-store"]);
const body = await res.json();
assert.deepEqual(body.pools, []);
assert.deepEqual(Object.keys(body).sort(), [
"apiBaseUrl",
"availableModels",
"blocks",
"expiresAt",
"generatedAt",
"pools",
"provider",
]);
});
test("the builder receives the calling key's identity and sharing settings", async () => {
const { seen, buildView } = recordingBuilder();
await call("anthropic", { "x-api-key": scoped.key }, { buildView });
assert.deepEqual(
[seen.input?.apiKeyId, seen.input?.provider, seen.input?.sharedQuotaProviders],
[scoped.id, "anthropic", null]
);
});
test("the builder receives the key's scopes, quotas, connections, expiry, sharing list and secret", async () => {
updateApiKeySelfServiceSettings(accountKey.id, { sharedQuotaProviders: ["claude"] });
const { seen, buildView } = recordingBuilder();
const res = await call(" CC ", bearer(accountKey.key), { buildView });
assert.equal(res.status, 200);
assert.deepEqual(seen.input, {
apiKeyId: accountKey.id,
scopes: [SELF_USAGE_SCOPE, SELF_ACCOUNT_QUOTA_SCOPE],
allowedQuotas: [],
allowedConnections: ["conn-allowed-1"],
expiresAt: null,
sharedQuotaProviders: ["claude"],
// Trimmed, lower-cased and alias-resolved (cc is the registry alias of claude).
provider: "claude",
});
assert.equal(seen.deps?.secret, TEST_SECRET);
});
test("a builder failure is a fixed 500 message; keys outside the contract never reach the wire", async () => {
const boom = await call("claude", bearer(scoped.key), {
buildView: async () => {
throw new Error("SQLITE_ERROR at /home/app/src/lib/quota/selfView.ts:42:7");
},
});
await assertFixed500(boom, ["SQLITE_ERROR", "selfView.ts", "/home/app"]);
const extra = await (
await call("claude", bearer(scoped.key), {
buildView: async () =>
({ ...EMPTY_VIEW, poolId: "p", connectionId: "c" }) as typeof EMPTY_VIEW,
})
).text();
assert.ok(!extra.includes("poolId") && !extra.includes("connectionId"));
});
test("a view that breaks the contract is the same fixed 500", async () => {
const res = await call("claude", bearer(scoped.key), {
buildView: async () => ({ ...EMPTY_VIEW, pools: "not-a-list" }) as unknown as typeof EMPTY_VIEW,
});
await assertFixed500(res, ["not-a-list", "ZodError", "invalid_type"]);
});
test("a key store failure inside the real authentication gate is the same fixed 500", async () => {
const lookups: string[] = [];
const failingStore = {
validateApiKey: async (key: string) => {
lookups.push(key);
throw new Error("SQLITE_CANTOPEN /data/storage.sqlite");
},
getApiKeyMetadata: async () => {
throw new Error("SQLITE_CANTOPEN /data/storage.sqlite");
},
};
const res = await call("claude", bearer(scoped.key), { keyStore: failingStore });
await assertFixed500(res, ["SQLITE_CANTOPEN", "storage.sqlite"]);
// The real gate read the header credential and reached the injected store.
assert.deepEqual(lookups, [scoped.key]);
// The flag check still runs before the store: with the flag off the store is never read.
delete process.env.QUOTA_SELF_PANEL;
const off = await call("claude", bearer(scoped.key), { keyStore: failingStore });
assert.equal(off.status, 404);
assert.deepEqual(lookups, [scoped.key]);
});
test("a missing server secret is the same fixed 500, without naming the secret", async () => {
delete process.env.API_KEY_SECRET;
try {
const res = await call("claude", bearer(scoped.key));
await assertFixed500(res, ["API_KEY_SECRET", "missing_pool_ref_secret", "secret"]);
} finally {
process.env.API_KEY_SECRET = TEST_SECRET;
}
});
test("a builder refusal for a missing self:usage scope is a 403", async () => {
const res = await call("claude", bearer(scoped.key), {
buildView: async () => {
throw new Error("missing_self_usage_scope");
},
});
assert.deepEqual([res.status, res.headers.get("Cache-Control")], [403, "no-store"]);
});
test("the route file is a thin shell over the handler", () => {
const src = fs.readFileSync(
path.join(repoRoot, "src/app/api/v1/me/quota/[provider]/route.ts"),
"utf8"
);
for (const piece of [/handleSelfQuotaGet/, /await params/, /dynamic = "force-dynamic"/]) {
assert.match(src, piece);
}
});

View File

@@ -0,0 +1,448 @@
// GET /api/v1/me/usage: the usage and cost series of the calling API key.
// The handler runs with its default wiring against usage rows seeded through the src/lib/db
// and src/lib/usage modules, in a temporary DATA_DIR of its own set before any module that can
// open the database is imported. Some tests inject the builder or the gate's key store.
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-v1-me-usage-route-"));
process.env.DATA_DIR = TEST_DATA_DIR;
process.env.API_KEY_SECRET = "test-secret-at-least-32-chars-long-0123456789";
const core = await import("../../../src/lib/db/core.ts");
const apiKeysDb = await import("../../../src/lib/db/apiKeys.ts");
const usageHistory = await import("../../../src/lib/usage/usageHistory.ts");
const dbSettings = await import("../../../src/lib/db/databaseSettings.ts");
const { SELF_USAGE_SCOPE } = await import("../../../src/shared/constants/selfServiceScopes.ts");
const { classifyRoute } = await import("../../../src/server/authz/classify.ts");
const {
isPublicApiRoute,
isPublicReadonlyCorsRoute,
PUBLIC_API_ROUTE_PREFIXES,
PUBLIC_API_ROUTES_EXACT,
PUBLIC_READONLY_API_ROUTES_EXACT,
PUBLIC_READONLY_CORS_API_ROUTES,
} = await import("../../../src/shared/constants/publicApiRoutes.ts");
const { handleSelfUsageGet } = await import("../../../src/server/selfService/usageHandler.ts");
type SelfUsageHandlerDeps =
import("../../../src/server/selfService/usageHandler.ts").SelfUsageHandlerDeps;
type SelfUsageResponse = import("../../../src/shared/schemas/selfUsage.ts").SelfUsageResponse;
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
test.after(() => {
delete process.env.QUOTA_SELF_PANEL;
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
let a = { id: "", key: "" };
let b = { id: "", key: "" };
let c = { id: "", key: "" };
let unscoped = { id: "", key: "" };
let future = { id: "", key: "" };
let revoked = { id: "", key: "" };
let retention = { id: "", key: "" };
let recorded = { id: "", key: "" };
let reused = { id: "", key: "" };
let revokedLater = { id: "", key: "" };
test.before(async () => {
const created = await Promise.all([
apiKeysDb.createApiKey("Key A", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key B", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key C", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key unscoped", "test-machine", []),
apiKeysDb.createApiKey("Key future", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key losing scope", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key retention", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key recorded", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key reused", "test-machine", [SELF_USAGE_SCOPE]),
apiKeysDb.createApiKey("Key revoked later", "test-machine", [SELF_USAGE_SCOPE]),
]);
[a, b, c, unscoped, future, revoked, retention, recorded, reused, revokedLater] = created.map(
(k) => ({
id: k.id,
key: k.key,
})
);
});
test.beforeEach(() => {
process.env.QUOTA_SELF_PANEL = "true";
});
const bearer = (k: string) => ({ Authorization: `Bearer ${k}` });
const call = (
query: string,
headers: Record<string, string> = {},
deps: SelfUsageHandlerDeps = {}
) => handleSelfUsageGet(new Request(`http://localhost/api/v1/me/usage${query}`, { headers }), deps);
// Distinct timestamps, a minute or more in the past: identical rows written in the same
// millisecond would be merged by the writer's duplicate guard.
let seq = 0;
function seed(o: Record<string, unknown>) {
seq += 1;
return usageHistory.saveRequestUsage({
tokens: { input: 100, output: 50 },
success: true,
latencyMs: 100,
timestamp: new Date(Date.now() - 60_000 - seq * 1000).toISOString(),
connectionId: "conn-secret-1",
...o,
} as Parameters<typeof usageHistory.saveRequestUsage>[0]);
}
const EMPTY_USAGE: SelfUsageResponse = {
range: "30d",
generatedAt: "2026-05-27T15:30:00.000Z",
coverage: {
from: "2026-04-27T15:30:00.000Z",
to: "2026-05-27T15:30:00.000Z",
retentionDays: 30,
truncatedByRetention: false,
},
summary: {
requests: 0,
promptTokens: 0,
completionTokens: 0,
totalTokens: 0,
costUsd: 0,
listPriceUsd: 0,
successfulRequests: 0,
successRatePct: 0,
uniqueModels: 0,
avgLatencyMs: 0,
firstRequest: null,
lastRequest: null,
},
daily: [],
dailyByModel: [],
byModel: [],
byProvider: [],
};
async function assertFixed500(res: Response, leaks: string[]) {
const text = await res.text();
assert.equal(res.status, 500);
assert.equal(res.headers.get("Cache-Control"), "no-store");
assert.equal(JSON.parse(text).error.message, "Failed to build usage");
for (const leak of [...leaks, " at "]) assert.ok(!text.includes(leak), `leaked: ${leak}`);
for (const [name, value] of res.headers) {
for (const leak of leaks) assert.ok(!value.includes(leak), `leaked in header ${name}`);
}
}
test("both spellings are client API routes, with no public-route entry", () => {
assert.equal(classifyRoute("/v1/me/usage").routeClass, "CLIENT_API");
assert.equal(classifyRoute("/api/v1/me/usage").routeClass, "CLIENT_API");
// Reachable without a dashboard session only through the existing "/api/v1/" prefix, like
// /api/v1/me/status; the handler authenticates the key itself.
const usagePath = "/api/v1/me/usage";
assert.equal(isPublicApiRoute(usagePath, "GET"), isPublicApiRoute("/api/v1/me/status", "GET"));
assert.deepEqual(
PUBLIC_API_ROUTE_PREFIXES.filter((prefix) => usagePath.startsWith(prefix)),
["/api/v1/"]
);
const ownEntries = [
...PUBLIC_API_ROUTES_EXACT,
...PUBLIC_READONLY_API_ROUTES_EXACT,
...PUBLIC_READONLY_CORS_API_ROUTES,
].filter((route) => route.startsWith("/api/v1/me") || route.startsWith("/v1/me"));
assert.deepEqual(ownEntries, []);
assert.equal(isPublicReadonlyCorsRoute(usagePath, "GET"), false);
});
test("key A never sees key B's rows, including a row that only matches by name", async () => {
await seed({ apiKeyId: a.id, apiKeyName: "Key A", provider: "claude", model: "claude-sonnet-5" });
await seed({ apiKeyId: a.id, apiKeyName: "Key A", provider: "claude", model: "claude-sonnet-5" });
await seed({ apiKeyId: b.id, apiKeyName: "Key B", provider: "openai", model: "gpt-5" });
await seed({ apiKeyId: b.id, apiKeyName: a.id, provider: "openai", model: "gpt-5" }); // name == A's id
// Legacy rows without a key id, named after A: NULL and empty-string api_key_id.
await seed({ apiKeyName: a.id, provider: "openai", model: "legacy-null-model" });
await seed({ apiKeyName: a.id, provider: "openai", model: "legacy-empty-model" });
const legacy = core
.getDbInstance()
.prepare("UPDATE usage_history SET api_key_id = '' WHERE model = 'legacy-empty-model'")
.run();
assert.equal(legacy.changes, 1);
const res = await call("?range=7d", bearer(a.key));
assert.deepEqual([res.status, res.headers.get("Cache-Control")], [200, "no-store"]);
const text = await res.text();
const body = JSON.parse(text);
assert.equal(body.summary.requests, 2);
assert.deepEqual(
body.byProvider.map((p: { provider: string }) => p.provider),
["claude"]
);
assert.deepEqual(
body.byModel.map((m: { model: string }) => m.model),
["claude-sonnet-5"]
);
for (const leak of ["gpt-5", "legacy-", "conn-secret-1", "Key A", "Key B", a.id, b.id]) {
assert.ok(!text.includes(leak), `leaked: ${leak}`);
}
assert.equal((await (await call("?range=7d", bearer(b.key))).json()).summary.requests, 2);
});
test("the response has exactly the documented keys", async () => {
const body = await (await call("?range=7d", bearer(a.key))).json();
assert.deepEqual(Object.keys(body).sort(), [
"byModel",
"byProvider",
"coverage",
"daily",
"dailyByModel",
"generatedAt",
"range",
"summary",
]);
assert.deepEqual(Object.keys(body.coverage).sort(), [
"from",
"retentionDays",
"to",
"truncatedByRetention",
]);
for (const day of body.daily) assert.match(day.date, /^\d{4}-\d{2}-\d{2}$/);
assert.equal(
body.daily.reduce((sum: number, day: { requests: number }) => sum + day.requests, 0),
body.summary.requests
);
});
test("a subscription request is $0 billed and priced at list price", async () => {
await seed({
apiKeyId: c.id,
apiKeyName: "Key C",
provider: "claude",
model: "claude-opus-4-8",
tokens: { input: 1000, output: 1000 },
});
const body = await (await call("?range=1d", bearer(c.key))).json();
assert.equal(body.summary.requests, 1);
assert.equal(body.summary.costUsd, 0);
assert.ok(body.summary.listPriceUsd > 0, "list price of a subscription request");
assert.equal(body.byModel[0].listPriceUsd, body.summary.listPriceUsd);
assert.equal(body.daily[0].listPriceUsd, body.summary.listPriceUsd);
});
test("a row stamped after now is not counted", async () => {
await seed({ apiKeyId: future.id, provider: "openai", model: "gpt-5" });
await seed({
apiKeyId: future.id,
provider: "openai",
model: "from-the-future",
timestamp: new Date(Date.now() + 3 * 86_400_000).toISOString(),
});
const text = await (await call("?range=1d", bearer(future.key))).text();
const body = JSON.parse(text);
assert.equal(body.summary.requests, 1);
assert.ok(body.summary.lastRequest <= body.coverage.to);
assert.ok(!text.includes("from-the-future"));
});
test("the gate runs before the reuse: a key that loses self:usage is refused at once", async () => {
const first = await call("?range=7d", bearer(revoked.key));
assert.equal(first.status, 200);
await apiKeysDb.updateApiKeyPermissions(revoked.id, { scopes: [] });
const after = await call("?range=7d", bearer(revoked.key));
assert.deepEqual([after.status, after.headers.get("Cache-Control")], [403, "no-store"]);
});
test("coverage follows the operator's stored raw-history retention setting", async () => {
// Default wiring: no injected retention. A fresh database carries the value its migration
// seeded (046_database_settings.sql), not the code's fallback of 30.
const stored = dbSettings.getUserDatabaseSettings().retention;
const seeded = stored.usageHistory;
const fresh = await (await call("?range=90d", bearer(retention.key))).json();
assert.equal(fresh.coverage.retentionDays, seeded);
assert.notEqual(seeded, 30);
dbSettings.updateDatabaseSettings({ retention: { ...stored, usageHistory: 7 } });
try {
const month = await (await call("?range=30d", bearer(retention.key))).json();
assert.deepEqual(
[month.coverage.retentionDays, month.coverage.truncatedByRetention],
[7, true]
);
const week = await (await call("?range=7d", bearer(retention.key))).json();
assert.deepEqual([week.coverage.retentionDays, week.coverage.truncatedByRetention], [7, false]);
} finally {
dbSettings.updateDatabaseSettings({ retention: { ...stored } });
}
});
test("provider and model are returned as recorded; an unpriced model counts 0", async () => {
// The shape written for a combo whose every target was refused: the routing label as
// provider and the client's model string.
await seed({
apiKeyId: recorded.id,
provider: "team-internal-combo",
model: "my-alias",
success: false,
tokens: {},
comboStrategy: "team-internal-combo",
});
await seed({ apiKeyId: recorded.id, provider: "openai", model: "totally-unpriced-model-xyz" });
const body = await (await call("?range=1d", bearer(recorded.key))).json();
const providers = body.byProvider.map((p: { provider: string }) => p.provider).sort();
assert.deepEqual(providers, ["openai", "team-internal-combo"]);
const unpriced = body.byModel.find(
(m: { model: string }) => m.model === "totally-unpriced-model-xyz"
);
assert.deepEqual([unpriced.costUsd, unpriced.listPriceUsd], [0, 0]);
assert.deepEqual([body.summary.costUsd, body.summary.listPriceUsd], [0, 0]);
assert.equal(body.summary.successRatePct, 50);
});
test("the default path reuses a built series within the reuse window", async () => {
// Key and range used by no other test, so the module's shared reuse cannot collide.
await seed({ apiKeyId: reused.id, provider: "openai", model: "gpt-5" });
const first = await (await call("?range=90d", bearer(reused.key))).json();
await seed({ apiKeyId: reused.id, provider: "openai", model: "recorded-in-between" });
const text = await (await call("?range=90d", bearer(reused.key))).text();
const second = JSON.parse(text);
assert.equal(first.summary.requests, 1);
assert.equal(second.generatedAt, first.generatedAt);
assert.equal(second.summary.requests, 1);
assert.ok(!text.includes("recorded-in-between"));
});
test("a key revoked after its series was cached is refused, not served", async () => {
const before = await call("?range=7d", bearer(revokedLater.key));
assert.equal(before.status, 200);
assert.equal(await apiKeysDb.revokeApiKey(revokedLater.id), true);
const after = await call("?range=7d", bearer(revokedLater.key));
assert.deepEqual([after.status, after.headers.get("Cache-Control")], [401, "no-store"]);
});
test("range is a closed set with a default", async () => {
assert.equal((await (await call("", bearer(a.key))).json()).range, "30d");
for (const bad of [
"?range=all",
"?range=365d",
"?range=ytd",
"?range=7d%27%20OR%201=1",
"?range=",
"?range=7D",
"?range=7d&range=all",
]) {
const res = await call(bad, bearer(a.key));
assert.deepEqual([res.status, res.headers.get("Cache-Control")], [400, "no-store"], bad);
assert.equal((await res.json()).error.message, "Invalid range");
}
});
test("authentication runs before range validation", async () => {
assert.equal((await call("?range=all")).status, 401);
assert.equal((await call("?range=all", bearer(unscoped.key))).status, 403);
});
test("auth, flag, headers and error sanitization follow the quota route", async () => {
assert.equal((await call("")).status, 401);
assert.equal((await call("", bearer(unscoped.key))).status, 403);
assert.equal((await call("", bearer(a.key))).headers.get("Cache-Control"), "no-store");
assert.equal((await call("", { "x-api-key": a.key })).status, 200);
const viaQuery = await call(`?range=7d&apiKey=${a.key}&key=${a.key}`);
assert.equal(viaQuery.status, 401);
const boom = await call("", bearer(a.key), {
buildUsage: async () => {
throw new Error("no such table at /srv/x.ts:1");
},
});
await assertFixed500(boom, ["no such table", "/srv/x.ts"]);
delete process.env.QUOTA_SELF_PANEL;
const off = await call("", bearer(a.key));
assert.deepEqual([off.status, off.headers.get("Cache-Control")], [404, "no-store"]);
});
test("the builder receives the calling key's id, scopes and the parsed range", async () => {
const seen: Array<[unknown, unknown]> = [];
const res = await call("?range=90d", bearer(a.key), {
buildUsage: async (key, range) => {
seen.push([key, range]);
return { ...EMPTY_USAGE, range };
},
});
assert.equal(res.status, 200);
assert.deepEqual(seen, [[{ id: a.id, scopes: [SELF_USAGE_SCOPE] }, "90d"]]);
});
test("keys outside the contract never reach the wire; a broken result is the fixed 500", async () => {
const extra = await (
await call("", bearer(a.key), {
buildUsage: async () =>
({
...EMPTY_USAGE,
connectionId: "conn-x",
apiKeyName: "Key B",
byModel: [
{
model: "m",
provider: "p",
requests: 1,
promptTokens: 1,
completionTokens: 1,
totalTokens: 2,
costUsd: 0,
listPriceUsd: 0,
avgLatencyMs: 1,
successRatePct: 100,
lastUsed: null,
accountKey: "acct-secret",
comboName: "combo-secret",
},
],
}) as unknown as SelfUsageResponse,
})
).text();
for (const leak of ["connectionId", "conn-x", "Key B", "acct-secret", "combo-secret"]) {
assert.ok(!extra.includes(leak), `leaked: ${leak}`);
}
const broken = await call("", bearer(a.key), {
buildUsage: async () =>
({ ...EMPTY_USAGE, daily: "not-a-list" }) as unknown as SelfUsageResponse,
});
await assertFixed500(broken, ["not-a-list", "ZodError", "invalid_type"]);
});
test("a key store failure inside the real authentication gate is the same fixed 500", async () => {
const lookups: string[] = [];
const failingStore = {
validateApiKey: async (key: string) => {
lookups.push(key);
throw new Error("SQLITE_CANTOPEN /data/storage.sqlite");
},
getApiKeyMetadata: async () => {
throw new Error("SQLITE_CANTOPEN /data/storage.sqlite");
},
};
const res = await call("?range=all", bearer(a.key), { keyStore: failingStore });
await assertFixed500(res, ["SQLITE_CANTOPEN", "storage.sqlite"]);
assert.deepEqual(lookups, [a.key]);
});
test("a builder refusal for a missing self:usage scope is a 403", async () => {
const res = await call("", bearer(a.key), {
buildUsage: async () => {
throw new Error("missing_self_usage_scope");
},
});
assert.deepEqual([res.status, res.headers.get("Cache-Control")], [403, "no-store"]);
});
test("the route file is a thin shell over the handler", () => {
const src = fs.readFileSync(path.join(repoRoot, "src/app/api/v1/me/usage/route.ts"), "utf8");
for (const piece of [
/handleSelfUsageGet/,
/dynamic = "force-dynamic"/,
/export async function GET/,
]) {
assert.match(src, piece);
}
});

View File

@@ -76,7 +76,8 @@ const {
// PII_REVERSIBLE_VAULT_ENABLED (#18017 wiring, default off) takes it to 123;
// SYSTEMONE_CLOUDFLARE_BACKEND_ENABLED (#16676), SYSTEMONE_OLLAMA_LOCAL_BACKEND_ENABLED (#14667)
// and COMBO_JEV_STRATEGY_ENABLED (#15279), all default off, take it to 126.
const EXPECTED_FEATURE_FLAG_COUNT = 126;
// QUOTA_SELF_PANEL (self-service quota API, default off) takes it to 127.
const EXPECTED_FEATURE_FLAG_COUNT = 127;
// tool_call wrapper repair, default on) to 86; OPENCODE_V2_CLIENT_FINGERPRINT_ENABLED
// (#16571, OpenCode v2 client fingerprint, default off) to 87.
// tool_call wrapper repair, default on) to 86; CLAUDE_OAUTH_SUMMARIZED_THINKING_UNREDACTED

View File

@@ -0,0 +1,152 @@
/**
* Test factories for the self-service quota view builders (selfView and its sibling modules).
* Stubs only: nothing here touches a database, the network or the environment.
*/
import type { PoolAllocation, QuotaPool } from "../../../src/lib/db/quotaPools.ts";
import type { ProviderPlan } from "../../../src/lib/quota/dimensions.ts";
import type {
QuotaSelfViewDeps,
QuotaSelfViewInput,
SelfViewPoolContext,
} from "../../../src/lib/quota/selfViewTypes.ts";
import type { QuotaStore } from "../../../src/lib/quota/types.ts";
import {
SELF_ACCOUNT_QUOTA_SCOPE,
SELF_USAGE_SCOPE,
} from "../../../src/shared/constants/selfServiceScopes.ts";
export const TEST_POOL_REF_SECRET = "test-pool-ref-secret-0123456789abcdef";
export const BOTH = [SELF_USAGE_SCOPE, SELF_ACCOUNT_QUOTA_SCOPE];
export function input(over: Partial<QuotaSelfViewInput> = {}): QuotaSelfViewInput {
return {
apiKeyId: "key-a",
scopes: [SELF_USAGE_SCOPE],
allowedQuotas: [],
expiresAt: null,
sharedQuotaProviders: null,
provider: "claude",
...over,
};
}
export function alloc(apiKeyId: string, weight: number): PoolAllocation {
return { apiKeyId, weight, policy: "hard" };
}
type LooseDimension = { unit: string; window: string; limit: number };
export type MakeDepsOverrides = Partial<QuotaSelfViewDeps> & {
/** Merged into every pool. */
pool?: Partial<QuotaPool>;
/** Merged into the plan of every pool. */
plan?: Partial<Omit<ProviderPlan, "dimensions">> & { dimensions?: LooseDimension[] };
/** Merged into the quota store stub. */
store?: Partial<Pick<QuotaStore, "peek" | "poolConsumedTotal">>;
};
const CONNECTION_PROVIDERS: Record<string, string> = {
"conn-secret-1": "claude",
"conn-secret-3": "codex",
};
function basePools(): QuotaPool[] {
const pool = (id: string, name: string, connectionId: string, createdAt: string): QuotaPool => ({
id,
connectionId,
connectionIds: [connectionId],
name,
groupId: `group-${id}`,
createdAt,
allocations: [alloc("key-a", 50), alloc("key-b", 50)],
});
return [
// Listed out of creation order on purpose: the view sorts by createdAt, then name.
pool("pool-b-id", "Pool B", "conn-secret-1", "2026-01-02T00:00:00.000Z"),
pool("pool-codex-id", "Pool C", "conn-secret-3", "2026-01-01T12:00:00.000Z"),
pool("pool-a-id", "Pool A", "conn-secret-1", "2026-01-01T00:00:00.000Z"),
];
}
/**
* Two claude pools ("Pool A", "Pool B") the key is allocated in, plus one codex pool. The codex
* pool is allocated to other keys by default, so a pool override that changes `allocations`
* also places "key-a" in it.
*/
export function makeDeps(over: MakeDepsOverrides = {}): QuotaSelfViewDeps {
const { pool: poolOver, plan: planOver, store: storeOver, ...rest } = over;
const pools = basePools().map((p) =>
p.id === "pool-codex-id" && !poolOver?.allocations
? { ...p, allocations: [alloc("key-b", 50), alloc("key-c", 50)], ...poolOver }
: { ...p, ...poolOver }
);
const store: Pick<QuotaStore, "peek" | "poolConsumedTotal"> = {
peek: async () => 120,
poolConsumedTotal: async () => 400,
...storeOver,
};
return {
now: () => Date.parse("2026-05-27T15:30:00.000Z"),
secret: TEST_POOL_REF_SECRET,
listAllocationsForApiKey: (apiKeyId) =>
pools.flatMap((p) =>
p.allocations
.filter((a) => a.apiKeyId === apiKeyId)
.map((allocation) => ({ poolId: p.id, allocation }))
),
getPool: (poolId) => pools.find((p) => p.id === poolId) ?? null,
resolveConnectionProvider: async (connectionId) =>
CONNECTION_PROVIDERS[connectionId] ?? "unknown",
resolvePlan: (connectionId, provider) =>
({
connectionId,
provider,
dimensions: [{ unit: "tokens", window: "daily", limit: 1000 }],
source: "manual",
...planOver,
}) as ProviderPlan,
getQuotaStore: async () => store,
// No account data by default, so no test reaches the real provider-limits modules.
resolveAccountQuotaEntries: async () => [],
// No schedules, caps or models by default, so no test opens the database through them.
listEnabledSchedules: () => [],
listModelCapsForApiKey: () => [],
listQuotaKeyModels: async () => [],
// No public API origin by default, so no test depends on the environment.
resolvePublicApiBaseUrl: () => null,
...rest,
};
}
export const PERCENT_PLAN = {
connectionId: "conn-secret-1",
provider: "claude",
dimensions: [
{ unit: "percent", window: "5h", limit: 100 },
{ unit: "percent", window: "weekly", limit: 100 },
],
source: "auto",
} as ProviderPlan;
/** By default the key may see the account data of every pool connection when visible. */
export function ctx(over: Partial<SelfViewPoolContext> = {}): SelfViewPoolContext {
const pool = basePools().find((p) => p.id === "pool-a-id") as QuotaPool;
const merged = {
pool,
allocation: pool.allocations[0],
provider: "claude",
ref: "qpr_testPoolARef0000000",
plan: PERCENT_PLAN,
effectiveWeight: 50,
connectionIds: ["conn-secret-1"],
accountVisible: true,
...over,
};
return {
...merged,
accountConnectionIds:
over.accountConnectionIds ?? (merged.accountVisible ? merged.connectionIds : []),
};
}

View File

@@ -0,0 +1,55 @@
/**
* resolvePublicApiBaseUrl: the API origin reported to key holders. The environment is passed in,
* so these tests never touch process.env.
*/
import test from "node:test";
import assert from "node:assert/strict";
import { resolvePublicApiBaseUrl } from "../../src/server/origin/publicApiBaseUrl.ts";
const r = (env: Record<string, string>) => resolvePublicApiBaseUrl(env as NodeJS.ProcessEnv);
const APP = { OMNIROUTE_PUBLIC_BASE_URL: "https://app.example.com" };
test("the API-specific origin wins, then the public base URL, then null", () => {
assert.equal(
r({ ...APP, OMNIROUTE_PUBLIC_API_BASE_URL: "https://api.example.com" }),
"https://api.example.com"
);
assert.equal(r(APP), "https://app.example.com");
assert.equal(r({ ...APP, OMNIROUTE_PUBLIC_API_BASE_URL: " " }), "https://app.example.com");
assert.equal(r({}), null);
assert.equal(r({ NEXT_PUBLIC_BASE_URL: "http://localhost:20128" }), null);
});
test("values are reduced to scheme, host and port; an invalid API origin yields null instead of falling back", () => {
assert.equal(
r({ OMNIROUTE_PUBLIC_API_BASE_URL: " HTTPS://API.Example.com:8443/v1/?x=1#f " }),
"https://api.example.com:8443"
);
for (const bad of ["not a url", "ftp://api.example.com", "javascript:alert(1)"])
assert.equal(r({ ...APP, OMNIROUTE_PUBLIC_API_BASE_URL: bad }), null);
assert.equal(
r({ OMNIROUTE_PUBLIC_API_BASE_URL: "https://u:p@api.example.com/x" }),
"https://api.example.com"
);
});
test("an invalid API origin is warned about once, by name, without its value", () => {
const warnings: Array<[Record<string, unknown>, string]> = [];
const notice = {
warned: false,
log: { warn: (f: Record<string, unknown>, m: string) => warnings.push([f, m]) },
};
const env = { ...APP, OMNIROUTE_PUBLIC_API_BASE_URL: "ftp://secret-host.example.com" };
assert.equal(resolvePublicApiBaseUrl(env, notice), null);
assert.equal(resolvePublicApiBaseUrl(env, notice), null);
assert.equal(warnings.length, 1);
assert.deepEqual(warnings[0][0], { variable: "OMNIROUTE_PUBLIC_API_BASE_URL" });
assert.ok(!JSON.stringify(warnings).includes("secret-host"));
// A valid or unset API origin never warns.
const quiet = { warned: false, log: notice.log };
resolvePublicApiBaseUrl(APP, quiet);
resolvePublicApiBaseUrl({ OMNIROUTE_PUBLIC_API_BASE_URL: "https://api.example.com" }, quiet);
assert.equal(warnings.length, 1);
});

View File

@@ -12,7 +12,9 @@
* Next.js / DOM setup, while providing strong structural coverage of:
* - Auth guard pattern (requireManagementAuth, 401 gate)
* - Error sanitization (buildErrorBody, no raw err.stack / err.message leaks)
* - Quota model resolution imports (resolveQuotaKeyScope, filterModelsToQuotaPools)
* - Quota model resolution delegated to listQuotaKeyModels
* (src/lib/quota/quotaKeyModels.ts), whose source carries the
* resolveQuotaKeyScope / filterModelsToQuotaPools / getCombos assertions
* - Response shape ({ models })
* - 404 on missing key (buildErrorBody(404, ...))
* - force-dynamic export
@@ -41,6 +43,11 @@ const ROUTE_PATH = join(ROOT, "src/app/api/quota/keys/[id]/models/route.ts");
const src = readFileSync(ROUTE_PATH, "utf8");
// The quota model listing lives in a shared helper the route calls.
const HELPER_PATH = join(ROOT, "src/lib/quota/quotaKeyModels.ts");
const helperSrc = readFileSync(HELPER_PATH, "utf8");
// ── Auth guard ────────────────────────────────────────────────────────────────
test("quota/keys/[id]/models: imports requireManagementAuth", () => {
@@ -93,32 +100,43 @@ test("quota/keys/[id]/models: does NOT leak raw err.message outside buildErrorBo
// ── Quota resolution imports ──────────────────────────────────────────────────
test("quota/keys/[id]/models: imports resolveQuotaKeyScope from @/lib/quota/quotaKey", () => {
test("quota/keys/[id]/models: imports listQuotaKeyModels from @/lib/quota/quotaKeyModels", () => {
assert.ok(
src.includes("resolveQuotaKeyScope"),
"route must call resolveQuotaKeyScope to compute pool scope"
src.includes("listQuotaKeyModels"),
"route must call listQuotaKeyModels to compute the key's models"
);
assert.ok(
src.includes("@/lib/quota/quotaKey"),
"route must import resolveQuotaKeyScope from @/lib/quota/quotaKey"
src.includes("@/lib/quota/quotaKeyModels"),
"route must import listQuotaKeyModels from @/lib/quota/quotaKeyModels"
);
});
test("quota/keys/[id]/models: imports filterModelsToQuotaPools from @/lib/quota/quotaCombos", () => {
test("quota/keys/[id]/models: helper imports resolveQuotaKeyScope from @/lib/quota/quotaKey", () => {
assert.ok(
src.includes("filterModelsToQuotaPools"),
"route must call filterModelsToQuotaPools to filter combo candidates"
helperSrc.includes("resolveQuotaKeyScope"),
"helper must call resolveQuotaKeyScope to compute pool scope"
);
assert.ok(
src.includes("@/lib/quota/quotaCombos"),
"route must import filterModelsToQuotaPools from @/lib/quota/quotaCombos"
helperSrc.includes("@/lib/quota/quotaKey"),
"helper must import resolveQuotaKeyScope from @/lib/quota/quotaKey"
);
});
test("quota/keys/[id]/models: passes scope.poolSlugs to filterModelsToQuotaPools", () => {
test("quota/keys/[id]/models: helper imports filterModelsToQuotaPools from @/lib/quota/quotaCombos", () => {
assert.ok(
src.includes("scope.poolSlugs"),
"route must pass scope.poolSlugs to filterModelsToQuotaPools (same as catalog.ts approach)"
helperSrc.includes("filterModelsToQuotaPools"),
"helper must call filterModelsToQuotaPools to filter combo candidates"
);
assert.ok(
helperSrc.includes("@/lib/quota/quotaCombos"),
"helper must import filterModelsToQuotaPools from @/lib/quota/quotaCombos"
);
});
test("quota/keys/[id]/models: helper passes scope.poolSlugs to filterModelsToQuotaPools", () => {
assert.ok(
helperSrc.includes("scope.poolSlugs"),
"helper must pass scope.poolSlugs to filterModelsToQuotaPools (same as catalog.ts approach)"
);
});
@@ -132,8 +150,11 @@ test("quota/keys/[id]/models: imports getApiKeyById from @/lib/db/apiKeys", () =
);
});
test("quota/keys/[id]/models: imports getCombos from @/lib/db/combos", () => {
assert.ok(src.includes("getCombos"), "route must call getCombos to build combo candidates");
test("quota/keys/[id]/models: helper imports getCombos from @/lib/db/combos", () => {
assert.ok(
helperSrc.includes("getCombos"),
"helper must call getCombos to build combo candidates"
);
});
// ── Response shape ────────────────────────────────────────────────────────────
@@ -145,10 +166,10 @@ test("quota/keys/[id]/models: GET returns { models } shape", () => {
);
});
test("quota/keys/[id]/models: maps filtered combos to model id strings (.map(m => m.id))", () => {
test("quota/keys/[id]/models: helper maps filtered combos to model id strings (.map(m => m.id))", () => {
assert.ok(
src.includes(".map(") && src.includes("m.id"),
"route must map filtered combo entries to their id strings"
helperSrc.includes(".map(") && helperSrc.includes("m.id"),
"helper must map filtered combo entries to their id strings"
);
});

View File

@@ -0,0 +1,66 @@
import test from "node:test";
import assert from "node:assert/strict";
import { quotaGroupSlug, quotaModelName } from "../../src/lib/quota/quotaModelNaming.ts";
import { listQuotaKeyModels } from "../../src/lib/quota/quotaKeyModels.ts";
const mine = quotaModelName("Team A", "claude", "claude-sonnet-5");
const theirs = quotaModelName("Team B", "claude", "claude-sonnet-5");
const deps = (combos: unknown, poolSlugs = [quotaGroupSlug("Team A")]) => ({
resolveQuotaKeyScope: async () => ({ poolSlugs }),
getCombos: async () => combos as Array<{ name?: unknown }>,
});
test("lists only the quota models of the key's own groups", async () => {
assert.deepEqual(
await listQuotaKeyModels(
["pool-1"],
deps([{ name: mine }, { name: theirs }, { name: "plain" }, { name: "" }, {}])
),
[mine]
);
});
test("a key without quota pools sees no models", async () => {
assert.deepEqual(await listQuotaKeyModels([], deps([{ name: mine }], [])), []);
});
test("null or undefined allowedQuotas resolve an empty scope and yield no models", async () => {
for (const allowedQuotas of [null, undefined]) {
const seen: string[][] = [];
const models = await listQuotaKeyModels(allowedQuotas, {
resolveQuotaKeyScope: async (quotas) => {
seen.push(quotas);
return { poolSlugs: quotas.length ? [quotaGroupSlug("Team A")] : [] };
},
getCombos: async () => [{ name: mine }],
});
assert.deepEqual(models, []);
assert.deepEqual(seen, [[]]);
}
});
test("a scope resolution failure propagates to the caller", async () => {
await assert.rejects(
listQuotaKeyModels(["pool-1"], {
...deps([{ name: mine }]),
resolveQuotaKeyScope: async () => {
throw new Error("scope lookup failed");
},
}),
/scope lookup failed/
);
});
test("a failed combo read yields an empty list instead of throwing", async () => {
assert.deepEqual(
await listQuotaKeyModels(["pool-1"], {
...deps([]),
getCombos: async () => {
throw new Error("db down");
},
}),
[]
);
});

View File

@@ -0,0 +1,359 @@
import test from "node:test";
import assert from "node:assert/strict";
import { buildQuotaSelfView } from "../../src/lib/quota/selfView.ts";
import { buildSelfViewAccounts } from "../../src/lib/quota/selfViewAccounts.ts";
import type { ProviderPlan } from "../../src/lib/quota/dimensions.ts";
import { BOTH, PERCENT_PLAN, ctx, input, makeDeps } from "./fixtures/quotaSelfView.ts";
const R1 = "2026-05-27T18:00:00.000Z";
const R2 = "2026-06-01T00:00:00.000Z";
/** The builder's clock: the same instant as the fixture's `now`, before R1 and R2. */
const NOW = Date.parse("2026-05-27T15:30:00.000Z");
const PAST = "2026-05-27T15:00:00.000Z";
function w(pct: number, resetAt: string | null) {
return { usedPercentage: pct, remainingPercentage: 100 - pct, resetAt };
}
const CACHE = {
"session (5h)": w(40, R1),
"weekly (7d)": w(81, R2),
"weekly fable (7d)": w(12, R2),
};
test("one neutral entry per pool connection, with account bars from the cached snapshot", () => {
const accounts = buildSelfViewAccounts(
ctx({ connectionIds: ["conn-secret-1", "conn-secret-2"] }),
[
{ connectionId: "conn-secret-1", quotas: CACHE },
{ connectionId: "conn-secret-2", quotas: CACHE, stale: true },
],
NOW
);
assert.deepEqual(
accounts.map((a) => [a.slot, a.label]),
[
[1, "Account 1"],
[2, "Account 2"],
]
);
assert.deepEqual(accounts[0].dimensions[0].account, { used: 40, status: "ok", resetAt: R1 });
assert.equal(accounts[1].dimensions[1].account?.status, "stale");
assert.deepEqual(accounts[0].modelWindows, {
status: "ok",
windows: [{ label: "weekly fable (7d)", usedPercent: 12, resetAt: R2 }],
});
assert.deepEqual(accounts[0].dimensions[0].yourShare, {
fairShare: 50,
consumed: null,
remaining: null,
status: "unavailable",
reason: "percent_attribution_unavailable",
});
});
test("an unavailable, missing or unmapped account window is flagged, not zeroed", () => {
const failed = buildSelfViewAccounts(
ctx(),
[{ connectionId: "conn-secret-1", available: false, reason: "fetch_failed" }],
NOW
);
assert.deepEqual(failed[0].dimensions[0].account, {
used: null,
status: "unavailable",
reason: "fetch_failed",
});
const absent = buildSelfViewAccounts(
ctx({ connectionIds: ["conn-secret-1", "conn-secret-2"] }),
[{ connectionId: "conn-secret-2", quotas: CACHE }],
NOW
);
assert.deepEqual([absent[0].dimensions[0].account?.reason, absent[1].slot], ["not_available", 2]);
assert.equal(absent[1].dimensions[0].account?.used, 40);
const bailian = buildSelfViewAccounts(
ctx({ provider: "bailian" }),
[{ connectionId: "conn-secret-1", quotas: { other: w(5, null) } }],
NOW
);
assert.equal(bailian[0].dimensions[0].account?.reason, "window_not_reported");
});
test("hidden account data leaves no account bar and no model windows", () => {
const [a] = buildSelfViewAccounts(ctx(), null, NOW);
assert.deepEqual(["account" in a.dimensions[0], "modelWindows" in a], [false, false]);
});
test("only the pool's own connections are ever asked for, and only for a key allowed to see them", async () => {
const asked: string[][] = [];
const resolveAccountQuotaEntries = async (m: { allowedConnections: string[] }) => {
asked.push(m.allowedConnections);
return [
{ connectionId: "conn-secret-1", quotas: CACHE },
{ connectionId: "someone-else", quotas: CACHE },
];
};
const deps = makeDeps({
pool: { connectionIds: [] },
plan: PERCENT_PLAN,
resolveAccountQuotaEntries,
});
const view = await buildQuotaSelfView(input({ scopes: BOTH }), deps);
assert.deepEqual(asked, [["conn-secret-1"], ["conn-secret-1"]]); // two claude pools; never an empty list
assert.equal(view.pools[0].accounts.length, 1);
asked.length = 0;
const hidden = await buildQuotaSelfView(input(), deps);
assert.deepEqual([asked.length, hidden.pools[0].accounts.length], [0, 1]);
assert.ok(!JSON.stringify(view).includes("conn-secret-1"));
});
test("a pool with no usable connection id never asks with an empty list", async () => {
const asked: string[][] = [];
const deps = makeDeps({
pool: { connectionIds: [], connectionId: "" },
plan: PERCENT_PLAN,
resolveConnectionProvider: async () => "unknown",
resolveAccountQuotaEntries: async (m) => {
asked.push(m.allowedConnections);
return [{ connectionId: "conn-secret-1", quotas: CACHE }];
},
});
const view = await buildQuotaSelfView(input({ scopes: BOTH }), deps);
assert.deepEqual(asked, []);
assert.equal(view.pools.length, 2);
assert.deepEqual(view.pools[0].accounts[0].dimensions[0].account, {
used: null,
status: "unavailable",
reason: "not_available",
});
});
test("a provider that is not shared hides account data and is not asked for", async () => {
let calls = 0;
const deps = makeDeps({
plan: PERCENT_PLAN,
resolveAccountQuotaEntries: async () => {
calls += 1;
return [{ connectionId: "conn-secret-1", quotas: CACHE }];
},
});
const view = await buildQuotaSelfView(
input({ scopes: BOTH, sharedQuotaProviders: ["codex"] }),
deps
);
assert.equal(calls, 0);
const [account] = view.pools[0].accounts;
assert.deepEqual(["account" in account.dimensions[0], "modelWindows" in account], [false, false]);
});
test("a failed account lookup is reported as unavailable for every account", async () => {
const deps = makeDeps({
plan: PERCENT_PLAN,
resolveAccountQuotaEntries: async () => {
throw new Error("conn-secret-1 lookup failed");
},
});
const view = await buildQuotaSelfView(input({ scopes: BOTH }), deps);
const [account] = view.pools[0].accounts;
assert.deepEqual(account.dimensions[0].account, {
used: null,
status: "unavailable",
reason: "not_available",
});
assert.deepEqual(account.modelWindows, {
status: "unavailable",
reason: "not_available",
windows: [],
});
assert.ok(!JSON.stringify(view).includes("conn-secret-1"));
});
test("an account dimension uses the plan limit of one account and skips placeholders", () => {
const plan = {
...PERCENT_PLAN,
dimensions: [
{ unit: "percent", window: "5h", limit: 100 },
{ unit: "percent", window: "weekly", limit: Number.EPSILON },
{ unit: "tokens", window: "daily", limit: 1000 },
],
} as ProviderPlan;
const accounts = buildSelfViewAccounts(
ctx({ plan, connectionIds: ["conn-secret-1", "conn-secret-2", "conn-secret-4"] }),
[{ connectionId: "conn-secret-1", quotas: CACHE }],
NOW
);
assert.equal(accounts.length, 3);
assert.deepEqual(
accounts[0].dimensions.map((d) => [d.unit, d.window, d.limit]),
[["percent", "5h", 100]]
);
assert.equal(accounts[0].dimensions[0].yourShare.fairShare, 50);
});
test("codex windows map to its own cache keys; a non-finite reading is not reported", () => {
const [codex] = buildSelfViewAccounts(
ctx({ provider: "codex" }),
[
{
connectionId: "conn-secret-1",
quotas: { session: w(25, R1), weekly: w(Number.NaN, R2), "gpt-5 weekly": w(3, R2) },
},
],
NOW
);
assert.deepEqual(codex.dimensions[0].account, { used: 25, status: "ok", resetAt: R1 });
assert.deepEqual(codex.dimensions[1].account, {
used: null,
status: "unavailable",
reason: "window_not_reported",
});
assert.deepEqual(
codex.modelWindows?.windows.map((x) => x.label),
["gpt-5 weekly"]
);
});
test("an unexpected entry reason is replaced by a fixed one", () => {
const [account] = buildSelfViewAccounts(
ctx(),
[{ connectionId: "conn-secret-1", available: false, reason: "lookup of conn-secret-1 failed" }],
NOW
);
assert.equal(account.dimensions[0].account?.reason, "not_available");
assert.equal(account.modelWindows?.reason, "not_available");
});
test("a provider without a plan-window mapping reports no model windows and copies no label", async () => {
const quotas = { "key:alice-prod": w(10, R1), "upstream-limit-7f3a9c": w(20, R2) };
const deps = makeDeps({
plan: PERCENT_PLAN,
resolveConnectionProvider: async () => "tokenrouter",
resolveAccountQuotaEntries: async () => [{ connectionId: "conn-secret-1", quotas }],
});
const view = await buildQuotaSelfView(input({ provider: "tokenrouter", scopes: BOTH }), deps);
const [account] = view.pools[0].accounts;
assert.deepEqual(account.modelWindows, { status: "ok", windows: [] });
const serialized = JSON.stringify(view);
assert.ok(!serialized.includes("key:alice-prod"));
assert.ok(!serialized.includes("upstream-limit-7f3a9c"));
const [direct] = buildSelfViewAccounts(
ctx({ provider: "megabrain" }),
[{ connectionId: "conn-secret-1", quotas, stale: true }],
NOW
);
assert.deepEqual(direct.modelWindows, { status: "stale", windows: [] });
});
test("a reading whose reset time already passed is stale, with its numbers kept", () => {
const reading = (resetAt: string | null) => ({
"session (5h)": w(40, resetAt),
"weekly (7d)": w(81, R2),
"weekly fable (7d)": w(12, resetAt),
});
const [past] = buildSelfViewAccounts(
ctx(),
[{ connectionId: "conn-secret-1", quotas: reading(PAST) }],
NOW
);
assert.deepEqual(past.dimensions[0].account, { used: 40, status: "stale", resetAt: PAST });
assert.deepEqual(past.dimensions[1].account, { used: 81, status: "ok", resetAt: R2 });
assert.deepEqual(past.modelWindows, {
status: "stale",
windows: [{ label: "weekly fable (7d)", usedPercent: 12, resetAt: PAST }],
});
const [future] = buildSelfViewAccounts(
ctx(),
[{ connectionId: "conn-secret-1", quotas: reading(R1) }],
NOW
);
assert.deepEqual(future.dimensions[0].account, { used: 40, status: "ok", resetAt: R1 });
assert.equal(future.modelWindows?.status, "ok");
const [alreadyStale] = buildSelfViewAccounts(
ctx(),
[{ connectionId: "conn-secret-1", quotas: reading(PAST), stale: true }],
NOW
);
assert.deepEqual(alreadyStale.dimensions[0].account, {
used: 40,
status: "stale",
resetAt: PAST,
});
assert.equal(alreadyStale.modelWindows?.status, "stale");
const [unparseable] = buildSelfViewAccounts(
ctx(),
[{ connectionId: "conn-secret-1", quotas: reading("not a date") }],
NOW
);
assert.equal(unparseable.dimensions[0].account?.status, "ok");
assert.equal(unparseable.modelWindows?.status, "ok");
});
test("two entries for the same connection: the first one wins", () => {
const [account] = buildSelfViewAccounts(
ctx(),
[
{ connectionId: "conn-secret-1", quotas: { "session (5h)": w(40, R1) } },
{ connectionId: "conn-secret-1", quotas: { "session (5h)": w(90, R1) } },
],
NOW
);
assert.deepEqual(account.dimensions[0].account, { used: 40, status: "ok", resetAt: R1 });
});
/** Two-account pools, an account lookup that records what it is asked for, both scopes. */
async function viewWithAllowedConnections(allowedConnections: string[] | undefined) {
const asked: string[][] = [];
const deps = makeDeps({
pool: { connectionIds: ["conn-secret-1", "conn-secret-2"] },
plan: PERCENT_PLAN,
resolveAccountQuotaEntries: async (m) => {
asked.push(m.allowedConnections);
return m.allowedConnections.map((connectionId) => ({ connectionId, quotas: CACHE }));
},
});
const view = await buildQuotaSelfView(input({ scopes: BOTH, allowedConnections }), deps);
return { asked, accounts: view.pools[0].accounts };
}
const hasAccountData = (account: { dimensions: object[]; modelWindows?: object }) =>
"modelWindows" in account || account.dimensions.some((d) => "account" in d);
test("a key's allowed connections limit its account bars; other accounts keep their entry", async () => {
const { asked, accounts } = await viewWithAllowedConnections(["conn-secret-2", "conn-other"]);
assert.deepEqual(asked, [["conn-secret-2"], ["conn-secret-2"]]);
assert.deepEqual(
accounts.map((a) => [a.label, hasAccountData(a)]),
[
["Account 1", false],
["Account 2", true],
]
);
assert.equal(accounts[1].dimensions[0].account?.used, 40);
});
test("an absent or empty allowed-connections list is no restriction, as in /v1/me/status", async () => {
for (const allowed of [undefined, []]) {
const { asked, accounts } = await viewWithAllowedConnections(allowed);
assert.deepEqual(asked[0], ["conn-secret-1", "conn-secret-2"]);
assert.deepEqual(
accounts.map((a) => hasAccountData(a)),
[true, true]
);
}
});
test("allowed connections that exclude every pool account ask for nothing and show no bar", async () => {
const { asked, accounts } = await viewWithAllowedConnections(["conn-other"]);
assert.deepEqual(asked, []);
assert.deepEqual(
accounts.map((a) => [a.label, hasAccountData(a)]),
[
["Account 1", false],
["Account 2", false],
]
);
});

View File

@@ -0,0 +1,315 @@
/**
* The `blocks` part of the self-service quota view (schedule windows and per-model caps), the
* key's models and expiry, and listModelCapsForApiKey against a real database in a temporary
* DATA_DIR of this file's own (set before any module that can open the database is imported).
*/
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import type { ModelCap } from "../../src/lib/db/quotaModelCaps.ts";
import type { QuotaSchedule } from "../../src/lib/quota/schedules.ts";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-quota-self-view-blocks-"));
process.env.DATA_DIR = TEST_DATA_DIR;
const core = await import("../../src/lib/db/core.ts");
const { listModelCapsForApiKey, setModelCap } = await import("../../src/lib/db/quotaModelCaps.ts");
const { buildSelfViewBlocks } = await import("../../src/lib/quota/selfViewBlocks.ts");
const { buildQuotaSelfView } = await import("../../src/lib/quota/selfView.ts");
const { ctx, input, makeDeps } = await import("./fixtures/quotaSelfView.ts");
test.after(() => {
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
const NOW = Date.UTC(2026, 4, 27, 15, 30);
function sched(over: Partial<QuotaSchedule>): QuotaSchedule {
return {
id: "s0",
poolId: "pool-a-id",
days: [0, 1, 2, 3, 4, 5, 6],
startMinute: 0,
endMinute: 1440,
timezone: "UTC",
mode: "allow",
reserves: [],
budgetWindow: "daily",
priority: 0,
enabled: true,
...over,
};
}
function cap(model: string, capValue: number, capUnit: ModelCap["capUnit"]): ModelCap {
return { poolId: "pool-a-id", apiKeyId: "key-a", model, capValue, capUnit };
}
function deps(
over: {
schedules?: QuotaSchedule[];
caps?: ModelCap[];
peek?: () => Promise<number>;
poolConsumedTotal?: () => Promise<number>;
} = {}
) {
return {
now: () => NOW,
listEnabledSchedules: () => over.schedules ?? [],
listModelCapsForApiKey: () => over.caps ?? [],
getQuotaStore: async () => ({
peek: over.peek ?? (async () => 0),
poolConsumedTotal: over.poolConsumedTotal ?? (async () => 0),
}),
};
}
const fail = async (): Promise<number> => {
throw new Error("x");
};
test("a pool without schedules or caps reports nothing", async () => {
assert.deepEqual(await buildSelfViewBlocks("key-a", [ctx()], deps()), {
schedules: [],
modelCaps: [],
});
});
test("a closed window says why and when it reopens; a blackout wins over an open window", async () => {
const [outside] = (
await buildSelfViewBlocks(
"key-a",
[ctx()],
deps({ schedules: [sched({ endMinute: 60, label: "night" })] })
)
).schedules;
assert.deepEqual(
[outside.state, outside.reason, outside.label],
["closed", "outside-window", null]
);
assert.ok((outside.retryAfterSeconds ?? 0) > 0);
assert.deepEqual([outside.reserves, outside.budget], [[], null]);
const [blackout] = (
await buildSelfViewBlocks(
"key-a",
[ctx()],
deps({ schedules: [sched({}), sched({ id: "s1", mode: "block", label: "freeze" })] })
)
).schedules;
assert.deepEqual([blackout.reason, blackout.label], ["blackout", "freeze"]);
});
test("an open window reports its reserves and whether its budget is spent", async () => {
const s = sched({
reserves: [{ window: "weekly", percent: 20 }],
budgetValue: 100,
budgetUnit: "requests",
});
let budgetKey: unknown;
const spent = await buildSelfViewBlocks(
"key-a",
[ctx()],
deps({
schedules: [s],
poolConsumedTotal: async (...args: unknown[]) => {
budgetKey = args;
return 100;
},
})
);
assert.deepEqual(spent.schedules[0], {
pool: ctx().ref,
state: "open",
reason: null,
label: null,
retryAfterSeconds: null,
reserves: [{ window: "weekly", percent: 20 }],
budget: { unit: "requests", window: "daily", exhausted: true },
});
// The schedule's own budget bucket, as the quota gate reads it.
assert.deepEqual(budgetKey, [
"pool-a-id",
{ poolId: "pool-a-id:sched:s0", unit: "requests", window: "daily" },
]);
const broken = await buildSelfViewBlocks(
"key-a",
[ctx()],
deps({ schedules: [s], poolConsumedTotal: fail })
);
assert.equal(broken.schedules[0].budget?.exhausted, null);
});
test("model caps list the key's own caps with consumption; placeholders are skipped", async () => {
const caps = [
cap("claude-fable-5", 50, "requests"),
cap("claude-haiku-5", Number.EPSILON, "requests"),
];
let capKey: unknown;
const out = await buildSelfViewBlocks(
"key-a",
[ctx()],
deps({
caps,
peek: async (...args: unknown[]) => {
capKey = args;
return 50;
},
})
);
assert.deepEqual(out.modelCaps, [
{
pool: ctx().ref,
model: "claude-fable-5",
unit: "requests",
window: "hourly",
cap: 50,
consumed: 50,
reached: true,
},
]);
// The per-model bucket of this key, as the quota gate reads it.
assert.deepEqual(capKey, [
"key-a",
{ poolId: "pool-a-id:model:claude-fable-5", unit: "requests", window: "hourly" },
]);
const failed = await buildSelfViewBlocks("key-a", [ctx()], deps({ caps, peek: fail }));
assert.deepEqual([failed.modelCaps[0].consumed, failed.modelCaps[0].reached], [null, null]);
});
test("a failed schedule or cap lookup, or a failed store load, never throws", async () => {
const throwing = {
...deps(),
listEnabledSchedules: (): QuotaSchedule[] => {
throw new Error("db down");
},
listModelCapsForApiKey: (): ModelCap[] => {
throw new Error("db down");
},
};
assert.deepEqual(await buildSelfViewBlocks("key-a", [ctx()], throwing), {
schedules: [],
modelCaps: [],
});
const noStore = {
...deps({
schedules: [sched({ budgetValue: 5, budgetUnit: "tokens" })],
caps: [cap("claude-fable-5", 50, "requests")],
}),
getQuotaStore: async (): Promise<never> => {
throw new Error("store init failed");
},
};
const out = await buildSelfViewBlocks("key-a", [ctx()], noStore);
assert.equal(out.schedules[0].budget?.exhausted, null);
assert.deepEqual([out.modelCaps[0].consumed, out.modelCaps[0].reached], [null, null]);
});
test("listModelCapsForApiKey returns one key's caps in one pool, ordered by model", () => {
for (const [poolId, apiKeyId, model, capValue] of [
["p1", "key-a", "m-b", 5],
["p1", "key-a", "m-a", 9],
["p1", "key-b", "m-a", 1],
["p2", "key-a", "m-z", 1],
] as const)
setModelCap({ poolId, apiKeyId, model, capValue, capUnit: "tokens" });
assert.deepEqual(
listModelCapsForApiKey("p1", "key-a").map((c) => [c.model, c.capValue]),
[
["m-a", 9],
["m-b", 5],
]
);
});
test("the view carries the key's models and expiry", async () => {
const view = await buildQuotaSelfView(
input({ expiresAt: "2026-12-01T02:59:59.000Z", allowedQuotas: ["pool-a-id"] }),
makeDeps({ listQuotaKeyModels: async () => ["qtSd/teama/claude/claude-sonnet-5"] })
);
assert.deepEqual(
[view.availableModels, view.expiresAt],
[["qtSd/teama/claude/claude-sonnet-5"], "2026-12-01T02:59:59.000Z"]
);
const failed = await buildQuotaSelfView(
input(),
makeDeps({
listQuotaKeyModels: async () => {
throw new Error("db down");
},
})
);
assert.deepEqual(failed.availableModels, []);
});
test("the view loads the quota store once and the blocks reuse it", async () => {
let loads = 0;
const store = { peek: async () => 7, poolConsumedTotal: async () => 0 };
const view = await buildQuotaSelfView(
input(),
makeDeps({
getQuotaStore: async () => {
loads += 1;
return store;
},
listModelCapsForApiKey: (poolId) =>
poolId === "pool-a-id" ? [cap("m-x", 10, "tokens")] : [],
})
);
assert.equal(loads, 1);
assert.deepEqual(
[view.pools[0].dimensions[0].yourShare.consumed, view.blocks.modelCaps[0].consumed],
[7, 7]
);
});
test("the view's default lookups read each pool's caps of this key only, under that pool's own ref", async () => {
// Rows this test needs, with model names no other test uses.
const rows: Array<[string, string, string, number]> = [
["pool-a-id", "key-a", "e2e-model-in-a", 200],
["pool-b-id", "key-a", "e2e-model-in-b", 300],
["pool-a-id", "key-b", "e2e-other-key-model", 7],
["pool-codex-id", "key-a", "e2e-other-provider-model", 9],
["pool-unallocated-id", "key-a", "e2e-unallocated-pool-model", 11],
];
for (const [poolId, apiKeyId, model, capValue] of rows)
setModelCap({ poolId, apiKeyId, model, capValue, capUnit: "requests" });
const view = await buildQuotaSelfView(
input(),
makeDeps({ listEnabledSchedules: undefined, listModelCapsForApiKey: undefined })
);
const refOf = (name: string) => view.pools.find((p) => p.name === name)?.ref;
assert.ok(refOf("Pool A") && refOf("Pool B") && refOf("Pool A") !== refOf("Pool B"));
const entry = (pool: string | undefined, model: string, capValue: number) => ({
pool,
model,
unit: "requests",
window: "hourly",
cap: capValue,
consumed: 120,
reached: capValue <= 120,
});
// Pools in view order (Pool A, then Pool B); each cap only under its own pool's ref.
assert.deepEqual(view.blocks, {
schedules: [],
modelCaps: [
entry(refOf("Pool A"), "e2e-model-in-a", 200),
entry(refOf("Pool B"), "e2e-model-in-b", 300),
],
});
const json = JSON.stringify(view);
for (const secret of [
"pool-a-id",
"pool-b-id",
"key-b",
"e2e-other-key-model",
"e2e-other-provider-model",
"e2e-unallocated-pool-model",
])
assert.ok(!json.includes(secret), secret);
});

View File

@@ -0,0 +1,71 @@
/**
* Runs buildQuotaSelfView with its DEFAULT account lookup (the real provider and provider-limits
* modules plus the shared refresh tracker), against a temporary DATA_DIR of its own (set before
* any module that can open the database is imported, so the file is safe to run on its own).
* A fresh cached reading must be served as is, without any refresh attempt.
*/
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-quota-self-view-loader-"));
process.env.DATA_DIR = TEST_DATA_DIR;
const coreDb = await import("../../src/lib/db/core.ts");
const { createProviderConnection } = await import("../../src/lib/db/providers.ts");
const { setProviderLimitsCache } = await import("../../src/lib/db/providerLimits.ts");
const { defaultQuotaRefreshTracker } =
await import("../../src/lib/usage/apiKeySelfServiceAccounts.ts");
const { buildQuotaSelfView } = await import("../../src/lib/quota/selfView.ts");
const { BOTH, PERCENT_PLAN, input, makeDeps } = await import("./fixtures/quotaSelfView.ts");
const nowMs = Date.now();
const resetAt = new Date(nowMs + 60 * 60_000).toISOString();
const connection = await createProviderConnection({
provider: "claude",
authType: "oauth",
name: "Self-service quota view default loader fixture",
accessToken: "test-oauth-token",
isActive: true,
testStatus: "active",
});
const connectionId = (connection as { id?: string }).id ?? "";
setProviderLimitsCache(connectionId, {
quotas: { "session (5h)": { usedPercentage: 37, remainingPercentage: 63, resetAt } },
plan: null,
message: null,
fetchedAt: new Date(nowMs).toISOString(),
source: "sync",
});
test.after(() => {
coreDb.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
test("the default account lookup serves a fresh cached reading without a refresh", async () => {
assert.ok(connectionId, "fixture connection created");
const deps = makeDeps({
now: () => nowMs,
pool: { connectionId, connectionIds: [connectionId] },
plan: PERCENT_PLAN,
resolveConnectionProvider: async () => "claude",
// An explicit undefined replaces the fixture's stub, so the builder loads its default lookup.
resolveAccountQuotaEntries: undefined,
});
const view = await buildQuotaSelfView(input({ scopes: BOTH }), deps);
assert.equal(view.pools.length, 2);
for (const pool of view.pools) {
assert.deepEqual(pool.accounts[0].dimensions[0].account, { used: 37, status: "ok", resetAt });
}
assert.equal(defaultQuotaRefreshTracker.lastAttempt.has(connectionId), false);
assert.equal(defaultQuotaRefreshTracker.inFlight.size, 0);
assert.ok(!JSON.stringify(view).includes(connectionId));
});

View File

@@ -0,0 +1,225 @@
import test from "node:test";
import assert from "node:assert/strict";
import { buildQuotaSelfView } from "../../src/lib/quota/selfView.ts";
import { selfQuotaResponseSchema } from "../../src/shared/schemas/selfQuota.ts";
import type { QuotaSchedule } from "../../src/lib/quota/schedules.ts";
import { BOTH, alloc, input, makeDeps } from "./fixtures/quotaSelfView.ts";
/** Open every day, all day (UTC), with a token budget: its state never depends on the clock. */
const BUDGET_SCHEDULE: QuotaSchedule = {
id: "s-budget",
poolId: "pool-a-id",
days: [0, 1, 2, 3, 4, 5, 6],
startMinute: 0,
endMinute: 1440,
timezone: "UTC",
mode: "allow",
reserves: [],
budgetValue: 5,
budgetUnit: "tokens",
budgetWindow: "daily",
priority: 0,
enabled: true,
};
test("returns every pool of the provider the key is allocated in, under either provider name", async () => {
const view = await buildQuotaSelfView(input(), makeDeps());
assert.deepEqual(
view.pools.map((p) => p.name),
["Pool A", "Pool B"]
);
assert.equal(new Set(view.pools.map((p) => p.ref)).size, 2);
assert.ok(view.pools.every((p) => p.borrowMode === "saturation" && p.provider === "claude"));
assert.equal(
(await buildQuotaSelfView(input({ provider: "anthropic" }), makeDeps())).pools.length,
2
);
});
test("a pool of another provider is left out even when the key is allocated in it", async () => {
const deps = makeDeps({ pool: { allocations: [alloc("key-a", 50), alloc("key-b", 50)] } });
assert.deepEqual(
(await buildQuotaSelfView(input(), deps)).pools.map((p) => p.name),
["Pool A", "Pool B"]
);
const codex = await buildQuotaSelfView(input({ provider: "codex" }), deps);
assert.deepEqual(
codex.pools.map((p) => [p.name, p.provider]),
[["Pool C", "codex"]]
);
assert.equal(codex.provider, "codex");
});
test("a countable window uses the pool bucket and the gate's limit (plan limit x accounts)", async () => {
const deps = makeDeps({
pool: {
connectionIds: ["conn-secret-1", "conn-secret-2"],
allocations: [alloc("key-a", 25), alloc("key-b", 75)],
},
});
const [dim] = (await buildQuotaSelfView(input({ scopes: BOTH }), deps)).pools[0].dimensions;
assert.equal(dim.limit, 2000);
assert.deepEqual(dim.yourShare, { fairShare: 500, consumed: 120, remaining: 380, status: "ok" });
assert.deepEqual(dim.total, { used: 400, status: "ok" });
});
test("the pool total is hidden without self:account-quota or when the provider is not shared", async () => {
const noScope = (await buildQuotaSelfView(input(), makeDeps())).pools[0];
assert.equal(noScope.accountVisible, false);
assert.equal("total" in noScope.dimensions[0], false);
const notShared = (
await buildQuotaSelfView(input({ scopes: BOTH, sharedQuotaProviders: ["codex"] }), makeDeps())
).pools[0];
assert.equal("total" in notShared.dimensions[0], false);
});
test("both scopes with an empty sharing list see no account-level field", async () => {
const [pool] = (
await buildQuotaSelfView(input({ scopes: BOTH, sharedQuotaProviders: [] }), makeDeps())
).pools;
assert.deepEqual([pool.accountVisible, "total" in pool.dimensions[0]], [false, false]);
assert.equal("modelWindows" in pool.accounts[0], false);
});
test("both scopes with the pool's provider in the sharing list see the account-level fields", async () => {
const [pool] = (
await buildQuotaSelfView(input({ scopes: BOTH, sharedQuotaProviders: ["claude"] }), makeDeps())
).pools;
assert.deepEqual([pool.accountVisible, "total" in pool.dimensions[0]], [true, true]);
assert.equal("modelWindows" in pool.accounts[0], true);
});
test("a failed store read is unavailable, never zero", async () => {
const deps = makeDeps({
store: {
peek: async () => {
throw new Error("redis down");
},
},
});
assert.deepEqual((await buildQuotaSelfView(input(), deps)).pools[0].dimensions[0].yourShare, {
fairShare: 500,
consumed: null,
remaining: null,
status: "unavailable",
reason: "store_unavailable",
});
});
test("a non-finite store read is unavailable, never a number", async () => {
const deps = makeDeps({ store: { peek: async () => Number.NaN } });
assert.deepEqual((await buildQuotaSelfView(input(), deps)).pools[0].dimensions[0].yourShare, {
fairShare: 500,
consumed: null,
remaining: null,
status: "unavailable",
reason: "store_unavailable",
});
});
test("with every provider shared (null) and both scopes, the pool total is visible", async () => {
const view = await buildQuotaSelfView(
input({ scopes: BOTH, sharedQuotaProviders: null }),
makeDeps()
);
assert.equal(view.pools[0].accountVisible, true);
assert.deepEqual(view.pools[0].dimensions[0].total, { used: 400, status: "ok" });
});
test("a failed pool total or store load is unavailable too", async () => {
const unavailable = { used: null, status: "unavailable", reason: "store_unavailable" };
const failedTotal = makeDeps({
store: {
poolConsumedTotal: async () => {
throw new Error("redis down");
},
},
});
const [dim] = (await buildQuotaSelfView(input({ scopes: BOTH }), failedTotal)).pools[0]
.dimensions;
assert.deepEqual(dim.total, unavailable);
assert.equal(dim.yourShare.status, "ok");
// Pool A also carries an open schedule with a budget and a model cap: both read the same
// (failed) store load, so their store-backed fields must be unknown, never false or 0.
const noStore = makeDeps({
getQuotaStore: async () => {
throw new Error("store init failed");
},
listEnabledSchedules: (poolId) => (poolId === "pool-a-id" ? [BUDGET_SCHEDULE] : []),
listModelCapsForApiKey: (poolId, apiKeyId) =>
poolId === "pool-a-id"
? [{ poolId, apiKeyId, model: "claude-fable-5", capValue: 50, capUnit: "requests" }]
: [],
});
const view = await buildQuotaSelfView(input({ scopes: BOTH }), noStore);
const [lost] = view.pools[0].dimensions;
assert.deepEqual(lost.total, unavailable);
assert.deepEqual(
[lost.yourShare.consumed, lost.yourShare.remaining, lost.yourShare.status],
[null, null, "unavailable"]
);
assert.deepEqual(
view.blocks.schedules.map((s) => [s.state, s.budget]),
[["open", { unit: "tokens", window: "daily", exhausted: null }]]
);
assert.deepEqual(
view.blocks.modelCaps.map((c) => [c.model, c.consumed, c.reached]),
[["claude-fable-5", null, null]]
);
});
test("needs the pool-ref secret as an input", async () => {
await assert.rejects(
buildQuotaSelfView(input(), makeDeps({ secret: undefined })),
/missing_pool_ref_secret/
);
});
test("all-zero weights split equally, as the gate does", async () => {
const deps = makeDeps({
pool: { allocations: ["key-a", "key-b", "key-c", "key-d"].map((k) => alloc(k, 0)) },
});
const pool = (await buildQuotaSelfView(input(), deps)).pools[0];
assert.deepEqual([pool.weight, pool.dimensions[0].yourShare.fairShare], [25, 250]);
});
test("placeholder and empty plans list the pool with no dimensions", async () => {
for (const dimensions of [[], [{ unit: "tokens", window: "5h", limit: Number.EPSILON }]])
assert.deepEqual(
(await buildQuotaSelfView(input(), makeDeps({ plan: { dimensions } }))).pools[0].dimensions,
[]
);
});
test("a pool whose connection is gone uses the plan's provider, or is skipped", async () => {
const gone = { resolveConnectionProvider: async () => "unknown" };
assert.equal(
(await buildQuotaSelfView(input(), makeDeps({ ...gone, plan: { provider: "claude" } }))).pools
.length,
2
);
assert.deepEqual(
(await buildQuotaSelfView(input(), makeDeps({ ...gone, plan: { provider: "unknown" } }))).pools,
[]
);
});
test("refuses a key without self:usage and never leaks internal ids", async () => {
await assert.rejects(
buildQuotaSelfView(input({ scopes: [] }), makeDeps()),
/missing_self_usage_scope/
);
const json = JSON.stringify(await buildQuotaSelfView(input({ scopes: BOTH }), makeDeps()));
for (const secret of ["pool-a-id", "pool-b-id", "conn-secret-1", "poolId", "connectionId"])
assert.ok(!json.includes(secret));
// Ids of the other keys allocated in the same pools never appear either.
for (const otherKey of ["key-b", "key-c"]) assert.ok(!json.includes(otherKey));
assert.doesNotThrow(() => selfQuotaResponseSchema.parse(JSON.parse(json)));
});
test("the view reports the public API origin it is given, or null", async () => {
const deps = makeDeps({ resolvePublicApiBaseUrl: () => "https://api.example.com" });
assert.equal((await buildQuotaSelfView(input(), deps)).apiBaseUrl, "https://api.example.com");
assert.equal((await buildQuotaSelfView(input(), makeDeps())).apiBaseUrl, null);
});

View File

@@ -0,0 +1,136 @@
import test from "node:test";
import assert from "node:assert/strict";
import { buildPoolRef } from "../../src/lib/quota/selfPoolRef.ts";
import { selfQuotaResponseSchema } from "../../src/shared/schemas/selfQuota.ts";
const POOL = "0b6c3f0e-1111-4222-8333-444455556666";
test("pool ref is opaque, stable, and bound to the key, the pool and the server secret", () => {
const a = buildPoolRef("key-a", POOL, "s3cret");
assert.match(a, /^qpr_[0-9a-f]{32}$/);
assert.equal(a, buildPoolRef("key-a", POOL, "s3cret"));
for (const other of [
buildPoolRef("key-b", POOL, "s3cret"),
buildPoolRef("key-a", "another", "s3cret"),
buildPoolRef("key-a", POOL, "x"),
])
assert.notEqual(a, other);
assert.ok(!a.includes("0b6c3f0e"));
assert.throws(() => buildPoolRef("key-a", POOL, ""));
assert.notEqual(buildPoolRef("k\u0000x", "y", "s3cret"), buildPoolRef("k", "x\u0000y", "s3cret"));
});
test("the response schema drops keys outside the contract and rejects an unknown borrow mode", () => {
const base = {
provider: "claude",
generatedAt: "2026-05-27T15:30:00.000Z",
pools: [],
availableModels: [],
expiresAt: null,
apiBaseUrl: null,
blocks: { schedules: [], modelCaps: [] },
};
assert.deepEqual(
selfQuotaResponseSchema.parse({ ...base, poolId: "leak", connectionId: "leak" }),
base
);
const badPool = {
ref: "qpr_x",
name: "p",
provider: "claude",
borrowMode: "consent",
policy: "hard",
weight: 50,
cap: null,
accountVisible: false,
dimensions: [],
accounts: [],
};
assert.throws(() => selfQuotaResponseSchema.parse({ ...base, pools: [badPool] }));
});
test("the response schema drops leaked keys at every nesting level", () => {
const leak = { poolId: "leak-pool", connectionId: "leak-conn", email: "leak@example.com" };
const share = { fairShare: 50, consumed: 10, remaining: 40, status: "ok" };
const clean = {
provider: "claude",
generatedAt: "2026-05-27T15:30:00.000Z",
pools: [
{
ref: "qpr_x",
name: "p",
provider: "claude",
borrowMode: "saturation",
policy: "hard",
weight: 50,
cap: null,
accountVisible: true,
dimensions: [
{
unit: "tokens",
window: "daily",
limit: 100,
total: { used: 20, status: "ok" },
yourShare: share,
},
],
accounts: [
{
slot: 1,
label: "Account 1",
dimensions: [
{
unit: "percent",
window: "5h",
limit: 100,
account: { used: 30, status: "ok", resetAt: null },
yourShare: share,
},
],
},
],
},
],
availableModels: [],
expiresAt: null,
apiBaseUrl: null,
blocks: {
schedules: [
{
pool: "qpr_x",
state: "open",
reason: null,
label: null,
retryAfterSeconds: null,
reserves: [],
budget: null,
},
],
modelCaps: [],
},
};
const [pool] = clean.pools;
const leaky = {
...clean,
pools: [
{
...pool,
...leak,
dimensions: [{ ...pool.dimensions[0], ...leak }],
accounts: [
{
...pool.accounts[0],
...leak,
dimensions: [{ ...pool.accounts[0].dimensions[0], ...leak }],
},
],
},
],
blocks: { ...clean.blocks, schedules: [{ ...clean.blocks.schedules[0], ...leak }] },
};
const parsed = selfQuotaResponseSchema.parse(leaky);
assert.deepEqual(parsed, clean);
const json = JSON.stringify(parsed);
for (const value of Object.values(leak)) assert.ok(!json.includes(value));
});

View File

@@ -0,0 +1,156 @@
// Unit tests for the self-service authentication gate used by the /v1/me/quota route: flag,
// header credentials, key validation, key metadata and scope.
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-self-service-auth-"));
process.env.DATA_DIR = TEST_DATA_DIR;
process.env.API_KEY_SECRET = "test-secret-at-least-32-chars-long-0123456789";
const core = await import("../../src/lib/db/core.ts");
const apiKeysDb = await import("../../src/lib/db/apiKeys.ts");
const { SELF_USAGE_SCOPE } = await import("../../src/shared/constants/selfServiceScopes.ts");
const { authenticateSelfServiceRequest } = await import("../../src/server/selfService/auth.ts");
type SelfServiceKeyStore = import("../../src/server/selfService/auth.ts").SelfServiceKeyStore;
test.after(() => {
delete process.env.QUOTA_SELF_PANEL;
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
let scoped = { id: "", key: "" };
let unscoped = { id: "", key: "" };
test.before(async () => {
const a = await apiKeysDb.createApiKey("self-service-scoped", "test-machine", [SELF_USAGE_SCOPE]);
const b = await apiKeysDb.createApiKey("self-service-unscoped", "test-machine", []);
scoped = { id: a.id, key: a.key };
unscoped = { id: b.id, key: b.key };
});
test.beforeEach(() => {
process.env.QUOTA_SELF_PANEL = "true";
});
const bearer = (k: string) => ({ Authorization: `Bearer ${k}` });
const req = (headers: Record<string, string> = {}, ip = "203.0.113.9") =>
new Request("http://localhost/api/v1/me/quota/claude", {
headers: { "x-forwarded-for": ip, ...headers },
});
const status = async (r: Request) => {
const a = await authenticateSelfServiceRequest(r);
return a.ok ? 200 : a.response.status;
};
async function assertRefusal(r: Request, expectedStatus: number, expectedMessage: string) {
const a = await authenticateSelfServiceRequest(r);
if (a.ok) assert.fail(`expected ${expectedStatus}`);
assert.equal(a.response.status, expectedStatus);
assert.equal(a.response.headers.get("Cache-Control"), "no-store");
const raw = await a.response.text();
assert.equal(JSON.parse(raw).error.message, expectedMessage);
assert.ok(!raw.includes("at /"), `stack trace leaked: ${raw}`);
}
test("flag off answers 404 before any credential is read", async () => {
delete process.env.QUOTA_SELF_PANEL;
await assertRefusal(req(bearer(scoped.key)), 404, "Not found");
await assertRefusal(req(), 404, "Not found");
});
test("a missing key is 401", async () => {
assert.equal(await status(req()), 401);
});
test("an invalid key is 401 no matter how many times one address sends it", async () => {
const seen: number[] = [];
for (let i = 0; i < 7; i++) seen.push(await status(req(bearer("sk-bad-repeated"))));
assert.deepEqual(seen, [401, 401, 401, 401, 401, 401, 401]);
assert.equal(await status(req(bearer(scoped.key))), 200);
});
test("a valid scoped Bearer key authenticates as that key", async () => {
const a = await authenticateSelfServiceRequest(req(bearer(scoped.key)));
if (!a.ok) assert.fail(`expected success, got ${a.response.status}`);
assert.equal(a.key.id, scoped.id);
assert.deepEqual(a.key.scopes, [SELF_USAGE_SCOPE]);
});
test("the environment key and a key without self:usage are refused", async () => {
process.env.OMNIROUTE_API_KEY = "sk-env-self-service-test";
try {
assert.equal(await status(req(bearer("sk-env-self-service-test"))), 401);
} finally {
delete process.env.OMNIROUTE_API_KEY;
}
assert.equal(await status(req(bearer(unscoped.key))), 403);
});
test("an invalid Bearer next to a valid x-api-key authenticates as the x-api-key key", async () => {
const a = await authenticateSelfServiceRequest(
req({ ...bearer("not-ours"), "x-api-key": scoped.key })
);
assert.ok(a.ok && a.key.id === scoped.id);
});
test("an invalid Bearer next to an invalid x-api-key is one 401", async () => {
await assertRefusal(
req({ ...bearer("not-ours"), "x-api-key": "also-not-ours" }),
401,
"Valid API key required"
);
});
test("every refusal is a sanitized error body with Cache-Control: no-store", async () => {
await assertRefusal(req(bearer("sk-bad")), 401, "Valid API key required");
await assertRefusal(req(bearer(unscoped.key)), 403, "API key lacks the self:usage scope");
delete process.env.QUOTA_SELF_PANEL;
await assertRefusal(req(bearer("sk-bad")), 404, "Not found");
});
test("the key is validated against its row on every call, never from the validation cache", async () => {
const seen: unknown[] = [];
const store = {
validateApiKey: async (_key: string, options?: unknown) => {
seen.push(options);
return true;
},
getApiKeyMetadata: async () => ({ id: "k-1", name: "k", scopes: [SELF_USAGE_SCOPE] }),
} as unknown as SelfServiceKeyStore;
const first = await authenticateSelfServiceRequest(req(bearer("any")), store);
const second = await authenticateSelfServiceRequest(req(bearer("any")), store);
assert.deepEqual([first.ok, second.ok], [true, true]);
assert.deepEqual(seen, [{ bypassCache: true }, { bypassCache: true }]);
});
test("an injected key store cannot skip the flag, header, environment-key or scope checks", async () => {
const reads: string[] = [];
// Only the fields the gate reads; the cast stands in for the full metadata row.
const storeAnswering = (metadata: { id: string; name: string; scopes: string[] }) =>
({
validateApiKey: async (key: string) => {
reads.push(key);
return true;
},
getApiKeyMetadata: async () => metadata,
}) as unknown as SelfServiceKeyStore;
const envKeyStore = storeAnswering({ id: "env-key", name: "env", scopes: [SELF_USAGE_SCOPE] });
const unscopedStore = storeAnswering({ id: "k-1", name: "k", scopes: [] });
const withStore = async (r: Request, store: SelfServiceKeyStore) => {
const a = await authenticateSelfServiceRequest(r, store);
return a.ok ? 200 : a.response.status;
};
assert.equal(await withStore(req(bearer("any")), envKeyStore), 401);
assert.equal(await withStore(req(bearer("any")), unscopedStore), 403);
reads.length = 0;
const viaQuery = new Request("http://localhost/api/v1/me/quota/claude?apiKey=any");
assert.equal(await withStore(viaQuery, envKeyStore), 401);
delete process.env.QUOTA_SELF_PANEL;
assert.equal(await withStore(req(bearer("any")), envKeyStore), 404);
assert.deepEqual(reads, [], "the store is not read without a header key or with the flag off");
});

View File

@@ -82,7 +82,8 @@ describe("feature-flags-settings count update", () => {
// PII_REVERSIBLE_VAULT_ENABLED (#18017 wiring, default off) the 123rd;
// SYSTEMONE_CLOUDFLARE_BACKEND_ENABLED, SYSTEMONE_OLLAMA_LOCAL_BACKEND_ENABLED and
// COMBO_JEV_STRATEGY_ENABLED (System One, default off) to 126.
assert.equal(FEATURE_FLAG_DEFINITIONS.length, 126);
// QUOTA_SELF_PANEL (self-service quota API, default off) to 127.
assert.equal(FEATURE_FLAG_DEFINITIONS.length, 127);
// COMPRESSION_CACHE_AUTOMATIC_PREFIX_ESTIMATE (#17114, default off) to 114.
// CURSOR_GROK_47_DROP_MAX_EFFORT (#17386, default off) to 112.
// UNPRICED_USAGE_BUDGET_POLICY (#14604, default fail_closed) to 113.