@bakery-framework/plugin-analytics 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Kyle Cyrus Santos Obille
+
+The Software is provided subject to the standard MIT License, as detailed below, with the addition of the Commons Clause v1.0.
+
+The Commons Clause v1.0
+
+The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, “Sell” means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/support services related to the Software), a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
+
+Standard MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software (subject to the Commons Clause condition above), and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @bakery-framework/plugin-analytics
+
+Request, route and error metrics for
+[Bakery](https://github.com/obillekyle/bakery), with a live WebSocket feed.
+
+```bash
+bun add @bakery-framework/plugin-analytics
+```
+
+## Usage
+
+```ts
+// server.config.ts
+import { defineConfig } from '@bakery-framework/core'
+import analyticsPlugin from '@bakery-framework/plugin-analytics'
+
+export default defineConfig({
+  root: 'src',
+  plugins: [analyticsPlugin()],
+})
+```
+
+Rolling histories are exported for reading directly — `history1m`, `history1h`,
+`history1d`, `history7d`, `history30d` — alongside `pageHitsMap`,
+`pageHitsLog` and the `recordRouteHit` / `recordDbHit` / `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.
+
+## 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
+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
+that check.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bakery-framework/plugin-analytics",
+  "version": "1.0.0",
+  "description": "Bakery analytics plugin.",
+  "keywords": [
+    "bakery",
+    "bun",
+    "analytics",
+    "metrics",
+    "plugin"
+  ],
+  "author": "obillekyle",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obillekyle/bakery.git",
+    "directory": "packages/plugins/analytics"
+  },
+  "homepage": "https://github.com/obillekyle/bakery#readme",
+  "bugs": "https://github.com/obillekyle/bakery/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./stats": "./src/endpoints/stats.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/tests"
+  ],
+  "dependencies": {
+    "@bakery-framework/core": "^1.0.0"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/core.ts

@@ -0,0 +1,377 @@
+import type { AnalyticsSnapshot } from './types'
+
+export const RETENTION_MS = 30 * 24 * 3600 * 1000
+export const BOOT_MAX_ITEMS = 5000
+export const HARD_CAP = 50_000
+
+export const history1m: AnalyticsSnapshot[] = []
+export const history1h: AnalyticsSnapshot[] = []
+export const history1d: AnalyticsSnapshot[] = []
+export const history7d: AnalyticsSnapshot[] = []
+export const history30d: AnalyticsSnapshot[] = []
+
+export const pageHitsLog: { timestamp: number; path: string }[] = []
+export const pageHitsMap = new Map<string, number>()
+
+/**
+ * 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).
+ */
+export { connectedLoggers } from '@bakery-framework/core/logger'
+
+type TempAccumulator = {
+  count: number
+  memoryUsed: number
+  activeLoggers: number
+  activeSessions: number
+  routeHits: number
+  apiHits: number
+  pageHits: number
+  uniqueRequests: number
+  dbHits: number
+  errorPageHits: number
+  ping: number
+}
+
+function createAccumulator(): TempAccumulator {
+  return {
+    count: 0,
+    memoryUsed: 0,
+    activeLoggers: 0,
+    activeSessions: 0,
+    routeHits: 0,
+    apiHits: 0,
+    pageHits: 0,
+    uniqueRequests: 0,
+    dbHits: 0,
+    errorPageHits: 0,
+    ping: 0,
+  }
+}
+
+const temp1h = createAccumulator()
+const temp1d = createAccumulator()
+const temp7d = createAccumulator()
+const temp30d = createAccumulator()
+
+let routeHitsThisSecond = 0
+let apiHitsThisSecond = 0
+let pageHitsThisSecond = 0
+const uniqueRequestsThisSecond = new Set<string>()
+let dbHitsThisSecond = 0
+let errorPageHitsThisSecond = 0
+
+/**
+ * Drop the oldest `count` entries from the log and take their paths back out
+ * 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
+ * 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.
+ */
+function dropOldestHits(count: number) {
+  if (count <= 0) return
+  for (let j = 0; j < count; j++) {
+    const p = pageHitsLog[j].path
+    const c = pageHitsMap.get(p)
+    if (c === 1) pageHitsMap.delete(p)
+    else if (c) pageHitsMap.set(p, c - 1)
+  }
+  pageHitsLog.splice(0, count)
+}
+
+function prunePageHitsLog(now: number) {
+  let i = 0
+  while (
+    i < pageHitsLog.length &&
+    pageHitsLog[i].timestamp < now - RETENTION_MS
+  )
+    i++
+  dropOldestHits(i)
+
+  if (pageHitsLog.length > HARD_CAP) {
+    dropOldestHits(pageHitsLog.length - HARD_CAP)
+  }
+}
+
+let _pageHitsLogPruneTimer: ReturnType<typeof setInterval> | null = null
+export function ensurePageHitsLogPruner() {
+  if (_pageHitsLogPruneTimer !== null) return
+  _pageHitsLogPruneTimer = setInterval(() => {
+    try {
+      prunePageHitsLog(Date.now())
+    } catch (_e) {
+      // swallow errors; pruner is best-effort
+    }
+  }, 60_000)
+}
+
+export function stopPageHitsLogPruner() {
+  if (_pageHitsLogPruneTimer !== null) {
+    clearInterval(_pageHitsLogPruneTimer)
+    _pageHitsLogPruneTimer = null
+  }
+}
+
+function accumulate(temp: TempAccumulator, s: AnalyticsSnapshot) {
+  temp.count++
+  temp.memoryUsed += s.memoryUsed || 0
+  temp.activeLoggers += s.activeLoggers || 0
+  temp.activeSessions += s.activeSessions || 0
+  temp.routeHits += s.routeHits || 0
+  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
+}
+
+function finalizeAggregation(
+  temp: TempAccumulator,
+  timestamp: number,
+): AnalyticsSnapshot {
+  const count = temp.count || 1
+  const result: AnalyticsSnapshot = {
+    timestamp,
+    memoryUsed: Math.round(temp.memoryUsed / count),
+    activeLoggers: Math.round(temp.activeLoggers / count),
+    activeSessions: Math.round(temp.activeSessions / count),
+    routeHits: temp.routeHits,
+    apiHits: temp.apiHits,
+    pageHits: temp.pageHits,
+    uniqueRequests: temp.uniqueRequests,
+    dbHits: temp.dbHits,
+    errorPageHits: temp.errorPageHits,
+    ping: Math.round(temp.ping / count),
+  }
+  Object.assign(temp, createAccumulator())
+  return result
+}
+
+function loadAccumulator(target: TempAccumulator, loaded: any) {
+  if (!loaded) return
+  if (Array.isArray(loaded)) {
+    Object.assign(target, createAccumulator())
+    target.count = loaded.length
+    for (const s of loaded) {
+      target.memoryUsed += s.memoryUsed || 0
+      target.activeLoggers += s.activeLoggers || 0
+      target.activeSessions += s.activeSessions || 0
+      target.routeHits += s.routeHits || 0
+      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
+    }
+  } else if (typeof loaded === 'object') {
+    Object.assign(target, loaded)
+  }
+}
+
+export function isAssetPath(path: string): boolean {
+  if (!path || typeof path !== 'string') return true
+  if (path.startsWith('/_')) return true
+  return /\.(css|js|mjs|cjs|ts|tsx|jsx|vue|json|map|png|jpg|jpeg|webp|gif|svg|ico|bmp|woff|woff2|ttf|eot|txt|xml|webmanifest)$/i.test(
+    path,
+  )
+}
+
+export function recordRouteHit(method: string, path: string, search = '') {
+  routeHitsThisSecond += 1
+  if (path.startsWith('/api/')) {
+    apiHitsThisSecond += 1
+  } else if (!isAssetPath(path)) {
+    pageHitsThisSecond += 1
+    pageHitsLog.push({ timestamp: Date.now(), path })
+    ensurePageHitsLogPruner()
+    pageHitsMap.set(path, (pageHitsMap.get(path) || 0) + 1)
+  }
+  uniqueRequestsThisSecond.add(`${method} ${path}${search}`)
+}
+
+export function recordDbHit() {
+  dbHitsThisSecond += 1
+}
+
+export function recordErrorPageHit() {
+  errorPageHitsThisSecond += 1
+}
+
+export function pushAnalyticsSnapshot(snapshot: {
+  timestamp: number
+  memoryUsed: number
+  activeLoggers: number
+  activeSessions: number
+  ping: number
+}) {
+  const fullSnapshot: AnalyticsSnapshot = {
+    ...snapshot,
+    routeHits: routeHitsThisSecond,
+    apiHits: apiHitsThisSecond,
+    pageHits: pageHitsThisSecond,
+    uniqueRequests: uniqueRequestsThisSecond.size,
+    dbHits: dbHitsThisSecond,
+    errorPageHits: errorPageHitsThisSecond,
+  }
+
+  history1m.push(fullSnapshot)
+  if (history1m.length > 60) history1m.shift()
+
+  accumulate(temp1h, fullSnapshot)
+  accumulate(temp1d, fullSnapshot)
+  accumulate(temp7d, fullSnapshot)
+  accumulate(temp30d, fullSnapshot)
+
+  if (temp1h.count >= 60) {
+    history1h.push(finalizeAggregation(temp1h, fullSnapshot.timestamp))
+    if (history1h.length > 60) history1h.shift()
+  }
+  if (temp1d.count >= 1800) {
+    history1d.push(finalizeAggregation(temp1d, fullSnapshot.timestamp))
+    if (history1d.length > 48) history1d.shift()
+  }
+  if (temp7d.count >= 21600) {
+    history7d.push(finalizeAggregation(temp7d, fullSnapshot.timestamp))
+    if (history7d.length > 28) history7d.shift()
+  }
+  if (temp30d.count >= 86400) {
+    history30d.push(finalizeAggregation(temp30d, fullSnapshot.timestamp))
+    if (history30d.length > 30) history30d.shift()
+  }
+
+  routeHitsThisSecond = 0
+  apiHitsThisSecond = 0
+  pageHitsThisSecond = 0
+  uniqueRequestsThisSecond.clear()
+  dbHitsThisSecond = 0
+  errorPageHitsThisSecond = 0
+}
+
+export function getLatestAnalyticsSnapshot() {
+  return (
+    history1m[history1m.length - 1] || {
+      routeHits: 0,
+      apiHits: 0,
+      pageHits: 0,
+      uniqueRequests: 0,
+      dbHits: 0,
+      errorPageHits: 0,
+      ping: 0,
+    }
+  )
+}
+
+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
+  }
+}
+
+export function getHistoryForTimescale(timescale: string): AnalyticsSnapshot[] {
+  switch (timescale) {
+    case '30d':
+      return history30d
+    case '7d':
+      return history7d
+    case '1d':
+      return history1d
+    case '1h':
+      return history1h
+    default:
+      return history1m
+  }
+}
+
+export function getLatestHistoryPoint(
+  timescale: string,
+): AnalyticsSnapshot | null {
+  const history = getHistoryForTimescale(timescale)
+  return history[history.length - 1] || null
+}
+
+export function getFilledHistoryForTimescale(
+  timescale: string,
+): AnalyticsSnapshot[] {
+  const raw = getHistoryForTimescale(timescale)
+  if (raw.length <= 1) return [...raw]
+
+  let interval = 1000
+  switch (timescale) {
+    case '30d':
+      interval = 86400000
+      break
+    case '7d':
+      interval = 21600000
+      break
+    case '1d':
+      interval = 1800000
+      break
+    case '1h':
+      interval = 60000
+      break
+    default:
+      interval = 1000
+      break
+  }
+
+  const limit = getHistoryLimitForTimescale(timescale)
+  const filled: AnalyticsSnapshot[] = []
+  filled.push({ ...raw[0] })
+
+  for (let i = 1; i < raw.length; i++) {
+    const prev = raw[i - 1]
+    const curr = raw[i]
+    const diff = curr.timestamp - prev.timestamp
+
+    if (diff > interval * 1.5) {
+      const startT = Math.max(
+        prev.timestamp + interval,
+        curr.timestamp - limit * interval,
+      )
+      let t = startT
+      while (t < curr.timestamp - interval * 0.5) {
+        filled.push({
+          timestamp: t,
+          memoryUsed: null,
+          activeLoggers: null,
+          activeSessions: null,
+          routeHits: null,
+          apiHits: null,
+          pageHits: null,
+          uniqueRequests: null,
+          dbHits: null,
+          errorPageHits: null,
+          ping: null,
+        })
+        t += interval
+      }
+    }
+    filled.push({ ...curr })
+  }
+
+  if (filled.length > limit) return filled.slice(-limit)
+  return filled
+}
+
+export function loadTemps(loaded: any) {
+  if (!loaded) return
+  if (loaded.temp1h) loadAccumulator(temp1h, loaded.temp1h)
+  if (loaded.temp1d) loadAccumulator(temp1d, loaded.temp1d)
+  if (loaded.temp7d) loadAccumulator(temp7d, loaded.temp7d)
+  if (loaded.temp30d) loadAccumulator(temp30d, loaded.temp30d)
+}

package/src/endpoints/stats.ts

@@ -0,0 +1,136 @@
+import { Bakery } from '@bakery-framework/core/core/bakery'
+import { DASHPASS_SESSION_KEY, Session } from '@bakery-framework/core/session'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import * as core from '../core'
+import { saveAnalyticsData } from '../storage-sqlite'
+import { timescaleToMs } from '../timescale'
+
+function getFilterCutoff(pagesFilter: string): number {
+  if (pagesFilter === 'all') return 0
+  return Date.now() - (timescaleToMs(pagesFilter) || 0)
+}
+
+function buildAggregatedHits(filterCutoff: number): Map<string, number> {
+  const aggregated = new Map<string, number>()
+  const hasCompleteWindow =
+    core.pageHitsLog.length > 0 && core.pageHitsLog[0].timestamp <= filterCutoff
+
+  if (filterCutoff > 0 && hasCompleteWindow) {
+    for (let i = core.pageHitsLog.length - 1; i >= 0; i--) {
+      const hit = core.pageHitsLog[i]
+      if (hit.timestamp < filterCutoff) break
+      aggregated.set(hit.path, (aggregated.get(hit.path) || 0) + 1)
+    }
+    return aggregated
+  }
+
+  for (const [k, v] of core.pageHitsMap.entries()) aggregated.set(k, v)
+  return aggregated
+}
+
+export function computeStats(
+  timescale: string,
+  excludeHistory: boolean,
+  pagesFilter: string,
+) {
+  const mem = process.memoryUsage()
+  const uptime = Math.round(process.uptime())
+  const latestHistory = core.getLatestAnalyticsSnapshot()
+
+  const filterCutoff = getFilterCutoff(pagesFilter)
+  const aggregated = buildAggregatedHits(filterCutoff)
+
+  const topPagesFiltered = Array.from(aggregated.entries())
+    .filter(([page]) => !core.isAssetPath(page))
+    .map(([page, hits]) => ({ page, hits }))
+    .sort((a, b) => b.hits - a.hits)
+    .slice(0, 10)
+
+  return {
+    uptime: `${uptime}s`,
+    uptimeSeconds: uptime,
+    pid: process.pid,
+    memoryUsed: `${Math.round(mem.rss / 1024 / 1024)} MB`,
+    memoryExternal: `${Math.round(mem.external / 1024 / 1024)} MB`,
+    bunVersion: Bun.version,
+    platform: process.platform,
+    arch: process.arch,
+    activeLoggers: core.connectedLoggers.size,
+    activeSessions: Session.count,
+    routeHits: latestHistory.routeHits,
+    apiHits: latestHistory.apiHits || 0,
+    pageHits: latestHistory.pageHits || 0,
+    uniqueRequests: latestHistory.uniqueRequests,
+    dbHits: latestHistory.dbHits,
+    errorPageHits: latestHistory.errorPageHits,
+    ping: latestHistory.ping,
+    topPages: topPagesFiltered,
+    history: excludeHistory
+      ? undefined
+      : core.getFilledHistoryForTimescale(timescale),
+    latestHistoryPoint: core.getLatestHistoryPoint(timescale),
+  }
+}
+
+/** The payload `/api/_analytics/stats` puts in the envelope's `data`. */
+export type AnalyticsStats = ReturnType<typeof computeStats>
+
+/**
+ * True when the caller may read analytics. Fails **closed** when DASHPASS is
+ * unset, matching the dashboard's behaviour — this previously returned
+ * "authorized" in that case, so the documented "disabled" posture actually
+ * exposed process stats and top pages to anyone.
+ */
+export function isAnalyticsAuthorized(req: Request): boolean {
+  if (!process.env.DASHPASS) return false
+  return Boolean(req.session?.get(DASHPASS_SESSION_KEY))
+}
+
+/**
+ * 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
+ * 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.
+ */
+function checkDashpassAuth(req: Request): JsonResponseData<undefined> | null {
+  if (isAnalyticsAuthorized(req)) return null
+  return process.env.DASHPASS
+    ? response.json.error<undefined>(401, 'Unauthorized')
+    : response.json.error<undefined>(404, 'Not Found')
+}
+
+export async function handleResetRequest(
+  req: Request,
+): Promise<JsonResponseData<undefined>> {
+  const authError = checkDashpassAuth(req)
+  if (authError) return authError
+
+  core.history1m.length = 0
+  core.history1h.length = 0
+  core.history1d.length = 0
+  core.history7d.length = 0
+  core.history30d.length = 0
+  core.pageHitsMap.clear()
+  core.pageHitsLog.length = 0
+
+  await saveAnalyticsData(Bakery.cacheDir)
+  return response.json.success<undefined>('Analytics data reset successfully')
+}
+
+export async function handleStatsRequest(
+  req: Request,
+  url: URL,
+): Promise<JsonResponseData<AnalyticsStats | undefined>> {
+  const authError = checkDashpassAuth(req)
+  if (authError) return authError
+
+  const timescale = url.searchParams.get('timescale') || '1m'
+  const excludeHistory = url.searchParams.get('excludeHistory') === 'true'
+  const pagesFilter = url.searchParams.get('pagesFilter') || 'all'
+
+  const stats = computeStats(timescale, excludeHistory, pagesFilter)
+  return response.json.success('success', stats)
+}

package/src/endpoints/websocket.ts

@@ -0,0 +1,60 @@
+import { WebSocketHandler } from '@bakery-framework/core/handlers'
+import type { ServerWebSocket } from 'bun'
+import { computeStats, isAnalyticsAuthorized } from './stats'
+
+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.
+  static canHandle(path: string, req?: Request): boolean {
+    if (path !== '/_analytics_ws') return false
+    return req ? isAnalyticsAuthorized(req) : false
+  }
+
+  static open(ws: ServerWebSocket<any>, _data: any) {
+    connectedAnalyticsClients.add(ws)
+  }
+
+  static upgrade() {
+    return {
+      timescale: '1m',
+      excludeHistory: true,
+      pagesFilter: '1d',
+    }
+  }
+
+  static async message(ws: ServerWebSocket<any>, message: any, data: any) {
+    try {
+      const msg = JSON.parse(String(message))
+      if (msg.type === 'subscribe') {
+        data.timescale = msg.timescale || '1m'
+        data.excludeHistory = !!msg.excludeHistory
+        data.pagesFilter = msg.pagesFilter || '1d'
+
+        const stats = computeStats(
+          data.timescale,
+          data.excludeHistory,
+          data.pagesFilter,
+        )
+
+        ws.send(
+          JSON.stringify({
+            status: 200,
+            excludeHistory: data.excludeHistory,
+            data: stats,
+          }),
+        )
+      }
+    } catch {
+      // The frame came from a client. Malformed JSON, or a subscribe naming a
+      // timescale that computes to nothing, must not throw out of the socket
+      // handler and take the connection down with it.
+    }
+  }
+
+  static close(ws: any) {
+    connectedAnalyticsClients.delete(ws)
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+import { definePlugin } from '@bakery-framework/core/plugins'
+import { recordErrorPageHit, recordRouteHit } from './core'
+
+export {
+  connectedLoggers,
+  history1d,
+  history1h,
+  history1m,
+  history7d,
+  history30d,
+  pageHitsLog,
+  pageHitsMap,
+  recordDbHit,
+  recordErrorPageHit,
+  recordRouteHit,
+} from './core'
+
+export default function analyticsPlugin() {
+  return definePlugin({
+    name: 'analytics',
+    async setup() {
+      const { setupAnalytics } = await import('./setup')
+      setupAnalytics()
+    },
+    onRoute(req) {
+      const url: URL = (req as any).__parsedUrl || new URL(req.url)
+      recordRouteHit(req.method, url.pathname, url.search)
+    },
+    onStart: async server => {
+      const { startAnalyticsLoop } = await import('./setup')
+      startAnalyticsLoop(server)
+    },
+
+    onError: recordErrorPageHit,
+  })
+}

package/src/log.ts

@@ -0,0 +1,24 @@
+import { Logger, messageLogger } from '@bakery-framework/core/logger'
+
+/**
+ * The plugin's own declared message table (convention 4).
+ *
+ * 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 —
+ * moving it is a change to `@bakery-framework/core`, not to this plugin.
+ */
+const analyticsMsgs = {
+  /**
+   * The flush that used to fail silently. Not a `trace`: on the shutdown path
+   * this is the last flush there will ever be, so it is a lost write, not a
+   * skipped retry.
+   */
+  SAVE_ERR: 'E Analytics flush failed: %r{error}%*',
+  LOOP_ERR: 'W Analytics loop tick failed: %r{error}%*',
+} as const
+
+export const analyticsLog = messageLogger(
+  new Logger('analytics'),
+  analyticsMsgs,
+)

package/src/loop.ts

@@ -0,0 +1,130 @@
+import { Bakery } from '@bakery-framework/core/core/bakery'
+import { errorMsg, getElapsed } from '@bakery-framework/core/logger'
+import { Session } from '@bakery-framework/core/session'
+import { Try } from '@bakery-framework/core/utils/common'
+import * as core from './core'
+import { computeStats } from './endpoints/stats'
+import { connectedAnalyticsClients } from './endpoints/websocket'
+import { analyticsLog } from './log'
+import { saveAnalyticsData } from './storage-sqlite'
+
+const SAVE_THROTTLE_MS = 60000
+
+/** One sample per second is what every `history1m` window assumes. */
+export const ANALYTICS_TICK_MS = 1000
+
+let lastSaveTime = 0
+
+/**
+ * Flush at most once per `SAVE_THROTTLE_MS`.
+ *
+ * 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,
+ * from a function whose whole job is to be harmless.
+ *
+ * `finally` rather than the success path: a failed flush that reset nothing
+ * would be retried on every following tick, turning one failure into a
+ * once-a-second hammer on a database that is already unhappy.
+ */
+async function throttleSave() {
+  if (Date.now() - lastSaveTime < SAVE_THROTTLE_MS) return
+  try {
+    await saveAnalyticsData(Bakery.cacheDir)
+  } finally {
+    lastSaveTime = Date.now()
+  }
+}
+
+async function runAnalyticsTick(server: any) {
+  const activeLoggersCount = core.connectedLoggers.size
+  const pingStart = Bun.nanoseconds()
+  const pingVal = await Try.return(async function getPing() {
+    const res = await server.fetch(`http://localhost/_analytics/ping`)
+    return res.status === 200 ? getElapsed(pingStart) : res.status
+  }, 0)
+
+  const mem = process.memoryUsage()
+  core.pushAnalyticsSnapshot({
+    timestamp: Date.now(),
+    memoryUsed: Math.round(mem.rss / 1024 / 1024),
+    activeLoggers: activeLoggersCount,
+    activeSessions: Session.count,
+    ping: pingVal,
+  })
+
+  // Awaited, not floated: a rejected flush used to escape this tick entirely
+  // and land nowhere.
+  await throttleSave()
+
+  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 }),
+      )
+    }
+  }
+}
+
+export let analyticsLoopTimer: ReturnType<typeof setTimeout> | null = null
+
+/** False between `stopAnalyticsLoop()` and the next start; gates the re-arm. */
+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(*)`.
+ * `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.
+ *
+ * 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.
+ * Re-arming in `finally` makes the overlap structurally impossible rather than
+ * merely unlikely, so neither failure can come back.
+ *
+ * `intervalMs` is a parameter so a test can drive the scheduler in
+ * milliseconds instead of minutes; nothing in the framework passes it.
+ */
+export function startAnalyticsLoop(
+  server: any,
+  intervalMs = ANALYTICS_TICK_MS,
+) {
+  stopAnalyticsLoop()
+  loopRunning = true
+
+  // One throttle window from now, not from the epoch. `lastSaveTime` starting
+  // at 0 made the very first tick flush a store that had accumulated exactly
+  // one sample, and put a SQLite write on the boot path.
+  lastSaveTime = Date.now()
+
+  const tick = async () => {
+    try {
+      await runAnalyticsTick(server)
+    } catch (e) {
+      analyticsLog.LOOP_ERR({ error: errorMsg(e) })
+    } finally {
+      // The re-arm lives here and only here: the next tick is scheduled once
+      // this one has fully settled, so two can never be in flight at once.
+      // A tick that was stopped mid-flight must not resurrect the loop.
+      if (loopRunning) analyticsLoopTimer = setTimeout(tick, intervalMs)
+    }
+  }
+
+  analyticsLoopTimer = setTimeout(tick, intervalMs)
+}
+
+export function stopAnalyticsLoop() {
+  loopRunning = false
+  if (analyticsLoopTimer) {
+    clearTimeout(analyticsLoopTimer)
+    analyticsLoopTimer = null
+  }
+}

package/src/setup.ts

@@ -0,0 +1,191 @@
+import { Bakery } from '@bakery-framework/core/core/bakery'
+import { Handler } from '@bakery-framework/core/handlers'
+import {
+  type PluginRouteTable,
+  routeTable,
+} from '@bakery-framework/core/plugins'
+import { FileSystem as fs } from '@bakery-framework/core/utils'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import * as core from './core'
+import { BOOT_MAX_ITEMS } from './core'
+import type { AnalyticsStats } from './endpoints/stats'
+import { handleResetRequest, handleStatsRequest } from './endpoints/stats'
+import { AnalyticsWSHandler } from './endpoints/websocket'
+import * as storageSqlite from './storage-sqlite'
+
+const PAGE_HITS_BOOT_WINDOW_MS = 24 * 3600 * 1000
+
+export const pageHitsLog = core.pageHitsLog
+export const pageHitsMap = core.pageHitsMap
+export const history1m = core.history1m
+export const history1h = core.history1h
+export const history1d = core.history1d
+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
+export const getHistoryLimitForTimescale = core.getHistoryLimitForTimescale
+export const getFilledHistoryForTimescale = core.getFilledHistoryForTimescale
+export const getHistoryForTimescale = core.getHistoryForTimescale
+export const getLatestHistoryPoint = core.getLatestHistoryPoint
+
+async function saveAnalyticsData() {
+  const cacheBase = Bakery.cacheDir
+  await storageSqlite.saveAnalyticsData(cacheBase)
+}
+
+function syncHistoryArrays(data: any) {
+  const syncArr = (source: any[], target: any[]) => {
+    if (source) {
+      target.length = 0
+      target.push(...source)
+    }
+  }
+  syncArr(data.history1m, core.history1m)
+  syncArr(data.history1h, core.history1h)
+  syncArr(data.history1d, core.history1d)
+  syncArr(data.history7d, core.history7d)
+  syncArr(data.history30d, core.history30d)
+}
+
+function processRawPageHits(pageHitsRaw: any) {
+  if (!Array.isArray(pageHitsRaw) || pageHitsRaw.length === 0) return
+
+  const minTs = Date.now() - PAGE_HITS_BOOT_WINDOW_MS
+  const list = pageHitsRaw
+    .map((e: any) => ({
+      timestamp: Number(e?.timestamp) || 0,
+      path: e?.path,
+    }))
+    .filter(
+      (e: any) =>
+        Number.isFinite(e.timestamp) &&
+        typeof e.path === 'string' &&
+        e.path.length > 0 &&
+        !core.isAssetPath(e.path) &&
+        e.timestamp >= minTs,
+    )
+    .slice(-BOOT_MAX_ITEMS)
+
+  pageHitsLog.length = 0
+  pageHitsLog.push(...list)
+}
+
+async function loadAnalyticsData() {
+  const cacheBase = Bakery.cacheDir
+  const { coreData, pageHitsRaw } =
+    await storageSqlite.loadAnalyticsData(cacheBase)
+
+  const data = coreData || {}
+  if (!coreData && !pageHitsRaw) return
+
+  syncHistoryArrays(data)
+
+  if (data.temp1h || data.temp1d || data.temp7d || data.temp30d) {
+    core.loadTemps(data)
+  }
+
+  if (data.pageHits && Array.isArray(data.pageHits)) {
+    pageHitsMap.clear()
+    for (const [k, v] of data.pageHits) {
+      if (!core.isAssetPath(k)) {
+        const count = typeof v === 'number' && Number.isFinite(v) ? v : 0
+
+        pageHitsMap.set(k, count > 1_000_000 ? 1 : count)
+      }
+    }
+  }
+
+  processRawPageHits(pageHitsRaw)
+}
+
+import { startAnalyticsLoop, stopAnalyticsLoop } from './loop'
+
+export { startAnalyticsLoop }
+
+/**
+ * The three paths this plugin claims, written once.
+ *
+ * `canHandle` and `resolveRoute` have to agree exactly: the handler sits at
+ * priority 110, above every content handler, so a path only `canHandle` knows
+ * about is claimed and then unroutable, and one only `resolveRoute` knows about
+ * is never reached. They held two verbatim copies of this list. The dashboard
+ * plugin keeps the same rule in `isDashboardPath`, over namespaces rather than
+ * exact paths.
+ *
+ * Exact matches, not prefixes — `/_analytics/pingback` belongs to the app.
+ */
+const ANALYTICS_PATHS = new Set([
+  '/_analytics/ping',
+  '/api/_analytics/stats',
+  '/api/_analytics/reset',
+])
+
+function isAnalyticsPath(path: string): boolean {
+  return ANALYTICS_PATHS.has(path)
+}
+
+class AnalyticsHandler extends Handler {
+  static canHandle(path: string) {
+    return isAnalyticsPath(path)
+  }
+  static resolveRoute(path: string): Handler.Route.Info | null {
+    if (isAnalyticsPath(path)) {
+      return new Handler.Route.Info(fs.resolve(''), path)
+    }
+    return null
+  }
+  static async handle(
+    _path: string,
+    req: Request,
+  ): Promise<AnalyticsResponse | undefined> {
+    const res = await handleAnalyticsRequest(req)
+    return res || undefined
+  }
+}
+
+/**
+ * Auth stays inside each endpoint (`handleStatsRequest` / `handleResetRequest`
+ * 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
+ * each endpoint's real return type through to `handleAnalyticsRequest`.
+ */
+const analyticsRoutes = routeTable({
+  '/_analytics/ping': () => response.text('pong'),
+  'POST /api/_analytics/reset': req => handleResetRequest(req),
+  '/api/_analytics/stats': (req, url) => handleStatsRequest(req, url),
+} satisfies PluginRouteTable)
+
+/**
+ * `/_analytics/ping` is a plain `Response`; the two `/api/` endpoints return
+ * the JSON envelope, which the router serialises in `processResponse`. Spelling
+ * the union out here means adding a route that returns something else is a
+ * compile error rather than a silent widening.
+ */
+export type AnalyticsResponse =
+  | Response
+  | JsonResponseData<AnalyticsStats | undefined>
+
+export function handleAnalyticsRequest(
+  req: Request,
+): Promise<AnalyticsResponse | null> {
+  return analyticsRoutes(req)
+}
+
+export function setupAnalytics() {
+  Bakery.handlers.fetch.set(AnalyticsHandler, 110)
+  Bakery.handlers.websocket.set(AnalyticsWSHandler)
+  void loadAnalyticsData()
+  Bakery.onShutdown(async () => {
+    stopAnalyticsLoop()
+    core.stopPageHitsLogPruner()
+    await saveAnalyticsData()
+  })
+}

package/src/storage-sqlite.ts

@@ -0,0 +1,251 @@
+import type Database from 'bun:sqlite'
+import { cacheDb } from '@bakery-framework/core/cache/shared-db'
+import { errorMsg, pluginLog } from '@bakery-framework/core/logger'
+import { Try } from '@bakery-framework/core/utils/common'
+import {
+  BOOT_MAX_ITEMS,
+  history1d,
+  history1h,
+  history1m,
+  history7d,
+  history30d,
+  pageHitsLog,
+  pageHitsMap,
+  RETENTION_MS,
+} from './core'
+import { analyticsLog } from './log'
+import { timescaleToMs } from './timescale'
+import type { AnalyticsSnapshot } from './types'
+
+/** Hard ceiling on persisted page hits, independent of RETENTION_MS. */
+const MAX_PAGE_HIT_ROWS = 200_000
+
+let db: Database | null = null
+let lastSavedPageHitTs = 0
+
+let stmtInsertPageHit: ReturnType<Database['prepare']> | null = null
+let stmtUpsertCore: ReturnType<Database['prepare']> | null = null
+let stmtSelectCore: ReturnType<Database['prepare']> | null = null
+let stmtSelectPageHits: ReturnType<Database['prepare']> | null = null
+let stmtDeletePageHits: ReturnType<Database['prepare']> | null = null
+
+function ensureSchema(d: Database) {
+  d.run(`CREATE TABLE IF NOT EXISTS page_hits (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp INTEGER NOT NULL,
+      path TEXT NOT NULL
+    );`)
+  d.run(
+    'CREATE INDEX IF NOT EXISTS idx_page_hits_timestamp ON page_hits(timestamp);',
+  )
+  d.run('CREATE INDEX IF NOT EXISTS idx_page_hits_path ON page_hits(path);')
+
+  d.run(`CREATE TABLE IF NOT EXISTS core (
+      key TEXT PRIMARY KEY,
+      value JSON
+    );`)
+}
+
+function initDbInstance() {
+  if (db) return db
+  db = cacheDb
+  try {
+    ensureSchema(db)
+  } catch (e) {
+    db = null
+    throw e
+  }
+  return db
+}
+
+export function initSqliteStorage() {
+  try {
+    return Promise.resolve(initDbInstance())
+  } catch (e) {
+    pluginLog.ANALYTICS_STORE_ERR({ error: errorMsg(e) })
+    return Promise.resolve(null)
+  }
+}
+
+export function getDb(): Database | null {
+  return db || null
+}
+
+function resetStatements() {
+  stmtInsertPageHit = null
+  stmtUpsertCore = null
+  stmtSelectCore = null
+  stmtSelectPageHits = null
+  stmtDeletePageHits = null
+}
+
+/**
+ * Test seam (convention 9) for the storage handle.
+ *
+ * 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.
+ */
+export function __setTestDb(instance: Database | null) {
+  db = instance
+  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.
+  if (instance) Try(() => ensureSchema(instance))
+}
+
+export function __resetTestDb() {
+  db = null
+  resetStatements()
+}
+
+export default {
+  initSqliteStorage,
+  getDb,
+}
+
+export async function saveAnalyticsData(_cacheBase: string) {
+  try {
+    await initSqliteStorage()
+    const d = getDb()
+    if (!d) return
+
+    if (!stmtDeletePageHits)
+      stmtDeletePageHits = d.prepare(
+        'DELETE FROM page_hits WHERE timestamp < ?',
+      )
+    if (!stmtInsertPageHit)
+      stmtInsertPageHit = d.prepare(
+        'INSERT INTO page_hits(timestamp,path) VALUES(?,?)',
+      )
+    if (!stmtUpsertCore)
+      stmtUpsertCore = d.prepare(
+        'INSERT OR REPLACE INTO core(key,value) VALUES(?,?)',
+      )
+
+    const now = Date.now()
+    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}
+         )`,
+      )
+    } 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
+      }
+    }
+
+    const coreData: any = {
+      history1m: history1m as AnalyticsSnapshot[],
+      history1h: history1h as AnalyticsSnapshot[],
+      history1d: history1d as AnalyticsSnapshot[],
+      history7d: history7d as AnalyticsSnapshot[],
+      history30d: history30d as AnalyticsSnapshot[],
+      pageHits: Array.from(pageHitsMap.entries()),
+    }
+    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
+      // 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.
+    //
+    // 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
+    // the last one there will ever be, so a throw there loses everything since
+    // the previous save, and lost it without a line of output. That is how a
+    // shared-cache-DB close ordered ahead of this hook stayed invisible.
+    analyticsLog.SAVE_ERR({ error: errorMsg(e) })
+  }
+}
+
+export async function loadAnalyticsData(
+  _cacheBase: string,
+  timescale: string = '1d',
+) {
+  try {
+    await initSqliteStorage()
+    const d = getDb()
+    if (!d) return { coreData: null, pageHitsRaw: null } as any
+
+    if (!stmtSelectCore)
+      stmtSelectCore = d.prepare('SELECT value FROM core WHERE key = ?')
+    if (!stmtSelectPageHits)
+      stmtSelectPageHits = d.prepare(
+        'SELECT timestamp, path FROM page_hits WHERE timestamp >= ? ORDER BY timestamp DESC LIMIT ?',
+      )
+
+    let coreData: any = null
+    try {
+      const row: any = stmtSelectCore.get('core')
+      if (row.value) {
+        coreData =
+          typeof row.value === 'string' ? JSON.parse(row.value) : row.value
+      }
+    } catch {
+      coreData = null
+    }
+
+    const windowMs = timescaleToMs(timescale) || 24 * 3600 * 1000
+    const now = Date.now()
+    const minTs = now - windowMs
+    let pageHitsRaw: any[] = []
+    try {
+      const rows: any[] = stmtSelectPageHits.all(minTs, BOOT_MAX_ITEMS) || []
+
+      for (let i = rows.length - 1; i >= 0; i--) {
+        const r = rows[i]
+        pageHitsRaw.push({ timestamp: r.timestamp, path: r.path })
+      }
+
+      try {
+        const maxRow: any = d
+          .prepare('SELECT MAX(timestamp) as maxTs FROM page_hits')
+          .get()
+        if (maxRow && typeof maxRow.maxTs === 'number') {
+          lastSavedPageHitTs = maxRow.maxTs
+        } else if (pageHitsRaw.length > 0) {
+          lastSavedPageHitTs = pageHitsRaw[pageHitsRaw.length - 1].timestamp
+        }
+      } catch {
+        if (pageHitsRaw.length > 0) {
+          lastSavedPageHitTs = pageHitsRaw[pageHitsRaw.length - 1].timestamp
+        }
+      }
+    } catch {
+      pageHitsRaw = null as any
+    }
+
+    return { coreData, pageHitsRaw } as any
+  } catch {
+    return { coreData: null, pageHitsRaw: null } as any
+  }
+}

package/src/timescale.ts

@@ -0,0 +1,16 @@
+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
+  }
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+export type AnalyticsSnapshot = {
+  timestamp: number
+  memoryUsed: number | null
+  activeLoggers: number | null
+  activeSessions: number | null
+  routeHits: number | null
+  apiHits: number | null
+  pageHits: number | null
+  uniqueRequests: number | null
+  dbHits: number | null
+  errorPageHits: number | null
+  ping: number | null
+}