mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-11-21 02:54:25 +00:00
Compare commits
38 Commits
fix/codeql
...
feat/self-
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
449bb033d0 | ||
|
|
69c4659799 | ||
|
|
7386390a98 | ||
|
|
c462690870 | ||
|
|
91fbc18468 | ||
|
|
52d5965b62 | ||
|
|
d26695267f | ||
|
|
224cd6881e | ||
|
|
d6fea69530 | ||
|
|
6a2df0bacd | ||
|
|
78094c591a | ||
|
|
4b65b9a5f4 | ||
|
|
457acfaebc | ||
|
|
501a583ca6 | ||
|
|
8f5539151f | ||
|
|
56d48d5663 | ||
|
|
dff04a8134 | ||
|
|
5b4efabf48 | ||
|
|
d0e38ce62b | ||
|
|
32e98b5e09 | ||
|
|
348cce66b1 | ||
|
|
84063acff2 | ||
|
|
b80a5f08d4 | ||
|
|
28283eda0b | ||
|
|
4df35faf05 | ||
|
|
b15c7b443a | ||
|
|
25d2aafc56 | ||
|
|
523ef28ded | ||
|
|
a5233debd8 | ||
|
|
cf97c2b9ee | ||
|
|
840ff8ff8f | ||
|
|
3290609d6e | ||
|
|
2930fdbb4c | ||
|
|
7f37df27cb | ||
|
|
7f17d1e52e | ||
|
|
401c55d26d | ||
|
|
ff18b6a7c2 | ||
|
|
516c76684b |
@@ -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.
|
||||
|
||||
1
changelog.d/features/20767-self-service-quota-api.md
Normal file
1
changelog.d/features/20767-self-service-quota-api.md
Normal 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)).
|
||||
1
changelog.d/features/20787-self-service-usage-api.md
Normal file
1
changelog.d/features/20787-self-service-usage-api.md
Normal 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))
|
||||
@@ -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:
|
||||
|
||||
@@ -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. |
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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) {
|
||||
|
||||
18
src/app/api/v1/me/quota/[provider]/route.ts
Normal file
18
src/app/api/v1/me/quota/[provider]/route.ts
Normal 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);
|
||||
}
|
||||
14
src/app/api/v1/me/usage/route.ts
Normal file
14
src/app/api/v1/me/usage/route.ts
Normal 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);
|
||||
}
|
||||
@@ -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(
|
||||
|
||||
38
src/lib/db/usageAnalytics/apiKeyScope.ts
Normal file
38
src/lib/db/usageAnalytics/apiKeyScope.ts
Normal 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 },
|
||||
});
|
||||
}
|
||||
53
src/lib/quota/quotaKeyModels.ts
Normal file
53
src/lib/quota/quotaKeyModels.ts
Normal 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);
|
||||
}
|
||||
29
src/lib/quota/selfPoolRef.ts
Normal file
29
src/lib/quota/selfPoolRef.ts
Normal 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
440
src/lib/quota/selfView.ts
Normal 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,
|
||||
}),
|
||||
});
|
||||
}
|
||||
179
src/lib/quota/selfViewAccounts.ts
Normal file
179
src/lib/quota/selfViewAccounts.ts
Normal 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;
|
||||
});
|
||||
}
|
||||
159
src/lib/quota/selfViewBlocks.ts
Normal file
159
src/lib/quota/selfViewBlocks.ts
Normal 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;
|
||||
}
|
||||
41
src/lib/quota/selfViewStore.ts
Normal file
41
src/lib/quota/selfViewStore.ts
Normal 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;
|
||||
}
|
||||
}
|
||||
78
src/lib/quota/selfViewTypes.ts
Normal file
78
src/lib/quota/selfViewTypes.ts
Normal 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[];
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
327
src/lib/usage/apiKeySelfServiceUsage.ts
Normal file
327
src/lib/usage/apiKeySelfServiceUsage.ts
Normal 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),
|
||||
};
|
||||
}
|
||||
100
src/lib/usage/apiKeySelfServiceUsageCache.ts
Normal file
100
src/lib/usage/apiKeySelfServiceUsageCache.ts
Normal 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 })
|
||||
);
|
||||
}
|
||||
72
src/server/origin/publicApiBaseUrl.ts
Normal file
72
src/server/origin/publicApiBaseUrl.ts
Normal 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;
|
||||
}
|
||||
122
src/server/selfService/auth.ts
Normal file
122
src/server/selfService/auth.ts
Normal 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) };
|
||||
}
|
||||
91
src/server/selfService/quotaHandler.ts
Normal file
91
src/server/selfService/quotaHandler.ts
Normal 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);
|
||||
}
|
||||
}
|
||||
70
src/server/selfService/usageHandler.ts
Normal file
70
src/server/selfService/usageHandler.ts
Normal 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);
|
||||
}
|
||||
}
|
||||
@@ -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,
|
||||
];
|
||||
|
||||
15
src/shared/constants/featureFlagDefinitionsQuotaSelf.ts
Normal file
15
src/shared/constants/featureFlagDefinitionsQuotaSelf.ts
Normal 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",
|
||||
};
|
||||
132
src/shared/schemas/selfQuota.ts
Normal file
132
src/shared/schemas/selfQuota.ts
Normal 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>;
|
||||
91
src/shared/schemas/selfUsage.ts
Normal file
91
src/shared/schemas/selfUsage.ts
Normal 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>;
|
||||
@@ -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(
|
||||
|
||||
453
tests/unit/api-key-self-service-usage.test.ts
Normal file
453
tests/unit/api-key-self-service-usage.test.ts
Normal 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);
|
||||
});
|
||||
226
tests/unit/api/v1-me-quota-e2e.test.ts
Normal file
226
tests/unit/api/v1-me-quota-e2e.test.ts
Normal 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",
|
||||
]);
|
||||
});
|
||||
272
tests/unit/api/v1-me-quota-route.test.ts
Normal file
272
tests/unit/api/v1-me-quota-route.test.ts
Normal 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);
|
||||
}
|
||||
});
|
||||
448
tests/unit/api/v1-me-usage-route.test.ts
Normal file
448
tests/unit/api/v1-me-usage-route.test.ts
Normal 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);
|
||||
}
|
||||
});
|
||||
@@ -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
|
||||
|
||||
152
tests/unit/fixtures/quotaSelfView.ts
Normal file
152
tests/unit/fixtures/quotaSelfView.ts
Normal 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 : []),
|
||||
};
|
||||
}
|
||||
55
tests/unit/public-api-base-url.test.ts
Normal file
55
tests/unit/public-api-base-url.test.ts
Normal 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);
|
||||
});
|
||||
@@ -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"
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
66
tests/unit/quota-key-models.test.ts
Normal file
66
tests/unit/quota-key-models.test.ts
Normal 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");
|
||||
},
|
||||
}),
|
||||
[]
|
||||
);
|
||||
});
|
||||
359
tests/unit/quota-self-view-accounts.test.ts
Normal file
359
tests/unit/quota-self-view-accounts.test.ts
Normal 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],
|
||||
]
|
||||
);
|
||||
});
|
||||
315
tests/unit/quota-self-view-blocks.test.ts
Normal file
315
tests/unit/quota-self-view-blocks.test.ts
Normal 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);
|
||||
});
|
||||
71
tests/unit/quota-self-view-default-loader.test.ts
Normal file
71
tests/unit/quota-self-view-default-loader.test.ts
Normal 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));
|
||||
});
|
||||
225
tests/unit/quota-self-view.test.ts
Normal file
225
tests/unit/quota-self-view.test.ts
Normal 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);
|
||||
});
|
||||
136
tests/unit/self-quota-contract.test.ts
Normal file
136
tests/unit/self-quota-contract.test.ts
Normal 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));
|
||||
});
|
||||
156
tests/unit/self-service-auth.test.ts
Normal file
156
tests/unit/self-service-auth.test.ts
Normal 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");
|
||||
});
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user