@bakery-framework/plugin-analytics 2.0.0-alpha.9 → 2.0.0-rc.2

package/README.md

@@ -20,23 +20,53 @@ export default defineConfig({
 })
 ```
 
-Rolling histories are exported for reading directly — `history1m`, `history1h`,
-`history1d`, `history7d`, `history30d` — alongside `pageHitsMap`,
-`pageHitsLog` and the `recordRouteHit` / `recordDbHit` / `recordErrorPageHit`
-counters.
+Rolling histories are exported for reading directly (`history1m`, `history1h`,
+`history1d`, `history7d`, `history30d`) alongside `pageHitsMap`,
+`pageHitsLog` and the `recordRouteHit` / `recordErrorPageHit` counters.
 
-The stats endpoint is guarded by `DASHPASS`. The safe state is the default:
-with `DASHPASS` unset the guard **denies everyone**, so the endpoint is closed
-until you deliberately open it. Setting `DASHPASS` is what enables access, and a
-caller still needs the matching session flag.
+## Authorization
+
+The stats endpoint, the reset endpoint and the live socket are closed unless
+you open them, and there are two ways to do it:
+
+```ts
+import { defineConfig } from '@bakery-framework/core'
+import analyticsPlugin from '@bakery-framework/plugin-analytics'
+
+export default defineConfig({
+  plugins: [
+    analyticsPlugin({
+      // A shared secret, sent as an `x-analytics-key` header or, for the
+      // socket, an `analytics-key` query parameter. A browser cannot set a
+      // header on a WebSocket handshake.
+      credential: process.env.ANALYTICS_KEY,
+
+      // Or your own predicate, which is what the dashboard plugin hands over
+      // when both are registered.
+      authorize: (req: Request) => req.headers.get('x-role') === 'admin',
+    }),
+  ],
+})
+```
+
+With neither configured the guard allows loopback in development and denies
+everything in production, so the closed state is the default rather than
+something to remember.
+
+**`DASHPASS` is not read and has not been since `bfe410c`.** Earlier versions
+of this file said the endpoint was guarded by it. It never granted access (it changed a status code), and nothing in the framework consults it now.
+Delete it from any environment that still carries it: a variable that looks
+like a credential and controls nothing is the kind of leftover an operator
+reasons from. See
+[Environment](https://github.com/obillekyle/bakery/blob/main/docs/configuration/environment.md).
 
 ## License
 
-MIT with the Commons Clause v1.0 — see [LICENSE](./LICENSE).
+MIT with the Commons Clause v1.0. See [LICENSE](./LICENSE).
 
-**Not an OSI-approved licence.** The Commons Clause removes the right to *sell*
-the software — meaning to charge for a product or service whose value derives
+**Not an OSI-approved license.** The Commons Clause removes the right to *sell*
+the software: meaning to charge for a product or service whose value derives
 substantially from it, hosting and support included. Everything else the MIT
-licence grants is unchanged: use it, modify it, ship it inside your own product.
-If your organisation only permits OSI-approved dependencies, this will not pass
+license grants is unchanged: use it, modify it, ship it inside your own product.
+If your organization only permits OSI-approved dependencies, this will not pass
 that check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-analytics",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0-rc.2",
   "description": "Bakery analytics plugin.",
   "keywords": [
     "bakery",
@@ -27,6 +27,7 @@
     ".": "./src/index.ts",
     "./setup": "./src/setup.ts",
     "./stats": "./src/endpoints/stats.ts",
+    "./timescale": "./src/timescale.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -35,9 +36,9 @@
     "!src/tests"
   ],
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.9"
+    "@bakery-framework/core": "^2.0.0-rc.2"
   },
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   }
 }

package/src/core.ts

@@ -1,3 +1,4 @@
+import { TIMESCALES, timescaleFacts } from './timescale'
 import type { AnalyticsSnapshot } from './types'
 
 export const RETENTION_MS = 30 * 24 * 3600 * 1000
@@ -14,7 +15,7 @@ export const pageHitsLog: { timestamp: number; path: string }[] = []
 export const pageHitsMap = new Map<string, number>()
 
 /**
- * Moved to `@server/logger` — LiveReloadHandler (core) owns membership, so
+ * Moved to `@server/logger`: LiveReloadHandler (core) owns membership, so
  * the registry cannot live in a plugin. Re-exported because this plugin's
  * public surface and internals read it (the `activeLoggers` gauge).
  */
@@ -29,7 +30,6 @@ type TempAccumulator = {
   apiHits: number
   pageHits: number
   uniqueRequests: number
-  dbHits: number
   errorPageHits: number
   ping: number
 }
@@ -44,7 +44,6 @@ function createAccumulator(): TempAccumulator {
     apiHits: 0,
     pageHits: 0,
     uniqueRequests: 0,
-    dbHits: 0,
     errorPageHits: 0,
     ping: 0,
   }
@@ -59,7 +58,6 @@ let routeHitsThisSecond = 0
 let apiHitsThisSecond = 0
 let pageHitsThisSecond = 0
 const uniqueRequestsThisSecond = new Set<string>()
-let dbHitsThisSecond = 0
 let errorPageHitsThisSecond = 0
 
 /**
@@ -67,7 +65,7 @@ let errorPageHitsThisSecond = 0
  * of the per-path tally.
  *
  * `pageHitsMap` is a count per path, so an entry leaving the log has to
- * decrement it — and a count that reaches zero is deleted rather than left at
+ * decrement it, and a count that reaches zero is deleted rather than left at
  * 0, which is what keeps the map from growing one dead path at a time. Both
  * pruning rules below (the retention window and the hard cap) evict from the
  * front, so both need exactly this.
@@ -104,9 +102,17 @@ export function ensurePageHitsLogPruner() {
     try {
       prunePageHitsLog(Date.now())
     } catch (_e) {
-      // swallow errors; pruner is best-effort
+      // Best-effort: a pruning failure must not take down the telemetry that
+      // is only observing the server.
     }
   }, 60_000)
+  // Started by the *first page hit*, so any process that serves one ordinary
+  // request holds the event loop open for ever without it - a script that
+  // imports the plugin and finishes its work never exits. Same class as the
+  // three core timers unref'd for A15; this one lives in a plugin and was
+  // outside what that pass looked at. Optional-called because a test may
+  // install a fake timer that has no `unref`.
+  _pageHitsLogPruneTimer.unref?.()
 }
 
 export function stopPageHitsLogPruner() {
@@ -125,7 +131,6 @@ function accumulate(temp: TempAccumulator, s: AnalyticsSnapshot) {
   temp.apiHits += s.apiHits || 0
   temp.pageHits += s.pageHits || 0
   temp.uniqueRequests += s.uniqueRequests || 0
-  temp.dbHits += s.dbHits || 0
   temp.errorPageHits += s.errorPageHits || 0
   temp.ping += s.ping || 0
 }
@@ -144,7 +149,6 @@ function finalizeAggregation(
     apiHits: temp.apiHits,
     pageHits: temp.pageHits,
     uniqueRequests: temp.uniqueRequests,
-    dbHits: temp.dbHits,
     errorPageHits: temp.errorPageHits,
     ping: Math.round(temp.ping / count),
   }
@@ -165,7 +169,6 @@ function loadAccumulator(target: TempAccumulator, loaded: any) {
       target.apiHits += s.apiHits || 0
       target.pageHits += s.pageHits || 0
       target.uniqueRequests += s.uniqueRequests || 0
-      target.dbHits += s.dbHits || 0
       target.errorPageHits += s.errorPageHits || 0
       target.ping += s.ping || 0
     }
@@ -182,7 +185,32 @@ export function isAssetPath(path: string): boolean {
   )
 }
 
+/**
+ * The analytics loop's own request does not count as traffic.
+ *
+ * `runAnalyticsTick` fetches `/_analytics/ping` through the real server once a
+ * second so it can time a round trip, and that request reaches `onRoute` like
+ * any other. The result was a permanent floor of one route hit and one unique
+ * request per second on an idle server - every chart reading 1 instead of 0,
+ * and a day's `uniqueRequests` carrying 86,400 of the loop's own pings.
+ *
+ * Exact matches, not a prefix, for the same reason `isAnalyticsPath` in
+ * `setup.ts` uses exact matches: `/_analytics/pingback` would belong to the
+ * application. The two `/api/_analytics/*` endpoints are the console asking
+ * for its own data, which is equally not application traffic.
+ */
+const SELF_PATHS = new Set([
+  '/_analytics/ping',
+  '/api/_analytics/stats',
+  '/api/_analytics/reset',
+])
+
+export function isSelfPath(path: string): boolean {
+  return SELF_PATHS.has(path)
+}
+
 export function recordRouteHit(method: string, path: string, search = '') {
+  if (SELF_PATHS.has(path)) return
   routeHitsThisSecond += 1
   if (path.startsWith('/api/')) {
     apiHitsThisSecond += 1
@@ -195,10 +223,6 @@ export function recordRouteHit(method: string, path: string, search = '') {
   uniqueRequestsThisSecond.add(`${method} ${path}${search}`)
 }
 
-export function recordDbHit() {
-  dbHitsThisSecond += 1
-}
-
 export function recordErrorPageHit() {
   errorPageHitsThisSecond += 1
 }
@@ -216,31 +240,34 @@ export function pushAnalyticsSnapshot(snapshot: {
     apiHits: apiHitsThisSecond,
     pageHits: pageHitsThisSecond,
     uniqueRequests: uniqueRequestsThisSecond.size,
-    dbHits: dbHitsThisSecond,
     errorPageHits: errorPageHitsThisSecond,
   }
 
   history1m.push(fullSnapshot)
   if (history1m.length > 60) history1m.shift()
 
+  // The bucket sizes were four literals here (60, 1800, 21600, 86400), and
+  // they are the same numbers the point limits and the chart intervals were
+  // built from in three other places. `samples` derives from the window and
+  // the point count, so a timescale that changes shape changes all of them.
   accumulate(temp1h, fullSnapshot)
   accumulate(temp1d, fullSnapshot)
   accumulate(temp7d, fullSnapshot)
   accumulate(temp30d, fullSnapshot)
 
-  if (temp1h.count >= 60) {
+  if (temp1h.count >= TIMESCALES['1h'].samples) {
     history1h.push(finalizeAggregation(temp1h, fullSnapshot.timestamp))
     if (history1h.length > 60) history1h.shift()
   }
-  if (temp1d.count >= 1800) {
+  if (temp1d.count >= TIMESCALES['1d'].samples) {
     history1d.push(finalizeAggregation(temp1d, fullSnapshot.timestamp))
     if (history1d.length > 48) history1d.shift()
   }
-  if (temp7d.count >= 21600) {
+  if (temp7d.count >= TIMESCALES['7d'].samples) {
     history7d.push(finalizeAggregation(temp7d, fullSnapshot.timestamp))
     if (history7d.length > 28) history7d.shift()
   }
-  if (temp30d.count >= 86400) {
+  if (temp30d.count >= TIMESCALES['30d'].samples) {
     history30d.push(finalizeAggregation(temp30d, fullSnapshot.timestamp))
     if (history30d.length > 30) history30d.shift()
   }
@@ -249,7 +276,6 @@ export function pushAnalyticsSnapshot(snapshot: {
   apiHitsThisSecond = 0
   pageHitsThisSecond = 0
   uniqueRequestsThisSecond.clear()
-  dbHitsThisSecond = 0
   errorPageHitsThisSecond = 0
 }
 
@@ -260,26 +286,15 @@ export function getLatestAnalyticsSnapshot() {
       apiHits: 0,
       pageHits: 0,
       uniqueRequests: 0,
-      dbHits: 0,
       errorPageHits: 0,
       ping: 0,
     }
   )
 }
 
+/** One of the five copies of the timescale table; see `timescale.ts`. */
 export function getHistoryLimitForTimescale(timescale: string): number {
-  switch (timescale) {
-    case '30d':
-      return 30
-    case '7d':
-      return 28
-    case '1d':
-      return 48
-    case '1h':
-      return 60
-    default:
-      return 60
-  }
+  return timescaleFacts(timescale).points
 }
 
 export function getHistoryForTimescale(timescale: string): AnalyticsSnapshot[] {
@@ -354,7 +369,6 @@ export function getFilledHistoryForTimescale(
           apiHits: null,
           pageHits: null,
           uniqueRequests: null,
-          dbHits: null,
           errorPageHits: null,
           ping: null,
         })
@@ -368,6 +382,34 @@ export function getFilledHistoryForTimescale(
   return filled
 }
 
+/**
+ * The write half of `loadTemps`, which had no write half.
+ *
+ * `setup.ts` checked `data.temp1h` on boot and `loadTemps` knew how to restore
+ * all four buckets, but nothing ever put them in the persisted snapshot - so
+ * the check was always false and every restart began aggregating from zero. A
+ * bucket only finalizes at its full count (60 samples for 1h, 1800 for 1d), so
+ * the visible symptom was the 1h chart staying empty for up to an hour after
+ * every boot, and the longer windows correspondingly longer.
+ *
+ * Plain objects rather than the accumulators themselves: this is serialized to
+ * JSON in the `core` row, and handing out the live objects would let a caller
+ * mutate the running aggregation.
+ */
+export function snapshotTemps(): {
+  temp1h: TempAccumulator
+  temp1d: TempAccumulator
+  temp7d: TempAccumulator
+  temp30d: TempAccumulator
+} {
+  return {
+    temp1h: { ...temp1h },
+    temp1d: { ...temp1d },
+    temp7d: { ...temp7d },
+    temp30d: { ...temp30d },
+  }
+}
+
 export function loadTemps(loaded: any) {
   if (!loaded) return
   if (loaded.temp1h) loadAccumulator(temp1h, loaded.temp1h)

package/src/endpoints/stats.ts

@@ -66,7 +66,6 @@ export function computeStats(
     apiHits: latestHistory.apiHits || 0,
     pageHits: latestHistory.pageHits || 0,
     uniqueRequests: latestHistory.uniqueRequests,
-    dbHits: latestHistory.dbHits,
     errorPageHits: latestHistory.errorPageHits,
     ping: latestHistory.ping,
     topPages: topPagesFiltered,
@@ -93,7 +92,7 @@ export type { AuthorizeFn } from '@bakery-framework/core/utils/http'
 
 /**
  * Analytics owns the auth for its endpoints, and the dashboard delegates to
- * it (`isAnalyticsAuthorized`) — the analytics key *is* the dashboard key.
+ * it (`isAnalyticsAuthorized`): the analytics key *is* the dashboard key.
  * Two doors, both fail closed and both off until configured:
  *
  *   - the shared `credential` (`x-analytics-key`, Bearer, or `?analytics-key=`)
@@ -101,7 +100,7 @@ export type { AuthorizeFn } from '@bakery-framework/core/utils/http'
  *
  * Neither configured means analytics is closed to everyone, which is the safe
  * default. Note `isAnalyticsAuthorized` is sync-fast on the credential path
- * and only awaits when a predicate is present — the websocket `canHandle`
+ * and only awaits when a predicate is present: the websocket `canHandle`
  * needs a boolean, so a predicate makes the check async there too.
  */
 let credential: string | undefined
@@ -127,9 +126,9 @@ export async function isAnalyticsAuthorized(req: Request): Promise<boolean> {
 }
 
 /**
- * The rejection envelope, or `null` when the caller may proceed — a guard
+ * The rejection envelope, or `null` when the caller may proceed: a guard
  * returns the rejection rather than throwing (convention 2). It is a
- * `JsonResponseData` and never a `Response`; the router serialises it through
+ * `JsonResponseData` and never a `Response`; the router serializes it through
  * the one JSON envelope in `processResponse`. The explicit `<undefined>` says
  * the envelope carries no `data`, which is what makes it assignable into every
  * caller's own payload type.
@@ -138,7 +137,7 @@ async function checkAnalyticsAuth(
   req: Request,
 ): Promise<JsonResponseData<undefined> | null> {
   if (await isAnalyticsAuthorized(req)) return null
-  // Armed-but-unauthorised is a 401; nothing configured is a 404 that does
+  // Armed-but-unauthorized is a 401; nothing configured is a 404 that does
   // not advertise the endpoint at all.
   return credential || authorizeFn
     ? response.json.error<undefined>(401, 'Unauthorized')

package/src/endpoints/websocket.ts

@@ -7,7 +7,7 @@ export const connectedAnalyticsClients = new Set<any>()
 export class AnalyticsWSHandler extends WebSocketHandler {
   // The upgrade is dispatched before any plugin hook runs, so the auth check
   // has to live here. Without it this socket served the same payload the HTTP
-  // stats endpoint guards — and pushed it live every second.
+  // stats endpoint guards, and pushed it live every second.
   static async canHandle(path: string, req?: Request): Promise<boolean> {
     if (path !== '/_analytics_ws') return false
     // Async because the auth may run an `authorize` predicate; the registry

package/src/index.ts

@@ -11,7 +11,6 @@ export {
   history30d,
   pageHitsLog,
   pageHitsMap,
-  recordDbHit,
   recordErrorPageHit,
   recordRouteHit,
 } from './core'

package/src/log.ts

@@ -5,7 +5,7 @@ import { Logger, messageLogger } from '@bakery-framework/core/logger'
  *
  * Declared here rather than added to core's `pluginLog`, on the same reasoning
  * the ORM uses for `sync/engine.ts` and `backup.ts`: a message belongs to the
- * package that emits it. `ANALYTICS_STORE_ERR` still lives in core's table —
+ * package that emits it. `ANALYTICS_STORE_ERR` still lives in core's table:
  * moving it is a change to `@bakery-framework/core`, not to this plugin.
  */
 const analyticsMsgs = {

package/src/loop.ts

@@ -6,7 +6,7 @@ import * as core from './core'
 import { computeStats } from './endpoints/stats'
 import { connectedAnalyticsClients } from './endpoints/websocket'
 import { analyticsLog } from './log'
-import { saveAnalyticsData } from './storage-sqlite'
+import { flushPageHits, saveAnalyticsData } from './storage-sqlite'
 
 const SAVE_THROTTLE_MS = 60000
 
@@ -20,7 +20,7 @@ let lastSaveTime = 0
  *
  * The timestamp is stamped when the write *settles*, not when it is
  * dispatched. Stamping first meant a flush that took longer than the window
- * let the next one start on top of it — two writers over the same tables,
+ * let the next one start on top of it: two writers over the same tables,
  * from a function whose whole job is to be harmless.
  *
  * `finally` rather than the success path: a failed flush that reset nothing
@@ -53,18 +53,68 @@ async function runAnalyticsTick(server: any) {
     ping: pingVal,
   })
 
+  // Hits go to disk every tick; the prune and the history snapshot stay on the
+  // throttle. The two were one call, and the insert was blamed for a stall the
+  // prune was doing: a minute of hits at 1,000 req/s inserts in 89-115 ms
+  // while the prune beside it cost 376 ms. Per tick the insert is 1-4 ms, so
+  // the large batch leaves the request thread and the expensive half runs a
+  // sixtieth as often.
+  //
   // Awaited, not floated: a rejected flush used to escape this tick entirely
   // and land nowhere.
+  const [flushErr] = await Try.catch(flushPageHits())
+  if (flushErr) analyticsLog.SAVE_ERR({ error: errorMsg(flushErr) })
+
   await throttleSave()
 
+  broadcastStats()
+}
+
+/**
+ * One `computeStats` per distinct subscription, not per client.
+ *
+ * Every connected console got its own call each second, and two consoles
+ * watching the same window asked the same question twice. They rarely differ:
+ * the timescale and the pages filter both default to the same values and a
+ * console only changes them when somebody clicks. Grouping by those two keys
+ * makes the common case one call however many consoles are open.
+ *
+ * Worth the grouping rather than a single global call, because the answer
+ * genuinely depends on both: a client watching `1h` must not be sent a `1m`
+ * payload. Measured at 1.10 ms a call with a 2,000-path tally, so this is a
+ * millisecond a second at five consoles rather than five - real, and smaller
+ * than the 10 ms a call the backlog recorded.
+ *
+ * The serialized frame is reused too. `JSON.stringify` of a stats payload is
+ * not free, and it was run once per client over an identical object.
+ *
+ * `compute` is a test seam (convention 9): counting the calls is the only
+ * way to assert the grouping, and two equal strings are indistinguishable
+ * from one computed twice.
+ */
+export function broadcastStats(compute = computeStats) {
+  if (connectedAnalyticsClients.size === 0) return
+
+  const byWindow = new Map<string, string>()
   for (const ws of connectedAnalyticsClients) {
     const opts = ws.data?.data
-    if (opts) {
-      const stats = computeStats(opts.timescale, true, opts.pagesFilter)
-      ws.send(
-        JSON.stringify({ status: 200, excludeHistory: true, data: stats }),
-      )
+    if (!opts) continue
+
+    const timescale = opts.timescale
+    const pagesFilter = opts.pagesFilter
+    // Separated by a delimiter neither value can contain. A timescale is one
+    // of `1m|1h|1d|7d|30d` and a filter the same shape, so joining them with a
+    // space would in fact be safe today; a form that cannot collide costs
+    // nothing and does not depend on that staying true.
+    const key = JSON.stringify([timescale, pagesFilter])
+
+    let frame = byWindow.get(key)
+    if (frame === undefined) {
+      const stats = compute(timescale, true, pagesFilter)
+      frame = JSON.stringify({ status: 200, excludeHistory: true, data: stats })
+      byWindow.set(key, frame)
     }
+    ws.send(frame)
   }
 }
 
@@ -77,8 +127,8 @@ let loopRunning = false
  * Sample the server once every `intervalMs`.
  *
  * A self-rescheduling `setTimeout`, not `setInterval`. The tick body makes a
- * full round trip through the server — `MiddlewareHandler`, so `onRequest` and
- * every app middleware — plus a `Session.count`, which is a SQLite `COUNT(*)`.
+ * full round trip through the server (`MiddlewareHandler`, so `onRequest` and
+ * every app middleware) plus a `Session.count`, which is a SQLite `COUNT(*)`.
  * `setInterval` does not wait for an async body, so once p50 exceeded one
  * second the ticks overlapped and the in-flight pings accumulated, each adding
  * load that lengthened the next: positive feedback, from the telemetry.
@@ -86,7 +136,7 @@ let loopRunning = false
  * The overlap was not only a load problem. `pushAnalyticsSnapshot` zeroes the
  * per-second counters at the end of a tick, so a re-entrant call double-advanced
  * the hourly accumulator and emptied the counters belonging to the tick still
- * in flight — drifting the 60-snapshot aggregation boundary off a real hour.
+ * in flight: drifting the 60-snapshot aggregation boundary off a real hour.
  * Re-arming in `finally` makes the overlap structurally impossible rather than
  * merely unlikely, so neither failure can come back.
  *

package/src/setup.ts

@@ -31,7 +31,6 @@ export const history7d = core.history7d
 export const history30d = core.history30d
 
 export const recordRouteHit = core.recordRouteHit
-export const recordDbHit = core.recordDbHit
 export const recordErrorPageHit = core.recordErrorPageHit
 export const pushAnalyticsSnapshot = core.pushAnalyticsSnapshot
 export const getLatestAnalyticsSnapshot = core.getLatestAnalyticsSnapshot
@@ -124,7 +123,7 @@ export { startAnalyticsLoop }
  * plugin keeps the same rule in `isDashboardPath`, over namespaces rather than
  * exact paths.
  *
- * Exact matches, not prefixes — `/_analytics/pingback` belongs to the app.
+ * Exact matches, not prefixes: `/_analytics/pingback` belongs to the app.
  */
 const ANALYTICS_PATHS = new Set([
   '/_analytics/ping',
@@ -157,7 +156,7 @@ class AnalyticsHandler extends Handler {
 
 /**
  * Auth stays inside each endpoint (`handleStatsRequest` / `handleResetRequest`
- * fail closed on their own) — this table only replaces the path/method chain.
+ * fail closed on their own): this table only replaces the path/method chain.
  *
  * `satisfies` rather than an annotation: it checks the table against
  * `PluginRouteTable` while keeping the literal type, so `routeTable` can carry
@@ -171,7 +170,7 @@ const analyticsRoutes = routeTable({
 
 /**
  * `/_analytics/ping` is a plain `Response`; the two `/api/` endpoints return
- * the JSON envelope, which the router serialises in `processResponse`. Spelling
+ * the JSON envelope, which the router serializes in `processResponse`. Spelling
  * the union out here means adding a route that returns something else is a
  * compile error rather than a silent widening.
  */
@@ -195,7 +194,7 @@ export interface AnalyticsAuthOptions {
 /**
  * The auth half of `setupAnalytics`, split out from the once-only half.
  *
- * Auth is (re)applied on every call — last config wins — so the dashboard
+ * Auth is (re)applied on every call (last config wins), so the dashboard
  * bringing analytics up with the shared key overrides a bare
  * `analyticsPlugin()`, whichever order they registered in.
  *
@@ -209,7 +208,7 @@ export interface AnalyticsAuthOptions {
  * shutting the console it was registered to open. A call that carries a value
  * wins; a bare call is a no-op against auth rather than a silent disarm.
  * Turning a door off means not registering the plugin, or passing the empty
- * string — never omitting the option.
+ * string, never omitting the option.
  *
  * It is separate, and exported, because `setupAnalytics` cannot be called from
  * a test: it also registers two handlers, installs a shutdown hook and kicks

package/src/storage-sqlite.ts

@@ -12,6 +12,7 @@ import {
   pageHitsLog,
   pageHitsMap,
   RETENTION_MS,
+  snapshotTemps,
 } from './core'
 import { analyticsLog } from './log'
 import { timescaleToMs } from './timescale'
@@ -82,7 +83,7 @@ function resetStatements() {
 /**
  * Test seam (convention 9) for the storage handle.
  *
- * The real handle is `cacheDb`, which the whole process shares — closing it to
+ * The real handle is `cacheDb`, which the whole process shares: closing it to
  * exercise a write failure would take every test file loaded afterwards with
  * it. The prepared statements are reset alongside, since they belong to the
  * connection they were compiled against.
@@ -92,7 +93,7 @@ export function __setTestDb(instance: Database | null) {
   resetStatements()
   // Same schema the real handle gets. A test that injects an already-closed
   // handle to drive the failure path cannot have one, which is the point of
-  // injecting it — hence `Try` rather than a throw.
+  // injecting it: hence `Try` rather than a throw.
   if (instance) Try(() => ensureSchema(instance))
 }
 
@@ -106,6 +107,57 @@ export default {
   getDb,
 }
 
+/**
+ * Write the page hits recorded since the last call, and nothing else.
+ *
+ * Split out of `saveAnalyticsData` so the two halves can run on different
+ * schedules, because they cost very different amounts. Inserting a second of
+ * hits is 1-4 ms; the full save, with its prune and its `core` upsert, is not.
+ *
+ * Measured across a minute of traffic at 1,000 req/s: inserting 60,000 rows in
+ * transactions of 1,000 costs 89-115 ms, against 376 ms for the prune the
+ * other half runs. So the insert was never what made the flush expensive - the
+ * per-minute batch was blamed for a stall the prune was doing - and moving the
+ * insert to the tick costs almost nothing while removing the one large batch
+ * from the request thread entirely.
+ *
+ * Returns the number of rows written so a caller can tell "nothing to do" from
+ * "could not write", which the void-returning original could not.
+ *
+ * **Throws rather than reporting.** Both callers already have a catch that
+ * names the failure, and a catch here as well produced two log lines for one
+ * closed database - which is worse than one, because the second looks like a
+ * second failure. The rule that telemetry never takes down what it measures
+ * is kept at the call sites, where it belongs.
+ */
+export async function flushPageHits(): Promise<number> {
+  {
+    await initSqliteStorage()
+    const d = getDb()
+    if (!d) return 0
+    if (pageHitsLog.length === 0) return 0
+
+    if (!stmtInsertPageHit)
+      stmtInsertPageHit = d.prepare(
+        'INSERT INTO page_hits(timestamp,path) VALUES(?,?)',
+      )
+
+    const newHits = pageHitsLog.filter(p => p.timestamp > lastSavedPageHitTs)
+    if (newHits.length === 0) return 0
+
+    const tx = d.transaction((rows: [number, string][]) => {
+      for (const r of rows) stmtInsertPageHit!.run(r[0], r[1])
+    })
+    const rows: [number, string][] = newHits.map(p => [p.timestamp, p.path])
+    const BATCH = 1000
+    for (let i = 0; i < rows.length; i += BATCH) {
+      tx(rows.slice(i, i + BATCH))
+    }
+    lastSavedPageHitTs = newHits[newHits.length - 1].timestamp
+    return rows.length
+  }
+}
+
 export async function saveAnalyticsData(_cacheBase: string) {
   try {
     await initSqliteStorage()
@@ -129,36 +181,53 @@ export async function saveAnalyticsData(_cacheBase: string) {
     const pruneBefore = now - RETENTION_MS
     try {
       stmtDeletePageHits.run(pruneBefore)
-      // Age alone doesn't bound this: a crawler hitting distinct URLs can add
-      // millions of rows well inside the retention window. Cap the row count too.
-      d.run(
-        `DELETE FROM page_hits WHERE rowid NOT IN (
-           SELECT rowid FROM page_hits ORDER BY timestamp DESC LIMIT ${MAX_PAGE_HIT_ROWS}
-         )`,
-      )
+
+      // **Ask before deleting.** Age alone does not bound this table - a
+      // crawler hitting distinct URLs can add millions of rows well inside the
+      // retention window - so the row count is capped too. But the capping
+      // statement is expensive in a way its shape hides: `NOT IN (SELECT rowid
+      // ... ORDER BY timestamp DESC LIMIT n)` sorts and materializes n rowids
+      // before it can decide that nothing needs deleting, and it ran on every
+      // single flush.
+      //
+      // A `count(*)` is answered from the index. Measured on a 150k-row table,
+      // three rounds each against a CPU-bound control that stayed flat:
+      //
+      //     prune as shipped          376 ms
+      //     prune with this guard       5 ms
+      //
+      // Over the cap the delete still runs and still costs what it costs
+      // (~360 ms at 250k rows), which is correct: that is the case where work
+      // is genuinely required, and it is the rare one.
+      const counted = d
+        .query<{ n: number }, []>('SELECT count(*) AS n FROM page_hits')
+        .get()
+      if ((counted?.n ?? 0) > MAX_PAGE_HIT_ROWS) {
+        d.run(
+          `DELETE FROM page_hits WHERE rowid NOT IN (
+             SELECT rowid FROM page_hits ORDER BY timestamp DESC LIMIT ${MAX_PAGE_HIT_ROWS}
+           )`,
+        )
+      }
     } catch {
       // Pruning is best-effort. Failing to trim old rows must not abandon the
       // inserts below, which are the point of this call.
     }
 
-    if (pageHitsLog.length > 0) {
-      const tx = d.transaction((rows: [number, string][]) => {
-        for (const r of rows) stmtInsertPageHit!.run(r[0], r[1])
-      })
-
-      const newHits = pageHitsLog.filter(p => p.timestamp > lastSavedPageHitTs)
-
-      if (newHits.length > 0) {
-        const rows: [number, string][] = newHits.map(p => [p.timestamp, p.path])
-        const BATCH = 1000
-        for (let i = 0; i < rows.length; i += BATCH) {
-          tx(rows.slice(i, i + BATCH))
-        }
-
-        lastSavedPageHitTs = newHits[newHits.length - 1].timestamp
-      }
-    }
+    // One writer for page hits, and it is `flushPageHits`. This call used to
+    // hold a second copy of the same insert loop; with the loop flushing every
+    // tick that copy would find nothing to do on almost every call, which is
+    // the worst kind of dead code - it still looks like the thing doing the
+    // work. Called rather than deleted because this function is also the
+    // shutdown save, where it is the last chance to write anything at all.
+    await flushPageHits()
 
+    // `temp*` are the in-progress aggregation buckets, and they were **not**
+    // in this object while `setup.ts` read `data.temp1h` on boot and
+    // `core.loadTemps` knew how to restore them. Every restart therefore threw
+    // away up to 59 seconds of 1h aggregation, up to 29 minutes of 1d, and so
+    // on - and because a bucket only finalizes at its full count, the 1h chart
+    // stayed empty for up to an hour after every boot rather than resuming.
     const coreData: any = {
       history1m: history1m as AnalyticsSnapshot[],
       history1h: history1h as AnalyticsSnapshot[],
@@ -166,17 +235,18 @@ export async function saveAnalyticsData(_cacheBase: string) {
       history7d: history7d as AnalyticsSnapshot[],
       history30d: history30d as AnalyticsSnapshot[],
       pageHits: Array.from(pageHitsMap.entries()),
+      ...snapshotTemps(),
     }
     try {
       stmtUpsertCore.run('core', JSON.stringify(coreData))
     } catch {
       // The snapshot is rebuilt from memory on the next flush, so a failed
-      // upsert costs one interval of persisted history — not anything the
+      // upsert costs one interval of persisted history, not anything the
       // process still holds.
     }
   } catch (e) {
     // Telemetry must never be able to take down what it is measuring, so this
-    // still does not rethrow — but it is no longer silent.
+    // still does not rethrow, but it is no longer silent.
     //
     // The comment that used to sit here said the next flush retries. That is
     // false exactly where it mattered: the flush registered in `onShutdown` is

package/src/timescale.ts

@@ -1,16 +1,90 @@
+/**
+ * Every timescale fact, in one place, derived from two numbers each.
+ *
+ * There were **five** of these tables across two packages, and they agreed,
+ * which is luck rather than design, because nothing made them. `timescaleToMs`
+ * here, `getHistoryLimitForTimescale` in `core.ts`, the bucket counts inside
+ * `pushAnalyticsSnapshot`, and `getTimescaleIntervalMs` / `getTimescaleLimit`
+ * in the dashboard's client, the last pair byte-identical to the second.
+ *
+ * Collapsing them turned up that the whole family follows from a window length
+ * and a point count. Checked against all five originals before this replaced
+ * them, and `timescale.test.ts` keeps checking:
+ *
+ *     bucketMs   = windowMs / points
+ *     samples    = bucketMs / TICK_MS
+ *
+ * So `1d` is a day shown as 48 points, which makes each point half an hour and
+ * each half hour 1,800 one-second samples, and those are exactly the numbers
+ * the five tables carried.
+ */
+
+/** One sample per second is what every `history1m` window assumes. */
+export const TICK_MS = 1000
+
+export type Timescale = '1m' | '1h' | '1d' | '7d' | '30d'
+
+const DAY_MS = 86_400_000
+
+/** Window length and how many points it is drawn as. Everything else derives. */
+const SHAPE: Record<Timescale, { windowMs: number; points: number }> = {
+  '1m': { windowMs: 60_000, points: 60 },
+  '1h': { windowMs: 3_600_000, points: 60 },
+  '1d': { windowMs: DAY_MS, points: 48 },
+  '7d': { windowMs: 7 * DAY_MS, points: 28 },
+  '30d': { windowMs: 30 * DAY_MS, points: 30 },
+}
+
+export interface TimescaleFacts {
+  /** How far back the window reaches. */
+  windowMs: number
+  /** How many points it is drawn as, and how many the history array keeps. */
+  points: number
+  /** How much time one point covers. */
+  bucketMs: number
+  /** How many one-second samples fold into one point. */
+  samples: number
+}
+
+export const TIMESCALES: Record<Timescale, TimescaleFacts> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(SHAPE).map(([key, { windowMs, points }]) => [
+      key,
+      {
+        windowMs,
+        points,
+        bucketMs: windowMs / points,
+        samples: windowMs / points / TICK_MS,
+      },
+    ]),
+  ),
+) as Record<Timescale, TimescaleFacts>
+
+/** The ordered list, for anything that offers a choice of them. */
+export const TIMESCALE_KEYS = Object.keys(SHAPE) as Timescale[]
+
+export function isTimescale(value: string): value is Timescale {
+  return value in SHAPE
+}
+
+/**
+ * Facts for a timescale, or `1m`'s.
+ *
+ * A default rather than a throw, because the value reaches here from a query
+ * parameter and a socket frame: both of which a client writes, and neither of
+ * which should be able to raise a 500. The narrowest window is the safe one to
+ * fall back to: it reads the least data and shows the least.
+ */
+export function timescaleFacts(timescale: string): TimescaleFacts {
+  return isTimescale(timescale) ? TIMESCALES[timescale] : TIMESCALES['1m']
+}
+
+/**
+ * How far back a timescale reaches, in milliseconds.
+ *
+ * `0` for an unknown one, which is what this answered before and what
+ * `storage-sqlite.ts` relies on to mean "no bound".
+ */
 export function timescaleToMs(timescale: string): number {
-  switch (timescale) {
-    case '1m':
-      return 60_000
-    case '1h':
-      return 3_600_000
-    case '1d':
-      return 86_400_000
-    case '7d':
-      return 7 * 86_400_000
-    case '30d':
-      return 30 * 86_400_000
-    default:
-      return 0
-  }
+  return isTimescale(timescale) ? TIMESCALES[timescale].windowMs : 0
 }

package/src/types.ts

@@ -7,7 +7,6 @@ export type AnalyticsSnapshot = {
   apiHits: number | null
   pageHits: number | null
   uniqueRequests: number | null
-  dbHits: number | null
   errorPageHits: number | null
   ping: number | null
 }