@mzzsfy/dsh-usage-dash 0.1.0

package/src/query.js

@@ -0,0 +1,193 @@
+// 用量聚合纯函数:store 行形状仅作数据约定,零宿主依赖。
+// 桶串本地时区推导,同粒度字典序即时间序;daily 零值槽全枚举,超槽数保最新丢最旧。
+
+import { costOf, matchPrice } from './pricing.js'
+
+export const MAX_SLOTS = 2000
+
+const PAD_WIDTH = 2
+const PERCENT_SCALE = 100
+
+const GRANULARITY_DAILY = 'D'
+const GRANULARITY_HOURLY = 'H'
+const GRANULARITY_MINUTE = 'M'
+
+const DAY_KEY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+const HOUR_KEY_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}$/
+const MINUTE_KEY_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/
+
+// 桶串前缀宽:D 段定位日槽,M 行截取父 H 桶
+const DAY_KEY_WIDTH = 'YYYY-MM-DD'.length
+const HOUR_KEY_WIDTH = 'YYYY-MM-DDTHH'.length
+
+const pad = (value) => String(value).padStart(PAD_WIDTH, '0')
+const formatDate = (date) => `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+const formatHour = (date) => `${formatDate(date)}T${pad(date.getHours())}`
+const formatMinute = (date) => `${formatHour(date)}:${pad(date.getMinutes())}`
+
+const nextDay = (date) => {
+  const next = new Date(date)
+  next.setDate(next.getDate() + 1)
+  return next
+}
+const nextHour = (date) => {
+  const next = new Date(date)
+  next.setHours(next.getHours() + 1)
+  return next
+}
+const nextMinute = (date) => {
+  const next = new Date(date)
+  next.setMinutes(next.getMinutes() + MINUTE_STEP_MINUTES)
+  return next
+}
+
+// 分钟桶粒度:枚举与桶键共用同一步长,from 必须对齐桶边界
+const MINUTE_STEP_MINUTES = 10
+
+// pattern 锚定桶串形态,suffix 补全为本地时区可解析日期串,format 回读校验分量合法性
+const BUCKET_FORMS = {
+  [GRANULARITY_DAILY]: { pattern: DAY_KEY_PATTERN, suffix: 'T00:00:00', format: formatDate, step: nextDay },
+  [GRANULARITY_HOURLY]: { pattern: HOUR_KEY_PATTERN, suffix: ':00:00', format: formatHour, step: nextHour },
+  [GRANULARITY_MINUTE]: { pattern: MINUTE_KEY_PATTERN, suffix: ':00', format: formatMinute, step: nextMinute, align: MINUTE_STEP_MINUTES },
+}
+
+const parseBucketKey = (key, form) => {
+  if (typeof key !== 'string' || !form.pattern.test(key)) return null
+  const parsed = new Date(`${key}${form.suffix}`)
+  return Number.isNaN(parsed.getTime()) || form.format(parsed) !== key ? null : parsed
+}
+
+const enumerateBucketKeys = (form) => (from, to) => {
+  const start = parseBucketKey(from, form)
+  const end = parseBucketKey(to, form)
+  if (!start || !end) return []
+  if (form.align && start.getMinutes() % form.align !== 0) return []
+  const keys = []
+  for (let cursor = start, key = form.format(cursor); key <= to; key = form.format(cursor)) {
+    keys.push(key)
+    cursor = form.step(cursor)
+  }
+  return keys
+}
+
+export const daysInRange = enumerateBucketKeys(BUCKET_FORMS[GRANULARITY_DAILY])
+export const hourKeysInRange = enumerateBucketKeys(BUCKET_FORMS[GRANULARITY_HOURLY])
+export const minuteKeysInRange = enumerateBucketKeys(BUCKET_FORMS[GRANULARITY_MINUTE])
+
+const emptySlot = (day) => ({
+  day,
+  total: 0,
+  byModel: {},
+  byProvider: {},
+  requests: 0,
+  turns: 0,
+  cacheHit: 0,
+  cacheMiss: 0,
+})
+
+const addRowToSlot = (slot, row, tokens) => {
+  slot.total += tokens
+  slot.requests += row.requests
+  slot.turns += row.turns
+  slot.cacheHit += row.cacheReadTokens
+  slot.cacheMiss += row.inputTokens + row.cacheWriteTokens
+}
+
+const percentOf = (part, total) => (total === 0 ? 0 : (part / total) * PERCENT_SCALE)
+
+const rowTokens = (row) => row.inputTokens + row.outputTokens + row.cacheReadTokens + row.cacheWriteTokens
+
+export function aggregateRange(rows, g, from, to) {
+  const form = BUCKET_FORMS[g]
+  const slots = enumerateBucketKeys(form)(from, to).map((key) => emptySlot(key))
+  const slotByKey = new Map(slots.map((slot) => [slot.day, slot]))
+  const modelTotals = new Map()
+  const providerTotals = new Map()
+  const activeBuckets = new Set()
+  for (const row of rows) {
+    const slot = slotByKey.get(row.bucket)
+    // 桶串未落在枚举序列(如改粒度前的历史残行)不可归属,跳过防崩
+    if (!slot) continue
+    const tokens = rowTokens(row)
+    addRowToSlot(slot, row, tokens)
+    if (tokens === 0) continue
+    activeBuckets.add(row.bucket)
+    slot.byModel[row.model] = (slot.byModel[row.model] ?? 0) + tokens
+    slot.byProvider[row.provider] = (slot.byProvider[row.provider] ?? 0) + tokens
+    const modelTotal = modelTotals.get(row.model)
+    if (modelTotal) modelTotal.tokens += tokens
+    else modelTotals.set(row.model, { provider: row.provider, tokens })
+    providerTotals.set(row.provider, (providerTotals.get(row.provider) ?? 0) + tokens)
+  }
+  const totals = { tokens: 0, requests: 0, turns: 0, cacheHit: 0, cacheMiss: 0 }
+  for (const slot of slots) {
+    totals.tokens += slot.total
+    totals.requests += slot.requests
+    totals.turns += slot.turns
+    totals.cacheHit += slot.cacheHit
+    totals.cacheMiss += slot.cacheMiss
+  }
+  const models = [...modelTotals.entries()]
+    .map(([model, agg]) => ({ model, provider: agg.provider, tokens: agg.tokens, percent: percentOf(agg.tokens, totals.tokens) }))
+    .sort((a, b) => b.tokens - a.tokens)
+  const providers = [...providerTotals.entries()]
+    .map(([provider, tokens]) => ({ provider, tokens, percent: percentOf(tokens, totals.tokens) }))
+    .sort((a, b) => b.tokens - a.tokens)
+  const truncated = slots.length > MAX_SLOTS
+  const daily = truncated ? slots.slice(-MAX_SLOTS) : slots
+  const top = models[0]
+  const result = {
+    from,
+    to,
+    tokens: totals.tokens,
+    requests: totals.requests,
+    turns: totals.turns,
+    cacheHit: totals.cacheHit,
+    cacheMiss: totals.cacheMiss,
+    activeDays: activeBuckets.size,
+    topModel: top?.model ?? '',
+    topProvider: top?.provider ?? '',
+    daily,
+    models,
+    providers,
+  }
+  if (truncated) result.truncated = true
+  return result
+}
+
+// 聚合计价的槽定位:D 折叠到日槽,H/M 即本槽;计价一律取行所属 H 桶起点
+const COST_SLOT_KEYS = {
+  [GRANULARITY_DAILY]: (bucket) => bucket.slice(0, DAY_KEY_WIDTH),
+  [GRANULARITY_HOURLY]: (bucket) => bucket,
+  [GRANULARITY_MINUTE]: (bucket) => bucket,
+}
+
+// 聚合计价:以可见槽为唯一口径,cost 行按 H 桶起点匹配价格后累加;
+// unpriced = 有 token 而未命中价的去重 H 桶数,被截断丢弃的行整体不参与。
+// 纯函数返回新 result,不修改入参;调用方不调用则响应无 cost/unpriced 字段
+export function attachCosts(result, costRows, granularity, rules) {
+  const slotKeyOf = COST_SLOT_KEYS[granularity]
+  const slotOfDay = new Map(result.daily.map((slot) => [slot.day, slot]))
+  const slotCosts = new Map()
+  const modelCosts = new Map(result.models.map((entry) => [entry.model, 0]))
+  const unpricedHours = new Set()
+  for (const row of costRows) {
+    const slot = slotOfDay.get(slotKeyOf(row.bucket))
+    if (!slot || rowTokens(row) === 0) continue
+    const hourKey = row.bucket.slice(0, HOUR_KEY_WIDTH)
+    const date = parseBucketKey(hourKey, BUCKET_FORMS[GRANULARITY_HOURLY])
+    if (!date) continue
+    const price = matchPrice(rules, row.model, date)
+    if (!price) {
+      unpricedHours.add(hourKey)
+      continue
+    }
+    const cost = costOf(price, row)
+    slotCosts.set(slot.day, (slotCosts.get(slot.day) ?? 0) + cost)
+    if (modelCosts.has(row.model)) modelCosts.set(row.model, modelCosts.get(row.model) + cost)
+  }
+  const daily = result.daily.map((slot) => ({ ...slot, cost: slotCosts.get(slot.day) ?? 0 }))
+  const cost = daily.reduce((sum, slot) => sum + slot.cost, 0)
+  const models = result.models.map((entry) => ({ ...entry, cost: modelCosts.get(entry.model) }))
+  return { ...result, daily, models, cost, unpriced: unpricedHours.size }
+}

package/src/routes.js

@@ -0,0 +1,323 @@
+// 用量统计数据路由:6 个 exact 端点共用守卫/校验/信封管线,粒度由路径分派,
+// pricing 端点守卫放宽(GET/POST 放行、不要求 content-type)。
+// 协议契约见 docs/feat-usage-dash/host-design.md 端点章:成功 {ok:true,value},
+// UsageError 回其 status 与 message(code 恒 usage_api_error),栅栏 forbidden,
+// 未匹配 not_found,其余一切 500 固定文案不回显内部文本。
+
+import { z } from 'zod'
+
+import { aggregateRange, attachCosts } from './query.js'
+import { CURRENCIES, CONDITION_KINDS, UNIT_PER_MILLION } from './pricing.js'
+import {
+  GRANULARITY_DAILY,
+  GRANULARITY_HOURLY,
+  GRANULARITY_MINUTE,
+  MINUTE_BUCKET_SPAN_MINUTES,
+  clampMinuteRetentionDays,
+  minuteKey,
+} from './store.js'
+
+const ROUTE_PREFIX = '/api/usage-dash'
+const MS_PER_DAY = 24 * 60 * 60 * 1000
+export const MAX_RANGE_SPAN_DAYS = 366
+const MAX_JSON_BODY_BYTES = 64 * 1024
+
+const HTTP_STATUS_OK = 200
+const HTTP_STATUS_BAD_REQUEST = 400
+const HTTP_STATUS_FORBIDDEN = 403
+const HTTP_STATUS_NOT_FOUND = 404
+const HTTP_STATUS_METHOD_NOT_ALLOWED = 405
+const HTTP_STATUS_PAYLOAD_TOO_LARGE = 413
+const HTTP_STATUS_CONFLICT = 409
+const HTTP_STATUS_UNAVAILABLE = 503
+const HTTP_STATUS_INTERNAL_ERROR = 500
+
+const ERROR_PREFIX = 'usage stats: '
+const MESSAGE_BACKFILL_RUNNING = `${ERROR_PREFIX}backfill already running`
+const MESSAGE_METHOD_NOT_ALLOWED = `${ERROR_PREFIX}method not allowed`
+const MESSAGE_CROSS_ORIGIN = 'cross-origin request rejected'
+const MESSAGE_CONTENT_TYPE = `${ERROR_PREFIX}content-type must be application/json`
+const MESSAGE_RANGE_REQUIRED = `${ERROR_PREFIX}from and to are required`
+const MESSAGE_INVALID_PRICING = `${ERROR_PREFIX}invalid pricing rules`
+const MESSAGE_PRICING_UNAVAILABLE = `${ERROR_PREFIX}pricing unavailable`
+const MESSAGE_INVALID_JSON = 'invalid json body'
+const MESSAGE_INTERNAL_ERROR = 'internal error'
+
+const CODE_USAGE_API_ERROR = 'usage_api_error'
+const CODE_FORBIDDEN = 'forbidden'
+const CODE_NOT_FOUND = 'not_found'
+
+const METHOD_GET = 'GET'
+const METHOD_POST = 'POST'
+const CONTENT_TYPE_JSON = 'application/json'
+const QUERY_SEPARATOR = /[?#]/
+const EMPTY_BUCKET = ''
+
+// D 端点按同窗口 H 行折叠费用:H 桶串字典序大于日键,读 H 行时上界补足当日末小时
+const HOURS_PER_DAY = 24
+const HOUR_LABEL_WIDTH = 2
+const LAST_HOUR_OF_DAY = `T${String(HOURS_PER_DAY - 1).padStart(HOUR_LABEL_WIDTH, '0')}`
+
+// 定价规则 wire 契约:kind 判别取 pricing 模块常量,单一来源;未知键由 zod 剥离
+const WEEKDAY_MIN = 0
+const WEEKDAY_MAX = 6
+
+const CONDITION_FIELD_SCHEMAS = {
+  dailyWindow: { from: z.string(), to: z.string() },
+  weekdays: { days: z.array(z.number().int().min(WEEKDAY_MIN).max(WEEKDAY_MAX)) },
+  monthDays: { from: z.number().int(), to: z.number().int() },
+  dateRange: { from: z.string(), to: z.string() },
+}
+
+const conditionSchema = z.union(
+  CONDITION_KINDS.map((kind) => z.object({ kind: z.literal(kind), ...CONDITION_FIELD_SCHEMAS[kind] })),
+)
+
+const pricingRulesSchema = z.array(
+  z.object({
+    model: z.string(),
+    unit: z.literal(UNIT_PER_MILLION).optional(),
+    currency: z.enum(CURRENCIES).nullable(),
+    price: z.object({
+      input: z.number().min(0),
+      output: z.number().min(0),
+      cacheRead: z.number().min(0),
+      cacheWrite: z.number().min(0),
+    }),
+    conditions: z.array(conditionSchema),
+  }),
+)
+
+// 桶串形态锚定 + 本地时区分量回读,回滚形(13 月/25 时/60 分)当场拒绝,
+// 与 query.js 桶串推导同源
+const DAY_KEY_PARTS = /^(\d{4})-(\d{2})-(\d{2})$/
+const HOUR_KEY_PARTS = /^(\d{4})-(\d{2})-(\d{2})T(\d{2})$/
+const MINUTE_KEY_PARTS = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
+
+const DATE_COMPONENTS = [
+  (date) => date.getFullYear(),
+  (date) => date.getMonth() + 1,
+  (date) => date.getDate(),
+  (date) => date.getHours(),
+  (date) => date.getMinutes(),
+]
+
+class UsageError extends Error {
+  constructor(status, message, code = CODE_USAGE_API_ERROR) {
+    super(message)
+    this.status = status
+    this.code = code
+  }
+}
+
+const usageError = (status, message, code) => new UsageError(status, message, code)
+
+function writeJson(res, value, status = HTTP_STATUS_OK) {
+  res.statusCode = status
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(value))
+}
+
+function writeError(ctx, res, err) {
+  if (err instanceof UsageError) {
+    writeJson(res, { ok: false, error: { code: err.code, message: err.message } }, err.status)
+    return
+  }
+  ctx.logger?.warn?.(`usage-dash: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`)
+  writeJson(res, { ok: false, error: { code: CODE_USAGE_API_ERROR, message: MESSAGE_INTERNAL_ERROR } }, HTTP_STATUS_INTERNAL_ERROR)
+}
+
+async function readJsonBody(req, maxBytes = MAX_JSON_BODY_BYTES) {
+  const chunks = []
+  let total = 0
+  for await (const chunk of req) {
+    total += typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.byteLength
+    if (total > maxBytes) throw usageError(HTTP_STATUS_PAYLOAD_TOO_LARGE, `request body exceeds ${maxBytes} bytes`)
+    chunks.push(chunk)
+  }
+  if (chunks.length === 0) return undefined
+  const text = Buffer
+    .concat(chunks.map((chunk) => (typeof chunk === 'string' ? Buffer.from(chunk) : chunk)))
+    .toString('utf8')
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw usageError(HTTP_STATUS_BAD_REQUEST, MESSAGE_INVALID_JSON)
+  }
+}
+
+// 同源守卫:浏览器写请求恒带 Origin,与 Host 不符即拒;无 Origin 的非浏览器客户端放行
+function rejectCrossOrigin(req) {
+  const origin = req.headers?.origin
+  if (!origin) return
+  let sameOrigin = false
+  try {
+    sameOrigin = new URL(origin).host === req.headers?.host
+  } catch {
+    sameOrigin = false
+  }
+  if (!sameOrigin) throw usageError(HTTP_STATUS_FORBIDDEN, MESSAGE_CROSS_ORIGIN, CODE_FORBIDDEN)
+}
+
+function rejectNonJson(req) {
+  const contentType = String(req.headers?.['content-type'] ?? '')
+  if (!contentType.includes(CONTENT_TYPE_JSON)) throw usageError(HTTP_STATUS_BAD_REQUEST, MESSAGE_CONTENT_TYPE)
+}
+
+function rejectWrongMethod(req) {
+  if ((req.method ?? METHOD_GET) !== METHOD_POST) {
+    throw usageError(HTTP_STATUS_METHOD_NOT_ALLOWED, MESSAGE_METHOD_NOT_ALLOWED)
+  }
+}
+
+// pricing 端点放宽:GET 读 POST 写均放行且不要求 content-type,其余方法照拒
+function rejectPricingMethod(req) {
+  const method = req.method ?? METHOD_GET
+  if (method !== METHOD_GET && method !== METHOD_POST) {
+    throw usageError(HTTP_STATUS_METHOD_NOT_ALLOWED, MESSAGE_METHOD_NOT_ALLOWED)
+  }
+}
+
+function parseBucketParts(value, pattern) {
+  if (typeof value !== 'string') return null
+  const match = pattern.exec(value)
+  if (!match) return null
+  const parts = match.slice(1).map(Number)
+  const date = new Date(parts[0], parts[1] - 1, parts[2], ...parts.slice(3))
+  return DATE_COMPONENTS.slice(0, parts.length).every((component, i) => component(date) === parts[i]) ? parts : null
+}
+
+function requireBucketRange(body, pattern, keyLabel) {
+  const from = body?.from
+  const to = body?.to
+  if (typeof from !== 'string' || typeof to !== 'string') {
+    throw usageError(HTTP_STATUS_BAD_REQUEST, MESSAGE_RANGE_REQUIRED)
+  }
+  const fromParts = parseBucketParts(from, pattern)
+  const toParts = parseBucketParts(to, pattern)
+  if (!fromParts || !toParts) throw usageError(HTTP_STATUS_BAD_REQUEST, `${ERROR_PREFIX}invalid ${keyLabel}`)
+  if (to < from) throw usageError(HTTP_STATUS_BAD_REQUEST, `${ERROR_PREFIX}to must not precede from`)
+  return { from, to, fromParts, toParts }
+}
+
+const utcDayOf = (parts) => Date.UTC(parts[0], parts[1] - 1, parts[2])
+
+// 聚合 + 定价注入:pricing 激活才挂 cost/unpriced,缺省响应形状与现状一致;
+// D 端点费用由同窗口 H 行折叠,其余粒度计价行即聚合行
+async function aggregateWithPricing(deps, granularity, from, to) {
+  const rows = await deps.store.rangeRows(granularity, from, to)
+  let value = aggregateRange(rows, granularity, from, to)
+  const pricing = deps.pricing
+  if (pricing?.active) {
+    const costRows = granularity === GRANULARITY_DAILY
+      ? await deps.store.rangeRows(GRANULARITY_HOURLY, from, `${to}${LAST_HOUR_OF_DAY}`)
+      : rows
+    value = attachCosts(value, costRows, granularity, pricing.rules())
+  }
+  return value
+}
+
+async function respondAggregate(deps, res, granularity, from, to) {
+  writeJson(res, { ok: true, value: await aggregateWithPricing(deps, granularity, from, to) })
+}
+
+const rangeHandler = (deps) => async (req, res) => {
+  const { from, to, fromParts, toParts } = requireBucketRange(await readJsonBody(req), DAY_KEY_PARTS, 'day key')
+  const spanDays = (utcDayOf(toParts) - utcDayOf(fromParts)) / MS_PER_DAY + 1
+  if (spanDays > MAX_RANGE_SPAN_DAYS) {
+    throw usageError(HTTP_STATUS_BAD_REQUEST, `${ERROR_PREFIX}span exceeds ${MAX_RANGE_SPAN_DAYS} days`)
+  }
+  await respondAggregate(deps, res, GRANULARITY_DAILY, from, to)
+}
+
+const hoursHandler = (deps) => async (req, res) => {
+  const { from, to } = requireBucketRange(await readJsonBody(req), HOUR_KEY_PARTS, 'hour key')
+  await respondAggregate(deps, res, GRANULARITY_HOURLY, from, to)
+}
+
+// 分钟保留窗口(天)换算为起点桶串:起点晚于请求 from 即窗口外已清理,
+// 标注实际可用范围;禁用(0)时恒无数据,covered 标注空串。
+// retentionDays 经 clamp 归一(非法回落默认,超上限截断),与 store.pruneMinutes 同源
+const minuteHandler = (deps) => async (req, res) => {
+  const { from, to, fromParts } = requireBucketRange(await readJsonBody(req), MINUTE_KEY_PARTS, 'minute key')
+  if (fromParts[fromParts.length - 1] % MINUTE_BUCKET_SPAN_MINUTES !== 0) {
+    throw usageError(HTTP_STATUS_BAD_REQUEST, `${ERROR_PREFIX}minute key must align to ${MINUTE_BUCKET_SPAN_MINUTES} minutes`)
+  }
+  const value = await aggregateWithPricing(deps, GRANULARITY_MINUTE, from, to)
+  const retention = clampMinuteRetentionDays(deps.retentionDays())
+  if (retention > 0) {
+    const windowStart = minuteKey(deps.now() - retention * MS_PER_DAY)
+    if (windowStart > from) Object.assign(value, { coveredFrom: windowStart, coveredTo: to })
+  } else {
+    Object.assign(value, { coveredFrom: EMPTY_BUCKET, coveredTo: EMPTY_BUCKET })
+  }
+  writeJson(res, { ok: true, value })
+}
+
+// pricing 端点:GET 回 {revision, rules};POST 整表替换经 zod 校验后写入并回读。
+// settings 未激活时能力缺席,GET 走空值桩,POST 拒 503——能力缺席属服务暂
+// 不可用而非请求状态冲突,不用 409
+const INACTIVE_PRICING = { active: false, rules: () => [], revision: () => 0 }
+
+const pricingHandler = (deps) => async (req, res) => {
+  const pricing = deps.pricing ?? INACTIVE_PRICING
+  if ((req.method ?? METHOD_GET) === METHOD_GET) {
+    writeJson(res, { ok: true, value: { revision: pricing.revision(), rules: pricing.rules() } })
+    return
+  }
+  if (!pricing.active) throw usageError(HTTP_STATUS_UNAVAILABLE, MESSAGE_PRICING_UNAVAILABLE)
+  const parsed = pricingRulesSchema.safeParse((await readJsonBody(req))?.rules)
+  if (!parsed.success) throw usageError(HTTP_STATUS_BAD_REQUEST, MESSAGE_INVALID_PRICING)
+  const rules = await pricing.replace(parsed.data)
+  writeJson(res, { ok: true, value: { revision: pricing.revision(), rules } })
+}
+
+const statusHandler = (deps) => async (req, res) => {
+  writeJson(res, { ok: true, value: deps.collector.status() })
+}
+
+// 409 只拒 boot 期扫描;reset 自身引发的重扫同样 running 为真,经 rebuilding 放行
+const resetHandler = (deps) => async (req, res) => {
+  if (deps.collector.running && !deps.collector.rebuilding) {
+    throw usageError(HTTP_STATUS_CONFLICT, MESSAGE_BACKFILL_RUNNING)
+  }
+  await deps.collector.resetAndRescan()
+  writeJson(res, { ok: true, value: deps.collector.status() })
+}
+
+const STANDARD_GUARDS = [rejectWrongMethod, rejectCrossOrigin, rejectNonJson]
+const PRICING_GUARDS = [rejectPricingMethod, rejectCrossOrigin]
+
+const ENDPOINTS = [
+  { path: `${ROUTE_PREFIX}/range`, mount: rangeHandler },
+  { path: `${ROUTE_PREFIX}/hours`, mount: hoursHandler },
+  { path: `${ROUTE_PREFIX}/minutes`, mount: minuteHandler },
+  { path: `${ROUTE_PREFIX}/status`, mount: statusHandler },
+  { path: `${ROUTE_PREFIX}/reset`, mount: resetHandler },
+  { path: `${ROUTE_PREFIX}/pricing`, mount: pricingHandler, guards: PRICING_GUARDS },
+]
+
+const routePathOf = (req) => (req.url ?? '').split(QUERY_SEPARATOR, 1)[0]
+
+export function registerUsageRoutes(ctx, { store, collector, retentionDays, now = Date.now, pricing }) {
+  const deps = { store, collector, retentionDays, now, pricing }
+  const handlers = new Map(ENDPOINTS.map((endpoint) => [endpoint.path, {
+    handler: endpoint.mount(deps),
+    guards: endpoint.guards ?? STANDARD_GUARDS,
+  }]))
+  // exact 注册下宿主只会命中自有路径,此处仍按路径精确等值分派,未匹配即 404
+  const dispatch = async (req, res) => {
+    try {
+      const path = routePathOf(req)
+      const matched = handlers.get(path)
+      if (!matched) throw usageError(HTTP_STATUS_NOT_FOUND, `unknown endpoint ${path}`, CODE_NOT_FOUND)
+      for (const guard of matched.guards) guard(req)
+      await matched.handler(req, res)
+    } catch (err) {
+      writeError(ctx, res, err)
+    }
+  }
+  const disposers = ENDPOINTS.map(({ path }) =>
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path, handler: dispatch }), `usage-dash: route ${path}`))
+  return () => disposers.forEach((dispose) => dispose?.())
+}