dsh-usage-badge 0.1.2 → 0.1.4

package/lib/index.js

@@ -18,7 +18,8 @@
 import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { createAggregator, resolveDshHome } from './fold.js'
+import { createCacheStore } from './cache-store.js'
+import { createAggregator, mergeRecords, resolveDshHome } from './fold.js'
 import { describeCalendar, loadBundledTable, resolveHolidayRules } from './holidays.js'
 import { OFFICIAL_SOURCES, applyOfficialPricing, fetchOfficialPricing } from './official-pricing.js'
 import {
@@ -27,6 +28,7 @@ import {
   bucketHourlyCosts,
   dayContext,
   dayKey,
+  isUnpriced,
   normalizePricing,
   timeOfUseState,
   totalCurrencyOf,
@@ -41,13 +43,33 @@ export const name = 'usage-badge'
 /** Route prefix owned by this plugin. */
 const ROUTE_PREFIX = '/usage-badge'
 
+/**
+ * What the browser half requires of the host half, and what this build provides.
+ *
+ * Bump it whenever the panel starts depending on something only a newer host does — an
+ * accepted patch key, a field in a response. The host half is loaded when the DSH process
+ * starts while the browser half is re-read on every page load, so a refreshed page against
+ * an unrestarted host is the normal way to get a UI whose buttons silently do nothing
+ * (an unknown patch key is accepted with a 200 and ignored). The panel compares this number
+ * and says so instead. `test/client.render.mjs` asserts the two halves agree.
+ */
+export const HOST_API_VERSION = 6
+
 /**
  * Directory under `$DSH_HOME/storages` holding every file this plugin owns, so its
  * cache and price table are never mistaken for harness data in the shared root.
  */
 const DATA_DIR_NAME = 'usage-badge'
 
-/** Calendar days retained in the payload; covers the 12-month view plus slack. */
+/**
+ * How many of the newest days **that have usage** travel in the payload; covers the 12-month view
+ * plus slack.
+ *
+ * Not a calendar-day window: the snapshot takes the newest 400 entries of the in-memory day map, so
+ * a sparse history reaches further back than 400 days — and a dense one stops inside them. The
+ * store's loading window (`CACHE_WINDOW_DAYS`) is a separate, calendar-day bound on what is read
+ * back from disk; it is deliberately wider so it never truncates what this can ask for.
+ */
 const DAYS_KEPT = 400
 
 /** A snapshot younger than this is reused instead of rebuilt on every poll. */
@@ -157,11 +179,94 @@ function summarizeDay(dayObj, pricing, date, withHourly, rules) {
     },
     providers: [...providers.values()]
       .sort((a, b) => b.amount - a.amount || a.provider.localeCompare(b.provider))
-      .map((row) => ({ ...row, amount: round(row.amount, 4), hourly: roundSeries(row.hourly) })),
+      .map((row) => {
+        const base = { ...row, amount: round(row.amount, 4) }
+        // Only the 24-hour view asks for a per-hour series, and a row without one omits the key
+        // rather than carrying `hourly: null`, so a month row and a day row have the same shape.
+        if (row.hourly) base.hourly = roundSeries(row.hourly)
+        return base
+      }),
     hourly: roundSeries(dayHours),
   }
 }
 
+/**
+ * Fold one calendar year's day rows into twelve natural months.
+ *
+ * All twelve are always present, in order, empty ones included: a month bar has to line up
+ * across years, and "no usage in March" is a fact about March rather than a month to drop.
+ * Costing is the day summariser's, day by day and request by request, so a month total is the
+ * sum of its days and nothing is priced at a coarser granularity than the daily charts use.
+ *
+ * @param {Map<string, Map<string, object>>} dayRows - merged day buckets, as `mergeRecords`
+ *   produces them, already restricted to the year.
+ */
+function summarizeYear(dayRows, pricing, rules, year) {
+  const months = Array.from({ length: 12 }, (_, index) => ({
+    month: `${year}-${String(index + 1).padStart(2, '0')}`,
+    label: `${index + 1}月`,
+    amount: 0,
+    requests: 0,
+    input: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    output: 0,
+    providers: new Map(),
+  }))
+  // The year's days travel with the months: the heatmap next to the monthly chart is a calendar
+  // grid, and days older than the loading window are not in the snapshot at all.
+  const days = []
+
+  for (const [date, dayObj] of dayRows) {
+    const month = months[Number(date.slice(5, 7)) - 1]
+    if (!month) continue
+    const summary = summarizeDay(dayObj, pricing, date, false, rules)
+    days.push(dayRow(date, summary, rules))
+    addTokens(month, summary.totals, summary.totals.amount)
+    for (const row of summary.providers) {
+      const target = month.providers.get(row.provider) ?? {
+        provider: row.provider,
+        amount: 0,
+        requests: 0,
+        input: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        output: 0,
+      }
+      addTokens(target, row, row.amount)
+      month.providers.set(row.provider, target)
+    }
+  }
+
+  const total = { amount: 0, requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 }
+  for (const month of months) {
+    total.amount += month.amount
+    total.requests += month.requests
+    total.input += month.input
+    total.cacheRead += month.cacheRead
+    total.cacheWrite += month.cacheWrite
+    total.output += month.output
+  }
+
+  return {
+    year: Number(year),
+    // How many days of that year this is based on, so an empty year is legible. Counted from the
+    // rows actually reported, not from the input map — a row whose date is unparseable is skipped
+    // and must not be counted as a day the caller can see.
+    days: days.length,
+    months: months.map((month) => ({
+      ...month,
+      amount: round(month.amount, 4),
+      providers: [...month.providers.values()]
+        .sort((a, b) => b.amount - a.amount || a.provider.localeCompare(b.provider))
+        .map((row) => ({ ...row, amount: round(row.amount, 4) })),
+    })),
+    // The days that had usage, oldest first — the calendar grid fills in the quiet ones itself.
+    daily: days,
+    total: { ...total, amount: round(total.amount, 4) },
+  }
+}
+
 /**
  * Recover the `provider|model` route behind a provider row, so a per-model
  * pricing rule can be evaluated for the period indicator. A provider row is
@@ -178,8 +283,50 @@ function dominantRouteOf(dayObj, providerName) {
   return best?.model ?? null
 }
 
+/**
+ * Routes inside the snapshot window that have usage but no price at all.
+ *
+ * Only reachable with `priceUnmatchedModels` off. The snapshot reports them because a
+ * route that contributes tokens and ¥0 is indistinguishable from a free one — the panel
+ * has to be able to say which models the amount is missing, or the total would be a
+ * silently wrong number of exactly the kind this plugin avoids everywhere else.
+ */
+function collectUnpriced(pricing, dayObjs, dates) {
+  // The common case by far: every model is priced, so there is nothing to walk. Answering
+  // before the loop keeps this off the snapshot-building path for tables that never ask.
+  if (pricing.priceUnmatchedModels !== false) return []
+  const window = new Set(dates)
+  const routes = new Map()
+  for (const [date, dayObj] of dayObjs) {
+    if (!window.has(date)) continue
+    for (const bucket of dayObj.values()) {
+      if (!isUnpriced(pricing, bucket.provider, bucket.model)) continue
+      const provider = String(bucket.provider ?? '').trim() || 'unknown'
+      const model = String(bucket.model ?? '').trim() || 'unknown'
+      const key = `${provider}|${model}`
+      const row = routes.get(key) ?? { provider, model, tokens: 0, requests: 0 }
+      row.tokens += (bucket.input || 0) + (bucket.cacheRead || 0) + (bucket.cacheWrite || 0) + (bucket.output || 0)
+      row.requests += bucket.requests || 0
+      routes.set(key, row)
+    }
+  }
+  return [...routes.values()].sort((a, b) => b.tokens - a.tokens || a.model.localeCompare(b.model))
+}
+
+/**
+ * One day, as a row: totals, per-provider splits, and the day's own classification.
+ *
+ * Shared by the snapshot and the year view, because both feed the same chart and the same
+ * heatmap, and a day that read differently in the two would be a bug with no upside. The marks
+ * travel with the row because it is the only way to read a past day's holiday status back.
+ */
+function dayRow(date, summary, rules) {
+  const context = dayContext(date, rules)
+  return { date, ...summary.totals, providers: summary.providers, dayClass: context.class, dayName: context.name }
+}
+
 /** Build the payload the browser half renders. */
-function buildSnapshot(aggregator, pricing, rules, status) {
+function buildSnapshot(aggregator, pricing, rules, status, years = []) {
   const now = Date.now()
   const today = dayKey(now)
   const dayObjs = aggregator.days
@@ -188,16 +335,13 @@ function buildSnapshot(aggregator, pricing, rules, status) {
   const todayObj = dayObjs.get(today)
   const todaySummary = summarizeDay(todayObj, pricing, today, true, rules)
 
-  const days = dates.map((date) => {
-    // The day's own classification travels with its row: the panel marks holidays
-    // on the chart, and it is the only way to read a past day's holiday status
-    // back from a snapshot.
-    const context = dayContext(date, rules)
-    const marks = { dayClass: context.class, dayName: context.name }
-    if (date === today) return { date, ...todaySummary.totals, providers: todaySummary.providers, ...marks }
-    const summary = summarizeDay(dayObjs.get(date), pricing, date, false, rules)
-    return { date, ...summary.totals, providers: summary.providers, ...marks }
-  })
+  const days = dates.map((date) =>
+    dayRow(
+      date,
+      date === today ? todaySummary : summarizeDay(dayObjs.get(date), pricing, date, false, rules),
+      rules,
+    ),
+  )
 
   // The badge is always CNY: a CNY total needs no rate, a USD total is converted
   // with the live exchange rate.
@@ -224,6 +368,12 @@ function buildSnapshot(aggregator, pricing, rules, status) {
     badge: { date: today, amount: round(badgeCny, 2), currency: 'cny' },
     today: { date: today, ...todaySummary.totals, hourly: todaySummary.hourly, providers: todaySummary.providers },
     days,
+    // Which calendar years have data, newest first. Answered by the store, not by the days
+    // above: the snapshot only carries a window, so a year older than that would be invisible
+    // even though its rows are still on disk.
+    years,
+    // Empty unless unmatched models are deliberately left unpriced.
+    unpriced: collectUnpriced(pricing, dayObjs, dates),
     band,
     calendar: describeCalendar(rules, now),
     status: { ...status, sessions: aggregator.sessionCount },
@@ -258,7 +408,7 @@ function readPricing(paths) {
   return normalizePricing(readRawPricing(paths).raw)
 }
 
-/** Read a request body, bounded. */
+/** Read a request body, bounded. An oversized one is a 413, not a server error. */
 function readBody(req) {
   return new Promise((resolvePromise, rejectPromise) => {
     const chunks = []
@@ -266,7 +416,9 @@ function readBody(req) {
     req.on('data', (chunk) => {
       size += chunk.length
       if (size > MAX_BODY_BYTES) {
-        rejectPromise(new Error('request body too large'))
+        const error = new Error(`request body larger than ${MAX_BODY_BYTES} bytes`)
+        error.statusCode = 413
+        rejectPromise(error)
         req.destroy()
         return
       }
@@ -321,7 +473,19 @@ function mergeConfig(raw, patch) {
   if (patch.exchangeRate !== undefined) next.exchangeRate = Number(patch.exchangeRate) || next.exchangeRate
   if (patch.totalCurrency !== undefined) next.totalCurrency = patch.totalCurrency === 'usd' ? 'usd' : 'cny'
   if (patch.multiplier !== undefined) next.multiplier = Number(patch.multiplier) || 1
-  if (patch.default && typeof patch.default === 'object') next.default = { ...(next.default ?? {}), ...patch.default }
+  // Accepted here even though the panel offers no field for it: only an explicit
+  // `false` turns the model-prefix fallback off.
+  if (patch.modelPrefixFallback !== undefined) next.modelPrefixFallback = patch.modelPrefixFallback !== false
+  // Same shape: only an explicit `false` stops the `default` row pricing unmatched models.
+  if (patch.priceUnmatchedModels !== undefined) next.priceUnmatchedModels = patch.priceUnmatchedModels !== false
+  // The catch-all row is replaced **wholesale**, exactly like `overrides` below — the panel sends
+  // the whole row it was showing, so a field the user cleared has to disappear. Merging instead
+  // (the older behaviour) made clearing a field a silent no-op that still reported success, and
+  // it meant an unwanted `currency` or rate could never be removed from the panel.
+  // `default: null` removes the row; the table then falls back to the built-in template until an
+  // official apply fills it again.
+  if (patch.default === null) delete next.default
+  else if (patch.default && typeof patch.default === 'object') next.default = { ...patch.default }
   if (patch.overrides && typeof patch.overrides === 'object') next.overrides = patch.overrides
   if (patch.timeOfUse !== undefined) next.timeOfUse = patch.timeOfUse
   if (patch.contextMultiplier !== undefined) next.contextMultiplier = patch.contextMultiplier
@@ -342,12 +506,15 @@ export function apply(ctx) {
   // already holds harness caches and, on some installs, other tools' settings.
   const dataDir = join(home, 'storages', DATA_DIR_NAME)
   const pricingPath = join(dataDir, 'pricing.json')
-  const cachePath = join(dataDir, 'cache.json')
   /** Pre-isolation location of the price table, honored as a migration fallback. */
   const legacyPricingPath = join(home, 'storages', 'usage-pricing.json')
   const pricingPaths = [pricingPath, legacyPricingPath]
 
-  const aggregator = createAggregator({ sessionsRoot, cachePath, log })
+  // The folded history lives in whichever store this runtime can offer — SQLite when
+  // `node:sqlite` is there, the original single-document JSON otherwise. Either way it is one
+  // file inside the plugin's own directory.
+  const store = createCacheStore({ dir: dataDir, log })
+  const aggregator = createAggregator({ sessionsRoot, store, log })
   aggregator.loadCache()
 
   const { path: pricingSourcePath } = readRawPricing(pricingPaths)
@@ -381,7 +548,16 @@ export function apply(ctx) {
     // Nothing changed and the previous payload is still fresh: reuse it rather
     // than re-costing every day on each poll.
     if (snapshot && status.folded === 0 && Date.now() - snapshot.generatedAt < SNAPSHOT_TTL_MS) return snapshot
-    snapshot = buildSnapshot(aggregator, pricing, rules, status)
+    // The year list is the one thing here that comes from the store rather than from memory, so a
+    // store that cannot answer must not take the badge down with it: every number in the payload is
+    // already in hand, and the picker simply has nothing to offer.
+    let years = []
+    try {
+      years = store.years()
+    } catch (error) {
+      log(`cache year list failed: ${error?.message ?? error}`)
+    }
+    snapshot = buildSnapshot(aggregator, pricing, rules, status, years)
     return snapshot
   }
 
@@ -406,12 +582,12 @@ export function apply(ctx) {
   async function warm() {
     try {
       const status = await refreshOnce()
-      // Persist straight away rather than waiting for the debounce: the initial
-      // fold is the expensive one, and its timer is unref'd, so a short-lived
-      // host would otherwise pay the full cold scan on every start.
-      if (status.folded > 0) aggregator.saveCache()
+      // The SQLite store has already committed every session it folded; the JSON fallback
+      // batches, and a short-lived host would otherwise pay the full cold scan on every start.
+      aggregator.flush()
       log(
         `ready: ${aggregator.sessionCount} session(s) over ${status.files} log(s), folded ${status.folded} in ${status.ms}ms` +
+          `; cache: ${store.kind}` +
           (rules.enabled ? `; holiday calendar on (${rules.holidays.size} holidays)` : ''),
       )
       if (rules.missingYears?.length) {
@@ -432,15 +608,50 @@ export function apply(ctx) {
         return
       }
 
+      // One calendar year, by month. Read straight from the store rather than from the
+      // snapshot, because a year older than the loading window is not in memory at all — and
+      // it is the store that knows which years exist in the first place.
+      if (route === '/year' && (req.method === 'GET' || req.method === 'HEAD')) {
+        const year = String(url.searchParams.get('year') ?? '')
+        if (!/^\d{4}$/.test(year)) {
+          sendJson(res, 400, { error: `year must be a four-digit calendar year, got ${JSON.stringify(year)}` })
+          return
+        }
+        const records = store.load({ since: `${year}-01-01`, until: `${year}-12-31` })
+        const dayRows = mergeRecords(records)
+        sendJson(res, 200, summarizeYear(dayRows, pricing, rules, year))
+        return
+      }
+
       if (route === '/config' && req.method === 'GET') {
         const calendar = describeCalendar(rules)
         // The bundled table is reported separately from the resolved rules: a
         // deployment with the calendar off still needs to see what data is
         // available before deciding to switch it on.
         const bundled = loadBundledTable()
+        // Read once: both the path the table came from and whether it carries a usable
+        // `default` row, which decides whether that row is the user's or the template's.
+        const raw = readRawPricing(pricingPaths)
+        const rawDefault = raw.raw?.default
+        // A row only counts when it actually says something: `{}` (or a non-object, which a hand
+        // edit can leave) still takes every rate from the template, and reporting that as the
+        // user's row is the silent-template problem this field exists to avoid. The panel clears
+        // all four inputs to `{}` if a save is allowed to, so this is reachable from the UI too.
+        const hasDefaultRow = Boolean(rawDefault) && typeof rawDefault === 'object' && Object.keys(rawDefault).length > 0
         sendJson(res, 200, {
           effective: pricing,
           template: DEFAULT_TEMPLATE,
+          // The handshake the panel checks before trusting a button: see HOST_API_VERSION.
+          apiVersion: HOST_API_VERSION,
+          // Where the `default` row comes from. A table with no `default` row of its own
+          // is priced by the built-in template, and the panel has to say so rather than
+          // present those rates as the user's.
+          defaultSource: hasDefaultRow ? 'file' : 'template',
+          // The row exactly as the file has it, which is what the editor shows and seeds from.
+          // `effective.default` is the template-merged view, and writing *that* back would
+          // materialise template fields nobody wrote — a field the user just cleared would
+          // look like it had come back on the next save.
+          defaultRow: hasDefaultRow ? rawDefault : null,
           calendar,
           bundled: {
             years: [...bundled.years].sort(),
@@ -460,11 +671,13 @@ export function apply(ctx) {
           paths: {
             dataDir,
             pricing: pricingPath,
-            cache: cachePath,
+            // The cache file this runtime is using, whichever backend that turned out to be.
+            cache: store.path,
+            cacheKind: store.kind,
             legacyPricing: legacyPricingPath,
             // Which file the effective table was actually read from; null means
             // neither exists, so the built-in template is in force.
-            pricingSource: readRawPricing(pricingPaths).path,
+            pricingSource: raw.path,
           },
         })
         return
@@ -516,6 +729,7 @@ export function apply(ctx) {
         log(
           `official prices applied: ${applied.models.join(', ')}${applied.aliases.length ? ` (+ ${applied.aliases.join(', ')})` : ''};` +
             ` override rows ${before} -> ${after}` +
+            (applied.defaultFrom ? `; default row filled from the first published line, ${applied.defaultFrom}` : '') +
             warning,
         )
         sendJson(res, 200, { ok: true, applied, effective: pricing, calendar: describeCalendar(rules) })
@@ -524,8 +738,10 @@ export function apply(ctx) {
 
       sendJson(res, 404, { error: `no such usage-badge route: ${route}` })
     } catch (error) {
-      log(`request failed: ${error?.message ?? error}`)
-      sendJson(res, 500, { error: String(error?.message ?? error) })
+      // A caller's mistake is reported as one; only genuinely unexpected failures are 500s.
+      const status = Number(error?.statusCode) >= 400 && Number(error?.statusCode) < 500 ? Number(error.statusCode) : 500
+      if (status === 500) log(`request failed: ${error?.message ?? error}`)
+      sendJson(res, status, { error: String(error?.message ?? error) })
     }
   }
 
@@ -536,8 +752,8 @@ export function apply(ctx) {
 
   ctx.effect(() => {
     void warm()
-    return () => aggregator.saveCache()
-  }, 'usage-badge: warm the fold and persist the cache on unload')
+    return () => aggregator.close()
+  }, 'usage-badge: warm the fold and close the cache on unload')
 
   log(`mounted on ${ROUTE_PREFIX} (home: ${home}; data: ${dataDir})`)
 }

package/lib/official-pricing.js

@@ -275,11 +275,12 @@ export async function fetchOfficialPricing(options = {}) {
  * holidays — without it a weekday holiday would be billed at peak.
  *
  * Unknown keys in the existing document survive, so hand-written rows elsewhere
- * are not lost.
+ * are not lost — including a `default` row, which is only ever *filled in* when the
+ * document has none (see below).
  *
  * @param {object} current - the raw user pricing document.
  * @param {object} parsed - a {@link parseOfficialPricing} result.
- * @returns {{document:object, applied:{models:string[], aliases:string[], peakRanges:number[][]}}}
+ * @returns {{document:object, applied:{models:string[], aliases:string[], peakRanges:number[][], defaultFrom:string|null}}}
  */
 export function applyOfficialPricing(current, parsed) {
   const next = current && typeof current === 'object' ? { ...current } : {}
@@ -309,6 +310,16 @@ export function applyOfficialPricing(current, parsed) {
   }
 
   next.overrides = overrides
+  // A table with no `default` row of its own is priced by the built-in template, and those
+  // rates are nobody's choice. Fill it from the published list's **first** line instead: the
+  // page leads with its cheapest model, so a model the table does not name is guessed low
+  // rather than invented. A `default` row the user already wrote is still left alone — this
+  // only replaces the absence of one.
+  let defaultFrom = null
+  if (!next.default && parsed.models.length > 0) {
+    next.default = rowFor(parsed.models[0])
+    defaultFrom = parsed.models[0].model
+  }
   next.timeOfUse = {
     ...(next.timeOfUse ?? {}),
     enabled: true,
@@ -323,6 +334,6 @@ export function applyOfficialPricing(current, parsed) {
 
   return {
     document: next,
-    applied: { models: applied, aliases: aliasNames, peakRanges: parsed.policy.peakRangesLocal },
+    applied: { models: applied, aliases: aliasNames, peakRanges: parsed.policy.peakRangesLocal, defaultFrom },
   }
 }