@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/README.md CHANGED
@@ -253,9 +253,7 @@ views: {
253
253
  - a `DELETE` for a row it drops;
254
254
  - a `MODIFY` for a row joined to the changed record (before or after), or whose values changed;
255
255
  - nothing for the rest.
256
- - **A row joined to the changed record is pushed even when its values look unchanged.** The "before" is the store's: each record as it was before its first modify that no broadcast has announced yet, plus the records a key lost. A client may hold newer values than that, for example from a snapshot taken after an unannounced change.
257
- - GSF's client index compares against what each client holds, and sends nothing for a modify that changes no exposed field.
258
- - So here a change to a column the view doesn't expose still pushes the rows joined to it. The values are unchanged, which clients take as a no-op.
256
+ - **Each client gets what changed for it.** These are the candidates. Each subscription then compares a row with what its client was last sent, as for any live change ([Dataserver paging](#dataserver-paging)). A `MODIFY` carries only the columns that changed (a re-derived field and a joined column included). One that changes no column the client sees, such as a change to a column the view doesn't expose, sends nothing. A row the client doesn't hold arrives as an `INSERT`.
259
257
  - **Anti-joins** are not a GSF construct, so a change to an anti-joined table is always pushed, as `INSERT`s and `DELETE`s.
260
258
  - **A DELETE broadcast before its row is removed** counts the row as gone.
261
259
  - **A view that joins its own base table** gets each changed base row once, from the base-table path.
@@ -656,7 +654,7 @@ the envelopes this engine sent up to 15.47 — see
656
654
  | `EVENT_LOGOUT` | `LOGOUT_ACK` | |
657
655
  | `HEARTBEAT_PING` | `HEARTBEAT_PONG` | |
658
656
  | `DATA_LOGON` | `LOGON_ACK {SEQUENCE_ID: 0}`, then `QUERY_UPDATE {ROW, MORE_ROWS, ROWS_COUNT, SEQUENCE_ID: 1}` | The first page only — see [Dataserver paging](#dataserver-paging). No matching rows: `{QUERY_UPDATE, MORE_ROWS: false, SEQUENCE_ID: 1}`, with no `ROW` and no `ROWS_COUNT`. A second logon on a live `SOURCE_REF` gets `MSG_NACK` 409 |
659
- | (live push) | `QUERY_UPDATE {ROW, SEQUENCE_ID}` | One row per push; `DETAILS.OPERATION` is `INSERT`/`MODIFY`/`DELETE`. No `MORE_ROWS`, no `ROWS_COUNT` |
657
+ | (live push) | `QUERY_UPDATE {ROW, SEQUENCE_ID}` | One row per push, or an `INSERT` and the `DELETE` it evicts from a full moving view; `DETAILS.OPERATION` is `INSERT`/`MODIFY`/`DELETE`, and a `MODIFY` carries only the changed fields. No `MORE_ROWS`, no `ROWS_COUNT` |
660
658
  | `MORE_ROWS` | `QUERY_UPDATE {ROW?, MORE_ROWS, SEQUENCE_ID}` on the logon's `SOURCE_REF`, plus `MORE_ROWS_ACK` | See [Dataserver paging](#dataserver-paging) |
661
659
  | `DATA_LOGOFF` | `LOGOFF_ACK` | `MSG_NACK` 404 when the connection has no such subscription |
662
660
  | `META_REQUEST` | `FEATURE_ACK {DETAILS}` | Dataservers, request servers (by name, without `REQ_`) and events — see [Declared schema](#declared-schema-meta_request-and-json_schema_request) |
@@ -711,11 +709,13 @@ createMockServer({ ...config, fidelity: 'legacy' });
711
709
 
712
710
  | | `'gsf'` (default) | `'legacy'` |
713
711
  |---|---|---|
714
- | `DATA_LOGON` | `LOGON_ACK`, then the first `MAX_ROWS` rows | Every row in one `QUERY_UPDATE`, no `LOGON_ACK`; `MAX_ROWS` and `MAX_VIEW` are ignored |
712
+ | `DATA_LOGON` | `LOGON_ACK`, then the first `MAX_ROWS` rows; `MAX_VIEW: 0` without `MOVING_VIEW: false` is `LOGON_NACK INVALID_PARAMETER` | Every row in one `QUERY_UPDATE`, no `LOGON_ACK`; `MAX_ROWS`, `MAX_VIEW` and `MOVING_VIEW` are ignored |
715
713
  | No matching rows | No `ROW`, no `ROWS_COUNT` | `ROW: []`, `ROWS_COUNT: 0` |
716
714
  | Repeated `DATA_LOGON` on a live `SOURCE_REF` | `MSG_NACK` 409; the first subscription keeps running | Replaces the subscription and sends a new snapshot |
717
715
  | `ROWS_COUNT` | Rows after the query `filter`, before `CRITERIA_MATCH` and the `rowFilter` | Rows after all three |
718
716
  | Live push | No `ROWS_COUNT`; only for rows the client holds, or as an `INSERT` for a row that is new to it | `ROWS_COUNT: 1`; to every subscription whose criteria match (every DELETE goes to all of them) |
717
+ | Live `MODIFY` | The fields that changed since the client was last sent the row, a nulled one as `null`, plus `DETAILS`; nothing when nothing it sees changed (`liveModify: 'full'`: the whole row) ([Live MODIFY](#live-modify-a-diff-of-what-the-client-holds)) | The whole row, every time |
718
+ | A full `MAX_VIEW` | A moving view (`MOVING_VIEW`, default `true`) takes a new row and evicts the oldest held one in the same frame; without one, it takes nothing ([Moving view](#a-full-view-the-moving-view)) | Unlimited |
719
719
  | `MORE_ROWS` | The next page, plus `MORE_ROWS_ACK` | Unanswered (logged as unhandled) |
720
720
  | `DATA_LOGOFF` | `LOGOFF_ACK`, or `MSG_NACK` 404 | Unanswered |
721
721
  | `META_REQUEST` / `JSON_SCHEMA_REQUEST` success | `FEATURE_ACK` / `JSON_SCHEMA_FEATURE_ACK` | Echoes the request's `MESSAGE_TYPE` |
@@ -893,7 +893,14 @@ v8.15.29: a `DateTime` as epoch millis, a `BigDecimal` as
893
893
  (default 1000) is the most rows the view holds across all pages. `MAX_ROWS`
894
894
  is clamped to `MAX_VIEW`, and `0` means "no limit" for either. These are
895
895
  also foundation-comms' `DatasourceDefaults`, so a grid that sets neither gets
896
- 250 rows and then pages.
896
+ 250 rows and then pages. **`DETAILS.MOVING_VIEW`** defaults to `true` (see
897
+ [the moving view](#a-full-view-the-moving-view)), so an unlimited view needs
898
+ `MAX_VIEW: 0` with `MOVING_VIEW: false`; `MAX_VIEW: 0` alone is `LOGON_NACK
899
+ INVALID_PARAMETER` "MOVING_VIEW can't be true if maxView is set to 0",
900
+ checked before `ORDER_BY` (`ConnectionManager.verifyClientOptions`).
901
+ foundation-comms sends `MOVING_VIEW: false` unless a grid sets
902
+ `moving-view`. A logon with a `VIEW_NUMBER` other than 0 gets a view of one
903
+ page (`MAX_ROWS`) that doesn't move (`ClientOptions.parse`).
897
904
  - **Row order.** Without `ORDER_BY` the dataserver reads its primary index,
898
905
  `RECORD_ID`, **newest first**, and `REVERSE: true` alone makes it oldest
899
906
  first, the order the rows were written in (genesis-pal-dataserver
@@ -945,34 +952,80 @@ v8.15.29: a `DateTime` as epoch millis, a `BigDecimal` as
945
952
  `SOURCE_REF`; closing one leaves the other's subscription alone.
946
953
 
947
954
  **Live changes follow what each client holds.** Like the real dataserver's
948
- client index, every subscription knows which rows it has sent (`held`) and
949
- which matched rows are still waiting (`pending`: past the current page, or
950
- past `MAX_VIEW`). A row is in scope while it passes the query `filter`,
951
- `CRITERIA_MATCH` and the user's `rowFilter`. For each live change:
955
+ client index, every subscription knows which rows it has sent, with the values
956
+ it sent (`held`), and which matched rows are still waiting (`pending`: past the
957
+ current page, or past `MAX_VIEW`). A row is in scope while it passes the query
958
+ `filter`, `CRITERIA_MATCH` and the user's `rowFilter`. For each live change
959
+ (`ClientIndex` / `MovingViewClientIndex`, v8.15.29):
952
960
 
953
961
  | The row is… | In scope after the change | Out of scope, or deleted |
954
962
  |---|---|---|
955
- | Held by the client | `MODIFY` pushed | `DELETE` pushed (row identity only) |
956
- | Waiting for `MORE_ROWS` | Waiting copy updated in place, nothing pushed | Dropped from the waiting rows, nothing pushed |
957
- | Not known to the client | `INSERT` pushed with the full row; now held | Nothing pushed |
963
+ | Held by the client | `MODIFY` of what changed pushed; nothing when nothing it sees changed. An `INSERT` of it is ignored | `DELETE` pushed (row identity only) |
964
+ | Waiting for `MORE_ROWS`, or not known to the client | `INSERT` pushed with the full row; now held, and no page repeats it. A full view takes it only [as a moving view](#a-full-view-the-moving-view) | Dropped from the waiting rows, nothing pushed |
958
965
 
959
- So a new row arrives as an `INSERT`, a row a MODIFY brings back into the
960
- criteria arrives as an `INSERT` (recorded: `DELETE` on leaving, `INSERT` on
961
- re-entering, same `ROW_REF`), and rows the client never got — including rows
962
- cut off by `MAX_VIEW`, and the view rows a change to a joined table touches —
963
- get no MODIFYs or DELETEs at all. A waiting row's page later
964
- delivers its current values. Nothing absorbed uses a `SEQUENCE_ID`.
966
+ So a new row arrives as an `INSERT`, and so does a row a MODIFY brings back
967
+ into the criteria (recorded: `DELETE` on leaving, `INSERT` on re-entering, same
968
+ `ROW_REF`) and a waiting row a MODIFY touches (`processModifyUpdate` →
969
+ `putNewRowEntry`: the client index doesn't know the row). Rows the client never
970
+ got get no MODIFYs or DELETEs at all. Nothing absorbed uses a `SEQUENCE_ID`.
965
971
 
966
972
  A new row is pushed as soon as it arrives, whatever the order — also when it
967
973
  sorts among the rows still waiting (under `ORDER_BY`, or oldest first) — and
968
974
  no later page sends it again: the real `ClientIndex.processInsertUpdate` sends
969
- it straight away while the view has room (always, with the default moving
970
- view), and `NextRowsStrategy` skips rows the client already holds.
971
-
972
- An `INSERT` is pushed even when the view already holds `MAX_VIEW` rows. The
973
- real server would also evict the oldest row in the same frame (the moving
974
- view, a later item), so here the view can grow past `MAX_VIEW`; the next
975
- `MORE_ROWS` then delivers nothing until DELETEs bring it back under the cap.
975
+ it straight away while the view has room, and `NextRowsStrategy` skips rows
976
+ the client already holds.
977
+
978
+ ### Live MODIFY: a diff of what the client holds
979
+
980
+ A live `MODIFY` carries only the fields whose values differ from what that
981
+ client was last sent for the row, plus `DETAILS {OPERATION, ROW_REF}`
982
+ (recorded: a renamed counterparty is `{NAME, DETAILS}`). A field that became
983
+ `null` is sent as `null`, and so is a column the user can no longer see. On a
984
+ view this includes a re-derived field and a joined column (recorded:
985
+ `{QUANTITY, CREATED_AT: null, TOTAL, ENTERED_BY: null, TRADE_STATUS: null,
986
+ DETAILS}` for a trade modify that left out three fields). The primary key
987
+ isn't there unless it changed, so a client must merge the row into the one it
988
+ holds by `ROW_REF`. GSF diffs the query's previous row against the new one
989
+ (`MemoryTableSubscriber.processModify`, `diffToGenesisSet`) and narrows it to
990
+ the client's columns (`QueryUpdate.Modified.setModifyFromQueryRow`). This
991
+ engine diffs against what each client holds, which is the same row once every
992
+ change is broadcast, and still right after a change that wasn't. A `MODIFY`
993
+ that changes nothing the client sees, such as a column outside its `FIELDS`,
994
+ isn't sent and takes no `SEQUENCE_ID`.
995
+
996
+ `liveModify: 'full'` (`MockServerConfig.liveModify`, type `LiveModifyMode`)
997
+ sends the whole row on every `MODIFY` instead, for a client that can't merge a
998
+ partial row yet; which `MODIFY`s are sent doesn't change. `fidelity:
999
+ 'legacy'` always sends whole rows.
1000
+
1001
+ ### A full view: the moving view
1002
+
1003
+ `DETAILS.MOVING_VIEW` (default `true`) decides what a view that holds
1004
+ `MAX_VIEW` rows does with a new one (recorded in `live-moving-view`, where the
1005
+ logon without `MOVING_VIEW` moves too):
1006
+
1007
+ - **Moving view.** The row is pushed as an `INSERT`, and the held row with the
1008
+ oldest `TIMESTAMP` is evicted as a `DELETE` in the same `QUERY_UPDATE`, after
1009
+ the `INSERT`. Oldest is the version the client holds, by `TIMESTAMP` and then
1010
+ `RECORD_ID` (`MovingViewClientIndex.timestampIndex`), whatever the order
1011
+ the view is in. Newest first, that is the last row of the snapshot; under
1012
+ `REVERSE` or `ORDER_BY` it can be any row, and a row a `MODIFY` reached is
1013
+ newer than one it didn't. When the new row is itself the oldest, nothing is
1014
+ sent. A `MODIFY` of a row the view doesn't hold evicts the same way.
1015
+ - **`MOVING_VIEW: false`.** The view takes nothing more (`MaxViewReached`).
1016
+ - Either way, a row the view doesn't take, or evicts, waits for a page only
1017
+ when it sorts after the last row a page delivered: the real
1018
+ `NextRowsStrategy` reads on from there and never goes back. Newest first, a
1019
+ new row sorts before it, and so does every row a page sent, so neither is
1020
+ sent again; only a row pushed while it was still waiting can come back. A
1021
+ later `DELETE` frees a slot but pushes nothing; the next `MORE_ROWS` fills
1022
+ it.
1023
+
1024
+ **Behaviour change.** Up to 15.58, a live `MODIFY` carried the whole row and
1025
+ was sent whenever a change reached a held row, a `MODIFY` of a waiting row
1026
+ pushed nothing, a full view took every new row and grew past `MAX_VIEW`, and
1027
+ `MAX_VIEW: 0` alone meant no limit. `liveModify: 'full'` brings back whole
1028
+ rows; `fidelity: 'legacy'` keeps all of it as it was in 15.47.
976
1029
 
977
1030
  Every row's `ROW_REF` is its own record's `RECORD_ID` (a view row's, its base
978
1031
  record's), so live changes are matched to exactly the row the client holds,
@@ -1287,10 +1340,10 @@ That includes the functions this engine evaluated before GSF's semantics —
1287
1340
  `Expr.contains`, `Expr.equals`, `Expr.equalsIgnoreCase`, `Expr.startsWith`,
1288
1341
  `Expr.endsWith`, `Expr.dateTimeIsEqual`, `FIELD.endsWith`, and an `Expr`
1289
1342
  function called as a field method (`TRADE_DATE.dateIsEqual(...)`).
1290
- foundation-criteria's `Serialisers.contains` and `Serialisers.endsWith` emit
1291
- two of them. **And a call no overload takes**, which GSF's `@CompileStatic`
1292
- compilation refuses: the wrong number of arguments
1293
- (`Expr.containsIgnoreCase(NAME)`), an ambiguous `null`
1343
+ foundation-criteria's deprecated `Serialisers.endsWith` still emits one of
1344
+ them (`Serialisers.contains` used to emit `Expr.contains`). **And a call no
1345
+ overload takes**, which GSF's `@CompileStatic` compilation refuses: the wrong
1346
+ number of arguments (`Expr.containsIgnoreCase(NAME)`), an ambiguous `null`
1294
1347
  (`Expr.dateIsToday(null)`), and — where the fields' types are declared — an
1295
1348
  argument of the wrong type (`Expr.containsIgnoreCase(QTY, '1')` on a `LONG`),
1296
1349
  a field method the field's type lacks (`QTY.startsWith('1')`), or a
@@ -1392,7 +1445,7 @@ A live **MODIFY** that moves a row out of a subscription's `CRITERIA_MATCH`, or
1392
1445
  out of the query's `filter`, is pushed as a **DELETE** carrying only the row's
1393
1446
  identity to a client that holds the row, and a MODIFY that brings a row back
1394
1447
  in is pushed as an **INSERT** (`resolveSubscriptionOperation()` and
1395
- `trackClientView()` in `src/server.ts`; see
1448
+ `viewUpdate()` in `src/server.ts`; see
1396
1449
  [Dataserver paging](#dataserver-paging)). If the predicate throws, the push
1397
1450
  is skipped instead: a broken filter must never evict rows. **Deletes** bypass
1398
1451
  the criteria predicate; they reach every client that holds the row. (Under
@@ -1401,24 +1454,20 @@ entering the criteria is pushed as a MODIFY.)
1401
1454
 
1402
1455
  Where this engine still differs from the real server:
1403
1456
 
1404
- - Live MODIFYs carry the **full row**. The real server sends only the changed
1405
- fields; a full row is a superset, which clients tolerate.
1406
- - A change through a view's **backwards join** pushes a MODIFY to every held
1407
- row joined to the changed record, even when no column the view exposes
1408
- changed. The real server compares against what the client holds and sends
1409
- nothing then (see [Views](#views-the-join-model)).
1410
- - There is no **moving view**. Once the view holds `MAX_VIEW` rows, live
1411
- INSERTs are still pushed instead of also evicting the oldest row.
1457
+ - **The read position** a row must sort after to wait for a page is the last
1458
+ row a page delivered. GSF's is the last row it read, which is further on
1459
+ when the rows after the last one delivered didn't match.
1460
+ - GSF's client index also drops a `MODIFY` whose row isn't newer, by
1461
+ `TIMESTAMP`, than the one the client holds (`modifyRowEntry`), and dates a
1462
+ view row a joined table's change reaches with the time of that change.
1463
+ Neither is modelled: broadcasts here arrive in order, and such a view row
1464
+ keeps its base row's `TIMESTAMP`, which only matters for which row a
1465
+ [moving view](#a-full-view-the-moving-view) evicts.
1412
1466
  - **`ROWS_COUNT` under a criteria-chosen index.** When a criteria makes the
1413
1467
  dataserver read through an index (see [Dataserver paging](#dataserver-paging)),
1414
1468
  GSF narrows the read to the range the criteria allows on that index
1415
1469
  (`IndexBuilderVisitor`), and `ROWS_COUNT` counts that range only. The mock
1416
1470
  counts the whole query, as it does for any other criteria.
1417
- - A MODIFY of a row still **waiting for `MORE_ROWS`** updates the waiting copy
1418
- and pushes nothing. GSF's client index doesn't know the row, so it pushes the
1419
- change as an `INSERT` with the full row (while the view has room, or always
1420
- with the moving view) and the later page skips it
1421
- (`ClientIndex.processModifyUpdate` → `putNewRowEntry`, v8.15.29).
1422
1471
  - **Criteria types** come from declared fields (and `fieldTypes` /
1423
1472
  `derivedTypes`) only. A field without one is read by its value, and a call
1424
1473
  or comparison it takes part in isn't type-checked: GSF would refuse
@@ -33,7 +33,7 @@
33
33
  // Deliberately NOT eval()/new Function() — this parses a small typed grammar
34
34
  // so a malformed or hostile criteria string can only fail to parse, never
35
35
  // execute arbitrary JS.
36
- import { CriteriaSyntaxError, tokenizeCriteria, UnsupportedCriteriaError, } from "./criteriaTokens.js";
36
+ import { CriteriaSyntaxError, decodeStringLiteral, tokenizeCriteria, UnsupportedCriteriaError, } from "./criteriaTokens.js";
37
37
  import * as gsf from "./gsfExpr.js";
38
38
  import { CriteriaEvaluationError, evaluationError } from "./gsfExpr.js";
39
39
  import { parseLegacyCriteria } from "./legacyCriteria.js";
@@ -72,7 +72,7 @@ const INT_MAX = 2_147_483_647;
72
72
  const NULL_POINTER = 'java.lang.NullPointerException';
73
73
  function parseLiteral(token) {
74
74
  if (/^['"]/.test(token)) {
75
- return { value: token.slice(1, -1).replace(/\\(.)/g, '$1'), type: 'String' };
75
+ return { value: decodeStringLiteral(token), type: 'String' };
76
76
  }
77
77
  if (/^-?\d+$/.test(token)) {
78
78
  const value = Number(token);
@@ -9,4 +9,5 @@ export interface CriteriaToken {
9
9
  offset: number;
10
10
  }
11
11
  export declare function tokenizeCriteria(input: string): CriteriaToken[];
12
+ export declare function decodeStringLiteral(token: string): string;
12
13
  export declare function parseGenesisDateTime(value: unknown): number | null;
@@ -33,6 +33,17 @@ export function tokenizeCriteria(input) {
33
33
  }
34
34
  return tokens;
35
35
  }
36
+ // Groovy's character escapes; any other escaped character stands for itself
37
+ // (\\, \', \", \$).
38
+ const ESCAPES = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r' };
39
+ const HEX = 16;
40
+ // The value of a quoted string token: its quotes off and its escapes decoded
41
+ // as Groovy decodes them, so '\n' is a line break and '\u0041' is A.
42
+ export function decodeStringLiteral(token) {
43
+ return token
44
+ .slice(1, -1)
45
+ .replace(/\\(?:u([0-9a-fA-F]{4})|([\s\S]))/g, (_, unicode, char) => unicode ? String.fromCharCode(parseInt(unicode, HEX)) : (ESCAPES[char] ?? char));
46
+ }
36
47
  const MS_DIGITS = 3; // '.5' means 500ms, not 5ms — right-pad to full precision
37
48
  // Genesis date/datetime values serialize as 'YYYYMMDD-HH:MM[:SS[.mmm]]'. Row
38
49
  // values may already be epoch millis (number) or an ISO string; anything
@@ -10,11 +10,11 @@
10
10
  // containsWordsStartingWithIgnoreCase, isNullOrBlank, notNullOrBlank,
11
11
  // dateIsAfter, dateIsBefore, dateTimeIsInRange — in the same false-not-throw
12
12
  // style.
13
- import { CriteriaSyntaxError, parseGenesisDateTime, tokenizeCriteria, UnsupportedCriteriaError, } from "./criteriaTokens.js";
13
+ import { CriteriaSyntaxError, decodeStringLiteral, parseGenesisDateTime, tokenizeCriteria, UnsupportedCriteriaError, } from "./criteriaTokens.js";
14
14
  import * as gsf from "./gsfExpr.js";
15
15
  function parseLiteral(token) {
16
16
  if (/^['"]/.test(token))
17
- return token.slice(1, -1).replace(/\\(.)/g, '$1');
17
+ return decodeStringLiteral(token);
18
18
  if (/^-?\d+(?:\.\d+)?$/.test(token))
19
19
  return Number(token);
20
20
  if (token === 'true')
@@ -1,11 +1,14 @@
1
1
  import type { Store } from '../db/store.ts';
2
- import type { Connection } from '../protocol/connection.ts';
2
+ import type { Connection, Subscription, ViewRow } from '../protocol/connection.ts';
3
3
  import type { GenesisMessage, MockServerConfig, QueryDef, Row } from '../types.ts';
4
4
  export declare function pagingOptions(details: Row): {
5
5
  maxRows: number;
6
6
  maxView: number;
7
+ movingView: boolean;
7
8
  };
8
9
  export declare function pendingKey(rowRef: unknown): string | undefined;
10
+ export declare function viewRow(row: Row, rowRef: unknown, source: Row): ViewRow;
11
+ export declare function waitForPage(subscription: Subscription, key: string, entry: ViewRow): void;
9
12
  export declare function rowEncoder(query: QueryDef, config: MockServerConfig, store: Store): ((row: Row) => Row) | undefined;
10
13
  export declare function handleDataLogon(message: GenesisMessage, connection: Connection, config: MockServerConfig, store: Store): void;
11
14
  export declare function handleMoreRows(message: GenesisMessage, connection: Connection, config: MockServerConfig): void;
@@ -18,11 +18,16 @@ function readCount(value, fallback) {
18
18
  }
19
19
  // MAX_ROWS is the page size, MAX_VIEW the most rows the client's view may
20
20
  // hold across all pages. 0 means "no limit" for either, and MAX_ROWS is
21
- // clamped to MAX_VIEW — both exactly as ClientOptions.parse does.
21
+ // clamped to MAX_VIEW. MOVING_VIEW defaults to true. A logon with a
22
+ // VIEW_NUMBER other than 0 asks for numbered pages: its view is one page,
23
+ // with no moving view. All of it as ClientOptions.parse does (v8.15.29).
22
24
  export function pagingOptions(details) {
23
- const maxView = readCount(details.MAX_VIEW, DEFAULT_MAX_VIEW) || Infinity;
24
- const maxRows = readCount(details.MAX_ROWS, DEFAULT_MAX_ROWS) || Infinity;
25
- return { maxRows: Math.min(maxRows, maxView), maxView };
25
+ const pageNumbered = readCount(details.VIEW_NUMBER, 0) !== 0;
26
+ const requestedRows = readCount(details.MAX_ROWS, DEFAULT_MAX_ROWS);
27
+ const maxView = (pageNumbered ? requestedRows : readCount(details.MAX_VIEW, DEFAULT_MAX_VIEW)) || Infinity;
28
+ const maxRows = requestedRows || Infinity;
29
+ const movingView = !pageNumbered && readFlag(details.MOVING_VIEW, true);
30
+ return { maxRows: Math.min(maxRows, maxView), maxView, movingView };
26
31
  }
27
32
  // The key a row is tracked under in Subscription.pending / held — undefined
28
33
  // for a row without a ROW_REF, which no live change could ever be matched
@@ -30,34 +35,68 @@ export function pagingOptions(details) {
30
35
  export function pendingKey(rowRef) {
31
36
  return rowRef === undefined || rowRef === null ? undefined : String(rowRef);
32
37
  }
38
+ // A row of the view, built from its stored (or view) row. `row` is its wire
39
+ // form: stamped as an INSERT while it waits, plain once held.
40
+ export function viewRow(row, rowRef, source) {
41
+ return { row, rowRef, source, timestamp: source.TIMESTAMP ?? source.RECORD_ID };
42
+ }
43
+ // What the client holds once a waiting row is sent: its values, no DETAILS.
44
+ function heldRow(waiting) {
45
+ const { DETAILS: _details, ...row } = waiting.row;
46
+ return { ...waiting, row };
47
+ }
33
48
  function buildPending(rows) {
34
49
  const pending = new Map();
35
- rows.forEach((row, index) => {
36
- const key = pendingKey(row.DETAILS?.ROW_REF);
50
+ rows.forEach((entry, index) => {
51
+ const key = pendingKey(entry.rowRef);
37
52
  // A row with no ROW_REF (or a duplicate one) still has to be delivered;
38
53
  // park it under a key no ROW_REF can produce rather than dropping it.
39
54
  // Live changes can't reach it there, which is as much as the client
40
55
  // could make of them: to it, rows sharing a ROW_REF are one row.
41
- pending.set(key === undefined || pending.has(key) ? `\u0000${index}` : key, row);
56
+ pending.set(key === undefined || pending.has(key) ? `\u0000${index}` : key, entry);
42
57
  });
43
58
  return pending;
44
59
  }
60
+ // A matched row the client doesn't hold and isn't sent now. It waits for a
61
+ // page when it sorts after the last row a page delivered, since the real
62
+ // NextRowsStrategy reads on from there; one that sorts before it is never
63
+ // read again. Pending stays in delivery order.
64
+ export function waitForPage(subscription, key, entry) {
65
+ const { pending, order, cursor } = subscription;
66
+ if (!pending)
67
+ return;
68
+ pending.delete(key);
69
+ if (!order) {
70
+ pending.set(key, entry);
71
+ return;
72
+ }
73
+ if (cursor && order(entry.source, cursor) <= 0)
74
+ return;
75
+ const waiting = [...pending];
76
+ const at = waiting.findIndex(([, other]) => order(entry.source, other.source) < 0);
77
+ waiting.splice(at === -1 ? waiting.length : at, 0, [key, entry]);
78
+ pending.clear();
79
+ for (const [waitingKey, other] of waiting)
80
+ pending.set(waitingKey, other);
81
+ }
45
82
  // The next page: up to MAX_ROWS waiting rows, but never more than the view
46
83
  // has room for. The real NextRowsStrategy reads while the client index is
47
84
  // below MAX_VIEW, so a full view gets an empty page, and a slot freed by a
48
- // DELETE is filled by the next row waiting. Delivered rows move to `held`.
85
+ // DELETE is filled by the next row waiting. Delivered rows move to `held`,
86
+ // and the last one is the new read position.
49
87
  function takePage(subscription) {
50
88
  const { pending, held } = subscription;
51
89
  if (!pending)
52
90
  return [];
53
91
  const room = Math.max(0, Math.min(subscription.maxRows ?? Infinity, (subscription.maxView ?? Infinity) - (held?.size ?? 0)));
54
92
  const page = [];
55
- for (const [key, row] of pending) {
93
+ for (const [key, entry] of pending) {
56
94
  if (page.length >= room)
57
95
  break;
58
- page.push(row);
96
+ page.push(entry.row);
59
97
  pending.delete(key);
60
- held?.add(key);
98
+ held?.set(key, heldRow(entry));
99
+ subscription.cursor = entry.source;
61
100
  }
62
101
  return page;
63
102
  }
@@ -120,6 +159,11 @@ function criteriaIndex(query, fields) {
120
159
  function readBoolean(value) {
121
160
  return value === true || (value !== undefined && value !== null && /^true$/i.test(String(value)));
122
161
  }
162
+ // A flag with a default, as GenesisSet.getBoolean(key, default) reads one:
163
+ // the default when it is absent, otherwise as readBoolean.
164
+ function readFlag(value, fallback) {
165
+ return value === undefined || value === null ? fallback : readBoolean(value);
166
+ }
123
167
  // How a query's rows go on the wire: each BIGDECIMAL column as a string with
124
168
  // its scale, as GSF's serializer writes a BigDecimal (db/values.ts).
125
169
  // undefined when the query has none — known without resolving the schema
@@ -177,7 +221,15 @@ export function handleDataLogon(message, connection, config, store) {
177
221
  const criteriaOptions = legacy
178
222
  ? { lenient: true }
179
223
  : { types: queryCriteriaTypes(query, config, store) };
224
+ const paging = pagingOptions(details);
180
225
  if (!legacy) {
226
+ // A moving view needs a MAX_VIEW to move in, and MOVING_VIEW defaults to
227
+ // true, so MAX_VIEW: 0 alone is refused. Checked before ORDER_BY
228
+ // (ConnectionManager.verifyClientOptions, v8.15.29).
229
+ if (paging.movingView && paging.maxView === Infinity) {
230
+ connection.reply(message, logonNack('INVALID_PARAMETER', "MOVING_VIEW can't be true if maxView is set to 0"));
231
+ return;
232
+ }
181
233
  // ORDER_BY names one of the query's own indexes (QueryDef.indexes). GSF
182
234
  // checks it before it looks at the criteria
183
235
  // (ConnectionManager.verifyClientOptions, v8.15.29).
@@ -252,14 +304,14 @@ export function handleDataLogon(message, connection, config, store) {
252
304
  : requestedFieldNames(details, query, exposed, config, store);
253
305
  // A BigDecimal goes out as a string with its column's scale (db/values.ts).
254
306
  const encode = legacy ? undefined : rowEncoder(query, config, store);
255
- const stampedRows = [];
307
+ const snapshotRows = [];
256
308
  for (const row of rows) {
257
309
  const permitted = permittedQueryRow(row, query.auth, user, fieldNames);
258
310
  if (!permitted)
259
311
  continue;
260
312
  const rowRef = getRowRef(row);
261
313
  const sent = dataserverRow(permitted, row, query.fields);
262
- stampedRows.push(stampRow(encode ? encode(sent) : sent, rowRef, 'INSERT', legacy));
314
+ snapshotRows.push(viewRow(stampRow(encode ? encode(sent) : sent, rowRef, 'INSERT', legacy), rowRef, row));
263
315
  }
264
316
  const subscription = {
265
317
  resourceName,
@@ -272,8 +324,8 @@ export function handleDataLogon(message, connection, config, store) {
272
324
  connection.subscribe(sourceRef, subscription);
273
325
  connection.reply(message, {
274
326
  MESSAGE_TYPE: MESSAGE_TYPE.QUERY_UPDATE,
275
- ROW: stampedRows,
276
- ROWS_COUNT: stampedRows.length,
327
+ ROW: snapshotRows.map((entry) => entry.row),
328
+ ROWS_COUNT: snapshotRows.length,
277
329
  SEQUENCE_ID: 1,
278
330
  MORE_ROWS: false,
279
331
  });
@@ -285,16 +337,16 @@ export function handleDataLogon(message, connection, config, store) {
285
337
  // which then answers every MORE_ROWS with an empty {MORE_ROWS: true} page.
286
338
  // A live INSERT is pushed straight away whatever the order, even when it
287
339
  // sorts among the rows still waiting, and a later page doesn't repeat it:
288
- // the real ClientIndex.processInsertUpdate sends it as soon as it arrives,
289
- // and NextRowsStrategy skips rows the client index already holds (GSF
290
- // v8.15.29). See server.ts trackClientView.
291
- const { maxRows, maxView } = pagingOptions(details);
340
+ // the real ClientIndex.processInsertUpdate sends it as soon as it arrives
341
+ // (a full view takes it only when it moves), and NextRowsStrategy skips
342
+ // rows the client index already holds (GSF v8.15.29). See server.ts
343
+ // viewUpdate.
292
344
  const tracked = {
293
345
  ...subscription,
294
- pending: buildPending(stampedRows),
295
- held: new Set(),
296
- maxRows,
297
- maxView,
346
+ pending: buildPending(snapshotRows),
347
+ held: new Map(),
348
+ ...paging,
349
+ ...(compare ? { order: compare } : {}),
298
350
  fieldNames,
299
351
  };
300
352
  const firstPage = takePage(tracked);
package/dist/index.d.ts CHANGED
@@ -4,4 +4,4 @@ export { Store } from './db/store.ts';
4
4
  export { RECORD_FIELDS, RECORD_ID, TIMESTAMP } from './db/identity.ts';
5
5
  export { ErrorCode, NackError, statusCodeFor, type ErrorCodeName, type GenesisErrorType, type NackErrorEntry, type NackErrorInput, type NackErrorOptions, } from './protocol/errors.ts';
6
6
  export { compileCriteria, type CriteriaOptions, filterByCriteria, type Predicate, } from './db/criteria.ts';
7
- export type { AntiJoinDef, AuthConfig, AuthUser, BroadcastFn, BroadcastTableChangeFn, CrudEventVerb, EventHandler, EventHandlerCtx, EventHandlerResult, EventSchemaOverride, FidelityMode, FieldDef, FieldMetadata, GeneratedFieldDef, GenesisFieldType, GenesisMessage, HttpRouteDef, IndexDef, JoinDef, JoinFieldLink, JoinLink, JoinType, JoinValueLink, MockServerConfig, OnMessageCtx, OnMessageHook, QueryDef, RequestingUser, RequestReplyDef, RequestReplyResolverCtx, ResourceAuthDef, ResourceItem, Row, SequenceFormat, SocketLike, SsoIdentityProvider, TableDef, ViewDef, ViewRowSources, } from './types.ts';
7
+ export type { AntiJoinDef, AuthConfig, AuthUser, BroadcastFn, BroadcastTableChangeFn, CrudEventVerb, EventHandler, EventHandlerCtx, EventHandlerResult, EventSchemaOverride, FidelityMode, FieldDef, FieldMetadata, GeneratedFieldDef, GenesisFieldType, GenesisMessage, HttpRouteDef, IndexDef, JoinDef, JoinFieldLink, JoinLink, JoinType, JoinValueLink, LiveModifyMode, MockServerConfig, OnMessageCtx, OnMessageHook, QueryDef, RequestingUser, RequestReplyDef, RequestReplyResolverCtx, ResourceAuthDef, ResourceItem, Row, SequenceFormat, SocketLike, SsoIdentityProvider, TableDef, ViewDef, ViewRowSources, } from './types.ts';
@@ -1,14 +1,23 @@
1
1
  import type { Predicate } from '../db/criteria.ts';
2
2
  import type { GenesisMessage, Row, SocketLike } from '../types.ts';
3
+ export interface ViewRow {
4
+ row: Row;
5
+ rowRef: unknown;
6
+ source: Row;
7
+ timestamp: unknown;
8
+ }
3
9
  export interface Subscription {
4
10
  resourceName: string;
5
11
  getRowRef: (row: Row) => unknown;
6
12
  predicate: Predicate;
7
13
  sequenceId: number;
8
- pending?: Map<string, Row>;
9
- held?: Set<string>;
14
+ pending?: Map<string, ViewRow>;
15
+ held?: Map<string, ViewRow>;
10
16
  maxRows?: number;
11
17
  maxView?: number;
18
+ movingView?: boolean;
19
+ order?: (a: Row, b: Row) => number;
20
+ cursor?: Row;
12
21
  fieldNames?: string[];
13
22
  encode?: (row: Row) => Row;
14
23
  }
@@ -1,2 +1,3 @@
1
- import type { MockServerConfig } from '../types.ts';
1
+ import type { LiveModifyMode, MockServerConfig } from '../types.ts';
2
2
  export declare function isLegacyFidelity(config: MockServerConfig): boolean;
3
+ export declare function liveModifyMode(config: MockServerConfig): LiveModifyMode;
@@ -4,3 +4,8 @@
4
4
  export function isLegacyFidelity(config) {
5
5
  return config.fidelity === 'legacy';
6
6
  }
7
+ // How a live MODIFY's row is written (see LiveModifyMode in types.ts): as
8
+ // GSF's diff unless the config asks for whole rows.
9
+ export function liveModifyMode(config) {
10
+ return config.liveModify ?? 'diff';
11
+ }