@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,24 +1,8 @@
1
- /**
2
- * The HTTP server every product's dispatcher listens on: a `node:http`
3
- * server with the request's span, the baseline headers, the address read
4
- * through the mounts, the orchestrator's probes, and the error-to-status
5
- * mapping the tests pin — and, in the middle, the product's own answer
6
- * (`Answering`). The database browser's server (browserServer.ts) and the
7
- * App framework's (server.ts) are each this, with what their product adds.
8
- *
9
- * Kept whole rather than rebuilt per product, for the reason `createApp`
10
- * was pulled out of `main` in the first place: a wiring a product wrote for
11
- * itself would be the one its tests prove, and the shared parts — what a
12
- * malformed target is answered with, what an error's status is, which
13
- * requests a close waits for — would agree only by convention.
14
- */
15
- import { createServer } from 'node:http';
16
1
  import { SOURCE_CLIENT, attachDevClient } from '../devclient.js';
17
2
  import { applyServerTimeouts } from '../serverTimeouts.js';
18
3
  import { Refusal, WriteConflict } from '../../adapters/adapter.js';
19
4
  import { HttpSourceError } from '../../adapters/http/egress.js';
20
5
  import { isPoolBusy } from '../../adapters/poolMetrics.js';
21
- import { withAdmission } from '../../adapters/poolAdmission.js';
22
6
  import { AppAccessDenied } from '../columnGrants.js';
23
7
  import { wrongTypeValue } from '../constraints.js';
24
8
  import { PathError } from '../../shared/view.js';
@@ -28,8 +12,7 @@ import { probe } from './probes.js';
28
12
  import { reportRefusal } from './refusalReport.js';
29
13
  import { HttpError, send, sendBusy } from './reply.js';
30
14
  import { routedPath, servedApp, traceRequest } from './traceRequest.js';
31
- import { setBaselineHeaders } from './baselineHeaders.js';
32
- import { forwardedClient } from './trust.js';
15
+ import { frontDoor } from './frontDoor.js';
33
16
  import { timeRequests } from '../../adapters/telemetry/serverTiming.js';
34
17
  /* From source, Vite's modules are addressed from the root whatever the base
35
18
  (devclient.ts): its own paths and the client's files, never a page, the
@@ -99,12 +82,13 @@ export function listen(options, answering) {
99
82
  /* The span of each request (traceRequest.ts) names its route from the
100
83
  address after routeAddress has read it inward, never as the browser
101
84
  spelled it: under a base path or a root mount it is the same route. */
102
- const server = createServer((req, res) =>
103
- /* Its pool checkouts wait in line as its client's until its session names
104
- the account (adapters/poolAdmission.ts, http/door.ts). */
105
- traceRequest(req, res, () => withAdmission(forwardedClient(req, options.bound.trustedProxies), () => {
106
- options.diagnostics?.observe(req, res);
107
- setBaselineHeaders(req, res, options.bound.trustedProxies);
85
+ const server = frontDoor({
86
+ /* Its pool checkouts wait in line as its client's until its session names the account
87
+ (adapters/poolAdmission.ts, http/door.ts). */
88
+ trustedProxies: () => options.bound.trustedProxies,
89
+ diagnostics: options.diagnostics,
90
+ around: (req, res, run) => traceRequest(req, res, run),
91
+ }, (req, res) => {
108
92
  // Node accepts request targets that URL cannot parse. Refuse them before
109
93
  // dispatch, and reuse this parse in error mapping and drain tracking too.
110
94
  let url;
@@ -112,7 +96,7 @@ export function listen(options, answering) {
112
96
  url = new URL(req.url ?? '/', 'http://localhost');
113
97
  }
114
98
  catch {
115
- return send(res, 400, { error: 'Invalid request target.' });
99
+ return void send(res, 400, { error: 'Invalid request target.' });
116
100
  }
117
101
  const mount = answering.mount();
118
102
  if (answering.outside?.(req, res, url))
@@ -130,17 +114,17 @@ export function listen(options, answering) {
130
114
  if (answering.failed?.(err, req, res, url))
131
115
  return;
132
116
  /* The client left: its request was cut off mid-body, or it closed the
133
- socket before the answer, and what failed was the read it no longer
134
- waits for. Nobody can be answered and nothing went wrong on this
135
- side, so it is not a 500 on the operator's terminal: the request's
136
- span still says it was aborted (traceRequest.ts). */
117
+ socket before the answer, and what failed was the read it no longer
118
+ waits for. Nobody can be answered and nothing went wrong on this
119
+ side, so it is not a 500 on the operator's terminal: the request's
120
+ span still says it was aborted (traceRequest.ts). */
137
121
  if (clientLeft(req, res, err)) {
138
122
  res.destroy();
139
123
  return;
140
124
  }
141
125
  /* The pool had no connection to give within its budget: the server is
142
- busy, which is neither the caller's mistake nor a failure, and a 500
143
- after ten seconds said both. Answered now, with when to come back. */
126
+ busy, which is neither the caller's mistake nor a failure, and a 500
127
+ after ten seconds said both. Answered now, with when to come back. */
144
128
  if (isPoolBusy(err) && !res.headersSent) {
145
129
  reportRefusal(req, 503, 'server_busy', err.message, err);
146
130
  return sendBusy(res, {}, false, err);
@@ -155,7 +139,7 @@ export function listen(options, answering) {
155
139
  pending.add(operation);
156
140
  void operation.finally(() => pending.delete(operation));
157
141
  }
158
- })));
142
+ });
159
143
  commandOperations.set(server, pending);
160
144
  if (SOURCE_CLIENT && options.sourceClient !== false)
161
145
  attachDevClient(server);
@@ -16,11 +16,13 @@
16
16
  *
17
17
  * Three things it deliberately does not do.
18
18
  *
19
- * It is **not persisted**. The browser's undo stack makes this argument and it
20
- * is the right one: a stack that outlives the process invites undoing
21
- * something from an hour ago, by which time the row has very likely moved on
22
- * and the "undo" is an overwrite wearing a friendly name. In-session is the
23
- * honest scope.
19
+ * It is **kept in memory unless the database holds its store**. A stack that
20
+ * outlives the process invites undoing something from an hour ago, by which
21
+ * time the row has very likely moved on and the "undo" is an overwrite
22
+ * wearing a friendly name. Where the store is provisioned (journalStore.ts)
23
+ * the history survives a restart all the same, bounded by depth and a week,
24
+ * and the check below is what keeps an old Undo honest; where it is not, the
25
+ * journal is this process's alone, as it always was.
24
26
  *
25
27
  * It **checks before it writes**. Putting the old value back over a newer one
26
28
  * is not an undo, it is a silent overwrite — so the row is re-read first and
@@ -72,6 +74,32 @@ export interface JournalEntry {
72
74
  blocksUndo?: boolean;
73
75
  steps: WriteStep[];
74
76
  }
77
+ /**
78
+ * Where a connection's journal is kept beside memory (journalStore.ts). The
79
+ * calls below stay synchronous: memory is what they answer from, and each
80
+ * change is written behind them, in order, on one chain per connection. A
81
+ * write the store refused is said through `warn` and stays in memory; the
82
+ * revert's check-before-write is what an Undo relies on either way.
83
+ */
84
+ export interface JournalStore {
85
+ /** The entries kept for `connection`, oldest first, after retention has pruned what is past it. */
86
+ load(connection: string): Promise<JournalEntry[]>;
87
+ append(entry: JournalEntry): Promise<void>;
88
+ /** The entry's state changed (an Undo started or became uncertain, a quarantine). */
89
+ update(entry: JournalEntry): Promise<void>;
90
+ remove(connection: string, id: number): Promise<void>;
91
+ }
92
+ /**
93
+ * Keep `connection`'s journal in `store` from now on. The first time, what the
94
+ * store holds becomes the history: an Undo the last process left in progress
95
+ * reads as uncertain, since nothing says whether it landed. Again (a
96
+ * reconnect), the store is swapped and memory, already kept, stays.
97
+ */
98
+ export declare function attachJournalStore(connection: string, store: JournalStore, warn?: (message: string) => void): Promise<void>;
99
+ /** Every change written behind so far, landed or refused: before a reply that reports one, and before a close. */
100
+ export declare function flushJournal(connection?: string): Promise<void>;
101
+ /** Whether `connection`'s journal is kept in its database. */
102
+ export declare function journalKept(connection: string): boolean;
75
103
  /** Record a write that landed. Returns the entry, mostly for tests. */
76
104
  export declare function recordWrite(connection: string, entry: Omit<JournalEntry, 'id' | 'at' | 'connection'>): JournalEntry;
77
105
  /** The most recent first, which is the order anyone asks about them in. */
@@ -81,7 +109,8 @@ export declare function lastRevertible(connection: string): JournalEntry | undef
81
109
  /** Entries are newest first. Never silently step past an unresolved Undo. */
82
110
  export declare function latestRevertible(entries: readonly JournalEntry[]): JournalEntry | undefined;
83
111
  export declare function forget(connection: string, id: number): void;
84
- /** Testing seam: a fresh process is the normal state, and tests want it too. */
112
+ /** Testing seam: a fresh process is the normal state, and tests want it too.
113
+ * What a store keeps is left there, as a process that ended leaves it. */
85
114
  export declare function clearJournal(connection?: string): void;
86
115
  /** Fail closed without publishing another entry (or consulting a clock). The
87
116
  * caller supplies already verified ownership; no record values are introduced. */
@@ -16,11 +16,13 @@
16
16
  *
17
17
  * Three things it deliberately does not do.
18
18
  *
19
- * It is **not persisted**. The browser's undo stack makes this argument and it
20
- * is the right one: a stack that outlives the process invites undoing
21
- * something from an hour ago, by which time the row has very likely moved on
22
- * and the "undo" is an overwrite wearing a friendly name. In-session is the
23
- * honest scope.
19
+ * It is **kept in memory unless the database holds its store**. A stack that
20
+ * outlives the process invites undoing something from an hour ago, by which
21
+ * time the row has very likely moved on and the "undo" is an overwrite
22
+ * wearing a friendly name. Where the store is provisioned (journalStore.ts)
23
+ * the history survives a restart all the same, bounded by depth and a week,
24
+ * and the check below is what keeps an old Undo honest; where it is not, the
25
+ * journal is this process's alone, as it always was.
24
26
  *
25
27
  * It **checks before it writes**. Putting the old value back over a newer one
26
28
  * is not an undo, it is a silent overwrite — so the row is re-read first and
@@ -45,6 +47,60 @@ const entriesFor = (connection) => {
45
47
  journals.set(connection, []);
46
48
  return journals.get(connection);
47
49
  };
50
+ const kept = new Map();
51
+ function persist(connection, work) {
52
+ const at = kept.get(connection);
53
+ if (!at)
54
+ return;
55
+ at.chain = at.chain
56
+ .then(() => work(at.store))
57
+ .catch((error) => at.warn(`"${connection}": the write journal store refused a change: ${error.message}`));
58
+ }
59
+ /**
60
+ * Keep `connection`'s journal in `store` from now on. The first time, what the
61
+ * store holds becomes the history: an Undo the last process left in progress
62
+ * reads as uncertain, since nothing says whether it landed. Again (a
63
+ * reconnect), the store is swapped and memory, already kept, stays.
64
+ */
65
+ export async function attachJournalStore(connection, store, warn = (message) => console.error(message)) {
66
+ const current = kept.get(connection);
67
+ if (current) {
68
+ await current.chain;
69
+ current.store = store;
70
+ current.warn = warn;
71
+ return;
72
+ }
73
+ const loaded = await store.load(connection);
74
+ const ids = new Set(loaded.map((entry) => entry.id));
75
+ const unkept = entriesFor(connection).filter((entry) => !ids.has(entry.id));
76
+ const list = [...loaded, ...unkept].sort((a, b) => a.id - b.id).slice(-DEPTH);
77
+ journals.set(connection, list);
78
+ for (const entry of list)
79
+ nextId = Math.max(nextId, entry.id + 1);
80
+ kept.set(connection, { store, chain: Promise.resolve(), warn });
81
+ for (const entry of loaded) {
82
+ if (entry.undoState !== 'pending')
83
+ continue;
84
+ Object.assign(entry, { undoState: 'unknown', revertible: false, reason: undoUncertain });
85
+ persist(connection, (each) => each.update(entry));
86
+ }
87
+ for (const entry of unkept)
88
+ persist(connection, (each) => each.append(entry));
89
+ await flushJournal(connection);
90
+ }
91
+ /** Every change written behind so far, landed or refused: before a reply that reports one, and before a close. */
92
+ export async function flushJournal(connection) {
93
+ const chains = connection === undefined ? [...kept.values()] : kept.has(connection) ? [kept.get(connection)] : [];
94
+ for (const at of chains) {
95
+ let seen;
96
+ while (seen !== at.chain)
97
+ await (seen = at.chain);
98
+ }
99
+ }
100
+ /** Whether `connection`'s journal is kept in its database. */
101
+ export function journalKept(connection) {
102
+ return kept.has(connection);
103
+ }
48
104
  /** Record a write that landed. Returns the entry, mostly for tests. */
49
105
  export function recordWrite(connection, entry) {
50
106
  const full = {
@@ -57,6 +113,7 @@ export function recordWrite(connection, entry) {
57
113
  list.push(full);
58
114
  if (list.length > DEPTH)
59
115
  list.shift();
116
+ persist(connection, (store) => store.append(full));
60
117
  return full;
61
118
  }
62
119
  /** The most recent first, which is the order anyone asks about them in. */
@@ -82,13 +139,19 @@ export function forget(connection, id) {
82
139
  const at = list.findIndex((e) => e.id === id);
83
140
  if (at !== -1)
84
141
  list.splice(at, 1);
142
+ persist(connection, (store) => store.remove(connection, id));
85
143
  }
86
- /** Testing seam: a fresh process is the normal state, and tests want it too. */
144
+ /** Testing seam: a fresh process is the normal state, and tests want it too.
145
+ * What a store keeps is left there, as a process that ended leaves it. */
87
146
  export function clearJournal(connection) {
88
- if (connection === undefined)
147
+ if (connection === undefined) {
89
148
  journals.clear();
90
- else
149
+ kept.clear();
150
+ }
151
+ else {
91
152
  journals.delete(connection);
153
+ kept.delete(connection);
154
+ }
92
155
  }
93
156
  /** Fail closed without publishing another entry (or consulting a clock). The
94
157
  * caller supplies already verified ownership; no record values are introduced. */
@@ -99,6 +162,7 @@ export function quarantineHistory(connection, owner) {
99
162
  entry.revertible = false;
100
163
  entry.undoState = 'unknown';
101
164
  entry.reason = 'Newer write history could not be confirmed. Refresh and reconcile before further editing.';
165
+ persist(connection, (store) => store.update(entry));
102
166
  }
103
167
  }
104
168
  const keyFilter = (key) => ({
@@ -171,6 +235,9 @@ export async function revert(adapter, connection, entry, errorMessage = (error)
171
235
  return { reverted: false, outcome: 'not_applied', entry, errors: [errorMessage(error)] };
172
236
  }
173
237
  canonical.undoState = 'pending';
238
+ // Kept before the inverse runs: a process that stops mid-Undo leaves it uncertain, never offered again as if untried.
239
+ persist(connection, (store) => store.update(canonical));
240
+ await flushJournal(connection);
174
241
  try {
175
242
  const result = await revertOwned(adapter, connection, owned, errorMessage);
176
243
  if (result.outcome === 'unknown') {
@@ -189,6 +256,10 @@ export async function revert(adapter, connection, entry, errorMessage = (error)
189
256
  finally {
190
257
  if (canonical.undoState === 'pending')
191
258
  delete canonical.undoState;
259
+ // An applied Undo was forgotten (revertOwned); anything else says its state again.
260
+ if (entriesFor(connection).includes(canonical))
261
+ persist(connection, (store) => store.update(canonical));
262
+ await flushJournal(connection);
192
263
  }
193
264
  }
194
265
  const undoUncertain = 'The Undo outcome could not be confirmed. Refresh and reconcile the records; do not retry this Undo.';
@@ -0,0 +1,37 @@
1
+ import { DatabaseSync } from 'node:sqlite';
2
+ import { type Adapter } from '../adapters/adapter.js';
3
+ import type { PgQuery } from '../adapters/postgresPool.js';
4
+ declare const WRITE_JOURNAL_VERSION = 1;
5
+ /** How much is kept: the journal's depth per connection, a week, and an entry of at most 4 MiB. */
6
+ export declare const WRITE_JOURNAL_RETENTION: Readonly<{
7
+ entries: 50;
8
+ days: 7;
9
+ bytes: number;
10
+ }>;
11
+ /** Exactly this version's two tables and their key indexes, nothing else under the prefix, and its version row. */
12
+ export declare function sqliteWriteJournalReady(db: DatabaseSync): boolean;
13
+ /**
14
+ * Explicit maintenance, never run when a connection opens: a file without the
15
+ * store gets this version; the same layout again changes nothing; anything
16
+ * else under the prefix is refused unchanged.
17
+ */
18
+ export declare function provisionSqliteWriteJournal(existingPath: string): {
19
+ version: typeof WRITE_JOURNAL_VERSION;
20
+ provisioned: boolean;
21
+ };
22
+ /** Whether the reserved relations are exactly this version's layout with its version row. */
23
+ export declare function postgresWriteJournalReady(client: PgQuery): Promise<boolean>;
24
+ /** Explicit maintenance, under the shared migration lock: creates this version
25
+ * where no store exists, changes nothing where it does, refuses anything else. */
26
+ export declare function provisionPostgresWriteJournal(url: string): Promise<{
27
+ version: typeof WRITE_JOURNAL_VERSION;
28
+ provisioned: boolean;
29
+ }>;
30
+ /**
31
+ * Keep `connection`'s journal in its database when the database holds the
32
+ * store: what it held is read back, and every write from here on is kept
33
+ * there too. Never fatal: a store that cannot be read leaves the journal in
34
+ * memory, said through `warn`. Resolves to whether the store is now used.
35
+ */
36
+ export declare function keepWriteJournal(connection: string, adapter: Adapter, warn?: (message: string) => void): Promise<boolean>;
37
+ export {};