@rebasepro/server 0.17.3 → 0.18.1

package/dist/{history-store-BUJ-37Sm.js.map → history-store-LHXaQywp.js.map}

@@ -1 +1 @@
-{"version":3,"file":"history-store-BUJ-37Sm.js","names":[],"sources":["../src/metrics/history-store.ts"],"sourcesContent":["/**\n * A little history for the metrics this process already keeps.\n *\n * ## Why this is in the framework and not in the cloud console\n *\n * The console wants to draw \"CPU over the last hour\". The obvious way to get it\n * on GKE is Cloud Monitoring, which already collects exactly this — and which\n * would make the panel unportable the day the platform moves, for a feature\n * every self-hoster also wants. So the history lives where the runtime lives:\n * the process samples ITSELF, into its OWN database, and anything that can read\n * the database can draw the chart. No cluster, no metrics-server, no vendor.\n *\n * That is the same rule the binder follows — the cloud is a better\n * implementation behind the same interface, never a different one.\n *\n * ## Why it stays cheap\n *\n * One row per series per instance per minute. Three series across two replicas\n * is 8,640 rows a day, and the sweep below bounds the window, so the table settles\n * at a size measured in megabytes. It is deliberately NOT a general time-series\n * store: no labels, no cardinality to explode, no per-request rows.\n *\n * A minute is the resolution because that is what the question needs — \"was it\n * slow at 15:40\", \"did my deploy cause that\" — and because a finer grain buys\n * nothing a reader can see on a chart of an hour.\n */\n/**\n * The positional-parameter shape every store in this package settles on.\n *\n * The bootstrapper's own `SqlExec` takes an options object; each store wraps it\n * once and reads better for it. Same two shapes, same reason, as `job-store`.\n */\nimport { revokeInternalTableSql } from \"@rebasepro/common\";\n\nexport type Exec = (sql: string, params?: unknown[]) => Promise<unknown>;\n\n/** Where the samples live. Framework-owned, like `rebase.jobs`. */\nexport const METRICS_HISTORY_TABLE = \"rebase.metric_samples\";\n\n/**\n * How long a sample is kept.\n *\n * Two weeks answers \"is this worse than last week\" and stops well short of\n * being an archive. Anything that needs to outlive it — billing, capacity\n * planning — is a rollup somebody else owns, not a longer retention here.\n *\n * Read it as \"14 days, or since this process started, whichever is longer\": the\n * sweep runs at boot and nowhere else, so a pod up for 90 days holds 90 days.\n * That is a deliberate trade rather than an oversight — a cron for it would be\n * machinery for a table that stays trivial either way, and reads are bounded by\n * the index regardless — but the table does not \"reach a steady size and stay\n * there\" on a long-lived pod, which an earlier version of this comment claimed.\n */\nexport const RETENTION_DAYS = 14;\n\n/** How often the process samples itself. Matched to the resolution it stores. */\nexport const SAMPLE_INTERVAL_MS = 60_000;\n\n/**\n * The series this records. A closed set on purpose — see the cardinality note.\n *\n * A list rather than only a union, because the route validates against it: an\n * unknown `?series=` must be a named 400 rather than an empty chart, which\n * reads exactly like a quiet period.\n *\n * **It lists what `sampleSelf` actually writes, and nothing else.** It used to\n * also name `requests_total`, `errors_total` and `event_loop_delay_ms`, none of\n * which anything ever recorded — so those three were *valid* parameters that\n * returned `points: []`, which is precisely the empty chart the 400 two\n * paragraphs up exists to prevent. A declared-but-unwritten series is worse\n * than an absent one: the 400 tells you the name is wrong, and the empty array\n * tells you the app was quiet.\n *\n * `event_loop_delay_ms` kept its place by gaining a sampler, because it is the\n * one signal here that says whether the process is *healthy* rather than how\n * much it is using, and it has no counter semantics to get wrong.\n *\n * `requests_total` and `errors_total` were dropped rather than wired up. The\n * registry does hold them, but they reset on restart, and a resetting counter\n * summed across replicas is not monotonic — a rolling deploy would draw a\n * cliff that looks like traffic collapsing. That needs a deliberate decision\n * about deltas and resets, not a line added at 2am. Adding either back means\n * adding its sampler in the same commit.\n */\nexport const METRIC_SERIES = [\n    \"cpu_millicores\",\n    \"memory_bytes\",\n    \"event_loop_delay_ms\"\n] as const;\n\nexport type MetricSeries = (typeof METRIC_SERIES)[number];\n\nexport interface MetricSample {\n    at: Date;\n    series: MetricSeries;\n    value: number;\n}\n\n/**\n * Create the table and sweep what has aged out.\n *\n * Called at boot, beside the job and cron stores, and for the same reason they\n * do it there: the only moment the schema is guaranteed to be reachable and\n * nobody is mid-request.\n */\nexport async function ensureMetricsHistory(exec: Exec): Promise<void> {\n    await exec(`\n        CREATE TABLE IF NOT EXISTS ${METRICS_HISTORY_TABLE} (\n            at        timestamptz      NOT NULL,\n            series    text             NOT NULL,\n            instance  text             NOT NULL,\n            value     double precision NOT NULL,\n            PRIMARY KEY (series, instance, at)\n        )\n    `, []);\n\n    // (series, at DESC) rather than the primary key's order: every read is\n    // \"this series across all instances, bounded by time\", and the PK leads with\n    // instance, which is the wrong first column for that scan.\n    await exec(`\n        CREATE INDEX IF NOT EXISTS metric_samples_series_recent\n            ON ${METRICS_HISTORY_TABLE} (series, at DESC)\n    `, []);\n\n    // Framework-internal, so the end-user role must not be able to address it.\n    //\n    // The driver grants `rebase_user` full DML across the schemas a project\n    // uses, plus `ALTER DEFAULT PRIVILEGES` so tables created later inherit it —\n    // and this one is created later, at boot. Without the revoke, an\n    // authenticated request could read and write another deployment's process\n    // metrics, and `pnpm rls:check` correctly called that `[critical]\n    // rls-disabled` the first time CI saw the table.\n    //\n    // REVOKE rather than `ENABLE ROW LEVEL SECURITY`, matching every other table\n    // in `REBASE_INTERNAL_TABLES`: RLS with no policy denies the same rows but\n    // is the weaker statement, because the grant survives and a later policy\n    // reopens it. There is no row here any end user should reach, so \"this role\n    // has no privilege at all\" is the honest encoding. The owner connection the\n    // recorder runs on is unaffected.\n    await exec(revokeInternalTableSql(\"rebase\", \"metric_samples\"), []);\n\n    // Swept here rather than by a cron, so a deployment that runs no scheduler\n    // still stays bounded. A DELETE is the right tool at this size — a few\n    // thousand rows a day — and partitioning would be machinery for a table\n    // that never gets big.\n    await exec(\n        `DELETE FROM ${METRICS_HISTORY_TABLE} WHERE at < now() - make_interval(days => $1)`,\n        [RETENTION_DAYS]\n    );\n}\n\n/**\n * What this process is using right now.\n *\n * `process.cpuUsage()` is cumulative, so a rate needs two readings and the gap\n * between them — which is why the previous one is threaded through rather than\n * held in a module global: a module global is shared by every test in a file\n * and makes the first assertion depend on whatever ran before it.\n */\nexport function sampleSelf(\n    previous: { cpu: NodeJS.CpuUsage; at: number } | null,\n    now = Date.now(),\n    /**\n     * Mean event-loop delay over the last window, in milliseconds, or undefined\n     * where it cannot be measured. Passed in rather than read here so this\n     * function stays pure: the histogram is a stateful handle the recorder owns.\n     */\n    eventLoopDelayMs?: number\n): { samples: Omit<MetricSample, \"at\">[]; cursor: { cpu: NodeJS.CpuUsage; at: number } } {\n    const cpu = process.cpuUsage();\n    const memory = process.memoryUsage();\n    const samples: Omit<MetricSample, \"at\">[] = [\n        { series: \"memory_bytes\", value: memory.rss }\n    ];\n\n    // Only when it was actually measured. Zero is a real and common reading for\n    // an idle process, so a `?? 0` here would be indistinguishable from a\n    // healthy one — the same substitution this module rejects everywhere else.\n    if (typeof eventLoopDelayMs === \"number\" && Number.isFinite(eventLoopDelayMs)) {\n        samples.push({ series: \"event_loop_delay_ms\", value: eventLoopDelayMs });\n    }\n\n    if (previous) {\n        const elapsedMs = now - previous.at;\n        if (elapsedMs > 0) {\n            // Microseconds of CPU over milliseconds of wall clock, as\n            // millicores: 1000m is one core saturated for the whole window.\n            const usedMicros = (cpu.user - previous.cpu.user) + (cpu.system - previous.cpu.system);\n            samples.push({ series: \"cpu_millicores\", value: (usedMicros / 1000 / elapsedMs) * 1000 });\n        }\n    }\n\n    return { samples, cursor: { cpu, at: now } };\n}\n\n/**\n * Write one tick's samples, for one instance.\n *\n * ## Why `instance` is part of the key\n *\n * A tenant's replicas share one database, and each records its OWN process. Key\n * a row by `(series, minute)` alone and the pods overwrite each other every\n * tick: one pod at 5m and another at 500m leave whichever wrote last, so a\n * scaled-out tenant charts one arbitrary replica and calls it the app. Adding\n * the instance makes each pod its own row, and lets the read decide whether the\n * question is \"the whole deployment\" or \"which pod is hot\".\n *\n * Cardinality stays bounded: rows are series × replicas × minutes, and replicas\n * are capped by the autoscaling ceiling. Six pods is ~43k rows a day and a\n * fortnight of them is well under a million.\n */\nexport async function recordSamples(\n    exec: Exec,\n    samples: Omit<MetricSample, \"at\">[],\n    instance: string,\n    at: Date = new Date()\n): Promise<void> {\n    if (samples.length === 0) return;\n    // Truncated to the minute, so a pod restarting mid-minute overwrites its own\n    // earlier row rather than adding a second one for the same instant.\n    const bucket = new Date(Math.floor(at.getTime() / 60_000) * 60_000);\n    for (const s of samples) {\n        if (!Number.isFinite(s.value)) continue;\n        await exec(\n            `INSERT INTO ${METRICS_HISTORY_TABLE} (at, series, instance, value)\n             VALUES ($1, $2, $3, $4)\n             ON CONFLICT (series, instance, at) DO UPDATE SET value = EXCLUDED.value`,\n            [bucket, s.series, instance, s.value]\n        );\n    }\n}\n\n/**\n * How a series combines across the replicas that reported it.\n *\n * Not one answer for everything, because the right one differs by what the\n * number means. CPU and memory are consumption: the deployment's figure is the\n * sum, and a mean would make scaling out look like it reduced usage. A queue\n * depth or an event-loop delay is a condition each process is independently in,\n * and summing those produces a number no single pod ever experienced.\n */\nconst COMBINE: Record<MetricSeries, \"sum\" | \"avg\"> = {\n    cpu_millicores: \"sum\",\n    memory_bytes: \"sum\",\n    event_loop_delay_ms: \"avg\"\n};\n\nexport interface SeriesPoint {\n    at: string;\n    /** The deployment's figure, combined per `COMBINE`. */\n    value: number;\n    /** How many instances reported in this bucket. */\n    instances: number;\n}\n\n/**\n * Read one series over a window, oldest first — the order a chart draws in.\n *\n * Combined across instances rather than returned per-pod. A chart of \"this\n * app's CPU\" is the question people ask; \"which pod is hot\" is answered by the\n * live panel, which already lists instances individually and does not need\n * history to do it.\n *\n * `instances` rides along because a sum whose contributor count changed is not\n * comparable with itself: CPU doubling because the app got busy and CPU\n * doubling because it scaled from one replica to two are different events, and\n * a line chart alone cannot tell them apart.\n */\nexport async function readSeries(\n    exec: Exec,\n    series: MetricSeries,\n    sinceMinutes: number\n): Promise<SeriesPoint[]> {\n    const combine = COMBINE[series] === \"avg\" ? \"avg\" : \"sum\";\n    // The current minute is EXCLUDED, and that is not tidiness.\n    //\n    // Each replica samples on its own phase — `setInterval` from whenever that\n    // pod booted — so at 10:45:20 the bucket for 10:45 holds rows from whichever\n    // pods have ticked so far, typically one of three. The chart takes the last\n    // point as its headline figure, so a three-replica app displayed one\n    // replica's CPU as the deployment's, the line ended in a cliff, and the\n    // instance step dropped underneath it — which the chart's own caption\n    // explains to the reader as a scale-down that never happened.\n    //\n    // Every live pod has written bucket M-1 before the clock enters M, so the\n    // newest bucket returned is complete and its `instances` is the true\n    // contributor count. `date_trunc` rather than arithmetic because it matches\n    // the recorder's `floor(t / 60_000) * 60_000` exactly, and is\n    // timezone-independent on a timestamptz.\n    const rows = await exec(\n        `SELECT at, ${combine}(value) AS value, count(*) AS instances\n           FROM ${METRICS_HISTORY_TABLE}\n          WHERE series = $1\n            AND at >= now() - make_interval(mins => $2)\n            AND at < date_trunc('minute', now())\n          GROUP BY at\n          ORDER BY at ASC`,\n        [series, sinceMinutes]\n    ) as unknown as { rows?: RawPoint[] } | RawPoint[];\n\n    const list = Array.isArray(rows) ? rows : (rows?.rows ?? []);\n    return list.map(r => ({\n        at: r.at instanceof Date ? r.at.toISOString() : String(r.at),\n        value: Number(r.value),\n        instances: Number(r.instances ?? 1)\n    }));\n}\n\ninterface RawPoint { at: Date | string; value: number; instances?: number | string }\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,wBAAwB;;AAmBrC,IAAa,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BlC,IAAa,gBAAgB;CACzB;CACA;CACA;AACJ;;;;;;;;AAiBA,eAAsB,qBAAqB,MAA2B;CAClE,MAAM,KAAK;qCACsB,sBAAsB;;;;;;;OAOpD,CAAC,CAAC;CAKL,MAAM,KAAK;;iBAEE,sBAAsB;OAChC,CAAC,CAAC;CAiBL,MAAM,KAAK,uBAAuB,UAAU,gBAAgB,GAAG,CAAC,CAAC;CAMjE,MAAM,KACF,eAAe,sBAAsB,gDACrC,CAAA,EAAe,CACnB;AACJ;;;;;;;;;AAUA,SAAgB,WACZ,UACA,MAAM,KAAK,IAAI,GAMf,kBACqF;CACrF,MAAM,MAAM,QAAQ,SAAS;CAE7B,MAAM,UAAsC,CACxC;EAAE,QAAQ;EAAgB,OAFf,QAAQ,YAEc,CAAA,CAAO;CAAI,CAChD;CAKA,IAAI,OAAO,qBAAqB,YAAY,OAAO,SAAS,gBAAgB,GACxE,QAAQ,KAAK;EAAE,QAAQ;EAAuB,OAAO;CAAiB,CAAC;CAG3E,IAAI,UAAU;EACV,MAAM,YAAY,MAAM,SAAS;EACjC,IAAI,YAAY,GAAG;GAGf,MAAM,aAAc,IAAI,OAAO,SAAS,IAAI,QAAS,IAAI,SAAS,SAAS,IAAI;GAC/E,QAAQ,KAAK;IAAE,QAAQ;IAAkB,OAAQ,aAAa,MAAO,YAAa;GAAK,CAAC;EAC5F;CACJ;CAEA,OAAO;EAAE;EAAS,QAAQ;GAAE;GAAK,IAAI;EAAI;CAAE;AAC/C;;;;;;;;;;;;;;;;;AAkBA,eAAsB,cAClB,MACA,SACA,UACA,qBAAW,IAAI,KAAK,GACP;CACb,IAAI,QAAQ,WAAW,GAAG;CAG1B,MAAM,yBAAS,IAAI,KAAK,KAAK,MAAM,GAAG,QAAQ,IAAI,GAAM,IAAI,GAAM;CAClE,KAAK,MAAM,KAAK,SAAS;EACrB,IAAI,CAAC,OAAO,SAAS,EAAE,KAAK,GAAG;EAC/B,MAAM,KACF,eAAe,sBAAsB;;uFAGrC;GAAC;GAAQ,EAAE;GAAQ;GAAU,EAAE;EAAK,CACxC;CACJ;AACJ;;;;;;;;;;AAWA,IAAM,UAA+C;CACjD,gBAAgB;CAChB,cAAc;CACd,qBAAqB;AACzB;;;;;;;;;;;;;;AAuBA,eAAsB,WAClB,MACA,QACA,cACsB;CAiBtB,MAAM,OAAO,MAAM,KACf,cAjBY,QAAQ,YAAY,QAAQ,QAAQ,MAiB1B;kBACZ,sBAAsB;;;;;4BAMhC,CAAC,QAAQ,YAAY,CACzB;CAGA,QADa,MAAM,QAAQ,IAAI,IAAI,OAAQ,MAAM,QAAQ,CAAC,EAAA,CAC9C,KAAI,OAAM;EAClB,IAAI,EAAE,cAAc,OAAO,EAAE,GAAG,YAAY,IAAI,OAAO,EAAE,EAAE;EAC3D,OAAO,OAAO,EAAE,KAAK;EACrB,WAAW,OAAO,EAAE,aAAa,CAAC;CACtC,EAAE;AACN"}
+{"version":3,"file":"history-store-LHXaQywp.js","names":[],"sources":["../src/metrics/history-store.ts"],"sourcesContent":["/**\n * A little history for the metrics this process already keeps.\n *\n * ## Why this is in the framework and not in the cloud console\n *\n * The console wants to draw \"CPU over the last hour\". The obvious way to get it\n * on GKE is Cloud Monitoring, which already collects exactly this — and which\n * would make the panel unportable the day the platform moves, for a feature\n * every self-hoster also wants. So the history lives where the runtime lives:\n * the process samples ITSELF, into its OWN database, and anything that can read\n * the database can draw the chart. No cluster, no metrics-server, no vendor.\n *\n * That is the same rule the binder follows — the cloud is a better\n * implementation behind the same interface, never a different one.\n *\n * ## Why it stays cheap\n *\n * One row per series per instance per minute. Three series across two replicas\n * is 8,640 rows a day, and the sweep below bounds the window, so the table settles\n * at a size measured in megabytes. It is deliberately NOT a general time-series\n * store: no labels, no cardinality to explode, no per-request rows.\n *\n * A minute is the resolution because that is what the question needs — \"was it\n * slow at 15:40\", \"did my deploy cause that\" — and because a finer grain buys\n * nothing a reader can see on a chart of an hour.\n */\n/**\n * The positional-parameter shape every store in this package settles on.\n *\n * The bootstrapper's own `SqlExec` takes an options object; each store wraps it\n * once and reads better for it. Same two shapes, same reason, as `job-store`.\n */\nimport { revokeInternalTableSql } from \"@rebasepro/common\";\n\nexport type Exec = (sql: string, params?: unknown[]) => Promise<unknown>;\n\n/** Where the samples live. Framework-owned, like `rebase.jobs`. */\nexport const METRICS_HISTORY_TABLE = \"rebase.metric_samples\";\n\n/**\n * How long a sample is kept.\n *\n * Two weeks answers \"is this worse than last week\" and stops well short of\n * being an archive. Anything that needs to outlive it — billing, capacity\n * planning — is a rollup somebody else owns, not a longer retention here.\n *\n * Read it as \"14 days, or since this process started, whichever is longer\": the\n * sweep runs at boot and nowhere else, so a pod up for 90 days holds 90 days.\n * That is a deliberate trade rather than an oversight — a cron for it would be\n * machinery for a table that stays trivial either way, and reads are bounded by\n * the index regardless — but the table does not \"reach a steady size and stay\n * there\" on a long-lived pod, which an earlier version of this comment claimed.\n */\nexport const RETENTION_DAYS = 14;\n\n/** How often the process samples itself. Matched to the resolution it stores. */\nexport const SAMPLE_INTERVAL_MS = 60_000;\n\n/**\n * The series this records. A closed set on purpose — see the cardinality note.\n *\n * A list rather than only a union, because the route validates against it: an\n * unknown `?series=` must be a named 400 rather than an empty chart, which\n * reads exactly like a quiet period.\n *\n * **It lists what `sampleSelf` actually writes, and nothing else.** It used to\n * also name `requests_total`, `errors_total` and `event_loop_delay_ms`, none of\n * which anything ever recorded — so those three were *valid* parameters that\n * returned `points: []`, which is precisely the empty chart the 400 two\n * paragraphs up exists to prevent. A declared-but-unwritten series is worse\n * than an absent one: the 400 tells you the name is wrong, and the empty array\n * tells you the app was quiet.\n *\n * `event_loop_delay_ms` kept its place by gaining a sampler, because it is the\n * one signal here that says whether the process is *healthy* rather than how\n * much it is using, and it has no counter semantics to get wrong.\n *\n * `requests_total` and `errors_total` were dropped rather than wired up. The\n * registry does hold them, but they reset on restart, and a resetting counter\n * summed across replicas is not monotonic — a rolling deploy would draw a\n * cliff that looks like traffic collapsing. That needs a deliberate decision\n * about deltas and resets, not a line added at 2am. Adding either back means\n * adding its sampler in the same commit.\n */\nexport const METRIC_SERIES = [\n    \"cpu_millicores\",\n    \"memory_bytes\",\n    \"event_loop_delay_ms\"\n] as const;\n\nexport type MetricSeries = (typeof METRIC_SERIES)[number];\n\nexport interface MetricSample {\n    at: Date;\n    series: MetricSeries;\n    value: number;\n}\n\n/**\n * Create the table and sweep what has aged out.\n *\n * Called at boot, beside the job and cron stores, and for the same reason they\n * do it there: the only moment the schema is guaranteed to be reachable and\n * nobody is mid-request.\n */\nexport async function ensureMetricsHistory(exec: Exec): Promise<void> {\n    await exec(`\n        CREATE TABLE IF NOT EXISTS ${METRICS_HISTORY_TABLE} (\n            at        timestamptz      NOT NULL,\n            series    text             NOT NULL,\n            instance  text             NOT NULL,\n            value     double precision NOT NULL,\n            PRIMARY KEY (series, instance, at)\n        )\n    `, []);\n\n    // (series, at DESC) rather than the primary key's order: every read is\n    // \"this series across all instances, bounded by time\", and the PK leads with\n    // instance, which is the wrong first column for that scan.\n    await exec(`\n        CREATE INDEX IF NOT EXISTS metric_samples_series_recent\n            ON ${METRICS_HISTORY_TABLE} (series, at DESC)\n    `, []);\n\n    // Framework-internal, so the end-user role must not be able to address it.\n    //\n    // The driver grants `rebase_user` full DML across the schemas a project\n    // uses, plus `ALTER DEFAULT PRIVILEGES` so tables created later inherit it —\n    // and this one is created later, at boot. Without the revoke, an\n    // authenticated request could read and write another deployment's process\n    // metrics, and `pnpm rls:check` correctly called that `[critical]\n    // rls-disabled` the first time CI saw the table.\n    //\n    // REVOKE rather than `ENABLE ROW LEVEL SECURITY`, matching every other table\n    // in `REBASE_INTERNAL_TABLES`: RLS with no policy denies the same rows but\n    // is the weaker statement, because the grant survives and a later policy\n    // reopens it. There is no row here any end user should reach, so \"this role\n    // has no privilege at all\" is the honest encoding. The owner connection the\n    // recorder runs on is unaffected.\n    await exec(revokeInternalTableSql(\"rebase\", \"metric_samples\"), []);\n\n    // Swept here rather than by a cron, so a deployment that runs no scheduler\n    // still stays bounded. A DELETE is the right tool at this size — a few\n    // thousand rows a day — and partitioning would be machinery for a table\n    // that never gets big.\n    await exec(\n        `DELETE FROM ${METRICS_HISTORY_TABLE} WHERE at < now() - make_interval(days => $1)`,\n        [RETENTION_DAYS]\n    );\n}\n\n/**\n * What this process is using right now.\n *\n * `process.cpuUsage()` is cumulative, so a rate needs two readings and the gap\n * between them — which is why the previous one is threaded through rather than\n * held in a module global: a module global is shared by every test in a file\n * and makes the first assertion depend on whatever ran before it.\n */\nexport function sampleSelf(\n    previous: { cpu: NodeJS.CpuUsage; at: number } | null,\n    now = Date.now(),\n    /**\n     * Mean event-loop delay over the last window, in milliseconds, or undefined\n     * where it cannot be measured. Passed in rather than read here so this\n     * function stays pure: the histogram is a stateful handle the recorder owns.\n     */\n    eventLoopDelayMs?: number\n): { samples: Omit<MetricSample, \"at\">[]; cursor: { cpu: NodeJS.CpuUsage; at: number } } {\n    const cpu = process.cpuUsage();\n    const memory = process.memoryUsage();\n    const samples: Omit<MetricSample, \"at\">[] = [\n        { series: \"memory_bytes\", value: memory.rss }\n    ];\n\n    // Only when it was actually measured. Zero is a real and common reading for\n    // an idle process, so a `?? 0` here would be indistinguishable from a\n    // healthy one — the same substitution this module rejects everywhere else.\n    if (typeof eventLoopDelayMs === \"number\" && Number.isFinite(eventLoopDelayMs)) {\n        samples.push({ series: \"event_loop_delay_ms\", value: eventLoopDelayMs });\n    }\n\n    if (previous) {\n        const elapsedMs = now - previous.at;\n        if (elapsedMs > 0) {\n            // Microseconds of CPU over milliseconds of wall clock, as\n            // millicores: 1000m is one core saturated for the whole window.\n            const usedMicros = (cpu.user - previous.cpu.user) + (cpu.system - previous.cpu.system);\n            samples.push({ series: \"cpu_millicores\", value: (usedMicros / 1000 / elapsedMs) * 1000 });\n        }\n    }\n\n    return { samples, cursor: { cpu, at: now } };\n}\n\n/**\n * Write one tick's samples, for one instance.\n *\n * ## Why `instance` is part of the key\n *\n * A tenant's replicas share one database, and each records its OWN process. Key\n * a row by `(series, minute)` alone and the pods overwrite each other every\n * tick: one pod at 5m and another at 500m leave whichever wrote last, so a\n * scaled-out tenant charts one arbitrary replica and calls it the app. Adding\n * the instance makes each pod its own row, and lets the read decide whether the\n * question is \"the whole deployment\" or \"which pod is hot\".\n *\n * Cardinality stays bounded: rows are series × replicas × minutes, and replicas\n * are capped by the autoscaling ceiling. Six pods is ~43k rows a day and a\n * fortnight of them is well under a million.\n */\nexport async function recordSamples(\n    exec: Exec,\n    samples: Omit<MetricSample, \"at\">[],\n    instance: string,\n    at: Date = new Date()\n): Promise<void> {\n    if (samples.length === 0) return;\n    // Truncated to the minute, so a pod restarting mid-minute overwrites its own\n    // earlier row rather than adding a second one for the same instant.\n    const bucket = new Date(Math.floor(at.getTime() / 60_000) * 60_000);\n    for (const s of samples) {\n        if (!Number.isFinite(s.value)) continue;\n        await exec(\n            `INSERT INTO ${METRICS_HISTORY_TABLE} (at, series, instance, value)\n             VALUES ($1, $2, $3, $4)\n             ON CONFLICT (series, instance, at) DO UPDATE SET value = EXCLUDED.value`,\n            [bucket, s.series, instance, s.value]\n        );\n    }\n}\n\n/**\n * How a series combines across the replicas that reported it.\n *\n * Not one answer for everything, because the right one differs by what the\n * number means. CPU and memory are consumption: the deployment's figure is the\n * sum, and a mean would make scaling out look like it reduced usage. A queue\n * depth or an event-loop delay is a condition each process is independently in,\n * and summing those produces a number no single pod ever experienced.\n */\nconst COMBINE: Record<MetricSeries, \"sum\" | \"avg\"> = {\n    cpu_millicores: \"sum\",\n    memory_bytes: \"sum\",\n    event_loop_delay_ms: \"avg\"\n};\n\nexport interface SeriesPoint {\n    at: string;\n    /** The deployment's figure, combined per `COMBINE`. */\n    value: number;\n    /** How many instances reported in this bucket. */\n    instances: number;\n}\n\n/**\n * Read one series over a window, oldest first — the order a chart draws in.\n *\n * Combined across instances rather than returned per-pod. A chart of \"this\n * app's CPU\" is the question people ask; \"which pod is hot\" is answered by the\n * live panel, which already lists instances individually and does not need\n * history to do it.\n *\n * `instances` rides along because a sum whose contributor count changed is not\n * comparable with itself: CPU doubling because the app got busy and CPU\n * doubling because it scaled from one replica to two are different events, and\n * a line chart alone cannot tell them apart.\n */\nexport async function readSeries(\n    exec: Exec,\n    series: MetricSeries,\n    sinceMinutes: number\n): Promise<SeriesPoint[]> {\n    const combine = COMBINE[series] === \"avg\" ? \"avg\" : \"sum\";\n    // The current minute is EXCLUDED, and that is not tidiness.\n    //\n    // Each replica samples on its own phase — `setInterval` from whenever that\n    // pod booted — so at 10:45:20 the bucket for 10:45 holds rows from whichever\n    // pods have ticked so far, typically one of three. The chart takes the last\n    // point as its headline figure, so a three-replica app displayed one\n    // replica's CPU as the deployment's, the line ended in a cliff, and the\n    // instance step dropped underneath it — which the chart's own caption\n    // explains to the reader as a scale-down that never happened.\n    //\n    // Every live pod has written bucket M-1 before the clock enters M, so the\n    // newest bucket returned is complete and its `instances` is the true\n    // contributor count. `date_trunc` rather than arithmetic because it matches\n    // the recorder's `floor(t / 60_000) * 60_000` exactly, and is\n    // timezone-independent on a timestamptz.\n    const rows = await exec(\n        `SELECT at, ${combine}(value) AS value, count(*) AS instances\n           FROM ${METRICS_HISTORY_TABLE}\n          WHERE series = $1\n            AND at >= now() - make_interval(mins => $2)\n            AND at < date_trunc('minute', now())\n          GROUP BY at\n          ORDER BY at ASC`,\n        [series, sinceMinutes]\n    ) as unknown as { rows?: RawPoint[] } | RawPoint[];\n\n    const list = Array.isArray(rows) ? rows : (rows?.rows ?? []);\n    return list.map(r => ({\n        at: r.at instanceof Date ? r.at.toISOString() : String(r.at),\n        value: Number(r.value),\n        instances: Number(r.instances ?? 1)\n    }));\n}\n\ninterface RawPoint { at: Date | string; value: number; instances?: number | string }\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,wBAAwB;;AAmBrC,IAAa,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BlC,IAAa,gBAAgB;CACzB;CACA;CACA;AACJ;;;;;;;;AAiBA,eAAsB,qBAAqB,MAA2B;CAClE,MAAM,KAAK;qCACsB,sBAAsB;;;;;;;OAOpD,CAAC,CAAC;CAKL,MAAM,KAAK;;iBAEE,sBAAsB;OAChC,CAAC,CAAC;CAiBL,MAAM,KAAK,uBAAuB,UAAU,gBAAgB,GAAG,CAAC,CAAC;CAMjE,MAAM,KACF,eAAe,sBAAsB,gDACrC,CAAA,EAAe,CACnB;AACJ;;;;;;;;;AAUA,SAAgB,WACZ,UACA,MAAM,KAAK,IAAI,GAMf,kBACqF;CACrF,MAAM,MAAM,QAAQ,SAAS;CAE7B,MAAM,UAAsC,CACxC;EAAE,QAAQ;EAAgB,OAFf,QAAQ,YAEc,CAAA,CAAO;CAAI,CAChD;CAKA,IAAI,OAAO,qBAAqB,YAAY,OAAO,SAAS,gBAAgB,GACxE,QAAQ,KAAK;EAAE,QAAQ;EAAuB,OAAO;CAAiB,CAAC;CAG3E,IAAI,UAAU;EACV,MAAM,YAAY,MAAM,SAAS;EACjC,IAAI,YAAY,GAAG;GAGf,MAAM,aAAc,IAAI,OAAO,SAAS,IAAI,QAAS,IAAI,SAAS,SAAS,IAAI;GAC/E,QAAQ,KAAK;IAAE,QAAQ;IAAkB,OAAQ,aAAa,MAAO,YAAa;GAAK,CAAC;EAC5F;CACJ;CAEA,OAAO;EAAE;EAAS,QAAQ;GAAE;GAAK,IAAI;EAAI;CAAE;AAC/C;;;;;;;;;;;;;;;;;AAkBA,eAAsB,cAClB,MACA,SACA,UACA,qBAAW,IAAI,KAAK,GACP;CACb,IAAI,QAAQ,WAAW,GAAG;CAG1B,MAAM,yBAAS,IAAI,KAAK,KAAK,MAAM,GAAG,QAAQ,IAAI,GAAM,IAAI,GAAM;CAClE,KAAK,MAAM,KAAK,SAAS;EACrB,IAAI,CAAC,OAAO,SAAS,EAAE,KAAK,GAAG;EAC/B,MAAM,KACF,eAAe,sBAAsB;;uFAGrC;GAAC;GAAQ,EAAE;GAAQ;GAAU,EAAE;EAAK,CACxC;CACJ;AACJ;;;;;;;;;;AAWA,IAAM,UAA+C;CACjD,gBAAgB;CAChB,cAAc;CACd,qBAAqB;AACzB;;;;;;;;;;;;;;AAuBA,eAAsB,WAClB,MACA,QACA,cACsB;CAiBtB,MAAM,OAAO,MAAM,KACf,cAjBY,QAAQ,YAAY,QAAQ,QAAQ,MAiB1B;kBACZ,sBAAsB;;;;;4BAMhC,CAAC,QAAQ,YAAY,CACzB;CAGA,QADa,MAAM,QAAQ,IAAI,IAAI,OAAQ,MAAM,QAAQ,CAAC,EAAA,CAC9C,KAAI,OAAM;EAClB,IAAI,EAAE,cAAc,OAAO,EAAE,GAAG,YAAY,IAAI,OAAO,EAAE,EAAE;EAC3D,OAAO,OAAO,EAAE,KAAK;EACrB,WAAW,OAAO,EAAE,aAAa,CAAC;CACtC,EAAE;AACN"}

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { resolveRequireAuth } from "./auth/require-auth.js";
 export type { RebaseBackendConfig, RebaseBackendInstance, RebaseAuthConfig, BaasOptions } from "./init.js";
 export { rebase, _setRebaseMock, _resetRebaseMock } from "./singleton.js";
 export { loadCollectionsFromDirectory, applyCollectionDefaults, type CollectionDefaults } from "./collections/loader.js";
-export { assertCollectionConfigs, findCollectionConfigProblems, unknownKeyPolicyFromEnv, type ConfigProblem, type UnknownKeyPolicy, type ValidateCollectionConfigOptions } from "./collections/validate-config.js";
+export { assertCollectionConfigs, CollectionConfigError, findCollectionConfigProblems, unknownKeyPolicyFromEnv, type ConfigProblem, type UnknownKeyPolicy, type ValidateCollectionConfigOptions } from "./collections/validate-config.js";
 export * from "./db/interfaces.js";
 export * from "./auth/interfaces.js";
 export { requireAuth, requireAdmin, optionalAuth, queryTokenAuth, fileTokenAuth, extractUserFromToken, hashPassword, verifyPassword, validatePasswordStrength, generateSecurePassword, resolveAuthHooks, createBuiltinAuthAdapter, createCustomAuthAdapter, createGoogleProvider, createLinkedinProvider, createGitHubProvider, createMicrosoftProvider, createAppleProvider, createFacebookProvider, createTwitterProvider, createDiscordProvider, createGitLabProvider, createBitbucketProvider, createSlackProvider, createSpotifyProvider, oauthCodeFlowSchema, pkceTokenParams, providerVerifiedEmail, verifyOidcIdToken, tryVerifyOidcIdToken, isApiKeyToken, validateApiKey, httpMethodToOperation, isOperationAllowed, safeCompare, getJwks, hasAsymmetricSigningKey, createJwksRoutes, configureJwt } from "./auth/index.js";
@@ -38,10 +38,20 @@ export type { LoadedCronJob, CronStore } from "./cron/index.js";
 export { createBackupRoutes, parseBackupDestination, parseBackupTimestamp, listBackupObjects, readBackupBytes } from "./backup/index.js";
 export type { BackupRoutesConfig, BackupDestination } from "./backup/index.js";
 export { authUid, authRoles, authJwt } from "./utils/sql.js";
-export { logger } from "./utils/logger.js";
+export { logger, rawQueryLoggingEnabled } from "./utils/logger.js";
 export type { Logger } from "./utils/logger.js";
 export { loadEnv } from "./env.js";
 export type { RebaseEnv } from "./env.js";
+/**
+ * The runtime's own Zod instance.
+ *
+ * `loadEnv({ extend })` composes the caller's schema with the framework's, so
+ * the two schemas must come from the same copy of zod: a schema built against
+ * a second, duplicated zod fails the framework's `instanceof` checks and the
+ * extension is silently dropped. Importing `z` from here instead of from
+ * `"zod"` makes that impossible to get wrong, whatever the installer resolved.
+ */
+export { z } from "zod";
 export * from "./types/index.js";
 export * from "./services/driver-registry.js";
 export * from "./services/webhook-service.js";
@@ -61,8 +71,10 @@ export type { LoadedBundle, BundleConfigExports } from "./boot/bundle.js";
 export { loadBootEnv, resolveCorsOrigin, isLocalhostOrigin } from "./boot/env.js";
 export type { RebaseBootEnv, CorsOriginResolver } from "./boot/env.js";
 export { resolveAuthOptions, resolveEmailOptions } from "./boot/options.js";
-export { envSuffixForKey, assertDistinctSuffixes, loadDeclaredStorageSources, resolveDataSources, resolveStorageSources, resolveStorageBackend } from "./boot/sources.js";
-export type { ResolvedDataSourceConfig, EnvBag } from "./boot/sources.js";
+export { ACCOUNT_SCOPED_STORAGE_BASES, envSuffixForKey, assertDistinctSuffixes, resolveDataSources, resolveStorageSources, resolveStorageBackend } from "./boot/sources.js";
+export type { ResolvedDataSourceConfig, EnvBag, ResolveStorageOptions } from "./boot/sources.js";
+export { registerResourceResolver, resourceResolver, resourceResolvers, assertEveryKindBindable, unbindableKinds, implicitDeclaration } from "./boot/resource-resolvers.js";
+export type { ResourceResolver, ResourceResolution, ResolveContext } from "./boot/resource-resolvers.js";
 export { initializeDataSource, initializeDataSources } from "./boot/driver.js";
 export type { InitializedDataSource, DriverConnection, BundleSchema } from "./boot/driver.js";
 export { MetricsRegistry, createMetricsMiddleware, createMetricsRoutes, classifySurface } from "./metrics/index.js";