@mistriwork/engine 1.0.0-rc.71 → 1.0.0-rc.73

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.
@@ -91,8 +91,13 @@ export interface PgConnectionOptions {
91
91
  /** Only readers are ever opened here (a tenant App's replica): the budget counts them and no writer. */
92
92
  readonly readersOnly?: boolean;
93
93
  }
94
+ /** The fewest readers an App's pool holds where none was chosen, whatever the cores. A page's reads leave at once,
95
+ * each on a reader of its own where they do not share a snapshot, and on a database a round trip away a page that
96
+ * waited for one of four readers paid its round trips in turns (a profile: one or two cores, 30 ms away). Readers
97
+ * are opened as they are asked and all but WARM_READERS let go idle, so the floor costs connections only under load. */
98
+ export declare const APP_READER_FLOOR = 10;
94
99
  /** An App's reader pool where none was chosen: as wide as its writers, at least the balanced size for `cores`
95
- * (this machine's, unless a deployment check asks for another's). */
100
+ * (this machine's, unless a deployment check asks for another's) and APP_READER_FLOOR. */
96
101
  export declare function appReaders(writers: number, cores?: number): number;
97
102
  /**
98
103
  * The defaults every manager in this process takes when it names none: the
@@ -7,8 +7,8 @@
7
7
  * from the command line:
8
8
  *
9
9
  * - How many readers the pool may hold: for an App as many as its writers
10
- * (at least balancedPoolSize), four for the database browser, unless told
11
- * otherwise; one to sixty-four.
10
+ * (at least balancedPoolSize and APP_READER_FLOOR, ten), four for the
11
+ * database browser, unless told otherwise; one to sixty-four.
12
12
  * - How many writers: balancedPoolSize for a process serving Apps unless told otherwise
13
13
  * (`pool.write`, `--write-pool`; writeLanes.ts), one to sixty-four, each running one
14
14
  * transaction beside the others (writeLanes.ts orders writes of one
@@ -65,10 +65,17 @@ const loadPg = async () => {
65
65
  * An App's is balanced against its writers (appReaders). */
66
66
  export const DEFAULT_READERS = 4;
67
67
  /** Readers kept connected through an idle spell. Without them the first read
68
- * after thirty quiet seconds paid a new connection and its two SETs — and a
68
+ * after a quiet spell paid a new connection and its two SETs — and a
69
69
  * dashboard's fan-out paid it several times at once. Two, not the whole pool:
70
70
  * a warm connection is a server backend held for nothing most of the day. */
71
71
  const WARM_READERS = 2;
72
+ /** Writers kept connected through an idle spell: one, for the same reason, so the first command after a quiet
73
+ * spell does not reconnect (a field report: about 230 ms on a hosted database). One is enough: a burst of commands
74
+ * opens the rest as it asks, and a backend held warm per writer would cost most when the pool is widest. */
75
+ const WARM_WRITERS = 1;
76
+ /** How long an idle connection stays open: five minutes, past a lunch-hour lull but well inside what a
77
+ * hosted database or its pooler lets a connection sit. The extra ones (beyond the warm minimum) close then. */
78
+ const IDLE_TIMEOUT_MS = 300_000;
72
79
  /** The most readers one database's pool may hold. Past this, a pooler in front of the server is the tool. */
73
80
  export const MAX_READERS = 64;
74
81
  /** What pg-pool says when no connection came free within the acquisition timeout. */
@@ -91,10 +98,15 @@ let timing;
91
98
  function defaultReaders(writers) {
92
99
  return writeOrder() === 'keyed' ? appReaders(writers) : DEFAULT_READERS;
93
100
  }
101
+ /** The fewest readers an App's pool holds where none was chosen, whatever the cores. A page's reads leave at once,
102
+ * each on a reader of its own where they do not share a snapshot, and on a database a round trip away a page that
103
+ * waited for one of four readers paid its round trips in turns (a profile: one or two cores, 30 ms away). Readers
104
+ * are opened as they are asked and all but WARM_READERS let go idle, so the floor costs connections only under load. */
105
+ export const APP_READER_FLOOR = 10;
94
106
  /** An App's reader pool where none was chosen: as wide as its writers, at least the balanced size for `cores`
95
- * (this machine's, unless a deployment check asks for another's). */
107
+ * (this machine's, unless a deployment check asks for another's) and APP_READER_FLOOR. */
96
108
  export function appReaders(writers, cores) {
97
- return Math.min(MAX_READERS, Math.max(balancedPoolSize(cores), writers));
109
+ return Math.min(MAX_READERS, Math.max(APP_READER_FLOOR, balancedPoolSize(cores), writers));
98
110
  }
99
111
  /**
100
112
  * The defaults every manager in this process takes when it names none: the
@@ -345,16 +357,14 @@ export class PgConnectionManager {
345
357
  ...this.dialOptions(),
346
358
  max: this.meters[role].size,
347
359
  connectionTimeoutMillis: 10_000,
348
- idleTimeoutMillis: 30_000,
349
- /* Readers only: a writer is opened for a write and may go. The idle
350
- ones never keep the process alive by themselves, so a one-shot mode
351
- that forgets to close still exits. */
352
- ...(write
353
- ? {}
354
- : {
355
- min: Math.min(WARM_READERS, this.meters[role].size),
356
- allowExitOnIdle: true,
357
- }),
360
+ idleTimeoutMillis: IDLE_TIMEOUT_MS,
361
+ /* Readers and the foreground writers keep a few connections warm
362
+ (the background writer, which runs jobs that are not waited on, keeps none). The
363
+ idle ones never keep the process alive by themselves, so a one-shot
364
+ mode that forgets to close still exits: that is why the writer
365
+ sets this too, now that it holds a connection through idle. */
366
+ allowExitOnIdle: true,
367
+ ...(role === 'background' ? {} : { min: Math.min(role === 'read' ? WARM_READERS : WARM_WRITERS, this.meters[role].size) }),
358
368
  /* A writer sends each statement as it is asked, not after the one
359
369
  before it is answered: a transaction that asks several at once
360
370
  (pipelined, postgresTransactionHandle.ts) pays one round trip for
@@ -76,9 +76,17 @@ export async function readSnapshotOn(connections, describe, run, observeCheckout
76
76
  if (ended || typeof next !== 'string' || !next.trim())
77
77
  throw new Refusal('The read snapshot is unavailable.');
78
78
  ended = true;
79
- if (ahead)
80
- await begun;
81
- const closed = (await client.query(`COMMIT; ${BEGIN_SNAPSHOT}${session}; ${next}; COMMIT`));
79
+ /* Sent at once, not after the BEGIN's answer: an owner may end the snapshot while its last reads are still in
80
+ flight, and on a reader that pipelines the end then leaves behind them, in their flight. The server runs a
81
+ connection's statements in order, so the fresh snapshot `next` reads in still begins after every read on
82
+ this one has finished. A BEGIN that failed is heard first, as before. */
83
+ const sent = client.query(`COMMIT; ${BEGIN_SNAPSHOT}${session}; ${next}; COMMIT`);
84
+ const [opened, ending] = await Promise.allSettled([ahead ? begun : undefined, sent]);
85
+ if (opened.status === 'rejected')
86
+ throw opened.reason;
87
+ if (ending.status === 'rejected')
88
+ throw ending.reason;
89
+ const closed = ending.value;
82
90
  return Object.freeze((Array.isArray(closed) ? closed : [closed]).slice(2 + set, -1));
83
91
  };
84
92
  try {
@@ -41,6 +41,9 @@ export interface StartupConfig {
41
41
  /** `"presentation": { "<app>": { name, logo, theme, locale } }`, as written: one deployment's name, logo, theme and
42
42
  locale for an App, which the App framework checks and applies (mistri app/appPresentation.ts). Never read by the browser. */
43
43
  presentation?: unknown;
44
+ /** `"auth": { "<app>": { "store": "…" } }`, as written: where one deployment keeps an App's accounts and sessions,
45
+ which wins over the App's own `auth.store` (mistri app/deploymentAuth.ts). Never read by the browser. */
46
+ auth?: unknown;
44
47
  }
45
48
  /**
46
49
  * Whether the config file a start would read names Apps: read raw, before anything is said of it, so the database
@@ -182,9 +182,11 @@ export async function readStartupConfig(opts, registry, given) {
182
182
  }
183
183
  /* Where the Apps are served, beside which Apps: a deployment's fact,
184
184
  checked with the flags' own rule once the Apps are loaded (main). */
185
- const { mount, basePath, presentation } = JSON.parse(await readFile(config.path, 'utf8'));
185
+ const { mount, basePath, presentation, auth } = JSON.parse(await readFile(config.path, 'utf8'));
186
186
  if (presentation !== undefined)
187
187
  read.presentation = presentation;
188
+ if (auth !== undefined)
189
+ read.auth = auth;
188
190
  if (mount !== undefined) {
189
191
  if (!mount || typeof mount !== 'object' || Array.isArray(mount) || Object.values(mount).some((at) => typeof at !== 'string')) {
190
192
  throw new Error(`${config.path}: "mount" must name each App's place by its id, like { "main": "/", "billing": "/billing" }.`);
@@ -53,6 +53,13 @@ interface ResourceReadHttpOptions {
53
53
  * by another name.
54
54
  */
55
55
  rowsMost?: (table: string) => number | undefined;
56
+ /**
57
+ * Asked just before a route's last wave of reads, where the routes below
58
+ * can say which that is: every read after it leaves in that one wave. A
59
+ * tenant App's bounded request lets its release fence leave with it
60
+ * (TenantReadContext.lastWave). Internal; absent, nothing.
61
+ */
62
+ lastWave?: () => void;
56
63
  }
57
64
  interface ResourceReadHttpReply {
58
65
  status: number;
@@ -110,6 +110,7 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
110
110
  return refused;
111
111
  }
112
112
  if (path === '/api/query') {
113
+ options.lastWave?.();
113
114
  const { result, order } = await readRecords(adapter, schema, {
114
115
  table: String(body.table ?? ''),
115
116
  filter: body.filter,
@@ -143,6 +144,8 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
143
144
  return refusal(400, [`lanes is { by: a column, limit: 1 to ${LANE_MOST} }.`]);
144
145
  const text = String(body.q ?? '');
145
146
  const person = await personFor(text);
147
+ /* Every branch below reads in one wave, rows beside their count (readRecords, readView), or not at all. */
148
+ options.lastWave?.();
146
149
  const parsed = parseQuery(text, { schema, now: options.now(), ...person });
147
150
  /* A view is a superset of a query, so the bar can take one.
148
151
  `invoice customer_id.name contains Harbour` is not a legal single-table
@@ -298,8 +301,9 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
298
301
  }
299
302
  results[at] = { errors: parsed.errors.length ? parsed.errors : [{ message: 'That question does not read as a count.' }] };
300
303
  }
304
+ /* The plain counts are the last wave only where no view's count is still reading beside them. */
301
305
  const batch = plain.length
302
- ? readCounts(adapter, schema, plain, body.countLimit).then((counts) => {
306
+ ? readCounts(adapter, schema, plain, body.countLimit, views.length ? undefined : options.lastWave).then((counts) => {
303
307
  plain.forEach(({ at }, i) => {
304
308
  results[at] = {
305
309
  total: counts[i].count,
@@ -471,6 +475,8 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
471
475
  let view = normaliseView(body.view);
472
476
  let merged = view;
473
477
  const person = await personFor(body.text, body.query);
478
+ // One wave from here: the view's rows beside its count (readView).
479
+ options.lastWave?.();
474
480
  const errors = [];
475
481
  if (!view.base && typeof body.text !== 'string') {
476
482
  return refusal(400, ['A view needs a base table.']);
@@ -546,6 +552,7 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
546
552
  most that many rows are counted, and past it the answer is the bound with
547
553
  `capped`. Absent, the count is the one these routes always gave. */
548
554
  if (path === '/api/count') {
555
+ options.lastWave?.();
549
556
  const result = await readCount(adapter, schema, {
550
557
  table: String(body.table ?? ''),
551
558
  filter: body.filter,
@@ -73,7 +73,7 @@ export declare function readCount(reader: ResourceReader, schema: DatabaseSchema
73
73
  export declare function readCounts(reader: ResourceReader, schema: DatabaseSchema, inputs: ReadonlyArray<{
74
74
  table: string;
75
75
  filter?: Filter;
76
- }>, countLimit?: unknown): Promise<CountResult[]>;
76
+ }>, countLimit?: unknown, lastWave?: () => void): Promise<CountResult[]>;
77
77
  export declare function readRecords(reader: ResourceReader, schema: DatabaseSchema, input: RecordReadInput, countMode?: ReadCountMode, countLimit?: unknown, continuation?: RecordsContinuation): Promise<{
78
78
  request: QueryRequest;
79
79
  result: import("@mistriwork/engine/adapters/adapter.js").QueryResult;
@@ -239,7 +239,9 @@ export async function readCount(reader, schema, input) {
239
239
  * `capped` past it. An unfiltered count of a table the catalog calls large is
240
240
  * the catalog's estimate instead, as a list's own total is.
241
241
  */
242
- export async function readCounts(reader, schema, inputs, countLimit) {
242
+ export async function readCounts(reader, schema, inputs, countLimit,
243
+ /* Asked just before the last wave of counts (resourceReadHttp.ts `lastWave`): the one statement, or the last window. */
244
+ lastWave) {
243
245
  const given = snapshotScopedData(inputs);
244
246
  const bound = countLimitOf(countLimit) ?? DEFAULT_COUNT_LIMIT;
245
247
  const items = given.map((item) => ({ table: checkedTable(schema, item.table, item).id, filter: item.filter }));
@@ -255,6 +257,7 @@ export async function readCounts(reader, schema, inputs, countLimit) {
255
257
  const said = (n) => (n > bound ? { count: bound, exact: true, capped: true } : { count: n, exact: true });
256
258
  const each = rest.length > 1 ? capture(reader, { countEach: true }).countEach : undefined;
257
259
  if (each) {
260
+ lastWave?.();
258
261
  const counts = await each(rest.map(({ item }) => item), bound + 1);
259
262
  rest.forEach(({ i }, at) => {
260
263
  results[i] = said(counts[at]);
@@ -266,7 +269,7 @@ export async function readCounts(reader, schema, inputs, countLimit) {
266
269
  throw new ResourceReadError(501, 'This connection cannot count records.');
267
270
  await inWindows(rest, async ({ item, i }) => {
268
271
  results[i] = said(await count(item.table, item.filter, bound + 1));
269
- });
272
+ }, lastWave);
270
273
  }
271
274
  return results;
272
275
  }
@@ -277,8 +280,10 @@ export async function readCounts(reader, schema, inputs, countLimit) {
277
280
  whole before a failure is thrown, so no count is still running when the
278
281
  request answers, and no further window starts after one. */
279
282
  const COUNT_WINDOW = 4;
280
- async function inWindows(items, run) {
283
+ async function inWindows(items, run, last) {
281
284
  for (let at = 0; at < items.length; at += COUNT_WINDOW) {
285
+ if (at + COUNT_WINDOW >= items.length)
286
+ last?.();
282
287
  const settled = await Promise.allSettled(items.slice(at, at + COUNT_WINDOW).map(run));
283
288
  const failed = settled.find((result) => result.status === 'rejected');
284
289
  if (failed)
@@ -1,6 +1,10 @@
1
- import type { AppListEmpty } from './listPresentations.js';
1
+ import type { AppListEmpty, AppListLink } from './listPresentations.js';
2
2
  /** Read the shared empty-list copy used by list views and related sections. */
3
3
  export declare function parseListEmpty(raw: unknown, at: string): AppListEmpty;
4
+ /** A list's `{ label, to }` to another room: its empty state's action, and the link at its head (a list view's
5
+ `link`). One shape, so the two read as one thing; where `to` may go is judged where the App is whole
6
+ (appDestinations.ts). */
7
+ export declare function parseListLink(raw: unknown, at: string): AppListLink;
4
8
  /** The authored shape again, for a definition written back out. */
5
9
  export declare function listEmptyConfig(empty: AppListEmpty): {
6
10
  title: string;
@@ -18,15 +18,20 @@ export function parseListEmpty(raw, at) {
18
18
  const result = { title, ...(description === undefined ? {} : { description }) };
19
19
  if (raw.action === undefined)
20
20
  return result;
21
- if (!isRecord(raw.action))
22
- throw new Error(`${here}, "action" must be an object with "label" and "to".`);
23
- const actionAt = `${here}, "action"`;
24
- allowKeys(raw.action, ['label', 'to'], actionAt);
25
- const label = parseCaption(raw.action.label, `${actionAt} needs a non-empty "label"`);
26
- const to = typeof raw.action.to === 'string' || isRecord(raw.action.to) ? parseLinkTo(raw.action.to, `${actionAt}, "to"`) : undefined;
21
+ return { ...result, action: parseListLink(raw.action, `${here}, "action"`) };
22
+ }
23
+ /** A list's `{ label, to }` to another room: its empty state's action, and the link at its head (a list view's
24
+ `link`). One shape, so the two read as one thing; where `to` may go is judged where the App is whole
25
+ (appDestinations.ts). */
26
+ export function parseListLink(raw, at) {
27
+ if (!isRecord(raw))
28
+ throw new Error(`${at} must be an object with "label" and "to".`);
29
+ allowKeys(raw, ['label', 'to'], at);
30
+ const label = parseCaption(raw.label, `${at} needs a non-empty "label"`);
31
+ const to = typeof raw.to === 'string' || isRecord(raw.to) ? parseLinkTo(raw.to, `${at}, "to"`) : undefined;
27
32
  if (!to || !('view' in to))
28
- throw new Error(`${actionAt} needs a "to": the key of a list, a dashboard or a signed-in form view, or { view, tab }.`);
29
- return { ...result, action: { label, ...to } };
33
+ throw new Error(`${at} needs a "to": the key of a list, a dashboard or a signed-in form view, or { view, tab }.`);
34
+ return { label, ...to };
30
35
  }
31
36
  /** The authored shape again, for a definition written back out. */
32
37
  export function listEmptyConfig(empty) {
@@ -194,11 +194,14 @@ export type AppListPresentation = AppTreeList | AppGanttList | AppChecklist | Ap
194
194
  export interface AppListEmpty {
195
195
  title: string;
196
196
  description?: string;
197
- action?: {
198
- label: string;
199
- view: string; /** The tab of a list it opens on, by its address word. */
200
- tab?: string;
201
- };
197
+ action?: AppListLink;
198
+ }
199
+ /** A list's way to another room: its empty state's action, and the link at its head (a list view's `link`). */
200
+ export interface AppListLink {
201
+ label: string;
202
+ view: string;
203
+ /** The tab of a list it opens on, by its address word. */
204
+ tab?: string;
202
205
  }
203
206
  /** Whether the Export menu is offered for a table, here and not beside the payload that sets `exportableTables`, since a list's first paint asks it and appPayload.ts imports the manifest parser: `ui.export` is the App's switch, and `exportableTables` (present in an App that grants by role) the person's. */
204
207
  export declare const exportOffered: (app: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mistriwork/engine",
3
- "version": "1.0.0-rc.71",
3
+ "version": "1.0.0-rc.73",
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": {