@rebasepro/server 0.33.1 → 0.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/dist/{GCSStorageController-kCv5MH2B.js → GCSStorageController-DKv7oDo7.js} +3 -3
  2. package/dist/{GCSStorageController-kCv5MH2B.js.map → GCSStorageController-DKv7oDo7.js.map} +1 -1
  3. package/dist/{S3StorageController-DqK533Sl.js → S3StorageController-CIQ2_mC5.js} +3 -3
  4. package/dist/{S3StorageController-DqK533Sl.js.map → S3StorageController-CIQ2_mC5.js.map} +1 -1
  5. package/dist/{access-CRQBlEZY.js → access-BdsIXo_L.js} +4 -4
  6. package/dist/{access-CRQBlEZY.js.map → access-BdsIXo_L.js.map} +1 -1
  7. package/dist/api/rest/api-generator.d.ts +11 -1
  8. package/dist/auth/api-keys/api-key-routes.d.ts +10 -1
  9. package/dist/auth/auth-hooks.d.ts +1 -1
  10. package/dist/auth/builtin-auth-adapter.d.ts +2 -0
  11. package/dist/auth/capabilities.d.ts +12 -0
  12. package/dist/auth/platform-signin-routes.d.ts +85 -0
  13. package/dist/auth/platform-token.d.ts +33 -0
  14. package/dist/auth/routes.d.ts +8 -0
  15. package/dist/auth/scope-routes.d.ts +7 -0
  16. package/dist/auth/seed-admin.d.ts +2 -0
  17. package/dist/{auth-BmwAqVP4.js → auth-CHOmnYwu.js} +370 -22
  18. package/dist/auth-CHOmnYwu.js.map +1 -0
  19. package/dist/{backup-CVNce2jz.js → backup-M37yPYpz.js} +6 -6
  20. package/dist/{backup-CVNce2jz.js.map → backup-M37yPYpz.js.map} +1 -1
  21. package/dist/boot/bundle.d.ts +12 -0
  22. package/dist/boot/env.d.ts +1 -0
  23. package/dist/{branch-routes-aLDaGOD1.js → branch-routes-Cl-Oa3CL.js} +2 -2
  24. package/dist/{branch-routes-aLDaGOD1.js.map → branch-routes-Cl-Oa3CL.js.map} +1 -1
  25. package/dist/{contract-routes-a4ZbN1h3.js → contract-routes-Dkxl-2B_.js} +3 -3
  26. package/dist/{contract-routes-a4ZbN1h3.js.map → contract-routes-Dkxl-2B_.js.map} +1 -1
  27. package/dist/{cron-loader-CWhyA5eR.js → cron-loader-BWahenzQ.js} +2 -2
  28. package/dist/{cron-loader-CWhyA5eR.js.map → cron-loader-BWahenzQ.js.map} +1 -1
  29. package/dist/{cron-routes-CMGAz1my.js → cron-routes-Cq6O3oPR.js} +4 -4
  30. package/dist/{cron-routes-CMGAz1my.js.map → cron-routes-Cq6O3oPR.js.map} +1 -1
  31. package/dist/{cron-scheduler-DQBdkkfb.js → cron-scheduler-B25NuV7o.js} +2 -2
  32. package/dist/{cron-scheduler-DQBdkkfb.js.map → cron-scheduler-B25NuV7o.js.map} +1 -1
  33. package/dist/{cron-store-CjUydRyp.js → cron-store-B1IStnKM.js} +2 -2
  34. package/dist/{cron-store-CjUydRyp.js.map → cron-store-B1IStnKM.js.map} +1 -1
  35. package/dist/dist-D_R0Khut.js +19354 -0
  36. package/dist/dist-D_R0Khut.js.map +1 -0
  37. package/dist/email/link-base.d.ts +21 -0
  38. package/dist/email/types.d.ts +4 -0
  39. package/dist/{filter-dialect-nsQ2ozPY.js → filter-dialect-DgWkoXt7.js} +2 -2
  40. package/dist/{filter-dialect-nsQ2ozPY.js.map → filter-dialect-DgWkoXt7.js.map} +1 -1
  41. package/dist/{function-loader-Cihj_r86.js → function-loader-C23HVFx8.js} +2 -2
  42. package/dist/{function-loader-Cihj_r86.js.map → function-loader-C23HVFx8.js.map} +1 -1
  43. package/dist/{function-routes-CWaldgEj.js → function-routes-DBKL2azw.js} +2 -2
  44. package/dist/{function-routes-CWaldgEj.js.map → function-routes-DBKL2azw.js.map} +1 -1
  45. package/dist/{history-recorder-B8TJMEfO.js → history-recorder-C5gixsU3.js} +16 -3
  46. package/dist/history-recorder-C5gixsU3.js.map +1 -0
  47. package/dist/history-store-c_cm9R3w.js +459 -0
  48. package/dist/history-store-c_cm9R3w.js.map +1 -0
  49. package/dist/index.d.ts +1 -1
  50. package/dist/index.es.js +281 -240
  51. package/dist/index.es.js.map +1 -1
  52. package/dist/{jobs-IJX3fE3X.js → jobs-uqvEGTfs.js} +2 -2
  53. package/dist/{jobs-IJX3fE3X.js.map → jobs-uqvEGTfs.js.map} +1 -1
  54. package/dist/{jwt-BuEprb39.js → jwt-B_5zx-7y.js} +3 -3
  55. package/dist/{jwt-BuEprb39.js.map → jwt-B_5zx-7y.js.map} +1 -1
  56. package/dist/{keys-C8gpPIOG.js → keys-C0g4vwP5.js} +2 -2
  57. package/dist/{keys-C8gpPIOG.js.map → keys-C0g4vwP5.js.map} +1 -1
  58. package/dist/{load-schema-BvRxAuaD.js → load-schema-aNynBztw.js} +2 -2
  59. package/dist/{load-schema-BvRxAuaD.js.map → load-schema-aNynBztw.js.map} +1 -1
  60. package/dist/{logs-routes-BAq2ZxuY.js → logs-routes-D2NGM5Pa.js} +2 -2
  61. package/dist/{logs-routes-BAq2ZxuY.js.map → logs-routes-D2NGM5Pa.js.map} +1 -1
  62. package/dist/metrics/history-recorder.d.ts +10 -1
  63. package/dist/metrics/history-store.d.ts +122 -7
  64. package/dist/metrics/index.d.ts +24 -2
  65. package/dist/{offline-ET6xI1ZO-CIdB1ilf.js → offline-ET6xI1ZO-Du75S8J1.js} +4 -4
  66. package/dist/{offline-ET6xI1ZO-CIdB1ilf.js.map → offline-ET6xI1ZO-Du75S8J1.js.map} +1 -1
  67. package/dist/{offline-store-DtmBwmKE-CzyvC_Zj.js → offline-store-DtmBwmKE-CEakGPWn.js} +3 -3
  68. package/dist/{offline-store-DtmBwmKE-CzyvC_Zj.js.map → offline-store-DtmBwmKE-CEakGPWn.js.map} +1 -1
  69. package/dist/{openapi-generator-CCLtAJ2s.js → openapi-generator-B7EbCjhN.js} +2 -2
  70. package/dist/{openapi-generator-CCLtAJ2s.js.map → openapi-generator-B7EbCjhN.js.map} +1 -1
  71. package/dist/{project-root-CuCOXvbk.js → project-root-BTQAiPki.js} +2 -2
  72. package/dist/{project-root-CuCOXvbk.js.map → project-root-BTQAiPki.js.map} +1 -1
  73. package/dist/{proxy-DUUXXoQo.js → proxy-0fGXJapt.js} +2 -2
  74. package/dist/{proxy-DUUXXoQo.js.map → proxy-0fGXJapt.js.map} +1 -1
  75. package/dist/{query-parser-C9l1eFov.js → query-parser-DwERE0rm.js} +3 -3
  76. package/dist/{query-parser-C9l1eFov.js.map → query-parser-DwERE0rm.js.map} +1 -1
  77. package/dist/{request-timeout-DOu8ItLQ.js → request-timeout-DdbFS6ef.js} +3 -3
  78. package/dist/{request-timeout-DOu8ItLQ.js.map → request-timeout-DdbFS6ef.js.map} +1 -1
  79. package/dist/{rls-simulator-routes-DIAjffhq.js → rls-simulator-routes-Cjv8yY1V.js} +3 -3
  80. package/dist/{rls-simulator-routes-DIAjffhq.js.map → rls-simulator-routes-Cjv8yY1V.js.map} +1 -1
  81. package/dist/{schema-editor-routes-qWGWBPi0.js → schema-editor-routes-CwdoGYKu.js} +4 -4
  82. package/dist/{schema-editor-routes-qWGWBPi0.js.map → schema-editor-routes-CwdoGYKu.js.map} +1 -1
  83. package/dist/{schema-tables-BneB2KZ7.js → schema-tables-DUThMxen.js} +3 -3
  84. package/dist/{schema-tables-BneB2KZ7.js.map → schema-tables-DUThMxen.js.map} +1 -1
  85. package/dist/{schema-tables-routes-BBZJK8_S.js → schema-tables-routes-Ch52xLqF.js} +4 -4
  86. package/dist/{schema-tables-routes-BBZJK8_S.js.map → schema-tables-routes-Ch52xLqF.js.map} +1 -1
  87. package/dist/{securityRuleToConditions-Cj5ZR7TS.js → securityRuleToConditions-DXPY_Z-x.js} +2 -2
  88. package/dist/{securityRuleToConditions-Cj5ZR7TS.js.map → securityRuleToConditions-DXPY_Z-x.js.map} +1 -1
  89. package/dist/{selection-BB8ejqa2.js → selection-BiTJ-Tiy.js} +2 -2
  90. package/dist/{selection-BB8ejqa2.js.map → selection-BiTJ-Tiy.js.map} +1 -1
  91. package/dist/{sql-export-routes-CPXI3qZ7.js → sql-export-routes-BYt7G2v-.js} +2 -2
  92. package/dist/{sql-export-routes-CPXI3qZ7.js.map → sql-export-routes-BYt7G2v-.js.map} +1 -1
  93. package/dist/{src-BdPKCs9u.js → src--EBfCtYm.js} +2 -2
  94. package/dist/src--EBfCtYm.js.map +1 -0
  95. package/dist/storage/routes.d.ts +6 -0
  96. package/dist/{table-source-editor-D3m_VMwN.js → table-source-editor-P5zp7lOn.js} +3 -3
  97. package/dist/{table-source-editor-D3m_VMwN.js.map → table-source-editor-P5zp7lOn.js.map} +1 -1
  98. package/package.json +5 -5
  99. package/dist/auth-BmwAqVP4.js.map +0 -1
  100. package/dist/dist-C1vNURUy.js +0 -19354
  101. package/dist/dist-C1vNURUy.js.map +0 -1
  102. package/dist/history-recorder-B8TJMEfO.js.map +0 -1
  103. package/dist/history-store-DzrJeEKv.js +0 -233
  104. package/dist/history-store-DzrJeEKv.js.map +0 -1
  105. package/dist/src-BdPKCs9u.js.map +0 -1
@@ -0,0 +1,459 @@
1
+ import { createRequire as __rebaseCreateRequire } from "module";
2
+ import __rebaseProcess from "process";
3
+ globalThis.process ??= __rebaseProcess;
4
+ __rebaseCreateRequire(import.meta.url);
5
+ import { a as revokeInternalTableSql } from "./internal-tables-XxM_NdR_.js";
6
+ import { n as sqlRows } from "./sql-rows-CIThkmuF.js";
7
+ //#region src/metrics/history-store.ts
8
+ /**
9
+ * A little history for the metrics this process already keeps.
10
+ *
11
+ * ## Why this is in the framework and not in the cloud console
12
+ *
13
+ * The console wants to draw "CPU over the last hour". The obvious way to get it
14
+ * on GKE is Cloud Monitoring, which already collects exactly this — and which
15
+ * would make the panel unportable the day the platform moves, for a feature
16
+ * every self-hoster also wants. So the history lives where the runtime lives:
17
+ * the process samples ITSELF, into its OWN database, and anything that can read
18
+ * the database can draw the chart. No cluster, no metrics-server, no vendor.
19
+ *
20
+ * That is the same rule the binder follows — the cloud is a better
21
+ * implementation behind the same interface, never a different one.
22
+ *
23
+ * ## Why it stays cheap
24
+ *
25
+ * One row per series per instance per minute. Three series across two replicas
26
+ * is 8,640 rows a day, and the sweep below bounds the window, so the table settles
27
+ * at a size measured in megabytes. It is deliberately NOT a general time-series
28
+ * store: no labels, no cardinality to explode, no per-request rows.
29
+ *
30
+ * A minute is the resolution because that is what the question needs — "was it
31
+ * slow at 15:40", "did my deploy cause that" — and because a finer grain buys
32
+ * nothing a reader can see on a chart of an hour.
33
+ */
34
+ /**
35
+ * The positional-parameter shape every store in this package settles on.
36
+ *
37
+ * The bootstrapper's own `SqlExec` takes an options object; each store wraps it
38
+ * once and reads better for it. Same two shapes, same reason, as `job-store`.
39
+ */
40
+ /** Where the samples live. Framework-owned, like `rebase.jobs`. */
41
+ var METRICS_HISTORY_TABLE = "rebase.metric_samples";
42
+ /** How often the process samples itself. Matched to the resolution it stores. */
43
+ var SAMPLE_INTERVAL_MS = 6e4;
44
+ /**
45
+ * The series this records. A closed set on purpose — see the cardinality note.
46
+ *
47
+ * A list rather than only a union, because the route validates against it: an
48
+ * unknown `?series=` must be a named 400 rather than an empty chart, which
49
+ * reads exactly like a quiet period.
50
+ *
51
+ * **It lists what `sampleSelf` actually writes, and nothing else.** It used to
52
+ * also name `requests_total`, `errors_total` and `event_loop_delay_ms`, none of
53
+ * which anything ever recorded — so those three were *valid* parameters that
54
+ * returned `points: []`, which is precisely the empty chart the 400 two
55
+ * paragraphs up exists to prevent. A declared-but-unwritten series is worse
56
+ * than an absent one: the 400 tells you the name is wrong, and the empty array
57
+ * tells you the app was quiet.
58
+ *
59
+ * `event_loop_delay_ms` kept its place by gaining a sampler, because it is the
60
+ * one signal here that says whether the process is *healthy* rather than how
61
+ * much it is using, and it has no counter semantics to get wrong.
62
+ *
63
+ * Requests and errors are NOT the registry's cumulative counters, which reset
64
+ * on restart and are not monotonic when summed across replicas — a rolling
65
+ * deploy would draw a cliff that looks like traffic collapsing. They are
66
+ * per-minute deltas per surface, written by `recordRequestDeltas`; see
67
+ * {@link REQUEST_DELTA_SERIES}. Every name here has a writer: `sampleSelf` for
68
+ * the first three, `recordRequestDeltas` for the rest.
69
+ */
70
+ var METRIC_SERIES = [
71
+ "cpu_millicores",
72
+ "memory_bytes",
73
+ "event_loop_delay_ms",
74
+ "requests_data",
75
+ "errors_data",
76
+ "requests_auth",
77
+ "errors_auth",
78
+ "requests_storage",
79
+ "errors_storage",
80
+ "requests_functions",
81
+ "errors_functions",
82
+ "requests_app",
83
+ "errors_app"
84
+ ];
85
+ /**
86
+ * The surfaces whose requests are recorded over time.
87
+ *
88
+ * `admin`, `meta` and `other` are left out on purpose: they are the console and
89
+ * tooling reading the backend, and on a quiet project they are most of the
90
+ * traffic — a chart of them would be a chart of somebody looking at the chart.
91
+ */
92
+ var RECORDED_SURFACES = [
93
+ "data",
94
+ "auth",
95
+ "storage",
96
+ "functions",
97
+ "app"
98
+ ];
99
+ /**
100
+ * The delta series: "requests this instance handled in this minute".
101
+ *
102
+ * ## Why deltas and not the counters
103
+ *
104
+ * The registry's request counters are cumulative and reset when the process
105
+ * does, and a resetting counter summed across replicas is not monotonic: a
106
+ * rolling deploy draws a cliff that looks like traffic collapsing. A delta has
107
+ * none of that. It never goes backwards, a restart is simply a new process
108
+ * whose first delta is its own count since boot, and the sum of deltas across
109
+ * replicas is the deployment's true figure for the minute.
110
+ *
111
+ * A delta of zero is NOT written — a quiet project would otherwise write ten
112
+ * zero rows a minute per instance for nothing — so a read fills zeros back in,
113
+ * but only for minutes some instance was alive (see {@link readSeriesBatch}).
114
+ */
115
+ var REQUEST_DELTA_SERIES = RECORDED_SURFACES.flatMap((surface) => [`requests_${surface}`, `errors_${surface}`]);
116
+ /** Whether a series is a per-minute delta, zero-filled on read. */
117
+ function isDeltaSeries(series) {
118
+ return REQUEST_DELTA_SERIES.includes(series);
119
+ }
120
+ /**
121
+ * The series every live instance writes every tick, and so the one a read uses
122
+ * to tell "running and quiet" (a zero) from "not running" (a gap).
123
+ */
124
+ var LIVENESS_SERIES = "memory_bytes";
125
+ /**
126
+ * Create the table and sweep what has aged out.
127
+ *
128
+ * Called at boot, beside the job and cron stores, and for the same reason they
129
+ * do it there: the only moment the schema is guaranteed to be reachable and
130
+ * nobody is mid-request.
131
+ */
132
+ async function ensureMetricsHistory(exec) {
133
+ await exec(`
134
+ CREATE TABLE IF NOT EXISTS ${METRICS_HISTORY_TABLE} (
135
+ at timestamptz NOT NULL,
136
+ series text NOT NULL,
137
+ instance text NOT NULL,
138
+ value double precision NOT NULL,
139
+ PRIMARY KEY (series, instance, at)
140
+ )
141
+ `, []);
142
+ await exec(`
143
+ CREATE INDEX IF NOT EXISTS metric_samples_series_recent
144
+ ON ${METRICS_HISTORY_TABLE} (series, at DESC)
145
+ `, []);
146
+ await exec(revokeInternalTableSql("rebase", "metric_samples"), []);
147
+ await sweepMetricsHistory(exec);
148
+ }
149
+ /**
150
+ * {@link ensureMetricsHistory} for a backend that changes nothing in its
151
+ * database: the table is read, never made, and its absence is an error — which
152
+ * the caller turns into "no history", the same outcome as a create that failed.
153
+ * The sweep still runs: it deletes rows, and keeping the table bounded is not a
154
+ * schema change.
155
+ */
156
+ async function adoptExistingMetricsHistory(exec) {
157
+ try {
158
+ await exec(`SELECT at, series, instance, value FROM ${METRICS_HISTORY_TABLE} WHERE false`, []);
159
+ } catch (error) {
160
+ throw new Error(`${METRICS_HISTORY_TABLE} is missing or out of date, and this backend changes nothing in its database`, { cause: error });
161
+ }
162
+ await sweepMetricsHistory(exec);
163
+ }
164
+ /**
165
+ * Swept at boot rather than by a cron, so a deployment that runs no scheduler
166
+ * still stays bounded. A DELETE is the right tool at this size — a few thousand
167
+ * rows a day — and partitioning would be machinery for a table that never gets
168
+ * big.
169
+ */
170
+ async function sweepMetricsHistory(exec) {
171
+ await exec(`DELETE FROM ${METRICS_HISTORY_TABLE} WHERE at < now() - make_interval(days => $1)`, [14]);
172
+ }
173
+ /**
174
+ * What this process is using right now.
175
+ *
176
+ * `process.cpuUsage()` is cumulative, so a rate needs two readings and the gap
177
+ * between them — which is why the previous one is threaded through rather than
178
+ * held in a module global: a module global is shared by every test in a file
179
+ * and makes the first assertion depend on whatever ran before it.
180
+ */
181
+ function sampleSelf(previous, now = Date.now(), eventLoopDelayMs) {
182
+ const cpu = process.cpuUsage();
183
+ const samples = [{
184
+ series: "memory_bytes",
185
+ value: process.memoryUsage().rss
186
+ }];
187
+ if (typeof eventLoopDelayMs === "number" && Number.isFinite(eventLoopDelayMs)) samples.push({
188
+ series: "event_loop_delay_ms",
189
+ value: eventLoopDelayMs
190
+ });
191
+ if (previous) {
192
+ const elapsedMs = now - previous.at;
193
+ if (elapsedMs > 0) {
194
+ const usedMicros = cpu.user - previous.cpu.user + (cpu.system - previous.cpu.system);
195
+ samples.push({
196
+ series: "cpu_millicores",
197
+ value: usedMicros / 1e3 / elapsedMs * 1e3
198
+ });
199
+ }
200
+ }
201
+ return {
202
+ samples,
203
+ cursor: {
204
+ cpu,
205
+ at: now
206
+ }
207
+ };
208
+ }
209
+ /**
210
+ * Write one tick's samples, for one instance.
211
+ *
212
+ * ## Why `instance` is part of the key
213
+ *
214
+ * A tenant's replicas share one database, and each records its OWN process. Key
215
+ * a row by `(series, minute)` alone and the pods overwrite each other every
216
+ * tick: one pod at 5m and another at 500m leave whichever wrote last, so a
217
+ * scaled-out tenant charts one arbitrary replica and calls it the app. Adding
218
+ * the instance makes each pod its own row, and lets the read decide whether the
219
+ * question is "the whole deployment" or "which pod is hot".
220
+ *
221
+ * Cardinality stays bounded: rows are series × replicas × minutes, and replicas
222
+ * are capped by the autoscaling ceiling. Six pods is ~43k rows a day and a
223
+ * fortnight of them is well under a million.
224
+ */
225
+ async function recordSamples(exec, samples, instance, at = /* @__PURE__ */ new Date()) {
226
+ if (samples.length === 0) return;
227
+ const bucket = /* @__PURE__ */ new Date(Math.floor(at.getTime() / 6e4) * 6e4);
228
+ for (const s of samples) {
229
+ if (!Number.isFinite(s.value)) continue;
230
+ await exec(`INSERT INTO ${METRICS_HISTORY_TABLE} (at, series, instance, value)
231
+ VALUES ($1, $2, $3, $4)
232
+ ON CONFLICT (series, instance, at) DO UPDATE SET value = EXCLUDED.value`, [
233
+ bucket,
234
+ s.series,
235
+ instance,
236
+ s.value
237
+ ]);
238
+ }
239
+ }
240
+ /**
241
+ * How a series combines across the replicas that reported it.
242
+ *
243
+ * Not one answer for everything, because the right one differs by what the
244
+ * number means. CPU and memory are consumption: the deployment's figure is the
245
+ * sum, and a mean would make scaling out look like it reduced usage. A queue
246
+ * depth or an event-loop delay is a condition each process is independently in,
247
+ * and summing those produces a number no single pod ever experienced.
248
+ */
249
+ var COMBINE = {
250
+ cpu_millicores: "sum",
251
+ memory_bytes: "sum",
252
+ event_loop_delay_ms: "avg",
253
+ requests_data: "sum",
254
+ errors_data: "sum",
255
+ requests_auth: "sum",
256
+ errors_auth: "sum",
257
+ requests_storage: "sum",
258
+ errors_storage: "sum",
259
+ requests_functions: "sum",
260
+ errors_functions: "sum",
261
+ requests_app: "sum",
262
+ errors_app: "sum"
263
+ };
264
+ /**
265
+ * Read one series over a window, oldest first — the order a chart draws in.
266
+ *
267
+ * Combined across instances rather than returned per-pod. A chart of "this
268
+ * app's CPU" is the question people ask; "which pod is hot" is answered by the
269
+ * live panel, which already lists instances individually and does not need
270
+ * history to do it.
271
+ *
272
+ * `instances` rides along because a sum whose contributor count changed is not
273
+ * comparable with itself: CPU doubling because the app got busy and CPU
274
+ * doubling because it scaled from one replica to two are different events, and
275
+ * a line chart alone cannot tell them apart.
276
+ */
277
+ async function readSeries(exec, series, sinceMinutes) {
278
+ if (isDeltaSeries(series)) return (await readSeriesBatch(exec, [series], sinceMinutes, 1))[series] ?? [];
279
+ return sqlRows(await exec(`SELECT at, ${COMBINE[series] === "avg" ? "avg" : "sum"}(value) AS value, count(*) AS instances
280
+ FROM ${METRICS_HISTORY_TABLE}
281
+ WHERE series = $1
282
+ AND at >= now() - make_interval(mins => $2)
283
+ AND at < date_trunc('minute', now())
284
+ GROUP BY at
285
+ ORDER BY at ASC`, [series, sinceMinutes])).map((r) => ({
286
+ at: r.at instanceof Date ? r.at.toISOString() : String(r.at),
287
+ value: Number(r.value),
288
+ instances: Number(r.instances ?? 1)
289
+ }));
290
+ }
291
+ /**
292
+ * Turn the registry's cumulative counts into this minute's deltas.
293
+ *
294
+ * Pure: the cursor is passed in and the caller decides when to advance it. A
295
+ * series with no previous reading — the first tick after boot — contributes its
296
+ * whole count since boot. A count LOWER than the cursor can only mean the
297
+ * counter restarted, and the honest delta is then the new count itself, never a
298
+ * negative. Zero deltas are left out: nothing is written for them.
299
+ */
300
+ function requestDeltas(totals, cursor) {
301
+ const deltas = [];
302
+ for (const surface of RECORDED_SURFACES) {
303
+ const counts = totals[surface] ?? {
304
+ requests: 0,
305
+ errors: 0
306
+ };
307
+ const pairs = [[`requests_${surface}`, counts.requests], [`errors_${surface}`, counts.errors]];
308
+ for (const [series, cumulative] of pairs) {
309
+ const previous = cursor[series] ?? 0;
310
+ const value = cumulative >= previous ? cumulative - previous : cumulative;
311
+ if (value > 0 && Number.isFinite(value)) deltas.push({
312
+ series,
313
+ value,
314
+ cumulative
315
+ });
316
+ }
317
+ }
318
+ return deltas;
319
+ }
320
+ /**
321
+ * Write this tick's request deltas and return the advanced cursor.
322
+ *
323
+ * Each series' cursor moves only when ITS row was written. A failed write
324
+ * leaves it where it was, so the next tick's delta covers both minutes: nothing
325
+ * is lost and nothing is counted twice. Per series rather than per tick,
326
+ * because the rows are separate statements and a failure halfway through must
327
+ * not re-count the half that landed.
328
+ *
329
+ * The upsert ADDS rather than replaces. Two writes for one minute from one
330
+ * instance — two ticks drifting into the same minute, or a container restart
331
+ * that keeps its hostname — are both real traffic, and replacing would drop
332
+ * the first.
333
+ */
334
+ async function recordRequestDeltas(exec, totals, cursor, instance, at = /* @__PURE__ */ new Date()) {
335
+ const bucket = /* @__PURE__ */ new Date(Math.floor(at.getTime() / 6e4) * 6e4);
336
+ const next = { ...cursor };
337
+ const failed = [];
338
+ for (const { series, value, cumulative } of requestDeltas(totals, cursor)) try {
339
+ await exec(`INSERT INTO ${METRICS_HISTORY_TABLE} (at, series, instance, value)
340
+ VALUES ($1, $2, $3, $4)
341
+ ON CONFLICT (series, instance, at) DO UPDATE SET value = ${METRICS_HISTORY_TABLE}.value + EXCLUDED.value`, [
342
+ bucket,
343
+ series,
344
+ instance,
345
+ value
346
+ ]);
347
+ next[series] = cumulative;
348
+ } catch (err) {
349
+ failed.push(err);
350
+ }
351
+ return {
352
+ cursor: next,
353
+ failed
354
+ };
355
+ }
356
+ /** The bucket sizes the batch read accepts, in minutes. */
357
+ var HISTORY_BUCKETS = [
358
+ 1,
359
+ 5,
360
+ 30,
361
+ 180
362
+ ];
363
+ /** The widest window a read may ask for, in minutes: the retention. */
364
+ var MAX_HISTORY_MINUTES = 20160;
365
+ /**
366
+ * Read several series over a window, bucketed, oldest first.
367
+ *
368
+ * ## The window
369
+ *
370
+ * Buckets are aligned to the epoch and the window ends at the start of the
371
+ * CURRENT bucket, which is excluded for the same reason {@link readSeries}
372
+ * excludes the current minute: it is still being written. The window then
373
+ * reaches back `minutes`, so a 60-minute read at one-minute buckets is at most
374
+ * sixty complete points, and a day at thirty is at most forty-eight.
375
+ *
376
+ * ## Gaps and zeros
377
+ *
378
+ * A delta series stores no zeros, so its read fills them in — but only for a
379
+ * minute in which some instance was alive, which is a minute with a
380
+ * {@link LIVENESS_SERIES} row. A minute nobody was running is absent: a gap on
381
+ * a chart, not a zero, because "the app was down" and "the app was quiet" are
382
+ * different answers. `instances` on a delta point is the number of live
383
+ * instances.
384
+ *
385
+ * ## Within a bucket
386
+ *
387
+ * - a delta series is summed over its minutes: requests in the bucket;
388
+ * - an `avg` series (event-loop delay) is the mean of its per-minute combined
389
+ * values;
390
+ * - a `sum` gauge (CPU, memory) is ALSO the mean of its per-minute combined
391
+ * values. Summing thirty minutes of memory would report thirty times the
392
+ * memory; a gauge is a level, not an amount that accumulates.
393
+ *
394
+ * `instances` is the maximum over the bucket. A bucket with no live minute is
395
+ * absent. Every requested series is a key in the result, an empty array when
396
+ * nothing was recorded in the window.
397
+ */
398
+ async function readSeriesBatch(exec, series, minutes, bucket) {
399
+ const requested = [...new Set(series)];
400
+ const deltas = requested.filter(isDeltaSeries);
401
+ const averaged = requested.filter((s) => COMBINE[s] === "avg");
402
+ const bucketSeconds = bucket * 60;
403
+ const result = await exec(`WITH win AS (
404
+ SELECT hi - make_interval(mins => $2::int) AS lo, hi
405
+ FROM (SELECT to_timestamp(floor(extract(epoch FROM now()) / $3::int) * $3::int) AS hi) h
406
+ ),
407
+ live AS (
408
+ SELECT s.at, count(*) AS instances
409
+ FROM ${METRICS_HISTORY_TABLE} s, win
410
+ WHERE s.series = '${LIVENESS_SERIES}' AND s.at >= win.lo AND s.at < win.hi
411
+ GROUP BY s.at
412
+ ),
413
+ per_minute AS (
414
+ SELECT s.series, s.at, sum(s.value) AS total, avg(s.value) AS mean, count(*) AS instances
415
+ FROM ${METRICS_HISTORY_TABLE} s, win
416
+ WHERE s.series = ANY($1::text[]) AND s.at >= win.lo AND s.at < win.hi
417
+ GROUP BY s.series, s.at
418
+ ),
419
+ minutes AS (
420
+ SELECT d.series, l.at, coalesce(p.total, 0) AS value, l.instances, true AS is_delta
421
+ FROM unnest($4::text[]) AS d(series)
422
+ CROSS JOIN live l
423
+ LEFT JOIN per_minute p ON p.series = d.series AND p.at = l.at
424
+ UNION ALL
425
+ SELECT p.series, p.at,
426
+ CASE WHEN p.series = ANY($5::text[]) THEN p.mean ELSE p.total END,
427
+ p.instances, false
428
+ FROM per_minute p
429
+ WHERE NOT (p.series = ANY($4::text[]))
430
+ )
431
+ SELECT series,
432
+ to_timestamp(floor(extract(epoch FROM at) / $3::int) * $3::int) AS at,
433
+ CASE WHEN bool_or(is_delta) THEN sum(value) ELSE avg(value) END AS value,
434
+ max(instances) AS instances
435
+ FROM minutes
436
+ GROUP BY 1, 2
437
+ ORDER BY 1, 2`, [
438
+ requested,
439
+ minutes,
440
+ bucketSeconds,
441
+ deltas,
442
+ averaged
443
+ ]);
444
+ const out = Object.fromEntries(requested.map((s) => [s, []]));
445
+ for (const r of sqlRows(result)) {
446
+ const list = out[r.series];
447
+ if (!list) continue;
448
+ list.push({
449
+ at: r.at instanceof Date ? r.at.toISOString() : new Date(String(r.at)).toISOString(),
450
+ value: Number(r.value),
451
+ instances: Number(r.instances ?? 1)
452
+ });
453
+ }
454
+ return out;
455
+ }
456
+ //#endregion
457
+ export { SAMPLE_INTERVAL_MS as a, readSeries as c, recordSamples as d, sampleSelf as f, RECORDED_SURFACES as i, readSeriesBatch as l, MAX_HISTORY_MINUTES as n, adoptExistingMetricsHistory as o, METRIC_SERIES as r, ensureMetricsHistory as s, HISTORY_BUCKETS as t, recordRequestDeltas as u };
458
+
459
+ //# sourceMappingURL=history-store-c_cm9R3w.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"history-store-c_cm9R3w.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, sqlRows } from \"@rebasepro/common\";\n\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 and errors are NOT the registry's cumulative counters, which reset\n * on restart and are not monotonic when summed across replicas — a rolling\n * deploy would draw a cliff that looks like traffic collapsing. They are\n * per-minute deltas per surface, written by `recordRequestDeltas`; see\n * {@link REQUEST_DELTA_SERIES}. Every name here has a writer: `sampleSelf` for\n * the first three, `recordRequestDeltas` for the rest.\n */\nexport const METRIC_SERIES = [\n \"cpu_millicores\",\n \"memory_bytes\",\n \"event_loop_delay_ms\",\n // Requests and errors per surface, as PER-MINUTE DELTAS — see\n // `REQUEST_DELTA_SERIES` below for why deltas and not the counters.\n \"requests_data\", \"errors_data\",\n \"requests_auth\", \"errors_auth\",\n \"requests_storage\", \"errors_storage\",\n \"requests_functions\", \"errors_functions\",\n \"requests_app\", \"errors_app\"\n] as const;\n\nexport type MetricSeries = (typeof METRIC_SERIES)[number];\n\n/**\n * The surfaces whose requests are recorded over time.\n *\n * `admin`, `meta` and `other` are left out on purpose: they are the console and\n * tooling reading the backend, and on a quiet project they are most of the\n * traffic — a chart of them would be a chart of somebody looking at the chart.\n */\nexport const RECORDED_SURFACES = [\"data\", \"auth\", \"storage\", \"functions\", \"app\"] as const;\n\nexport type RecordedSurface = (typeof RECORDED_SURFACES)[number];\n\n/**\n * The delta series: \"requests this instance handled in this minute\".\n *\n * ## Why deltas and not the counters\n *\n * The registry's request counters are cumulative and reset when the process\n * does, and a resetting counter summed across replicas is not monotonic: a\n * rolling deploy draws a cliff that looks like traffic collapsing. A delta has\n * none of that. It never goes backwards, a restart is simply a new process\n * whose first delta is its own count since boot, and the sum of deltas across\n * replicas is the deployment's true figure for the minute.\n *\n * A delta of zero is NOT written — a quiet project would otherwise write ten\n * zero rows a minute per instance for nothing — so a read fills zeros back in,\n * but only for minutes some instance was alive (see {@link readSeriesBatch}).\n */\nexport const REQUEST_DELTA_SERIES: readonly MetricSeries[] = RECORDED_SURFACES.flatMap(surface => [\n `requests_${surface}` as const,\n `errors_${surface}` as const\n]);\n\n/** Whether a series is a per-minute delta, zero-filled on read. */\nexport function isDeltaSeries(series: MetricSeries): boolean {\n return REQUEST_DELTA_SERIES.includes(series);\n}\n\n/**\n * The series every live instance writes every tick, and so the one a read uses\n * to tell \"running and quiet\" (a zero) from \"not running\" (a gap).\n */\nexport const LIVENESS_SERIES: MetricSeries = \"memory_bytes\";\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 await sweepMetricsHistory(exec);\n}\n\n/**\n * {@link ensureMetricsHistory} for a backend that changes nothing in its\n * database: the table is read, never made, and its absence is an error — which\n * the caller turns into \"no history\", the same outcome as a create that failed.\n * The sweep still runs: it deletes rows, and keeping the table bounded is not a\n * schema change.\n */\nexport async function adoptExistingMetricsHistory(exec: Exec): Promise<void> {\n try {\n await exec(`SELECT at, series, instance, value FROM ${METRICS_HISTORY_TABLE} WHERE false`, []);\n } catch (error) {\n throw new Error(\n `${METRICS_HISTORY_TABLE} is missing or out of date, and this backend changes nothing in its database`,\n { cause: error }\n );\n }\n await sweepMetricsHistory(exec);\n}\n\n/**\n * Swept at boot 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 thousand\n * rows a day — and partitioning would be machinery for a table that never gets\n * big.\n */\nasync function sweepMetricsHistory(exec: Exec): Promise<void> {\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 // Each replica's delta is its own share of the minute's traffic, so the\n // deployment's figure is their sum.\n requests_data: \"sum\",\n errors_data: \"sum\",\n requests_auth: \"sum\",\n errors_auth: \"sum\",\n requests_storage: \"sum\",\n errors_storage: \"sum\",\n requests_functions: \"sum\",\n errors_functions: \"sum\",\n requests_app: \"sum\",\n errors_app: \"sum\"\n};\n\n/** How a series combines across replicas. Exported for the route's tests. */\nexport function combineOf(series: MetricSeries): \"sum\" | \"avg\" {\n return COMBINE[series];\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 // A delta series is zero-filled against liveness, which only the batch\n // read knows how to do. One minute per bucket is the same resolution.\n if (isDeltaSeries(series)) {\n const batch = await readSeriesBatch(exec, [series], sinceMinutes, 1);\n return batch[series] ?? [];\n }\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 result = 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 );\n\n return sqlRows<RawPoint>(result).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\n/** Cumulative requests and errors per recorded surface, as the registry holds them. */\nexport type SurfaceTotals = Partial<Record<RecordedSurface, { requests: number; errors: number }>>;\n\n/** The previous cumulative count per delta series — the recorder's cursor. */\nexport type DeltaCursor = Partial<Record<MetricSeries, number>>;\n\n/**\n * Turn the registry's cumulative counts into this minute's deltas.\n *\n * Pure: the cursor is passed in and the caller decides when to advance it. A\n * series with no previous reading — the first tick after boot — contributes its\n * whole count since boot. A count LOWER than the cursor can only mean the\n * counter restarted, and the honest delta is then the new count itself, never a\n * negative. Zero deltas are left out: nothing is written for them.\n */\nexport function requestDeltas(\n totals: SurfaceTotals,\n cursor: DeltaCursor\n): { series: MetricSeries; value: number; cumulative: number }[] {\n const deltas: { series: MetricSeries; value: number; cumulative: number }[] = [];\n for (const surface of RECORDED_SURFACES) {\n const counts = totals[surface] ?? { requests: 0, errors: 0 };\n const pairs: [MetricSeries, number][] = [\n [`requests_${surface}`, counts.requests],\n [`errors_${surface}`, counts.errors]\n ];\n for (const [series, cumulative] of pairs) {\n const previous = cursor[series] ?? 0;\n const value = cumulative >= previous ? cumulative - previous : cumulative;\n if (value > 0 && Number.isFinite(value)) deltas.push({ series, value, cumulative });\n }\n }\n return deltas;\n}\n\n/**\n * Write this tick's request deltas and return the advanced cursor.\n *\n * Each series' cursor moves only when ITS row was written. A failed write\n * leaves it where it was, so the next tick's delta covers both minutes: nothing\n * is lost and nothing is counted twice. Per series rather than per tick,\n * because the rows are separate statements and a failure halfway through must\n * not re-count the half that landed.\n *\n * The upsert ADDS rather than replaces. Two writes for one minute from one\n * instance — two ticks drifting into the same minute, or a container restart\n * that keeps its hostname — are both real traffic, and replacing would drop\n * the first.\n */\nexport async function recordRequestDeltas(\n exec: Exec,\n totals: SurfaceTotals,\n cursor: DeltaCursor,\n instance: string,\n at: Date = new Date()\n): Promise<{ cursor: DeltaCursor; failed: unknown[] }> {\n const bucket = new Date(Math.floor(at.getTime() / 60_000) * 60_000);\n const next: DeltaCursor = { ...cursor };\n const failed: unknown[] = [];\n for (const { series, value, cumulative } of requestDeltas(totals, cursor)) {\n try {\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 = ${METRICS_HISTORY_TABLE}.value + EXCLUDED.value`,\n [bucket, series, instance, value]\n );\n next[series] = cumulative;\n } catch (err) {\n failed.push(err);\n }\n }\n return { cursor: next, failed };\n}\n\n/** The bucket sizes the batch read accepts, in minutes. */\nexport const HISTORY_BUCKETS = [1, 5, 30, 180] as const;\n\nexport type HistoryBucket = (typeof HISTORY_BUCKETS)[number];\n\n/** The widest window a read may ask for, in minutes: the retention. */\nexport const MAX_HISTORY_MINUTES = 20_160;\n\n/** How many series one batch read may name. */\nexport const MAX_BATCH_SERIES = 16;\n\n/**\n * Read several series over a window, bucketed, oldest first.\n *\n * ## The window\n *\n * Buckets are aligned to the epoch and the window ends at the start of the\n * CURRENT bucket, which is excluded for the same reason {@link readSeries}\n * excludes the current minute: it is still being written. The window then\n * reaches back `minutes`, so a 60-minute read at one-minute buckets is at most\n * sixty complete points, and a day at thirty is at most forty-eight.\n *\n * ## Gaps and zeros\n *\n * A delta series stores no zeros, so its read fills them in — but only for a\n * minute in which some instance was alive, which is a minute with a\n * {@link LIVENESS_SERIES} row. A minute nobody was running is absent: a gap on\n * a chart, not a zero, because \"the app was down\" and \"the app was quiet\" are\n * different answers. `instances` on a delta point is the number of live\n * instances.\n *\n * ## Within a bucket\n *\n * - a delta series is summed over its minutes: requests in the bucket;\n * - an `avg` series (event-loop delay) is the mean of its per-minute combined\n * values;\n * - a `sum` gauge (CPU, memory) is ALSO the mean of its per-minute combined\n * values. Summing thirty minutes of memory would report thirty times the\n * memory; a gauge is a level, not an amount that accumulates.\n *\n * `instances` is the maximum over the bucket. A bucket with no live minute is\n * absent. Every requested series is a key in the result, an empty array when\n * nothing was recorded in the window.\n */\nexport async function readSeriesBatch(\n exec: Exec,\n series: readonly MetricSeries[],\n minutes: number,\n bucket: HistoryBucket\n): Promise<Record<string, SeriesPoint[]>> {\n const requested = [...new Set(series)];\n const deltas = requested.filter(isDeltaSeries);\n const averaged = requested.filter(s => COMBINE[s] === \"avg\");\n const bucketSeconds = bucket * 60;\n\n const result = await exec(\n `WITH win AS (\n SELECT hi - make_interval(mins => $2::int) AS lo, hi\n FROM (SELECT to_timestamp(floor(extract(epoch FROM now()) / $3::int) * $3::int) AS hi) h\n ),\n live AS (\n SELECT s.at, count(*) AS instances\n FROM ${METRICS_HISTORY_TABLE} s, win\n WHERE s.series = '${LIVENESS_SERIES}' AND s.at >= win.lo AND s.at < win.hi\n GROUP BY s.at\n ),\n per_minute AS (\n SELECT s.series, s.at, sum(s.value) AS total, avg(s.value) AS mean, count(*) AS instances\n FROM ${METRICS_HISTORY_TABLE} s, win\n WHERE s.series = ANY($1::text[]) AND s.at >= win.lo AND s.at < win.hi\n GROUP BY s.series, s.at\n ),\n minutes AS (\n SELECT d.series, l.at, coalesce(p.total, 0) AS value, l.instances, true AS is_delta\n FROM unnest($4::text[]) AS d(series)\n CROSS JOIN live l\n LEFT JOIN per_minute p ON p.series = d.series AND p.at = l.at\n UNION ALL\n SELECT p.series, p.at,\n CASE WHEN p.series = ANY($5::text[]) THEN p.mean ELSE p.total END,\n p.instances, false\n FROM per_minute p\n WHERE NOT (p.series = ANY($4::text[]))\n )\n SELECT series,\n to_timestamp(floor(extract(epoch FROM at) / $3::int) * $3::int) AS at,\n CASE WHEN bool_or(is_delta) THEN sum(value) ELSE avg(value) END AS value,\n max(instances) AS instances\n FROM minutes\n GROUP BY 1, 2\n ORDER BY 1, 2`,\n [requested, minutes, bucketSeconds, deltas, averaged]\n );\n\n const out: Record<string, SeriesPoint[]> = Object.fromEntries(requested.map(s => [s, [] as SeriesPoint[]]));\n for (const r of sqlRows<RawBatchPoint>(result)) {\n const list = out[r.series];\n if (!list) continue;\n list.push({\n at: r.at instanceof Date ? r.at.toISOString() : new Date(String(r.at)).toISOString(),\n value: Number(r.value),\n instances: Number(r.instances ?? 1)\n });\n }\n return out;\n}\n\ninterface RawBatchPoint { series: string; at: Date | string; value: number | string; instances?: number | string }\n"],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -124,7 +124,7 @@ export { registerResourceResolver, resourceResolver, resourceResolvers, assertEv
124
124
  export type { ResourceResolver, ResourceResolution, ResolveContext } from "./boot/resource-resolvers.js";
125
125
  export { initializeDataSource, initializeDataSources } from "./boot/driver.js";
126
126
  export type { InitializedDataSource, DriverConnection, BundleSchema } from "./boot/driver.js";
127
- export { MetricsRegistry, createMetricsMiddleware, createMetricsRoutes, classifySurface, isUncountedPath } from "./metrics/index.js";
127
+ export { MetricsRegistry, createMetricsMiddleware, createMetricsRoutes, classifySurface, isErrorStatus, isUncountedPath } from "./metrics/index.js";
128
128
  export type { MetricSurface, MetricsHandle } from "./metrics/index.js";
129
129
  export { createContractRoutes } from "./api/contract-routes.js";
130
130
  export type { ContractRoutesConfig } from "./api/contract-routes.js";