From 0dd6bb6897ccf7cb0fdc89d0ef5c10de80ebbb77 Mon Sep 17 00:00:00 2001 From: Karan Date: Sat, 10 Oct 2026 00:18:39 -0400 Subject: [PATCH 1/5] runtime: app tokens, protect(), scope "functions"; init creates a project and dashboard link - token option (GenClass.init, createRuntime, data-token, token=, GENCLASS_CONFIG): validated (gc_ + 22 base62; invalid -> one warning, ignored) and sent as the telemetry envelope's top-level token - protect(name, fn) (named export and GenClass.protect, also on the script tag's window.GenClass): each call runs in a task op named after the function; same this/args/return/throws, sync stays sync; no runtime -> fn directly - InitOptions.scope "functions": decisions only for activity inside protected functions (gated in RuntimeImpl.trigger and runDelivery; recording and situation text unchanged) - Decision.fn and the decision telemetry event's fn: outermost protected function in the subject's cause chain - CLI init: creates a project at genclass.dev/api/projects (name from package.json), writes the token, prints the private dashboard link, saves it in .genclass.local (+ .gitignore); --token, --no-token, --no-telemetry implies no token; network failure -> warn and continue. CLI tests run with a mocked fetch. Co-Authored-By: Claude Opus 5.5 --- packages/runtime/bin/genclass-runtime.mjs | 11 +- packages/runtime/bin/lib/edit.mjs | 18 +- packages/runtime/bin/lib/init.mjs | 116 ++++++++- packages/runtime/bin/lib/token.mjs | 102 ++++++++ packages/runtime/src/cdn/config.ts | 10 +- packages/runtime/src/cdn/global.ts | 7 +- packages/runtime/src/index.ts | 35 ++- packages/runtime/src/protect.ts | 70 +++++ packages/runtime/src/runtime.ts | 94 ++++++- packages/runtime/src/telemetry/client.ts | 8 +- packages/runtime/src/telemetry/config.ts | 2 + packages/runtime/src/telemetry/index.ts | 2 + packages/runtime/src/token.ts | 26 ++ packages/runtime/src/trace/ops.ts | 2 + packages/runtime/src/types.ts | 17 ++ packages/runtime/test/install/cli.test.ts | 129 ++++++++- packages/runtime/test/install/mock-fetch.mjs | 26 ++ packages/runtime/test/projects.test.ts | 259 +++++++++++++++++++ 18 files changed, 898 insertions(+), 36 deletions(-) create mode 100644 packages/runtime/bin/lib/token.mjs create mode 100644 packages/runtime/src/protect.ts create mode 100644 packages/runtime/src/token.ts create mode 100644 packages/runtime/test/install/mock-fetch.mjs create mode 100644 packages/runtime/test/projects.test.ts diff --git a/packages/runtime/bin/genclass-runtime.mjs b/packages/runtime/bin/genclass-runtime.mjs index 0d1c08e5..8471be36 100755 --- a/packages/runtime/bin/genclass-runtime.mjs +++ b/packages/runtime/bin/genclass-runtime.mjs @@ -1,10 +1,10 @@ #!/usr/bin/env node // genclass-runtime CLI (Node >= 20, no dependencies). Also runs as `npx @genclass/runtime `. // -// genclass-runtime init [--mode observe|guard|heal] [--yes] [--dry-run] [--no-install] [--no-devtools] +// genclass-runtime init [--mode observe|guard|heal] [--token | --no-token] [--yes] [--dry-run] [--no-install] [--no-devtools] // genclass-runtime remove [--yes] [--dry-run] [--keep-package] -// Set GenClass up in a project (framework detection, install, one marked import in the entry file) and take it -// out again. Implemented in bin/lib/ (owner: INSTALL). +// Set GenClass up in a project (framework detection, install, one marked import in the entry file, an app token +// and private dashboard link from genclass.dev) and take it out again. Implemented in bin/lib/ (owner: INSTALL). // genclass-runtime fetch-model [--from ] [--variant q8|fp16|all] [--ort wasm|webgpu|all|none] [--ort-from ] [--force] [--quiet] // Download a GenClass model directory (model.json + model files) so an app can self-host it, plus the // onnxruntime-web files the runtime loads (into /ort/, the version the runtime bundles): @@ -50,12 +50,13 @@ const ORT_FILES = { const ROLES = ["tokenizer", "calibration", "meta"]; const USAGE = `Usage: - genclass-runtime init [--mode observe|guard|heal] [--yes] [--dry-run] [--no-install] [--no-devtools] + genclass-runtime init [--mode observe|guard|heal] [--token | --no-token] [--yes] [--dry-run] [--no-install] [--no-devtools] genclass-runtime remove [--yes] [--dry-run] [--keep-package] genclass-runtime fetch-model [--from ] [--variant q8|fp16|all] [--ort wasm|webgpu|all|none] [--ort-from ] [--force] [--quiet] genclass-runtime info -init sets GenClass up in the current project (shows the diff and asks first); remove undoes it +init sets GenClass up in the current project (shows the diff and asks first) and creates this app's token and +private dashboard link at genclass.dev (--no-token: no network); remove undoes it (\`genclass-runtime init --help\` for details). fetch-model downloads a GenClass model directory for self-hosting (default --variant all). The default --from is @genclass/runtime-model@0.2.0 on npm via jsDelivr, the runtime's own default model: diff --git a/packages/runtime/bin/lib/edit.mjs b/packages/runtime/bin/lib/edit.mjs index 63c93af0..96ee3dd5 100644 --- a/packages/runtime/bin/lib/edit.mjs +++ b/packages/runtime/bin/lib/edit.mjs @@ -441,14 +441,15 @@ export function bodyTagEnd(text) { export const CONFIG_COMMENT = "// Read by @genclass/runtime/auto, imported right after this file: any GenClass.init() option works here (see the README)."; -const isEmptyConfig = (cfg) => !cfg || (cfg.telemetry === undefined && !cfg.model); +const isEmptyConfig = (cfg) => !cfg || (cfg.telemetry === undefined && !cfg.model && !cfg.token); export { isEmptyConfig }; const modelLiteral = (m) => `model: { baseUrl: ${JSON.stringify(m.baseUrl)}, ortWasmPaths: ${JSON.stringify(m.ortWasmPaths)}${m.device ? `, device: ${JSON.stringify(m.device)}` : ""} }`; -/** The object init writes: `{ telemetry: false, model: { baseUrl: "/genclass-model/", ortWasmPaths: "..." } }`. */ +/** The object init writes: `{ token: "gc_...", telemetry: false, model: { baseUrl: "/genclass-model/", ortWasmPaths: "..." } }`. */ export function configLiteral(cfg) { const parts = []; + if (cfg.token) parts.push(`token: ${JSON.stringify(cfg.token)}`); if (cfg.telemetry !== undefined) parts.push(`telemetry: ${cfg.telemetry ? "true" : "false"}`); if (cfg.model) parts.push(modelLiteral(cfg.model)); return parts.length ? `{ ${parts.join(", ")} }` : "{}"; @@ -457,10 +458,14 @@ export function configLiteral(cfg) { /** The statement in genclass.config.(ts|js). */ export const configStatement = (cfg, ts) => `${ts ? "(globalThis as { GENCLASS_CONFIG?: object })" : "globalThis"}.GENCLASS_CONFIG = ${configLiteral(cfg)};`; -/** Sets telemetry / model in an existing GENCLASS_CONFIG statement (other keys a user added stay). */ +/** Sets token / telemetry / model in an existing GENCLASS_CONFIG statement (other keys a user added stay). */ export function updateConfigText(text, cfg) { return text.replace(/(GENCLASS_CONFIG\s*=\s*\{)([^;]*)(\}\s*;?)/, (_m, open, body, close) => { let b = body; + if (cfg.token) { + const v = `token: ${JSON.stringify(cfg.token)}`; + b = /\btoken\s*:\s*(?:"[^"]*"|'[^']*')/.test(b) ? b.replace(/\btoken\s*:\s*(?:"[^"]*"|'[^']*')/, v) : `${v}, ${b.trim()}`; + } if (cfg.telemetry !== undefined) { const v = `telemetry: ${cfg.telemetry ? "true" : "false"}`; b = /\btelemetry\s*:\s*(?:true|false)/.test(b) ? b.replace(/\btelemetry\s*:\s*(?:true|false)/, v) : `${v}, ${b.trim()}`; @@ -474,15 +479,16 @@ export function updateConfigText(text, cfg) { /** `telemetry=off, model=/genclass-model/, ort=/genclass-model/ort/` (meta content), "" when nothing to say. */ export function metaContent(cfg) { const parts = []; + if (cfg.token) parts.push(`token=${cfg.token}`); if (cfg.telemetry === false) parts.push("telemetry=off"); if (cfg.model) parts.push(`model=${cfg.model.baseUrl}`, `ort=${cfg.model.ortWasmPaths}`, ...(cfg.model.device ? [`device=${cfg.model.device}`] : [])); return parts.join(", "); } -const TAG_ATTRS = { telemetry: "data-telemetry", model: "data-model", ort: "data-ort", device: "data-device" }; +const TAG_ATTRS = { token: "data-token", telemetry: "data-telemetry", model: "data-model", ort: "data-ort", device: "data-device" }; const attrRe = (name) => new RegExp(String.raw`\s+${name}\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)`, "i"); -/** A script tag with data-telemetry / data-model / data-ort set for cfg (telemetry true removes the opt-out). */ +/** A script tag with data-token / data-telemetry / data-model / data-ort set for cfg (telemetry true removes the opt-out). */ export function tagWithConfig(tag, cfg) { const set = (t, name, value) => { const re = attrRe(name); @@ -493,6 +499,7 @@ export function tagWithConfig(tag, cfg) { return `${t.slice(0, close.index)}${attr}${t.slice(close.index)}`; }; let t = tag; + if (cfg.token) t = set(t, TAG_ATTRS.token, cfg.token); if (cfg.telemetry !== undefined) t = set(t, TAG_ATTRS.telemetry, cfg.telemetry ? null : "off"); if (cfg.model) { t = set(t, TAG_ATTRS.model, cfg.model.baseUrl); @@ -527,6 +534,7 @@ export function switchMetaConfig(text, cfg) { if (metaAt >= 0) { const cur = /content=["']([^"']*)["']/i.exec(lines[metaAt])?.[1] ?? ""; const pairs = Object.fromEntries(cur.split(/[,;]\s*/).filter(Boolean).map((p) => [p.split("=")[0].trim(), p.slice(p.indexOf("=") + 1).trim()])); + if (cfg.token) pairs.token = cfg.token; if (cfg.telemetry === false) pairs.telemetry = "off"; if (cfg.telemetry === true) delete pairs.telemetry; if (cfg.model) Object.assign(pairs, { model: cfg.model.baseUrl, ort: cfg.model.ortWasmPaths, ...(cfg.model.device ? { device: cfg.model.device } : {}) }); diff --git a/packages/runtime/bin/lib/init.mjs b/packages/runtime/bin/lib/init.mjs index c0a8150a..32d57386 100644 --- a/packages/runtime/bin/lib/init.mjs +++ b/packages/runtime/bin/lib/init.mjs @@ -13,6 +13,7 @@ import { fileURLToPath } from "node:url"; import { detectCsp, detectProject, detectState, htmlFiles, isDir, isFile, readText, walkSkipped, walkSources } from "./detect.mjs"; import { MARK, hasMarker, isEmptyConfig, planRemoval, removeMarked, switchMetaConfig, switchMode, switchTagConfig, updateConfigText } from "./edit.mjs"; import { AUTO, configFileChange, configFileFor, planInit, scriptTag } from "./plan.mjs"; +import { LOCAL_FILE, START_URL, TOKEN_RE, createProject, readLocal, saveLocal, tokenInFiles } from "./token.mjs"; import { banner, c, confirm, err, out, printChange, row, sym } from "./ui.mjs"; const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", ".."); @@ -32,7 +33,8 @@ export const TELEMETRY_URL = `${REPO}/packages/runtime/TELEMETRY.md`; export const PRIVACY_URL = `${REPO}/PRIVACY.md`; export const USAGE = `Usage: - genclass-runtime init [--mode observe|guard|heal] [--no-telemetry | --telemetry] [--model-url ] + genclass-runtime init [--mode observe|guard|heal] [--token | --no-token] + [--no-telemetry | --telemetry] [--model-url ] [--yes] [--dry-run] [--no-install] [--no-devtools] [--cwd ] genclass-runtime remove [--yes] [--dry-run] [--keep-package] [--cwd ] @@ -43,9 +45,14 @@ remove takes out exactly what init added (the lines and blocks marked "${MARK} one of them was edited) and uninstalls the package if nothing else imports it. --mode observe (default: reports, never changes anything), guard or heal + --token use this app token (no network). By default init creates one for this app at + genclass.dev (named after package.json's name), writes it into what it adds, and + saves the token and your private dashboard link in ${LOCAL_FILE} + --no-token no token, no network (no dashboard; you can add one later: ${START_URL}) --no-telemetry turn off GenClass's anonymous diagnostics (on by default; see TELEMETRY.md and PRIVACY.md). Written as an option file (genclass.config.ts/js, imported right before - the auto import), or data-telemetry="off" on a plain HTML script tag + the auto import), or data-telemetry="off" on a plain HTML script tag. Implies + --no-token (a dashboard only gets data while telemetry is on) --telemetry keep them on, written explicitly (on an existing setup: undoes --no-telemetry) --model-url use a self-hosted model directory (made with \`fetch-model\`), e.g. /genclass-model/, with ONNX Runtime from ort/ (for a Content-Security-Policy without cdn.jsdelivr.net) @@ -72,10 +79,11 @@ const BOOL = { "no-sri": "noSri", "no-telemetry": "noTelemetry", telemetry: "telemetry", + "no-token": "noToken", help: "help", h: "help", }; -const VALUE = { mode: "mode", from: "from", cdn: "cdn", cwd: "cwd", strategy: "strategy", "model-url": "modelUrl" }; +const VALUE = { mode: "mode", from: "from", cdn: "cdn", cwd: "cwd", strategy: "strategy", "model-url": "modelUrl", token: "token" }; function parse(argv) { const o = {}; @@ -98,6 +106,9 @@ function parse(argv) { } if (o.mode && !MODES.includes(o.mode)) throw new UsageError(`--mode must be observe, guard or heal`); if (o.noTelemetry && o.telemetry) throw new UsageError(`--telemetry and --no-telemetry contradict each other`); + if (o.token !== undefined && o.noToken) throw new UsageError(`--token and --no-token contradict each other`); + if (o.token !== undefined && o.noTelemetry) throw new UsageError(`--no-telemetry means no token (a dashboard only gets data while telemetry is on): drop --token`); + if (o.token !== undefined && !TOKEN_RE.test(o.token)) throw new UsageError(`--token must be "gc_" followed by 22 letters or digits (get one: ${START_URL})`); if (o.strategy && !["instrumentation", "layout", "pages"].includes(o.strategy)) throw new UsageError(`--strategy must be instrumentation, layout or pages`); return o; } @@ -254,9 +265,10 @@ function printRecommendations(recs) { // ----------------------------------------------------------------------------------------- options -/** The options init writes: { telemetry?, model? } (empty: none). */ -export function configOf(o) { +/** The options init writes: { token?, telemetry?, model? } (empty: none). */ +export function configOf(o, token) { const c = {}; + if (token) c.token = token; if (o.noTelemetry) c.telemetry = false; else if (o.telemetry) c.telemetry = true; if (o.modelUrl) { @@ -371,35 +383,35 @@ async function switchModes(o, project, changes, install, spec, cwd, what) { if (o.dryRun) { out(` ${c.gray("Dry run: nothing was written.")}`); out(); - return 0; + return { code: 0, applied: false }; } if (!o.yes) { const ok = await confirm(what.mode ? `Switch to ${o.mode} mode${what.options ? ` (${what.options})` : ""}?` : `Apply ${what.options}?`); if (ok === null) { out(` Not a terminal, so nothing was written. Re-run with ${c.bold("--yes")} to apply.`); out(); - return 1; + return { code: 1, applied: false }; } if (!ok) { out(` Nothing changed.`); out(); - return 0; + return { code: 0, applied: false }; } out(); } if (install && !spawn(...installArgs(project.pm, spec), cwd)) { err(` ${c.red(sym.cross)} Installing ${PKG} failed, so no files were changed.`); - return 1; + return { code: 1, applied: false }; } for (const ch of changes) writeChange(ch); const done = [what.mode ? `now starts in ${o.mode} mode` : null, what.options ? `options: ${what.options}` : null].filter(Boolean).join("; "); out(` ${c.green(sym.ok)} ${c.bold(`GenClass Runtime ${done}.`)} ${c.gray(`(${changes.map((ch) => ch.rel).join(", ")})`)}`); out(); - return 0; + return { code: 0, applied: true }; } /** "telemetry off, model /genclass-model/" */ -const describeConfig = (cfg) => [cfg.telemetry === false ? "telemetry off" : cfg.telemetry ? "telemetry on" : null, cfg.model ? `model ${cfg.model.baseUrl}` : null].filter(Boolean).join(", "); +const describeConfig = (cfg) => [cfg.token ? `token ${cfg.token}` : null, cfg.telemetry === false ? "telemetry off" : cfg.telemetry ? "telemetry on" : null, cfg.model ? `model ${cfg.model.baseUrl}` : null].filter(Boolean).join(", "); /** Telemetry as the marked files set it (an existing setup): false when init wrote the opt-out. */ function currentConfig(files) { @@ -426,11 +438,73 @@ function withLocalDevice(cfg, project) { return cfg; } +// ------------------------------------------------------------------------------------- token, dashboard + +/** + * The app token init writes: { token?, write (put it into what init adds), source, created? (a new project: + * { token, dashboardUrl, name, created }), why? (no token), failed? }. Network only to create a new project, and + * never with --token, --no-token, --no-telemetry or --dry-run, or when this project already has a token. + */ +async function chooseToken(o, project, cwd, marked) { + if (o.noTelemetry) return { why: "--no-telemetry" }; + if (o.noToken) return { why: "--no-token" }; + const inFiles = tokenInFiles(marked); + const local = readLocal(cwd); + if (o.token) return { token: o.token, write: o.token !== inFiles, source: "--token", local: local?.token === o.token ? local : null }; + if (inFiles) return { token: inFiles, write: false, source: "already in your setup", local: local?.token === inFiles ? local : null }; + if (local) return { token: local.token, write: true, source: LOCAL_FILE, local }; + if (!o.telemetry && currentConfig(marked).telemetry === false) return { why: "telemetry is off in your setup" }; + if (o.dryRun) return { why: "dry run", wouldCreate: true }; + const r = await createProject(project.pkg?.name || project.name); + if (!r.ok) return { why: r.reason, failed: true }; + return { token: r.token, write: true, source: "new", created: r }; +} + +function tokenRow(tk) { + if (tk.token) { + row("Token", `${tk.token} ${c.gray(`(${tk.source === "new" ? "created for this app at genclass.dev" : tk.source})`)}`); + out(` Public (it ships in your page). The diagnostics above also feed this app's private dashboard.`); + return; + } + if (tk.wouldCreate) { + row("Token", `${c.gray("a new one would be created at genclass.dev (dry run: no network)")}`); + return; + } + if (tk.failed) { + row("Token", `none: could not create one (${tk.why})`, c.yellow(sym.warn)); + out(` GenClass works without it; you only miss the dashboard. Get a token at ${c.cyan(START_URL)}`); + out(` and run ${c.cyan(`${CMD} init --token gc_...`)}`); + return; + } + row("Token", c.gray(`none (${tk.why})`)); +} + +/** After init: the dashboard link (saved to .genclass.local when init wrote its changes). */ +function dashboardNotice(tk, cwd, applied) { + const link = tk.created?.dashboardUrl ?? tk.local?.dashboardUrl; + if (!tk.token || !link) return; + let saved = null; + if (tk.created && applied) { + try { + saved = saveLocal(cwd, { token: tk.token, dashboardUrl: link, name: tk.created.name, created: tk.created.created }); + } catch (e) { + err(` ${c.yellow(sym.warn)} Could not write ${LOCAL_FILE} (${e?.message ?? e}): copy the link below now.`); + } + } + out(` ${c.bold("Your dashboard")} ${c.bold(c.cyan(link))}`); + out(` ${c.yellow("Keep this link private; it is the only way to open your dashboard.")}`); + if (saved) out(` ${c.gray(`Saved in ${LOCAL_FILE}${saved.gitignore === "added" ? " (added to .gitignore)" : saved.gitignore === "listed" ? " (already in .gitignore)" : " (no .gitignore here: keep it out of version control)"}.`)}`); + else if (tk.created) out(` ${c.gray(`Nothing was written. To use this app's token later: ${CMD} init --token ${tk.token}`)}`); + else if (tk.local) out(` ${c.gray(`(from ${LOCAL_FILE})`)}`); + out(` ${c.gray("It shows data once your app runs with telemetry on (visitors who opt out or send Global Privacy Control are not counted).")}`); + out(); +} + async function init(o) { const cwd = projectDir(o); banner("init"); const project = detectProject(cwd); - const cfg = withLocalDevice(configOf(o), project); + let cfg = withLocalDevice(configOf(o), project); if (project.refused) { out(` ${c.yellow(sym.warn)} Not adding GenClass to ${c.bold(cwd)}: ${project.refused}.`); out(` If this is a browser app, add the import as the first line of its browser entry file yourself:`); @@ -450,6 +524,10 @@ async function init(o) { const files = walkSources(cwd); const marked = files.filter((f) => hasMarker(readText(f) ?? "")); + // a hand-written setup (no init markers): init leaves the code alone, so no token is created for it + const handWritten = !marked.length && manualRefs(files).length > 0; + const tk = handWritten ? { why: "GenClass is set up by hand here: pass token to GenClass.init()" } : await chooseToken(o, project, cwd, marked); + if (tk.write) cfg = { token: tk.token, ...cfg }; const needsPackage = !!project.pkg && project.framework !== "html" && !project.has(PKG); const install = needsPackage && !o.noInstall; const spec = installSpec(o); @@ -480,12 +558,18 @@ async function init(o) { const optionsChanged = switches.some((ch) => !o.mode || ch.kind === "create" || switchMode(ch.before, o.mode) !== ch.after); out(); telemetryNotice(isEmptyConfig(cfg) ? currentConfig(marked) : { ...currentConfig(marked), ...cfg }, null); + tokenRow(tk); cspAdvice(project, files, cfg); out(); - if (switches.length) return switchModes(o, project, switches, install, spec, cwd, { mode: !!o.mode && switches.some((ch) => switchMode(ch.before, o.mode) !== ch.before), options: optionsChanged && !isEmptyConfig(cfg) ? describeConfig(cfg) : null }); + if (switches.length) { + const r = await switchModes(o, project, switches, install, spec, cwd, { mode: !!o.mode && switches.some((ch) => switchMode(ch.before, o.mode) !== ch.before), options: optionsChanged && !isEmptyConfig(cfg) ? describeConfig(cfg) : null }); + dashboardNotice(tk, cwd, r.applied); + return r.code; + } if (!install) { out(` ${c.green("Nothing to do.")}${marked.length ? ` To take it out: ${c.cyan(`${CMD} remove`)}` : ""}`); out(); + dashboardNotice(tk, cwd, false); return 0; } out(); @@ -514,6 +598,7 @@ async function init(o) { row("Mode", `${o.mode ?? "observe"}${o.mode ? "" : c.gray(" (default: reports only, never changes anything; --mode guard lets it act)")}`); const cfgAt = plan.changes.find((ch) => /genclass\.config\.[cm]?[jt]s$/.test(ch.file))?.rel ?? (cfg.telemetry === false ? plan.changes[0]?.rel : null); telemetryNotice(cfg, cfgAt); + tokenRow(tk); cspAdvice(project, files, cfg); out(); out(` ${c.bold("Changes")}`); @@ -536,11 +621,13 @@ async function init(o) { if (ok === null) { out(` Not a terminal, so nothing was written. Re-run with ${c.bold("--yes")} to apply (or ${c.bold("--dry-run")} to preview).`); out(); + dashboardNotice(tk, cwd, false); return 1; } if (!ok) { out(` Nothing changed.`); out(); + dashboardNotice(tk, cwd, false); return 0; } out(); @@ -548,6 +635,7 @@ async function init(o) { if (install && !spawn(...installArgs(project.pm, spec), cwd)) { err(` ${c.red(sym.cross)} Installing ${PKG} failed, so no files were changed.`); + dashboardNotice(tk, cwd, false); return 1; } for (const ch of plan.changes) writeChange(ch); @@ -555,6 +643,7 @@ async function init(o) { out(); out(` ${c.green(sym.ok)} ${c.bold("GenClass Runtime is set up.")} ${c.gray(`(${plan.changes.map((ch) => ch.rel).join(", ")})`)}`); out(); + dashboardNotice(tk, cwd, true); out(` ${c.bold("Next")}`); const script = project.pkg?.scripts?.dev ? "dev" : project.pkg?.scripts?.start ? "start" : null; if (project.framework === "html") out(` ${sym.dot} Open your page. GenClass starts before your other scripts.`); @@ -654,6 +743,7 @@ async function remove(o) { } out(); out(` ${c.green(sym.ok)} ${c.bold("GenClass Runtime is removed.")}${changes.length ? ` ${c.gray(`(${changes.map((ch) => ch.rel).join(", ")})`)}` : ""}`); + if (isFile(join(cwd, LOCAL_FILE))) out(` ${c.gray(`${LOCAL_FILE} stays (your token and private dashboard link); delete it when you no longer need the dashboard.`)}`); out(); return 0; } diff --git a/packages/runtime/bin/lib/token.mjs b/packages/runtime/bin/lib/token.mjs new file mode 100644 index 00000000..212b6d58 --- /dev/null +++ b/packages/runtime/bin/lib/token.mjs @@ -0,0 +1,102 @@ +// The app token and private dashboard link for `genclass-runtime init` (owner: INSTALL). +// +// A token (`gc_` + 22 base62) identifies one web app. It is public (it ships in the page) and only lets telemetry be +// grouped under that app. The dashboard link (https://genclass.dev/dashboard/) is private: whoever has it sees +// the app's stats. init creates both with POST https://genclass.dev/api/projects (server: telemetry-worker/), writes the +// token into the snippet it adds, and keeps the link in .genclass.local (git-ignored when a .gitignore exists). + +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; + +export const TOKEN_RE = /^gc_[A-Za-z0-9]{22}$/; +const TOKEN_IN_TEXT = /\bgc_[A-Za-z0-9]{22}\b/; +export const PROJECTS_URL = "https://genclass.dev/api/projects"; +export const START_URL = "https://genclass.dev/start"; +const DASHBOARD_RE = /^https:\/\/genclass\.dev\/dashboard\/[A-Za-z0-9]+$/; +export const LOCAL_FILE = ".genclass.local"; +const TIMEOUT_MS = 10_000; + +const read = (f) => { + try { + return readFileSync(f, "utf8"); + } catch { + return null; + } +}; + +/** { token?, dashboardUrl? } from /.genclass.local (KEY=value lines), or null. */ +export function readLocal(dir) { + const t = read(join(dir, LOCAL_FILE)); + if (t === null) return null; + const kv = {}; + for (const line of t.split(/\r?\n/)) { + const m = /^\s*([A-Z_]+)\s*=\s*(\S*)\s*$/.exec(line); + if (m) kv[m[1]] = m[2]; + } + const r = {}; + if (TOKEN_RE.test(kv.GENCLASS_TOKEN ?? "")) r.token = kv.GENCLASS_TOKEN; + if (DASHBOARD_RE.test(kv.GENCLASS_DASHBOARD ?? "")) r.dashboardUrl = kv.GENCLASS_DASHBOARD; + return r.token ? r : null; +} + +/** The first token written in these files (a setup init already made), or null. */ +export function tokenInFiles(files) { + for (const f of files) { + const m = TOKEN_IN_TEXT.exec(read(f) ?? ""); + if (m) return m[0]; + } + return null; +} + +/** + * Writes .genclass.local and, when /.gitignore exists and does not list it yet, adds it there. Returns + * { file, gitignore: "added" | "listed" | "none" }. + */ +export function saveLocal(dir, { token, dashboardUrl, name, created }) { + const lines = [ + "# GenClass: this app's token and private dashboard link (written by `npx @genclass/runtime init`).", + "# Keep this file private and out of git: the dashboard link is the only way to open your dashboard.", + `GENCLASS_TOKEN=${token}`, + ...(dashboardUrl ? [`GENCLASS_DASHBOARD=${dashboardUrl}`] : []), + ...(name ? [`GENCLASS_PROJECT=${String(name).replace(/\s+/g, "_")}`] : []), + ...(created ? [`GENCLASS_CREATED=${created}`] : []), + ]; + const file = join(dir, LOCAL_FILE); + writeFileSync(file, `${lines.join("\n")}\n`); + const gi = join(dir, ".gitignore"); + const g = read(gi); + if (g === null) return { file, gitignore: "none" }; + if (g.split(/\r?\n/).some((l) => /^\/?\.genclass\.local\s*$/.test(l.trim()))) return { file, gitignore: "listed" }; + const eol = g.includes("\r\n") ? "\r\n" : "\n"; + writeFileSync(gi, `${g}${g === "" || g.endsWith("\n") ? "" : eol}${LOCAL_FILE}${eol}`); + return { file, gitignore: "added" }; +} + +/** + * POST /api/projects. Resolves { ok: true, token, dashboardUrl, name, created } or { ok: false, reason } (never + * rejects). `fetchFn` defaults to the global fetch (tests replace it). + */ +export async function createProject(name, fetchFn = globalThis.fetch) { + if (typeof fetchFn !== "function") return { ok: false, reason: "this Node.js has no fetch" }; + const ctl = typeof AbortController === "function" ? new AbortController() : null; + const timer = ctl ? setTimeout(() => ctl.abort(), TIMEOUT_MS) : null; + try { + const body = JSON.stringify(name ? { name: String(name).slice(0, 80) } : {}); + const res = await fetchFn(PROJECTS_URL, { method: "POST", headers: { "content-type": "application/json" }, body, ...(ctl ? { signal: ctl.signal } : {}) }); + if (res.status === 429) return { ok: false, reason: "too many new projects from this network right now (HTTP 429)" }; + if (!res.ok) return { ok: false, reason: `the server answered HTTP ${res.status}` }; + let j; + try { + j = await res.json(); + } catch { + return { ok: false, reason: "the server's answer was not JSON" }; + } + if (!j || !TOKEN_RE.test(String(j.token ?? "")) || !DASHBOARD_RE.test(String(j.dashboardUrl ?? ""))) return { ok: false, reason: "the server's answer had no valid token and dashboard link" }; + return { ok: true, token: j.token, dashboardUrl: j.dashboardUrl, name: typeof j.name === "string" ? j.name : name, created: typeof j.created === "string" ? j.created : undefined }; + } catch (e) { + const aborted = e?.name === "AbortError"; + return { ok: false, reason: aborted ? `no answer within ${TIMEOUT_MS / 1000} s` : `network error (${e?.cause?.code ?? e?.message ?? e})` }; + } finally { + if (timer) clearTimeout(timer); + } +} diff --git a/packages/runtime/src/cdn/config.ts b/packages/runtime/src/cdn/config.ts index 2beb16a2..069b889b 100644 --- a/packages/runtime/src/cdn/config.ts +++ b/packages/runtime/src/cdn/config.ts @@ -10,7 +10,8 @@ // Keys of the meta tag and data attributes: mode, model (a model directory URL, or "off"), device, preload, ort // (onnxruntime-web wasm directory), worker, report, debug, triage, devtools (bare / true, "local" = only on // localhost, false, or a corner such as "bottom-left"), telemetry (off/false/no: no anonymous diagnostics), autostate -// (off/false/no: no automatic state discovery; on by default in these entries). +// (off/false/no: no automatic state discovery; on by default in these entries), token (the app's dashboard token, +// gc_...), scope (app or functions). // // Trust: every `` in the document is read (head or body, first to last), and its keys can set // the mode and the model and onnxruntime-web URLs. That is deliberate (no build step needed), but on a page that @@ -112,6 +113,13 @@ export function fromPairs(pairs: Record): PageConfig { // automatic state discovery (on by default in the zero-code entries): only an opt-out here if (isOff(lv)) c.autoState = false; break; + case "token": + // the app's dashboard token (validated with a console warning by createRuntime) + if (v) c.token = v; + break; + case "scope": + if (lv === "app" || lv === "functions") c.scope = lv; + break; case "telemetry": // anonymous diagnostics (TELEMETRY.md): only an opt-out here; on is the GenClass.init default if (isOff(lv)) c.telemetry = false; diff --git a/packages/runtime/src/cdn/global.ts b/packages/runtime/src/cdn/global.ts index f8b50fe2..457ac08e 100644 --- a/packages/runtime/src/cdn/global.ts +++ b/packages/runtime/src/cdn/global.ts @@ -4,7 +4,7 @@ // // Runs GenClass.init() as soon as the tag executes (put it first in so it sees the page's first requests), // with options from the tag's data attributes, and window.GENCLASS_CONFIG (src/cdn/config.ts), -// and exposes window.GenClass: { init, runtime, destroy, devtools, createRuntime, version }. `data-manual` only +// and exposes window.GenClass: { init, runtime, destroy, devtools, createRuntime, protect, version }. `data-manual` only // exposes window.GenClass (call GenClass.init(options) yourself; the page configuration still applies underneath); `data-devtools` mounts the overlay (bare: always, // "local": only on localhost); `data-base` is the URL of the package's dist/ directory when you self-host the file. // @@ -14,7 +14,7 @@ // onnxruntime-web package or `data-ort`), and the devtools overlay (dist/devtools/index.js). import { registerDiscovery } from "../discover/index.js"; -import { GenClass, createRuntime, GenClassUnavailableError } from "../index.js"; +import { GenClass, createRuntime, GenClassUnavailableError, protect } from "../index.js"; import type { DevtoolsHandle, DevtoolsOptions } from "../devtools/index.js"; import type { InitOptions, ModelOptions, Runtime } from "../types.js"; import { devtoolsOptions, fromDataset, isKilled, mergeConfig, readMetaConfig, readWindowConfig, splitConfig, whenBody, type PageConfig } from "./config.js"; @@ -79,6 +79,8 @@ export interface GenClassGlobal { /** Load and mount the devtools overlay (initialises GenClass first if needed). */ devtools(options?: DevtoolsOptions): Promise; createRuntime: typeof createRuntime; + /** Wrap a function so each call is tracked and protected under `name` (see protect() in the README). */ + protect: typeof protect; GenClassUnavailableError: typeof GenClassUnavailableError; /** The dist/ directory the worker, onnxruntime-web and devtools load from. */ readonly base: string; @@ -155,6 +157,7 @@ function install(): void { return mount(GenClass.runtime ?? api.init(), options); }, createRuntime, + protect, GenClassUnavailableError, }; w.GenClass = api; diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts index d53d2368..5989f806 100644 --- a/packages/runtime/src/index.ts +++ b/packages/runtime/src/index.ts @@ -9,6 +9,8 @@ import { RuntimeImpl } from "./runtime.js"; import { createModelHost } from "./model/host.js"; import { startTelemetry } from "./telemetry/index.js"; import { telemetryOff } from "./telemetry/client.js"; +import { resolveToken } from "./token.js"; +import { protect, setProtectResolver } from "./protect.js"; export * from "./types.js"; export { browserClock } from "./clock.js"; @@ -36,6 +38,8 @@ export { describeElement } from "./observe/dom-user.js"; export { RuntimeImpl } from "./runtime.js"; export { DEFAULT_TELEMETRY_ENDPOINT, TELEMETRY_SCHEMA, TELEMETRY_NOTICE } from "./telemetry/index.js"; export { RUNTIME_VERSION } from "./version.js"; +export { protect } from "./protect.js"; +export { TOKEN_PATTERN, isValidToken } from "./token.js"; /** fetch as it was when this module loaded: the model host downloads with it, so GenClass never observes itself. */ const NATIVE_FETCH: typeof fetch | undefined = @@ -199,14 +203,29 @@ export function createRuntime(options: CreateOptions = {}): Runtime { decider = makeHost(options.model, nf, options.clock, (options.global ?? globalThis) as never); } const rt = new RuntimeImpl({ ...options, decider: decider ?? null, ownsDecider: owns }); + const con = () => (rt.global.console as Console | undefined) ?? (globalThis as { console?: Console }).console; + const token = resolveToken(options.token, (m) => con()?.warn?.(`[GenClass] ${m}`)); if (options.enabled === false) rt.telemetry = telemetryOff("disabled"); else - rt.telemetry = startTelemetry(rt, options.telemetry, false, { - model: owns ? "local" : decider ? "custom" : "off", - ...(options.triage ? { triage: options.triage } : {}), - ...(options.shadow ? { shadow: options.shadow } : {}), - ...(options.policy?.holdWrites ? { holdWrites: true } : {}), - }); + rt.telemetry = startTelemetry( + rt, + options.telemetry, + false, + { + model: owns ? "local" : decider ? "custom" : "off", + ...(options.triage ? { triage: options.triage } : {}), + ...(options.shadow ? { shadow: options.shadow } : {}), + ...(options.policy?.holdWrites ? { holdWrites: true } : {}), + }, + token, + ); + if (token && !rt.telemetry.enabled && options.debug) { + try { + con()?.info?.(`[GenClass] A token is set, but telemetry is off (${rt.telemetry.reason ?? "off"}), so nothing reaches your dashboard from this page.`); + } catch { + /* ignore */ + } + } return rt; } @@ -271,8 +290,12 @@ export const GenClass = { current = null; r?.destroy(); }, + /** The same as the named export protect(): wrap a function so GenClass tracks and protects each call. */ + protect, }; +setProtectResolver(() => (current instanceof RuntimeImpl ? current : null)); + function initUnsafe(options: InitOptions): Runtime { { const g = globalThis as unknown as Record; diff --git a/packages/runtime/src/protect.ts b/packages/runtime/src/protect.ts new file mode 100644 index 00000000..3923f4ca --- /dev/null +++ b/packages/runtime/src/protect.ts @@ -0,0 +1,70 @@ +// protect(): the function-specific way to use GenClass (InitOptions.scope "functions"). +// +// import { GenClass, protect } from "@genclass/runtime"; +// GenClass.init({ token: "gc_...", scope: "functions" }); +// export const submitOrder = protect("checkout submit", async (cart) => { ... }); +// +// Each call runs inside a "task" op named `name` (like runtime.op), so the fetches, state writes, timers and errors +// it causes are attributed to it, and decisions about them carry `fn: name`. Invariants: +// - Safe at module-import time: the runtime is looked up on every call (GenClass.runtime). No runtime: fn is called +// directly (one check of overhead). +// - Same signature: `this`, arguments, return value and thrown errors pass through; sync stays sync. An async +// function's promise is replaced by one that settles the same way (as runtime.op does). Other thenables are +// returned as they are. +// - Never throws on its own (a missing name: a console warning and fn.name is used; not a function: a warning and +// the value is returned unchanged). + +import type { RuntimeImpl } from "./runtime.js"; + +let resolve: () => RuntimeImpl | null = () => null; + +/** Where protect() finds the runtime (src/index.ts: GenClass.runtime). Internal; tests point it at their runtime. */ +export function setProtectResolver(fn: () => RuntimeImpl | null): void { + resolve = fn; +} + +const MAX_NAME = 80; + +function warn(msg: string): void { + try { + (globalThis as { console?: Console }).console?.warn?.(`[GenClass] ${msg}`); + } catch { + /* ignore */ + } +} + +/** + * Wrap `fn` so each call is tracked as the protected function `name`. Returns a function with the same signature. + * Decisions about what the call causes (duplicate submits, overlapping or out-of-order calls, failures) are reported + * under `name`; with `GenClass.init({ scope: "functions" })` only those are decided. + */ +export function protect unknown>(name: string, fn: F): F { + if (typeof fn !== "function") { + warn(`protect(${JSON.stringify(String(name))}) needs a function; got ${fn === null ? "null" : typeof fn}.`); + return fn; + } + let label = typeof name === "string" ? name.trim() : ""; + if (!label) { + label = fn.name || "anonymous"; + warn(`protect() needs a name; using ${JSON.stringify(label)}.`); + } + if (label.length > MAX_NAME) label = label.slice(0, MAX_NAME); + const call = fn as unknown as (...a: unknown[]) => unknown; + const wrapped = function (this: unknown, ...args: unknown[]): unknown { + let rt: RuntimeImpl | null = null; + try { + rt = resolve(); + } catch { + rt = null; + } + if (!rt || typeof rt.runProtected !== "function") return call.apply(this, args); + return rt.runProtected(label, call, this, args); + }; + try { + Object.defineProperty(wrapped, "name", { value: fn.name, configurable: true }); + Object.defineProperty(wrapped, "length", { value: fn.length, configurable: true }); + } catch { + /* cosmetic only */ + } + return wrapped as unknown as F; +} diff --git a/packages/runtime/src/runtime.ts b/packages/runtime/src/runtime.ts index 5617a419..dad2ab7c 100644 --- a/packages/runtime/src/runtime.ts +++ b/packages/runtime/src/runtime.ts @@ -229,6 +229,8 @@ export class RuntimeImpl implements Runtime { private rateWarnedAt = -Infinity; private readonly appFn: (() => { title?: string; route?: string }) | undefined; private readonly debug: boolean; + /** InitOptions.scope: "functions" raises decisions only for activity inside protect()ed functions. */ + readonly scope: "app" | "functions"; private readonly persist: boolean; private _mode: Mode; private paused = false; @@ -354,6 +356,7 @@ export class RuntimeImpl implements Runtime { this.hub.holdWrites = this.policy.holdWrites; this.rate = new RateLimiter(() => this.policy.actionLimits); this.debug = !!o.debug; + this.scope = o.scope === "functions" ? "functions" : "app"; // URL overrides only demote, unless debug (OPTIONS-SPEC §3) const url = this.urlParams(); this._mode = o.mode ?? "observe"; @@ -1270,6 +1273,9 @@ export class RuntimeImpl implements Runtime { }; if (!this.consultable()) return passive(); const subjectOp = subjectOpOf(spec); + // the protect()ed function the subject ran inside; scope "functions": nothing else is decided (explicit asks are) + const fn = this.protectedFnOf(subjectOp ?? this.ambientNoMaterialize()); + if (this.scope === "functions" && fn === undefined && spec.trigger !== "ask") return passive(); const effMode = this.effectiveMode(subjectOp); // a route scope "off": ops there are recorded, never decided if (effMode === "off") return passive(); @@ -1370,7 +1376,7 @@ export class RuntimeImpl implements Runtime { return passive(); } this.sum.decision(res.latencyMs); - this.onDecision(built, res.answers, this.clock.now() - t0, ctl, passive, { waits, covers: background !== null, expired, passiveRan: () => passiveRan, hold: opts.hold, budget, block, subjectOp }); + this.onDecision(built, res.answers, this.clock.now() - t0, ctl, passive, { waits, covers: background !== null, expired, passiveRan: () => passiveRan, hold: opts.hold, budget, block, subjectOp, ...(fn !== undefined ? { fn } : {}) }); } finally { // decided (onDecision marked the delivery decided) or dropped (its later writes are decided on their own) if (background) this.deliveryPending.delete(background); @@ -1399,6 +1405,7 @@ export class RuntimeImpl implements Runtime { budget?: number; block?: "protected" | "cross-origin" | "scope" | null; subjectOp?: OpRec | null; + fn?: string; }, ): void { const trigger = built.spec.trigger; @@ -1543,6 +1550,7 @@ export class RuntimeImpl implements Runtime { decision.thresholdSource = gates.source[g.thresholdTier]; } if (reason) decision.reason = reason; + if (st.fn !== undefined) decision.fn = st.fn; this.decisionsBuf.push(decision); if (this.decisionsBuf.length > DECISIONS_KEPT) this.decisionsBuf.shift(); const rec: ExplainRec = { @@ -1866,6 +1874,8 @@ export class RuntimeImpl implements Runtime { const op = o.op; // protected / ignored-scope / off-scope subjects pass at once: no body read, no hold, zero added latency if (!this.consultable() || this.paused || this.destroyed || op.genclass || op.scope?.protected || op.scope?.mode === "off") return rel(); + // scope "functions": deliveries outside protect()ed functions are only observed + if (this.scope === "functions" && this.protectedFnOf(op) === undefined) return rel(); const since = heldSince ?? this.clock.now(); const now = this.clock.now(); const predicted = predictedWrites(this.env, op); @@ -2872,6 +2882,88 @@ export class RuntimeImpl implements Runtime { ); } + /** + * One call of a protect()ed function (src/protect.ts): runs fn inside a "task" op named `name`, like op(), but + * keeps sync results sync and returns fn's own value (the same promise object for async functions). Never throws + * on its own: anything that goes wrong in the bookkeeping falls back to calling fn directly. + */ + runProtected(name: string, fn: (...a: unknown[]) => R, self: unknown, args: unknown[]): R { + let o: OpRec | null = null; + try { + if (!this.destroyed) { + o = this.startOp("task", name); + o.fn = name; + } + } catch { + o = null; + } + if (!o) return fn.apply(self, args); + const op = o; + const end = (status: "ok" | "error", e?: unknown) => { + try { + this.endOp(op, status, status === "error" ? { errorText: (e as Error)?.message ?? String(e) } : {}); + } catch { + /* bookkeeping never breaks the app */ + } + }; + let r: R; + try { + r = this.ctx.run(op, () => fn.apply(self, args)); + } catch (e) { + end("error", e); + throw e; + } + // A native promise (any async function): return the promise its settlement chains to, as op() does, so an + // unhandled rejection still surfaces as one and a handled one never does. Other thenables (query builders that + // run on .then(), custom deferreds) are returned untouched and never touched: the op ends now. + if (!(r instanceof Promise)) { + end("ok"); + return r; + } + try { + return (r as Promise).then( + (v) => { + end("ok"); + this.stickSafe(op); + return v; + }, + (e: unknown) => { + end("error", e); + this.stickSafe(op); + throw e; + }, + ) as R; + } catch { + end("ok"); + return r; + } + } + + private stickSafe(op: OpRec): void { + try { + this.ctx.stick(op); + } catch { + /* ignore */ + } + } + + /** The ambient op without materializing a lazy timer op (no op ids consumed). */ + private ambientNoMaterialize(): OpRec | null { + const c = this.ctx.peek(); + return c instanceof LazyOp ? c.nearest : c; + } + + /** The outermost protect()ed function in op's cause chain, or undefined. */ + protectedFnOf(op: OpRec | null | undefined): string | undefined { + let found: string | undefined; + let x: OpRec | undefined = op ?? undefined; + for (let n = 0; x && n < 256; n++) { + if (x.fn !== undefined) found = x.fn; + x = x.cause !== undefined ? this.ops.get(x.cause) : undefined; + } + return found; + } + emit(name: string, data?: Record): void { const op = this.ctx.op(); const d: Record = {}; diff --git a/packages/runtime/src/telemetry/client.ts b/packages/runtime/src/telemetry/client.ts index 3db5e6df..f8c5db19 100644 --- a/packages/runtime/src/telemetry/client.ts +++ b/packages/runtime/src/telemetry/client.ts @@ -115,6 +115,9 @@ export class TelemetryClient implements TelemetryStatus { get sessionId(): string { return this.cfg.sessionId; } + get token(): string | undefined { + return this.cfg.token; + } // ------------------------------------------------------------------------------------------------ events @@ -268,6 +271,8 @@ export class TelemetryClient implements TelemetryStatus { : undefined, effectiveMode: d.effectiveMode, shadow: d.shadow ? compact({ action: d.shadow.action, tier: d.shadow.tier, wouldPass: d.shadow.wouldPass, reason: cut(d.shadow.reason, 120) }) : undefined, + // the protect()ed function the subject ran inside (a name the app chose) + fn: cut(d.fn, 80), }); if (d.reason === "vetoed" || d.reason === "would-veto") { c.vetoes++; @@ -522,7 +527,8 @@ export class TelemetryClient implements TelemetryStatus { } catch { /* ignore */ } - return `{"schema":${JSON.stringify(TELEMETRY_SCHEMA)},"sid":${JSON.stringify(this.cfg.sessionId)},"sent":${this.at()},"runtime":${JSON.stringify(RUNTIME_VERSION)},"model":${JSON.stringify(model)},"events":[`; + const token = this.cfg.token ? `"token":${JSON.stringify(this.cfg.token)},` : ""; + return `{"schema":${JSON.stringify(TELEMETRY_SCHEMA)},${token}"sid":${JSON.stringify(this.cfg.sessionId)},"sent":${this.at()},"runtime":${JSON.stringify(RUNTIME_VERSION)},"model":${JSON.stringify(model)},"events":[`; } private send(body: string, n: number, beacon: boolean): Promise { diff --git a/packages/runtime/src/telemetry/config.ts b/packages/runtime/src/telemetry/config.ts index 1e6f3da8..488d9667 100644 --- a/packages/runtime/src/telemetry/config.ts +++ b/packages/runtime/src/telemetry/config.ts @@ -22,6 +22,8 @@ export interface TelemetryConfig { situation: boolean; transport: TelemetryTransport; sessionId: string; + /** The app token (InitOptions.token), already validated; sent as the batch envelope's `token`. */ + token?: string; } export type TelemetryResolution = { on: true; config: TelemetryConfig } | { on: false; reason: string }; diff --git a/packages/runtime/src/telemetry/index.ts b/packages/runtime/src/telemetry/index.ts index 745883a5..6cc1c214 100644 --- a/packages/runtime/src/telemetry/index.ts +++ b/packages/runtime/src/telemetry/index.ts @@ -22,10 +22,12 @@ export function startTelemetry( opt: boolean | TelemetryOptions | undefined, defaultOn: boolean, info: TelemetrySessionInfo, + token?: string, ): TelemetryStatus { try { const res = resolveTelemetry(opt, rt.global, defaultOn); if (!res.on) return telemetryOff(res.reason); + if (token) res.config.token = token; const client = new TelemetryClient(rt, res.config, rt.global, info); if (!noticeShown) { noticeShown = true; diff --git a/packages/runtime/src/token.ts b/packages/runtime/src/token.ts new file mode 100644 index 00000000..0a505199 --- /dev/null +++ b/packages/runtime/src/token.ts @@ -0,0 +1,26 @@ +// App tokens (InitOptions.token): `gc_` + 22 base62 characters. Public by design: a token only lets a page's +// telemetry batches be grouped under the app's private dashboard link (https://genclass.dev/dashboard/). + +export const TOKEN_PATTERN = /^gc_[A-Za-z0-9]{22}$/; + +/** True for a well-formed token. */ +export function isValidToken(v: unknown): v is string { + return typeof v === "string" && TOKEN_PATTERN.test(v); +} + +/** + * The configured token, trimmed, or undefined. A value that is set but malformed logs one warning (`warn`) and is + * ignored. Never throws. + */ +export function resolveToken(v: unknown, warn: (msg: string) => void): string | undefined { + if (v === undefined || v === null || v === "") return undefined; + const t = typeof v === "string" ? v.trim() : v; + if (isValidToken(t)) return t; + try { + const shown = typeof v === "string" ? JSON.stringify(v.length > 40 ? `${v.slice(0, 40)}…` : v) : typeof v; + warn(`Ignoring token ${shown}: a GenClass token is "gc_" followed by 22 letters or digits. Get one with \`npx @genclass/runtime init\` or at https://genclass.dev/start.`); + } catch { + /* ignore */ + } + return undefined; +} diff --git a/packages/runtime/src/trace/ops.ts b/packages/runtime/src/trace/ops.ts index 07730727..c3dec19b 100644 --- a/packages/runtime/src/trace/ops.ts +++ b/packages/runtime/src/trace/ops.ts @@ -36,6 +36,8 @@ export interface OpRec extends Op { profiled?: boolean; /** Triggers already raised with this op as the subject. */ triggered?: Set; + /** Set on the task op of a protect()ed function call: the function's name. */ + fn?: string; /** Root op is a GenClass action: never gated, never profiled. */ genclass?: boolean; /** Children count (diagnostic). */ diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.ts index 9289ca16..f907f409 100644 --- a/packages/runtime/src/types.ts +++ b/packages/runtime/src/types.ts @@ -683,6 +683,19 @@ export interface InitOptions { * single sources off (`{ react: false }`). Also ``. */ autoState?: boolean | AutoStateOptions; + /** + * Your app's GenClass token (`gc_` + 22 letters/digits; get one with `npx @genclass/runtime init` or at + * https://genclass.dev/start). Public: it only lets this app's telemetry batches be grouped under your private + * dashboard link. It does nothing while telemetry is off (opt-outs and Global Privacy Control still win). An invalid + * value logs one console warning and is ignored. Also `data-token`, ``. + */ + token?: string; + /** + * Where GenClass raises decisions. "app" (default): the whole app. "functions": only for activity inside functions + * wrapped with `protect()` (their fetches, state writes, timers and errors); everything else is still observed + * and recorded as context, but never decided on or acted on. + */ + scope?: "app" | "functions"; } /** InitOptions.autoState as an object: each source defaults to on. */ @@ -740,6 +753,8 @@ export interface TelemetryStatus { readonly endpoint?: string; /** Random per page load (not persisted). */ readonly sessionId?: string; + /** The app token sent with each batch (InitOptions.token), when one is configured and valid. */ + readonly token?: string; /** Send what is queued now (resolves when the requests settle; never rejects). */ flush(): Promise; } @@ -891,6 +906,8 @@ export interface Decision { answers: Record; /** Structured reference to the subject (same as EvaluateRequest.subject). */ subjectRef?: SubjectRef; + /** The protect()ed function the subject ran inside (the outermost one in its cause chain); unset otherwise. */ + fn?: string; } export type Detection = Decision; diff --git a/packages/runtime/test/install/cli.test.ts b/packages/runtime/test/install/cli.test.ts index 3c834d77..013e0d82 100644 --- a/packages/runtime/test/install/cli.test.ts +++ b/packages/runtime/test/install/cli.test.ts @@ -5,7 +5,7 @@ import { execFileSync } from "node:child_process"; import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join, relative, resolve } from "node:path"; -import { fileURLToPath } from "node:url"; +import { fileURLToPath, pathToFileURL } from "node:url"; import { afterAll, describe, expect, it, vi } from "vitest"; // @ts-expect-error plain ESM module without types import { appendEnd, bodyTagEnd, codeStyle, insertTop, planRemoval, removeMarked, switchMode, topOffset } from "../../bin/lib/edit.mjs"; @@ -55,9 +55,20 @@ function snapshot(dir: string): Record { return out; } +// Every CLI run gets a fake fetch (no test reaches the network; by default it fails like being offline). +const MOCK_FETCH = resolve(HERE, "mock-fetch.mjs"); + function cli(dir: string, ...args: string[]): { code: number; out: string } { + return cliEnv({}, dir, ...args); +} + +function cliEnv(env: Record, dir: string, ...args: string[]): { code: number; out: string } { try { - const out = execFileSync(process.execPath, [BIN, ...args, "--cwd", dir], { encoding: "utf8", env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" }, stdio: ["ignore", "pipe", "pipe"] }); + const out = execFileSync(process.execPath, ["--import", pathToFileURL(MOCK_FETCH).href, BIN, ...args, "--cwd", dir], { + encoding: "utf8", + env: { ...process.env, GENCLASS_TEST_FETCH: "fail", ...env, NO_COLOR: "1", FORCE_COLOR: "0" }, + stdio: ["ignore", "pipe", "pipe"], + }); return { code: 0, out }; } catch (e) { const err = e as { status: number; stdout: string; stderr: string }; @@ -792,3 +803,117 @@ describe("init finds a Content-Security-Policy and prints the self-host steps", expect(readFileSync(join(dir, "genclass.config.js"), "utf8")).toContain(`device: "wasm"`); }); }); + +describe("init: app token and private dashboard link (fetch mocked; never the real genclass.dev)", () => { + const TOKEN = "gc_TestToken0123456789abc"; + const LINK = "https://genclass.dev/dashboard/TestSecret0123456789abcdefghijkl"; + const viteApp = (extra: Record = {}) => + project({ "package.json": pkg({ vite: "^7" }, { name: "shop-web" }), "index.html": VITE_HTML.replace("main.tsx", "main.ts"), "src/main.ts": "console.log(1);\n", ...extra }); + const calls = (log: string) => { + try { + return readFileSync(log, "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l) as { url: string; method: string; body: string }); + } catch { + return []; + } + }; + const logFile = () => join(mkdtempSync(join(tmpdir(), "gc-fetch-")), "calls.jsonl"); + + it("by default creates a project named after package.json, writes the token, prints and saves the private link", () => { + const dir = viteApp({ ".gitignore": "node_modules\n" }); + const log = logFile(); + roots.push(dirname(log)); + const r = cliEnv({ GENCLASS_TEST_FETCH: "ok", GENCLASS_TEST_FETCH_LOG: log }, dir, "init", "--yes", "--no-install"); + expect(r.code, r.out).toBe(0); + expect(calls(log)).toEqual([{ url: "https://genclass.dev/api/projects", method: "POST", body: JSON.stringify({ name: "shop-web" }) }]); + const files = snapshot(dir); + expect(files["src/genclass.config.ts"]).toContain(`GENCLASS_CONFIG = { token: "${TOKEN}" };`); + expect(files["src/main.ts"].split("\n")[0]).toBe(`import "./genclass.config"; // genclass:init`); + expect(files[".genclass.local"]).toContain(`GENCLASS_TOKEN=${TOKEN}\nGENCLASS_DASHBOARD=${LINK}\n`); + expect(files[".gitignore"]).toBe("node_modules\n.genclass.local\n"); + expect(r.out).toContain(LINK); + expect(r.out).toContain("keep this link private; it is the only way to open your dashboard".replace(/^k/, "K")); + // again: the token is already there, no network, nothing to do + const r2 = cliEnv({ GENCLASS_TEST_FETCH: "ok", GENCLASS_TEST_FETCH_LOG: log }, dir, "init", "--yes", "--no-install"); + expect(r2.code, r2.out).toBe(0); + expect(r2.out).toContain("Nothing to do"); + expect(calls(log)).toHaveLength(1); + expect(snapshot(dir)).toEqual(files); + // remove takes out what init wrote and keeps the link file (the only copy of the dashboard link) + const r3 = cli(dir, "remove", "--yes"); + expect(r3.code, r3.out).toBe(0); + expect(r3.out).toContain(".genclass.local stays"); + const left = snapshot(dir); + expect(left["src/main.ts"]).toBe("console.log(1);\n"); + expect(left["src/genclass.config.ts"]).toBeUndefined(); + expect(left[".genclass.local"]).toBe(files[".genclass.local"]); + }); + + it("--token uses that token without any network; --no-token and --no-telemetry write none", () => { + const log = logFile(); + roots.push(dirname(log)); + const env = { GENCLASS_TEST_FETCH: "ok", GENCLASS_TEST_FETCH_LOG: log }; + const a = viteApp(); + const mine = "gc_Mine0123456789abcdefgh"; + expect(cliEnv(env, a, "init", "--yes", "--no-install", "--token", mine).code).toBe(0); + expect(snapshot(a)["src/genclass.config.ts"]).toContain(`token: "${mine}"`); + expect(snapshot(a)[".genclass.local"]).toBeUndefined(); + const b = viteApp(); + const rb = cliEnv(env, b, "init", "--yes", "--no-install", "--no-token"); + expect(rb.code).toBe(0); + expect(rb.out).toContain("none (--no-token)"); + expect(snapshot(b)["src/genclass.config.ts"]).toBeUndefined(); + const c2 = viteApp(); + expect(cliEnv(env, c2, "init", "--yes", "--no-install", "--no-telemetry").code).toBe(0); + expect(snapshot(c2)["src/genclass.config.ts"]).toContain("GENCLASS_CONFIG = { telemetry: false };"); + // --dry-run: no network either + const d = viteApp(); + const rd = cliEnv(env, d, "init", "--dry-run"); + expect(rd.code).toBe(0); + expect(rd.out).toContain("dry run: no network"); + expect(calls(log)).toHaveLength(0); + }); + + it("flag errors: a malformed --token, --token with --no-token or --no-telemetry", () => { + const dir = viteApp(); + for (const args of [["--token", "gc_short"], ["--token", "gc_Mine0123456789abcdefgh", "--no-token"], ["--token", "gc_Mine0123456789abcdefgh", "--no-telemetry"]]) { + const r = cli(dir, "init", "--yes", "--no-install", ...args); + expect(r.code, r.out).toBe(2); + } + }); + + it("network failure, HTTP 429 or a bad answer: warns, sets GenClass up without a token, says where to get one", () => { + for (const mode of ["fail", "429", "500", "bad"]) { + const dir = viteApp({ ".gitignore": "dist\n" }); + const r = cliEnv({ GENCLASS_TEST_FETCH: mode }, dir, "init", "--yes", "--no-install"); + expect(r.code, r.out).toBe(0); + expect(r.out).toContain("could not create one"); + expect(r.out).toContain("https://genclass.dev/start"); + const files = snapshot(dir); + expect(files["src/main.ts"].split("\n")[0]).toBe(`import genclass from "@genclass/runtime/auto"; // genclass:init`); + expect(files["src/genclass.config.ts"]).toBeUndefined(); + expect(files[".genclass.local"]).toBeUndefined(); + expect(files[".gitignore"]).toBe("dist\n"); + } + }); + + it("an existing setup gets the token added in place; .genclass.local is reused without network", () => { + const dir = viteApp(); + expect(cli(dir, "init", "--yes", "--no-install").code).toBe(0); // offline: no token + writeFileSync(join(dir, ".genclass.local"), `GENCLASS_TOKEN=${TOKEN}\nGENCLASS_DASHBOARD=${LINK}\n`); + const log = logFile(); + roots.push(dirname(log)); + const r = cliEnv({ GENCLASS_TEST_FETCH: "ok", GENCLASS_TEST_FETCH_LOG: log }, dir, "init", "--yes", "--no-install"); + expect(r.code, r.out).toBe(0); + expect(calls(log)).toHaveLength(0); + expect(snapshot(dir)["src/genclass.config.ts"]).toContain(`token: "${TOKEN}"`); + expect(r.out).toContain(LINK); + }); + + it("plain HTML gets data-token on the script tag (and remove gives the page back byte for byte)", () => { + const html = project({ "index.html": `\n\n x\n\n\n\n` }); + expect(cliEnv({ GENCLASS_TEST_FETCH: "ok" }, html, "init", "--yes", "--no-install", "--cdn", "https://example.test/g.js", "--no-sri").code).toBe(0); + expect(snapshot(html)["index.html"]).toContain(` `); + expect(cli(html, "remove", "--yes").code).toBe(0); + expect(snapshot(html)["index.html"]).toBe(`\n\n x\n\n\n\n`); + }); +}); diff --git a/packages/runtime/test/install/mock-fetch.mjs b/packages/runtime/test/install/mock-fetch.mjs new file mode 100644 index 00000000..f215d0a3 --- /dev/null +++ b/packages/runtime/test/install/mock-fetch.mjs @@ -0,0 +1,26 @@ +// Preloaded into the CLI by test/install/cli.test.ts (`node --import`): replaces fetch so no test reaches the network +// (in particular never https://genclass.dev/api/projects). GENCLASS_TEST_FETCH picks the answer: "fail" (default: +// a network error), "ok" (201 with a project), "429", "500", "bad" (201 without a valid token). Every call is +// appended to the file GENCLASS_TEST_FETCH_LOG as one JSON line. + +import { appendFileSync } from "node:fs"; + +const mode = process.env.GENCLASS_TEST_FETCH || "fail"; +const log = process.env.GENCLASS_TEST_FETCH_LOG; + +globalThis.fetch = async (url, init = {}) => { + if (log) appendFileSync(log, `${JSON.stringify({ url: String(url), method: init.method ?? "GET", body: init.body ?? null })}\n`); + if (mode === "fail") throw new TypeError("fetch failed", { cause: { code: "ENOTFOUND" } }); + const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }); + if (mode === "429") return json(429, { error: "rate limited" }); + if (mode === "500") return json(500, { error: "boom" }); + if (mode === "bad") return json(201, { token: "nope" }); + const name = (() => { + try { + return JSON.parse(init.body).name ?? ""; + } catch { + return ""; + } + })(); + return json(201, { token: "gc_TestToken0123456789abc", dashboardUrl: "https://genclass.dev/dashboard/TestSecret0123456789abcdefghijkl", name, created: "2026-10-10T00:00:00.000Z" }); +}; diff --git a/packages/runtime/test/projects.test.ts b/packages/runtime/test/projects.test.ts new file mode 100644 index 00000000..454e8d56 --- /dev/null +++ b/packages/runtime/test/projects.test.ts @@ -0,0 +1,259 @@ +// App tokens, dashboards and protect() (README "Your dashboard", "Function-specific"): the token from every config +// source, invalid tokens, the telemetry envelope's `token`, `fn` on decisions, protect() semantics and +// InitOptions.scope "functions". Telemetry is only on where a test injects a recording transport. + +import { afterEach, describe, expect, it, vi } from "vitest"; +import { GenClass, createRuntime, isValidToken, protect, TOKEN_PATTERN } from "../src/index.js"; +import { fromDataset, fromPairs, mergeConfig, parsePairs, readMetaConfig, readWindowConfig } from "../src/cdn/config.js"; +import { setProtectResolver } from "../src/protect.js"; +import type { RuntimeImpl } from "../src/runtime.js"; +import { resetTelemetryNotice } from "../src/telemetry/index.js"; +import type { TelemetryTransport } from "../src/types.js"; +import { defaultScript, setup } from "./helpers.js"; + +const TOKEN = "gc_AbCdEfGhIjKlMnOpQrStUv"; + +interface Sent { + body: Record & { events: Record[] }; +} +function recorder(): TelemetryTransport & { sent: Sent[] } { + const sent: Sent[] = []; + return { + sent, + send(_url, body) { + sent.push({ body: JSON.parse(body) }); + return Promise.resolve(); + }, + }; +} + +afterEach(() => { + setProtectResolver(() => (GenClass.runtime as RuntimeImpl | null) ?? null); + GenClass.destroy(); + vi.restoreAllMocks(); +}); + +describe("token format", () => { + it("gc_ + 22 base62 characters", () => { + expect(TOKEN_PATTERN.source).toBe("^gc_[A-Za-z0-9]{22}$"); + expect(isValidToken(TOKEN)).toBe(true); + for (const bad of ["", "gc_", "gc_short", `${TOKEN}x`, TOKEN.replace("gc_", "GC_"), "gc_AbCdEfGhIjKlMnOpQrSt-v", 42, null]) expect(isValidToken(bad)).toBe(false); + }); +}); + +describe("token from every config source", () => { + it("meta tag, data attributes, window.GENCLASS_CONFIG and GenClass.init options", () => { + expect(fromPairs(parsePairs(`token=${TOKEN}, mode=observe`))).toEqual({ token: TOKEN, mode: "observe" }); + const doc = { querySelectorAll: () => [{ getAttribute: () => `token=${TOKEN}` }] }; + expect(readMetaConfig(doc).token).toBe(TOKEN); + expect(fromDataset({ token: TOKEN, devtools: "local" }).token).toBe(TOKEN); + expect(readWindowConfig({ GENCLASS_CONFIG: { token: TOKEN, scope: "functions" } })).toEqual({ token: TOKEN, scope: "functions" }); + // window config wins over the meta tag, as for every other key + expect(mergeConfig(fromPairs({ token: "gc_metametametametametameta" }), { token: TOKEN }).token).toBe(TOKEN); + expect(fromPairs(parsePairs("scope=functions")).scope).toBe("functions"); + expect(fromPairs(parsePairs("scope=everything")).scope).toBeUndefined(); + }); + + it("a valid token goes on every batch envelope (top-level `token`); runtime.telemetry.token reports it", async () => { + const transport = recorder(); + const s = setup({ token: TOKEN, telemetry: { transport }, extraGlobal: { crypto: globalThis.crypto } }); + expect(s.rt.telemetry?.token).toBe(TOKEN); + await s.rt.telemetry!.flush(); + expect(transport.sent.length).toBeGreaterThan(0); + for (const b of transport.sent) { + expect(b.body.token).toBe(TOKEN); + expect(b.body.schema).toBe("genclass-telemetry/1"); + } + // never inside an event + expect(JSON.stringify(transport.sent.flatMap((b) => b.body.events))).not.toContain(TOKEN); + s.rt.destroy(); + }); + + it("no token: the envelope has no `token` key", async () => { + const transport = recorder(); + const s = setup({ telemetry: { transport }, extraGlobal: { crypto: globalThis.crypto } }); + await s.rt.telemetry!.flush(); + expect(transport.sent.length).toBeGreaterThan(0); + for (const b of transport.sent) expect("token" in b.body).toBe(false); + s.rt.destroy(); + }); + + it("an invalid token: one console warning, ignored, never throws", async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined); + const transport = recorder(); + const s = setup({ token: "gc_tooShort", telemetry: { transport }, extraGlobal: { crypto: globalThis.crypto, console } }); + expect(warn.mock.calls.filter((c) => String(c[0]).includes("Ignoring token"))).toHaveLength(1); + expect(s.rt.telemetry?.token).toBeUndefined(); + await s.rt.telemetry!.flush(); + for (const b of transport.sent) expect("token" in b.body).toBe(false); + s.rt.destroy(); + expect(() => createRuntime({ token: 12 as unknown as string, report: "silent", observe: {} })).not.toThrow(); + }); + + it("GenClass.init({ token }) with telemetry off: nothing is sent; one info line in debug only", () => { + const info = vi.spyOn(console, "info").mockImplementation(() => undefined); + const quiet = createRuntime({ token: TOKEN, report: "silent", observe: {} }); + expect(quiet.telemetry).toMatchObject({ enabled: false }); + expect(info).not.toHaveBeenCalled(); + const loud = createRuntime({ token: TOKEN, debug: true, report: "silent", observe: {}, telemetry: false }); + expect(info.mock.calls.filter((c) => String(c[0]).includes("telemetry is off"))).toHaveLength(1); + quiet.destroy(); + loud.destroy(); + }); + + it("opt-outs still win over a token (GPC)", () => { + resetTelemetryNotice(); + const s = setup({ token: TOKEN, telemetry: { transport: recorder() }, extraGlobal: { crypto: globalThis.crypto, navigator: { globalPrivacyControl: true } } }); + expect(s.rt.telemetry).toMatchObject({ enabled: false, reason: "gpc" }); + s.rt.destroy(); + }); +}); + +// ------------------------------------------------------------------------------------------------ protect() + +describe("protect(): same function, tracked", () => { + it("without a runtime it calls fn directly (this, args, return value, throws)", () => { + setProtectResolver(() => null); + const obj = { + k: 2, + mul: protect("mul", function (this: { k: number }, a: number, b: number) { + return this.k * a * b; + }), + }; + expect(obj.mul(3, 4)).toBe(24); + const boom = protect("boom", () => { + throw new RangeError("nope"); + }); + expect(() => boom()).toThrow(RangeError); + expect(GenClass.protect).toBe(protect); + }); + + it("keeps name and length; bad arguments warn and never throw", () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined); + function submitOrder(_a: number, _b: string) { + return 1; + } + const p = protect("checkout", submitOrder); + expect(p.name).toBe("submitOrder"); + expect(p.length).toBe(2); + expect(() => protect("x", undefined as unknown as () => void)).not.toThrow(); + expect(protect("", submitOrder)(1, "a")).toBe(1); + expect(warn).toHaveBeenCalledTimes(2); + }); + + it("with a runtime: sync stays sync, async stays async, `this`, args, results and errors pass through", async () => { + const s = setup(); + setProtectResolver(() => s.rt); + const self = { base: 10 }; + const sync = protect("sync", function (this: typeof self, x: number) { + return this.base + x; + }); + expect(sync.call(self, 5)).toBe(15); + const asyncFn = protect("async", async (x: number) => x * 2); + const r = asyncFn(21); + expect(r).toBeInstanceOf(Promise); + await expect(r).resolves.toBe(42); + const throwsSync = protect("throws", () => { + throw new TypeError("sync boom"); + }); + expect(() => throwsSync()).toThrow("sync boom"); + const rejects = protect("rejects", async () => { + throw new Error("async boom"); + }); + await expect(rejects()).rejects.toThrow("async boom"); + // other thenables come back untouched (never .then()-ed by GenClass) + const thenable = { then: vi.fn() }; + expect(protect("q", () => thenable)()).toBe(thenable); + expect(thenable.then).not.toHaveBeenCalled(); + // each call is a task op named after the function + const names = s.rt.history().filter((e) => e.kind === "op.start").map((e) => e.name); + expect(names).toEqual(expect.arrayContaining(["sync", "async", "throws", "rejects", "q"])); + s.rt.destroy(); + }); + + it("a destroyed runtime: fn is called directly", () => { + const s = setup(); + setProtectResolver(() => s.rt); + s.rt.destroy(); + expect(protect("after", (a: number) => a + 1)(1)).toBe(2); + }); + + it("decisions about what a protected call caused carry fn (also in telemetry); others do not", async () => { + const transport = recorder(); + const s = setup({ triage: "always", telemetry: { transport }, extraGlobal: { crypto: globalThis.crypto }, script: defaultScript({ failure: { diagnosis: "transient" } }) }); + setProtectResolver(() => s.rt); + s.server.on("POST", "/api/orders", { status: 500, body: {}, latency: 20 }); + s.server.on("GET", "/api/feed", { status: 500, body: {}, latency: 20 }); + // outer wraps inner: the outermost protected function names the decision + const inner = protect("inner", async () => { + await s.fetch("/api/orders", { method: "POST", body: "{}" }).catch(() => undefined); + }); + const outer = protect("checkout submit", () => inner()); + void outer(); + void s.fetch("/api/feed").catch(() => undefined); + await s.clock.advance(2000); + const ds = s.rt.decisions().filter((d) => d.trigger === "failure"); + expect(ds).toHaveLength(2); + const orders = ds.find((d) => d.subject.includes("/api/orders"))!; + const feed = ds.find((d) => d.subject.includes("/api/feed"))!; + expect(orders.fn).toBe("checkout submit"); + expect(feed.fn).toBeUndefined(); + await s.rt.telemetry!.flush(); + const evs = transport.sent.flatMap((b) => b.body.events).filter((e) => e.t === "decision" && e.trigger === "failure"); + expect(evs.map((e) => e.fn).sort()).toEqual(["checkout submit", undefined]); + s.rt.destroy(); + }); +}); + +describe("scope: \"functions\"", () => { + async function run(scope: "app" | "functions" | undefined) { + const s = setup({ triage: "always", ...(scope ? { scope } : {}), script: defaultScript({ failure: { diagnosis: "transient" } }) }); + setProtectResolver(() => s.rt); + s.server.on("POST", "/api/orders", { status: 500, body: {}, latency: 20 }); + s.server.on("GET", "/api/feed", { status: 500, body: {}, latency: 20 }); + const submit = protect("checkout submit", (body: string) => s.fetch("/api/orders", { method: "POST", body })); + void s.fetch("/api/feed").catch(() => undefined); + await s.clock.advance(500); + void submit("{}").catch(() => undefined); + await s.clock.advance(2000); + const ds = s.rt.decisions(); + const out = { + s, + triggers: ds.map((d) => `${d.trigger} ${d.subject}`), + decided: ds.map((d) => d.subject), + orderState: (() => { + const d = ds.find((x) => x.trigger === "failure" && x.subject.includes("/api/orders")); + return s.decider.calls.find((c) => c.trigger === "failure" && c.subject?.op === d?.subjectRef?.op)?.state; + })(), + history: s.rt.history().filter((e) => e.kind !== "decision").map((e) => `${e.kind} ${e.name}`), + }; + s.rt.destroy(); + return out; + } + + it("decides only for activity inside protected functions; still records everything", async () => { + const fns = await run("functions"); + expect(fns.decided.length).toBeGreaterThan(0); + expect(fns.decided.every((x) => x.includes("/api/orders"))).toBe(true); + expect(fns.triggers.some((t) => t.includes("/api/feed"))).toBe(false); + // the unprotected request is still in the history (context) + expect(fns.history.some((h) => h.includes("/api/feed"))).toBe(true); + }); + + it("default scope (app) is unchanged: unprotected activity is decided too; the situation text is identical", async () => { + const app = await run(undefined); + const explicit = await run("app"); + const fns = await run("functions"); + expect(app.decided.some((x) => x.includes("/api/feed"))).toBe(true); + expect(app.decided).toEqual(explicit.decided); + expect(app.history).toEqual(fns.history); + // gating changes which subjects are decided, never what the model reads about a decided one + expect(fns.orderState).toBeDefined(); + expect(fns.orderState).toEqual(app.orderState); + }); + + it("GenClass.init({ scope }) passes through", () => { + const rt = GenClass.init({ scope: "functions", model: false, report: "silent", telemetry: false }) as RuntimeImpl; + expect(rt.scope).toBe("functions"); + }); +}); From d09641e86ac173bd1baef1e3fa3ee2012b605a1e Mon Sep 17 00:00:00 2001 From: Karan Date: Sat, 10 Oct 2026 00:23:26 -0400 Subject: [PATCH 2/5] docs: two ways in (one line / protect()), your dashboard, tokens in TELEMETRY/PRIVACY/CHANGELOG beta.4 READMEs (root, package, alias): Easy (one line) and Function-specific (protect + scope "functions") quickstarts and a "Your dashboard" section; init's token flags. TELEMETRY.md: envelope token, decision fn, who sees dashboard data. PRIVACY.md: dashboards for site owners, 90-day retention. CHANGELOG beta.4, API.md, agent docs (public API, telemetry, new dashboard-projects.md), OPEN_TASKS (per-function mode not done). Test: attribution after await. Co-Authored-By: Claude Opus 5.5 --- OPEN_TASKS.md | 15 ++ PRIVACY.md | 18 +- README.md | 64 ++++++- docs/agents/README.md | 1 + docs/agents/dashboard-projects.md | 76 ++++++++ .../runtime/public-api-and-lifecycle.md | 39 +++- docs/agents/telemetry.md | 12 +- docs/runtime/API.md | 31 ++++ packages/genclass-runtime/README.md | 15 +- packages/runtime/CHANGELOG.md | 34 ++++ packages/runtime/README.md | 171 ++++++++++++++++-- packages/runtime/TELEMETRY.md | 26 ++- packages/runtime/test/bundle.test.ts | 4 +- packages/runtime/test/projects.test.ts | 19 ++ 14 files changed, 484 insertions(+), 41 deletions(-) create mode 100644 docs/agents/dashboard-projects.md diff --git a/OPEN_TASKS.md b/OPEN_TASKS.md index 54958af7..b736bd14 100644 --- a/OPEN_TASKS.md +++ b/OPEN_TASKS.md @@ -123,6 +123,21 @@ Mehar operates the Azure cluster; nobody else touches Azure. The jobs below run ## Next +- **Review `feat/projects`** (local, 2026-10-10): app tokens (`InitOptions.token`, envelope `token`), `protect()`, + `scope: "functions"`, `Decision.fn`, and `init` creating a project at genclass.dev + ([docs/agents/dashboard-projects.md](docs/agents/dashboard-projects.md)). Open: + - **Per-function mode** (`protect(name, fn, { mode })`) not implemented: `OpRec.scope` (route scope, demote only) + is snapshotted per request from its URL and route, not inherited through the cause chain, so a protected call's + requests would need to inherit a scope from the task op first (`RuntimeImpl.startOp` -> `defaultScope`, + `scopeOf`, and every `op.scope` reader: `effectiveMode`, `blockOf`, `runDelivery`). Promotion above the session + mode (e.g. guard only inside checkout while the app observes) would also contradict "URL/route overrides only + demote"; decide the semantics first. + - The collector on this branch drops unknown top-level fields, so `token` reaches dashboards only with the + server-side work in `telemetry-worker/` (separate workstream). Check end to end before publishing. + - No introspection of protected functions (`runtime.functions()`); add only if the dashboard or devtools need it. + - `init` creates the project before showing the diff (so the diff shows the real token); a declined run prints + the link and writes nothing, so it can leave an unused project on the server. + - **Review `feat/one-line`** (local, 2026-10-10): automatic state discovery for the one line (React, Redux/RTK, Zustand devtools; observed-only store kind). Then: Vue 3 + Pinia discovery (`__VUE_DEVTOOLS_GLOBAL_HOOK__` / pinia `$subscribe`; not started, `autoState.pinia` is accepted and ignored); exact attribution for diff --git a/PRIVACY.md b/PRIVACY.md index c8a5daa9..81253d66 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -1,6 +1,6 @@ # GenClass Runtime: privacy policy -_Last updated: 2026-10-09._ +_Last updated: 2026-10-10._ This policy covers the diagnostics that `@genclass/runtime` (from `0.1.0-beta.3`) sends to its maintainers. It does not cover the website or app that uses GenClass; that site has its own privacy policy. @@ -23,19 +23,29 @@ When a website runs GenClass with telemetry on (the default), the browser sends - **Technical details:** GenClass and model versions, settings, device type (WebGPU or WASM), load times and error counts, and the website's hostname. - **Your approximate country**, from our server provider. +- **The website's GenClass token**, if the site set one. It tells us which website the data came from, so that + website's owner can see it on their dashboard. We do **not** store IP addresses, browser user-agent strings or cookies, and we do not set cookies. Each page load gets a random session ID that is not saved anywhere. ## Why we collect it -To measure how well the model works and to train better versions of it. We do not sell the data, use it for -advertising, or try to identify individual people. +To measure how well the model works and to train better versions of it, and to show website owners how GenClass +works on their own site. We do not sell the data, use it for advertising, or try to identify individual people. + +## Dashboards for website owners + +A website owner can get a private dashboard link for their site's token. Whoever holds that link can see aggregated +diagnostics for that site (counts of decisions, detections and actions, routes, model speed, versions) and its +recent detections, which may include the situation text described above. Data from browsers that opted out or send +Global Privacy Control never reaches a dashboard. ## Where it goes and how long we keep it Data is sent to our collector on Cloudflare and stored in Cloudflare R2. It is deleted automatically after -**90 days**. Only GenClass maintainers can access it. Cloudflare processes it on our behalf. +**90 days**; dashboard data is deleted after 90 days too. Only GenClass maintainers can access the stored data, and +the owner of a website's dashboard link can see that website's dashboard. Cloudflare processes it on our behalf. ## How to turn it off diff --git a/README.md b/README.md index a66e73d9..89e977dd 100644 --- a/README.md +++ b/README.md @@ -7,20 +7,70 @@ **A runtime for web apps. It watches the app from the inside and uses a small local model to flag, and optionally prevent, stale responses, races, duplicate requests, inconsistent state and failure storms.** -One line, first in `` or first in your entry file: +There are two ways to use it. + +### Easy: one line, the whole app + +```bash +npx @genclass/runtime init # finds your framework, adds the line, creates your app's token and dashboard link +``` + +or by hand, first in ``: ```html - + ``` +or first in your entry file (after `npm install @genclass/runtime`; the token goes in a +`` tag or `window.GENCLASS_CONFIG = { token: "gc_..." }`, and `init` +writes it for you): + ```ts -import "@genclass/runtime/auto"; // after npm install @genclass/runtime +import "@genclass/runtime/auto"; ``` That covers the whole app: network, user actions, errors, timing, and the app's state (React component state, Redux / Redux Toolkit and Zustand `devtools` stores are discovered automatically; discovered React and Zustand state -is observed only). Observe mode by default: it reports only. `npx @genclass/runtime init` writes the line for you; -`GenClass.init()` is the explicit setup ([package README](packages/runtime/README.md#automatic-state-discovery)). +is observed only). Observe mode by default: it reports only. + +### Function-specific: only the functions you choose + +```ts +import { GenClass, protect } from "@genclass/runtime"; + +GenClass.init({ token: "gc_your_app_token", scope: "functions" }); + +// a checkout submit: what GenClass finds here (a double submit, overlapping calls, a failure) is reported +// under "checkout submit" +export const submitOrder = protect("checkout submit", async (cart) => { + const res = await fetch("/api/orders", { method: "POST", body: JSON.stringify(cart) }); + if (!res.ok) throw new Error(`order failed: ${res.status}`); + return res.json(); +}); + +// a search box: an out-of-order response, for example, is reported under "search" +export const search = protect("search", (q) => fetch(`/api/search?q=${encodeURIComponent(q)}`).then((r) => r.json())); +``` + +`protect(name, fn)` returns a function with the same signature (same `this`, arguments, return value and errors; +a sync function stays sync). With `scope: "functions"` GenClass still records the rest of the app as context, but it +only makes decisions about what the protected functions cause. Without a runtime, a protected function just calls +`fn`. Details: [package README](packages/runtime/README.md#function-specific-protect). + +### Your dashboard + +Each web app gets a **token** (`gc_` plus 22 letters and digits) and a private **dashboard link** +(`https://genclass.dev/dashboard/...`). `npx @genclass/runtime init` creates both, writes the token into your app, +prints the link and saves it in `.genclass.local` (added to `.gitignore`). Or click "Get a token" at +[genclass.dev/start](https://genclass.dev/start). + +- The token is public: it ships in your page and only lets your app's diagnostics be grouped together. +- **The dashboard link is the key.** Anyone with it sees your app's stats, and it is the only way to open them. + Keep it private. +- It shows decisions, detections by diagnosis, actions taken, top routes and protected functions, model load, + backend and latency, runtime and model versions, and recent detections. +- It gets data only while telemetry is on. Visitors who opt out or send Global Privacy Control are not counted. + Data is kept for 90 days. GenClass Runtime records what the app does: user actions, async operations and their causal chains, network traffic (fetch, XHR, WebSocket, EventSource), store writes with per-field versions, errors and timing. It computes @@ -113,6 +163,8 @@ which available action is best. There is no list of known bugs in the code. stores no IP address or user agent. One console notice per page says it is on. - **Opt out:** `GenClass.init({ telemetry: false })`, `?genclass=no-telemetry`, `localStorage.setItem("genclass.telemetry", "off")`; browsers sending Global Privacy Control are never collected. +- **With a token**, the same diagnostics are also grouped under your app's private dashboard, which whoever holds + its link can open. Without telemetry, a token does nothing. - Apps that ship GenClass may need to disclose this to their users (GDPR/CCPA). Full schema, storage and guidance: [packages/runtime/TELEMETRY.md](packages/runtime/TELEMETRY.md). @@ -165,7 +217,7 @@ NODE_OPTIONS=--expose-gc npx vitest run test/review-perf.test.ts --retry=2 # t The same steps run in CI ([.github/workflows/ci.yml](.github/workflows/ci.yml), Node 22) on pushes to `main`, `runtime`, `mvp` and `mvp-v2`, on pull requests, and on manual dispatch. -Last full local run (2026-10-09, branch `mvp-v2-b6`, version `0.1.0-beta.4`): 514 tests passed and 14 skipped, plus +Last full local run (2026-10-10, branch `feat/projects`, version `0.1.0-beta.4`): 584 tests passed and 14 skipped, plus the 4 perf tests run alone. The skips are model-parity tests, which need `GENCLASS_MODEL_DIR`. The perf tests time a 5,000-item store and can fail under parallel load. diff --git a/docs/agents/README.md b/docs/agents/README.md index 0be1da73..d95949bb 100644 --- a/docs/agents/README.md +++ b/docs/agents/README.md @@ -52,6 +52,7 @@ Each row names the doc to read, and then any further docs to check. "Ask first" | Understand or change the default mode (`observe` since f3636b2) | [runtime/public-api-and-lifecycle.md](runtime/public-api-and-lifecycle.md) | [runtime/devtools.md](runtime/devtools.md) (mode labels), [runtime/build-test-release.md](runtime/build-test-release.md) (`setup()` passes `guard`) | | Add a `Runtime` method or event | [runtime/public-api-and-lifecycle.md](runtime/public-api-and-lifecycle.md) | [runtime/devtools.md](runtime/devtools.md) (`MockRuntime`), [demos.md](demos.md) (runtime shim) | | Change telemetry (what is sent, defaults, opt-outs, the collector in `telemetry-worker/`) or any privacy claim in a README | [telemetry.md](telemetry.md) | `packages/runtime/TELEMETRY.md`, [runtime/public-api-and-lifecycle.md](runtime/public-api-and-lifecycle.md) | +| Change app tokens, dashboards, `protect()`, `scope: "functions"` or `init`'s project creation | [dashboard-projects.md](dashboard-projects.md) | [telemetry.md](telemetry.md), [runtime/public-api-and-lifecycle.md](runtime/public-api-and-lifecycle.md); server side: `telemetry-worker/` | | Change `GenClass.init`, the kill switch or `destroy()` | [runtime/public-api-and-lifecycle.md](runtime/public-api-and-lifecycle.md) | [runtime/observe-and-trace.md](runtime/observe-and-trace.md) (how globals are restored) | | Write a plugin, custom action or standing question | [runtime/public-api-and-lifecycle.md](runtime/public-api-and-lifecycle.md) (plugin API) | [runtime/decide-policy-actions.md](runtime/decide-policy-actions.md), [model-io-contract.md](model-io-contract.md) (no retrain; quality unmeasured) | | Add code that depends on time (timers, timestamps, ids) | [runtime/public-api-and-lifecycle.md](runtime/public-api-and-lifecycle.md) (`Clock` rules) | [runtime/build-test-release.md](runtime/build-test-release.md) (`FakeClock` tests) | diff --git a/docs/agents/dashboard-projects.md b/docs/agents/dashboard-projects.md new file mode 100644 index 00000000..348518c3 --- /dev/null +++ b/docs/agents/dashboard-projects.md @@ -0,0 +1,76 @@ +# App tokens, projects and dashboards + +> **Scope:** the client side of per-app dashboards: `InitOptions.token`, the telemetry envelope's `token`, `protect()` +> and `InitOptions.scope`, `Decision.fn`, and the `init` CLI's project creation (`packages/runtime/bin/lib/token.mjs`, +> `init.mjs`). The server side (project creation, ingest by token, the dashboard pages) lives in `telemetry-worker/` +> and is built by a separate workstream; this doc only states the contract both sides follow. +> **Read this when:** you touch tokens, dashboards, `protect()`, `scope`, or `init`'s network call. +> **Source of truth:** the code. Verified against branch `feat/projects` (from 126026f), 2026-10-10. If this doc and +> the code disagree, the code wins. + +## TL;DR + +- A **token** identifies one web app: `gc_` + 22 base62 characters (`^gc_[A-Za-z0-9]{22}$`). It is public (it ships + in client code) and only lets data be sent. The **dashboard link** `https://genclass.dev/dashboard/` + (secret = 32 base62) is private; whoever has it sees that app's stats. +- Dashboards only receive data while telemetry is on. Every opt-out and Global Privacy Control still wins; a token + changes nothing about what is collected, only how the collector can group it. +- `protect(name, fn)` is the function-specific way in; `scope: "functions"` limits decisions to protected functions. + Decisions about what a protected call caused carry `fn: name`, also on telemetry `decision` events. + +## The shared contract (do not deviate without the server side) + +| piece | client (this repo, `packages/runtime`) | server (`telemetry-worker/`) | +|---|---|---| +| create a project | `init` -> `POST https://genclass.dev/api/projects`, JSON `{ "name"?: string }` (≤ 80 chars, from package.json `name`) | 201 `{ token, dashboardUrl, name, created }`; CORS open; rate-limited (429). Humans: "Get a token" at https://genclass.dev/start | +| send data | batch envelope (schema `genclass-telemetry/1`) gains optional top-level `token`, only for a valid-format token (`src/telemetry/client.ts` -> `header()`) | endpoint unchanged (`DEFAULT_TELEMETRY_ENDPOINT`); groups batches by `token` | +| function names | `decision` events gain optional `fn` (outermost protected function in the subject op's cause chain, ≤ 80 chars) | shown as "top functions" | +| retention | n/a | dashboard data deleted after 90 days | + +Note: the collector on this branch (`telemetry-worker/src/index.ts` at 126026f) keeps only known top-level fields, so +it drops `token` until the server-side work lands. Do not edit `telemetry-worker/` from this workstream. + +## Files + +| file | what | +|---|---| +| `packages/runtime/src/token.ts` | `TOKEN_PATTERN`, `isValidToken`, `resolveToken` (malformed: one warning, ignored) | +| `packages/runtime/src/index.ts` | `createRuntime` resolves the token and passes it to `startTelemetry`; debug-only info line when telemetry is off; `GenClass.protect`; `setProtectResolver(() => current)` | +| `packages/runtime/src/telemetry/*` | `TelemetryConfig.token`, envelope `token`, `TelemetryClient.token`, `fn` on decision events | +| `packages/runtime/src/protect.ts` | `protect(name, fn)`, `setProtectResolver` (internal) | +| `packages/runtime/src/runtime.ts` | `RuntimeImpl.scope`, `runProtected`, `protectedFnOf`; the `scope` gate in `trigger()` and `runDelivery()`; `Decision.fn` in `onDecision` | +| `packages/runtime/src/cdn/config.ts`, `src/cdn/global.ts` | `token=` / `scope=` page-config keys (meta, `data-token`, `data-scope`); `window.GenClass.protect` | +| `packages/runtime/bin/lib/token.mjs` | `createProject` (10 s timeout, never rejects), `readLocal` / `saveLocal` (`.genclass.local`, `.gitignore`), `tokenInFiles` | +| `packages/runtime/bin/lib/init.mjs` | `chooseToken`, `tokenRow`, `dashboardNotice`; flags `--token`, `--no-token` | +| `packages/runtime/bin/lib/edit.mjs` | `token` in `configLiteral`, `updateConfigText`, `metaContent`, `tagWithConfig`, `switchMetaConfig`, `isEmptyConfig` | +| `packages/runtime/test/projects.test.ts` | runtime side (16 tests) | +| `packages/runtime/test/install/cli.test.ts`, `test/install/mock-fetch.mjs` | CLI side; every CLI run in the tests preloads a fake `fetch` (default: offline), so no test calls genclass.dev | + +## CLI behaviour (`init`) + +Order in `chooseToken`: `--no-telemetry` -> none; `--no-token` -> none; `--token` (validated at parse time; usage +error with `--no-token` or `--no-telemetry`) -> that token, no network; a token already in init's marked files -> +reuse, write nothing; `.genclass.local` -> reuse, write it into the setup; telemetry off in the existing setup -> none; +`--dry-run` -> none, no network; else create a project. A hand-written setup (GenClass imported without init's +markers) gets no token. The project is created before the diff is shown; `.genclass.local` is written only after +the changes are applied. If the user declines, the link is printed with "Nothing was written" and the +`init --token` command to use later. `remove` never deletes `.genclass.local` (the only copy of the link). + +## Invariants and gotchas + +- The token never reaches `RuntimeImpl`, situations or the model; `fn` is not model-visible (it is set on the + `Decision` after the model answered). The op name of a protected call is model-visible like any `runtime.op` name. +- `scope: "functions"` must not change the situation text format (`situation-v2.x` is frozen): it only returns the + passive action earlier. `projects.test.ts` checks the same subject gets an identical state under both scopes. +- `protect()` must never throw on its own and must keep sync functions sync; it resolves the runtime per call so it + can wrap at import time. With the script tag, apps must use `window.GenClass.protect` (an npm copy has its own + `GenClass.runtime`). +- Attribution is the runtime's normal best-effort causality (`trace/context.ts`): requests started inside the call or + in continuations of its own observed requests and timers count; work started from unrelated callbacks does not. + Code right after an awaited protected call, in the same task, is attributed to it too (as with `runtime.op`). + +## Open + +- Per-function mode (`protect(name, fn, { mode })`) is not implemented: route scopes are snapshotted per request and + not inherited through the cause chain (`OPEN_TASKS.md`). +- `protect()`ed functions are not listed in an introspection API (no `runtime.functions()`). diff --git a/docs/agents/runtime/public-api-and-lifecycle.md b/docs/agents/runtime/public-api-and-lifecycle.md index 6165cef2..ae9e5b52 100644 --- a/docs/agents/runtime/public-api-and-lifecycle.md +++ b/docs/agents/runtime/public-api-and-lifecycle.md @@ -2,7 +2,7 @@ > **Scope:** `packages/runtime/src/index.ts`, `packages/runtime/src/runtime.ts` (wiring, construction, init/destroy, modes, kill switch, option resolution, events, plugins, introspection, settled points, the delivery gate and background write observation as seen from the facade), `packages/runtime/src/types.ts`, `packages/runtime/src/errors.ts`, `packages/runtime/src/clock.ts`, `packages/runtime/src/util.ts`, `packages/runtime/package.json`; the consumer-facing side of the zero-code entries (`packages/runtime/src/auto.ts`, `packages/runtime/src/cdn/*`, `packages/runtime/bin/genclass-runtime.mjs` `init`/`remove`); their internals (framework detection, edit planning, the CDN worker and onnxruntime bundling) belong to INSTALL and are only summarised here. > **Read this when:** you add or change an init option, a `Runtime` method, an event, a plugin hook or a subpath export; you touch `GenClass.init` / `createRuntime` / the kill switch / `destroy()`; you touch `@genclass/runtime/auto*`, the script-tag global (`window.GenClass`) or `genclass-runtime init|remove`; you need the exact default of any option (the default mode is `observe`); you add timing or scheduling code; you wire a new subsystem into `RuntimeImpl`. -> **Source of truth:** the code. Automatic state discovery (`autoState`, `stores()`, `@genclass/runtime/discover`) verified against branch `feat/one-line` (from 89237ab), 2026-10-10. The rest verified against branch `mvp-v2-merge` (mvp-v2 + origin/runtime eff18cb + observe/redaction fixes 054da38, f107013), 2026-10-08. origin/runtime has since moved past eff18cb (ca08174..5bc40c9: realapps wave 4, runtime batch 6 with model-provided gate thresholds, tag `situation-v2.1`); none of that is merged here or described in this doc. If this doc and the code disagree, the code wins. +> **Source of truth:** the code. App tokens, `protect()` and `scope` verified against branch `feat/projects` (from 126026f), 2026-10-10. Automatic state discovery (`autoState`, `stores()`, `@genclass/runtime/discover`) verified against branch `feat/one-line` (from 89237ab), 2026-10-10. The rest verified against branch `mvp-v2-merge` (mvp-v2 + origin/runtime eff18cb + observe/redaction fixes 054da38, f107013), 2026-10-08. origin/runtime has since moved past eff18cb (ca08174..5bc40c9: realapps wave 4, runtime batch 6 with model-provided gate thresholds, tag `situation-v2.1`); none of that is merged here or described in this doc. If this doc and the code disagree, the code wins. ## TL;DR @@ -105,6 +105,8 @@ ESM only (`"type": "module"`, only `import` conditions; the script-tag build is | `BUILTIN_ACTIONS`, `TRIGGER_ACTIONS` (now with `delivery: ["deliver", "discard", "defer"]`), `PASSIVE` (`delivery: "deliver"`), `DEFAULT_DIAGNOSES` | question vocabulary | `src/situation/questions.ts` | | `describeElement` | DOM element -> `'button "Place order"'` | `src/observe/dom-user.ts` | | `RuntimeImpl` | class (advanced; exposes internals) | `src/runtime.ts` | +| `protect(name, fn)` (also `GenClass.protect`) | function wrapper (feat/projects) | `src/protect.ts` | +| `TOKEN_PATTERN` (`/^gc_[A-Za-z0-9]{22}$/`), `isValidToken(v)` | app token format | `src/token.ts` | Not exported from the root: `util.ts` helpers, `normalizeError`, `policyConfig`/`holdBudget`/`gate`, `COMPACT_QUESTIONS_BUDGET` (1400), `TRIGGER_DESCRIPTIONS` and `ACTION_INSTRUCTIONS` (`situation/questions.ts`). The root export list itself did not change in batch 4/5 (the only `index.ts` change is `eventsource` in `ALL_OFF`), nor with the zero-code entries (`index.ts` and `types.ts` are unchanged since b435acb). @@ -124,7 +126,7 @@ Owner: INSTALL (f3a9dd1, merged from origin/runtime). Not in npm `0.1.0-alpha.1` Note the order: for `/auto/` the mode in the import path is the **lowest** precedence, so a `` or `GENCLASS_CONFIG` mode overrides it; for the script tag the meta tag is below the data attributes. The URL / localStorage kill switch (`?genclass=off|observe|guard|heal`) still beats everything inside `GenClass.init`. -Pair keys (`fromPairs`; unknown keys and invalid values are ignored): `mode` (`observe|guard|heal`), `model` (`off`/`false`/`0`/`no`/`none` -> `model: false`; bare/`true` -> defaults; anything else -> `model.baseUrl`), `modelurl` / `baseurl`, `device` (`auto|webgpu|wasm`), `preload` (`eager|idle|lazy`), `ort` / `ortwasmpaths` (-> `model.ortWasmPaths`), `worker` (false only for an "off" word), `report` (`console|silent`), `debug`, `triage` (`salient|always`), `devtools`. `devtools` (`DevtoolsSetting`): bare/`true` -> always; `local`/`dev`/`localhost` -> only when `isLocalHost(location)` (loopback, `*.localhost`, `*.local`, `*.test`, `file:`); a corner (`bottom-right`, `bottom-left`, `top-right`, `top-left`) -> `{ position }`; an "off" word -> not mounted. `devtools` is split off (`splitConfig`) and never reaches `GenClass.init`. +Pair keys (`fromPairs`; unknown keys and invalid values are ignored): `token` (any non-empty value; validated later by `createRuntime`), `scope` (`app|functions`), `mode` (`observe|guard|heal`), `model` (`off`/`false`/`0`/`no`/`none` -> `model: false`; bare/`true` -> defaults; anything else -> `model.baseUrl`), `modelurl` / `baseurl`, `device` (`auto|webgpu|wasm`), `preload` (`eager|idle|lazy`), `ort` / `ortwasmpaths` (-> `model.ortWasmPaths`), `worker` (false only for an "off" word), `report` (`console|silent`), `debug`, `triage` (`salient|always`), `devtools`. `devtools` (`DevtoolsSetting`): bare/`true` -> always; `local`/`dev`/`localhost` -> only when `isLocalHost(location)` (loopback, `*.localhost`, `*.local`, `*.test`, `file:`); a corner (`bottom-right`, `bottom-left`, `top-right`, `top-left`) -> `{ position }`; an "off" word -> not mounted. `devtools` is split off (`splitConfig`) and never reaches `GenClass.init`. **`@genclass/runtime/auto`, `/auto/`** (`src/auto.ts`, `src/cdn/auto-*.ts` -> `startAuto(defaults)`): 1. Not a browser (`window` or `document` not an object): return `GenClass.init(defaults)` (the non-browser branch: no observers, no model; meta and window config are not read). @@ -132,7 +134,7 @@ Pair keys (`fromPairs`; unknown keys and invalid values are ignored): `mode` (`o 3. Default export: that `Runtime` (`import rt from "@genclass/runtime/auto"`); named export `GenClass`. Runs at module evaluation, so it must be the first import of the entry for stores created at import time to see `GenClass.runtime`. The bare `/auto` has no mode default: it runs in `observe`. **Script tag** (`src/cdn/global.ts`, built to `dist/genclass.global.js` / `.min.js`; `install()` runs at evaluation when `window` and `document` exist): -- Installs `window.GenClass: GenClassGlobal` = `{ version, base, init(options?), runtime (getter), destroy(), devtools(options?), createRuntime, GenClassUnavailableError }`. This is **not** the module `GenClass` object: `init` merges the page configuration under `options`, adds the CDN model wiring and mounts devtools; `destroy` also unmounts the overlay; `devtools()` mounts it (initialising first if needed). A second copy of the tag keeps the first global (`__genclassGlobal` flag). +- Installs `window.GenClass: GenClassGlobal` = `{ version, base, init(options?), runtime (getter), destroy(), devtools(options?), createRuntime, protect, GenClassUnavailableError }`. This is **not** the module `GenClass` object: `init` merges the page configuration under `options`, adds the CDN model wiring and mounts devtools; `destroy` also unmounts the overlay; `devtools()` mounts it (initialising first if needed). A second copy of the tag keeps the first global (`__genclassGlobal` flag). - Auto-init: `api.init()` at once unless `data-manual` is present (and not `"false"`); a throw is caught and warned. - `base` (where everything else loads from): `data-base` (resolved, trailing `/` added), else `assetBase(script.src)`: on jsDelivr/unpkg the URL is re-pinned to `@/dist/` (so `@latest` never mixes releases), else the script's directory; fallback `https://cdn.jsdelivr.net/npm/@genclass/runtime@/dist/`. The script element is `document.currentScript`, else the last `script[src]` whose URL looks like this file. - Model wiring (`withCdnModel`, skipped when `decider` is set or `model === false`): host options `workerFactory` (a module Worker from a same-origin Blob URL that imports `cdn/worker.js`, since browsers refuse cross-origin worker URLs) and `ortLoader` (`cdn/ort-webgpu.js` / `ort-wasm.js`), with the caller's `model` fields spread over them. These are `ModelHostOptions` fields (`model/host.ts`), passed through `ModelOptions` by a cast; they are not in the public `ModelOptions` type. Model weights still come from `DEFAULT_MODEL_BASE_URL` unless `model`/`data-model` says otherwise. @@ -141,6 +143,7 @@ Pair keys (`fromPairs`; unknown keys and invalid values are ignored): `mode` (`o **CLI `init` / `remove`** (`bin/lib/init.mjs` -> `run`; consumer view only): - `init` detects the package manager and framework (`detect.mjs`), installs `@genclass/runtime` (unless `--no-install`; `--from ` picks the spec), and adds, as the first statement of the entry file, `import ""` (with devtools: `import genclass from ""` plus a dev-only `if () import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass))` at the end). Plain HTML gets a script tag (`plan.mjs` -> `scriptTag`: jsDelivr URL pinned to the CLI's own version unless `--cdn`; an `integrity` sha384 of the package's local `dist/genclass.global(.min).js` when that file exists, unless `--no-sri`; `data-mode` when a mode other than `guard` is given; `data-devtools="local"` unless `--no-devtools`). It shows the diff and asks unless `--yes`; `--dry-run` writes nothing; running it twice changes nothing. - Every added line or created file carries the marker `genclass:init` (`edit.mjs` -> `MARK`), except the inline forms used when the insertion point shares its line with other code (a one-line `` or ``), marked `genclass:inline` (`MARK_INLINE`); `remove` deletes exactly the marked lines/blocks/inline forms and uninstalls the package unless `--keep-package` or `--no-install` (or something else still uses it). +- Token (feat/projects; `bin/lib/token.mjs`, `init.mjs` -> `chooseToken`, `tokenRow`, `dashboardNotice`): by default `init` POSTs `https://genclass.dev/api/projects` (`{ name }` from package.json) and writes the token into its config (`genclass.config.*` -> `GENCLASS_CONFIG.token`, `data-token`, Astro meta `token=`), prints the dashboard link and, after the changes are applied, saves `.genclass.local` (and appends it to an existing `.gitignore`). No network with `--token`, `--no-token`, `--no-telemetry`, `--dry-run`, a token already in the marked files, or one in `.genclass.local`. Failure -> warning, no token. Details: [../dashboard-projects.md](../dashboard-projects.md). - Mode mapping (`plan.mjs` -> `AUTO`): `observe` -> `/auto/observe`, `heal` -> `/auto/heal`, `guard` **or no `--mode`** -> plain `/auto`. On this branch plain `/auto` runs in `observe`, so `init --mode guard` currently produces an observe-mode install, and the CLI's help/summary still call `guard` the default. See Drift. **Automatic state discovery (branch `feat/one-line`, ships in `0.1.0-beta.4`).** `InitOptions.autoState?: boolean | @@ -159,6 +162,33 @@ StoreInfo[]` (`{ name, kind: "atom"|"guard"|"adapter"|"observed", source?, writa `RuntimeImpl.discoveryStats()` (React walk stats, Redux/connected store names); `decisionInfo().autoState` (telemetry marks the decision event `autoState: true`; the situation text is sent as usual). +**App tokens, `protect()` and `scope` (branch `feat/projects`, ships in `0.1.0-beta.4`).** Server side and the CLI +flow: [../dashboard-projects.md](../dashboard-projects.md). +- `InitOptions.token?: string`: `index.ts` -> `createRuntime` runs `token.ts` -> `resolveToken` (trim; malformed -> + one `console.warn` on the runtime global's console, ignored; never throws) and passes it to + `telemetry/index.ts` -> `startTelemetry(..., token)`, which sets `TelemetryConfig.token`; `client.ts` -> `header()` + writes it as the envelope's first field after `schema`; `TelemetryStatus.token` exposes it. With a token but + telemetry off and `debug: true`, `createRuntime` logs one `console.info`. The token never reaches `RuntimeImpl`, + situations or the model. +- `protect(name, fn)` (`src/protect.ts`): resolves the runtime on every call through `setProtectResolver` (set by + `index.ts` to `GenClass.runtime` when it is a `RuntimeImpl`; tests point it at their own runtime). No runtime -> + `fn.apply(this, args)`. Else `RuntimeImpl.runProtected(name, fn, this, args)`: `startOp("task", name)` with + `OpRec.fn = name`, `ctx.run(op, ...)`; a sync throw ends the op `"error"` and rethrows; a native `Promise` result + is replaced by `r.then(...)` that ends the op and `ctx.stick`s it (like `op()`), so unhandled-rejection behaviour + is unchanged; any other value or thenable ends the op at once and is returned untouched (never `.then()`-ed). Names + are trimmed and cut to 80 chars; `name`/`length` of `fn` are copied. Unlike `op()` it never turns a sync function + async. +- `RuntimeImpl.protectedFnOf(op)`: walks `op.cause` through `ops.get` (≤ 256 steps) and returns the outermost + `fn`. `trigger()` computes it for `subjectOpOf(spec)` (or the ambient op without materializing a lazy timer op) and + passes it to `onDecision`, which sets `Decision.fn`; `client.ts` sends it as `fn` on `decision` events. +- `InitOptions.scope?: "app" | "functions"` -> `RuntimeImpl.scope`. `"functions"`: `trigger()` returns the passive + action before triage when `fn` is undefined (except `ask`), and `runDelivery` releases a delivery at once when its + op has no protected function in its chain. Recording, learning and situation building are unchanged (test: + `test/projects.test.ts`, identical situation state for the same subject under both scopes). +- Not implemented: a per-function mode. Route scopes (`OpRec.scope`) are snapshotted per request from the URL/route + and not inherited through the cause chain, so `protect(name, fn, { mode })` would need that inheritance first + (`OPEN_TASKS.md`). + ### Modes and tiers `Mode = "observe" | "guard" | "heal"`; `Tier = "passive" | "guard" | "heal"` (`types.ts`). The mode-tier rule is `src/decide/policy.ts` -> `modeAllows`: @@ -194,6 +224,8 @@ Defaults below are what `RuntimeImpl`'s constructor applies, unless the row says | `vocabulary` | `Vocabulary` (`{ diagnoses?: Record; actions?: Partial> }`) | `undefined` | `diagnoses` replaces `DEFAULT_DIAGNOSES`; `expected` is always kept (added from the defaults if missing, always first) and plugin labels are added only when the label is not already present (`situation/questions.ts` -> `diagnosisVocabulary`). `actions[name]` overrides the description of a built-in **or custom** action (`situation/questions.ts` -> `actionDescription`: vocabulary, then `ActionDef.description`, then the trigger-specific built-in wording in `TRIGGER_DESCRIPTIONS` (situation-v2: `delivery`'s `deliver`/`discard`/`defer`), then `BUILTIN_ACTIONS[name].description`). The override applies to every trigger an action appears on. Changes model input wording. | | `settleMs` | `number` | `60` | Quiet time before a settled point. | | `situation` | `{ budget?: number \| "auto" }` | `"auto"` | Situation size in characters. A number is used as is (no device sizing, no budget scale). See `situationBudget()`. | +| `token` | `string` | none | App token for the dashboard (`gc_` + 22 base62). Telemetry only: sent on the batch envelope; malformed -> one warning, ignored. See above. | +| `scope` | `"app" \| "functions"` | `"app"` | `"functions"`: decisions only for activity inside `protect()`ed functions (`RuntimeImpl.trigger`, `runDelivery`). | ### `CreateOptions` (`types.ts` -> `CreateOptions extends InitOptions`) @@ -686,6 +718,7 @@ All in `packages/runtime/test/` (vitest, `environment: "node"`, `testTimeout: 20 | test file | what it asserts (scope of this doc) | |---|---| +| `projects.test.ts` (feat/projects, 16 tests) | Token format; token from meta / data attributes / `GENCLASS_CONFIG` / options; envelope `token` (and none without one); malformed token -> one warning; token with telemetry off (debug info line); GPC still wins; `protect()` without a runtime, `this`/args/sync/async/throws/rejections/thenables, `name`/`length`, destroyed runtime; `Decision.fn` and telemetry `fn` (outermost function), attribution after an `await`; `scope: "functions"` decides only protected activity, default scope unchanged, identical situation state for the same subject. CLI token tests are in `test/install/cli.test.ts` (6 tests, fetch mocked by `test/install/mock-fetch.mjs`). | | `default-mode.test.ts` (f3636b2, 054da38) | `createRuntime` and `GenClass.init` without a mode start in `observe`; `mode: "guard"` and `?genclass=guard` opt in; in observe, a sure model (p 0.99) records `delivery`/`mutation`/`request` decisions and detections but nothing is held, `executed` is false and `interventions()` is empty; a model that never answers delays nothing (atom write, adapter propose, fetch, failed fetch) while it is still asked in the background. | | `delivery.test.ts`, `content.test.ts`, `no-reorder.test.ts` (batch 4/5) | The delivery gate (salience, `discard` drop marks and undo, `defer`), body analysis (F1/F2/F3, read-your-writes), and that held writes never reorder a store's writes. Owned by [decide-policy-actions.md](decide-policy-actions.md) / [learn-situation-triage.md](learn-situation-triage.md). | | `observe-delivery.test.ts` (054da38) | Observe: a conflicting fetch response with a slow body resolves at network time and is decided once in the background on the state it was delivered into; an app write before the body is read decides it at that write; F1 is not lost; standing questions on `delivery` are answered; XHR listeners run inside the original dispatch with the body analyzed first; WebSocket/EventSource messages delivered synchronously and in order, still decided. Guard unchanged: stale response held and discarded; a too-slow model releases at once and the write is late-reverted on its own. | diff --git a/docs/agents/telemetry.md b/docs/agents/telemetry.md index fead4598..ee3850d9 100644 --- a/docs/agents/telemetry.md +++ b/docs/agents/telemetry.md @@ -20,6 +20,11 @@ `TELEMETRY.md` + CHANGELOG update. - Telemetry is **read-only** on the runtime and never feeds a decision: it does not touch `src/situation/*` or any model-visible text (rule 2), and a test asserts the model input is byte-identical with and without it. +- **App tokens (branch `feat/projects`):** an optional top-level `token` on the batch envelope (`InitOptions.token`, + validated `^gc_[A-Za-z0-9]{22}$`, only when set and valid) and `fn` on `decision` events (the `protect()`ed + function). They group an app's batches for its private dashboard on genclass.dev; nothing else about what is sent + changed. Server side: `telemetry-worker/` (owned by a separate workstream); agent doc + [dashboard-projects.md](dashboard-projects.md). - Collector: Cloudflare Worker `genclass-telemetry` at `https://genclass-telemetry.mehar-144.workers.dev` (account `144bd5f5270b51dbe7faf46227a154f0`, logged in as mehar@daybot.ca), R2 bucket `genclass-telemetry`. @@ -30,7 +35,8 @@ | `packages/runtime/src/telemetry/config.ts` | `DEFAULT_TELEMETRY_ENDPOINT`, `TELEMETRY_SCHEMA` (`genclass-telemetry/1`), `TELEMETRY_NOTICE`, `resolveTelemetry` (defaults, opt-outs, sampling, session id) | | `packages/runtime/src/telemetry/transport.ts` | `nativeTransport`: `fetch` and `navigator.sendBeacon` captured at module load; text/plain, keepalive, `credentials: "omit"`, `referrerPolicy: "no-referrer"` | | `packages/runtime/src/telemetry/client.ts` | `TelemetryClient`: listeners -> events, queue (`MAX_QUEUE` 1000), batching (`maxBatch`, `MAX_REQUEST_BYTES` 60,000), flush timer on the runtime `Clock`, pagehide / hidden-tab beacon, summaries (`SUMMARY_MS` 60 s), `telemetryOff` | -| `packages/runtime/src/telemetry/index.ts` | `startTelemetry` (called by `createRuntime`), the once-per-page console notice | +| `packages/runtime/src/telemetry/index.ts` | `startTelemetry` (called by `createRuntime`; `token` argument -> `TelemetryConfig.token`), the once-per-page console notice | +| `packages/runtime/src/token.ts` | `TOKEN_PATTERN`, `isValidToken`, `resolveToken` (one warning for a malformed token) | | `packages/runtime/src/version.ts` | `RUNTIME_VERSION` (must equal package.json; a test checks it; bump with every release) | | `packages/runtime/src/runtime.ts` | `RuntimeTap` / `RuntimeImpl.tap` (model errors, fail-opens: `not-ready`, `no-answer`, `error`), `decisionInfo(id)` (situation text, held, budget, compact, gates, `autoState`: discovered state recorded; `client.ts` sends the situation text as usual and marks the event `autoState: true`), `addTeardown(fn)` (final flush on destroy), `ExplainRec.held/budget/compact` | | `packages/runtime/src/index.ts` | `createRuntime` -> `startTelemetry(rt, options.telemetry, false, info)`; `GenClass.init` browser branch sets `telemetry: options.telemetry ?? true`; the `?genclass=off` kill switch -> `telemetryOff("kill-switch")` | @@ -46,6 +52,8 @@ browser (`headless`) -> `?genclass=no-telemetry|off` (any `genclass` URL value) -> `localStorage["genclass.telemetry"] === "off"` -> `navigator.globalPrivacyControl === true` (`gpc`) -> no `crypto.getRandomValues` (`no-crypto`; never `Math.random`) -> `sample` draw (`sampled-out`) -> no transport. `enabled: false` in `createRuntime` -> `disabled`. +- **Envelope:** `{ schema, token?, sid, sent, runtime, model, events }` (`client.ts` -> `header()`); `token` only + when `TelemetryConfig.token` is set. - **Session id:** 12 random bytes as 24 hex chars, per page load, never stored. Times are ms since the client started (`rt.clock`); the collector adds `receivedAt`. - **Events** (`t`): `session`, `model`, `status`, `decision`, `detect`, `action` (`applied` / `failed` / `undone`, @@ -90,4 +98,4 @@ would send telemetry when run; they were left unchanged (honest-evaluation separation for demos). Add `?genclass=no-telemetry` or `telemetry: false` there if those runs should not reach the collector. - `sendBeacon` sends the page's `Referer` per the document's policy (cannot be turned off); the collector ignores it. -- The `init` CLI does not mention telemetry in its output yet. +- The `init` CLI prints a telemetry notice and, since `feat/projects`, the token and the dashboard link. diff --git a/docs/runtime/API.md b/docs/runtime/API.md index 2a85df5b..7aa21317 100644 --- a/docs/runtime/API.md +++ b/docs/runtime/API.md @@ -23,6 +23,12 @@ Contents: [init and modes](#init-and-modes) · [options](#options) · [state](#s GenClass.init(options?: InitOptions): Runtime // idempotent: a second call returns the same runtime GenClass.runtime: Runtime | null GenClass.destroy(): void // uninstall observers, restore globals, terminate the model worker +GenClass.protect: typeof protect // the same as the named export below + +// named exports +protect unknown>(name: string, fn: F): F // see "Protected functions" +TOKEN_PATTERN: RegExp // /^gc_[A-Za-z0-9]{22}$/ +isValidToken(v: unknown): v is string ``` | mode | what it does | @@ -46,6 +52,11 @@ no model. Use [`createRuntime`](#headless-use-tests-ssr-simulation) for headless Control; off by default outside a browser and in `createRuntime()`. Schema and details: [packages/runtime/TELEMETRY.md](../../packages/runtime/TELEMETRY.md). +**App token and dashboard.** `token: "gc_..."` (from `npx @genclass/runtime init` or https://genclass.dev/start) is +sent with each telemetry batch so the app's diagnostics show up on its private dashboard +(`https://genclass.dev/dashboard/`). Public; malformed values log one warning and are ignored; it does nothing +while telemetry is off. `rt.telemetry.token` reports it. + ## Options ```ts @@ -83,6 +94,8 @@ interface InitOptions { autoState?: boolean | { react?: boolean; redux?: boolean; zustand?: boolean; pinia?: boolean }; // automatic state discovery: default on in @genclass/runtime/auto* and the script tag, // off in GenClass.init / createRuntime (there it needs import "@genclass/runtime/discover" first) + token?: string; // app token, gc_ + 22 letters/digits: groups telemetry under your private dashboard + scope?: "app" | "functions"; // ["app"]; "functions": decisions only for activity inside protect()ed functions // batch 12 (docs/runtime/OPTIONS-SPEC.md); defaults in brackets enabled?: boolean | (() => boolean | Promise) | { get(): boolean | Promise; subscribe?(cb: () => void): () => void }; @@ -253,6 +266,24 @@ user handler or `rt.op` body runs, after a fetch/XHR settles and when its body ( and inside timers scheduled during an operation; it is cleared at the end of the task. Writes record the ambient operation as their cause; operations started while another is ambient get it as their parent. +### Protected functions + +```ts +import { GenClass, protect } from "@genclass/runtime"; +GenClass.init({ token: "gc_...", scope: "functions" }); + +const submitOrder = protect("checkout submit", async (cart: Cart) => { /* fetch, writes, ... */ }); +``` + +`protect(name, fn)` returns a function with `fn`'s signature. Each call runs as a `"task"` operation named `name` +(like `rt.op`), so what it starts is linked to it, and decisions about that carry `Decision.fn = name` (the +outermost protected function when they nest; also `fn` on telemetry `decision` events). `this`, arguments, return +value and thrown errors pass through; a sync function stays sync; an async function's promise is replaced by one +that settles the same way; other thenables are returned untouched. It looks up `GenClass.runtime` on every call and +calls `fn` directly when there is none. It never throws on its own. With `scope: "functions"` everything is still +recorded, but decisions are raised only for subjects inside a protected call. There is no per-function `mode` +option yet. + ## Asking the model ```ts diff --git a/packages/genclass-runtime/README.md b/packages/genclass-runtime/README.md index 5eca7d6b..97bf6f27 100644 --- a/packages/genclass-runtime/README.md +++ b/packages/genclass-runtime/README.md @@ -7,8 +7,19 @@ npx genclass-runtime init ``` It does the same as `npx @genclass/runtime init`: it finds your framework, installs `@genclass/runtime`, adds one -line to your entry file and shows you the diff first. Docs: [@genclass/runtime](https://www.npmjs.com/package/@genclass/runtime). +line to your entry file and shows you the diff first. It also creates your app's token and private dashboard link at +genclass.dev, writes the token into what it adds, and saves the link in `.genclass.local` (keep that link private; +it is the only way to open your dashboard). + +```bash +npx genclass-runtime init --token gc_... # use a token you already have (no network) +npx genclass-runtime init --no-token # no token, no network +``` + +Docs: [@genclass/runtime](https://www.npmjs.com/package/@genclass/runtime) (one-line setup, function-specific +`protect()`, your dashboard). Privacy: since `0.1.0-beta.3` the installed runtime sends anonymous diagnostics (GenClass's decisions, including redacted situation text) to the GenClass maintainers by default. Opt out with `GenClass.init({ telemetry: false })` -or `?genclass=no-telemetry`; details in [TELEMETRY.md](https://github.com/daybot-solutions-inc/GenClass-lib/blob/main/packages/runtime/TELEMETRY.md). +or `?genclass=no-telemetry` (`init --no-telemetry` also skips the token); with a token the same diagnostics also feed +your app's private dashboard. Details in [TELEMETRY.md](https://github.com/daybot-solutions-inc/GenClass-lib/blob/main/packages/runtime/TELEMETRY.md). diff --git a/packages/runtime/CHANGELOG.md b/packages/runtime/CHANGELOG.md index e3da8219..9ddc9a9c 100644 --- a/packages/runtime/CHANGELOG.md +++ b/packages/runtime/CHANGELOG.md @@ -2,6 +2,40 @@ ## 0.1.0-beta.4 (unpublished, 2026-10-10) +### App tokens and dashboards; function-specific protection with `protect()` + +Each web app can now have a token that sends its diagnostics to a private dashboard on genclass.dev, and GenClass can +be pointed at a few functions instead of the whole app. No situation text or other model-visible text changes +(`scope: "functions"` changes which subjects are decided, never what the model reads about one). + +- **`InitOptions.token`** (also `data-token`, ``, + `window.GENCLASS_CONFIG.token`): `gc_` + 22 letters or digits (`TOKEN_PATTERN`, `isValidToken` exported). Sent as + the telemetry batch envelope's top-level `token`; `runtime.telemetry.token` reports it. A malformed token logs one + console warning and is ignored; never throws. It does nothing while telemetry is off (with `debug: true` the + console says so once); opt-outs and Global Privacy Control still win. +- **`protect(name, fn)`** (named export, `GenClass.protect`, and `window.GenClass.protect` on the script tag): returns + a function with the same signature whose calls run as an operation named `name` (like `runtime.op`), so the + requests, state writes, timers and errors it causes are linked to it. `this`, arguments, return value and thrown + errors pass through; sync stays sync; an async function's promise is replaced by one that settles the same way; + other thenables are returned untouched. Safe to wrap at import time: without a runtime it calls `fn` directly. +- **`InitOptions.scope`**: `"app"` (default, unchanged) or `"functions"`: decisions only for activity inside + protected functions (gated where triggers are raised and at the delivery gate); everything is still recorded as + context. Also `data-scope` / `scope=` in the meta tag. +- **`Decision.fn`** and **`fn` on telemetry `decision` events**: the outermost protected function in the subject's + cause chain. +- **`init` creates a project**: by default `npx @genclass/runtime init` calls `POST https://genclass.dev/api/projects` + (name from `package.json`), writes the token into what it adds (`genclass.config.*`, `data-token`, or the Astro + meta line), prints the private dashboard link ("keep this link private; it is the only way to open your + dashboard"), and saves both in `.genclass.local` (added to `.gitignore` when there is one; `remove` keeps it). + `--token ` uses an existing token without network, `--no-token` skips it, `--no-telemetry` implies no + token, `--dry-run` never calls the network. A network failure or HTTP error warns, continues without a token and + points to https://genclass.dev/start. Running `init` again reuses the token. +- **Not done:** a per-function mode (`protect(name, fn, { mode })`): route scopes are snapshotted per request, not + inherited through a call's cause chain, so it was left out (OPEN_TASKS.md). +- **Cost:** about +0.9 KB gzip on `/auto` (97.4 KB), the main entry (90.3 KB) and the script-tag file (111.4 KB). +- **Privacy:** TELEMETRY.md ("App tokens and dashboards") and PRIVACY.md ("Dashboards for website owners") describe + the token, the `fn` field and who can see dashboard data (90-day retention). + ### One line covers the whole app (automatic state discovery) `` or `import "@genclass/runtime/auto"` now diff --git a/packages/runtime/README.md b/packages/runtime/README.md index 363f1ff6..b5862fad 100644 --- a/packages/runtime/README.md +++ b/packages/runtime/README.md @@ -16,10 +16,12 @@ WASM, in a Web Worker) answers two questions: what is happening, and which of th runtime has no list of known bugs: triage picks the situations, the model decides. By default it only reports; in `guard` mode it can also stop the failure before your users see it. -**One line covers the whole app.** First in ``: +Two ways to use it: + +**Easy: one line, the whole app.** First in ``: ```html - + ``` or first in your entry file (any bundler; Next.js: `instrumentation-client.ts`): @@ -28,11 +30,33 @@ or first in your entry file (any bundler; Next.js: `instrumentation-client.ts`): import "@genclass/runtime/auto"; ``` -That is the whole setup. Network traffic, user actions, errors and timing are observed, and so is your app's state: -React component state (`useState`, `useReducer`, `useSyncExternalStore`, class state), Redux and Redux Toolkit -stores, and Zustand stores with `devtools` are found automatically, with no store to register -([Automatic state discovery](#automatic-state-discovery)). It starts in observe mode: it reports, and never changes -what your app does (see Known limitations). `npx @genclass/runtime init` writes the line for you. +`npx @genclass/runtime init` writes the line for you, creates your app's token and dashboard link, and puts the +token where the line reads it. That is the whole setup. Network traffic, user actions, errors and timing are +observed, and so is your app's state: React component state (`useState`, `useReducer`, `useSyncExternalStore`, class +state), Redux and Redux Toolkit stores, and Zustand stores with `devtools` are found automatically, with no store to +register ([Automatic state discovery](#automatic-state-discovery)). It starts in observe mode: it reports, and never +changes what your app does (see Known limitations). + +**Function-specific: only the functions you choose.** + +```ts +import { GenClass, protect } from "@genclass/runtime"; + +GenClass.init({ token: "gc_your_app_token", scope: "functions" }); + +export const submitOrder = protect("checkout submit", async (cart) => { + const res = await fetch("/api/orders", { method: "POST", body: JSON.stringify(cart) }); + if (!res.ok) throw new Error(`order failed: ${res.status}`); + return res.json(); +}); +``` + +GenClass then decides only about what `submitOrder` causes (a double submit, overlapping calls, a failure) and +reports it under "checkout submit"; the rest of the app is recorded as context only. +[Function-specific: protect()](#function-specific-protect). + +**Your dashboard.** The token sends your app's diagnostics to a private dashboard at genclass.dev: decisions, +detections, actions, top routes and functions, model load and latency. [Your dashboard](#your-dashboard). > **Privacy notice: anonymous diagnostics are on by default since `0.1.0-beta.3`.** `GenClass.init()` in a browser > sends GenClass's decisions, including the redacted situation text the model read, to the GenClass maintainers to @@ -70,7 +94,8 @@ what your app does (see Known limitations). `npx @genclass/runtime init` writes ## Contents -[Install](#install) · [Automatic state discovery](#automatic-state-discovery) · +[Install](#install) · [Function-specific: protect()](#function-specific-protect) · [Your dashboard](#your-dashboard) · +[Automatic state discovery](#automatic-state-discovery) · [Why it's an easy yes](#why-its-an-easy-yes-measured) · [Modes](#modes) · [What it looks for](#what-it-looks-for) · [State it can protect](#state-it-can-protect) · [Ask it questions](#ask-it-questions) · [Observability](#observability) · [Extend it](#extend-it) · @@ -123,6 +148,28 @@ npx @genclass/runtime remove # undo exactly what init added Other flags: `--no-install`, `--no-devtools`, `--cwd `, `--cdn ` and `--no-sri` (plain HTML), `remove --keep-package`. +**Token and dashboard.** By default `init` also creates a project for your app at genclass.dev (named after +`package.json`'s `name`), writes its token into what it adds, and prints your private dashboard link: + +``` + Your dashboard https://genclass.dev/dashboard/... + Keep this link private; it is the only way to open your dashboard. + Saved in .genclass.local (added to .gitignore). +``` + +The link is saved in `.genclass.local` (with the token), and `.genclass.local` is added to `.gitignore` when the +project has one; `remove` leaves that file alone. Running `init` again reuses the token (no new project). + +```bash +npx @genclass/runtime init --token gc_... # use a token you already have (no network) +npx @genclass/runtime init --no-token # no token, no network +``` + +`--no-telemetry` implies `--no-token` (a dashboard only gets data while telemetry is on). If genclass.dev cannot be +reached, `init` says so, sets GenClass up without a token, and points you to +[genclass.dev/start](https://genclass.dev/start); run `init --token gc_...` later. `--dry-run` never calls the +network. + Options without editing code (also on a project `init` already set up; `remove` takes them out too): ```bash @@ -170,8 +217,9 @@ import "@genclass/runtime/auto/observe"; // observe, explicitly import rt from "@genclass/runtime/auto"; // the same, and the runtime it started ``` -Optional page configuration, read once: `` or -`window.GENCLASS_CONFIG = { mode: "guard", devtools: true }` (any `InitOptions`), set before the import runs. During +Optional page configuration, read once: `` or +`window.GENCLASS_CONFIG = { token: "gc_...", mode: "guard", devtools: true }` (any `InitOptions`), set before the +import runs. During SSR or in Node, `/auto` installs nothing and returns an inert runtime. **3. One script tag** (no build step), first in ``: @@ -180,9 +228,10 @@ SSR or in Node, `/auto` installs nothing and returns an inert runtime. ``` -It exposes `window.GenClass`, discovers the app's state like the import does, and loads the model worker, ONNX -Runtime Web and the overlay on demand from the same version on the CDN. `data-mode` takes `observe` (the default), `guard` or `heal`; `data-devtools="local"` shows the -overlay only on localhost; `data-manual` skips the automatic `GenClass.init()`. Pin a version in production +It exposes `window.GenClass` (with `GenClass.protect`), discovers the app's state like the import does, and loads the model worker, ONNX +Runtime Web and the overlay on demand from the same version on the CDN. `data-mode` takes `observe` (the default), `guard` or `heal`; `data-token="gc_..."` is your app's token; +`data-scope="functions"` limits decisions to protected functions; `data-devtools="local"` shows the overlay only on +localhost; `data-manual` skips the automatic `GenClass.init()`. Pin a version in production (`https://cdn.jsdelivr.net/npm/@genclass/runtime@0.1.0-beta.4`); the plain-HTML path of `init` writes a pinned jsDelivr URL with SRI. @@ -196,7 +245,7 @@ npm install @genclass/runtime // first thing in your entry file import { GenClass } from "@genclass/runtime"; -const rt = GenClass.init(); // observe; GenClass.init({ mode: "guard" }) to let it act +const rt = GenClass.init({ token: "gc_..." }); // observe; add mode: "guard" to let it act ``` `GenClass.init()` does not discover state on its own: register stores ([State it can protect](#state-it-can-protect)), @@ -204,6 +253,85 @@ or import `@genclass/runtime/discover` first and pass `autoState: true`. The unscoped name `genclass-runtime` is not published; use `npx @genclass/runtime`. +## Function-specific: protect() + +Use this when you want GenClass on a few functions that matter (a checkout submit, a search, a save) rather than on +the whole app. + +```ts +import { GenClass, protect } from "@genclass/runtime"; + +GenClass.init({ token: "gc_...", scope: "functions" }); // early, e.g. in your entry file + +// Wrap at module level; calls made before GenClass.init() simply run fn. +export const submitOrder = protect("checkout submit", async (cart: Cart) => { + const res = await fetch("/api/orders", { method: "POST", body: JSON.stringify(cart) }); + if (!res.ok) throw new Error(`order failed: ${res.status}`); + return res.json(); +}); + +export const search = protect("search", async (q: string) => { + const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`); + return (await res.json()) as Result[]; +}); + +class CartStore { + save = protect("cart save", function (this: CartStore, items: Item[]) { + return api.put("/api/cart", items); // `this` is the store, as without protect + }); +} +``` + +What `protect(name, fn)` does: + +- **Same function.** It returns a function with the same signature: `this`, arguments, return value and thrown + errors pass through, and a sync function stays sync. For an `async` function you get a promise that settles + exactly like `fn`'s (it is a new promise object, as with `runtime.op`). Other thenables are returned untouched. + `protect` itself never throws. +- **Each call is tracked.** The call runs as an operation named `name` (the same as `runtime.op(name, fn)`). The + requests, state writes, timers and errors it starts are linked to it, directly or through the causal chain GenClass + already follows (a request started after an `await` on one of the function's own requests counts). Work started + from somewhere else, such as a WebSocket message or another click handler, does not. +- **Decisions name the function.** A decision about something a protected call caused carries `fn: name` + (`rt.on("decide", (d) => d.fn)`, the telemetry `decision` event, and your dashboard). With nested protected + functions, the outermost one is named. +- **No runtime, no cost.** A protected function looks up `GenClass.runtime` on every call. Before `GenClass.init()` + (or after `GenClass.destroy()`) it calls `fn` directly. +- **Also** as `GenClass.protect`, and on the script tag's `window.GenClass.protect`. With the script tag, use + `window.GenClass.protect`: a copy imported from npm would not see the script tag's runtime. + +**`scope: "functions"`** (`InitOptions.scope`; also `data-scope="functions"` / `scope=functions` in the meta tag): +GenClass still observes the whole app and keeps it as context in the situations it builds, but it raises decisions +only for activity inside protected functions. Everything else is never decided, held or acted on. The default, +`scope: "app"`, decides about the whole app as before; `protect()` then only adds the function names. The mode still +applies: in `observe` (the default) GenClass reports, in `guard` it may act on what protected functions cause. + +A per-function mode (`protect(name, fn, { mode })`) does not exist yet: use `routes` or `requests.protect` to narrow +where GenClass acts. + +## Your dashboard + +Each web app gets a **token** and a private **dashboard link**: + +| | what | who may see it | +|---|---|---| +| token | `gc_` + 22 letters and digits, e.g. `gc_4fQ9...` | public: it ships in your page. It only lets your app's diagnostics be grouped together. | +| dashboard link | `https://genclass.dev/dashboard/` | **private**: anyone with the link sees your app's stats, and it is the only way to open them | + +**Get one:** `npx @genclass/runtime init` (creates both, writes the token, prints the link and saves it in +`.genclass.local`), or click "Get a token" at [genclass.dev/start](https://genclass.dev/start) and pass the token +yourself: `GenClass.init({ token })`, `data-token="..."`, `` or +`window.GENCLASS_CONFIG = { token }`. A malformed token logs one console warning and is ignored. + +**What it shows:** decisions, detections by diagnosis, actions taken, top routes and protected functions, +model load, backend (WebGPU or WASM) and latency, runtime and model versions, and recent detections. + +**What it needs:** telemetry on (the default with `GenClass.init()` in a browser). With telemetry off, a token does +nothing (with `debug: true` the console says so once). Visitors who opt out (`?genclass=no-telemetry`, +`localStorage["genclass.telemetry"] = "off"`) or whose browser sends Global Privacy Control are not counted. The +token is sent with each telemetry batch; nothing else changes about what is sent ([Privacy and +telemetry](#privacy-and-telemetry)). Dashboard data is kept for 90 days. + ## Automatic state discovery With the one line (`@genclass/runtime/auto*` or the script tag) GenClass finds the app's state on its own. It @@ -269,7 +397,7 @@ These hold for the runtime; whether the model's decisions are good is a separate it changed carry an `x-genclass` header. - **Off in one step.** `?genclass=off` in the URL installs nothing, and observe (the default) never changes execution. -- **Small on the main thread.** The main entry is about 89 KB gzip (minified, without the optional devtools). The +- **Small on the main thread.** The main entry is about 90 KB gzip (minified, without the optional devtools). The default model is 10.2 MB on WASM (13.6 MB fp16 on WebGPU with `shader-f16`), downloaded once at idle and cached. It runs in a worker that holds 190 to 280 MB while loaded: see [Costs](#costs). @@ -513,6 +641,7 @@ measured. GenClass runs with safe defaults (`mode: "observe"`, a `"balanced"` gate that applies once you opt into guard or heal, circuit breaker on). The options below narrow where it acts, cap how much it does, and send findings to your tools. None of them tell the model what a bug looks like. They only scope and limit it. +- **Your app**: `token` (your dashboard, see [Your dashboard](#your-dashboard)), `scope` (`"app"` or `"functions"`, see [protect()](#function-specific-protect)). - **Activation**: `enabled` (a boolean, a predicate, or a subscribable feature flag; while it is false the model is never downloaded), `rt.disable({ undo: true })` (remote kill that also rolls back recent actions), `sample` (the fraction of sessions allowed to act; the rest only observe). - **Scope**: `routes` (per-route mode and aggressiveness, which can only be lowered), `requests.ignore` (analytics traffic), `requests.protect` (endpoints that are never held, retried, cached or discarded), `requests.labels` (endpoint names for reports), `requests.correlate` (attach your trace id to records). - **Safety**: `breaker` (automatic downgrade after undos, or after errors that follow an action), `shadow` (records what a higher mode would have done), `onBeforeAction` + `vetoMode` (a synchronous veto, or a report-only trial of one), `policy.actionLimits` (per-minute, per-subject and per-session caps), `policy.holdBudgetMs` (a hard ceiling on added latency). @@ -661,15 +790,16 @@ observe mode against running without GenClass. With network chaos, 3 of 198 runs | Redux-style dispatch on 5,000 entities | about 0.7 ms | | settled-point check | 0.3 ms | -- **Bundle:** what every page loads is about 96 KB gzip for `@genclass/runtime/auto` with automatic state - discovery (89 KB before it) and 89 KB for the main entry with `GenClass.init()`, which does not carry discovery, +- **Bundle:** what every page loads is about 97 KB gzip for `@genclass/runtime/auto` with automatic state + discovery (89 KB before it) and 90 KB for the main entry with `GenClass.init()`, which does not carry discovery + (tokens and `protect()` added about 0.9 KB to each), measured with esbuild (`test/bundle.test.ts` keeps them under 98 KB and 92 KB). It was 97 to 99 KB up to `0.1.0-beta.3`, whose README said 83 KB. The model worker, ONNX Runtime Web's JavaScript (about 70 KB gzip for WASM, 115 KB with WebGPU, minified) and the devtools are separate chunks loaded on demand. ONNX Runtime's own `.wasm` (14 MB, 3.1 MB brotli; 27 MB, 5.5 MB brotli with WebGPU) is never part of your build: the runtime fetches it when the model loads (from jsDelivr, or `model.ortWasmPaths`). Up to `0.1.0-beta.3`, bundlers copied both `.wasm` builds (41 MB, one file over 25 MiB) into every app's build output unused. The script-tag file - is about 110 KB gzip (with discovery); its model worker and ONNX Runtime glue load on demand. + is about 111 KB gzip (with discovery); its model worker and ONNX Runtime glue load on demand. - **Model:** the default model is 9.6 MB (q8, pruned 16k vocabulary) on WASM and 13.6 MB (fp16) on WebGPU with `shader-f16`. With onnxruntime-web 1.30 on single-thread WASM, measured in Node on the training VM, a forward pass took about 176 / 320 / 583 ms at 500 / 780 / 1,170 tokens (p50 315 ms on runtime-sized requests). Single-thread @@ -698,7 +828,7 @@ without `?genclass=off`: | | with GenClass | |---|---| -| JavaScript on every page (first load, gzip) | +97 KB with `0.1.0-beta.3`; `0.1.0-beta.4` cuts the runtime itself to about 89 KB (see Performance) | +| JavaScript on every page (first load, gzip) | +97 KB with `0.1.0-beta.3`; `0.1.0-beta.4` cuts the runtime itself to about 90 KB (see Performance) | | Main thread: load event, LCP, long tasks | no measurable change; main JS heap +0.4 MB | | **Memory: renderer process (holds the model worker)** | **+190 to 280 MB RSS** while the model is loaded (cold 448 vs 169 MB, warm 361 vs 171 MB) | | **First visit download** | **12.7 MB** after the load event (q8 model 9.45 MB, ONNX Runtime wasm 3.07 MB brotli, tokenizer 207 KB); WebGPU devices: 13.6 MB fp16 model plus the larger ONNX Runtime build | @@ -787,6 +917,9 @@ GenClass.init({ model: { baseUrl: "/genclass-model/", ortWasmPaths: "/genclass-m - **If you ship GenClass**, the data comes from your users' browsers: you may need to mention it in your privacy policy and, where you need consent for analytics (GDPR/ePrivacy), start with `telemetry: false` until consent. Stored data is deleted after 90 days. Privacy policy: [PRIVACY.md](https://github.com/daybot-solutions-inc/GenClass-lib/blob/main/PRIVACY.md). + - **With a token** (`token` option), each batch also carries your app's token, and decisions about protected + functions carry the function's name (`fn`). The site owner who holds the dashboard link for that token sees + aggregated diagnostics and recent detections from it. Without telemetry the token sends nothing. - `telemetry: { endpoint, sample, flushMs, maxBatch, include }` sends to your own collector, samples page loads, or tunes batching. `runtime.telemetry` tells whether it is on and why not. - **Inputs:** typed values of password fields, `cc-*` / `one-time-code` / password autocomplete fields, and fields diff --git a/packages/runtime/TELEMETRY.md b/packages/runtime/TELEMETRY.md index 73a89ff6..c8f3a0e0 100644 --- a/packages/runtime/TELEMETRY.md +++ b/packages/runtime/TELEMETRY.md @@ -23,7 +23,7 @@ When it is on, the console shows one notice per page: [GenClass] Sends anonymous diagnostics (decisions, redacted situation text) to improve the model. Opt out: GenClass.init({ telemetry: false }) or ?genclass=no-telemetry. ``` -`runtime.telemetry` reports `{ enabled, reason?, endpoint?, sessionId?, flush() }`; `reason` says why it is off +`runtime.telemetry` reports `{ enabled, reason?, endpoint?, sessionId?, token?, flush() }`; `reason` says why it is off (`option`, `headless`, `url`, `localStorage`, `gpc`, `sampled-out`, `no-crypto`, `no-transport`, `kill-switch`, `disabled`). @@ -51,6 +51,7 @@ Only data the runtime already computes for its own decisions, after redaction: ```jsonc { "schema": "genclass-telemetry/1", + "token": "gc_…", // only when the app configured a valid token (InitOptions.token); see "App tokens" "sid": "3f9c…", // 24 hex chars from crypto.getRandomValues, new on every page load, never stored "sent": 12034, // ms since this page's GenClass started (no wall-clock time is sent) "runtime": "0.1.0-beta.3", // @genclass/runtime version @@ -66,7 +67,7 @@ Every event has `t` (type), `seq` (0, 1, 2, … per page) and `at` (ms since sta | `session` | once, at init | `runtime`, `host` (the page's hostname, which identifies the app using GenClass), `route` (the page path with id-like segments replaced by `:id`, no query or fragment), `mode`, `effectiveMode`, `aggressiveness`, `sampled`, `model` (`local` / `custom` / `off`), `modelState`, `modelVersion`, `triage`, `shadow`, `holdWrites`, `device` (`webgpu` available, `cores`, `memoryGB` (the browser's coarse deviceMemory), `crossOriginIsolated`, `effectiveType`, `saveData`), `sample`, `situation` (whether situation text is included) | | `model` | model state changes | `state`, `version`, `model`, `variant`, `device` (webgpu/wasm), `threads`, `worker`, `workerError`, `gpu` (WebGPU probe summary), `ort`, `loadMs`, `warmupMs`, `fromCache`, `bytes`, `phase`, `reason`, `error` (GenClass model-host error text, ≤ 200 chars), `attempts` | | `status` | mode, aggressiveness or breaker changes | `mode`, `effectiveMode`, `aggressiveness`, `breaker` | -| `decision` | every model decision | `id`, `trigger`, `route`, `model`, `latencyMs`, `held` (the subject waited for the answer; false = decided in the background), `situation` (text, see above), `autoState` (true when discovered state was recorded on the page), `budget`, `compact`, `questions` (question ids), `answers` (per question: calibrated `probabilities` per label, `choice`, `confidence`; or `p` / `score`), `diagnosis`, `diagnosisConfidence`, `action` (chosen), `confidence`, `tier`, `candidate`, `ran`, `executed`, `acted`, `reason` (why the passive action ran), `mass`, `gateKind`, `threshold` / `gain` / `margin`, `thresholdSource`, `gates` (report/guard/heal thresholds, aggressiveness, level and sources), `effectiveMode`, `shadow` | +| `decision` | every model decision | `id`, `trigger`, `route`, `model`, `latencyMs`, `held` (the subject waited for the answer; false = decided in the background), `situation` (text, see above), `autoState` (true when discovered state was recorded on the page), `budget`, `compact`, `questions` (question ids), `answers` (per question: calibrated `probabilities` per label, `choice`, `confidence`; or `p` / `score`), `diagnosis`, `diagnosisConfidence`, `action` (chosen), `confidence`, `tier`, `candidate`, `ran`, `executed`, `acted`, `reason` (why the passive action ran), `mass`, `gateKind`, `threshold` / `gain` / `margin`, `thresholdSource`, `gates` (report/guard/heal thresholds, aggressiveness, level and sources), `effectiveMode`, `shadow`, `fn` (the name the app gave the `protect()`ed function the decision's subject ran inside, the outermost one; omitted otherwise) | | `detect` | a decision reported as a detection | `decision`, `trigger`, `diagnosis`, `p` | | `action` | an action ran, failed or was undone | `id`, `decision`, `action`, `tier`, `trigger`, `outcome` (`applied` / `failed` / `undone`), `late` (a late revert), `reversible`, `droppedFields` (count) | | `veto` | `onBeforeAction` vetoed an action | `decision`, `action`, `enforced` | @@ -85,6 +86,24 @@ Numbers are rounded to 4 decimals. The source of truth is `packages/runtime/src/ - At most 1,000 queued events; beyond that new events are dropped and counted. A failed request is dropped, never retried. Telemetry never throws into your app, never changes what the model sees, and never delays a decision. +## App tokens and dashboards + +An app can set a **token** (`InitOptions.token`, `data-token`, `` or +`window.GENCLASS_CONFIG.token`): `gc_` followed by 22 letters or digits, created by `npx @genclass/runtime init` or at +https://genclass.dev/start. + +- The token is public (it is in the page). It is sent as the batch envelope's top-level `token` and nowhere else; it + lets the collector group the batches of one app. A malformed token logs one console warning and is not sent. +- Whoever holds the app's private dashboard link (`https://genclass.dev/dashboard/`, given once when the + token is created) can see aggregated diagnostics for that token (decisions, detections by diagnosis, actions, top + routes and protected functions, model load, backend and latency, versions) and its recent detections. Dashboard + data is also deleted after 90 days. +- A token changes nothing about what is collected or when: with telemetry off (any opt-out, or Global Privacy + Control) nothing is sent and the dashboard gets nothing from that page. With `debug: true` the console says once + that a token is set while telemetry is off. +- `decision` events carry `fn` when the decision was about something a `protect()`ed function caused (the name the + app chose, at most 80 characters). + ## Where it goes - **Endpoint:** `https://genclass-telemetry.mehar-144.workers.dev/v1/events` (`DEFAULT_TELEMETRY_ENDPOINT`), a @@ -93,7 +112,8 @@ Numbers are rounded to 4 decimals. The source of truth is `packages/runtime/src/ partitioned by UTC date, runtime version and model version. The collector adds only the time it received the batch and the visitor's coarse **country** (two letters, from Cloudflare). It does not store IP addresses, user agents, cookies or any request header, and it drops unknown fields. -- **Use:** model evaluation and training by the GenClass maintainers. Not sold, not used for advertising. +- **Use:** model evaluation and training by the GenClass maintainers, and, for batches that carry a token, that + app's dashboard. Not sold, not used for advertising. - **Retention:** 90 days. An R2 lifecycle rule (`expire-90d`, prefix `events/`) deletes every stored batch 90 days after it was written. The maintainers may change this later; changes are recorded in the CHANGELOG. - **Your own endpoint:** `telemetry: { endpoint: "https://…" }` sends the same batches to a collector you run diff --git a/packages/runtime/test/bundle.test.ts b/packages/runtime/test/bundle.test.ts index e0767c75..53d05abf 100644 --- a/packages/runtime/test/bundle.test.ts +++ b/packages/runtime/test/bundle.test.ts @@ -60,9 +60,9 @@ describe.skipIf(!built)("dist as an app bundles it", () => { }, 60_000); // /auto carries automatic state discovery (autoState, beta.4: about 6.5 KB); the main entry does not (README: about - // 96 KB for /auto, 89 KB for GenClass.init) + // 97 KB for /auto, 90 KB for GenClass.init) const LIMIT_KB: Record = { "auto.js": 98, "index.js": 92 }; - it("first-load cost of /auto and the main entry, minified + gzip: under 98 KB / 92 KB (README: about 96 / 89 KB)", async () => { + it("first-load cost of /auto and the main entry, minified + gzip: under 98 KB / 92 KB (README: about 97 / 90 KB)", async () => { const { build } = await import("esbuild"); const uses: Record = { "auto.js": "", "index.js": "GenClass.init({});" }; for (const entry of ["auto.js", "index.js"]) { diff --git a/packages/runtime/test/projects.test.ts b/packages/runtime/test/projects.test.ts index 454e8d56..5762f237 100644 --- a/packages/runtime/test/projects.test.ts +++ b/packages/runtime/test/projects.test.ts @@ -205,6 +205,25 @@ describe("protect(): same function, tracked", () => { }); }); +describe("protect(): attribution after await", () => { + it("a request started after awaiting the function's own request is still attributed (fn and scope)", async () => { + const s = setup({ triage: "always", scope: "functions", script: defaultScript({ failure: { diagnosis: "transient" } }) }); + setProtectResolver(() => s.rt); + s.server.on("GET", "/api/cart", { status: 200, body: { id: 1 }, latency: 20 }); + s.server.on("POST", "/api/orders", { status: 500, body: {}, latency: 20 }); + const submit = protect("checkout submit", async () => { + const cart = await (await s.fetch("/api/cart")).json(); + return s.fetch("/api/orders", { method: "POST", body: JSON.stringify(cart) }); + }); + void submit().catch(() => undefined); + await s.clock.advance(2000); + const d = s.rt.decisions().find((x) => x.trigger === "failure"); + expect(d?.subject).toContain("/api/orders"); + expect(d?.fn).toBe("checkout submit"); + s.rt.destroy(); + }); +}); + describe("scope: \"functions\"", () => { async function run(scope: "app" | "functions" | undefined) { const s = setup({ triage: "always", ...(scope ? { scope } : {}), script: defaultScript({ failure: { diagnosis: "transient" } }) }); From 9a7f01c417b7744deb2bb909dcf0660e69ed3a29 Mon Sep 17 00:00:00 2001 From: Karan Date: Sat, 10 Oct 2026 00:23:53 -0400 Subject: [PATCH 3/5] PRIVACY: dashboards show recent detections without the situation text Co-Authored-By: Claude Opus 5.5 --- PRIVACY.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/PRIVACY.md b/PRIVACY.md index 81253d66..9397c6bf 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -37,9 +37,9 @@ works on their own site. We do not sell the data, use it for advertising, or try ## Dashboards for website owners A website owner can get a private dashboard link for their site's token. Whoever holds that link can see aggregated -diagnostics for that site (counts of decisions, detections and actions, routes, model speed, versions) and its -recent detections, which may include the situation text described above. Data from browsers that opted out or send -Global Privacy Control never reaches a dashboard. +diagnostics for that site (counts of decisions, detections and actions, routes, model speed, versions) and a list +of recent detections (time, route or function name, diagnosis, action). Dashboards do not show the situation text. +Data from browsers that opted out or send Global Privacy Control never reaches a dashboard. ## Where it goes and how long we keep it From 7b20cd4aad3731bc513403a759a03e11d9c5ba4e Mon Sep 17 00:00:00 2001 From: Karan Date: Sat, 10 Oct 2026 00:24:54 -0400 Subject: [PATCH 4/5] telemetry-worker: per-app tokens and dashboards on genclass.dev - POST /api/projects issues a public token (gc_ + 22 base62) and a private dashboard link (genclass.dev/dashboard/<32 base62>); D1 stores only the SHA-256 of the secret. Per-client Rate Limiting binding plus a global ceiling of 60 projects/min. - Batches with a known top-level token are aggregated into D1 counters (daily + hourly, one db.batch per batch, in waitUntil); unknown, malformed or missing tokens: R2 only, record shape unchanged. R2 lines carry `token` when one was sent. Decision `fn` is counted per protected function. - GET /api/projects/ stats (24h/7d/30d); /start and /dashboard/ pages (inline SVG charts, strict nonce CSP, noindex, no-referrer, light/dark, mobile). No situation text in the dashboard store. - Daily cron retention: daily/recent 90 d, hourly 48 h, summary state 2 d. - Routes genclass.dev/{start*,dashboard*,api/*}; unserved paths go to the site through a service binding. Entry module exports only the default handler (collector code moved to src/collector.ts). - Tests: D1 via node:sqlite running the real migrations (21 total). Co-Authored-By: Claude Opus 5.5 --- docs/agents/telemetry.md | 13 + telemetry-worker/README.md | 133 ++++- .../migrations/0001_dashboard.sql | 63 +++ .../migrations/0002_projects_created.sql | 2 + telemetry-worker/src/collector.ts | 338 +++++++++++++ telemetry-worker/src/dashboard.ts | 471 ++++++++++++++++++ telemetry-worker/src/index.ts | 189 +------ telemetry-worker/src/pages.ts | 428 ++++++++++++++++ telemetry-worker/test/dashboard.test.ts | 376 ++++++++++++++ telemetry-worker/test/index.test.ts | 2 +- telemetry-worker/wrangler.toml | 31 ++ 11 files changed, 1857 insertions(+), 189 deletions(-) create mode 100644 telemetry-worker/migrations/0001_dashboard.sql create mode 100644 telemetry-worker/migrations/0002_projects_created.sql create mode 100644 telemetry-worker/src/collector.ts create mode 100644 telemetry-worker/src/dashboard.ts create mode 100644 telemetry-worker/src/pages.ts create mode 100644 telemetry-worker/test/dashboard.test.ts diff --git a/docs/agents/telemetry.md b/docs/agents/telemetry.md index fead4598..95981b6e 100644 --- a/docs/agents/telemetry.md +++ b/docs/agents/telemetry.md @@ -71,6 +71,19 @@ read with `npx --yes wrangler@4 r2 object get "genclass-telemetry/" --remote --file out.gz`. - **Retention: 90 days**, by the R2 lifecycle rule `expire-90d` on prefix `events/` (set 2026-10-09; owner may change it). +## Per-app tokens and dashboards (server side) + +- Same worker (`genclass-telemetry`), also routed on `genclass.dev/{start*,dashboard*,api/*}` in front of the site + (`genclass-site`, not ours; unknown paths go to it via the `SITE` service binding). Code: `telemetry-worker/src/` + `index.ts` (entry: default export only), `collector.ts` (ingest + routing), `dashboard.ts` (D1: projects, + aggregation, stats, retention), `pages.ts` (`/start`, `/dashboard/`); tests `test/dashboard.test.ts` + (D1 = `node:sqlite` running `migrations/*.sql`). Details: `telemetry-worker/README.md`. +- Token `gc_` + 22 base62 (public, top-level `token` on a batch); dashboard secret 32 base62 (private; D1 keeps only + its SHA-256). Known token -> counters in D1 `genclass-dashboard` (+ raw batch to R2 as always, with `token` in each + line); unknown / malformed / missing -> R2 only, record shape unchanged. Decision events may carry `fn`. +- The dashboard never stores situation text. Retention: daily counters and recent rows 90 days (cron `17 3 * * *`), + hourly 48 h. + ## How to change it safely - Adding a field or event: only data the runtime already has, redacted; update `client.ts`, `TELEMETRY.md` (the diff --git a/telemetry-worker/README.md b/telemetry-worker/README.md index 9d238def..af4414c6 100644 --- a/telemetry-worker/README.md +++ b/telemetry-worker/README.md @@ -1,44 +1,143 @@ -# genclass-telemetry (collector) +# genclass-telemetry (collector, per-app tokens and dashboards) Cloudflare Worker that receives the default-on diagnostics batches from `@genclass/runtime` (see -[`packages/runtime/TELEMETRY.md`](../packages/runtime/TELEMETRY.md)) and stores them in R2. +[`packages/runtime/TELEMETRY.md`](../packages/runtime/TELEMETRY.md)) and stores them in R2, and that gives every web app +a token and a private dashboard on genclass.dev. -- **Deployed:** `https://genclass-telemetry.mehar-144.workers.dev` (account `144bd5f5270b51dbe7faf46227a154f0`, - worker `genclass-telemetry`, workers.dev route). The runtime's `DEFAULT_TELEMETRY_ENDPOINT` is this URL + `/v1/events`. -- **Storage:** R2 bucket `genclass-telemetry`, one gzip JSON Lines object per accepted batch at - `events/dt=YYYY-MM-DD/rt=/model=/.jsonl.gz` (date = server UTC date). - Each line is `{ sid, runtime, model, sent, receivedAt, country, event }`. -- **Retention:** 90 days, enforced by the R2 lifecycle rule `expire-90d` (prefix `events/`, set 2026-10-09): - `npx --yes wrangler@4 r2 bucket lifecycle add genclass-telemetry expire-90d events/ --expire-days 90`. - Check it with `npx --yes wrangler@4 r2 bucket lifecycle list genclass-telemetry`. +- **Deployed:** worker `genclass-telemetry`, account `144bd5f5270b51dbe7faf46227a154f0`. + - `https://genclass-telemetry.mehar-144.workers.dev` (workers.dev). The runtime's `DEFAULT_TELEMETRY_ENDPOINT` is this + URL + `/v1/events`. + - Zone routes on genclass.dev: `genclass.dev/start*`, `genclass.dev/dashboard*`, `genclass.dev/api/*`. They run in + front of the site (worker `genclass-site`, custom domain, owned by Mehar; this worker never changes it). Paths + under `/start*` and `/dashboard*` that this worker does not serve are handed to the site unchanged through the + `SITE` service binding (a plain `fetch()` from a route to a custom-domain origin returns 522). +- **Storage:** + - R2 bucket `genclass-telemetry`: one gzip JSON Lines object per accepted batch at + `events/dt=YYYY-MM-DD/rt=/model=/.jsonl.gz` (date = server UTC date). + Each line is `{ sid, runtime, model, sent, receivedAt, country, event }`, plus `token` when the batch carried a + well-formed one (known or not). Batches without a token are stored exactly as before. + - D1 database `genclass-dashboard` (`694d7d16-8a47-4810-8e0d-e9c89533460a`): projects and dashboard counters (below). +- **Retention:** 90 days. + - R2: lifecycle rule `expire-90d` (prefix `events/`, set 2026-10-09): + `npx --yes wrangler@4 r2 bucket lifecycle add genclass-telemetry expire-90d events/ --expire-days 90`. + Check it with `npx --yes wrangler@4 r2 bucket lifecycle list genclass-telemetry`. + - D1: a daily Cron Trigger (`17 3 * * *`, `scheduled` in `src/index.ts`, `retention()` in `src/dashboard.ts`) + deletes `daily` and `recent` rows older than 90 days, `hourly` rows older than 48 hours and `sessions` rows older + than 2 days. Projects themselves (token, name, hash of the secret) are kept until deleted. -## Routes +## Architecture + +``` +browser (@genclass/runtime) --POST /v1/events {token?, ...}--> genclass-telemetry + |-- R2: raw batch (always, as before) + '-- token known? -> D1 counters (ctx.waitUntil, one db.batch) +genclass.dev/start --> /start page --POST /api/projects--> D1 projects (token, sha256(secret)) +genclass.dev/dashboard/ --> dashboard page --GET /api/projects/?range=--> D1 counters +``` + +| file | what | +|---|---| +| `src/index.ts` | entry point: default export only (`fetch`, `scheduled`). The Workers runtime treats every named export of the main module as an entrypoint, so nothing else is exported here. | +| `src/collector.ts` | ingest (`POST /v1/events`), envelope validation (incl. optional `token`), routing for `/api/*`, `/start`, `/dashboard*` | +| `src/dashboard.ts` | ids and hashing, project creation and lookup, token cache, aggregation of a batch into counters, stats for the dashboard, retention | +| `src/pages.ts` | HTML/CSS/JS for `/start` and `/dashboard/` (inline, per-response CSP nonce, no external resources) | +| `migrations/*.sql` | D1 schema | +| `test/index.test.ts`, `test/dashboard.test.ts` | unit tests (R2 mocked; D1 = `node:sqlite` running the real migrations) | + +## Endpoints | route | behaviour | |---|---| -| `POST /v1/events` | body `{ schema: "genclass-telemetry/1", sid, sent, runtime, model, events: [{ t, ... }] }`; content-type `application/json` or `text/plain` (sendBeacon / no CORS preflight). 202 `{ ok, accepted }`; 400 bad shape/JSON; 413 over 256 KB; 415 other content type; 503 R2 failure | +| `POST /v1/events` (also `/api/v1/events`) | body `{ schema: "genclass-telemetry/1", sid, sent, runtime, model, token?, events: [{ t, ... }] }`; content-type `application/json` or `text/plain` (sendBeacon / no CORS preflight). 202 `{ ok, accepted }`; 400 bad shape/JSON; 413 over 256 KB; 415 other content type; 503 R2 failure. A missing, malformed (`^gc_[A-Za-z0-9]{22}$`) or unknown `token` never changes the response. | | `OPTIONS /v1/events` | CORS preflight (`access-control-allow-origin: *`) | | `GET /v1/health` | `{ ok: true, schema }` | +| `POST /api/projects` | body `{ name? }` (JSON object or empty; name sanitised, at most 80 chars, default "Untitled app"). 201 `{ token, dashboardUrl, name, created }`, `dashboardUrl` = `https://genclass.dev/dashboard/<32 base62>`. CORS `*`, no credentials. 429 JSON when rate-limited, 400 bad JSON, 413 over 4 KB. | +| `GET /api/projects/?range=24h\|7d\|30d` | dashboard stats JSON (default `7d`): `name, token, created, lastEvent, range, from, generated, totals, breakdowns{metric: [{key,count}]}` (top 25 each), `series` (24 hourly or 7/30 daily buckets: sessions, decisions, detections, acted), `recent` (last 50 detections/interventions in the window). 404 `{ ok:false, error:"not found" }` for an unknown or malformed secret. Same-origin only (no CORS). | +| `GET /start` | "Get a token" page | +| `GET /dashboard/` | the dashboard (404 page for an unknown secret); `GET /dashboard` redirects to `/start` | + +Rate limits on project creation: the Workers Rate Limiting binding `CREATE_LIMITER` (10 per 60 s per client, keyed by +a SHA-256 of `cf-connecting-ip`; the IP is never stored; the binding is per location and eventually consistent, so it +is approximate) plus a global ceiling of 60 new projects per minute checked in D1. + +Page and stats responses send `cache-control: no-store`, `referrer-policy: no-referrer`, `x-robots-tag: noindex`, +and the pages a strict CSP (`default-src 'none'`, scripts and styles only with the response's nonce, +`connect-src 'self'`, `frame-ancestors 'none'`). All dynamic text is inserted with `textContent`. Limits: 256 KB body, 500 events per batch, `sid` 8-64 chars `[A-Za-z0-9_-]`, every event an object with a string `t`. -Unknown top-level fields are dropped. Event objects are stored as sent (the client defines them). +Unknown top-level fields are dropped. Event objects are stored in R2 as sent (the client defines them). + +## Tokens and secrets + +- **Token** `gc_` + 22 base62 (about 131 bits) from `crypto.getRandomValues` (rejection-sampled, unbiased). Public: it + ships in the app's code and only attributes data to the app. +- **Dashboard secret** 32 base62 (about 190 bits). Private; shown once at creation. D1 stores only its SHA-256 hex + (`projects.secret_hash`), and lookups go by that hash. There is no recovery: a lost link means a new token. +- Token lookups during ingest are cached in memory per isolate (5 min for known tokens, 30 s for unknown ones). + +## D1 schema (`migrations/`) + +| table | columns | notes | +|---|---|---| +| `projects` | `token` PK, `secret_hash` UNIQUE, `name`, `created`, `last_event` | one row per app | +| `daily` | `token, day (YYYY-MM-DD), metric, key, count` PK(token, day, metric, key) | counters per UTC day; `key` is the breakdown value, `''` for totals | +| `hourly` | `token, hour (YYYY-MM-DDTHH), metric, key, count` | same counters per UTC hour, kept 48 h (the 24 h view) | +| `recent` | `id, token, t, route, fn, trigger, diagnosis, action, ran, confidence, mode, executed, acted, kind` | last 500 detections / acted decisions per token; never situation text | +| `sessions` | `sid_hash, token, day, counts` | last cumulative `summary` counters per page load (SHA-256 of token + sid), so repeated summaries count once; kept 2 days | + +Metrics (`daily.metric`/`hourly.metric`; `key` in brackets): + +| from event | metrics | +|---|---| +| `session` | `sessions`, `host` [hostname], `page_route` [route], `runtime` [version], `model_version` [version], `mode` [effectiveMode], `model_kind` [local/custom/off], `webgpu_available` [yes/no] | +| `model` | `model_state` [state], `model_ready`, `backend` [webgpu/wasm], `model_load_ms_sum` / `model_load_ms_n`, `model_from_cache`, `model_load_failed` | +| `decision` | `decisions`, `trigger`, `route`, `fn`, `diagnosis`, `decision_mode`, `executed`, `acted`, `acted_action` [ran], `fn_acted`, `latency_ms_sum` / `latency_ms_n`, `latency_bucket` | +| `detect` | `detections`, `detect_diagnosis`, `detect_trigger`, `detect_route`, `fn_detect` (route/fn from the decision in the same batch) | +| `action` | `action_outcome` [applied/failed/undone], `intervention` [action, applied only] | +| `veto`, `breaker`, `model-error` | `vetoes`, `breaker_trips`, `model_error_events` [code] | +| `summary` (delta per page load) | `fail_open` [reason:trigger], `model_errors` [code] | + +Each batch is aggregated in one `db.batch()` (multi-row upserts `count = count + excluded.count`, at most 300 distinct +counters per batch), plus one `SELECT` when the batch has a `summary`. Aggregation runs in `ctx.waitUntil` after the +202 and its failures are swallowed, so D1 can never break ingest. ## Privacy invariants The worker never stores or logs the client IP, user agent, cookies or any other request header. The only server additions are `receivedAt` (ISO time) and `country` (Cloudflare's two-letter `request.cf.country`; null if absent). -Workers observability/logs are disabled in `wrangler.toml`. `test/index.test.ts` asserts that headers and the city never -reach the stored object. +The dashboard store holds counters, hostnames, routes, function names, labels and versions, never situation text, +session ids (only a hash, for 2 days) or the dashboard secret (only its hash). Workers observability/logs are disabled +in `wrangler.toml`. Tests assert that headers, the city and the situation text never reach the stores. ## Develop / deploy ```sh cd telemetry-worker -../node_modules/.bin/vitest run --root . # unit tests (Node; R2 mocked) -npx --yes wrangler@4 deploy # deploy (needs wrangler login to the account above) +../node_modules/.bin/vitest run --root . # unit tests (Node 22.5+ for node:sqlite) +npx --yes wrangler@4 d1 migrations apply genclass-dashboard --remote # new migrations first +npx --yes wrangler@4 deploy # worker, routes, cron (wrangler login to the account above) curl https://genclass-telemetry.mehar-144.workers.dev/v1/health ``` +Local: `npx --yes wrangler@4 d1 migrations apply genclass-dashboard --local`, then `npx --yes wrangler@4 dev --local` +and open `http://localhost:8787/start` (dashboard links point at genclass.dev; replace the origin with localhost). + There is no `wrangler r2 object list`; list keys with the Cloudflare API (`GET /client/v4/accounts//r2/buckets/genclass-telemetry/objects?prefix=events/`) or the dashboard, then `npx --yes wrangler@4 r2 object get "genclass-telemetry/" --remote --file out.gz`. + +### Delete a project + +With the token (`gc_...`), or find it by name with +`npx --yes wrangler@4 d1 execute genclass-dashboard --remote --command "SELECT token, name, created FROM projects WHERE name = 'My app'"`: + +```sh +T=gc_XXXXXXXXXXXXXXXXXXXXXX +npx --yes wrangler@4 d1 execute genclass-dashboard --remote --command " + DELETE FROM daily WHERE token = '$T'; DELETE FROM hourly WHERE token = '$T'; + DELETE FROM recent WHERE token = '$T'; DELETE FROM sessions WHERE token = '$T'; + DELETE FROM projects WHERE token = '$T';" +``` + +The dashboard link then returns 404 and later batches with that token are stored in R2 only (the in-memory token cache +may keep aggregating for up to 5 minutes). Raw R2 objects are not indexed by token; they expire after 90 days. diff --git a/telemetry-worker/migrations/0001_dashboard.sql b/telemetry-worker/migrations/0001_dashboard.sql new file mode 100644 index 00000000..75b456d4 --- /dev/null +++ b/telemetry-worker/migrations/0001_dashboard.sql @@ -0,0 +1,63 @@ +-- GenClass per-app tokens and dashboards (D1 database `genclass-dashboard`). +-- Apply: npx --yes wrangler@4 d1 migrations apply genclass-dashboard --remote + +-- One row per web app. `token` is public (ships in client code); only a SHA-256 hex of the private dashboard +-- secret is stored, so the database alone cannot be used to open a dashboard. +CREATE TABLE projects ( + token TEXT PRIMARY KEY, + secret_hash TEXT NOT NULL UNIQUE, + name TEXT NOT NULL, + created TEXT NOT NULL, + last_event TEXT +); + +-- Counters per UTC day. metric = what is counted, key = the breakdown value ('' for plain totals). +-- Sums (e.g. latency) are stored as metric `_sum` next to `_n`. +CREATE TABLE daily ( + token TEXT NOT NULL, + day TEXT NOT NULL, -- YYYY-MM-DD (UTC) + metric TEXT NOT NULL, + key TEXT NOT NULL DEFAULT '', + count REAL NOT NULL DEFAULT 0, + PRIMARY KEY (token, day, metric, key) +) WITHOUT ROWID; + +-- The same counters per UTC hour, kept for 48 hours only (the dashboard's 24 h window). +CREATE TABLE hourly ( + token TEXT NOT NULL, + hour TEXT NOT NULL, -- YYYY-MM-DDTHH (UTC) + metric TEXT NOT NULL, + key TEXT NOT NULL DEFAULT '', + count REAL NOT NULL DEFAULT 0, + PRIMARY KEY (token, hour, metric, key) +) WITHOUT ROWID; + +-- Recent detections / interventions, at most 500 per token. Never situation text. +CREATE TABLE recent ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + token TEXT NOT NULL, + t TEXT NOT NULL, -- ISO time the batch was received + route TEXT, + fn TEXT, + trigger TEXT, + diagnosis TEXT, + action TEXT, -- the action the model chose + ran TEXT, -- the action that actually ran + confidence REAL, + mode TEXT, -- effectiveMode + executed INTEGER, + acted INTEGER, + kind TEXT -- 'detect' | 'acted' +); +CREATE INDEX recent_token_id ON recent (token, id); +CREATE INDEX recent_t ON recent (t); + +-- Last cumulative `summary` counters seen per page load (sid hashed), so repeated summaries are counted as deltas. +-- Kept for 2 days. +CREATE TABLE sessions ( + sid_hash TEXT PRIMARY KEY, + token TEXT NOT NULL, + day TEXT NOT NULL, + counts TEXT NOT NULL +); +CREATE INDEX sessions_day ON sessions (day); diff --git a/telemetry-worker/migrations/0002_projects_created.sql b/telemetry-worker/migrations/0002_projects_created.sql new file mode 100644 index 00000000..5b1cae5e --- /dev/null +++ b/telemetry-worker/migrations/0002_projects_created.sql @@ -0,0 +1,2 @@ +-- Index for the global project-creation ceiling (projects created in the last minute). +CREATE INDEX projects_created ON projects (created); diff --git a/telemetry-worker/src/collector.ts b/telemetry-worker/src/collector.ts new file mode 100644 index 00000000..960eac16 --- /dev/null +++ b/telemetry-worker/src/collector.ts @@ -0,0 +1,338 @@ +// GenClass telemetry collector: a Cloudflare Worker that accepts batches from @genclass/runtime +// (packages/runtime/src/telemetry/*) and writes them, gzip-compressed JSON Lines, to R2. +// +// Privacy invariants (packages/runtime/TELEMETRY.md): +// - Never store the client IP, user agent, cookies or any request header. The only server-side additions are +// `receivedAt` (ISO time) and `country` (Cloudflare's coarse two-letter `request.cf.country`). +// - Only the known top-level batch fields are kept; anything else is dropped. +// - Nothing from the request is logged (wrangler.toml disables observability). +// +// Routes: POST /v1/events (application/json or text/plain, so navigator.sendBeacon needs no CORS preflight), +// OPTIONS /v1/events (CORS preflight), GET /v1/health. +// +// Per-app tokens and dashboards (src/dashboard.ts, src/pages.ts; also routed on genclass.dev/{api/*,start*,dashboard*}): +// POST /api/projects, GET /api/projects/, GET /start, GET /dashboard/. A batch with a known top-level +// `token` is also aggregated into D1 for that app's dashboard; without one it is stored in R2 only, exactly as before. + +import { + aggregate, + createProject, + knownToken, + projectBySecret, + randomBase62, + RANGES, + sanitizeName, + sha256Hex, + stats, + TOKEN_RE, + type D1Like, + type Range, +} from "./dashboard.js"; +import { dashboardPage, notFoundPage, securityHeaders, startPage } from "./pages.js"; + +export const SCHEMA = "genclass-telemetry/1"; +export const MAX_BODY_BYTES = 256 * 1024; +export const MAX_EVENTS = 500; + +/** The subset of the R2 binding this worker uses (avoids a dependency on @cloudflare/workers-types). */ +export interface BucketLike { + put(key: string, value: ArrayBuffer | Uint8Array, options?: { httpMetadata?: Record }): Promise; +} + +export interface RateLimiterLike { + limit(o: { key: string }): Promise<{ success: boolean }>; +} + +export interface Env { + BUCKET: BucketLike; + /** D1 `genclass-dashboard` (projects and aggregates). Without it the worker is the plain R2 collector. */ + DB?: D1Like; + /** Workers Rate Limiting binding for project creation (10 / 60 s per client). */ + CREATE_LIMITER?: RateLimiterLike; + /** Service binding to the site worker (`genclass-site`), for genclass.dev paths this worker does not serve. */ + SITE?: { fetch(request: Request): Promise }; + /** Origin used in dashboard links (default https://genclass.dev). */ + DASHBOARD_ORIGIN?: string; +} + +const CORS: Record = { + "access-control-allow-origin": "*", + "access-control-allow-methods": "POST, GET, OPTIONS", + "access-control-allow-headers": "content-type", + "access-control-max-age": "86400", +}; + +export function reply(status: number, body: unknown): Response { + return new Response(body === null ? null : JSON.stringify(body), { + status, + headers: { ...CORS, "content-type": "application/json", "cache-control": "no-store" }, + }); +} + +/** Path-segment-safe version label: `[A-Za-z0-9._+-]`, at most 40 chars, else `fallback`. */ +export function pathLabel(v: unknown, fallback: string): string { + if (typeof v !== "string") return fallback; + const s = v.trim(); + return /^[A-Za-z0-9._+-]{1,40}$/.test(s) ? s : fallback; +} + +export interface Batch { + schema: string; + sid: string; + sent: number; + runtime: string; + model: string | null; + /** Per-app token (`gc_` + 22 base62), only when present and well-formed. */ + token?: string; + events: Record[]; +} + +/** Validate a parsed body. Returns the normalised batch (unknown top-level fields dropped) or an error string. */ +export function validate(body: unknown): Batch | string { + if (body === null || typeof body !== "object" || Array.isArray(body)) return "body must be a JSON object"; + const b = body as Record; + if (b.schema !== SCHEMA) return `schema must be "${SCHEMA}"`; + if (typeof b.sid !== "string" || !/^[A-Za-z0-9_-]{8,64}$/.test(b.sid)) return "sid must be 8-64 chars [A-Za-z0-9_-]"; + if (typeof b.sent !== "number" || !Number.isFinite(b.sent)) return "sent must be a finite number"; + if (typeof b.runtime !== "string" || b.runtime.length === 0 || b.runtime.length > 40) return "runtime must be a version string"; + if (b.model !== null && b.model !== undefined && (typeof b.model !== "string" || b.model.length > 80)) { + return "model must be a string or null"; + } + if (!Array.isArray(b.events)) return "events must be an array"; + if (b.events.length === 0) return "events must not be empty"; + if (b.events.length > MAX_EVENTS) return `at most ${MAX_EVENTS} events per batch`; + for (const e of b.events) { + if (e === null || typeof e !== "object" || Array.isArray(e)) return "each event must be an object"; + const t = (e as Record).t; + if (typeof t !== "string" || t.length === 0 || t.length > 32) return "each event needs a string type `t`"; + } + return { + schema: SCHEMA, + sid: b.sid, + sent: b.sent, + runtime: b.runtime, + model: typeof b.model === "string" ? b.model : null, + // optional; a missing or malformed token never rejects the batch (it is simply not attributed to an app) + ...(typeof b.token === "string" && TOKEN_RE.test(b.token) ? { token: b.token } : {}), + events: b.events as Record[], + }; +} + +async function gzip(text: string): Promise { + const stream = new Blob([text]).stream().pipeThrough(new CompressionStream("gzip")); + return new Uint8Array(await new Response(stream).arrayBuffer()); +} + +/** Read the body with a hard byte cap (the Content-Length header may be absent or wrong). */ +async function readCapped(request: Request, cap: number): Promise { + const declared = Number(request.headers.get("content-length")); + if (Number.isFinite(declared) && declared > cap) return null; + if (!request.body) return new Uint8Array(0); + const reader = request.body.getReader(); + const chunks: Uint8Array[] = []; + let total = 0; + for (;;) { + const { done, value } = await reader.read(); + if (done) break; + total += value.byteLength; + if (total > cap) { + try { await reader.cancel(); } catch { /* ignore */ } + return null; + } + chunks.push(value); + } + const out = new Uint8Array(total); + let o = 0; + for (const c of chunks) { out.set(c, o); o += c.byteLength; } + return out; +} + +export interface HandleOptions { + /** Injected for tests. */ + now?: () => Date; + uuid?: () => string; + /** ctx.waitUntil in production (aggregation runs after the response); tests await inline. */ + waitUntil?: (p: Promise) => void; + /** Requests on genclass.dev that this worker does not serve go on to the site (fetch in production). */ + passthrough?: (request: Request) => Promise; +} + +export async function handle(request: Request, env: Env, opts: HandleOptions = {}): Promise { + const url = new URL(request.url); + const path = url.pathname.replace(/\/+$/, ""); + + if (path === "/v1/health" && (request.method === "GET" || request.method === "HEAD")) { + return reply(200, { ok: true, schema: SCHEMA }); + } + if (path === "/v1/events" || path === "/api/v1/events") return ingest(request, env, opts); + const site = await routeSite(request, url, path, env, opts); + if (site) return site; + // On genclass.dev, anything else under the routed prefixes belongs to the site. + if (!url.hostname.endsWith(".workers.dev") && url.hostname !== "localhost" && opts.passthrough !== undefined) { + return opts.passthrough(request); + } + return reply(404, { ok: false, error: "not found" }); +} + +async function ingest(request: Request, env: Env, opts: HandleOptions): Promise { + if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS }); + if (request.method !== "POST") return reply(405, { ok: false, error: "method not allowed" }); + + const ct = (request.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase(); + if (ct !== "application/json" && ct !== "text/plain") { + return reply(415, { ok: false, error: "content-type must be application/json or text/plain" }); + } + + const raw = await readCapped(request, MAX_BODY_BYTES); + if (raw === null) return reply(413, { ok: false, error: `body over ${MAX_BODY_BYTES} bytes` }); + + let parsed: unknown; + try { + parsed = JSON.parse(new TextDecoder().decode(raw)); + } catch { + return reply(400, { ok: false, error: "invalid JSON" }); + } + const batch = validate(parsed); + if (typeof batch === "string") return reply(400, { ok: false, error: batch }); + + const now = (opts.now ?? (() => new Date()))(); + const receivedAt = now.toISOString(); + // Coarse country only; never the IP, colo, city, ASN or any header. + const cf = (request as unknown as { cf?: { country?: unknown } }).cf; + const country = typeof cf?.country === "string" && /^[A-Z0-9]{2}$/.test(cf.country) ? cf.country : null; + + const meta = { + sid: batch.sid, runtime: batch.runtime, model: batch.model, sent: batch.sent, receivedAt, country, + ...(batch.token ? { token: batch.token } : {}), + }; + const lines = batch.events.map((event) => JSON.stringify({ ...meta, event })).join("\n") + "\n"; + + const dt = receivedAt.slice(0, 10); + const rt = pathLabel(batch.runtime, "unknown"); + const model = pathLabel(batch.model, "none"); + const id = (opts.uuid ?? (() => crypto.randomUUID()))(); + const key = `events/dt=${dt}/rt=${rt}/model=${model}/${id}.jsonl.gz`; + + try { + await env.BUCKET.put(key, await gzip(lines), { + httpMetadata: { contentType: "application/gzip" }, + }); + } catch { + return reply(503, { ok: false, error: "storage unavailable" }); + } + + // Dashboard aggregation for a known token. Never affects the response (failures are swallowed). + const db = env.DB; + if (batch.token && db) { + const token = batch.token; + const task = (async () => { + if (await knownToken(db, token, now.getTime())) await aggregate(db, token, batch, now); + })().catch(() => undefined); + if (opts.waitUntil) opts.waitUntil(task); + else await task; + } + return reply(202, { ok: true, accepted: batch.events.length }); +} + +// ------------------------------------------------------------------------------------------ tokens and dashboards + +/** Global ceiling on project creation (all clients together). */ +export const MAX_PROJECTS_PER_MINUTE = 60; + +const PROJECT_CORS: Record = { + "access-control-allow-origin": "*", + "access-control-allow-methods": "POST, OPTIONS", + "access-control-allow-headers": "content-type", + "access-control-max-age": "86400", +}; + +function json(status: number, body: unknown, headers: Record = {}): Response { + return new Response(JSON.stringify(body), { + status, + headers: { + "content-type": "application/json", + "cache-control": "no-store", + "referrer-policy": "no-referrer", + "x-robots-tag": "noindex, nofollow", + "x-content-type-options": "nosniff", + ...headers, + }, + }); +} + +function html(status: number, body: string, nonce: string): Response { + return new Response(body, { status, headers: securityHeaders(nonce) }); +} + +async function routeSite(request: Request, url: URL, path: string, env: Env, opts: HandleOptions): Promise { + const m = request.method; + const now = (opts.now ?? (() => new Date()))(); + + if (path === "/api/projects") { + if (m === "OPTIONS") return new Response(null, { status: 204, headers: PROJECT_CORS }); + if (m !== "POST") return json(405, { ok: false, error: "method not allowed" }, PROJECT_CORS); + if (!env.DB) return json(503, { ok: false, error: "dashboards unavailable" }, PROJECT_CORS); + if (env.CREATE_LIMITER) { + // The limiter key is a hash of the client IP; the IP itself is never stored or logged. + const ip = request.headers.get("cf-connecting-ip") ?? "unknown"; + const { success } = await env.CREATE_LIMITER.limit({ key: (await sha256Hex(`create:${ip}`)).slice(0, 32) }); + if (!success) return json(429, { ok: false, error: "too many projects created; try again in a minute" }, { ...PROJECT_CORS, "retry-after": "60" }); + } + // Backstop for the (per-location, eventually consistent) limiter: a global ceiling on new projects per minute. + const recent = await env.DB.prepare("SELECT COUNT(*) AS n FROM projects WHERE created > ?") + .bind(new Date(now.getTime() - 60_000).toISOString()) + .first<{ n: number }>(); + if ((recent?.n ?? 0) >= MAX_PROJECTS_PER_MINUTE) { + return json(429, { ok: false, error: "too many projects created; try again in a minute" }, { ...PROJECT_CORS, "retry-after": "60" }); + } + const raw = await readCapped(request, 4096); + if (raw === null) return json(413, { ok: false, error: "body too large" }, PROJECT_CORS); + let body: unknown = {}; + const text = new TextDecoder().decode(raw).trim(); + if (text) { + try { + body = JSON.parse(text); + } catch { + return json(400, { ok: false, error: "invalid JSON" }, PROJECT_CORS); + } + } + if (body === null || typeof body !== "object" || Array.isArray(body)) return json(400, { ok: false, error: "body must be a JSON object" }, PROJECT_CORS); + const name = sanitizeName((body as Record).name); + const p = await createProject(env.DB, name, now); + const origin = (env.DASHBOARD_ORIGIN ?? "https://genclass.dev").replace(/\/+$/, ""); + return json(201, { token: p.token, dashboardUrl: `${origin}/dashboard/${p.secret}`, name: p.name, created: p.created }, PROJECT_CORS); + } + + const api = /^\/api\/projects\/([^/]+)$/.exec(path); + if (api) { + if (m !== "GET" && m !== "HEAD") return json(405, { ok: false, error: "method not allowed" }); + const p = env.DB ? await projectBySecret(env.DB, api[1]!) : null; + if (!p || !env.DB) return json(404, { ok: false, error: "not found" }); + const r = url.searchParams.get("range") as Range | null; + const range: Range = r && RANGES.includes(r) ? r : "7d"; + return json(200, await stats(env.DB, p, range, now)); + } + + if (path === "/start") { + if (m !== "GET" && m !== "HEAD") return null; + const nonce = randomBase62(22); + return html(200, startPage(nonce), nonce); + } + + if (path === "/dashboard") { + if (m !== "GET" && m !== "HEAD") return null; + return new Response(null, { status: 302, headers: { location: "/start", "cache-control": "no-store" } }); + } + + const dash = /^\/dashboard\/([^/]+)$/.exec(path); + if (dash) { + if (m !== "GET" && m !== "HEAD") return null; + const nonce = randomBase62(22); + const p = env.DB ? await projectBySecret(env.DB, dash[1]!) : null; + if (!p) return html(404, notFoundPage(nonce), nonce); + return html(200, dashboardPage(nonce, { name: p.name, token: p.token, created: p.created, lastEvent: p.last_event }), nonce); + } + + if (path.startsWith("/api/")) return json(404, { ok: false, error: "not found" }); + return null; +} diff --git a/telemetry-worker/src/dashboard.ts b/telemetry-worker/src/dashboard.ts new file mode 100644 index 00000000..482ce108 --- /dev/null +++ b/telemetry-worker/src/dashboard.ts @@ -0,0 +1,471 @@ +// Per-app tokens and dashboards: D1 storage, aggregation of telemetry batches, stats for the dashboard, retention. +// +// - A token (`gc_` + 22 base62) identifies one web app. It is public (ships in client code) and only lets data be +// sent. The dashboard secret (32 base62) is private; only its SHA-256 hex is stored. +// - Aggregates are counters per (token, UTC day | UTC hour, metric, key). No situation text, no IP, no user agent. +// - Retention (daily cron): daily counters and recent rows 90 days, hourly counters 48 hours, summary state 2 days. + +export const TOKEN_RE = /^gc_[A-Za-z0-9]{22}$/; +export const SECRET_RE = /^[A-Za-z0-9]{32}$/; +export const RECENT_CAP = 500; +export const RETENTION_DAYS = 90; +/** Distinct counters one batch may touch (bounds D1 writes per batch). */ +export const MAX_COUNTERS = 300; +const KEY_MAX = 120; +const ROWS_PER_STMT = 16; // 5 bound params per row; D1 allows 100 per statement + +// --------------------------------------------------------------------------------------------- D1 subset + +export interface D1Stmt { + bind(...values: unknown[]): D1Stmt; + first>(): Promise; + all>(): Promise<{ results: T[] }>; + run(): Promise; +} +export interface D1Like { + prepare(sql: string): D1Stmt; + batch(stmts: D1Stmt[]): Promise; +} + +// --------------------------------------------------------------------------------------------- ids, hashing + +const B62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; + +/** n base62 chars from crypto.getRandomValues, unbiased (rejection sampling). */ +export function randomBase62(n: number): string { + let out = ""; + while (out.length < n) { + const bytes = crypto.getRandomValues(new Uint8Array(n * 2)); + for (const b of bytes) { + if (b < 248) out += B62[b % 62]; + if (out.length === n) break; + } + } + return out; +} + +export const newToken = (): string => `gc_${randomBase62(22)}`; +export const newSecret = (): string => randomBase62(32); + +export async function sha256Hex(s: string): Promise { + const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s)); + return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join(""); +} + +/** Project name: printable text, whitespace collapsed, at most 80 chars; default "Untitled app". */ +export function sanitizeName(v: unknown): string { + if (typeof v !== "string") return "Untitled app"; + // eslint-disable-next-line no-control-regex + const s = v.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, " ").replace(/\s+/g, " ").trim(); + const cut = [...s].slice(0, 80).join("").trim(); + return cut || "Untitled app"; +} + +export const dayKey = (d: Date): string => d.toISOString().slice(0, 10); +export const hourKey = (d: Date): string => d.toISOString().slice(0, 13); + +// --------------------------------------------------------------------------------------------- projects + +export interface Project { + token: string; + name: string; + created: string; + last_event: string | null; +} + +export async function createProject(db: D1Like, name: string, now: Date): Promise<{ token: string; secret: string; name: string; created: string }> { + for (let attempt = 0; ; attempt++) { + const token = newToken(); + const secret = newSecret(); + const created = now.toISOString(); + try { + await db + .prepare("INSERT INTO projects (token, secret_hash, name, created) VALUES (?, ?, ?, ?)") + .bind(token, await sha256Hex(secret), name, created) + .run(); + tokenCache.set(token, { ok: true, exp: now.getTime() + CACHE_OK_MS }); + return { token, secret, name, created }; + } catch (e) { + if (attempt >= 2) throw e; // a collision is astronomically unlikely; anything else is a real error + } + } +} + +/** Look a project up by its dashboard secret (by hash, so lookup time does not depend on how much of it matches). */ +export async function projectBySecret(db: D1Like, secret: string): Promise { + if (!SECRET_RE.test(secret)) return null; + return db + .prepare("SELECT token, name, created, last_event FROM projects WHERE secret_hash = ?") + .bind(await sha256Hex(secret)) + .first(); +} + +const CACHE_OK_MS = 5 * 60_000; +const CACHE_MISS_MS = 30_000; +const tokenCache = new Map(); +export function resetTokenCache(): void { + tokenCache.clear(); +} + +/** Is this a token of a known project? Cached in memory briefly (5 min hits, 30 s misses). */ +export async function knownToken(db: D1Like, token: string, nowMs: number): Promise { + if (!TOKEN_RE.test(token)) return false; + const c = tokenCache.get(token); + if (c && c.exp > nowMs) return c.ok; + const row = await db.prepare("SELECT 1 AS ok FROM projects WHERE token = ?").bind(token).first(); + const ok = !!row; + if (tokenCache.size > 5000) tokenCache.clear(); + tokenCache.set(token, { ok, exp: nowMs + (ok ? CACHE_OK_MS : CACHE_MISS_MS) }); + return ok; +} + +// --------------------------------------------------------------------------------------------- aggregation + +type Ev = Record; +export interface AggBatch { + sid: string; + runtime: string; + model: string | null; + events: Ev[]; +} + +const str = (v: unknown): string | undefined => (typeof v === "string" && v.trim() ? [...v.trim()].slice(0, KEY_MAX).join("") : undefined); +const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined); + +export const LATENCY_BUCKETS: [number, string][] = [ + [50, "<50 ms"], + [100, "50-100 ms"], + [250, "100-250 ms"], + [500, "250-500 ms"], + [1000, "0.5-1 s"], + [2500, "1-2.5 s"], + [Infinity, ">2.5 s"], +]; +const latencyBucket = (ms: number): string => LATENCY_BUCKETS.find(([max]) => ms < max)![1]; + +class Counters { + readonly m = new Map(); + add(metric: string, key: string | undefined = "", n = 1): void { + if (!(n > 0) || !Number.isFinite(n)) return; + const k = `${metric}\u0000${key ?? ""}`; + const prev = this.m.get(k); + if (prev === undefined && this.m.size >= MAX_COUNTERS) return; + this.m.set(k, (prev ?? 0) + n); + } +} + +interface RecentRow { + route?: string; + fn?: string; + trigger?: string; + diagnosis?: string; + action?: string; + ran?: string; + confidence?: number; + mode?: string; + executed?: boolean; + acted?: boolean; + kind: "detect" | "acted"; +} + +/** Pure part of the aggregation: counters and recent rows for one batch (exported for tests). */ +export function summarize(batch: AggBatch): { counters: Counters; recent: RecentRow[]; summary?: Ev } { + const c = new Counters(); + const recent: RecentRow[] = []; + const decisions = new Map(); + for (const e of batch.events) if (e.t === "decision" && typeof e.id === "string") decisions.set(e.id, e); + const detected = new Set(); + let summary: Ev | undefined; + + for (const e of batch.events) { + switch (e.t) { + case "session": { + c.add("sessions"); + c.add("host", str(e.host) ?? "(unknown)"); + c.add("page_route", str(e.route) ?? "(unknown)"); + c.add("runtime", str(e.runtime) ?? str(batch.runtime) ?? "(unknown)"); + c.add("model_version", str(e.modelVersion) ?? str(batch.model) ?? "none"); + c.add("mode", str(e.effectiveMode) ?? str(e.mode) ?? "(unknown)"); + c.add("model_kind", str(e.model) ?? "(unknown)"); + const dev = e.device as Ev | undefined; + if (dev && typeof dev === "object") c.add("webgpu_available", dev.webgpu ? "yes" : "no"); + break; + } + case "model": { + const state = str(e.state); + if (!state) break; + c.add("model_state", state); + if (state === "ready") { + c.add("model_ready"); + c.add("backend", str(e.device) ?? "(unknown)"); + const ms = num(e.loadMs); + if (ms !== undefined && ms >= 0) { + c.add("model_load_ms_sum", "", ms); + c.add("model_load_ms_n"); + } + if (e.fromCache === true) c.add("model_from_cache"); + } else if (state === "error") { + c.add("model_load_failed"); + } + break; + } + case "decision": { + c.add("decisions"); + c.add("trigger", str(e.trigger) ?? "(unknown)"); + c.add("route", str(e.route) ?? "(unknown)"); + const fn = str(e.fn); + if (fn) c.add("fn", fn); + c.add("diagnosis", str(e.diagnosis) ?? "(unknown)"); + c.add("decision_mode", str(e.effectiveMode) ?? "(unknown)"); + if (e.executed === true) c.add("executed"); + if (e.acted === true) { + c.add("acted"); + c.add("acted_action", str(e.ran) ?? str(e.action) ?? "(unknown)"); + if (fn) c.add("fn_acted", fn); + } + const lat = num(e.latencyMs); + if (lat !== undefined && lat >= 0) { + c.add("latency_ms_sum", "", lat); + c.add("latency_ms_n"); + c.add("latency_bucket", latencyBucket(lat)); + } + break; + } + case "detect": { + c.add("detections"); + c.add("detect_diagnosis", str(e.diagnosis) ?? "(unknown)"); + c.add("detect_trigger", str(e.trigger) ?? "(unknown)"); + const d = typeof e.decision === "string" ? decisions.get(e.decision) : undefined; + if (d) { + detected.add(e.decision as string); + c.add("detect_route", str(d.route) ?? "(unknown)"); + const fn = str(d.fn); + if (fn) c.add("fn_detect", fn); + } else { + recent.push({ kind: "detect", trigger: str(e.trigger), diagnosis: str(e.diagnosis), confidence: num(e.p) }); + } + break; + } + case "action": { + const outcome = str(e.outcome) ?? "(unknown)"; + c.add("action_outcome", outcome); + if (outcome === "applied") c.add("intervention", str(e.action) ?? "(unknown)"); + break; + } + case "veto": + c.add("vetoes"); + break; + case "breaker": + if (e.tripped === true) c.add("breaker_trips"); + break; + case "model-error": + c.add("model_error_events", str(e.code) ?? "error"); + break; + case "summary": { + const prevSeq = num(summary?.seq) ?? -1; + if (!summary || (num(e.seq) ?? 0) >= prevSeq) summary = e; + break; + } + } + } + + for (const [id, d] of decisions) { + const acted = d.acted === true; + if (!acted && !detected.has(id)) continue; + recent.push({ + kind: detected.has(id) ? "detect" : "acted", + route: str(d.route), + fn: str(d.fn), + trigger: str(d.trigger), + diagnosis: str(d.diagnosis), + action: str(d.action), + ran: str(d.ran), + confidence: num(d.confidence), + mode: str(d.effectiveMode), + executed: d.executed === true, + acted, + }); + } + return { counters: c, recent: recent.slice(-100), summary }; +} + +type CountMap = Record; +function countMap(v: unknown): CountMap { + const out: CountMap = {}; + if (!v || typeof v !== "object") return out; + let i = 0; + for (const [k, n] of Object.entries(v as Record)) { + if (i++ >= 50) break; + const x = num(n); + if (x !== undefined && x > 0) out[[...k].slice(0, KEY_MAX).join("")] = x; + } + return out; +} + +function upserts(db: D1Like, table: "daily" | "hourly", col: "day" | "hour", token: string, bucket: string, counters: Counters): D1Stmt[] { + const entries = [...counters.m]; + const out: D1Stmt[] = []; + for (let i = 0; i < entries.length; i += ROWS_PER_STMT) { + const chunk = entries.slice(i, i + ROWS_PER_STMT); + const sql = + `INSERT INTO ${table} (token, ${col}, metric, key, count) VALUES ` + + chunk.map(() => "(?, ?, ?, ?, ?)").join(", ") + + ` ON CONFLICT (token, ${col}, metric, key) DO UPDATE SET count = count + excluded.count`; + const params: unknown[] = []; + for (const [k, n] of chunk) { + const [metric, key] = k.split("\u0000") as [string, string]; + params.push(token, bucket, metric, key, n); + } + out.push(db.prepare(sql).bind(...params)); + } + return out; +} + +/** Aggregate one accepted batch for a known token: all writes in one db.batch(). */ +export async function aggregate(db: D1Like, token: string, batch: AggBatch, now: Date): Promise { + const { counters, recent, summary } = summarize(batch); + const iso = now.toISOString(); + const day = dayKey(now); + + // `summary` counters are cumulative per page load; count only what is new since the last summary we saw. + let sessionStmt: D1Stmt | undefined; + if (summary) { + const counts = (summary.counts ?? {}) as Ev; + const cur = { failOpen: countMap(counts.failOpen), modelErrors: countMap(counts.modelErrors) }; + const sidHash = (await sha256Hex(`${token}:${batch.sid}`)).slice(0, 32); + const row = await db.prepare("SELECT counts FROM sessions WHERE sid_hash = ?").bind(sidHash).first<{ counts: string }>(); + let prev: { failOpen?: CountMap; modelErrors?: CountMap } = {}; + try { + prev = row ? JSON.parse(row.counts) : {}; + } catch { + /* corrupt: treat as new */ + } + for (const [k, n] of Object.entries(cur.failOpen)) counters.add("fail_open", k, n - (prev.failOpen?.[k] ?? 0)); + for (const [k, n] of Object.entries(cur.modelErrors)) counters.add("model_errors", k, n - (prev.modelErrors?.[k] ?? 0)); + sessionStmt = db + .prepare("INSERT INTO sessions (sid_hash, token, day, counts) VALUES (?, ?, ?, ?) ON CONFLICT (sid_hash) DO UPDATE SET counts = excluded.counts, day = excluded.day") + .bind(sidHash, token, day, JSON.stringify(cur)); + } + + const stmts: D1Stmt[] = [ + ...upserts(db, "daily", "day", token, day, counters), + ...upserts(db, "hourly", "hour", token, hourKey(now), counters), + db.prepare("UPDATE projects SET last_event = ? WHERE token = ?").bind(iso, token), + ]; + if (sessionStmt) stmts.push(sessionStmt); + for (const r of recent) { + stmts.push( + db + .prepare("INSERT INTO recent (token, t, route, fn, trigger, diagnosis, action, ran, confidence, mode, executed, acted, kind) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)") + .bind(token, iso, r.route ?? null, r.fn ?? null, r.trigger ?? null, r.diagnosis ?? null, r.action ?? null, r.ran ?? null, r.confidence ?? null, r.mode ?? null, r.executed === undefined ? null : r.executed ? 1 : 0, r.acted === undefined ? null : r.acted ? 1 : 0, r.kind), + ); + } + if (recent.length) { + stmts.push( + db + .prepare("DELETE FROM recent WHERE token = ?1 AND id < (SELECT id FROM recent WHERE token = ?1 ORDER BY id DESC LIMIT 1 OFFSET ?2)") + .bind(token, RECENT_CAP - 1), + ); + } + await db.batch(stmts); +} + +// --------------------------------------------------------------------------------------------- stats + +export type Range = "24h" | "7d" | "30d"; +export const RANGES: Range[] = ["24h", "7d", "30d"]; +const SERIES_METRICS = ["sessions", "decisions", "detections", "acted"]; + +export interface Stats { + name: string; + token: string; + created: string; + lastEvent: string | null; + range: Range; + from: string; + generated: string; + totals: Record; + breakdowns: Record; + series: { bucket: string; sessions: number; decisions: number; detections: number; acted: number }[]; + recent: Record[]; +} + +export async function stats(db: D1Like, p: Project, range: Range, now: Date): Promise { + const hourly = range === "24h"; + const table = hourly ? "hourly" : "daily"; + const col = hourly ? "hour" : "day"; + const span = hourly ? 24 : range === "7d" ? 7 : 30; + const buckets: string[] = []; + for (let i = span - 1; i >= 0; i--) { + const d = new Date(now.getTime() - i * (hourly ? 3_600_000 : 86_400_000)); + buckets.push(hourly ? hourKey(d) : dayKey(d)); + } + const from = buckets[0]!; + + const [agg, series, recent] = await db.batch([ + db.prepare(`SELECT metric, key, SUM(count) AS c FROM ${table} WHERE token = ? AND ${col} >= ? GROUP BY metric, key`).bind(p.token, from), + db + .prepare(`SELECT ${col} AS b, metric, SUM(count) AS c FROM ${table} WHERE token = ? AND ${col} >= ? AND key = '' AND metric IN (${SERIES_METRICS.map(() => "?").join(", ")}) GROUP BY ${col}, metric`) + .bind(p.token, from, ...SERIES_METRICS), + db + .prepare("SELECT t, route, fn, trigger, diagnosis, action, ran, confidence, mode, executed, acted, kind FROM recent WHERE token = ? AND t >= ? ORDER BY id DESC LIMIT 50") + .bind(p.token, hourly ? new Date(now.getTime() - 86_400_000).toISOString() : `${from}T00:00:00.000Z`), + ]); + const rows = (r: unknown) => ((r as { results?: Record[] })?.results ?? []) as Record[]; + + const totals: Record = {}; + const breakdowns: Record = {}; + for (const r of rows(agg)) { + const metric = String(r.metric); + const key = String(r.key ?? ""); + const c = Number(r.c) || 0; + if (key === "") totals[metric] = (totals[metric] ?? 0) + c; + else (breakdowns[metric] ??= []).push({ key, count: c }); + } + for (const list of Object.values(breakdowns)) { + list.sort((a, b) => b.count - a.count || a.key.localeCompare(b.key)); + list.splice(25); + } + const sumOf = (m: string) => (breakdowns[m] ?? []).reduce((s, x) => s + x.count, 0); + totals.latencyAvgMs = totals.latency_ms_n ? Math.round(totals.latency_ms_sum! / totals.latency_ms_n) : 0; + totals.modelLoadAvgMs = totals.model_load_ms_n ? Math.round(totals.model_load_ms_sum! / totals.model_load_ms_n) : 0; + totals.failOpens = sumOf("fail_open"); + totals.modelErrors = sumOf("model_errors"); + totals.interventions = sumOf("intervention"); + if (breakdowns.latency_bucket) { + const order = LATENCY_BUCKETS.map(([, l]) => l); + breakdowns.latency_bucket.sort((a, b) => order.indexOf(a.key) - order.indexOf(b.key)); + } + + const byBucket = new Map(buckets.map((b) => [b, { bucket: b, sessions: 0, decisions: 0, detections: 0, acted: 0 }])); + for (const r of rows(series)) { + const s = byBucket.get(String(r.b)); + if (s && SERIES_METRICS.includes(String(r.metric))) (s as Record)[String(r.metric)] = Number(r.c) || 0; + } + + return { + name: p.name, + token: p.token, + created: p.created, + lastEvent: p.last_event, + range, + from: hourly ? `${from}:00:00.000Z` : `${from}T00:00:00.000Z`, + generated: now.toISOString(), + totals, + breakdowns, + series: [...byBucket.values()], + recent: rows(recent).map((r) => ({ ...r, executed: r.executed === null ? null : !!r.executed, acted: r.acted === null ? null : !!r.acted })), + }; +} + +// --------------------------------------------------------------------------------------------- retention + +export async function retention(db: D1Like, now: Date): Promise { + const cutoff = new Date(now.getTime() - RETENTION_DAYS * 86_400_000); + await db.batch([ + db.prepare("DELETE FROM daily WHERE day < ?").bind(dayKey(cutoff)), + db.prepare("DELETE FROM hourly WHERE hour < ?").bind(hourKey(new Date(now.getTime() - 48 * 3_600_000))), + db.prepare("DELETE FROM recent WHERE t < ?").bind(cutoff.toISOString()), + db.prepare("DELETE FROM sessions WHERE day < ?").bind(dayKey(new Date(now.getTime() - 2 * 86_400_000))), + ]); +} diff --git a/telemetry-worker/src/index.ts b/telemetry-worker/src/index.ts index d7daa400..edc6d1fb 100644 --- a/telemetry-worker/src/index.ts +++ b/telemetry-worker/src/index.ts @@ -1,177 +1,24 @@ -// GenClass telemetry collector: a Cloudflare Worker that accepts batches from @genclass/runtime -// (packages/runtime/src/telemetry/*) and writes them, gzip-compressed JSON Lines, to R2. -// -// Privacy invariants (packages/runtime/TELEMETRY.md): -// - Never store the client IP, user agent, cookies or any request header. The only server-side additions are -// `receivedAt` (ISO time) and `country` (Cloudflare's coarse two-letter `request.cf.country`). -// - Only the known top-level batch fields are kept; anything else is dropped. -// - Nothing from the request is logged (wrangler.toml disables observability). -// -// Routes: POST /v1/events (application/json or text/plain, so navigator.sendBeacon needs no CORS preflight), -// OPTIONS /v1/events (CORS preflight), GET /v1/health. +// Worker entry point. Only the default export lives here: the Workers runtime treats every named export of the main +// module as an entrypoint, so the collector and dashboard code (and their constants) live in collector.ts. +import { handle, reply, type Env } from "./collector.js"; +import { retention } from "./dashboard.js"; -export const SCHEMA = "genclass-telemetry/1"; -export const MAX_BODY_BYTES = 256 * 1024; -export const MAX_EVENTS = 500; - -/** The subset of the R2 binding this worker uses (avoids a dependency on @cloudflare/workers-types). */ -export interface BucketLike { - put(key: string, value: ArrayBuffer | Uint8Array, options?: { httpMetadata?: Record }): Promise; -} - -export interface Env { - BUCKET: BucketLike; -} - -const CORS: Record = { - "access-control-allow-origin": "*", - "access-control-allow-methods": "POST, GET, OPTIONS", - "access-control-allow-headers": "content-type", - "access-control-max-age": "86400", -}; - -function reply(status: number, body: unknown): Response { - return new Response(body === null ? null : JSON.stringify(body), { - status, - headers: { ...CORS, "content-type": "application/json", "cache-control": "no-store" }, - }); -} - -/** Path-segment-safe version label: `[A-Za-z0-9._+-]`, at most 40 chars, else `fallback`. */ -export function pathLabel(v: unknown, fallback: string): string { - if (typeof v !== "string") return fallback; - const s = v.trim(); - return /^[A-Za-z0-9._+-]{1,40}$/.test(s) ? s : fallback; -} - -export interface Batch { - schema: string; - sid: string; - sent: number; - runtime: string; - model: string | null; - events: Record[]; -} - -/** Validate a parsed body. Returns the normalised batch (unknown top-level fields dropped) or an error string. */ -export function validate(body: unknown): Batch | string { - if (body === null || typeof body !== "object" || Array.isArray(body)) return "body must be a JSON object"; - const b = body as Record; - if (b.schema !== SCHEMA) return `schema must be "${SCHEMA}"`; - if (typeof b.sid !== "string" || !/^[A-Za-z0-9_-]{8,64}$/.test(b.sid)) return "sid must be 8-64 chars [A-Za-z0-9_-]"; - if (typeof b.sent !== "number" || !Number.isFinite(b.sent)) return "sent must be a finite number"; - if (typeof b.runtime !== "string" || b.runtime.length === 0 || b.runtime.length > 40) return "runtime must be a version string"; - if (b.model !== null && b.model !== undefined && (typeof b.model !== "string" || b.model.length > 80)) { - return "model must be a string or null"; - } - if (!Array.isArray(b.events)) return "events must be an array"; - if (b.events.length === 0) return "events must not be empty"; - if (b.events.length > MAX_EVENTS) return `at most ${MAX_EVENTS} events per batch`; - for (const e of b.events) { - if (e === null || typeof e !== "object" || Array.isArray(e)) return "each event must be an object"; - const t = (e as Record).t; - if (typeof t !== "string" || t.length === 0 || t.length > 32) return "each event needs a string type `t`"; - } - return { - schema: SCHEMA, - sid: b.sid, - sent: b.sent, - runtime: b.runtime, - model: typeof b.model === "string" ? b.model : null, - events: b.events as Record[], - }; -} - -async function gzip(text: string): Promise { - const stream = new Blob([text]).stream().pipeThrough(new CompressionStream("gzip")); - return new Uint8Array(await new Response(stream).arrayBuffer()); -} - -/** Read the body with a hard byte cap (the Content-Length header may be absent or wrong). */ -async function readCapped(request: Request, cap: number): Promise { - const declared = Number(request.headers.get("content-length")); - if (Number.isFinite(declared) && declared > cap) return null; - if (!request.body) return new Uint8Array(0); - const reader = request.body.getReader(); - const chunks: Uint8Array[] = []; - let total = 0; - for (;;) { - const { done, value } = await reader.read(); - if (done) break; - total += value.byteLength; - if (total > cap) { - try { await reader.cancel(); } catch { /* ignore */ } - return null; - } - chunks.push(value); - } - const out = new Uint8Array(total); - let o = 0; - for (const c of chunks) { out.set(c, o); o += c.byteLength; } - return out; -} - -export interface HandleOptions { - /** Injected for tests. */ - now?: () => Date; - uuid?: () => string; -} - -export async function handle(request: Request, env: Env, opts: HandleOptions = {}): Promise { - const url = new URL(request.url); - const path = url.pathname.replace(/\/+$/, ""); - - if (path === "/v1/health" && (request.method === "GET" || request.method === "HEAD")) { - return reply(200, { ok: true, schema: SCHEMA }); - } - if (path !== "/v1/events") return reply(404, { ok: false, error: "not found" }); - if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS }); - if (request.method !== "POST") return reply(405, { ok: false, error: "method not allowed" }); - - const ct = (request.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase(); - if (ct !== "application/json" && ct !== "text/plain") { - return reply(415, { ok: false, error: "content-type must be application/json or text/plain" }); - } - - const raw = await readCapped(request, MAX_BODY_BYTES); - if (raw === null) return reply(413, { ok: false, error: `body over ${MAX_BODY_BYTES} bytes` }); - - let parsed: unknown; - try { - parsed = JSON.parse(new TextDecoder().decode(raw)); - } catch { - return reply(400, { ok: false, error: "invalid JSON" }); - } - const batch = validate(parsed); - if (typeof batch === "string") return reply(400, { ok: false, error: batch }); - - const now = (opts.now ?? (() => new Date()))(); - const receivedAt = now.toISOString(); - // Coarse country only; never the IP, colo, city, ASN or any header. - const cf = (request as unknown as { cf?: { country?: unknown } }).cf; - const country = typeof cf?.country === "string" && /^[A-Z0-9]{2}$/.test(cf.country) ? cf.country : null; - - const meta = { sid: batch.sid, runtime: batch.runtime, model: batch.model, sent: batch.sent, receivedAt, country }; - const lines = batch.events.map((event) => JSON.stringify({ ...meta, event })).join("\n") + "\n"; - - const dt = receivedAt.slice(0, 10); - const rt = pathLabel(batch.runtime, "unknown"); - const model = pathLabel(batch.model, "none"); - const id = (opts.uuid ?? (() => crypto.randomUUID()))(); - const key = `events/dt=${dt}/rt=${rt}/model=${model}/${id}.jsonl.gz`; - - try { - await env.BUCKET.put(key, await gzip(lines), { - httpMetadata: { contentType: "application/gzip" }, - }); - } catch { - return reply(503, { ok: false, error: "storage unavailable" }); - } - return reply(202, { ok: true, accepted: batch.events.length }); +interface Ctx { + waitUntil(p: Promise): void; } export default { - fetch(request: Request, env: Env): Promise { - return handle(request, env).catch(() => reply(500, { ok: false, error: "internal error" })); + fetch(request: Request, env: Env, ctx: Ctx): Promise { + // Unserved genclass.dev paths go to the site worker through a service binding (a plain fetch() from a route to a + // custom-domain origin fails with 522). + const site = env.SITE; + const passthrough = site ? (r: Request) => site.fetch(r) : undefined; + return handle(request, env, { waitUntil: (p) => ctx.waitUntil(p), passthrough }).catch(() => + reply(500, { ok: false, error: "internal error" }), + ); + }, + /** Daily cron: delete dashboard rows past retention (R2 has its own 90-day lifecycle rule). */ + async scheduled(_event: unknown, env: Env, ctx: Ctx): Promise { + if (env.DB) ctx.waitUntil(retention(env.DB, new Date())); }, }; diff --git a/telemetry-worker/src/pages.ts b/telemetry-worker/src/pages.ts new file mode 100644 index 00000000..3f84b66d --- /dev/null +++ b/telemetry-worker/src/pages.ts @@ -0,0 +1,428 @@ +// HTML for https://genclass.dev/start (get a token) and https://genclass.dev/dashboard/ (the dashboard). +// No external scripts, styles or fonts. Inline + +`; +} + +// ------------------------------------------------------------------------------------------------- /start + +export function startPage(nonce: string): string { + const body = ` +
+

Get a token for your web app

+

One token per app. Add it to GenClass and every page load, detection and fix shows up on your own + private dashboard. Free, no account.

+
+
+
+
+
+
+
+
+ +
Dashboards show counts only (never the situation text) and keep data for 90 days. +See privacy and +what is sent.
`; + const script = ` +(function(){ + var f = document.getElementById("f"), go = document.getElementById("go"), err = document.getElementById("err"); + f.addEventListener("submit", function(ev){ + ev.preventDefault(); err.textContent = ""; go.disabled = true; go.textContent = "Creating..."; + fetch("/api/projects", { method: "POST", headers: { "content-type": "application/json" }, + body: JSON.stringify({ name: document.getElementById("name").value }) }) + .then(function(r){ return r.json().then(function(j){ return { s: r.status, j: j }; }); }) + .then(function(x){ + if (x.s !== 201) throw new Error(x.s === 429 ? "Too many new tokens from your network. Try again in a minute." : (x.j && x.j.error) || "Something went wrong."); + var j = x.j; + document.getElementById("tok").textContent = j.token; + document.getElementById("tokc").appendChild(copyBtn(function(){ return j.token; })); + var d = document.getElementById("dash"); d.textContent = j.dashboardUrl; d.href = j.dashboardUrl; + document.getElementById("dashc").appendChild(copyBtn(function(){ return j.dashboardUrl; })); + document.getElementById("open").href = j.dashboardUrl; + renderSnippets(document.getElementById("snips"), j.token); + f.classList.add("hidden"); + var out = document.getElementById("out"); out.classList.remove("hidden"); out.scrollIntoView({ behavior: "smooth" }); + }) + .catch(function(e){ err.textContent = e.message || String(e); go.disabled = false; go.textContent = "Get a token"; }); + }); +})();`; + return shell(nonce, "Get a token | GenClass", body, script); +} + +// ------------------------------------------------------------------------------------------------- 404 + +export function notFoundPage(nonce: string): string { + return shell( + nonce, + "Dashboard not found | GenClass", + `

Dashboard not found

+

This link does not match any GenClass dashboard. Check that you copied the whole link, or +get a new token.

`, + "", + ); +} + +// ------------------------------------------------------------------------------------------------- dashboard + +export function dashboardPage(nonce: string, project: { name: string; token: string; created: string; lastEvent: string | null }): string { + const body = ` + +
+
+
+

+
Token + Loading...
+
+
+
+ +
+ +
+
+

+
+ +
+
+
+
+

Recent detections and interventions

+
+
TimeRoute / functionTriggerDiagnosisActionConfidenceModeExecuted
+ +
+
Install snippets
+
Counts only; GenClass never shows or stores the situation text here. Data is kept 90 days (hourly detail 48 hours). +Keep this link private: anyone with it can see these stats. Get another token.
`; + const script = ` +(function(){ + var P = JSON.parse(document.getElementById("project").textContent); + var secret = location.pathname.split("/").filter(Boolean)[1] || ""; + var range = "7d"; + try { var saved = localStorage.getItem("gc.dash.range"); if (saved === "24h" || saved === "7d" || saved === "30d") range = saved; } catch (e) {} + document.getElementById("pname").textContent = P.name; + document.title = P.name + " | GenClass dashboard"; + document.getElementById("ptok").textContent = P.token; + document.getElementById("ptokc").appendChild(copyBtn(function(){ return P.token; })); + renderSnippets(document.getElementById("snips"), P.token); + var nf = new Intl.NumberFormat(); + function fmt(n){ return nf.format(Math.round(n || 0)); } + function ago(iso){ + var s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000); + if (s < 90) return Math.round(s) + " s ago"; if (s < 5400) return Math.round(s / 60) + " min ago"; + if (s < 129600) return Math.round(s / 3600) + " h ago"; return Math.round(s / 86400) + " days ago"; + } + function kpi(label, value, sub){ + var c = el("div", "card kpi"); c.appendChild(el("div", "l", label)); c.appendChild(el("div", "v", value)); + if (sub) c.appendChild(el("div", "s", sub)); return c; + } + function bars(title, list, opts){ + opts = opts || {}; + var c = el("div", "card"); c.appendChild(el("h2", null, title)); + if (opts.note) { var n = el("p", "muted small", opts.note); n.style.marginTop = "-6px"; n.style.marginBottom = "8px"; c.appendChild(n); } + if (!list || !list.length) { c.appendChild(el("p", "empty", "None in this period.")); return c; } + var max = Math.max.apply(null, list.map(function(x){ return x.count; })) || 1; + var ul = el("ul", "bars"); + list.slice(0, opts.limit || 10).forEach(function(x){ + var li = el("li"); var k = el("span", "k", x.key); k.title = x.key; li.appendChild(k); + li.appendChild(el("span", "n", fmt(x.count) + (x.extra ? " " + x.extra : ""))); + var tr = el("span", "track"); var fi = el("span", "fill"); fi.style.display = "block"; fi.style.width = Math.max(2, 100 * x.count / max) + "%"; + if (opts.color) fi.style.background = opts.color; tr.appendChild(fi); li.appendChild(tr); ul.appendChild(li); + }); + c.appendChild(ul); return c; + } + var SVGNS = "http://www.w3.org/2000/svg"; + function chart(title, series, field, color, hourly){ + var c = el("div", "card chart"); var total = series.reduce(function(s, x){ return s + x[field]; }, 0); + var h = el("h2", null, title + " "); h.appendChild(el("span", "muted small", fmt(total) + " total")); c.appendChild(h); + var W = 600, H = 120, n = series.length, gap = n > 20 ? 2 : 4, bw = (W - gap * (n - 1)) / n; + var max = Math.max.apply(null, series.map(function(x){ return x[field]; })) || 1; + var svg = document.createElementNS(SVGNS, "svg"); svg.setAttribute("viewBox", "0 0 " + W + " " + H); svg.setAttribute("preserveAspectRatio", "none"); + svg.setAttribute("role", "img"); svg.setAttribute("aria-label", title + " per " + (hourly ? "hour" : "day")); + var base = document.createElementNS(SVGNS, "rect"); base.setAttribute("x", 0); base.setAttribute("y", H - 1); base.setAttribute("width", W); base.setAttribute("height", 1); + base.setAttribute("fill", "currentColor"); base.setAttribute("opacity", ".2"); svg.appendChild(base); + series.forEach(function(x, i){ + var v = x[field], bh = v ? Math.max(2, (H - 6) * v / max) : 0; + var r = document.createElementNS(SVGNS, "rect"); + r.setAttribute("x", i * (bw + gap)); r.setAttribute("y", H - bh); r.setAttribute("width", Math.max(1, bw)); r.setAttribute("height", bh); r.setAttribute("rx", 2); + r.setAttribute("fill", color); + var t = document.createElementNS(SVGNS, "title"); t.textContent = label(x.bucket, hourly) + ": " + fmt(v); r.appendChild(t); svg.appendChild(r); + }); + c.appendChild(svg); + var ax = el("div", "axis"); ax.appendChild(el("span", null, label(series[0].bucket, hourly))); ax.appendChild(el("span", null, label(series[n - 1].bucket, hourly))); + c.appendChild(ax); return c; + } + function label(b, hourly){ + var d = new Date(hourly ? b + ":00:00Z" : b + "T00:00:00Z"); + return hourly ? d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : d.toLocaleDateString([], { month: "short", day: "numeric", timeZone: "UTC" }); + } + function css(name){ return getComputedStyle(document.documentElement).getPropertyValue(name).trim(); } + function render(S){ + var T = S.totals, B = S.breakdowns; + var live = !!S.lastEvent; + var st = document.getElementById("status"); st.classList.toggle("live", live); + document.getElementById("statust").textContent = live ? "Last event " + ago(S.lastEvent) : "No data yet"; + document.getElementById("nodata").classList.toggle("hidden", live); + var inst = document.getElementById("install"); if (!live) inst.open = true; + document.getElementById("updated").textContent = "Updated " + new Date(S.generated).toLocaleTimeString() + ". Times in your timezone; days are UTC."; + var modelErr = Math.max(T.modelErrors || 0, (B.model_error_events || []).reduce(function(s, x){ return s + x.count; }, 0)); + var k = document.getElementById("kpis"); k.textContent = ""; + k.appendChild(kpi("Page loads", fmt(T.sessions))); + k.appendChild(kpi("Decisions", fmt(T.decisions), T.sessions ? (T.decisions / T.sessions).toFixed(1) + " per page load" : "")); + k.appendChild(kpi("Detections", fmt(T.detections))); + k.appendChild(kpi("Interventions", fmt(T.interventions), fmt(T.acted) + " decisions acted")); + k.appendChild(kpi("Model latency", T.latency_ms_n ? fmt(T.latencyAvgMs) + " ms" : "-", T.latency_ms_n ? "average of " + fmt(T.latency_ms_n) : "")); + k.appendChild(kpi("Model loads", fmt(T.model_ready), (T.model_load_failed ? fmt(T.model_load_failed) + " failed" : "0 failed") + (T.model_load_ms_n ? ", avg " + fmt(T.modelLoadAvgMs) + " ms" : ""))); + k.appendChild(kpi("Model errors", fmt(modelErr))); + k.appendChild(kpi("Fail-opens", fmt(T.failOpens), "app ran unprotected")); + var hourly = S.range === "24h"; + var ch = document.getElementById("charts"); ch.textContent = ""; + ch.appendChild(chart("Page loads", S.series, "sessions", css("--bar"), hourly)); + ch.appendChild(chart("Decisions", S.series, "decisions", css("--bar2"), hourly)); + ch.appendChild(chart("Detections", S.series, "detections", css("--bar3"), hourly)); + var fnDetect = {}, fnActed = {}; + (B.fn_detect || []).forEach(function(x){ fnDetect[x.key] = x.count; }); + (B.fn_acted || []).forEach(function(x){ fnActed[x.key] = x.count; }); + var fns = (B.fn || []).map(function(x){ return { key: x.key, count: x.count, extra: "(" + fmt(fnDetect[x.key]) + " det, " + fmt(fnActed[x.key]) + " fixed)" }; }); + var cards = document.getElementById("cards"); cards.textContent = ""; + var warn = css("--bar3"), ok = css("--bar2"); + [ + bars("Detections by diagnosis", B.detect_diagnosis, { color: warn }), + bars("Interventions (actions applied)", B.intervention, { color: ok }), + bars("Action outcomes", B.action_outcome), + bars("Top protected functions", fns, { note: "Decisions per protect() name (detections, fixes)." }), + bars("Top routes (decisions)", B.route), + bars("Top pages (page loads)", B.page_route), + bars("Triggers", B.trigger), + bars("Diagnoses (all decisions)", B.diagnosis), + bars("Model backend", B.backend, { note: "Where the model ran when it loaded." }), + bars("Model load states", B.model_state), + bars("Model latency", B.latency_bucket, { limit: 12 }), + bars("Model errors", (B.model_errors && B.model_errors.length) ? B.model_errors : B.model_error_events, { color: warn }), + bars("Fail-opens (reason:trigger)", B.fail_open, { color: warn }), + bars("Modes", B.mode), + bars("Runtime versions", B.runtime), + bars("Model versions", B.model_version), + bars("Hosts seen", B.host, { note: "Every hostname that sent data with this token. Unknown hosts may mean someone copied your token." }) + ].forEach(function(c){ cards.appendChild(c); }); + var tb = document.getElementById("recent"); tb.textContent = ""; + (S.recent || []).forEach(function(r){ + var tr = el("tr"); + var t = el("td", null, new Date(r.t).toLocaleString([], { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" })); t.title = r.t; tr.appendChild(t); + tr.appendChild(el("td", "mono", [r.route, r.fn ? "fn " + r.fn : null].filter(Boolean).join(" ") || "-")); + tr.appendChild(el("td", null, r.trigger || "-")); + tr.appendChild(el("td", null, r.diagnosis || "-")); + tr.appendChild(el("td", "mono", r.ran && r.action && r.ran !== r.action ? r.action + " (ran " + r.ran + ")" : (r.ran || r.action || "-"))); + tr.appendChild(el("td", null, typeof r.confidence === "number" ? Math.round(r.confidence * 100) + "%" : "-")); + tr.appendChild(el("td", null, r.mode || "-")); + tr.appendChild(el("td", null, r.executed == null ? "-" : r.executed ? "yes" : "no")); + tb.appendChild(tr); + }); + document.getElementById("recent0").classList.toggle("hidden", (S.recent || []).length > 0); + } + var btn = document.getElementById("refresh"); + function load(){ + btn.disabled = true; + fetch("/api/projects/" + encodeURIComponent(secret) + "?range=" + range, { headers: { accept: "application/json" }, cache: "no-store" }) + .then(function(r){ if (!r.ok) throw new Error("HTTP " + r.status); return r.json(); }) + .then(render) + .catch(function(e){ document.getElementById("updated").textContent = "Could not load stats (" + e.message + "). Retrying shortly."; }) + .then(function(){ btn.disabled = false; }); + } + document.querySelectorAll(".tabs button").forEach(function(b){ + b.setAttribute("aria-pressed", String(b.getAttribute("data-r") === range)); + b.addEventListener("click", function(){ + range = b.getAttribute("data-r"); + try { localStorage.setItem("gc.dash.range", range); } catch (e) {} + document.querySelectorAll(".tabs button").forEach(function(o){ o.setAttribute("aria-pressed", String(o === b)); }); + load(); + }); + }); + btn.addEventListener("click", load); + setInterval(function(){ if (document.visibilityState === "visible") load(); }, 60000); + load(); +})();`; + return shell(nonce, `${project.name} | GenClass dashboard`, body, script); +} diff --git a/telemetry-worker/test/dashboard.test.ts b/telemetry-worker/test/dashboard.test.ts new file mode 100644 index 00000000..52fe795a --- /dev/null +++ b/telemetry-worker/test/dashboard.test.ts @@ -0,0 +1,376 @@ +import { beforeEach, describe, expect, it } from "vitest"; +import { gunzipSync } from "node:zlib"; +import { readFileSync } from "node:fs"; +import { createRequire } from "node:module"; +import worker from "../src/index.js"; +import { handle, MAX_PROJECTS_PER_MINUTE, validate, type Env } from "../src/collector.js"; +import { RECENT_CAP, resetTokenCache, retention, sanitizeName, sha256Hex, TOKEN_RE, type D1Like, type D1Stmt } from "../src/dashboard.js"; + +// D1 stand-in backed by node:sqlite running the real migration, so the SQL itself is under test. +const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite") as typeof import("node:sqlite"); +const MIGRATION = ["0001_dashboard.sql", "0002_projects_created.sql"].map((f) => readFileSync(new URL(`../migrations/${f}`, import.meta.url), "utf8")).join("\n"); + +function d1() { + const db = new DatabaseSync(":memory:"); + db.exec(MIGRATION); + let batches = 0; + const stmt = (sql: string, params: unknown[] = []): D1Stmt => ({ + bind: (...v: unknown[]) => stmt(sql, v), + first: async () => (db.prepare(sql).get(...(params as never[])) ?? null) as T | null, + all: async () => ({ results: db.prepare(sql).all(...(params as never[])) as T[] }), + run: async () => db.prepare(sql).run(...(params as never[])), + }); + const api: D1Like = { + prepare: (sql) => stmt(sql), + async batch(stmts) { + batches++; + db.exec("BEGIN"); + try { + const out = []; + for (const s of stmts) out.push(await s.all()); + db.exec("COMMIT"); + return out; + } catch (e) { + db.exec("ROLLBACK"); + throw e; + } + }, + }; + return { api, db, rows: (sql: string, ...p: unknown[]) => db.prepare(sql).all(...(p as never[])) as Record[], batches: () => batches }; +} + +function setup(limiter?: Env["CREATE_LIMITER"]) { + const puts: { key: string; body: Uint8Array }[] = []; + const sql = d1(); + const env: Env = { + BUCKET: { + async put(key: string, value: ArrayBuffer | Uint8Array) { + puts.push({ key, body: value instanceof Uint8Array ? value : new Uint8Array(value) }); + }, + }, + DB: sql.api, + CREATE_LIMITER: limiter, + }; + return { env, puts, sql }; +} + +const NOW = new Date("2026-10-08T12:00:00Z"); +let uuidN = 0; +const opts = { now: () => NOW, uuid: () => `u-${++uuidN}` }; + +async function create(env: Env, body: unknown = { name: "Acme checkout" }, ip = "203.0.113.7") { + const res = await handle( + new Request("https://genclass.dev/api/projects", { method: "POST", body: JSON.stringify(body), headers: { "content-type": "application/json", "cf-connecting-ip": ip } }), + env, + opts, + ); + return { res, json: (await res.json()) as Record }; +} + +function post(body: unknown) { + const r = new Request("https://genclass-telemetry.example.workers.dev/v1/events", { method: "POST", body: JSON.stringify(body), headers: { "content-type": "text/plain;charset=UTF-8" } }); + Object.defineProperty(r, "cf", { value: { country: "CA", city: "Toronto" } }); + return r; +} + +const secretOf = (url: string) => url.split("/").pop()!; + +/** A realistic page load, shaped like packages/runtime/src/telemetry/client.ts emits it. */ +function pageBatch(token: string | undefined, sid = "3f9c0a1b2c3d4e5f60718293", extra: Record[] = []) { + return { + schema: "genclass-telemetry/1", + sid, + sent: 12034, + runtime: "0.1.0-beta.5", + model: "2.0.0-rc4t", + ...(token === undefined ? {} : { token }), + events: [ + { t: "session", seq: 0, at: 1, runtime: "0.1.0-beta.5", host: "shop.acme.test", route: "/cart/:id", mode: "heal", effectiveMode: "heal", aggressiveness: 0.5, sampled: true, model: "local", modelState: "loading", modelVersion: "2.0.0-rc4t", device: { webgpu: true, cores: 8 }, sample: 1, situation: true }, + { t: "model", seq: 1, at: 900, state: "ready", version: "2.0.0-rc4t", device: "webgpu", loadMs: 840, fromCache: true }, + { t: "decision", seq: 2, at: 1200, id: "d1", trigger: "mutation", route: "/cart/:id", fn: "saveCart", model: "genclass-2", latencyMs: 42, held: true, situation: "SECRET SITUATION TEXT op saveCart", diagnosis: "stale", diagnosisConfidence: 0.97, action: "discard", confidence: 0.95, tier: "guard", ran: "discard", executed: true, acted: true, effectiveMode: "heal" }, + { t: "detect", seq: 3, at: 1201, decision: "d1", trigger: "mutation", diagnosis: "stale", p: 0.97 }, + { t: "action", seq: 4, at: 1202, id: "a1", decision: "d1", action: "discard", tier: "guard", trigger: "mutation", outcome: "applied", reversible: true }, + { t: "decision", seq: 5, at: 2000, id: "d2", trigger: "response", route: "/cart/:id", model: "genclass-2", latencyMs: 180, situation: "more text", diagnosis: "expected", action: "proceed", confidence: 0.99, tier: "passive", ran: "proceed", executed: true, acted: false, effectiveMode: "heal" }, + { t: "model-error", seq: 6, at: 2100, code: "inference_failed", message: "x" }, + { t: "action", seq: 7, at: 3000, id: "a1", decision: "d1", action: "discard", tier: "guard", trigger: "mutation", outcome: "undone" }, + { t: "summary", seq: 8, at: 4000, reason: "hidden", counts: { decisions: 2, failOpen: { "timeout:response": 2 }, modelErrors: { inference_failed: 1 } } }, + ...extra, + ], + }; +} + +beforeEach(() => resetTokenCache()); + +describe("project creation", () => { + it("creates a project: token, private dashboard link, only the secret's hash stored", async () => { + const { env, sql } = setup(); + const { res, json } = await create(env, { name: " Acme\u0000 checkout\n\u202e " }); + expect(res.status).toBe(201); + expect(res.headers.get("access-control-allow-origin")).toBe("*"); + expect(res.headers.get("access-control-allow-credentials")).toBeNull(); + expect(json.token).toMatch(TOKEN_RE); + expect(json.dashboardUrl).toMatch(/^https:\/\/genclass\.dev\/dashboard\/[A-Za-z0-9]{32}$/); + expect(json.name).toBe("Acme checkout"); + expect(json.created).toBe(NOW.toISOString()); + const rows = sql.rows("SELECT * FROM projects"); + expect(rows).toHaveLength(1); + expect(rows[0]!.token).toBe(json.token); + expect(rows[0]!.secret_hash).toBe(await sha256Hex(secretOf(json.dashboardUrl))); + expect(JSON.stringify(rows)).not.toContain(secretOf(json.dashboardUrl)); + }); + + it("names: optional, sanitised, at most 80 chars; bad bodies rejected; CORS preflight", async () => { + const { env } = setup(); + expect((await create(env, {})).json.name).toBe("Untitled app"); + expect((await create(env, { name: 42 })).json.name).toBe("Untitled app"); + expect([...(await create(env, { name: "x".repeat(200) })).json.name]).toHaveLength(80); + expect(sanitizeName("hi")).toBe("hi"); // stored as text; pages escape it + const empty = await handle(new Request("https://genclass.dev/api/projects", { method: "POST" }), env, opts); + expect(empty.status).toBe(201); + const bad = await handle(new Request("https://genclass.dev/api/projects", { method: "POST", body: "{nope" }), env, opts); + expect(bad.status).toBe(400); + expect((await handle(new Request("https://genclass.dev/api/projects", { method: "POST", body: "[1]" }), env, opts)).status).toBe(400); + const pre = await handle(new Request("https://genclass.dev/api/projects", { method: "OPTIONS" }), env, opts); + expect(pre.status).toBe(204); + expect(pre.headers.get("access-control-allow-origin")).toBe("*"); + expect((await handle(new Request("https://genclass.dev/api/projects"), env, opts)).status).toBe(405); + }); + + it("rate-limits creation per client without passing the IP to the limiter", async () => { + const keys: string[] = []; + const counts = new Map(); + const { env, sql } = setup({ + async limit({ key }) { + keys.push(key); + counts.set(key, (counts.get(key) ?? 0) + 1); + return { success: counts.get(key)! <= 10 }; + }, + }); + for (let i = 0; i < 10; i++) expect((await create(env)).res.status).toBe(201); + const r = await create(env); + expect(r.res.status).toBe(429); + expect(r.json).toMatchObject({ ok: false }); + expect(r.res.headers.get("access-control-allow-origin")).toBe("*"); + expect((await create(env, {}, "198.51.100.9")).res.status).toBe(201); + expect(keys.join()).not.toContain("203.0.113.7"); + expect(sql.rows("SELECT COUNT(*) AS n FROM projects")[0]!.n).toBe(11); + }); + it("has a global ceiling on new projects per minute, independent of the per-client limiter", async () => { + const { env } = setup(); + for (let i = 0; i < MAX_PROJECTS_PER_MINUTE; i++) expect((await create(env, {}, `198.51.100.${i}`)).res.status).toBe(201); + expect((await create(env, {}, "192.0.2.1")).res.status).toBe(429); + const later = await handle( + new Request("https://genclass.dev/api/projects", { method: "POST", body: "{}" }), + env, + { ...opts, now: () => new Date(NOW.getTime() + 61_000) }, + ); + expect(later.status).toBe(201); + }); +}); + +describe("token on telemetry batches", () => { + it("validate keeps a well-formed token and drops a malformed one without rejecting the batch", () => { + const ok = validate(pageBatch("gc_abcdefghijklmnopqrstuv")); + expect(typeof ok !== "string" && ok.token).toBe("gc_abcdefghijklmnopqrstuv"); + for (const t of ["gc_short", "xx_abcdefghijklmnopqrstuv", "gc_abcdefghijklmnopqrst-v", 7, null]) { + const b = validate(pageBatch(t as string)); + expect(typeof b).not.toBe("string"); + expect(b).not.toHaveProperty("token"); + } + }); + + it("aggregates a known token's batch for its dashboard (and still stores the raw batch, with the token, in R2)", async () => { + const { env, puts, sql } = setup(); + const { json } = await create(env); + const res = await handle(post(pageBatch(json.token)), env, opts); + expect(res.status).toBe(202); + expect(puts).toHaveLength(1); + expect(puts[0]!.key).toMatch(/^events\/dt=2026-10-08\/rt=0\.1\.0-beta\.5\/model=2\.0\.0-rc4t\/u-\d+\.jsonl\.gz$/); + const line = JSON.parse(gunzipSync(puts[0]!.body).toString("utf8").split("\n")[0]!); + expect(line).toMatchObject({ sid: "3f9c0a1b2c3d4e5f60718293", token: json.token, country: "CA", event: { t: "session" } }); + + // the dashboard store never holds situation text, sid or the secret + const dump = JSON.stringify([sql.rows("SELECT * FROM daily"), sql.rows("SELECT * FROM hourly"), sql.rows("SELECT * FROM recent"), sql.rows("SELECT * FROM sessions")]); + expect(dump).not.toMatch(/SECRET SITUATION|more text|3f9c0a1b2c3d4e5f60718293/); + expect(sql.rows("SELECT last_event FROM projects")[0]!.last_event).toBe(NOW.toISOString()); + + const st = await handle(new Request(`https://genclass.dev/api/projects/${secretOf(json.dashboardUrl)}?range=7d`), env, opts); + expect(st.status).toBe(200); + expect(st.headers.get("referrer-policy")).toBe("no-referrer"); + const s = (await st.json()) as Record; + expect(s).toMatchObject({ name: "Acme checkout", token: json.token, lastEvent: NOW.toISOString(), range: "7d" }); + expect(s.totals).toMatchObject({ sessions: 1, decisions: 2, detections: 1, acted: 1, executed: 2, model_ready: 1, latencyAvgMs: 111, modelLoadAvgMs: 840, failOpens: 2, modelErrors: 1, interventions: 1 }); + const bd = (m: string) => Object.fromEntries((s.breakdowns[m] ?? []).map((x: any) => [x.key, x.count])); + expect(bd("detect_diagnosis")).toEqual({ stale: 1 }); + expect(bd("diagnosis")).toEqual({ stale: 1, expected: 1 }); + expect(bd("intervention")).toEqual({ discard: 1 }); + expect(bd("action_outcome")).toEqual({ applied: 1, undone: 1 }); + expect(bd("route")).toEqual({ "/cart/:id": 2 }); + expect(bd("fn")).toEqual({ saveCart: 1 }); + expect(bd("fn_detect")).toEqual({ saveCart: 1 }); + expect(bd("fn_acted")).toEqual({ saveCart: 1 }); + expect(bd("backend")).toEqual({ webgpu: 1 }); + expect(bd("host")).toEqual({ "shop.acme.test": 1 }); + expect(bd("runtime")).toEqual({ "0.1.0-beta.5": 1 }); + expect(bd("model_version")).toEqual({ "2.0.0-rc4t": 1 }); + expect(bd("fail_open")).toEqual({ "timeout:response": 2 }); + expect(bd("model_errors")).toEqual({ inference_failed: 1 }); + expect(bd("latency_bucket")).toEqual({ "<50 ms": 1, "100-250 ms": 1 }); + expect(s.series).toHaveLength(7); + expect(s.series.at(-1)).toEqual({ bucket: "2026-10-08", sessions: 1, decisions: 2, detections: 1, acted: 1 }); + expect(s.recent).toEqual([ + { t: NOW.toISOString(), route: "/cart/:id", fn: "saveCart", trigger: "mutation", diagnosis: "stale", action: "discard", ran: "discard", confidence: 0.95, mode: "heal", executed: true, acted: true, kind: "detect" }, + ]); + expect(JSON.stringify(s)).not.toContain("SITUATION"); + + // 24 h (hourly) and 30 d windows + const h = (await (await handle(new Request(`https://genclass.dev/api/projects/${secretOf(json.dashboardUrl)}?range=24h`), env, opts)).json()) as any; + expect(h.series).toHaveLength(24); + expect(h.series.at(-1)).toMatchObject({ bucket: "2026-10-08T12", sessions: 1 }); + expect(h.totals.decisions).toBe(2); + const m = (await (await handle(new Request(`https://genclass.dev/api/projects/${secretOf(json.dashboardUrl)}?range=30d`), env, opts)).json()) as any; + expect(m.series).toHaveLength(30); + }); + + it("counts cumulative summaries once per page load (deltas) and aggregates in one D1 batch", async () => { + const { env, sql } = setup(); + const { json } = await create(env); + await handle(post(pageBatch(json.token)), env, opts); + const before = sql.batches(); + // the same page later sends a bigger cumulative summary + await handle( + post({ ...pageBatch(json.token), events: [{ t: "summary", seq: 20, at: 9000, reason: "pagehide", counts: { failOpen: { "timeout:response": 3, "busy:mutation": 1 }, modelErrors: { inference_failed: 1 } } }] }), + env, + opts, + ); + expect(sql.batches() - before).toBe(1); + const s = (await (await handle(new Request(`https://genclass.dev/api/projects/${secretOf(json.dashboardUrl)}`), env, opts)).json()) as any; + expect(s.totals.failOpens).toBe(4); + expect(s.totals.modelErrors).toBe(1); + }); + + it("caps recent rows per token", async () => { + const { env, sql } = setup(); + const { json } = await create(env); + const acted = (i: number) => ({ t: "decision", seq: i, at: i, id: `d${i}`, trigger: "mutation", diagnosis: "stale", action: "discard", ran: "discard", executed: true, acted: true }); + for (let b = 0; b < 6; b++) { + await handle(post({ ...pageBatch(json.token), events: Array.from({ length: 100 }, (_, i) => acted(b * 100 + i)) }), env, opts); + } + expect(sql.rows("SELECT COUNT(*) AS n FROM recent")[0]!.n).toBe(RECENT_CAP); + expect(sql.rows("SELECT MIN(id) AS lo, MAX(id) AS hi FROM recent")[0]).toEqual({ lo: 101, hi: 600 }); + }); + + it("unknown, malformed or missing tokens: stored in R2 exactly as before, nothing aggregated", async () => { + const { env, puts, sql } = setup(); + await create(env); + for (const token of ["gc_unknownunknownunknown1", "not-a-token", undefined]) { + const res = await handle(post(pageBatch(token)), env, opts); + expect(res.status).toBe(202); + expect(await res.json()).toEqual({ ok: true, accepted: 9 }); + } + expect(puts).toHaveLength(3); + const first = (i: number) => JSON.parse(gunzipSync(puts[i]!.body).toString("utf8").split("\n")[0]!); + expect(first(0).token).toBe("gc_unknownunknownunknown1"); + // old clients (no token) and malformed tokens: the exact pre-dashboard record shape + for (const i of [1, 2]) expect(Object.keys(first(i))).toEqual(["sid", "runtime", "model", "sent", "receivedAt", "country", "event"]); + expect(sql.rows("SELECT COUNT(*) AS n FROM daily")[0]!.n).toBe(0); + expect(sql.rows("SELECT COUNT(*) AS n FROM recent")[0]!.n).toBe(0); + }); + + it("a D1 failure never fails ingest", async () => { + const { env, puts } = setup(); + const { json } = await create(env); + env.DB = { prepare: () => { throw new Error("d1 down"); }, batch: async () => { throw new Error("d1 down"); } }; + const res = await handle(post(pageBatch(json.token)), env, opts); + expect(res.status).toBe(202); + expect(puts).toHaveLength(1); + }); + + it("works without a DB binding (plain collector)", async () => { + const { env, puts } = setup(); + delete env.DB; + expect((await handle(post(pageBatch("gc_abcdefghijklmnopqrstuv")), env, opts)).status).toBe(202); + expect(puts).toHaveLength(1); + }); +}); + +describe("dashboard pages", () => { + it("serves the dashboard for a valid secret with strict headers; 404 otherwise", async () => { + const { env } = setup(); + const { json } = await create(env, { name: "" }); + const res = await handle(new Request(json.dashboardUrl), env, opts); + expect(res.status).toBe(200); + const csp = res.headers.get("content-security-policy")!; + expect(csp).toMatch(/default-src 'none'; script-src 'nonce-[A-Za-z0-9]{22}'/); + expect(res.headers.get("referrer-policy")).toBe("no-referrer"); + expect(res.headers.get("x-robots-tag")).toContain("noindex"); + const body = await res.text(); + const nonce = /nonce-([A-Za-z0-9]{22})/.exec(csp)![1]!; + expect(body).toContain(` { + const { env } = setup(); + const start = await handle(new Request("https://genclass.dev/start"), env, opts); + expect(start.status).toBe(200); + const html = await start.text(); + expect(html).toContain("Get a token"); + expect(html).toContain('fetch("/api/projects"'); + expect(html).toContain("https://cdn.jsdelivr.net/npm/@genclass/runtime"); + expect((await handle(new Request("https://genclass.dev/dashboard"), env, opts)).headers.get("location")).toBe("/start"); + const seen: string[] = []; + const passthrough = async (r: Request) => { + seen.push(new URL(r.url).pathname); + return new Response("site", { status: 200 }); + }; + expect(await (await handle(new Request("https://genclass.dev/starter-kit"), env, { ...opts, passthrough })).text()).toBe("site"); + expect(seen).toEqual(["/starter-kit"]); + // on workers.dev nothing is passed through + expect((await handle(new Request("https://x.workers.dev/starter-kit"), env, { ...opts, passthrough })).status).toBe(404); + expect((await handle(new Request("https://genclass.dev/api/nope"), env, { ...opts, passthrough })).status).toBe(404); + }); +}); + +describe("retention", () => { + it("deletes daily/recent rows older than 90 days, hourly older than 48 h, summary state older than 2 days", async () => { + const { env, sql } = setup(); + const { json } = await create(env); + const db = sql.db; + const ins = db.prepare("INSERT INTO daily (token, day, metric, key, count) VALUES (?, ?, 'sessions', '', 1)"); + for (const d of ["2026-07-09", "2026-07-10", "2026-10-08"]) ins.run(json.token, d); + const insH = db.prepare("INSERT INTO hourly (token, hour, metric, key, count) VALUES (?, ?, 'sessions', '', 1)"); + for (const h of ["2026-10-06T11", "2026-10-06T12", "2026-10-08T12"]) insH.run(json.token, h); + const insR = db.prepare("INSERT INTO recent (token, t, kind) VALUES (?, ?, 'detect')"); + for (const t of ["2026-07-10T11:00:00.000Z", "2026-07-10T13:00:00.000Z"]) insR.run(json.token, t); + const insS = db.prepare("INSERT INTO sessions (sid_hash, token, day, counts) VALUES (?, ?, ?, '{}')"); + insS.run("a", json.token, "2026-10-05"); + insS.run("b", json.token, "2026-10-06"); + + await retention(sql.api, NOW); + expect(sql.rows("SELECT day FROM daily ORDER BY day").map((r) => r.day)).toEqual(["2026-07-10", "2026-10-08"]); + expect(sql.rows("SELECT hour FROM hourly ORDER BY hour").map((r) => r.hour)).toEqual(["2026-10-06T12", "2026-10-08T12"]); + expect(sql.rows("SELECT t FROM recent").map((r) => r.t)).toEqual(["2026-07-10T13:00:00.000Z"]); + expect(sql.rows("SELECT sid_hash FROM sessions").map((r) => r.sid_hash)).toEqual(["b"]); + expect(sql.rows("SELECT COUNT(*) AS n FROM projects")[0]!.n).toBe(1); + }); + + it("the scheduled handler runs the sweep", async () => { + const { env, sql } = setup(); + sql.db.prepare("INSERT INTO daily (token, day, metric, key, count) VALUES ('gc_x', '2020-01-01', 'sessions', '', 1)").run(); + const waits: Promise[] = []; + await worker.scheduled({}, env, { waitUntil: (p) => waits.push(p) }); + await Promise.all(waits); + expect(sql.rows("SELECT COUNT(*) AS n FROM daily")[0]!.n).toBe(0); + }); +}); diff --git a/telemetry-worker/test/index.test.ts b/telemetry-worker/test/index.test.ts index f397a39a..c7005fba 100644 --- a/telemetry-worker/test/index.test.ts +++ b/telemetry-worker/test/index.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from "vitest"; import { gunzipSync } from "node:zlib"; -import { handle, MAX_BODY_BYTES, MAX_EVENTS, validate } from "../src/index.js"; +import { handle, MAX_BODY_BYTES, MAX_EVENTS, validate } from "../src/collector.js"; function bucket() { const puts: { key: string; body: Uint8Array }[] = []; diff --git a/telemetry-worker/wrangler.toml b/telemetry-worker/wrangler.toml index a86dadfe..6d2f25a7 100644 --- a/telemetry-worker/wrangler.toml +++ b/telemetry-worker/wrangler.toml @@ -8,9 +8,40 @@ workers_dev = true # Never log request contents: no observability/logpush of request bodies or headers. logpush = false +# genclass.dev paths that the site (worker `genclass-site`, custom domain) does not serve. Routes run in front of +# the custom domain; unknown paths under /start* and /dashboard* are passed to the site (service binding SITE). +routes = [ + { pattern = "genclass.dev/dashboard*", zone_name = "genclass.dev" }, + { pattern = "genclass.dev/start*", zone_name = "genclass.dev" }, + { pattern = "genclass.dev/api/*", zone_name = "genclass.dev" }, +] + [observability] enabled = false [[r2_buckets]] binding = "BUCKET" bucket_name = "genclass-telemetry" + +# Per-app tokens and dashboards (see README). D1 holds projects and aggregates; created 2026-10-10. +[[d1_databases]] +binding = "DB" +database_name = "genclass-dashboard" +database_id = "694d7d16-8a47-4810-8e0d-e9c89533460a" +migrations_dir = "migrations" + +# Project creation: 10 per 60 s per client (keyed by a hash of the client IP, never stored). +[[ratelimits]] +name = "CREATE_LIMITER" +namespace_id = "7301" +simple = { limit = 10, period = 60 } + +# Read-only use of the site worker: unknown genclass.dev/start* and /dashboard* paths are handed to it unchanged. +[[services]] +binding = "SITE" +service = "genclass-site" + +# Daily retention sweep of dashboard rows (03:17 UTC). +[triggers] +crons = ["17 3 * * *"] + From 6d93e8183c84b072740793eb5dc66b34c78b893e Mon Sep 17 00:00:00 2001 From: Karan Date: Sat, 10 Oct 2026 00:25:41 -0400 Subject: [PATCH 5/5] docs(agents): point at the deployed dashboard server files Co-Authored-By: Claude Opus 5.5 --- docs/agents/dashboard-projects.md | 5 +++-- docs/agents/telemetry.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/agents/dashboard-projects.md b/docs/agents/dashboard-projects.md index 348518c3..bd8610d9 100644 --- a/docs/agents/dashboard-projects.md +++ b/docs/agents/dashboard-projects.md @@ -27,8 +27,9 @@ | function names | `decision` events gain optional `fn` (outermost protected function in the subject op's cause chain, ≤ 80 chars) | shown as "top functions" | | retention | n/a | dashboard data deleted after 90 days | -Note: the collector on this branch (`telemetry-worker/src/index.ts` at 126026f) keeps only known top-level fields, so -it drops `token` until the server-side work lands. Do not edit `telemetry-worker/` from this workstream. +Server side: `telemetry-worker/src/collector.ts` (ingest, projects API, routing), `src/dashboard.ts` (D1 aggregation, +stats, retention), `src/pages.ts` (/start and /dashboard HTML), `migrations/` (D1 `genclass-dashboard`). Deployed on +genclass.dev routes `/start*`, `/dashboard*`, `/api/*`; see [telemetry-worker/README.md](../../telemetry-worker/README.md). ## Files diff --git a/docs/agents/telemetry.md b/docs/agents/telemetry.md index 8b154d05..6dbb4e78 100644 --- a/docs/agents/telemetry.md +++ b/docs/agents/telemetry.md @@ -44,7 +44,7 @@ | `packages/runtime/src/cdn/config.ts` | `telemetry=off` page-config key (meta tag, `data-telemetry`) | | `packages/runtime/test/telemetry.test.ts` | 13 tests: defaults, every opt-out incl. GPC, batching / bounded queue, pagehide + hidden beacon, event shapes, situation text == `stateText(req.state)` of the model input, secrets absent, transport errors, model input unchanged, native fetch not observed | | `packages/runtime/TELEMETRY.md` | public disclosure and schema (ships in the npm package) | -| `telemetry-worker/{wrangler.toml,src/index.ts,test/index.test.ts,README.md}` | collector (6 tests: `../node_modules/.bin/vitest run --root .` in `telemetry-worker/`) | +| `telemetry-worker/{wrangler.toml,src/index.ts,src/collector.ts,src/dashboard.ts,src/pages.ts,migrations/,test/,README.md}` | collector, projects API and dashboards (`index.ts` exports only the handler; 21 tests: `../node_modules/.bin/vitest run --root .` in `telemetry-worker/`) | ## Behaviour