dsh-usage-badge 0.1.1 → 0.1.3

package/lib/fold.js

@@ -1,5 +1,5 @@
 /**
- * dsh-usage-badge — session-log folding and its incremental cache.
+ * dsh-usage-badge — session-log folding.
  *
  * DSH persists one append-only log per session under `$DSH_HOME/sessions`. This
  * module folds every log it finds into per-day / per-(provider, model) token
@@ -10,31 +10,28 @@
  * Ported from the desktop shell's `usage-sidecar.mjs` fold, with the same
  * discovery rules (generation selection per session directory) and the same
  * size/mtime cursor that keeps a refresh proportional to what actually changed.
- * The cache file is this plugin's own (`usage-badge-cache.json`) rather than the
- * shell's `usage-cache.json`: both read the same logs, but sharing one cache file
- * would mean two writers racing over it.
+ * Where the folded history lives between runs is `cache-store.js`'s business, not
+ * this module's: a fold hands it one session at a time and asks it for the window
+ * back.
  *
  * @module dsh-usage-badge/fold
  */
 
-import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { zstdDecompressSync } from 'node:zlib'
 
-import { dayKey, initHourly, localHour } from './pricing.js'
+import { addBucket, emptyBucket, UNKNOWN } from './buckets.js'
+import { dayKey, localHour } from './pricing.js'
 
-/** Bucket key and display name used when a log records no provider/model. */
-export const UNKNOWN = 'unknown'
+export { UNKNOWN }
 
 /** Matches `session.jsonl`, `session.jsonl.zstd`, `session.v2.jsonl(.zstd)`, … */
 const SESSION_LOG_RE = /^session(?:\.v(\d+))?\.jsonl(?:\.zstd)?$/
 
 const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
 
-/** This plugin's cache format version. Unknown versions are ignored, not migrated. */
-const CACHE_VERSION = 1
-
 /** Files folded between event-loop yields, so a cold scan never stalls the host. */
 const YIELD_EVERY = 25
 
@@ -141,58 +138,6 @@ export function sessionIdFromLogPath(file) {
   return parts.length >= 2 ? parts[parts.length - 2] : file
 }
 
-function emptyBucket(provider, model) {
-  return {
-    provider,
-    model,
-    input: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    output: 0,
-    requests: 0,
-    hourly: initHourly(),
-    usageRecords: [],
-  }
-}
-
-/**
- * Add `source` into `target`.
- *
- * A missing per-request list marks a legacy aggregate row: mixing one into a
- * bucket that has a list would silently drop the aggregate's share from the
- * context-tier price, so the list is dropped to `null` for the whole bucket
- * instead, and that bucket falls back to flat pricing. Appending is looped rather
- * than spread because one day bucket can hold hundreds of thousands of requests,
- * which would overflow the argument list long before it exhausted memory.
- */
-function addBucket(target, source) {
-  target.input += Number(source?.input) || 0
-  target.cacheRead += Number(source?.cacheRead) || 0
-  target.cacheWrite += Number(source?.cacheWrite) || 0
-  target.output += Number(source?.output) || 0
-  target.requests += Number(source?.requests) || 0
-  if (!Array.isArray(target.hourly)) target.hourly = initHourly()
-  if (Array.isArray(source?.hourly)) {
-    for (let hour = 0; hour < 24; hour++) {
-      const from = source.hourly[hour]
-      const to = target.hourly[hour]
-      if (!from || !to) continue
-      to.input += Number(from.input) || 0
-      to.cacheRead += Number(from.cacheRead) || 0
-      to.cacheWrite += Number(from.cacheWrite) || 0
-      to.output += Number(from.output) || 0
-      to.requests += Number(from.requests) || 0
-    }
-  }
-  if (!Array.isArray(target.usageRecords) || !Array.isArray(source?.usageRecords)) {
-    target.usageRecords = null
-  } else {
-    for (const usage of source.usageRecords) {
-      if (usage && typeof usage === 'object') target.usageRecords.push(usage)
-    }
-  }
-}
-
 /**
  * Fold one session log into per-day, per-route buckets.
  *
@@ -299,47 +244,31 @@ export function foldSession(file, previous) {
   }
 }
 
-function serializeSession(record) {
-  const days = {}
-  for (const [date, dayObj] of record.days ?? []) {
-    days[date] = {}
-    for (const [key, bucket] of dayObj) days[date][key] = bucket
-  }
-  return {
-    path: record.path,
-    fileSize: record.fileSize,
-    fileMtimeMs: record.fileMtimeMs,
-    seq: record.seq,
-    provider: record.provider,
-    model: record.model,
-    days,
-  }
-}
-
-function deserializeSession(sessionId, record) {
-  if (!record || typeof record !== 'object' || !record.days || typeof record.days !== 'object') return null
-  const days = new Map()
-  for (const [date, sourceDay] of Object.entries(record.days)) {
-    if (!sourceDay || typeof sourceDay !== 'object') continue
-    const dayObj = new Map()
-    for (const [key, source] of Object.entries(sourceDay)) {
-      if (!source || typeof source !== 'object') continue
-      const bucket = emptyBucket(String(source.provider ?? UNKNOWN), String(source.model ?? UNKNOWN))
-      addBucket(bucket, source)
-      dayObj.set(key, bucket)
+/**
+ * Merge session records into the per-day / per-route view the snapshot reads.
+ *
+ * Exported because a caller that reads a slice of history straight from the store (the year
+ * view does) needs exactly this merge rather than a second implementation of it.
+ *
+ * @param {Iterable<object>} records - session records, each carrying a `days` map.
+ */
+export function mergeRecords(records) {
+  const merged = new Map()
+  for (const record of records) {
+    for (const [date, sourceDay] of record.days ?? []) {
+      let dayObj = merged.get(date)
+      if (!dayObj) {
+        dayObj = new Map()
+        merged.set(date, dayObj)
+      }
+      for (const [key, source] of sourceDay) {
+        const target = dayObj.get(key) ?? emptyBucket(source.provider, source.model)
+        addBucket(target, source)
+        dayObj.set(key, target)
+      }
     }
-    days.set(date, dayObj)
-  }
-  return {
-    sessionId,
-    path: String(record.path ?? ''),
-    fileSize: Number(record.fileSize) || 0,
-    fileMtimeMs: Number(record.fileMtimeMs) || 0,
-    seq: Number(record.seq) || -1,
-    provider: record.provider ?? null,
-    model: record.model ?? null,
-    days,
   }
+  return merged
 }
 
 /**
@@ -350,46 +279,37 @@ function deserializeSession(sessionId, record) {
  * per-session records on every refresh; that is deliberate, because rebuilding is
  * what makes a deleted log keep its cached contribution instead of erasing
  * history that the log no longer exists to prove.
+ *
+ * @param {{sessionsRoot:string, store:object, log?:Function}} options `store` is the cache
+ *   from `cache-store.js`: a fold writes the sessions it changed and reads a window back.
  */
-export function createAggregator({ sessionsRoot, cachePath, log = () => {} }) {
+export function createAggregator({ sessionsRoot, store, log = () => {} }) {
   const records = new Map()
   const cursors = new Map()
   let days = new Map()
-  let saveTimer = null
   let lastRefresh = null
 
   function mergeDays() {
-    const merged = new Map()
-    for (const record of records.values()) {
-      for (const [date, sourceDay] of record.days ?? []) {
-        let dayObj = merged.get(date)
-        if (!dayObj) {
-          dayObj = new Map()
-          merged.set(date, dayObj)
-        }
-        for (const [key, source] of sourceDay) {
-          const target = dayObj.get(key) ?? emptyBucket(source.provider, source.model)
-          addBucket(target, source)
-          dayObj.set(key, target)
-        }
-      }
-    }
-    days = merged
+    days = mergeRecords(records.values())
   }
 
+  /**
+   * Take back the stored history, oldest row first dropped into the window the panel can
+   * show. Sessions whose days all fall outside the window still come back — with their
+   * cursor, so their logs are never folded again — just without the buckets that no view
+   * asks for. Their rows stay in the store.
+   */
   function loadCache() {
-    let raw
+    let loaded
     try {
-      raw = JSON.parse(readFileSync(cachePath, 'utf8'))
-    } catch {
+      loaded = store.load()
+    } catch (error) {
+      log(`cache load failed: ${error?.message ?? error}`)
       return false
     }
-    if (!raw || raw.version !== CACHE_VERSION || !raw.sessions || typeof raw.sessions !== 'object') return false
-    for (const [sessionId, source] of Object.entries(raw.sessions)) {
-      const record = deserializeSession(sessionId, source)
-      if (!record) continue
-      records.set(sessionId, record)
-      cursors.set(sessionId, {
+    for (const record of loaded ?? []) {
+      records.set(record.sessionId, record)
+      cursors.set(record.sessionId, {
         seq: record.seq,
         provider: record.provider,
         model: record.model,
@@ -399,64 +319,36 @@ export function createAggregator({ sessionsRoot, cachePath, log = () => {} }) {
       })
     }
     mergeDays()
-    log(`cache loaded: ${records.size} session(s)`)
-    return true
+    log(`cache loaded: ${records.size} session(s) from ${store.kind}`)
+    return records.size > 0
   }
 
-  function saveCache() {
-    const sessions = {}
-    for (const [sessionId, record] of records) sessions[sessionId] = serializeSession(record)
-    // The temporary name carries pid, time and entropy so a restarted host can
-    // never collide with a stale temp file another process still holds open.
-    const temp = `${cachePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
-    try {
-      mkdirSync(join(cachePath, '..'), { recursive: true })
-      writeFileSync(temp, JSON.stringify({ version: CACHE_VERSION, sessions }))
-      try {
-        renameSync(temp, cachePath)
-      } catch {
-        // Windows cannot rename over an existing file; the complete temp file is
-        // already on disk, so removing the old one first is safe here.
-        try {
-          unlinkSync(cachePath)
-        } catch {
-          // absent is fine
-        }
-        renameSync(temp, cachePath)
-      }
-    } catch (error) {
-      try {
-        unlinkSync(temp)
-      } catch {
-        // best-effort cleanup only
-      }
-      log(`cache save failed: ${error?.message ?? error}`)
-    }
+  /** Write through anything the store is holding back; called on warm-up and on unload. */
+  function flush() {
+    store.flush()
   }
 
-  function scheduleCacheSave() {
-    if (saveTimer) return
-    saveTimer = setTimeout(() => {
-      saveTimer = null
-      saveCache()
-    }, 2000)
-    saveTimer.unref?.()
+  /** Flush and release the store's handle. */
+  function close() {
+    store.close()
   }
 
   /**
    * Fold every changed log.
    *
+   * A changed session is written back immediately, one session at a time: that is the whole
+   * reason the store is not a single document, and it means there is no save timer to lose
+   * work in and no moment where a burst of edits has to be batched.
+   *
    * @returns {Promise<{files:number, folded:number, ms:number}>} what this pass did.
    */
   async function refresh() {
     const started = Date.now()
     const files = listLogFiles(sessionsRoot)
-    const seen = new Set()
     let folded = 0
     let sinceYield = 0
     for (const file of files) {
       const sessionId = sessionIdFromLogPath(file)
-      seen.add(sessionId)
       const cursor = cursors.get(sessionId)
       let stat
       try {
@@ -467,8 +359,14 @@ export function createAggregator({ sessionsRoot, cachePath, log = () => {} }) {
       if (cursor && cursor.fileSize === stat.size && cursor.fileMtimeMs === (stat.mtimeMs || 0) && cursor.path === file) {
         continue
       }
-      const record = foldSession(file, records.get(sessionId))
-      if (record) {
+      const previous = records.get(sessionId)
+      const record = foldSession(file, previous)
+      // `foldSession` hands the previous record straight back when it could not read the log, and
+      // that record is already in the store — writing it again would replace the session's rows
+      // with only the days this process happens to hold (the loading window), deleting the older
+      // ones on the way past. Leaving the cursor untouched also means the next refresh retries the
+      // fold, which is what a transient read failure wants.
+      if (record && record !== previous) {
         records.set(sessionId, record)
         cursors.set(sessionId, {
           seq: record.seq,
@@ -479,18 +377,23 @@ export function createAggregator({ sessionsRoot, cachePath, log = () => {} }) {
           path: record.path,
         })
         folded++
+        // Written back one session at a time, right here: a save costs the changed session's
+        // days, not the whole history, so there is nothing to batch and no timer to lose it in.
+        try {
+          store.put(record)
+        } catch (error) {
+          log(`cache write failed for ${sessionId}: ${error?.message ?? error}`)
+        }
       }
       if (++sinceYield >= YIELD_EVERY) {
         sinceYield = 0
         await new Promise((r) => setImmediate(r))
       }
     }
-    // A session whose log disappeared keeps its record (and therefore its
-    // history) but stops being refreshed.
-    if (folded > 0) {
-      mergeDays()
-      scheduleCacheSave()
-    }
+    // A session whose log disappeared keeps its record (and therefore its history) but stops
+    // being refreshed — and, because nothing writes it again, that history stays in the store
+    // for good rather than being erased by the log's absence.
+    if (folded > 0) mergeDays()
     lastRefresh = { files: files.length, folded, ms: Date.now() - started, at: Date.now() }
     return lastRefresh
   }
@@ -498,7 +401,8 @@ export function createAggregator({ sessionsRoot, cachePath, log = () => {} }) {
   return {
     loadCache,
     refresh,
-    saveCache,
+    flush,
+    close,
     get days() {
       return days
     },

package/lib/holidays.js

@@ -6,10 +6,11 @@
  * > 空闲时段价格为高峰时段价格的一半。北京时间周一至周五（**不含中国法定节假日**）
  * > 9:00 - 12:00、14:00 - 18:00 为高峰时段；其余时段，包括周末及**中国法定节假日全天均为空闲时段**。
  *
- * So a weekday holiday must be billed entirely off-peak, and a 调休 weekend that
- * the State Council turns into a working day must be billed as a working day
- * again. Both directions need the real calendar, which is why this module ships
- * one rather than inferring from the weekday alone.
+ * So a weekday holiday must be billed entirely off-peak, and — the part that is easy to
+ * get backwards — a 调休 weekend the State Council turns into a working day stays a
+ * *weekend*, because the policy names 周末 as off-peak in full. This module therefore
+ * only ever *adds* off-peak days; it never turns one into a working day. (The 调休
+ * workdays are still recorded in `holidays-cn.json`, for audit.)
  *
  * The bundled table is per-year data transcribed from the State Council notices
  * (see `holidays-cn.json`, which records document numbers and URLs). A year the