Files
ssw__ipass/rust/crates/ipass-core/src/usage.rs
T
admin 0d8e1c94d1 refactor(plugin): P3 拆 plugin-llm —— LLM 路由/配额/计量/审计/趋势迁入独立插件
- plugin-llm 新 crate:llm/upstreams/usage_filter/llm_audit/stats/handlers/api/config/models/store
- 下行契约(downstream_key/identity/check_quota/fail)与记账原语(usage::bump/read/bump_day)已下沉 ipass-core
- usage_filter 改走 loc::enabled(Switch::Llm) + core::plugin::ctx_index(解除对 gateway 私有 ModuleConfig 的依赖)
- gateway 收缩为壳:LlmHandler/LlmHealthHandler/AuditHandler 随 LlmPlugin 装配;
  /api/admin/trend 留 gateway(需 users+upstreams+apix 三方名册,组合根职责)
- 行为等价:262 项回归全绿(gateway 102 + llm 160)
2026-09-13 12:08:34 +08:00

240 lines
8.6 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 通用记账原语(无任何业务语义)。
//!
//! 只回答「给这个前缀下的这个键 +1」「这个键现在的读数是什么」——
//! **不认识** `ust:` 与 `ums:` 的区别,更不认识「LLM」「token」这些词。
//! 业务解读(趋势 / 总览 / 按人聚合)在 plugin-llm 的 `stats` 模块,
//! 它把键前缀与本模块的原语组合起来。
//!
//! value 编码共用两种:
//! * 窗口读数:`<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`
//! * 日桶:`<请求数>:<入>:<出>`(趋势图数据源,TTL 到期自然淘汰)
use serde_json::{Value, json};
use crate::state;
use crate::util;
/// 一条统计记录的读数。`today` 已按调用方给的日窗折算过(跨天即为 0)。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Usage {
/// 今日(本地自然日)计数
pub today: i64,
/// 累计计数(自该计数键建立以来,不随跨天归零)
pub total: i64,
/// 最近一次记账时间戳;0 = 从未
pub last_ts: i64,
}
impl Usage {
/// 累加(聚合用)。`last_ts` 取最大。
pub fn merge(&mut self, other: &Usage) {
self.today += other.today;
self.total += other.total;
if other.last_ts > self.last_ts {
self.last_ts = other.last_ts;
}
}
pub fn json(&self) -> Value {
json!({
"today": self.today,
"total": self.total,
"last_ts": self.last_ts,
"last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() },
})
}
}
/// token 计量读数。日窗语义与 [`Usage`] 相同:跨天 today 归零、累计保留。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct TokenUsage {
/// 今日入 token
pub tin_today: i64,
/// 累计入 token
pub tin_total: i64,
/// 今日出 token
pub tout_today: i64,
/// 累计出 token
pub tout_total: i64,
/// 最近一次有 token 记账的调用时间戳;0 = 从未
pub last_ts: i64,
}
impl TokenUsage {
/// 累加(聚合用)。`last_ts` 取最大。
pub fn merge(&mut self, other: &TokenUsage) {
self.tin_today += other.tin_today;
self.tin_total += other.tin_total;
self.tout_today += other.tout_today;
self.tout_total += other.tout_total;
if other.last_ts > self.last_ts {
self.last_ts = other.last_ts;
}
}
pub fn json(&self) -> Value {
json!({
"in_today": self.tin_today,
"in_total": self.tin_total,
"out_today": self.tout_today,
"out_total": self.tout_total,
"last_ts": self.last_ts,
"last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() },
})
}
}
/// 一天的聚合值(日桶)
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DayBucket {
pub requests: i64,
pub tin: i64,
pub tout: i64,
}
impl DayBucket {
pub fn merge(&mut self, other: &DayBucket) {
self.requests += other.requests;
self.tin += other.tin;
self.tout += other.tout;
}
}
// ===========================================================================
// 窗口读数(<日窗id>:<今日>:<累计>:<最近时间戳>)
// ===========================================================================
fn encode(day: i64, u: &Usage) -> String {
format!("{}:{}:{}:{}", day, u.today, u.total, u.last_ts)
}
/// 解码并把"今日数"按当前日窗折算——跨天时旧值归零,累计值保留。
fn decode(payload: &str, day: i64) -> Usage {
let mut it = payload.split(':');
let stored_day = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let last_ts = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
Usage { today: if stored_day == day { today } else { 0 }, total, last_ts }
}
/// 窗口计数 +1(读-增-写不加写锁的近似语义:并发下偶发少计一次,
/// 统计用途无影响;换来的是调用方热路径不为统计抢锁)。
pub fn bump(prefix: &[u8], name: &str, day: i64, now: i64) {
let current = state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default();
let next = Usage {
today: current.today + 1,
total: current.total + 1,
last_ts: now,
};
state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0);
}
/// 读窗口读数(不跨窗折算由 decode 按 day 完成)
pub fn read(prefix: &[u8], name: &str, day: i64) -> Usage {
state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default()
}
// ===========================================================================
// token 窗口读数(<日窗id>:<入今日>:<入累计>:<出今日>:<出累计>:<最近时间戳>)
// ===========================================================================
fn encode_t(day: i64, t: &TokenUsage) -> String {
format!(
"{}:{}:{}:{}:{}:{}",
day, t.tin_today, t.tin_total, t.tout_today, t.tout_total, t.last_ts
)
}
fn decode_t(payload: &str, day: i64) -> TokenUsage {
let mut it = payload.split(':');
let stored_day = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let in_today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let in_total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let out_today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let out_total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let last_ts = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let live = stored_day == day;
TokenUsage {
tin_today: if live { in_today } else { 0 },
tin_total: in_total,
tout_today: if live { out_today } else { 0 },
tout_total: out_total,
last_ts,
}
}
/// token 窗口累加(同 bump 的近似语义)
pub fn bump_t(prefix: &[u8], name: &str, tin: u64, tout: u64, day: i64, now: i64) {
let current = state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode_t(&payload, day))
.unwrap_or_default();
let next = TokenUsage {
tin_today: current.tin_today + tin as i64,
tin_total: current.tin_total + tin as i64,
tout_today: current.tout_today + tout as i64,
tout_total: current.tout_total + tout as i64,
last_ts: now,
};
state::put(prefix, name.as_bytes(), encode_t(day, &next).as_bytes(), 0);
}
/// 读 token 窗口读数
pub fn read_t(prefix: &[u8], name: &str, day: i64) -> TokenUsage {
state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode_t(&payload, day))
.unwrap_or_default()
}
// ===========================================================================
// 日桶(趋势图数据源)
// ===========================================================================
//
// 以自然日为键的桶:一个桶一天,读取时按日窗 id **精确取键**(get_live),
// 不做前缀扫描——键数随时间增长也不会拖慢任何热路径。
// TTL 由调用方传入(业务保留策略属于插件,不属于本模块)。
/// `<请求数>:<入token>:<出token>`
fn encode_day(b: &DayBucket) -> String {
format!("{}:{}:{}", b.requests, b.tin, b.tout)
}
fn decode_day(payload: &str) -> DayBucket {
let mut it = payload.split(':');
let num = |v: Option<&str>| v.and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
DayBucket {
requests: num(it.next()),
tin: num(it.next()),
tout: num(it.next()),
}
}
/// 累加一日桶。`ttl_secs` 为保留时长(到期由共享内存自然淘汰)。
pub fn bump_day(prefix: &[u8], name: &str, delta: &DayBucket, ttl_secs: i64) {
let mut next = state::get_live(prefix, name.as_bytes(), util::now())
.map(|p| decode_day(&p))
.unwrap_or_default();
next.merge(delta);
// 写入失败只记日志:统计是旁路功能,绝不影响转发
if !state::put(
prefix,
name.as_bytes(),
encode_day(&next).as_bytes(),
util::now() + ttl_secs,
) {
util::log_err("[usage] 日桶写入失败(共享内存不足?)");
}
}
/// 读一个日桶(不存在 = 全 0)
pub fn day_bucket(prefix: &[u8], name: &str) -> DayBucket {
state::get_live(prefix, name.as_bytes(), util::now())
.map(|p| decode_day(&p))
.unwrap_or_default()
}