@mistriwork/engine 1.0.0-rc.15 → 1.0.0-rc.17

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 (58) hide show
  1. package/README.md +5 -0
  2. package/dist/host.d.ts +46 -0
  3. package/dist/host.js +51 -0
  4. package/dist/server/cli/startup.js +7 -2
  5. package/dist/server/cli/usage.d.ts +2 -0
  6. package/dist/server/cli/usage.js +12 -1
  7. package/dist/server/clientHttp.js +20 -3
  8. package/dist/server/config/profile.d.ts +10 -3
  9. package/dist/server/config/profile.js +28 -4
  10. package/dist/server/connections.js +9 -0
  11. package/dist/server/http/baselineHeaders.d.ts +13 -3
  12. package/dist/server/http/baselineHeaders.js +6 -0
  13. package/dist/server/http/exportRoute.d.ts +74 -0
  14. package/dist/server/http/exportRoute.js +206 -169
  15. package/dist/server/http/frontDoor.d.ts +41 -0
  16. package/dist/server/http/frontDoor.js +36 -0
  17. package/dist/server/http/recordCompose.d.ts +3 -0
  18. package/dist/server/http/recordCompose.js +1 -0
  19. package/dist/server/http/reply.js +6 -0
  20. package/dist/server/http/serverCore.d.ts +2 -2
  21. package/dist/server/http/serverCore.js +16 -32
  22. package/dist/server/journal.d.ts +35 -6
  23. package/dist/server/journal.js +79 -8
  24. package/dist/server/journalStore.d.ts +37 -0
  25. package/dist/server/journalStore.js +352 -0
  26. package/dist/server/migrate/cli.js +8 -1
  27. package/dist/server/migrate/target.d.ts +8 -0
  28. package/dist/server/migrate/target.js +15 -0
  29. package/dist/server/seed/seed.js +46 -11
  30. package/dist/shared/appCards.d.ts +4 -0
  31. package/dist/shared/appCards.js +5 -0
  32. package/dist/shared/appListColumns.d.ts +7 -0
  33. package/dist/shared/appListColumns.js +13 -0
  34. package/dist/shared/breakdown.js +8 -2
  35. package/dist/shared/computed.d.ts +16 -2
  36. package/dist/shared/computed.js +23 -4
  37. package/dist/shared/computedValue.js +23 -0
  38. package/dist/shared/listQuestion.js +2 -2
  39. package/dist/shared/mentionLookup.js +3 -1
  40. package/dist/shared/page.js +23 -5
  41. package/dist/shared/pageAnatomy.js +2 -0
  42. package/dist/shared/pageConfig.d.ts +1 -1
  43. package/dist/shared/pageConfig.js +68 -18
  44. package/dist/shared/pageModel.d.ts +42 -5
  45. package/dist/shared/pagePaths.js +4 -1
  46. package/dist/shared/pagePlans.d.ts +2 -2
  47. package/dist/shared/pagePlans.js +3 -3
  48. package/dist/shared/recordLabel.d.ts +12 -3
  49. package/dist/shared/recordLabel.js +39 -18
  50. package/dist/shared/recordReads.d.ts +6 -30
  51. package/dist/shared/recordReads.js +32 -2
  52. package/dist/shared/rollups.d.ts +4 -4
  53. package/dist/shared/rollups.js +1 -1
  54. package/dist/shared/schema.d.ts +7 -0
  55. package/dist/shared/schema.js +17 -0
  56. package/dist/shared/servedApp.d.ts +1 -1
  57. package/dist/shared/viewLabels.js +22 -17
  58. package/package.json +5 -2
@@ -1,59 +1,82 @@
1
1
  import { createBrotliCompress, createGzip, constants as zlib } from 'node:zlib';
2
- import { MAX_LIMIT, clampLimit } from '../../shared/reads.js';
2
+ import { withCancellation } from '../../adapters/statementControl.js';
3
3
  import { parseQuery } from '../../shared/query.js';
4
4
  import { textToView } from '../../shared/viewtext.js';
5
- import { findTable, primaryKey, resolveOrder } from '../../shared/schema.js';
5
+ import { findTable, resolveOrder } from '../../shared/schema.js';
6
6
  import { backrefsTo, resolveAggregate, tryResolvePath } from '../../shared/viewPaths.js';
7
7
  import { CRLF, csvField, csvRecord, jsonRecord } from '../../shared/csv.js';
8
8
  import { readRecords, readView } from '../resourceReadOperations.js';
9
- import { acceptedEncoding, httpRead, send } from './reply.js';
9
+ import { recordsPaging, settlePage, viewPaging } from '../keysetReadHttp.js';
10
+ import { acceptedEncoding, httpRead, policyResponses, send } from './reply.js';
10
11
  import { rollupReads } from '../../shared/rollups.js';
11
12
  const EXPORT_PATH = '/api/export';
12
- /** Rows read per statement: large enough that a 100,000-row file is a hundred
13
- * reads, small enough that one batch is never a memory event. */
14
- const BATCH = 1000;
13
+ /** Rows read per statement, and so the most the server holds of a file at once:
14
+ * large enough that a million-row file is a thousand reads, small enough that
15
+ * one batch is never a memory event. */
16
+ export const EXPORT_BATCH = 1000;
15
17
  const FORMATS = {
16
18
  csv: { type: 'text/csv', extension: 'csv' },
17
19
  json: { type: 'application/json', extension: 'json' },
18
20
  ndjson: { type: 'application/x-ndjson', extension: 'ndjson' },
19
21
  };
20
22
  export async function exportRoute(post, hooks) {
21
- const { res, path, body, adapter, schema, appNow } = post;
22
- if (path !== EXPORT_PATH)
23
+ if (post.path !== EXPORT_PATH)
23
24
  return false;
25
+ const { person, amounts } = hooks;
26
+ const end = await exportFile({
27
+ res: post.res,
28
+ body: post.body,
29
+ adapter: post.adapter,
30
+ schema: post.schema,
31
+ now: post.appNow,
32
+ may: hooks.may(post),
33
+ ...(person ? { person: (text) => person(post, text) } : {}),
34
+ ...(amounts ? { amounts: (tableId) => amounts(post, tableId) } : {}),
35
+ });
36
+ if (!end)
37
+ return true;
38
+ /* A row policy's reply waits for its context (handler.ts underPolicy): so does the file's last write. */
39
+ const held = policyResponses.get(post.res);
40
+ if (held)
41
+ held.reply = end;
42
+ else
43
+ end();
44
+ return true;
45
+ }
46
+ /**
47
+ * The export, streamed. Resolves with the file's last write, for the caller
48
+ * to make once whatever the reads ran in has settled; undefined when the
49
+ * answer was not a file (it was sent already) or the file was cut.
50
+ */
51
+ export async function exportFile(asked) {
52
+ const { res, body, adapter, schema, may } = asked;
53
+ const answer = asked.answer ?? ((status, value) => send(res, status, value));
54
+ const amountsOf = (tableId) => asked.amounts?.(tableId);
24
55
  /* An App that grants by role says who exports which table (appExportable); the file is refused where the Export menu is not offered. */
25
- const may = hooks.may(post);
26
56
  if (!may('')) {
27
- send(res, 403, { error: 'Export is not available to this person.' });
28
- return true;
29
- }
30
- // Never reached in one (httpRowPolicyAllows), and refused here as well: a policy reply cannot stream.
31
- if (post.rowPolicy) {
32
- send(res, 403, {
33
- error: 'This operation is unavailable in a row-policy application.',
34
- });
35
- return true;
57
+ answer(403, { error: 'Export is not available to this person.' });
58
+ return undefined;
36
59
  }
37
60
  const format = body.format ?? 'csv';
38
61
  if (typeof format !== 'string' || !Object.hasOwn(FORMATS, format)) {
39
- send(res, 400, { error: 'format must be "csv", "json" or "ndjson".' });
40
- return true;
62
+ answer(400, { error: 'format must be "csv", "json" or "ndjson".' });
63
+ return undefined;
41
64
  }
42
65
  if (body.columns !== undefined && (!Array.isArray(body.columns) || body.columns.some((column) => typeof column !== 'string'))) {
43
- send(res, 400, { error: 'columns must be a list of column names.' });
44
- return true;
66
+ answer(400, { error: 'columns must be a list of column names.' });
67
+ return undefined;
45
68
  }
46
69
  const text = String(body.q ?? '');
47
- const me = await hooks.person?.(post, text);
70
+ const me = await asked.person?.(text);
48
71
  const person = me === undefined ? {} : { me };
49
- const parsed = parseQuery(text, { schema, now: appNow(), ...person });
72
+ const parsed = parseQuery(text, { schema, now: asked.now(), ...person });
50
73
  /* A question only a view can answer (a path through a reference) exports
51
74
  as a view, paged by offset: its rows have no single key to resume from. */
52
75
  if ((!parsed.query || parsed.errors.length) && adapter.runView) {
53
76
  const asView = textToView(schema, text, {
54
77
  id: 'export',
55
78
  name: '',
56
- now: appNow(),
79
+ now: asked.now(),
57
80
  ...person,
58
81
  });
59
82
  if (asView.view && !asView.errors.length) {
@@ -61,60 +84,72 @@ export async function exportRoute(post, hooks) {
61
84
  /* Every table the view reaches, not only its base: a column through a reference, an aggregate or a filter on one reads another table's rows into the file. */
62
85
  for (const reached of viewTables(schema, view))
63
86
  if (!may(reached))
64
- return refuseTable(res, reached === UNKNOWN_TABLE ? view.base : reached);
65
- const total = clampLimit(view.limit ?? MAX_LIMIT);
66
- const read = (offset) => httpRead(() => readView(adapter, schema, view, { limit: Math.min(BATCH, total - offset), offset }, 'none')).then(({ result }) => result);
67
- await stream(res, format, view.base, total, read, requested(body) ?? undefined, hooks.amounts?.(post, view.base));
68
- return true;
87
+ return refuseTable(answer, reached === UNKNOWN_TABLE ? view.base : reached);
88
+ const base = findTable(schema, view.base);
89
+ /* A union pages by offset: its rows have no one key order across branches (unionReads.ts), as the list's. */
90
+ const keyed = base && !base.union ? base : undefined;
91
+ let step;
92
+ const read = async (offset, size) => {
93
+ const paging = keyed && viewPaging(schema, keyed, view, step);
94
+ /* Past the first batch with no boundary to resume from, the file goes on by offset in the same total order. */
95
+ const continued = paging && (!step || paging.continuation) ? paging : undefined;
96
+ const { result } = await httpRead(() => readView(adapter, schema, continued?.view ?? view, { limit: size, offset: continued?.continuation ? 0 : offset }, 'none', undefined, continued?.continuation));
97
+ if (!continued)
98
+ return result;
99
+ const settled = settlePage(continued.order, continued.extra, result);
100
+ step = settled.bounds ? { after: settled.bounds.last } : undefined;
101
+ return { columns: settled.columns, rows: settled.rows };
102
+ };
103
+ return stream(res, format, view.base, rowsWanted(view.limit), read, requested(body) ?? undefined, amountsOf(view.base), asked.headers);
69
104
  }
70
105
  }
71
- if (!parsed.query) {
72
- send(res, 200, { errors: parsed.errors });
73
- return true;
74
- }
75
- if (parsed.errors.length) {
76
- send(res, 200, { errors: parsed.errors });
77
- return true;
106
+ if (!parsed.query || parsed.errors.length) {
107
+ answer(200, { errors: parsed.errors });
108
+ return undefined;
78
109
  }
79
110
  const query = parsed.query;
80
111
  const table = findTable(schema, query.table);
81
112
  if (!table) {
82
- send(res, 404, { error: `Unknown table "${query.table}"` });
83
- return true;
113
+ answer(404, { error: `Unknown table "${query.table}"` });
114
+ return undefined;
84
115
  }
85
116
  if (!may(table.id))
86
- return refuseTable(res, table.id);
117
+ return refuseTable(answer, table.id);
87
118
  const wanted = requested(body) ?? (query.columns?.length ? query.columns : undefined);
88
119
  for (const reached of queryTables(schema, table, query, wanted))
89
120
  if (!may(reached))
90
- return refuseTable(res, reached === UNKNOWN_TABLE ? table.id : reached);
91
- const total = clampLimit(query.limit ?? MAX_LIMIT);
92
- const order = resolveOrder(table, query.orderBy).order;
93
- const keyset = keysetOrder(table, order, schema.dialect);
94
- /* The key is read even when the file does not show it: it is where the
95
- next batch starts. It never reaches the file (`wanted` is the file's). */
96
- const reading = wanted && keyset ? [...new Set([...wanted, ...keyset.map((o) => o.column)])] : wanted;
97
- let after;
98
- const read = async (offset) => {
121
+ return refuseTable(answer, reached === UNKNOWN_TABLE ? table.id : reached);
122
+ /* The order the list reads in, made total with the key; an offset batch reads in it too. */
123
+ const order = schema.dialect === 'http' && !query.orderBy?.length ? undefined : resolveOrder(table, query.orderBy).order;
124
+ let step;
125
+ const read = async (offset, size) => {
126
+ /* A union pages by offset: its rows have no one key order across branches (unionReads.ts), as the list's. */
127
+ const paging = table.union ? undefined : recordsPaging(table, schema.dialect, query.orderBy, wanted, query.filter, step);
128
+ /* Past the first batch with no boundary to resume from, the file goes on by offset in the same total order. */
129
+ const continued = paging && (!step || paging.continuation) ? paging : undefined;
130
+ /* An order column the file does not show is read for the boundary and taken out again (settlePage): it never
131
+ reaches the file, whose columns are `wanted`. */
132
+ const columns = continued?.columns ?? wanted;
99
133
  const { result } = await httpRead(() => readRecords(adapter, schema, {
100
134
  ...query,
101
- ...(reading ? { columns: reading } : {}),
102
- orderBy: order,
103
- filter: keyset && after ? beyond(query.filter, keyset, after) : query.filter,
104
- limit: Math.min(BATCH, total - offset),
105
- offset: keyset ? 0 : offset,
106
- }, 'none'));
107
- after = result.rows.at(-1);
108
- return result;
135
+ ...(columns ? { columns } : {}),
136
+ ...(order ? { orderBy: order } : {}),
137
+ limit: size,
138
+ offset: continued?.continuation ? 0 : offset,
139
+ }, 'none', undefined, continued?.continuation));
140
+ if (!continued)
141
+ return result;
142
+ const settled = settlePage(continued.order, continued.extra, result);
143
+ step = settled.bounds ? { after: settled.bounds.last } : undefined;
144
+ return { columns: settled.columns, rows: settled.rows };
109
145
  };
110
- await stream(res, format, table.id, total, read, wanted, hooks.amounts?.(post, table.id));
111
- return true;
146
+ return stream(res, format, table.id, rowsWanted(query.limit), read, wanted, amountsOf(table.id), asked.headers);
112
147
  }
113
- function refuseTable(res, tableId) {
114
- send(res, 403, {
148
+ function refuseTable(answer, tableId) {
149
+ answer(403, {
115
150
  error: `Export of "${tableId}" is not available to this person.`,
116
151
  });
117
- return true;
152
+ return undefined;
118
153
  }
119
154
  /** Stands for a table a view reaches that cannot be named (a many-valued condition it cannot resolve): never exportable. */
120
155
  const UNKNOWN_TABLE = '\u0000unknown';
@@ -204,117 +239,119 @@ function pathReach(schema, base, tables) {
204
239
  function requested(body) {
205
240
  return Array.isArray(body.columns) && body.columns.length ? body.columns : undefined;
206
241
  }
207
- /* Types whose values come back exactly as stored on Postgres. */
208
- const EXACT_TYPE = /^(tiny|small|medium|big)?int(eger)?\d*\b|^(big|small)?serial|char|text|uuid/i;
209
- /**
210
- * The order a keyset can resume, or undefined. Only the key, and only
211
- * columns whose value comes back exactly as it is stored: an integer or text
212
- * on Postgres — a timestamp comes back to the millisecond and a
213
- * float rounded, and resuming "after" a rounded value repeats or skips rows —
214
- * and anything on SQLite, which hands back what it holds.
215
- */
216
- function keysetOrder(table, order, dialect) {
217
- const key = primaryKey(table);
218
- if (!key.length || order.length !== key.length || order.some((o, i) => o.column !== key[i]))
219
- return undefined;
220
- if (dialect === 'http')
221
- return undefined;
222
- const exact = order.every((o) => {
223
- const column = table.columns.find((c) => c.name === o.column);
224
- if (!column || column.nullable)
225
- return false;
226
- return dialect === 'sqlite' || EXACT_TYPE.test(column.type);
227
- });
228
- return exact ? order : undefined;
242
+ /** How many rows the file holds: the question's own `limit` where it says one, with no ceiling; every row otherwise. */
243
+ function rowsWanted(limit) {
244
+ const n = typeof limit === 'number' ? limit : typeof limit === 'string' && limit.trim() !== '' ? Number(limit) : NaN;
245
+ return Number.isFinite(n) && n >= 1 ? Math.floor(n) : Infinity;
229
246
  }
230
- /**
231
- * The rows after `last` in `order`, within the question's own filter: for a
232
- * key (a, b) ascending, `a > x OR (a = x AND b > y)`, crossed with each of the
233
- * filter's OR-groups so every group keeps all of its own conditions. Values
234
- * are bound like any other condition's.
235
- */
236
- function beyond(filter, order, last) {
237
- const steps = order.map((o, i) => [
238
- ...order.slice(0, i).map((earlier) => ({
239
- column: earlier.column,
240
- op: '=',
241
- value: last[earlier.column],
242
- })),
243
- {
244
- column: o.column,
245
- op: o.direction === 'desc' ? '<' : '>',
246
- value: last[o.column],
247
- },
248
- ]);
249
- const groups = filter?.groups?.length ? filter.groups : [[]];
250
- return {
251
- groups: groups.flatMap((group) => steps.map((step) => [...group, ...step])),
252
- };
247
+ /** Said when the client went away mid-file: nothing reads it, it only stops the loop. */
248
+ class Abandoned extends Error {
249
+ constructor() {
250
+ super('The export was abandoned.');
251
+ this.name = 'Abandoned';
252
+ }
253
253
  }
254
- async function stream(res, format, table, total, read, wanted, amounts) {
255
- /* The first batch is read before a byte is written: a refusal, a column
256
- that does not exist, a database that is down all still answer as the
257
- ordinary error they are, through the handler's own mapping. */
258
- let batch = await read(0);
259
- const columns = wanted ?? batch.columns;
260
- const spec = FORMATS[format];
261
- const encoding = acceptedEncoding(res);
262
- res.writeHead(200, {
263
- 'content-type': `${spec.type}; charset=utf-8`,
264
- 'content-disposition': `attachment; filename="${table.replace(/[^\w.-]+/g, '_')}.${spec.extension}"`,
265
- 'cache-control': 'private, no-store',
266
- 'x-content-type-options': 'nosniff',
267
- vary: 'Accept-Encoding',
268
- ...(encoding ? { 'content-encoding': encoding } : {}),
269
- });
270
- const out = encoding === 'br'
271
- ? createBrotliCompress({
272
- params: {
273
- [zlib.BROTLI_PARAM_QUALITY]: 4,
274
- [zlib.BROTLI_PARAM_MODE]: zlib.BROTLI_MODE_TEXT,
275
- },
276
- })
277
- : encoding === 'gzip'
278
- ? createGzip({ level: 6 })
279
- : res;
280
- if (out !== res)
281
- out.pipe(res);
282
- const write = (chunk) => new Promise((resolve, reject) => {
283
- if (res.destroyed)
284
- return reject(new Error('The export was abandoned.'));
285
- if (out.write(chunk))
286
- resolve();
287
- else
288
- out.once('drain', resolve);
289
- });
254
+ async function stream(res, format, table, total, read, wanted, amounts, headers = {}) {
255
+ /* A client that leaves stops the read in flight (the adapters watch this signal) and every one after it. */
256
+ const stop = new AbortController();
257
+ const left = () => {
258
+ if (!res.writableFinished)
259
+ stop.abort();
260
+ };
261
+ res.once('close', left);
262
+ const reading = (offset) => withCancellation(stop.signal, () => read(offset, Math.min(EXPORT_BATCH, total - offset)));
290
263
  try {
291
- /* A spreadsheet opens a UTF-8 CSV without a byte-order mark in the local
292
- codepage; the browser's own export writes one too (export.js). */
293
- if (format === 'csv')
294
- await write(`${columns.map(csvField).join(',')}${CRLF}`);
295
- let written = 0;
296
- for (;;) {
297
- const lines = batch.rows.map((row, i) => format === 'csv'
298
- ? `${csvRecord(columns, amounts ? amounts(row) : row)}${CRLF}`
299
- : format === 'ndjson'
300
- ? `${JSON.stringify(jsonRecord(columns, row))}\n`
301
- : // A JSON array as export.js's toJson writes one: two-space indent, one record per element.
302
- `${written + i === 0 ? '[\n' : ',\n'}${JSON.stringify(jsonRecord(columns, row), null, 2).replace(/^/gm, ' ')}`);
303
- if (lines.length)
304
- await write(lines.join(''));
305
- written += batch.rows.length;
306
- if (batch.rows.length < BATCH || written >= total)
307
- break;
308
- batch = await read(written);
264
+ /* The first batch is read before a byte is written: a refusal, a column
265
+ that does not exist, a database that is down all still answer as the
266
+ ordinary error they are, through the handler's own mapping. */
267
+ let batch = await reading(0);
268
+ if (stop.signal.aborted)
269
+ return undefined;
270
+ const columns = wanted ?? batch.columns;
271
+ const spec = FORMATS[format];
272
+ const encoding = acceptedEncoding(res);
273
+ res.writeHead(200, {
274
+ 'content-type': `${spec.type}; charset=utf-8`,
275
+ 'content-disposition': `attachment; filename="${table.replace(/[^\w.-]+/g, '_')}.${spec.extension}"`,
276
+ 'cache-control': 'private, no-store',
277
+ 'x-content-type-options': 'nosniff',
278
+ vary: 'Accept-Encoding',
279
+ ...(encoding ? { 'content-encoding': encoding } : {}),
280
+ ...headers,
281
+ });
282
+ const out = encoding === 'br'
283
+ ? createBrotliCompress({
284
+ params: {
285
+ [zlib.BROTLI_PARAM_QUALITY]: 4,
286
+ [zlib.BROTLI_PARAM_MODE]: zlib.BROTLI_MODE_TEXT,
287
+ },
288
+ })
289
+ : encoding === 'gzip'
290
+ ? createGzip({ level: 6 })
291
+ : res;
292
+ if (out !== res) {
293
+ out.pipe(res);
294
+ stop.signal.addEventListener('abort', () => out.destroy(), { once: true });
295
+ }
296
+ /* Backpressure: a chunk the connection cannot take yet holds the loop until it drains, so the next batch is
297
+ read only once this one is on its way. A client that leaves meanwhile ends the wait (a drain that never comes
298
+ would hold the loop and its batch for good). */
299
+ const write = (chunk) => new Promise((resolve, reject) => {
300
+ if (stop.signal.aborted || res.destroyed)
301
+ return reject(new Abandoned());
302
+ if (out.write(chunk))
303
+ return resolve();
304
+ const settle = (fn) => () => {
305
+ out.off('drain', drained);
306
+ stop.signal.removeEventListener('abort', gone);
307
+ fn();
308
+ };
309
+ const drained = settle(resolve);
310
+ const gone = settle(() => reject(new Abandoned()));
311
+ out.once('drain', drained);
312
+ stop.signal.addEventListener('abort', gone, { once: true });
313
+ });
314
+ try {
315
+ /* A spreadsheet opens a UTF-8 CSV without a byte-order mark in the local
316
+ codepage; the browser's own export writes one too (export.js). */
317
+ if (format === 'csv')
318
+ await write(`\ufeff${columns.map(csvField).join(',')}${CRLF}`);
319
+ let written = 0;
320
+ for (;;) {
321
+ const lines = batch.rows.map((row, i) => format === 'csv'
322
+ ? `${csvRecord(columns, amounts ? amounts(row) : row)}${CRLF}`
323
+ : format === 'ndjson'
324
+ ? `${JSON.stringify(jsonRecord(columns, row))}\n`
325
+ : // A JSON array as export.js's toJson writes one: two-space indent, one record per element.
326
+ `${written + i === 0 ? '[\n' : ',\n'}${JSON.stringify(jsonRecord(columns, row), null, 2).replace(/^/gm, ' ')}`);
327
+ if (lines.length)
328
+ await write(lines.join(''));
329
+ const size = Math.min(EXPORT_BATCH, total - written);
330
+ written += batch.rows.length;
331
+ if (batch.rows.length < size || written >= total)
332
+ break;
333
+ batch = await reading(written);
334
+ if (stop.signal.aborted)
335
+ throw new Abandoned();
336
+ }
337
+ if (format === 'json')
338
+ await write(written ? '\n]\n' : '[]\n');
339
+ /* The last write is the caller's to make: a reply held for a context that has not settled yet waits for it. */
340
+ return () => {
341
+ if (!res.destroyed)
342
+ out.end();
343
+ };
344
+ }
345
+ catch {
346
+ /* Past the first byte a status cannot change: the connection is cut, so
347
+ the browser reports a failed download rather than saving half a file
348
+ that looks whole. */
349
+ stop.abort();
350
+ res.destroy();
351
+ return undefined;
309
352
  }
310
- if (format === 'json')
311
- await write(written ? '\n]\n' : '[]\n');
312
- out.end();
313
353
  }
314
- catch {
315
- /* Past the first byte a status cannot change: the connection is cut, so
316
- the browser reports a failed download rather than saving half a file
317
- that looks whole. */
318
- res.destroy();
354
+ finally {
355
+ res.off('close', left);
319
356
  }
320
357
  }
@@ -0,0 +1,41 @@
1
+ /**
2
+ * The one place an HTTP server is made. Every listener that takes a person's
3
+ * request (the single-App server, the tenant servers and the suite) is
4
+ * `frontDoor(options, handle)`, so what no surface may forget is done here
5
+ * once, before its handler reads anything:
6
+ *
7
+ * - the request waits in a pool's line as its client's, read through the
8
+ * proxies this server trusts (poolAdmission.ts, trust.ts `forwardedClient`);
9
+ * - the baseline headers (baselineHeaders.ts), set before anything is routed
10
+ * so a reply that names its own still wins;
11
+ * - the guard (`guard`), the surface's first refusal: a Host it does not
12
+ * serve (trust.ts `hostRefusal`, `doorRefusal`), or a stop in progress.
13
+ * It runs after the headers, so a refusal carries them as an answer does.
14
+ *
15
+ * A surface's own refusals, in the shapes its callers read, stay in the
16
+ * surface; what they have in common is the part here. A `createServer` call
17
+ * anywhere else in a package's source is refused by
18
+ * `test/front-door-structure.test.ts`, which names the few that are not a door.
19
+ */
20
+ import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
21
+ import { type ProxyRange } from './trust.js';
22
+ interface FrontDoorOptions {
23
+ /** The proxies whose forwarded address and protocol are read; read per request, so a late binding is seen. */
24
+ readonly trustedProxies?: readonly ProxyRange[] | (() => readonly ProxyRange[] | undefined);
25
+ /** False for a server nobody queues at, whose callers a front has already admitted; default true. */
26
+ readonly admit?: boolean;
27
+ /** Seen first, after admission: the operator's meters (operations/diagnostics.ts). */
28
+ readonly diagnostics?: {
29
+ observe(req: IncomingMessage, res: ServerResponse): void;
30
+ };
31
+ /**
32
+ * Outermost, around admission: the request's span (traceRequest.ts) covers
33
+ * the line it waits in. Call `run` once.
34
+ */
35
+ readonly around?: (req: IncomingMessage, res: ServerResponse, run: () => void) => void;
36
+ /** The first refusal: true when it answered, and nothing further is read. */
37
+ readonly guard?: (req: IncomingMessage, res: ServerResponse) => boolean;
38
+ }
39
+ /** The server, made but not listening. */
40
+ export declare function frontDoor(options: FrontDoorOptions, handle: (req: IncomingMessage, res: ServerResponse) => void): Server;
41
+ export {};
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The one place an HTTP server is made. Every listener that takes a person's
3
+ * request (the single-App server, the tenant servers and the suite) is
4
+ * `frontDoor(options, handle)`, so what no surface may forget is done here
5
+ * once, before its handler reads anything:
6
+ *
7
+ * - the request waits in a pool's line as its client's, read through the
8
+ * proxies this server trusts (poolAdmission.ts, trust.ts `forwardedClient`);
9
+ * - the baseline headers (baselineHeaders.ts), set before anything is routed
10
+ * so a reply that names its own still wins;
11
+ * - the guard (`guard`), the surface's first refusal: a Host it does not
12
+ * serve (trust.ts `hostRefusal`, `doorRefusal`), or a stop in progress.
13
+ * It runs after the headers, so a refusal carries them as an answer does.
14
+ *
15
+ * A surface's own refusals, in the shapes its callers read, stay in the
16
+ * surface; what they have in common is the part here. A `createServer` call
17
+ * anywhere else in a package's source is refused by
18
+ * `test/front-door-structure.test.ts`, which names the few that are not a door.
19
+ */
20
+ import { createServer } from 'node:http';
21
+ import { withAdmission } from '../../adapters/poolAdmission.js';
22
+ import { setBaselineHeaders } from './baselineHeaders.js';
23
+ import { forwardedClient } from './trust.js';
24
+ /** The server, made but not listening. */
25
+ export function frontDoor(options, handle) {
26
+ const proxies = () => (typeof options.trustedProxies === 'function' ? options.trustedProxies() : options.trustedProxies) ?? [];
27
+ const through = (req, res) => {
28
+ options.diagnostics?.observe(req, res);
29
+ setBaselineHeaders(req, res, proxies());
30
+ if (options.guard?.(req, res))
31
+ return;
32
+ handle(req, res);
33
+ };
34
+ const admitted = (req, res) => options.admit === false ? through(req, res) : withAdmission(forwardedClient(req, proxies()), () => through(req, res));
35
+ return createServer((req, res) => (options.around ? options.around(req, res, () => admitted(req, res)) : admitted(req, res)));
36
+ }
@@ -28,6 +28,9 @@ export type ComposeResources = Record<string, {
28
28
  defined?: Record<string, {
29
29
  per?: string;
30
30
  }>;
31
+ display?: Record<string, {
32
+ subtitle?: string;
33
+ }>;
31
34
  actions?: Array<{
32
35
  when?: string;
33
36
  command?: {
@@ -55,6 +55,7 @@ export async function composeRecordPage({ ctx, source, body, post, hooks, }) {
55
55
  app: ctx.appConfigured,
56
56
  recordLabel: (table) => resources[table]?.recordLabel,
57
57
  defined: (table) => resources[table]?.defined,
58
+ display: (table, column) => resources[table]?.display?.[column],
58
59
  };
59
60
  const options = { rows, history: true, ...(tab === undefined ? {} : { tab: tab }) };
60
61
  /* What the page reads that its plan does not decide — the record's row,
@@ -75,6 +75,12 @@ export function send(res, status, body) {
75
75
  }
76
76
  if (res.destroyed || res.writableEnded)
77
77
  return;
78
+ /* A reply already under way — a streamed export whose policy context failed after its rows went
79
+ (exportRoute.ts) — cannot become an error: it is cut, and the client sees a failed download. */
80
+ if (res.headersSent) {
81
+ res.destroy();
82
+ return;
83
+ }
78
84
  /* While the dev observer runs, a failure says where its trace is: the
79
85
  "Open in observer" link beside the refusal (observe/mount.ts). */
80
86
  const observe = traceLink && status >= 400 && body && typeof body === 'object' && !Array.isArray(body)
@@ -12,10 +12,10 @@
12
12
  * malformed target is answered with, what an error's status is, which
13
13
  * requests a close waits for — would agree only by convention.
14
14
  */
15
- import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
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 Bound } from './trust.js';
18
+ import type { Bound } from './trust.js';
19
19
  /**
20
20
  * The request read through the server's mounts (shared/mount.ts): the base
21
21
  * path taken off `req.url`, which the static files, the App API and Better