@mistriwork/engine 1.0.0-rc.75 → 1.0.0-rc.78

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 (54) hide show
  1. package/dist/adapters/adapter.d.ts +6 -0
  2. package/dist/adapters/postgres.js +13 -7
  3. package/dist/adapters/postgresPool.d.ts +28 -0
  4. package/dist/adapters/postgresPool.js +36 -3
  5. package/dist/adapters/scoped/scopedReads.js +5 -1
  6. package/dist/adapters/scoped/scopedTransaction.js +3 -1
  7. package/dist/adapters/serverSettings.d.ts +2 -0
  8. package/dist/adapters/sqlite.js +7 -5
  9. package/dist/server/cli/args.d.ts +2 -1
  10. package/dist/server/cli/args.js +13 -2
  11. package/dist/server/columnGrants.d.ts +3 -0
  12. package/dist/server/columnGrants.js +29 -4
  13. package/dist/server/connections.d.ts +1 -1
  14. package/dist/server/connections.js +2 -0
  15. package/dist/server/http/probes.d.ts +10 -1
  16. package/dist/server/http/probes.js +6 -2
  17. package/dist/server/http/recordWrites.js +7 -1
  18. package/dist/server/http/refusalReport.js +7 -1
  19. package/dist/server/http/serverCore.d.ts +2 -1
  20. package/dist/server/migrate/cli.js +7 -0
  21. package/dist/server/poolConfig.d.ts +4 -0
  22. package/dist/server/poolConfig.js +20 -7
  23. package/dist/server/resourceReadHttp.js +7 -2
  24. package/dist/server/resourceReadOperations.js +5 -1
  25. package/dist/shared/aggregate.js +7 -1
  26. package/dist/shared/appComponents.js +1 -1
  27. package/dist/shared/autoBucket.d.ts +29 -5
  28. package/dist/shared/autoBucket.js +49 -14
  29. package/dist/shared/computedParse.d.ts +2 -0
  30. package/dist/shared/computedParse.js +1 -1
  31. package/dist/shared/computedWhere.d.ts +47 -0
  32. package/dist/shared/computedWhere.js +159 -0
  33. package/dist/shared/filter.d.ts +5 -0
  34. package/dist/shared/filter.js +4 -0
  35. package/dist/shared/query.js +20 -22
  36. package/dist/shared/queryDates.d.ts +16 -0
  37. package/dist/shared/queryDates.js +29 -0
  38. package/dist/shared/queryOperands.d.ts +24 -0
  39. package/dist/shared/queryOperands.js +36 -0
  40. package/dist/shared/refusal.d.ts +8 -0
  41. package/dist/shared/refusal.js +15 -0
  42. package/dist/shared/resourceHttp.d.ts +1 -1
  43. package/dist/shared/rowCondition.d.ts +5 -0
  44. package/dist/shared/rowCondition.js +80 -0
  45. package/dist/shared/schema.d.ts +10 -0
  46. package/dist/shared/schema.js +8 -0
  47. package/dist/shared/scopeCatalog.d.ts +1 -1
  48. package/dist/shared/scopeCatalog.js +13 -1
  49. package/dist/shared/servedApp.d.ts +19 -0
  50. package/dist/shared/structuredFilter.d.ts +3 -0
  51. package/dist/shared/viewLabels.d.ts +6 -1
  52. package/dist/shared/viewLabels.js +1 -1
  53. package/package.json +2 -1
  54. package/schema/model.d.ts +12 -3
@@ -823,6 +823,12 @@ export interface UpdateResult {
823
823
  affected: number;
824
824
  /** Values after coercion to their column types, for the caller to confirm. */
825
825
  applied: Record<string, string | number | boolean | null>;
826
+ /**
827
+ * The row as the UPDATE left it, where the engine gives it back with the
828
+ * write (a PostgreSQL transaction's `RETURNING *`); absent elsewhere, and
829
+ * dropped by any layer that writes again before handing the result on.
830
+ */
831
+ row?: Record<string, unknown>;
826
832
  sql: {
827
833
  text: string;
828
834
  params: unknown[];
@@ -9,7 +9,7 @@
9
9
  */
10
10
  import { isProxy } from 'node:util/types';
11
11
  import { inlineRows, inlineWithin } from '../shared/anyRows.js';
12
- import { asksAboutRows } from '../shared/filter.js';
12
+ import { asksComputed, computedTable, readsCatalog, withComputedWhere } from '../shared/computedWhere.js';
13
13
  import { qualifiedTable } from '../shared/sqlRelation.js';
14
14
  import { POSTGRES_STYLE, buildWhere, clampLimit, clampOffset, Refusal, WriteConflict, TransactionOperations, queueRecordLock, recordLockFilter, TransactionOutcomeUnknown, countStatement, countEachStatement, countEachRows, countsTogether, orderClause, lanesStatement, withoutLaneRow, refuseUpdateMatches, } from './adapter.js';
15
15
  import { compileAggregate } from '../shared/aggregate.js';
@@ -525,18 +525,20 @@ export class PostgresAdapter {
525
525
  (commandDb.ts). The catalog is read only when the filter asks, and a filter that asks of a catalog this handle
526
526
  cannot read is refused, as one nothing resolves is. */
527
527
  async whereOf(id, qualified, filter) {
528
- if (!asksAboutRows(filter))
528
+ if (!readsCatalog(filter))
529
529
  return buildWhere(filter, POSTGRES_STYLE);
530
530
  const schema = await this.schema().catch(() => undefined);
531
531
  const inline = schema && inlineRows(schema, id, qualified, POSTGRES_STYLE, (child) => qualifiedTable(schema, child.id, POSTGRES_STYLE));
532
532
  /* Another table's keys (`in`) are read as this table is, from its own relation: the same bound. */
533
533
  const within = schema && inlineWithin(schema, POSTGRES_STYLE, (other) => qualifiedTable(schema, other.id, POSTGRES_STYLE));
534
- return buildWhere(filter, POSTGRES_STYLE, 1, undefined, undefined, undefined, undefined, false, undefined, false, inline, within);
534
+ /* A computed column is written as its expression over this table's own columns (computedWhere.ts). */
535
+ const own = filter && asksComputed(filter) ? withComputedWhere(filter, computedTable(schema, id), POSTGRES_STYLE) : undefined;
536
+ return buildWhere(own?.filter ?? filter, POSTGRES_STYLE, 1, own?.column, undefined, undefined, undefined, false, undefined, false, inline, within);
535
537
  }
536
538
  async queryOn(request, db, read = false) {
537
539
  const { schema, name } = read ? await this.readTable(request.table) : await this.assertTable(request.table, db);
538
540
  const qualified = `${POSTGRES_STYLE.quote(schema)}.${POSTGRES_STYLE.quote(name)}`;
539
- const where = asksAboutRows(request.filter)
541
+ const where = readsCatalog(request.filter)
540
542
  ? await this.whereOf(request.table, qualified, request.filter)
541
543
  : buildWhere(request.filter, POSTGRES_STYLE);
542
544
  const cols = request.columns?.length ? request.columns.map((c) => POSTGRES_STYLE.quote(c)).join(', ') : '*';
@@ -665,7 +667,7 @@ export class PostgresAdapter {
665
667
  async countOn(table, filter, db, limit, read = false) {
666
668
  const { schema, name } = read ? await this.readTable(table) : await this.assertTable(table, db);
667
669
  const qualified = `${POSTGRES_STYLE.quote(schema)}.${POSTGRES_STYLE.quote(name)}`;
668
- const where = asksAboutRows(filter) ? await this.whereOf(table, qualified, filter) : buildWhere(filter, POSTGRES_STYLE);
670
+ const where = readsCatalog(filter) ? await this.whereOf(table, qualified, filter) : buildWhere(filter, POSTGRES_STYLE);
669
671
  const text = countStatement(`${qualified}${where.text}`, limit);
670
672
  const result = await db.query(text, where.params);
671
673
  return Number(result.rows[0]?.n ?? 0);
@@ -765,7 +767,10 @@ export class PostgresAdapter {
765
767
  const assignments = columns.map((c, i) => `${POSTGRES_STYLE.quote(c)} = ${POSTGRES_STYLE.placeholder(i + 1)}`).join(', ');
766
768
  const where = buildWhere(filter, POSTGRES_STYLE, columns.length + 1);
767
769
  const guard = buildUpdateGuard(request, Object.fromEntries(meta.map((column) => [column.name, column.type])), POSTGRES_STYLE, 'postgres', columns.length + where.params.length + 1);
768
- const text = `UPDATE ${qualified(found)} SET ${assignments}${where.text}${guard.text}`;
770
+ /* Inside a transaction the row comes back with the write, as insert's does: an App that validates the stored
771
+ row after its save (appValidation.ts validateStoredPostImage) read it again, a round trip of its own between
772
+ the UPDATE and the COMMIT. Outside one nothing validates after, so nothing comes back. */
773
+ const text = `UPDATE ${qualified(found)} SET ${assignments}${where.text}${guard.text}${transactional ? ' RETURNING *' : ''}`;
769
774
  const params = [...Object.values(applied), ...where.params, ...guard.params];
770
775
  const result = await write.query(text, params);
771
776
  if (request.expected !== undefined && Number(result.rowCount ?? 0) === 0)
@@ -775,7 +780,8 @@ export class PostgresAdapter {
775
780
  /* Postgres counts rows matched, not rows whose bytes changed, so saving a
776
781
  cell without changing its value still reports 1 — the editor would
777
782
  otherwise tell the user a successful write failed. */
778
- return { affected: Number(result.rowCount ?? 0), applied, sql: { text, params } };
783
+ const row = transactional && result.rows?.length === 1 ? toJsonSafe(result.rows[0]) : undefined;
784
+ return { affected: Number(result.rowCount ?? 0), applied, ...(row ? { row } : {}), sql: { text, params } };
779
785
  }
780
786
  /**
781
787
  * Add one row.
@@ -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
- configureServerSettings({ readers, pooler });
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: IDLE_TIMEOUT_MS,
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: Math.min(role === 'read' ? WARM_READERS : WARM_WRITERS, this.meters[role].size) }),
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
@@ -9,6 +9,7 @@ import { compileAggregate } from '../../shared/aggregate.js';
9
9
  import { childRows, plannedWithin, withinRows } from '../../shared/anyRows.js';
10
10
  import { readExactly, summed } from '../../shared/decimals.js';
11
11
  import { RequestFault } from '../../shared/refusal.js';
12
+ import { asksComputed, withComputedWhere } from '../../shared/computedWhere.js';
12
13
  import { storedTextOf, storedTextSelect } from './storedText.js';
13
14
  /** Structured read arguments must not retain mutable values across driver
14
15
  * waits. This is deliberately separate from stricter nonempty policy filters:
@@ -151,7 +152,10 @@ references = false) {
151
152
  throw new RequestFault("This read cannot compare a column with another table's rows.");
152
153
  })()
153
154
  : undefined;
154
- const where = buildWhere(filter, style, prefix.params.length + 1, column, undefined, undefined, exists, references, typeIn(table), false, undefined, within);
155
+ /* A computed column is written as its expression over this table's own columns (computedWhere.ts), each read
156
+ through the same resolver, so a column this read cannot name is refused inside the expression as outside. */
157
+ const own = filter && asksComputed(filter) ? withComputedWhere(filter, table, style, column, typeIn(table)) : undefined;
158
+ const where = buildWhere(own?.filter ?? filter, style, prefix.params.length + 1, own?.column ?? column, undefined, undefined, exists, references, own?.types ?? typeIn(table), false, undefined, within);
155
159
  return { table, column, relation, prefix, where, params: [...prefix.params, ...where.params] };
156
160
  };
157
161
  /* A SQLite sum that cannot be exact says so in its cell (decimals.ts); PostgreSQL's numeric always is. */
@@ -828,7 +828,9 @@ referencesOf) {
828
828
  shiftedRefusal(table, protectedColumns, before, now);
829
829
  await parents(table, now, set);
830
830
  await afterward(afterwards, { new: now, old: before });
831
- return result;
831
+ // The row the UPDATE returned was not read through the scope, and what ran after it may have written it again.
832
+ const { row: _unscoped, ...said } = result;
833
+ return said;
832
834
  };
833
835
  /* A batch keeps every rule a row at a time keeps, and pays its flights once: the references it gives checked before
834
836
  its one statement, a foreign key a read (combined), then one locked read of the rows it wrote, key IN (…), and
@@ -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
  /**
@@ -13,7 +13,7 @@ import { waitForLocks, assertIndependentWrite, writeToFile, prepareGuarded, tran
13
13
  export { cachedStatement, schemaFingerprint } from './sqliteHandles.js';
14
14
  import { captureScopeCatalog, mapScopeCatalog } from '../shared/scopeCatalog.js';
15
15
  import { inlineRows, inlineWithin } from '../shared/anyRows.js';
16
- import { asksAboutRows } from '../shared/filter.js';
16
+ import { asksComputed, computedTable, readsCatalog, withComputedWhere } from '../shared/computedWhere.js';
17
17
  import { qualifiedTable } from '../shared/sqlRelation.js';
18
18
  import { DatabaseSync } from 'node:sqlite';
19
19
  import { isPromise, isProxy } from 'node:util/types';
@@ -495,13 +495,15 @@ export class SqliteAdapter {
495
495
  (commandDb.ts). The catalog is read only when the filter asks, and a filter that asks of a catalog this handle
496
496
  cannot read is refused, as one nothing resolves is. */
497
497
  async whereOf(id, relation, filter) {
498
- if (!asksAboutRows(filter))
498
+ if (!readsCatalog(filter))
499
499
  return buildWhere(filter, ANSI_STYLE);
500
500
  const schema = await this.schema().catch(() => undefined);
501
501
  const inline = schema && inlineRows(schema, id, ANSI_STYLE.quote(relation), ANSI_STYLE, (child) => qualifiedTable(schema, child.id, ANSI_STYLE));
502
502
  /* Another table's keys (`in`) are read as this table is, from its own relation: the same bound. */
503
503
  const within = schema && inlineWithin(schema, ANSI_STYLE, (other) => qualifiedTable(schema, other.id, ANSI_STYLE));
504
- return buildWhere(filter, ANSI_STYLE, 1, undefined, undefined, undefined, undefined, false, undefined, false, inline, within);
504
+ /* A computed column is written as its expression over this table's own columns (computedWhere.ts). */
505
+ const own = filter && asksComputed(filter) ? withComputedWhere(filter, computedTable(schema, id), ANSI_STYLE) : undefined;
506
+ return buildWhere(own?.filter ?? filter, ANSI_STYLE, 1, own?.column, undefined, undefined, undefined, false, undefined, false, inline, within);
505
507
  }
506
508
  async queryOn(request, db, read = false) {
507
509
  const table = read ? this.readTable(request.table) : this.assertTable(request.table, db);
@@ -512,7 +514,7 @@ export class SqliteAdapter {
512
514
  its operation input, and the schema wait below must not outlive it. */
513
515
  const limit = clampLimit(request.limit);
514
516
  const offset = clampOffset(request.offset);
515
- const where = asksAboutRows(request.filter)
517
+ const where = readsCatalog(request.filter)
516
518
  ? await this.whereOf(request.table, table, request.filter)
517
519
  : buildWhere(request.filter, ANSI_STYLE);
518
520
  /* A sort by declared vocabulary needs the catalog, but an ordinary read must
@@ -754,7 +756,7 @@ export class SqliteAdapter {
754
756
  }
755
757
  async countOn(table, filter, db, limit, read = false) {
756
758
  const name = read ? this.readTable(table) : this.assertTable(table, db);
757
- const where = asksAboutRows(filter) ? await this.whereOf(table, name, filter) : buildWhere(filter, ANSI_STYLE);
759
+ const where = readsCatalog(filter) ? await this.whereOf(table, name, filter) : buildWhere(filter, ANSI_STYLE);
758
760
  const text = countStatement(`${ANSI_STYLE.quote(name)}${where.text}`, limit);
759
761
  const [row] = await this.readRows(text, where.params, true, db);
760
762
  return Number(row?.n ?? 0);
@@ -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;
@@ -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
  }
@@ -36,6 +36,9 @@ export interface ColumnGrant {
36
36
  read: ReadonlySet<string>;
37
37
  write: ReadonlySet<string>;
38
38
  }>;
39
+ /** Of each table's rollups and computed columns, the ones a field grant names to be read, by table id: what the
40
+ App's catalog keeps of them (GRANTED_DERIVED). A table missing here keeps every one its reader can compute. */
41
+ derived?: ReadonlyMap<string, ReadonlySet<string>>;
39
42
  /** Columns read and written by the server for its own work (a file's object
40
43
  and hash): never listed in a served catalog, and refused to every request
41
44
  but the server's own (`serverRequest`). */
@@ -14,9 +14,10 @@ import { compileView, resolveAggregate, tryResolvePath } from '../shared/view.js
14
14
  import { rollupReads } from '../shared/rollups.js';
15
15
  import { compileBreakdown, measureConditions } from '../shared/breakdown.js';
16
16
  import { aggregateColumns } from '../shared/aggregate.js';
17
+ import { checkedComputed } from '../shared/computedWhere.js';
17
18
  import { textToView } from '../shared/viewtext.js';
18
19
  import { textToBreakdown } from '../shared/breakdowntext.js';
19
- import { isJsonType } from '../shared/schema.js';
20
+ import { GRANTED_DERIVED, isJsonType } from '../shared/schema.js';
20
21
  import { impliedEdges } from '../shared/declaredReferences.js';
21
22
  import { unformedColumns } from '../shared/form.js';
22
23
  import { isServerRequest } from './serverRequests.js';
@@ -45,6 +46,7 @@ export function captureGrant(grant) {
45
46
  fields: new Map([...grant.fields].map(([table, fields]) => [table, { read: new Set(fields.read), write: new Set(fields.write) }])),
46
47
  }
47
48
  : {}),
49
+ ...(grant.derived ? { derived: new Map([...grant.derived].map(([table, names]) => [table, new Set(names)])) } : {}),
48
50
  };
49
51
  }
50
52
  const withoutCarriedReferences = (def) => {
@@ -68,7 +70,7 @@ const prunedCatalogs = new WeakMap();
68
70
  /* A tenant request resolves its grant afresh each time, so its sets are never
69
71
  the same objects twice, and every read in it pruned the catalog again
70
72
  (G118). A captured catalog is frozen, and pruning reads nothing of the grant
71
- but the six things in this key, so the answer for a catalog and a key is
73
+ but what this key holds, so the answer for a catalog and a key is
72
74
  kept — bounded, oldest out first — and frozen, so no caller can change the
73
75
  copy another one is handed. */
74
76
  const prunedByContent = new WeakMap();
@@ -87,6 +89,7 @@ function grantKey(access) {
87
89
  access.internal
88
90
  ? [...access.internal].map(([table, columns]) => [table, sorted(columns)]).sort((a, b) => (a[0] < b[0] ? -1 : 1))
89
91
  : null,
92
+ access.derived ? [...access.derived].map(([table, names]) => [table, sorted(names)]).sort((a, b) => (a[0] < b[0] ? -1 : 1)) : null,
90
93
  ]);
91
94
  }
92
95
  /** Test-only: how many times a catalog was pruned rather than reused. */
@@ -120,13 +123,14 @@ export function accessibleSchema(schema, access) {
120
123
  kept.appendOnly === access.appendOnly &&
121
124
  kept.fields === access.fields &&
122
125
  kept.internal === access.internal &&
126
+ kept.derived === access.derived &&
123
127
  kept.scoped === scoped)
124
128
  return kept.pruned;
125
129
  // Frozen over a captured catalog, as the content path's is: what reads it later (resourceChecks) may then keep by its identity.
126
130
  const made = pruneCatalog(schema, access);
127
131
  const pruned = isCapturedScopeCatalog(schema) ? freezeDerivedCatalog(made) : made;
128
- const { writable, creatable, appendOnly, fields, internal } = access;
129
- byGrant.set(access.readable, { writable, creatable, appendOnly, fields, internal, scoped, pruned });
132
+ const { writable, creatable, appendOnly, fields, internal, derived } = access;
133
+ byGrant.set(access.readable, { writable, creatable, appendOnly, fields, internal, derived, scoped, pruned });
130
134
  return pruned;
131
135
  }
132
136
  function pruneCatalog(schema, access) {
@@ -217,6 +221,7 @@ function pruneCatalog(schema, access) {
217
221
  deletable above; the columns stay writable, for the New form. Capability only, never the authority
218
222
  (authorizeColumnWrites is). */
219
223
  ...(access.appendOnly?.has(table.id) ? { appendOnly: true, deletable: false } : {}),
224
+ ...(access.derived?.has(table.id) ? { [GRANTED_DERIVED]: Object.freeze([...access.derived.get(table.id)].sort()) } : {}),
220
225
  ...(table.indexed ? { indexed: table.indexed.filter((column) => listed(table.id, column)) } : {}),
221
226
  // Like `indexed`: a hidden column is not named, even as unique.
222
227
  ...(table.unique ? { unique: table.unique.filter((column) => listed(table.id, column)) } : {}),
@@ -407,11 +412,31 @@ export function resourceChecks(full, access) {
407
412
  const filter = requestData(input);
408
413
  /* An `any`/`no` condition names the rows that point here, not a column of this table: its child, reference and
409
414
  conditions are held to the reader as a view's are (assertAnyRows), and its own `column` is never read. */
415
+ /* A computed column a condition names is no column of the table: the condition is held to what its expression
416
+ reads (worked out from the expression, never from the request), each one a column this reader is served. */
417
+ let computed = new Map();
418
+ if (filter?.computed !== undefined) {
419
+ const declared = full.tables.find((item) => item.id === table);
420
+ if (!declared)
421
+ throw new AppAccessDenied();
422
+ try {
423
+ computed = checkedComputed(filter, declared);
424
+ }
425
+ catch {
426
+ throw new AppAccessDenied();
427
+ }
428
+ for (const def of computed.values())
429
+ assertFields(table, def.reads, 'read', server);
430
+ }
410
431
  if (filter)
411
432
  for (const group of filter.groups)
412
433
  for (const condition of group)
413
434
  if (condition.any)
414
435
  assertAnyRows({ groups: [[{ ...condition, path: condition.column }]] });
436
+ else if (computed.has(condition.column)) {
437
+ if (condition.within !== undefined || condition.other !== undefined)
438
+ throw new AppAccessDenied();
439
+ }
415
440
  else {
416
441
  assertFields(table, [condition.column], 'read', server);
417
442
  if (condition.within !== undefined)
@@ -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
  : {}),
@@ -13,10 +13,19 @@
13
13
  * in the container's environment on each deploy, and `build` is the id of the
14
14
  * build being served. Both are random or a hash, so safe to expose.
15
15
  *
16
+ * While a tenant server is still opening its tenants, `/readyz` also says how far
17
+ * it has got (`ready`, `opened`, `of`), and afterward which tenant keys failed to
18
+ * open: counts and keys only, never an error.
19
+ *
16
20
  * The operator reads with more in them (`/api/operations/readiness`) are
17
21
  * signed-in and granted; these are not, and so say nothing else.
18
22
  */
19
23
  import type { IncomingMessage, ServerResponse } from 'node:http';
20
24
  /** Where `/readyz` reads the served build's id from; the App framework registers it when it serves a build. */
21
25
  export declare function setBuildIdSource(source: () => string | null): void;
22
- export declare function probe(req: IncomingMessage, res: ServerResponse, path: string, ready?: () => boolean): boolean;
26
+ /** What a readiness check may say beside yes or no: words for the body (how far a start has got, what failed to open). */
27
+ export type ReadyAnswer = boolean | {
28
+ readonly ok: boolean;
29
+ readonly body?: Readonly<Record<string, unknown>>;
30
+ };
31
+ export declare function probe(req: IncomingMessage, res: ServerResponse, path: string, ready?: () => ReadyAnswer): boolean;
@@ -11,9 +11,13 @@ export function probe(req, res, path, ready) {
11
11
  return true;
12
12
  }
13
13
  let ok = true;
14
+ let extra = {};
14
15
  if (path === '/readyz') {
15
16
  try {
16
- ok = ready?.() ?? true;
17
+ const answer = ready?.() ?? true;
18
+ ok = typeof answer === 'boolean' ? answer : answer.ok;
19
+ if (typeof answer === 'object' && answer.body)
20
+ extra = answer.body;
17
21
  }
18
22
  catch {
19
23
  ok = false;
@@ -22,6 +26,6 @@ export function probe(req, res, path, ready) {
22
26
  res.writeHead(ok ? 200 : 503, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
23
27
  res.end(req.method === 'HEAD'
24
28
  ? undefined
25
- : JSON.stringify({ status: ok ? 'ok' : 'unavailable', deploy: process.env.MISTRI_DEPLOY_ID || null, build: buildSource() }));
29
+ : JSON.stringify({ status: ok ? 'ok' : 'unavailable', deploy: process.env.MISTRI_DEPLOY_ID || null, build: buildSource(), ...extra }));
26
30
  return true;
27
31
  }
@@ -7,6 +7,7 @@ import { AppAccessDenied } from '../columnGrants.js';
7
7
  import { deleteImpact } from '../impact.js';
8
8
  import { explainWriteFailure, writeFailureOutcome, writeRefusalStatus } from '../constraints.js';
9
9
  import { findTable } from '../../shared/schema.js';
10
+ import { isFrozenRefusal } from '../../shared/refusal.js';
10
11
  import { FILE_UPLOAD_PATH, bytesLabelled, send, sendBusy, sendResource, sendRowLocked } from './reply.js';
11
12
  /* A failed insert or update's status. The database refusing it for good — a key taken, a reference to nothing, a
12
13
  value its column cannot hold — is 409 or 422 (constraints.ts writeRefusalStatus); it was a 200 whose body alone
@@ -107,6 +108,11 @@ export async function recordWriteRoutes(post, hooks) {
107
108
  }
108
109
  if (!completed && rules?.refused(res, path, err))
109
110
  return true;
111
+ /* A frozen record (`frozen`, appModel.ts) is the record's state, said as a conflict is: 409, by its own code. */
112
+ if (!completed && isFrozenRefusal(err)) {
113
+ sendResource(res, path, 409, { errors: [await failureOf(err, false, values)], outcome: 'rejected' });
114
+ return true;
115
+ }
110
116
  if (!completed && (err instanceof Refusal || err instanceof WriteConflict))
111
117
  throw err;
112
118
  /* Pointing an existing row at a row that is not there is the same
@@ -290,7 +296,7 @@ export async function recordWriteRoutes(post, hooks) {
290
296
  }
291
297
  const outcome = completed ? 'unknown' : err instanceof Refusal ? 'rejected' : writeFailureOutcome(err);
292
298
  const errors = [rules ? rules.failure(post, err, completed) : { message: err.message }];
293
- sendResource(res, path, outcome === 'unknown' ? 200 : (writeRefusalStatus(err) ?? 400), outcome === 'unknown' ? { impact, deleted: null, outcome, errors } : { impact, deleted: false, outcome, errors });
299
+ sendResource(res, path, outcome === 'unknown' ? 200 : isFrozenRefusal(err) ? 409 : (writeRefusalStatus(err) ?? 400), outcome === 'unknown' ? { impact, deleted: null, outcome, errors } : { impact, deleted: false, outcome, errors });
294
300
  return true;
295
301
  }
296
302
  }
@@ -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
  }
@@ -15,6 +15,7 @@
15
15
  import type { IncomingMessage, Server, ServerResponse } from 'node:http';
16
16
  import type { RequestDiagnostics } from '../operations/diagnostics.js';
17
17
  import { type AddressMount } from '../../shared/mount.js';
18
+ import { type ReadyAnswer } from './probes.js';
18
19
  import type { Bound } from './trust.js';
19
20
  /**
20
21
  * The request read through the server's mounts (shared/mount.ts): the base
@@ -37,7 +38,7 @@ export interface Listening {
37
38
  readonly bound: Bound;
38
39
  readonly diagnostics?: RequestDiagnostics;
39
40
  /** Whether the server should take traffic now: false while it starts, reloads its policy or shuts down (`/readyz`). */
40
- readonly ready?: () => boolean;
41
+ readonly ready?: () => ReadyAnswer;
41
42
  /** A suite owns the source client and HMR at its shared listener. */
42
43
  readonly sourceClient?: false;
43
44
  /** A suite must drain even disconnected form submissions before closing its App registry. */
@@ -570,6 +570,13 @@ async function runDesired(command, target, options, name, write) {
570
570
  const path = newMigration(target.dir, name, false, new Date(), `${diffHeader()}${sql}\n`);
571
571
  write(`wrote ${shown(path)}:`);
572
572
  write(sql);
573
+ // A trigger's body is the database's to run: `check` names the ones that read other tables once they are migrated in.
574
+ const triggers = [
575
+ ...sql.matchAll(/\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:CONSTRAINT\s+)?TRIGGER\s+(?:IF\s+NOT\s+EXISTS\s+)?("[^"]+"|[\w$.]+)/gi),
576
+ ].map((found) => found[1]);
577
+ if (triggers.length)
578
+ write(`note: it creates ${plural(triggers.length, 'trigger')} (${triggers.join(', ')}). A trigger that reads another table can refuse a write ` +
579
+ 'in ways an App cannot see; `mistri check --app` names those [trigger-cross-table].');
573
580
  if (/\bDROP\b/i.test(sql))
574
581
  write('note: it drops something. If that is a rename, rewrite it as RENAME: a diff cannot tell a rename from a drop and an add.');
575
582
  return EXIT.ok;
@@ -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