@mistriwork/engine 1.0.0-rc.74 → 1.0.0-rc.77
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.
- package/dist/adapters/postgresPool.d.ts +28 -0
- package/dist/adapters/postgresPool.js +36 -3
- package/dist/adapters/serverSettings.d.ts +2 -0
- package/dist/server/cli/args.d.ts +2 -1
- package/dist/server/cli/args.js +13 -2
- package/dist/server/connections.d.ts +1 -1
- package/dist/server/connections.js +2 -0
- package/dist/server/http/refusalReport.js +7 -1
- package/dist/server/poolConfig.d.ts +4 -0
- package/dist/server/poolConfig.js +20 -7
- package/dist/server/resourceReadHttp.js +7 -2
- package/dist/shared/appComponents.js +1 -1
- package/dist/shared/autoBucket.d.ts +29 -5
- package/dist/shared/autoBucket.js +49 -14
- package/package.json +1 -1
|
@@ -54,6 +54,28 @@ export declare const pipelinesAs: (wrapper: PgQuery, client: PgQuery) => void;
|
|
|
54
54
|
/** The database browser's reader pool size unless a connection or the command line says otherwise.
|
|
55
55
|
* An App's is balanced against its writers (appReaders). */
|
|
56
56
|
export declare const DEFAULT_READERS = 4;
|
|
57
|
+
/** The longest an idle connection may be kept: a day. Past it a forgotten setting holds a server backend for nothing,
|
|
58
|
+
* and a hosted database or pooler has closed the socket long before. */
|
|
59
|
+
export declare const MAX_IDLE_SECONDS = 86400;
|
|
60
|
+
/** Whether `value` is an idle window a connection accepts: whole seconds from 1 to a day. */
|
|
61
|
+
export declare function isIdleSeconds(value: unknown): value is number;
|
|
62
|
+
/** Whether `value` is a warm-connection count a connection accepts: a whole number from 0 to the pool's largest size. */
|
|
63
|
+
export declare function isMinIdle(value: unknown): value is number;
|
|
64
|
+
/**
|
|
65
|
+
* How long an idle connection stays open and how many stay connected through it, for one pool: the connection's own
|
|
66
|
+
* `pool` setting, else the server's (`MISTRI_POOL_IDLE`, in seconds), else the built-in five minutes and `warm`. The
|
|
67
|
+
* connection's wins, as `pool.read` wins over `--read-pool`: the deployment sets a default, one database overrides it.
|
|
68
|
+
* `minIdle` is capped at the pool's size, which pg would otherwise refuse.
|
|
69
|
+
*/
|
|
70
|
+
export declare function resolvePoolIdle(options: {
|
|
71
|
+
readonly idleSeconds?: number;
|
|
72
|
+
readonly minIdle?: number;
|
|
73
|
+
}, server: {
|
|
74
|
+
readonly idleSeconds?: number;
|
|
75
|
+
}, warm: number, size: number): {
|
|
76
|
+
idleTimeoutMillis: number;
|
|
77
|
+
min: number;
|
|
78
|
+
};
|
|
57
79
|
/** The most readers one database's pool may hold. Past this, a pooler in front of the server is the tool. */
|
|
58
80
|
export declare const MAX_READERS = 64;
|
|
59
81
|
/** Whether `value` is a reader pool size a manager accepts: a whole number from 1 to 64. */
|
|
@@ -63,6 +85,10 @@ export interface PgConnectionOptions {
|
|
|
63
85
|
readonly readers?: number;
|
|
64
86
|
/** Writer connections held at once, 1–64, where writes are keyed (writeLanes.ts); one where they are serial. */
|
|
65
87
|
readonly writers?: number;
|
|
88
|
+
/** Seconds an idle connection stays open, 1 to 86400. The process's (`MISTRI_POOL_IDLE`), else five minutes, when absent. */
|
|
89
|
+
readonly idleSeconds?: number;
|
|
90
|
+
/** Connections each pool keeps open through an idle spell, 0 to 64 (never more than the pool's size). Two readers and one writer when absent. */
|
|
91
|
+
readonly minIdle?: number;
|
|
66
92
|
/** How long a writer waits for a lock. The process's (`--lock-timeout`) when absent. */
|
|
67
93
|
readonly lockTimeoutMs?: number;
|
|
68
94
|
/** What sits between this process and the server. The process default when absent. */
|
|
@@ -113,6 +139,7 @@ export declare function appReaders(writers: number, cores?: number): number;
|
|
|
113
139
|
export declare function configurePostgresPools(options: {
|
|
114
140
|
readers?: number;
|
|
115
141
|
pooler?: PoolerMode;
|
|
142
|
+
idleSeconds?: number;
|
|
116
143
|
}): void;
|
|
117
144
|
/** The defaults, as this server's settings leave them. */
|
|
118
145
|
export declare function postgresPoolDefaults(): Readonly<{
|
|
@@ -156,6 +183,7 @@ export declare class PgConnectionManager {
|
|
|
156
183
|
/** Bounded concurrency for best-effort pg_cancel_backend helper connections. */
|
|
157
184
|
private cancelsInFlight;
|
|
158
185
|
private readonly cancelQueue;
|
|
186
|
+
private readonly idle;
|
|
159
187
|
private readonly pendingCancels;
|
|
160
188
|
constructor(connectionString: string, onLoad?: (pg: unknown) => void, load?: PgPoolLoader, options?: PgConnectionOptions);
|
|
161
189
|
/**
|
|
@@ -76,6 +76,30 @@ const WARM_WRITERS = 1;
|
|
|
76
76
|
/** How long an idle connection stays open: five minutes, past a lunch-hour lull but well inside what a
|
|
77
77
|
* hosted database or its pooler lets a connection sit. The extra ones (beyond the warm minimum) close then. */
|
|
78
78
|
const IDLE_TIMEOUT_MS = 300_000;
|
|
79
|
+
/** The longest an idle connection may be kept: a day. Past it a forgotten setting holds a server backend for nothing,
|
|
80
|
+
* and a hosted database or pooler has closed the socket long before. */
|
|
81
|
+
export const MAX_IDLE_SECONDS = 86_400;
|
|
82
|
+
/** Whether `value` is an idle window a connection accepts: whole seconds from 1 to a day. */
|
|
83
|
+
export function isIdleSeconds(value) {
|
|
84
|
+
return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_IDLE_SECONDS;
|
|
85
|
+
}
|
|
86
|
+
/** Whether `value` is a warm-connection count a connection accepts: a whole number from 0 to the pool's largest size. */
|
|
87
|
+
export function isMinIdle(value) {
|
|
88
|
+
return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_READERS;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* How long an idle connection stays open and how many stay connected through it, for one pool: the connection's own
|
|
92
|
+
* `pool` setting, else the server's (`MISTRI_POOL_IDLE`, in seconds), else the built-in five minutes and `warm`. The
|
|
93
|
+
* connection's wins, as `pool.read` wins over `--read-pool`: the deployment sets a default, one database overrides it.
|
|
94
|
+
* `minIdle` is capped at the pool's size, which pg would otherwise refuse.
|
|
95
|
+
*/
|
|
96
|
+
export function resolvePoolIdle(options, server, warm, size) {
|
|
97
|
+
const seconds = options.idleSeconds ?? server.idleSeconds;
|
|
98
|
+
return {
|
|
99
|
+
idleTimeoutMillis: seconds === undefined ? IDLE_TIMEOUT_MS : seconds * 1000,
|
|
100
|
+
min: Math.min(options.minIdle ?? warm, size),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
79
103
|
/** The most readers one database's pool may hold. Past this, a pooler in front of the server is the tool. */
|
|
80
104
|
export const MAX_READERS = 64;
|
|
81
105
|
/** What pg-pool says when no connection came free within the acquisition timeout. */
|
|
@@ -126,7 +150,9 @@ export function configurePostgresPools(options) {
|
|
|
126
150
|
const pooler = options.pooler ?? 'session';
|
|
127
151
|
if (pooler !== 'session' && pooler !== 'transaction')
|
|
128
152
|
throw new RangeError('The pooler is "session" or "transaction".');
|
|
129
|
-
|
|
153
|
+
if (options.idleSeconds !== undefined && !isIdleSeconds(options.idleSeconds))
|
|
154
|
+
throw new RangeError(`A PostgreSQL idle connection stays 1 to ${MAX_IDLE_SECONDS} seconds; ${String(options.idleSeconds)} is not one of them.`);
|
|
155
|
+
configureServerSettings({ readers, pooler, idleSeconds: options.idleSeconds });
|
|
130
156
|
}
|
|
131
157
|
/** The defaults, as this server's settings leave them. */
|
|
132
158
|
export function postgresPoolDefaults() {
|
|
@@ -175,6 +201,7 @@ export class PgConnectionManager {
|
|
|
175
201
|
/** Bounded concurrency for best-effort pg_cancel_backend helper connections. */
|
|
176
202
|
cancelsInFlight = 0;
|
|
177
203
|
cancelQueue = [];
|
|
204
|
+
idle;
|
|
178
205
|
pendingCancels = new Set();
|
|
179
206
|
constructor(connectionString, onLoad = () => { }, load = loadPg, options = {}) {
|
|
180
207
|
this.connectionString = connectionString;
|
|
@@ -189,6 +216,11 @@ export class PgConnectionManager {
|
|
|
189
216
|
if (!isWriterCount(writers))
|
|
190
217
|
throw new RangeError(`A PostgreSQL write pool holds 1 to ${MAX_WRITERS} connections; ${String(writers)} is not one of them.`);
|
|
191
218
|
this.pooler = options.pooler ?? serverSettings().pooler;
|
|
219
|
+
if (options.idleSeconds !== undefined && !isIdleSeconds(options.idleSeconds))
|
|
220
|
+
throw new RangeError(`A PostgreSQL idle connection stays 1 to ${MAX_IDLE_SECONDS} seconds; ${String(options.idleSeconds)} is not one of them.`);
|
|
221
|
+
if (options.minIdle !== undefined && !isMinIdle(options.minIdle))
|
|
222
|
+
throw new RangeError(`A PostgreSQL pool keeps 0 to ${MAX_READERS} idle connections; ${String(options.minIdle)} is not one of them.`);
|
|
223
|
+
this.idle = { idleSeconds: options.idleSeconds, minIdle: options.minIdle };
|
|
192
224
|
this.network = options.network;
|
|
193
225
|
this.pipelineReads = options.pipelineReads === true;
|
|
194
226
|
this.timingLabel = options.timingLabel ?? 'app';
|
|
@@ -353,18 +385,19 @@ export class PgConnectionManager {
|
|
|
353
385
|
throw new Error('Could not find a Pool export in the "pg" package.');
|
|
354
386
|
const write = role !== 'read';
|
|
355
387
|
const session = this.pooler === 'session';
|
|
388
|
+
const idle = resolvePoolIdle(this.idle, serverSettings(), role === 'read' ? WARM_READERS : WARM_WRITERS, this.meters[role].size);
|
|
356
389
|
const pool = new Pool({
|
|
357
390
|
...this.dialOptions(),
|
|
358
391
|
max: this.meters[role].size,
|
|
359
392
|
connectionTimeoutMillis: 10_000,
|
|
360
|
-
idleTimeoutMillis:
|
|
393
|
+
idleTimeoutMillis: idle.idleTimeoutMillis,
|
|
361
394
|
/* Readers and the foreground writers keep a few connections warm
|
|
362
395
|
(the background writer, which runs jobs that are not waited on, keeps none). The
|
|
363
396
|
idle ones never keep the process alive by themselves, so a one-shot
|
|
364
397
|
mode that forgets to close still exits: that is why the writer
|
|
365
398
|
sets this too, now that it holds a connection through idle. */
|
|
366
399
|
allowExitOnIdle: true,
|
|
367
|
-
...(role === 'background' ? {} : { min:
|
|
400
|
+
...(role === 'background' ? {} : { min: idle.min }),
|
|
368
401
|
/* A writer sends each statement as it is asked, not after the one
|
|
369
402
|
before it is answered: a transaction that asks several at once
|
|
370
403
|
(pipelined, postgresTransactionHandle.ts) pays one round trip for
|
|
@@ -23,6 +23,8 @@ export interface ServerSettings {
|
|
|
23
23
|
readonly pooler: PoolerMode;
|
|
24
24
|
/** `--write-pool`; unset, the balanced size (writeLanes.ts). */
|
|
25
25
|
readonly writers?: number;
|
|
26
|
+
/** `MISTRI_POOL_IDLE`: seconds an idle PostgreSQL connection stays open; unset, five minutes (postgresPool.ts). */
|
|
27
|
+
readonly idleSeconds?: number;
|
|
26
28
|
/** `--lock-timeout`; unset, the default. */
|
|
27
29
|
readonly lockTimeoutMs?: number;
|
|
28
30
|
/**
|
|
@@ -176,9 +176,10 @@ export declare function shutdownTimings(opts: Pick<Options, 'drainDelay' | 'shut
|
|
|
176
176
|
* they cannot be used. Refused rather than clamped: a pod sized for 16
|
|
177
177
|
* readers that quietly got 4 is a capacity plan nobody can see failing.
|
|
178
178
|
*/
|
|
179
|
-
export declare function postgresPoolFlags(opts: Pick<Options, 'readPool' | 'writePool' | 'pooler' | 'lockTimeout'
|
|
179
|
+
export declare function postgresPoolFlags(opts: Pick<Options, 'readPool' | 'writePool' | 'pooler' | 'lockTimeout'>, env?: NodeJS.ProcessEnv): {
|
|
180
180
|
readers?: number;
|
|
181
181
|
writers?: number;
|
|
182
182
|
pooler?: PoolerMode;
|
|
183
183
|
lockTimeoutMs?: number;
|
|
184
|
+
idleSeconds?: number;
|
|
184
185
|
} | string;
|
package/dist/server/cli/args.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* test/prose.test.ts holds the two and the README to each other.
|
|
6
6
|
*/
|
|
7
7
|
import { parseHostList } from '../http/trust.js';
|
|
8
|
-
import { isReaderCount, MAX_READERS } from '../../adapters/postgresPool.js';
|
|
8
|
+
import { isIdleSeconds, isReaderCount, MAX_IDLE_SECONDS, MAX_READERS } from '../../adapters/postgresPool.js';
|
|
9
9
|
import { isLockTimeout, isWriterCount, MAX_LOCK_TIMEOUT_MS, MAX_WRITERS, MIN_LOCK_TIMEOUT_MS } from '../../adapters/writeLanes.js';
|
|
10
10
|
import { envName, productEnv } from '../product.js';
|
|
11
11
|
/**
|
|
@@ -315,7 +315,7 @@ export function shutdownTimings(opts) {
|
|
|
315
315
|
* they cannot be used. Refused rather than clamped: a pod sized for 16
|
|
316
316
|
* readers that quietly got 4 is a capacity plan nobody can see failing.
|
|
317
317
|
*/
|
|
318
|
-
export function postgresPoolFlags(opts) {
|
|
318
|
+
export function postgresPoolFlags(opts, env = process.env) {
|
|
319
319
|
let readers;
|
|
320
320
|
if (opts.readPool !== undefined) {
|
|
321
321
|
readers = /^\d+$/.test(opts.readPool) ? Number(opts.readPool) : Number.NaN;
|
|
@@ -341,10 +341,21 @@ export function postgresPoolFlags(opts) {
|
|
|
341
341
|
if (pooler !== undefined && pooler !== 'session' && pooler !== 'transaction') {
|
|
342
342
|
return `--pooler takes "session" or "transaction"; "${pooler}" is neither. It comes from the flag or ${envName('POOLER')}.`;
|
|
343
343
|
}
|
|
344
|
+
/* Environment only, like the deployment fact it is: how long a hosted database or its pooler lets a connection sit
|
|
345
|
+
idle. A connection's own "pool": { "idleSeconds" } wins over it (postgresPool.ts resolvePoolIdle). */
|
|
346
|
+
let idleSeconds;
|
|
347
|
+
const idle = productEnv('POOL_IDLE', env)?.trim();
|
|
348
|
+
if (idle) {
|
|
349
|
+
idleSeconds = /^\d+$/.test(idle) ? Number(idle) : Number.NaN;
|
|
350
|
+
if (!isIdleSeconds(idleSeconds)) {
|
|
351
|
+
return `${envName('POOL_IDLE')} takes whole seconds from 1 to ${MAX_IDLE_SECONDS}; "${idle}" is not one.`;
|
|
352
|
+
}
|
|
353
|
+
}
|
|
344
354
|
return {
|
|
345
355
|
...(readers !== undefined ? { readers } : {}),
|
|
346
356
|
...(writers !== undefined ? { writers } : {}),
|
|
347
357
|
...(pooler !== undefined ? { pooler } : {}),
|
|
348
358
|
...(lockTimeoutMs !== undefined ? { lockTimeoutMs } : {}),
|
|
359
|
+
...(idleSeconds !== undefined ? { idleSeconds } : {}),
|
|
349
360
|
};
|
|
350
361
|
}
|
|
@@ -301,7 +301,7 @@ interface ConfigFile {
|
|
|
301
301
|
rows?: boolean;
|
|
302
302
|
/** Table → columns never served over the connection (hiddenColumns.ts). */
|
|
303
303
|
hidden?: HiddenColumnRules;
|
|
304
|
-
/** `{ "read": n, "write": m }`: a PostgreSQL connection's pool sizes, checked by poolOf. */
|
|
304
|
+
/** `{ "read": n, "write": m, "idleSeconds": s, "minIdle": k }`: a PostgreSQL connection's pool sizes and idle window, checked by poolOf. */
|
|
305
305
|
pool?: unknown;
|
|
306
306
|
/** Read replicas' URLs, checked by replicasOf. */
|
|
307
307
|
replicas?: unknown;
|
|
@@ -478,6 +478,8 @@ export class Registry {
|
|
|
478
478
|
postgres: {
|
|
479
479
|
...(entry.config.pool.read !== undefined ? { readers: entry.config.pool.read } : {}),
|
|
480
480
|
...(entry.config.pool.write !== undefined ? { writers: entry.config.pool.write } : {}),
|
|
481
|
+
...(entry.config.pool.idleSeconds !== undefined ? { idleSeconds: entry.config.pool.idleSeconds } : {}),
|
|
482
|
+
...(entry.config.pool.minIdle !== undefined ? { minIdle: entry.config.pool.minIdle } : {}),
|
|
481
483
|
},
|
|
482
484
|
}
|
|
483
485
|
: {}),
|
|
@@ -16,6 +16,12 @@ const authoring = new Set();
|
|
|
16
16
|
export function authoringApp(path) {
|
|
17
17
|
authoring.add(path);
|
|
18
18
|
}
|
|
19
|
+
/* The test kit's host (mistri/testing, run from source) asks every refusal it answers to carry its cause, so a test
|
|
20
|
+
reads why a tenant member or a seeded role was refused without opening the host's log. The word alone is not
|
|
21
|
+
trusted: a process says it is a test (`NODE_ENV=test`) as well, so an environment file that carried the seam into a
|
|
22
|
+
deployment tells nobody anything. */
|
|
23
|
+
const TEST_REFUSAL_CAUSE = 'MISTRI_TEST_REFUSAL_CAUSE';
|
|
24
|
+
const causeForTests = (env = process.env) => env[TEST_REFUSAL_CAUSE] === 'source' && env.NODE_ENV === 'test';
|
|
19
25
|
/** Mark this request as the author's own, when it is: see the module comment. */
|
|
20
26
|
export function noteAuthorRequest(req, bound, administrator, apps) {
|
|
21
27
|
if (administrator &&
|
|
@@ -81,5 +87,5 @@ export function reportRefusal(req, status, code, heard, error, always = false) {
|
|
|
81
87
|
console.error(` because: ${reason}`);
|
|
82
88
|
}
|
|
83
89
|
// The innermost reason is the one that names the rule, the table or the column.
|
|
84
|
-
return authors.has(req) ? reasons.at(-1) : undefined;
|
|
90
|
+
return authors.has(req) || causeForTests() ? reasons.at(-1) : undefined;
|
|
85
91
|
}
|
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
export interface PoolSize {
|
|
3
3
|
read?: number;
|
|
4
4
|
write?: number;
|
|
5
|
+
/** Seconds an idle connection stays open; the server's (`MISTRI_POOL_IDLE`), else five minutes, when absent. */
|
|
6
|
+
idleSeconds?: number;
|
|
7
|
+
/** Connections each pool keeps open through an idle spell; two readers and one writer when absent. */
|
|
8
|
+
minIdle?: number;
|
|
5
9
|
}
|
|
6
10
|
/**
|
|
7
11
|
* Refused rather than clamped or ignored, as `writable` is: a number quietly
|
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* A connection's `"pool"` and `"replicas"` in tablewalk.json, checked where the file is read:
|
|
3
|
-
* `{ "read": n, "write": m
|
|
4
|
-
*
|
|
3
|
+
* `{ "read": n, "write": m, "idleSeconds": s, "minIdle": k }`: the sizes each a
|
|
4
|
+
* whole number from 1 to 64, the idle window whole seconds from 1 to a day, the
|
|
5
|
+
* warm count 0 to 64, every one optional, on a PostgreSQL connection. Apart from the loader because
|
|
5
6
|
* the rule is the pool's (postgresPool.ts holds the bounds); the loader only
|
|
6
7
|
* asks it, as it asks httpConnection.ts about an API's fields.
|
|
7
8
|
*/
|
|
8
|
-
import { isReaderCount, MAX_READERS } from '../adapters/postgresPool.js';
|
|
9
|
+
import { isIdleSeconds, isMinIdle, isReaderCount, MAX_IDLE_SECONDS, MAX_READERS } from '../adapters/postgresPool.js';
|
|
9
10
|
import { isWriterCount, MAX_WRITERS } from '../adapters/writeLanes.js';
|
|
10
11
|
import { MAX_REPLICAS } from '../adapters/replicas.js';
|
|
12
|
+
const POOL_KEYS = ['read', 'write', 'idleSeconds', 'minIdle'];
|
|
11
13
|
/**
|
|
12
14
|
* Refused rather than clamped or ignored, as `writable` is: a number quietly
|
|
13
15
|
* overridden is a capacity plan that is not the one in the file. An HTTP
|
|
@@ -28,12 +30,18 @@ export function poolOf(entry, http, path) {
|
|
|
28
30
|
throw new Error(`${where} has "pool": ${JSON.stringify(written)}. It must be an object such as { "read": 16, "write": 8 }.`);
|
|
29
31
|
}
|
|
30
32
|
const pool = written;
|
|
31
|
-
const stray = Object.keys(pool).find((key) => key
|
|
33
|
+
const stray = Object.keys(pool).find((key) => !POOL_KEYS.includes(key));
|
|
32
34
|
if (stray !== undefined)
|
|
33
|
-
throw new Error(`${where} has "pool.${stray}". A pool takes "read" and "
|
|
34
|
-
if (
|
|
35
|
+
throw new Error(`${where} has "pool.${stray}". A pool takes "read", "write", "idleSeconds" and "minIdle".`);
|
|
36
|
+
if (!POOL_KEYS.some((key) => pool[key] !== undefined)) {
|
|
35
37
|
throw new Error(`${where} has an empty "pool". Say how many connections may read or write at once, such as { "read": 16, "write": 8 }.`);
|
|
36
38
|
}
|
|
39
|
+
if (pool.idleSeconds !== undefined && !isIdleSeconds(pool.idleSeconds)) {
|
|
40
|
+
throw new Error(`${where} has "pool": { "idleSeconds": ${JSON.stringify(pool.idleSeconds)} }. It must be whole seconds from 1 to ${MAX_IDLE_SECONDS}, without quotes.`);
|
|
41
|
+
}
|
|
42
|
+
if (pool.minIdle !== undefined && !isMinIdle(pool.minIdle)) {
|
|
43
|
+
throw new Error(`${where} has "pool": { "minIdle": ${JSON.stringify(pool.minIdle)} }. It must be a whole number from 0 to ${MAX_READERS}, without quotes.`);
|
|
44
|
+
}
|
|
37
45
|
if (pool.read !== undefined && !isReaderCount(pool.read)) {
|
|
38
46
|
throw new Error(`${where} has "pool": { "read": ${JSON.stringify(pool.read)} }. It must be a whole number from 1 to ${MAX_READERS}, without quotes.`);
|
|
39
47
|
}
|
|
@@ -45,7 +53,12 @@ export function poolOf(entry, http, path) {
|
|
|
45
53
|
if (!/^postgres(ql)?:\/\//i.test(url))
|
|
46
54
|
throw new Error(`${where} is not a PostgreSQL connection; SQLite has no pool. Remove "pool".`);
|
|
47
55
|
}
|
|
48
|
-
return {
|
|
56
|
+
return {
|
|
57
|
+
...(pool.read !== undefined ? { read: pool.read } : {}),
|
|
58
|
+
...(pool.write !== undefined ? { write: pool.write } : {}),
|
|
59
|
+
...(pool.idleSeconds !== undefined ? { idleSeconds: pool.idleSeconds } : {}),
|
|
60
|
+
...(pool.minIdle !== undefined ? { minIdle: pool.minIdle } : {}),
|
|
61
|
+
};
|
|
49
62
|
}
|
|
50
63
|
/**
|
|
51
64
|
* A connection's `"replicas"`: `["postgres://…", "${REPLICA_URL}", …]`, read
|
|
@@ -353,14 +353,19 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
|
|
|
353
353
|
}
|
|
354
354
|
const results = Array.from({ length: items.length });
|
|
355
355
|
const queue = items.map((item, at) => ({ item, at }));
|
|
356
|
+
/* An item's route knows its own last wave, not the batch's: the others are
|
|
357
|
+
still queued, or between their reads, when it says so, and a tenant App's
|
|
358
|
+
fence that left with it refuses every read after (TenantReadContext.lastWave).
|
|
359
|
+
Only a batch of one is that route alone. */
|
|
360
|
+
const each = items.length === 1 ? options : { ...options, lastWave: undefined };
|
|
356
361
|
const one = async () => {
|
|
357
362
|
for (let next = queue.shift(); next; next = queue.shift()) {
|
|
358
363
|
const page = run(next.item);
|
|
359
364
|
const { def, text, limit, offset } = next.item;
|
|
360
365
|
try {
|
|
361
366
|
results[next.at] = (await (page
|
|
362
|
-
? dispatchResourceReadHttp('/api/run', Object.fromEntries(RUN_FIELDS.filter((field) => page[field] !== undefined).map((field) => [field, page[field]])), adapter, schema,
|
|
363
|
-
: dispatchResourceReadHttp('/api/breakdown', { def, text, limit, offset }, adapter, schema,
|
|
367
|
+
? dispatchResourceReadHttp('/api/run', Object.fromEntries(RUN_FIELDS.filter((field) => page[field] !== undefined).map((field) => [field, page[field]])), adapter, schema, each)
|
|
368
|
+
: dispatchResourceReadHttp('/api/breakdown', { def, text, limit, offset }, adapter, schema, each)));
|
|
364
369
|
}
|
|
365
370
|
catch (error) {
|
|
366
371
|
/* A request's own refusal (a ResourceReadError: the provider's are
|
|
@@ -428,7 +428,7 @@ export function parsePage(raw, at) {
|
|
|
428
428
|
params.length > MAX_PAGE_PARAMS ||
|
|
429
429
|
params.some((name) => typeof name !== 'string' || !PARAM.test(name)) ||
|
|
430
430
|
params.includes('period')) {
|
|
431
|
-
throw new Error(`[page-params] ${at} has "params" that are not up to ${MAX_PAGE_PARAMS} lowercase words, each 'id', 'text', 'date', 'date-range' or a list of its values, like params: { list: 'id' }; "period" is a dashboard's
|
|
431
|
+
throw new Error(`[page-params] ${at} has "params" that are not up to ${MAX_PAGE_PARAMS} lowercase words, each 'id', 'text', 'date', 'date-range' or a list of its values, like params: { list: 'id' }; "period" is a dashboard's address word, so a page's own window is named "window": params: { window: ['last-30-days', 'last-90-days'] }, read by a windowed <Metric window="window" over="close_date" previous spark />.`);
|
|
432
432
|
}
|
|
433
433
|
if (raw.loader !== undefined && (typeof raw.loader !== 'string' || !LOADER.test(raw.loader))) {
|
|
434
434
|
throw new Error(`[page-loader] ${at} has a "loader" that is not a loader's name, as the commands module's defineLoaders() registers it.`);
|
|
@@ -25,12 +25,36 @@ export declare function unitForSpan(days: number): AutoUnit;
|
|
|
25
25
|
export declare function readUnit(base: AutoUnit, addsUp: boolean): AutoUnit;
|
|
26
26
|
/** The label of the period a day, month or quarter label falls in, spelled as the server spells it. */
|
|
27
27
|
export declare function bucketKey(key: string, unit: AutoUnit, weekStart?: number): string;
|
|
28
|
+
interface FillOptions {
|
|
29
|
+
/** The unit the rows are keyed in: their keys are spelled as the server spells it (`2026-03-14`, `2026-03`, `2026-Q1`). */
|
|
30
|
+
unit: AutoUnit;
|
|
31
|
+
/** The first instant to fill from, its period included; absent, the first row's. */
|
|
32
|
+
from?: Date;
|
|
33
|
+
/** The last instant to fill to, its period included; absent, the last row's. */
|
|
34
|
+
to?: Date;
|
|
35
|
+
/** The zone `from` and `to` are read in, the App's: absent, their local fields. */
|
|
36
|
+
timeZone?: string;
|
|
37
|
+
/** The field a row's period is under: `key`, or the server's name for it (`day(created_at)`). */
|
|
38
|
+
key?: string;
|
|
39
|
+
/** The fields a filled period holds as 0: absent, the first row's numeric ones, else `value`. */
|
|
40
|
+
zero?: readonly string[];
|
|
41
|
+
weekStart?: number;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Rows keyed by period with the periods that held no rows put back as zero, marked `filled: true`, from `from`'s
|
|
45
|
+
* period to `to`'s (or the rows' own first and last), in order. A count of nothing is 0: a line drawn through only
|
|
46
|
+
* the days that had rows said a quiet week was a steady one. The periods are the App's calendar's (`timeZone`), so a
|
|
47
|
+
* moment near midnight falls on the day the people using the App say it did. Rows whose keys the unit does not spell
|
|
48
|
+
* come back as they came; only a count or a sum is honestly filled with 0, which the caller decides.
|
|
49
|
+
*/
|
|
50
|
+
export declare function fillBuckets<R extends Record<string, unknown>>(rows: readonly R[], { unit, from, to, timeZone, key, zero, weekStart }: FillOptions): Array<R | (Record<string, unknown> & {
|
|
51
|
+
filled: true;
|
|
52
|
+
})>;
|
|
28
53
|
/**
|
|
29
|
-
* A trend's points over its window: the periods that held no rows put back as zero, from the window's
|
|
30
|
-
* to today's, and the read periods added up into the unit the span is drawn in.
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
* unit does not spell are left as they came.
|
|
54
|
+
* A trend's points over its window: the periods that held no rows put back as zero (`fillBuckets`), from the window's
|
|
55
|
+
* first period to today's, and the read periods added up into the unit the span is drawn in. Three busy days of a
|
|
56
|
+
* week drew no line at all before. Only a count or a sum adds up so: any other measure's points are drawn as read,
|
|
57
|
+
* and labels the read unit does not spell are left as they came.
|
|
34
58
|
*/
|
|
35
59
|
export declare function trendPoints<R extends {
|
|
36
60
|
key: unknown;
|
|
@@ -131,28 +131,63 @@ const SPELLED = {
|
|
|
131
131
|
};
|
|
132
132
|
/** The local calendar day of a date, as the server spells a day. */
|
|
133
133
|
const localDay = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
|
|
134
|
+
/** The calendar day an instant falls on in a zone, as the server spells a day; with no zone, its local fields (the wall
|
|
135
|
+
clock `dateWindow` computes a zoned window in, `zonedNow`). */
|
|
136
|
+
function dayIn(d, timeZone) {
|
|
137
|
+
if (!timeZone)
|
|
138
|
+
return localDay(d);
|
|
139
|
+
const parts = new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(d);
|
|
140
|
+
const get = (type) => parts.find((p) => p.type === type)?.value ?? '';
|
|
141
|
+
return `${get('year')}-${get('month')}-${get('day')}`;
|
|
142
|
+
}
|
|
143
|
+
/** The label of the period an instant falls in, in a zone. */
|
|
144
|
+
const periodOf = (d, unit, timeZone, weekStart) => bucketKey(dayIn(d, timeZone), unit, weekStart);
|
|
134
145
|
/**
|
|
135
|
-
*
|
|
136
|
-
* to
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
146
|
+
* Rows keyed by period with the periods that held no rows put back as zero, marked `filled: true`, from `from`'s
|
|
147
|
+
* period to `to`'s (or the rows' own first and last), in order. A count of nothing is 0: a line drawn through only
|
|
148
|
+
* the days that had rows said a quiet week was a steady one. The periods are the App's calendar's (`timeZone`), so a
|
|
149
|
+
* moment near midnight falls on the day the people using the App say it did. Rows whose keys the unit does not spell
|
|
150
|
+
* come back as they came; only a count or a sum is honestly filled with 0, which the caller decides.
|
|
151
|
+
*/
|
|
152
|
+
export function fillBuckets(rows, { unit, from, to, timeZone, key = 'key', zero, weekStart = 1 }) {
|
|
153
|
+
const keys = rows.map((row) => String(row[key] ?? ''));
|
|
154
|
+
if (keys.some((k) => !SPELLED[unit].test(k)))
|
|
155
|
+
return [...rows];
|
|
156
|
+
const ends = [from, to].flatMap((d) => (d ? [periodOf(d, unit, timeZone, weekStart)] : []));
|
|
157
|
+
const sorted = [...keys, ...ends].sort();
|
|
158
|
+
if (!sorted.length)
|
|
159
|
+
return [...rows];
|
|
160
|
+
const numeric = rows.length ? Object.keys(rows[0]).filter((field) => field !== key && typeof rows[0][field] === 'number') : [];
|
|
161
|
+
const zeros = Object.fromEntries((zero ?? (numeric.length ? numeric : ['value'])).map((field) => [field, 0]));
|
|
162
|
+
const held = new Map(rows.map((row, i) => [keys[i], row]));
|
|
163
|
+
const out = [];
|
|
164
|
+
for (let at = sorted[0], n = 0; at <= sorted[sorted.length - 1] && n < 5000; at = nextKey(at, unit), n++)
|
|
165
|
+
/* The period first, as the server writes a row: the hook reads a row's measure as the column after its groups. */
|
|
166
|
+
out.push(held.get(at) ?? { [key]: at, ...zeros, filled: true });
|
|
167
|
+
return out;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* A trend's points over its window: the periods that held no rows put back as zero (`fillBuckets`), from the window's
|
|
171
|
+
* first period to today's, and the read periods added up into the unit the span is drawn in. Three busy days of a
|
|
172
|
+
* week drew no line at all before. Only a count or a sum adds up so: any other measure's points are drawn as read,
|
|
173
|
+
* and labels the read unit does not spell are left as they came.
|
|
140
174
|
*/
|
|
141
175
|
export function trendPoints(rows, read, unit, measure, window, now) {
|
|
142
176
|
if (!/^(count|sum\s+[\w.$+]+)(\s+as\s+[\w$]+)?$/i.test((measure ?? 'count').trim()))
|
|
143
177
|
return [...rows];
|
|
144
|
-
const
|
|
145
|
-
if (
|
|
178
|
+
const keyed = rows.map((row) => ({ key: String(row.key ?? ''), value: Number(row.value) || 0 }));
|
|
179
|
+
if (keyed.some((row) => !SPELLED[read].test(row.key)))
|
|
146
180
|
return [...rows];
|
|
147
|
-
|
|
148
|
-
const sorted = [...keys, ...ends.map((d) => bucketKey(localDay(d), read))].sort();
|
|
149
|
-
if (!sorted.length)
|
|
181
|
+
if (!keyed.length && !window)
|
|
150
182
|
return [...rows];
|
|
151
|
-
const
|
|
183
|
+
const filled = fillBuckets(keyed, {
|
|
184
|
+
unit: read,
|
|
185
|
+
...(window ? { from: window.start, to: new Date(Math.min(window.end.getTime() - 1, now.getTime())) } : {}),
|
|
186
|
+
});
|
|
152
187
|
const into = new Map();
|
|
153
|
-
for (
|
|
154
|
-
const label = bucketKey(key, unit);
|
|
155
|
-
into.set(label, (into.get(label) ?? 0) + (
|
|
188
|
+
for (const row of filled) {
|
|
189
|
+
const label = bucketKey(String(row.key), unit);
|
|
190
|
+
into.set(label, (into.get(label) ?? 0) + (Number(row.value) || 0));
|
|
156
191
|
}
|
|
157
192
|
return [...into].map(([key, value]) => ({ key, value }));
|
|
158
193
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mistriwork/engine",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.77",
|
|
4
4
|
"description": "The engine both products stand on: the adapters (SQLite, Postgres), the catalog, the query language, keyset pages, the HTTP kit and the shared rules. No React.",
|
|
5
5
|
"homepage": "https://mistriwork.dev",
|
|
6
6
|
"bugs": {
|