feat(plugins): expose historical quota observations by window

Let plugins page through retained account observations and find a prior baseline without reading raw provider documents or refreshing upstream. Reuse provider window identities and the existing completion index, preserving resets and gaps.

Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Zyy
2026-11-17 17:06:55 +08:00
co-authored by Codex
parent 4d4c1e48ce
commit 832858dade
31 changed files with 706 additions and 34 deletions
@@ -23,6 +23,7 @@ pub mod provider_credentials;
pub mod proxies;
pub mod quota_forecast;
pub mod quota_forecast_sampling;
pub mod quota_history;
pub mod reset_credit_automation;
pub mod retention;
pub mod settings;
@@ -0,0 +1,87 @@
//! 单个额度桶的历史观测;原始文档只在宿主内交给 Provider 解释
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use super::{observability::TimeRange, provider_credentials::ProviderDocument};
#[derive(Debug, Clone)]
pub struct QuotaHistoryQuery {
pub window_key: String,
pub range: TimeRange,
pub cursor: Option<QuotaHistoryCursor>,
}
impl QuotaHistoryQuery {
/// 起点基线最多回看一个查询区间
pub fn scan_start(&self) -> DateTime<Utc> {
self.range
.start
.checked_sub_signed(self.range.end - self.range.start)
.unwrap_or(DateTime::<Utc>::MIN_UTC)
}
}
/// 完成时间可能相同,继续读取时保留数据库精度和请求 ID
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct QuotaHistoryCursor {
pub completed_at: DateTime<Utc>,
pub id: String,
}
pub struct QuotaDocumentPage {
pub documents: Vec<(DateTime<Utc>, ProviderDocument)>,
pub next_cursor: Option<QuotaHistoryCursor>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct QuotaReading {
pub plan_type: Option<String>,
pub used_percent: f64,
pub reset_at: Option<DateTime<Utc>>,
}
pub type QuotaHistoryParser = fn(&ProviderDocument, &str) -> Option<QuotaReading>;
pub struct QuotaHistoryPoint {
pub observed_at: DateTime<Utc>,
pub reading: QuotaReading,
}
#[derive(Default)]
pub struct QuotaHistoryPage {
pub samples: Vec<QuotaHistoryPoint>,
pub baseline: Option<QuotaHistoryPoint>,
pub next_cursor: Option<QuotaHistoryCursor>,
}
impl QuotaHistoryPage {
pub fn from_documents(
page: QuotaDocumentPage,
query: &QuotaHistoryQuery,
parse: QuotaHistoryParser,
) -> Self {
let mut result = Self {
next_cursor: page.next_cursor,
..Self::default()
};
for (observed_at, document) in page.documents {
let Some(reading) = parse(&document, &query.window_key) else {
continue;
};
let point = QuotaHistoryPoint {
observed_at,
reading,
};
if observed_at < query.range.start {
// 倒序扫描遇到的第一个同桶读数就是最近基线,无需再向前翻页
result.baseline = Some(point);
result.next_cursor = None;
break;
}
result.samples.push(point);
}
result
}
}
@@ -34,6 +34,12 @@ pub trait PluginAccountAccess: Send + Sync {
Err(AdminError::unavailable("插件额度事实查询暂不可用"))
}
async fn quota_history(
&self,
account: &ProviderAccountId,
query: crate::model::quota_history::QuotaHistoryQuery,
) -> Result<crate::model::quota_history::QuotaHistoryPage, AdminError>;
/// 通过 Provider 原生管理路径刷新额度;不向插件暴露凭据或执行额度重置
async fn refresh_quota(
&self,
@@ -349,6 +349,11 @@ pub trait ProviderAdmin: Send + Sync {
Ok(None)
}
/// 历史文档由 Provider 按稳定窗口键解释,不支持的 Provider 不扫描请求记录
fn quota_history_parser(&self) -> Option<crate::model::quota_history::QuotaHistoryParser> {
None
}
/// 历史观测的协议字段仅由具体 Provider 解释;不支持时保留累计估算
fn quota_forecast_observation(
&self,
@@ -180,6 +180,16 @@ pub trait AccountStore:
windows: &[AccountUsageWindowQuery],
) -> AdminStoreResult<Vec<AccountUsageWindowResult>>;
/// 按完成时间倒序读取一页保留的请求观测,不按本地计费结果筛选
async fn quota_documents(
&self,
account: &gateway_core::account::ProviderAccountId,
provider: &gateway_core::routing::ProviderKind,
created_at: DateTime<Utc>,
range: TimeRange,
before: Option<&crate::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<crate::model::quota_history::QuotaDocumentPage>;
/// 从同一数据库语句取得截止快照的累计用量和有界历史观测
async fn load_quota_forecast_history(
&self,
@@ -126,6 +126,46 @@ impl PluginAccountAccess for DefaultPluginAccountAccess {
self.quota(account_id, false).await
}
async fn quota_history(
&self,
account_id: &ProviderAccountId,
query: crate::model::quota_history::QuotaHistoryQuery,
) -> Result<crate::model::quota_history::QuotaHistoryPage, AdminError> {
use crate::model::{observability::TimeRange, quota_history::QuotaHistoryPage};
let account = self
.accounts
.load_account_record(account_id)
.await
.map_err(|error| map_store_error(error, "plugin quota history"))?
.ok_or_else(|| AdminError::not_found("账号不存在"))?;
let Some(parse) = self
.provider(&account.provider_kind)?
.quota_history_parser()
else {
return Ok(QuotaHistoryPage::default());
};
let start = query.scan_start().max(account.created_at);
if start >= query.range.end {
return Ok(QuotaHistoryPage::default());
}
let page = self
.accounts
.quota_documents(
account_id,
&account.provider_kind,
account.created_at,
TimeRange {
start,
end: query.range.end,
},
query.cursor.as_ref(),
)
.await
.map_err(|error| map_store_error(error, "plugin quota history"))?;
Ok(QuotaHistoryPage::from_documents(page, &query, parse))
}
async fn refresh_quota(
&self,
account_id: &ProviderAccountId,
@@ -845,6 +845,17 @@ impl AccountStore for FakeAccountStore {
.clone())
}
async fn quota_documents(
&self,
_: &gateway_core::account::ProviderAccountId,
_: &gateway_core::routing::ProviderKind,
_: chrono::DateTime<chrono::Utc>,
_: gateway_admin::model::observability::TimeRange,
_: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<gateway_admin::model::quota_history::QuotaDocumentPage> {
unreachable!("测试不读取历史额度文档")
}
async fn load_quota_forecast_history(
&self,
window: &AccountUsageWindowQuery,
@@ -546,6 +546,17 @@ impl AccountStore for UnavailableStore {
Err(unavailable("account quota window usage"))
}
async fn quota_documents(
&self,
_: &gateway_core::account::ProviderAccountId,
_: &gateway_core::routing::ProviderKind,
_: chrono::DateTime<chrono::Utc>,
_: gateway_admin::model::observability::TimeRange,
_: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<gateway_admin::model::quota_history::QuotaDocumentPage> {
unreachable!("测试不读取历史额度文档")
}
async fn load_quota_forecast_history(
&self,
_: &AccountUsageWindowQuery,
@@ -1300,6 +1300,17 @@ impl AccountStore for UnusedStore {
Err(unavailable("account quota window usage"))
}
async fn quota_documents(
&self,
_: &gateway_core::account::ProviderAccountId,
_: &gateway_core::routing::ProviderKind,
_: chrono::DateTime<chrono::Utc>,
_: gateway_admin::model::observability::TimeRange,
_: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<gateway_admin::model::quota_history::QuotaDocumentPage> {
unreachable!("测试不读取历史额度文档")
}
async fn load_quota_forecast_history(
&self,
_: &AccountUsageWindowQuery,
@@ -98,6 +98,7 @@ impl PluginData {
next_cursor: page.next_cursor.map(|id| id.as_str().to_owned()),
})
}
data::QUOTA_HISTORY => return self.quota_history(payload).await,
data::QUOTA_GET | data::QUOTA_REFRESH | data::QUOTA_DETAILS => {
let accounts = self.accounts.upgrade().map_err(map_admin_error)?;
let query: data::QuotaFactsQuery =
@@ -162,4 +163,67 @@ impl PluginData {
payload,
})
}
async fn quota_history(&self, payload: &[u8]) -> Result<RpcReply, PluginFault> {
use gateway_admin::model::{
observability::TimeRange,
quota_history::{QuotaHistoryPoint, QuotaHistoryQuery},
};
let wire: data::QuotaHistoryQuery =
serde_json::from_slice(payload).map_err(|_| invalid())?;
let id = ProviderAccountId::new(wire.account_id).map_err(|_| invalid())?;
let time = |ms| chrono::DateTime::from_timestamp_millis(ms).ok_or_else(invalid);
let range =
TimeRange::new(time(wire.start_ms)?, time(wire.end_ms)?).map_err(|_| invalid())?;
if wire.start_ms < 0
|| wire.window_key.is_empty()
|| wire.window_key.len() > 256
|| wire.window_key.chars().any(char::is_control)
{
return Err(invalid());
}
let query = QuotaHistoryQuery {
window_key: wire.window_key,
range,
cursor: wire
.cursor
.as_deref()
.map(serde_json::from_str)
.transpose()
.map_err(|_| invalid())?,
};
if query.cursor.as_ref().is_some_and(|c| {
c.completed_at >= range.end
|| c.completed_at < query.scan_start()
|| c.id.is_empty()
|| c.id.contains('\0')
}) {
return Err(invalid());
}
let page = self
.accounts
.upgrade()
.map_err(map_admin_error)?
.quota_history(&id, query)
.await
.map_err(map_admin_error)?;
let sample = |p: QuotaHistoryPoint| data::QuotaHistorySample {
observed_at_ms: p.observed_at.timestamp_millis(),
used_percent: p.reading.used_percent,
reset_at_ms: p.reading.reset_at.map(|at| at.timestamp_millis()),
plan_type: p.reading.plan_type,
};
super::admin::encode(&data::QuotaHistoryPage {
schema_version: 1,
samples: page.samples.into_iter().map(sample).collect(),
baseline: page.baseline.map(sample),
next_cursor: page
.next_cursor
.as_ref()
.map(serde_json::to_string)
.transpose()
.map_err(|_| invalid())?,
})
}
}
@@ -216,6 +216,7 @@ impl CallbackHandler for PluginCallbacks {
| gateway_plugin_sdk::call::data::KEYS_GET
| gateway_plugin_sdk::call::data::QUOTA_GET
| gateway_plugin_sdk::call::data::QUOTA_REFRESH
| gateway_plugin_sdk::call::data::QUOTA_HISTORY
| gateway_plugin_sdk::call::data::QUOTA_DETAILS
) {
return data.call(&method, params, &payload).await;
@@ -15,6 +15,17 @@ struct BudgetAccountAccess {
#[async_trait::async_trait]
impl gateway_admin::ports::plugin_accounts::PluginAccountAccess for BudgetAccountAccess {
async fn quota_history(
&self,
_: &gateway_core::account::ProviderAccountId,
_: gateway_admin::model::quota_history::QuotaHistoryQuery,
) -> Result<
gateway_admin::model::quota_history::QuotaHistoryPage,
gateway_admin::model::AdminError,
> {
unreachable!("账号提交不读取额度历史")
}
async fn list(
&self,
_: gateway_admin::model::provider_credentials::PluginAccountListQuery,
@@ -75,6 +75,30 @@ fn account() -> AccountRecord {
#[async_trait]
impl PluginAccountAccess for Facts {
async fn quota_history(
&self,
id: &ProviderAccountId,
query: gateway_admin::model::quota_history::QuotaHistoryQuery,
) -> Result<gateway_admin::model::quota_history::QuotaHistoryPage, AdminError> {
use gateway_admin::model::quota_history::{
QuotaHistoryPage, QuotaHistoryPoint, QuotaReading,
};
assert_eq!(id.as_str(), "acct_facts");
assert_eq!(query.window_key, "weekly");
assert!(query.cursor.is_none());
Ok(QuotaHistoryPage {
samples: vec![QuotaHistoryPoint {
observed_at: query.range.start,
reading: QuotaReading {
plan_type: None,
used_percent: 12.5,
reset_at: None,
},
}],
..Default::default()
})
}
async fn refresh_quota(
&self,
account: &ProviderAccountId,
@@ -201,6 +225,9 @@ async fn management_facts_validate_queries_without_permission_declarations() {
{"method":"host.data.accounts.list","query":{"provider_id":"openai","cursor":"acct_before","limit":1}},
{"method":"host.data.quota.get","query":{"account_id":"acct_facts"}},
{"method":"host.data.quota.details","query":{"account_id":"acct_facts"}},
{"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":1000,"end_ms":2000}},
{"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":2000,"end_ms":1000}},
{"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":1000,"end_ms":2000,"cursor":"invalid"}},
{"method":"host.data.accounts.list","query":{"limit":0}},
{"method":"host.data.accounts.list","query":{"limit":65535}},
{"method":"host.data.quota.get","query":{"account_id":"acct_facts","sql":"SELECT secret"}}
@@ -269,7 +296,12 @@ async fn management_facts_validate_queries_without_permission_declarations() {
Some("123456789.123456789")
);
assert!(!result[2].to_string().contains("provider-internal-fixture"));
for invalid in &result.as_array().unwrap()[3..] {
let history: gateway_plugin_sdk::call::data::QuotaHistoryPage =
serde_json::from_value(result[3].clone()).unwrap();
assert_eq!(history.samples[0].used_percent, 12.5);
assert_eq!(history.samples[0].observed_at_ms, 1000);
assert_eq!(history.samples[0].reset_at_ms, None);
for invalid in &result.as_array().unwrap()[4..] {
assert_eq!(invalid["error"], "invalid_input");
}
@@ -107,6 +107,7 @@ async fn callbacks_are_dispatched_in_every_stage_without_permission_declarations
"host.data.accounts.list",
"host.data.keys.get",
"host.data.quota.get",
"host.data.quota.history",
"host.groups.ensure",
"host.groups.change_members",
"host.keys.ensure",
+1 -1
View File
@@ -23,7 +23,7 @@ SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力
| `call::upstream_adapter` | 内置 OpenAI / xAI 的[受管上游适配器](docs/upstream-adapters.md)注册、执行、出站与续接合同 |
| `call::policy` | 模型路由、账号调度与重试决策合同 |
| `call::catalog` | 固定 Provider 的直接别名与适配模型注册合同,见[模型目录](docs/capabilities.md#模型目录) |
| `call::data` | 最小账号事实与已有额度观测的只读合同 |
| `call::data` | 账号事实、当前额度与历史额度观测 |
| `call::observation` | 请求完成、用量、费用与实际上游 WebSocket 响应事件的统一观察合同 |
| `call::host` | 账号、私有状态、受管 HTTP、模型、亲和、日志及调用内流的宿主回调合同 |
| `call::management` | 管理 API、页面与资源声明、公开回调,以及 CLI 命令与待保存账号 |
@@ -89,6 +89,7 @@ Provider 固定为宿主内置的 OpenAI 与 xAI。宿主开放以下 11 类扩
| `call.host.quota_details(query)` | `host.data.quota.details` | `QuotaFactsQuery { account_id }`:读取完整额度事实,包含窗口归属、触顶和点数 |
| `call.host.check_access(query)` | `host.data.access.check` | `AccessQuery { client_key_id, account_ids, upstream_model }`:读取 Key 对指定账号及可选上游模型的冻结授权 |
| `call.host.verify_client(request)` | `host.client.verify` | `VerifyClientRequest { authorization }`:复用入口认证,返回 `VerifiedClient { client_key_id }` |
| `call.host.quota_history(query)` | `host.data.quota.history` | 按账号、窗口键和时间范围分页读取已保留的额度观测 |
| `call.host.quota_facts(query)` | `host.data.quota.get` | `QuotaFactsQuery { account_id }`:读取 Provider 现有观测,不访问上游刷新 |
| `call.host.key_facts(query)` | `host.data.keys.get` | `ClientKeyFactsQuery { client_key_id }`:读取当前 Key 的启用状态及显式分组 ID,不返回密钥 |
@@ -108,6 +109,16 @@ SDK 解析响应时忽略未知字段,包含账号分页、账号及额度窗
`quota_details` 保留 Provider 已解释的 `limit_reached`、窗口 `group`、`label`、`limit_id`、`limit_name`、`role`
及点数 `has_credits`、`unlimited`、`balance`;缺失值仍为 `null`,不返回上游原始文档,不发起刷新
`quota_history(QuotaHistoryQuery { account_id, window_key, start_ms, end_ms, cursor })` 按请求完成时间倒序返回
`[start_ms, end_ms)` 内的同桶读数。窗口键与 `quota_details` 相同,区间最长 366 天。每个样本包含
`observed_at_ms`、`used_percent` 和当时观测到的 `reset_at_ms`、`plan_type`,后两项可为 `null`。
首次省略游标;即使 `samples` 为空,只要有 `next_cursor` 就沿用原查询继续。末页的 `baseline` 是起点前最近的同桶读数,
最多向前查一个等长区间。例如查最近 48 小时,基线最多再向前找 48 小时;没有基线时返回 `null`
历史来自保留的已结束请求,不含独立额度刷新。Provider 未提供可解析的同桶观测时没有样本。
缺样不代表零;跨重置或套餐变更不能直接相减。这是观测记录,不是精确消耗账本。
分页不冻结数据,长区间建议在后台读取并复用结果
`verify_client` 使用当前请求设置和原认证计划,包含外部 principal 到 Key 的映射;没有 HTTP 入口时使用当前发布配置。
认证可以调用认证插件,继续扣减父预算并响应取消;验证成功不做推理准入、账号租约、使用记录或计费。
授权原文只作本次认证输入,不进入返回值
@@ -5,6 +5,7 @@ use serde::{Deserialize, Serialize};
pub const ACCOUNTS_LIST: &str = "host.data.accounts.list";
pub const QUOTA_REFRESH: &str = "host.quota_observations.refresh";
pub const QUOTA_HISTORY: &str = "host.data.quota.history";
pub const QUOTA_GET: &str = "host.data.quota.get";
pub const KEYS_GET: &str = "host.data.keys.get";
pub const CLIENT_VERIFY: &str = "host.client.verify";
@@ -93,6 +94,35 @@ pub struct QuotaFactsQuery {
pub account_id: String,
}
/// UTC 毫秒半开区间;续页沿用原查询并原样传回游标
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct QuotaHistoryQuery {
pub account_id: String,
pub window_key: String,
pub start_ms: i64,
pub end_ms: i64,
pub cursor: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuotaHistorySample {
pub plan_type: Option<String>,
pub observed_at_ms: i64,
pub used_percent: f64,
pub reset_at_ms: Option<i64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuotaHistoryPage {
pub schema_version: u32,
/// 请求完成时间倒序;空页也可能需要继续
pub samples: Vec<QuotaHistorySample>,
/// 最后一页才可能包含起点前的最近同桶观测
pub baseline: Option<QuotaHistorySample>,
pub next_cursor: Option<String>,
}
/// Provider 已有快照的必要投影;空观测时间表示没有可用样本,不代表额度为零
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuotaFacts {
@@ -75,6 +75,17 @@ impl HostClient {
payload_call(self, data::QUOTA_GET, query).await
}
/// 按账号、额度桶和时间范围读取已保留的观测,不刷新上游
///
/// # Errors
/// 账号不存在、查询无效或宿主读取失败时返回错误
pub async fn quota_history(
&self,
query: data::QuotaHistoryQuery,
) -> Result<data::QuotaHistoryPage, PluginFault> {
payload_call(self, data::QUOTA_HISTORY, query).await
}
/// 读取已有额度窗口标签、触顶与点数事实,不触发刷新或补算
///
/// # Errors
@@ -235,10 +235,11 @@ impl AccountStore for PgAdminAccountStore {
account_id: &CoreProviderAccountId,
) -> AdminStoreResult<Option<AccountRecord>> {
self.accounts
.load_provider_account(account_id.as_str())
.list_provider_account_summaries(None, true, Some(&[account_id.as_str()]), None)
.await
.map_err(|error| admin_store_error(ENTITY, error))?
.map(|record| admin_account_record(record.summary))
.pop()
.map(admin_account_record)
.transpose()
}
@@ -455,6 +456,26 @@ impl AccountStore for PgAdminAccountStore {
self.usage_by_windows(windows).await
}
async fn quota_documents(
&self,
account: &gateway_core::account::ProviderAccountId,
provider: &gateway_core::routing::ProviderKind,
created_at: chrono::DateTime<chrono::Utc>,
range: gateway_admin::model::observability::TimeRange,
before: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<gateway_admin::model::quota_history::QuotaDocumentPage> {
super::quota_history::documents(
&self.pool,
&self.query_budget,
account,
provider,
created_at,
range,
before,
)
.await
}
async fn load_quota_forecast_history(
&self,
window: &AccountUsageWindowQuery,
@@ -61,6 +61,7 @@ mod mapping;
mod model_catalogs;
mod quota;
mod quota_forecast;
mod quota_history;
mod quota_warmup;
mod repository;
mod reset_credit_automation;
@@ -0,0 +1,72 @@
//! 按账号完成时间索引分页读取历史观测;过滤窗口的协议字段由 Provider 解释
use futures::TryStreamExt as _;
use gateway_admin::model::quota_history::{QuotaDocumentPage, QuotaHistoryCursor};
use super::*;
pub(super) async fn documents(
pool: &PgPool,
budget: &crate::postgres::ObservabilityQueryBudget,
account: &CoreProviderAccountId,
provider: &gateway_core::routing::ProviderKind,
created_at: DateTime<Utc>,
range: TimeRange,
before: Option<&QuotaHistoryCursor>,
) -> AdminStoreResult<QuotaDocumentPage> {
const PAGE_SIZE: usize = 64;
const PAGE_BYTES: usize = 2 * 1024 * 1024;
let (until, last_id) = before.map_or((range.end, ""), |c| (c.completed_at, c.id.as_str()));
budget
.run(pool, "read quota documents", |mut connection| async move {
let mut rows = sqlx::query_as::<_, (DateTime<Utc>, String, String)>(
"select completed_at,id,provider_observation_json::text from model_requests
where provider_account_ref=$1 and provider_kind=$2 and started_at >= $3
and completed_at >= $4 and completed_at < $5 and (completed_at,id) < ($6,$7)
and outcome <> 'running' and provider_observation_json is not null
order by completed_at desc,id desc limit $8",
)
.bind(account.as_str())
.bind(provider.as_str())
.bind(created_at)
.bind(range.start)
.bind(range.end)
.bind(until)
.bind(last_id)
.bind((PAGE_SIZE + 1) as i64)
.fetch(&mut *connection);
let mut documents = Vec::new();
let mut bytes = 0;
let mut last = None;
while let Some((completed_at, id, json)) = rows
.try_next()
.await
.map_err(|error| postgres_unavailable("read quota documents", error))?
{
// 首份文档独占一页也要前进,否则大文档会卡住所有后续页
if documents.len() == PAGE_SIZE
|| (!documents.is_empty() && bytes + json.len() > PAGE_BYTES)
{
return Ok(QuotaDocumentPage {
documents,
next_cursor: last,
});
}
bytes += json.len();
let document = serde_json::from_str(&json)
.map_err(|_| invalid("invalid provider observation"))?;
documents.push((
completed_at,
ProviderDocument::new(OpaqueProviderData::new(document)),
));
last = Some(QuotaHistoryCursor { completed_at, id });
}
Ok(QuotaDocumentPage {
documents,
next_cursor: None,
})
})
.await
.map_err(|error| admin_store_error(ENTITY, error))
}
@@ -13,6 +13,7 @@ mod deletion;
mod protection_revision;
mod quota;
mod quota_forecast;
mod quota_history;
mod timestamps;
mod usage_projection;
@@ -0,0 +1,162 @@
//! 验证历史额度按账号与完成时间翻页,保留重置和最近有效基线
use gateway_admin::model::quota_history::{QuotaHistoryPage, QuotaHistoryQuery, QuotaReading};
use super::*;
#[tokio::test]
async fn quota_history_pages_sparse_tied_observations_through_the_nearest_baseline() {
let Some(db) = TestDatabase::create("quota_history").await else {
return;
};
let store = admin_account_store(&db.pool);
let id = ProviderAccountId::new("acct_history").unwrap();
let mut saved = account(id.as_str(), "history");
saved.enabled = false;
PgProviderAccountRepository::new(db.pool.clone())
.insert_provider_account(saved)
.await
.unwrap();
let record = store.load_account_record(&id).await.unwrap().unwrap();
let created = record.created_at;
let provider = record.provider_kind;
let start = chrono::DateTime::from_timestamp(created.timestamp() + 3600, 0).unwrap();
let range = TimeRange::new(start, start + TimeDelta::minutes(10)).unwrap();
let tied = start + TimeDelta::microseconds(1_123_456);
let before_reset = start.timestamp() + 1;
let after_reset = before_reset + 604800;
let weekly = |percent, reset| json!({"weekly":[percent,reset]});
let row = |key: String, at, doc| (key, "acct_history", "openai", at, doc);
// 同一微秒的请求跨页时,继续扫描才能找到其中唯一的同桶读数
let mut rows: Vec<_> = (0..66)
.map(|i| {
row(
format!("tied_{i:02}"),
tied,
if i == 0 {
weekly(3, after_reset)
} else {
json!({})
},
)
})
.collect();
rows.extend([
row("start".into(), start, weekly(96, before_reset)),
row("end".into(), range.end, weekly(90, after_reset)),
row(
"wrong_window".into(),
start - TimeDelta::microseconds(1),
json!({"daily":[60,before_reset]}),
),
row(
"baseline".into(),
start - TimeDelta::minutes(1),
weekly(94, before_reset),
),
row(
"older".into(),
start - TimeDelta::minutes(2),
weekly(80, before_reset),
),
row(
"outside_lookback".into(),
start - TimeDelta::minutes(11),
json!({"unknown":[75,before_reset]}),
),
(
"other".into(),
"acct_other",
"openai",
tied,
weekly(90, after_reset),
),
(
"other_provider".into(),
"acct_history",
"other",
tied,
weekly(88, after_reset),
),
]);
for (request_id, account_id, provider_kind, at, doc) in rows {
seed_model_request(
&db.pool,
ModelRequestSeed {
request_id: &request_id,
account_id,
provider_kind,
model: "gpt-test",
total_tokens: 1,
cost_amount: "1",
started_at: at - TimeDelta::seconds(1),
},
)
.await
.unwrap();
sqlx::query("update model_requests set provider_observation_json=$2 where id=$1")
.bind(request_id)
.bind(doc)
.execute(&db.pool)
.await
.unwrap();
}
for key in ["weekly", "unknown"] {
let mut query = QuotaHistoryQuery {
window_key: key.into(),
range,
cursor: None,
};
let scan = TimeRange {
start: query.scan_start(),
end: range.end,
};
let mut samples = Vec::new();
let mut pages = 0;
let baseline = loop {
let raw = store
.quota_documents(&id, &provider, created, scan, query.cursor.as_ref())
.await
.unwrap();
let page = QuotaHistoryPage::from_documents(raw, &query, |doc, key| {
let pair = doc.expose_to_provider().expose_to_provider().get(key)?;
Some(QuotaReading {
used_percent: pair[0].as_f64()?,
reset_at: chrono::DateTime::from_timestamp(pair[1].as_i64()?, 0),
plan_type: None,
})
});
pages += 1;
if pages == 1 {
assert!(page.samples.is_empty() && page.next_cursor.is_some());
}
samples.extend(page.samples.into_iter().map(|p| {
(
p.observed_at,
p.reading.used_percent,
p.reading.reset_at.unwrap().timestamp(),
)
}));
query.cursor = page.next_cursor;
if query.cursor.is_none() {
break page.baseline;
}
assert!(pages < 4, "游标未前进");
};
if key == "weekly" {
assert_eq!(
samples,
[(tied, 3.0, after_reset), (start, 96.0, before_reset)]
);
let base = baseline.unwrap();
assert_eq!(
(base.observed_at, base.reading.used_percent),
(start - TimeDelta::minutes(1), 94.0)
);
} else {
assert!(samples.is_empty() && baseline.is_none());
}
}
db.close().await;
}
@@ -797,35 +797,31 @@ impl ProviderAdmin for OpenAiAdminProvider {
}
}
fn quota_history_parser(
&self,
) -> Option<gateway_admin::model::quota_history::QuotaHistoryParser> {
Some(quota::history_reading)
}
fn quota_forecast_observation(
&self,
document: &ProviderDocument,
window: &ProviderQuotaWindow,
) -> Option<QuotaForecastObservation> {
use gateway_protocol::openai::events::parse_rate_limit_headers;
if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide {
return None;
}
let value = document
.expose_to_provider()
.expose_to_provider()
.get("rateLimitHeaders")?;
let headers: Vec<(String, String)> = serde_json::from_value(value.clone()).ok()?;
let parsed = parse_rate_limit_headers(&headers)?;
let limit = parsed.limits.get(window.limit_id.as_deref()?)?;
let observed = match window.role? {
ProviderQuotaWindowRole::Primary => limit.primary?,
ProviderQuotaWindowRole::Secondary => limit.secondary?,
ProviderQuotaWindowRole::Monthly => return None,
};
if observed.window_minutes?.checked_mul(60)? != window.window_seconds? {
let (observed, plan_type) = quota::history_window(document, &window.key)?;
if Some(observed.source()) != window.limit_id.as_deref()
|| Some(quota_role(observed.role())) != window.role
|| observed.window_seconds()? != window.window_seconds?
{
return None;
}
Some(QuotaForecastObservation {
used_percent: observed.used_percent,
reset_at: DateTime::<Utc>::from_timestamp(observed.reset_at?, 0)?,
plan_type: parsed.plan_type,
used_percent: observed.used_percent()?,
reset_at: observed.reset_at()?,
plan_type,
})
}
@@ -1,4 +1,4 @@
//! 管理端批量读取原生额度,不在列表查询中访问上游
//! 管理端额度快照与历史请求观测的只读投影
use super::*;
@@ -74,3 +74,29 @@ impl OpenAiAdminProvider {
.collect()
}
}
pub(super) fn history_window(
document: &ProviderDocument,
key: &str,
) -> Option<(crate::credential::CodexQuotaWindow, Option<String>)> {
let headers = document
.expose_to_provider()
.expose_to_provider()
.get("rateLimitHeaders")?;
let headers: Vec<(String, String)> = serde::Deserialize::deserialize(headers).ok()?;
let parsed = gateway_protocol::openai::events::parse_rate_limit_headers(&headers)?;
let window = crate::credential::observed_quota_window(&parsed, key)?;
Some((window, parsed.plan_type))
}
pub(super) fn history_reading(
document: &ProviderDocument,
key: &str,
) -> Option<gateway_admin::model::quota_history::QuotaReading> {
let (window, plan_type) = history_window(document, key)?;
Some(gateway_admin::model::quota_history::QuotaReading {
plan_type,
used_percent: window.used_percent()?,
reset_at: window.reset_at(),
})
}
@@ -59,6 +59,7 @@ pub use oauth::{
pub use profile_statistics::{
CodexCredentialProfileService, CodexProfileAvatarError, CodexProfileStatisticsError,
};
pub(crate) use quota::observed_quota_window;
pub use quota::{
CodexAccountQuotaSnapshot, CodexCredentialQuotaError, CodexCredentialQuotaService,
CodexInitialSyncDelays, CodexQuotaFact, CodexQuotaRefreshPolicy, CodexQuotaSyncSummary,
@@ -18,6 +18,7 @@ mod warmup;
const BUCKET_USAGE_FIELD: &str = "_cpr_bucket_last_used_at";
pub(crate) use passive::observed_quota_window;
pub use reset_credits::CodexResetCreditsError;
use reset_credits::ResetCreditLocks;
use scheduling::CodexQuotaSchedulingProjection;
@@ -151,6 +151,18 @@ impl CodexCredentialQuotaService {
}
}
pub(crate) fn observed_quota_window(
parsed: &ParsedRateLimits,
key: &str,
) -> Option<CodexQuotaWindow> {
// 只解释本次响应,不借用当前快照补全旧观测或把具名桶镜像当作账号额度
let (quota, _) = merge_passive_quota(Map::new(), std::slice::from_ref(parsed), None);
snapshot::quota_windows(&quota)
.ok()?
.into_iter()
.find(|window| window.key() == key)
}
fn merge_passive_quota(
mut quota: Map<String, Value>,
observations: &[ParsedRateLimits],
@@ -416,16 +416,7 @@ pub(crate) fn parse_account_quota_snapshot(
) -> Result<CodexAccountQuotaSnapshot, CodexCredentialQuotaError> {
let object = canonical_quota_object(usage)?;
let fact = parse_codex_quota_object(&object)?;
let mut windows = Vec::new();
for limit in canonical_rate_limits(&object)? {
parse_rate_limit_windows(
&limit.source,
limit.account_wide,
limit.limit_name.as_deref(),
limit.rate_limit,
&mut windows,
)?;
}
let mut windows = quota_windows(&object)?;
windows.sort_by(|left, right| {
quota_source_order(left.source())
.cmp(&quota_source_order(right.source()))
@@ -610,6 +601,22 @@ fn is_codex_limit_id(value: &str) -> bool {
value.trim().eq_ignore_ascii_case("codex")
}
pub(super) fn quota_windows(
object: &Map<String, Value>,
) -> Result<Vec<CodexQuotaWindow>, CodexCredentialQuotaError> {
let mut windows = Vec::new();
for limit in canonical_rate_limits(object)? {
parse_rate_limit_windows(
&limit.source,
limit.account_wide,
limit.limit_name.as_deref(),
limit.rate_limit,
&mut windows,
)?;
}
Ok(windows)
}
fn parse_rate_limit_windows(
source: &str,
account_wide: bool,
@@ -352,6 +352,33 @@ async fn quota_forecast_observation_reuses_protocol_parser_and_keeps_window_iden
.unwrap()
.clone(),
));
let history = provider.quota_history_parser().unwrap();
let short = history(&document, "codex:18000s").unwrap();
assert_eq!(short.used_percent, 4.0);
assert_eq!(short.reset_at.unwrap().timestamp(), 1_789_218_647);
assert!(history(&document, "other:18000s").is_none());
let named = ProviderDocument::new(OpaqueProviderData::new(
json!({
"rateLimitHeaders": [
["x-codex-primary-used-percent","23"],["x-codex-primary-window-minutes","1"],
["x-feature-primary-used-percent","23"],["x-feature-primary-window-minutes","1"],
["x-feature-secondary-used-percent","56"],["x-feature-secondary-window-minutes","1"]
]
})
.as_object()
.unwrap()
.clone(),
));
assert!(history(&named, "codex:60s").is_none());
assert!(history(&named, "feature:60s").is_none());
let primary = history(&named, "feature:60s:primary_window").unwrap();
assert_eq!((primary.used_percent, primary.reset_at), (23.0, None));
assert_eq!(
history(&named, "feature:60s:secondary_window")
.unwrap()
.used_percent,
56.0
);
let observed = provider
.quota_forecast_observation(&document, &window)
.unwrap();
+3 -1
View File
@@ -1175,7 +1175,9 @@ Admin 按卡片与所选指标向 Store 请求计数、金额或分布,缓存
预测数值复用统计投影的十五分钟开始时间桶,并以账号与五分钟完成时间桶分组。
完整完成时间桶合并累计量,跨采样截止值的小桶、开始时间边界和重建区间读取窄事实;
同一快照撤销待投影旧版本并加入当前源版本。预测采样保留请求完成状态,不按恢复标记排除请求;其他业务统计排除恢复请求。
Provider 文档按账号和完成时间索引读取,每个采样槽只保留最后一份
Provider 文档按账号和完成时间索引读取,预测每个采样槽只保留最后一份。
插件的[额度历史查询](../backend/crates/gateway-plugin/sdk/docs/capabilities.md#基础事实)沿同一索引分页,由 Provider 解释所选窗口;
它保留重置前后的读数,不计算预测或累计消耗
### 请求记录与交付