@genesislcap/mock-server 15.64.1 → 15.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/server.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import http from 'node:http';
2
2
  import { WebSocketServer, type WebSocket } from 'ws';
3
3
  import { recordKey } from './db/identity.ts';
4
+ import { compareRecordIds } from './db/ordering.ts';
4
5
  import { Store } from './db/store.ts';
5
6
  import {
6
7
  entriesReading,
@@ -10,11 +11,11 @@ import {
10
11
  type ViewEntry,
11
12
  } from './db/views.ts';
12
13
  import { crudEventHandler } from './handlers/crudEvents.ts';
13
- import { pendingKey } from './handlers/dataLogon.ts';
14
+ import { pendingKey, viewRow, waitForPage } from './handlers/dataLogon.ts';
14
15
  import { createHttpRequestListener } from './handlers/http.ts';
15
16
  import { permittedQueryRow, requestingUser } from './handlers/resourceAuth.ts';
16
- import { Connection, type Subscription } from './protocol/connection.ts';
17
- import { isLegacyFidelity } from './protocol/fidelity.ts';
17
+ import { Connection, type Subscription, type ViewRow } from './protocol/connection.ts';
18
+ import { isLegacyFidelity, liveModifyMode } from './protocol/fidelity.ts';
18
19
  import { routeMessage } from './protocol/router.ts';
19
20
  import { dataserverRow, stampRow, type RowOperation } from './protocol/rowUpdate.ts';
20
21
  import type {
@@ -39,18 +40,55 @@ interface TableChange {
39
40
  records: Set<string>;
40
41
  }
41
42
 
42
- // Whether two rows carry the same columns and values (a value compared as
43
- // JSON when it isn't the same primitive).
43
+ // Whether two values are the same: the same primitive, or the same JSON.
44
+ function sameValue(a: unknown, b: unknown): boolean {
45
+ return Object.is(a, b) || JSON.stringify(a) === JSON.stringify(b);
46
+ }
47
+
48
+ // Whether two rows carry the same columns and values.
44
49
  function sameValues(a: Row, b: Row): boolean {
45
50
  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
46
51
  for (const key of keys) {
47
- if (!Object.is(a[key], b[key]) && JSON.stringify(a[key]) !== JSON.stringify(b[key])) {
48
- return false;
49
- }
52
+ if (!sameValue(a[key], b[key])) return false;
50
53
  }
51
54
  return true;
52
55
  }
53
56
 
57
+ // What a live MODIFY sends a client that holds `held`: each field whose value
58
+ // differs in `next`, a field that became null (or that `next` no longer
59
+ // carries, as a column now hidden from the user) as null — as GSF's
60
+ // diffToGenesisSet and the hidden-field handling of
61
+ // QueryUpdate.Modified.setModifyFromQueryRow write it (v8.15.29). Null and
62
+ // absent are the same value. In column order.
63
+ function changedFields(held: Row, next: Row): Row {
64
+ const changed: Row = {};
65
+ for (const field of new Set([...Object.keys(held), ...Object.keys(next)])) {
66
+ const value = next[field] ?? null;
67
+ if (!sameValue(held[field] ?? null, value)) changed[field] = value;
68
+ }
69
+ return changed;
70
+ }
71
+
72
+ // The held row a moving view evicts: the oldest version the client holds, by
73
+ // TIMESTAMP and then RECORD_ID, as MovingViewClientIndex's timestampIndex
74
+ // orders them (v8.15.29) — not the row last in the snapshot order. Rows with
75
+ // no ROW_REF can't be named in a DELETE, so are never chosen.
76
+ function oldestHeld(held: Map<string, ViewRow>): [string, ViewRow] | undefined {
77
+ let oldest: [string, ViewRow] | undefined;
78
+ for (const candidate of held) {
79
+ const [, entry] = candidate;
80
+ if (entry.rowRef === undefined || entry.rowRef === null) continue;
81
+ if (
82
+ !oldest ||
83
+ (compareRecordIds(entry.timestamp, oldest[1].timestamp) ||
84
+ compareRecordIds(entry.rowRef, oldest[1].rowRef)) < 0
85
+ ) {
86
+ oldest = candidate;
87
+ }
88
+ }
89
+ return oldest;
90
+ }
91
+
54
92
  export interface MockServer {
55
93
  start(port: number): WebSocketServer;
56
94
  // Like start(), but resolves with the ACTUAL bound port once listening —
@@ -102,7 +140,7 @@ export function createMockServer(config: MockServerConfig): MockServer {
102
140
  // predicate would evaluate against missing fields and drop the push —
103
141
  // leaving the client holding a ghost row. A DELETE therefore skips the
104
142
  // predicate; which subscriptions it reaches is decided by what each client
105
- // holds (trackClientView), or, in legacy mode, it reaches all of them.
143
+ // holds (viewUpdate), or, in legacy mode, it reaches all of them.
106
144
  // 'error' is kept distinct from 'no-match' because only a clean no-match may
107
145
  // be turned into a DELETE below; a broken predicate must not evict rows.
108
146
  function evaluateSubscription(
@@ -146,59 +184,83 @@ export function createMockServer(config: MockServerConfig): MockServer {
146
184
  return operation === 'MODIFY' ? 'DELETE' : null;
147
185
  }
148
186
 
149
- // Decides what one 'gsf' subscription's client gets for a live change, from
150
- // what that client holds — as the real dataserver does with its client
151
- // index — and keeps the subscription's pending/held sets up to date.
152
- // `operation` is the change after the query filter and CRITERIA_MATCH
153
- // (a MODIFY that left them arrives as a DELETE); the user's rowFilter is
154
- // applied here too, so leaving it counts as leaving the subscription.
155
- // - A row still waiting for MORE_ROWS (past the page, or past MAX_VIEW) is
156
- // never pushed: the client has never seen it. A change replaces the
157
- // waiting copy in place, so the page later delivers current values; a
158
- // DELETE drops it.
159
- // - A held row gets the MODIFY, or a DELETE when it is gone or out of scope.
187
+ // The rows of the QUERY_UPDATE one 'gsf' subscription's client gets for a
188
+ // live change, decided from what that client holds as the real
189
+ // dataserver's client index decides (ClientIndex and MovingViewClientIndex,
190
+ // v8.15.29); none to push nothing. Keeps the subscription's pending and
191
+ // held rows up to date. `operation` is the change after the query filter
192
+ // and CRITERIA_MATCH (a MODIFY that left them arrives as a DELETE); the
193
+ // user's rowFilter is applied here too, so leaving it counts as leaving the
194
+ // subscription.
195
+ // - A held row gets a MODIFY of what changed since the client last got it
196
+ // (liveModify 'full': the whole row), and nothing when nothing it can
197
+ // see changed; a DELETE when it is gone or out of scope. An INSERT of a
198
+ // row it holds is ignored.
160
199
  // - A row the client doesn't hold that is (now) in scope is pushed as an
161
- // INSERT and becomes held: a brand-new row, or one a MODIFY brought back
162
- // into the criteria. Out of scope, the client is told nothing. The
163
- // snapshot's order doesn't matter: a new row that sorts among the rows
164
- // still waiting is pushed now too, as GSF's client index does, and no
165
- // later page repeats it.
166
- // An INSERT is pushed even when the view already holds MAX_VIEW rows; the
167
- // real server would also evict the oldest row in the same frame (moving
168
- // view), which this engine doesn't, so the view can grow past MAX_VIEW.
200
+ // INSERT and becomes held: a new row, one waiting for MORE_ROWS, one a
201
+ // MODIFY brought back into the criteria (processInsertUpdate, and
202
+ // putNewRowEntry for a MODIFY). The snapshot's order doesn't matter, and
203
+ // no later page repeats it. A full view takes it only when it moves:
204
+ // the held row with the oldest TIMESTAMP is evicted, as a DELETE after
205
+ // the INSERT in the same frame (nothing at all when that is the new row
206
+ // itself). Without a moving view a full view takes nothing
207
+ // (MaxViewReached), and the row waits for a page if it sorts after the
208
+ // read position (waitForPage) — as an evicted row does too.
209
+ // - Out of scope or deleted, a waiting row is dropped and a row the client
210
+ // never held gets nothing.
169
211
  // A row without a ROW_REF can't be matched to anything the client holds,
170
212
  // so changes to it aren't pushed.
171
- // Returns the operation to push, or null to push nothing.
172
- function trackClientView(
213
+ function viewUpdate(
173
214
  subscription: Subscription,
174
215
  connection: Connection,
175
216
  query: QueryDef | undefined,
176
217
  operation: RowOperation,
177
218
  row: Row,
178
219
  rowRef: unknown,
179
- ): RowOperation | null {
220
+ ): Row[] {
180
221
  const key = pendingKey(rowRef);
181
- const pending = subscription.pending;
182
- const held = subscription.held;
183
- if (key === undefined || !pending || !held) return null;
222
+ const { pending, held } = subscription;
223
+ if (key === undefined || !pending || !held) return [];
184
224
  const permitted =
185
225
  operation === 'DELETE'
186
226
  ? undefined
187
227
  : permittedQueryRow(row, query?.auth, requestingUser(connection), subscription.fieldNames);
188
- if (pending.has(key)) {
189
- if (permitted)
190
- pending.set(key, stampRow(wireRow(subscription, permitted, row), rowRef, 'INSERT'));
191
- else pending.delete(key);
192
- return null;
193
- }
194
- if (held.has(key)) {
195
- if (permitted) return 'MODIFY';
228
+ const current = held.get(key);
229
+ if (!permitted) {
230
+ pending.delete(key);
231
+ if (!current) return [];
196
232
  held.delete(key);
197
- return 'DELETE';
233
+ return [stampRow({}, rowRef, 'DELETE')];
234
+ }
235
+ const entry = viewRow(wireRow(subscription, permitted, row), rowRef, row);
236
+ if (current) {
237
+ if (operation === 'INSERT') return [];
238
+ held.set(key, entry);
239
+ const changed = changedFields(current.row, entry.row);
240
+ if (Object.keys(changed).length === 0) return [];
241
+ return [stampRow(liveModifyMode(config) === 'full' ? entry.row : changed, rowRef, 'MODIFY')];
242
+ }
243
+ const waiting = (view: ViewRow): ViewRow => ({
244
+ ...view,
245
+ row: stampRow(view.row, view.rowRef, 'INSERT'),
246
+ });
247
+ const maxView = subscription.maxView ?? Infinity;
248
+ if (!subscription.movingView && held.size >= maxView) {
249
+ waitForPage(subscription, key, waiting(entry));
250
+ return [];
251
+ }
252
+ pending.delete(key);
253
+ held.set(key, entry);
254
+ const rows = [stampRow(entry.row, rowRef, 'INSERT')];
255
+ const evicted = held.size > maxView ? oldestHeld(held) : undefined;
256
+ if (evicted) {
257
+ const [evictedKey, evictedRow] = evicted;
258
+ held.delete(evictedKey);
259
+ waitForPage(subscription, evictedKey, waiting(evictedRow));
260
+ if (evictedKey === key) return [];
261
+ rows.push(stampRow({}, evictedRow.rowRef, 'DELETE'));
198
262
  }
199
- if (!permitted) return null;
200
- held.add(key);
201
- return 'INSERT';
263
+ return rows;
202
264
  }
203
265
 
204
266
  function pushChange(resourceName: string, operation: RowOperation, row: Row): void {
@@ -228,39 +290,44 @@ export function createMockServer(config: MockServerConfig): MockServer {
228
290
  // ROW_REF is computed from the unstripped row, since pk fields may
229
291
  // themselves be hidden from this user.
230
292
  const rowRef = subscription.getRowRef(row);
231
- const rowOperation = subscription.held
232
- ? trackClientView(subscription, connection, query, resolved, row, rowRef)
233
- : resolved;
234
- if (rowOperation === null) continue;
235
293
  const legacy = isLegacyFidelity(config);
236
- let outRow = row;
237
- if (rowOperation === 'DELETE') {
294
+ let rows: Row[];
295
+ if (subscription.held) {
296
+ rows = viewUpdate(subscription, connection, query, resolved, row, rowRef);
297
+ } else if (resolved === 'DELETE') {
238
298
  // GSF's DELETE row is DETAILS {OPERATION, ROW_REF} and nothing else.
239
299
  // Legacy mode sent the pk fields: the stub it was given for a real
240
300
  // DELETE, or one rebuilt from the key for a change that left the
241
301
  // subscription (the full row may carry columns hideFields strips).
242
- if (!legacy) outRow = {};
243
- else if (operation !== 'DELETE') {
244
- outRow = query ? store.rowStubFromKey(query.source, rowRef as string) : row;
302
+ let outRow: Row = {};
303
+ if (legacy) {
304
+ outRow =
305
+ operation !== 'DELETE' && query
306
+ ? store.rowStubFromKey(query.source, rowRef as string)
307
+ : row;
245
308
  }
309
+ rows = [stampRow(outRow, rowRef, resolved, legacy)];
246
310
  } else {
247
- // Only the subscription's columns, minus the ones this user can't see.
311
+ // Only the subscription's columns, minus the ones this user can't
312
+ // see; always the whole row.
248
313
  const permitted = permittedQueryRow(
249
314
  row,
250
315
  query?.auth,
251
316
  requestingUser(connection),
252
317
  subscription.fieldNames,
253
318
  );
254
- if (!permitted) continue;
255
- outRow = wireRow(subscription, permitted, row);
319
+ rows = permitted
320
+ ? [stampRow(wireRow(subscription, permitted, row), rowRef, resolved, legacy)]
321
+ : [];
256
322
  }
323
+ if (rows.length === 0) continue;
257
324
  subscription.sequenceId += 1;
258
325
  // A live push carries neither MORE_ROWS nor ROWS_COUNT on the real
259
326
  // server — those describe the snapshot. Legacy mode sent ROWS_COUNT: 1.
260
327
  connection.send({
261
328
  MESSAGE_TYPE: 'QUERY_UPDATE',
262
329
  SOURCE_REF: sourceRef,
263
- ROW: [stampRow(outRow, rowRef, rowOperation, legacy)],
330
+ ROW: rows,
264
331
  ...(legacy ? { ROWS_COUNT: 1 } : {}),
265
332
  SEQUENCE_ID: subscription.sequenceId,
266
333
  });
package/src/types.ts CHANGED
@@ -500,9 +500,19 @@ export type OnMessageHook = (
500
500
  // to be removed in a later release.
501
501
  export type FidelityMode = 'gsf' | 'legacy';
502
502
 
503
+ // How a live MODIFY's row is written under fidelity 'gsf'. 'diff' (the
504
+ // default) is GSF's: only the fields that changed since the client was last
505
+ // sent the row, a field that became null as null, plus DETAILS. 'full' sends
506
+ // the whole row, for a client that can't merge a partial row yet. Either
507
+ // way a MODIFY that changes nothing the client sees isn't sent. Fidelity
508
+ // 'legacy' always sends whole rows.
509
+ export type LiveModifyMode = 'diff' | 'full';
510
+
503
511
  export interface MockServerConfig {
504
512
  // Defaults to 'gsf'. See FidelityMode and the README's "Wire fidelity".
505
513
  fidelity?: FidelityMode;
514
+ // Defaults to 'diff'. See LiveModifyMode and the README's "Dataserver paging".
515
+ liveModify?: LiveModifyMode;
506
516
  tables?: Record<string, TableDef>;
507
517
  views?: Record<string, ViewDef>;
508
518
  queries?: Record<string, QueryDef>;