@genesislcap/foundation-comms 15.79.2-alpha-e9d30db797.0 → 15.80.0-FUI-2666.1

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 (64) hide show
  1. package/asconfig.json +15 -0
  2. package/assembly/scdb/README.md +74 -0
  3. package/assembly/scdb/bench.mjs +32 -0
  4. package/assembly/scdb/decoder.ts +217 -0
  5. package/assembly/scdb/decoder.wasm +0 -0
  6. package/assembly/scdb/inline-wasm-base64.mjs +24 -0
  7. package/dist/dts/connect/connect.d.ts +2 -0
  8. package/dist/dts/connect/connect.d.ts.map +1 -1
  9. package/dist/dts/connect/http.connect.d.ts +10 -0
  10. package/dist/dts/connect/http.connect.d.ts.map +1 -1
  11. package/dist/dts/connect/message.d.ts +18 -0
  12. package/dist/dts/connect/message.d.ts.map +1 -1
  13. package/dist/dts/connect/scdbStreamDecoder.d.ts +66 -0
  14. package/dist/dts/connect/scdbStreamDecoder.d.ts.map +1 -0
  15. package/dist/dts/connect/socket.d.ts +33 -0
  16. package/dist/dts/connect/socket.d.ts.map +1 -1
  17. package/dist/dts/connect/socket.types.d.ts +14 -0
  18. package/dist/dts/connect/socket.types.d.ts.map +1 -1
  19. package/dist/dts/datasource/datasource.d.ts.map +1 -1
  20. package/dist/dts/datasource/datasource.types.d.ts +8 -0
  21. package/dist/dts/datasource/datasource.types.d.ts.map +1 -1
  22. package/dist/dts/datasource/index.d.ts +1 -0
  23. package/dist/dts/datasource/index.d.ts.map +1 -1
  24. package/dist/dts/datasource/scdb/base64.d.ts +6 -0
  25. package/dist/dts/datasource/scdb/base64.d.ts.map +1 -0
  26. package/dist/dts/datasource/scdb/dictionaryHash.d.ts +40 -0
  27. package/dist/dts/datasource/scdb/dictionaryHash.d.ts.map +1 -0
  28. package/dist/dts/datasource/scdb/index.d.ts +6 -0
  29. package/dist/dts/datasource/scdb/index.d.ts.map +1 -0
  30. package/dist/dts/datasource/scdb/scdb-js-bench.d.mts +2 -0
  31. package/dist/dts/datasource/scdb/scdb-js-bench.d.mts.map +1 -0
  32. package/dist/dts/datasource/scdb/scdbDecode.d.ts +24 -0
  33. package/dist/dts/datasource/scdb/scdbDecode.d.ts.map +1 -0
  34. package/dist/dts/datasource/scdb/scdbDecoder.d.ts +42 -0
  35. package/dist/dts/datasource/scdb/scdbDecoder.d.ts.map +1 -0
  36. package/dist/dts/datasource/scdb/scdbWasmDecoder.d.ts +27 -0
  37. package/dist/dts/datasource/scdb/scdbWasmDecoder.d.ts.map +1 -0
  38. package/dist/dts/datasource/scdb/scdbjDecoder.d.ts +35 -0
  39. package/dist/dts/datasource/scdb/scdbjDecoder.d.ts.map +1 -0
  40. package/dist/dts/datasource/scdb/wasm/decoder.wasm.base64.d.ts +7 -0
  41. package/dist/dts/datasource/scdb/wasm/decoder.wasm.base64.d.ts.map +1 -0
  42. package/dist/dts/testing/mocks/connect/socket.d.ts +1 -0
  43. package/dist/dts/testing/mocks/connect/socket.d.ts.map +1 -1
  44. package/dist/esm/connect/connect.js +22 -3
  45. package/dist/esm/connect/http.connect.js +33 -1
  46. package/dist/esm/connect/message.js +3 -1
  47. package/dist/esm/connect/scdbStreamDecoder.js +160 -0
  48. package/dist/esm/connect/socket.js +132 -2
  49. package/dist/esm/datasource/datasource.js +3 -0
  50. package/dist/esm/datasource/index.js +1 -0
  51. package/dist/esm/datasource/scdb/base64.js +17 -0
  52. package/dist/esm/datasource/scdb/dictionaryHash.js +45 -0
  53. package/dist/esm/datasource/scdb/index.js +5 -0
  54. package/dist/esm/datasource/scdb/scdb-golden-v1.json +15 -0
  55. package/dist/esm/datasource/scdb/scdb-js-bench.mjs +461 -0
  56. package/dist/esm/datasource/scdb/scdbDecode.js +67 -0
  57. package/dist/esm/datasource/scdb/scdbDecoder.js +279 -0
  58. package/dist/esm/datasource/scdb/scdbWasmDecoder.js +213 -0
  59. package/dist/esm/datasource/scdb/scdbjDecoder.js +60 -0
  60. package/dist/esm/datasource/scdb/wasm/decoder.wasm.base64.js +6 -0
  61. package/dist/esm/testing/mocks/connect/socket.js +3 -0
  62. package/dist/foundation-comms.api.json +1453 -8
  63. package/dist/foundation-comms.d.ts +261 -0
  64. package/package.json +14 -12
@@ -0,0 +1,160 @@
1
+ import { decodeColumnarQueryUpdate, decodeColumnarReply, dictionaryFromMetadata, dictionaryHash, } from '../datasource/scdb';
2
+ import { logger } from '../utils';
3
+ /** Req/rep requests carry the resource name in their `REQ_`-prefixed `MESSAGE_TYPE`. */
4
+ export function resourceNameOf(sent) {
5
+ var _a;
6
+ const datasourceName = (_a = sent === null || sent === void 0 ? void 0 : sent.DETAILS) === null || _a === void 0 ? void 0 : _a.DATASOURCE_NAME;
7
+ if (datasourceName)
8
+ return datasourceName;
9
+ const messageType = sent === null || sent === void 0 ? void 0 : sent.MESSAGE_TYPE;
10
+ if (typeof messageType === 'string' && messageType.startsWith('REQ_')) {
11
+ return messageType.slice('REQ_'.length);
12
+ }
13
+ return undefined;
14
+ }
15
+ /**
16
+ * Socket-side adapter that makes the SCDB columnar encodings transparent to all stream consumers.
17
+ *
18
+ * The column dictionary is **derived from resource metadata** (the same metadata the client already
19
+ * holds in `MetaCache`), NOT sent on the wire — for BOTH dataserver and req/rep. The server only
20
+ * stamps the payload with a small `DICT_HASH`; this adapter derives the dictionary from metadata,
21
+ * validates it against that hash, and decodes. The dictionary is resolved **per message from
22
+ * metadata** (not bound to the `LOGON_ACK`/`SOURCE_REF`).
23
+ *
24
+ * - Dataserver: `QUERY_UPDATE` carries no hash, so the expected hash is captured once from
25
+ * `LOGON_ACK` (which the socket consumes and does NOT forward), keyed by resource; the dictionary
26
+ * itself is still derived from metadata per update and decoded in place into `ROW`.
27
+ * - Req/rep: each reply carries its own `DICT_HASH`; dictionary derived from metadata and decoded
28
+ * into `REPLY`.
29
+ *
30
+ * The server sends a negotiated batch only in columnar form, so a message that cannot be decoded is
31
+ * lost.
32
+ *
33
+ * Memory: validated dictionaries are cached by their content hash, so all subscriptions/resources
34
+ * sharing a schema share one `string[]`, and a schema change (new hash) naturally re-derives.
35
+ */
36
+ export class ScdbStreamDecoder {
37
+ constructor(metaCache) {
38
+ this.metaCache = metaCache;
39
+ /** Content hash -> validated dictionary. Shared across every resource/subscription with that schema. */
40
+ this.byHash = new Map();
41
+ /** Dataserver resource -> expected DICT_HASH captured from its LOGON_ACK (QUERY_UPDATE has none). */
42
+ this.expectedHashByResource = new Map();
43
+ /** Resources with an in-flight metadata refresh, to avoid issuing duplicate META_REQUESTs. */
44
+ this.refreshing = new Set();
45
+ }
46
+ /** Optionally supply the WASM decoder for the binary `SCDB_V1` fast-path (else pure-JS is used). */
47
+ setWasm(wasm) {
48
+ this.wasm = wasm;
49
+ }
50
+ /** Wire the metadata-refresh hook (host supplies a force-refresh, e.g. `getMetadata(r, false)`). */
51
+ setMetadataRefresher(refresher) {
52
+ this.metadataRefresher = refresher;
53
+ }
54
+ /** Without cached metadata the columnar answer could not be decoded, so row mode is requested. */
55
+ prepareRequest(message) {
56
+ const details = message.DETAILS;
57
+ if (!(details === null || details === void 0 ? void 0 : details.ENCODING))
58
+ return;
59
+ const resourceName = resourceNameOf(message);
60
+ if (resourceName && this.metaCache.hasMetadataFor(resourceName))
61
+ return;
62
+ const withoutEncoding = Object.assign({}, details);
63
+ delete withoutEncoding.ENCODING;
64
+ message.DETAILS = withoutEncoding;
65
+ if (resourceName)
66
+ this.requestRefresh(resourceName);
67
+ }
68
+ /**
69
+ * Capture the dataserver resource's expected `DICT_HASH` from a `LOGON_ACK` (call before it is
70
+ * dropped) and pre-warm the dictionary from metadata. No-op for row-mode logons.
71
+ */
72
+ onLogonAck(msg, resourceName) {
73
+ if (!(msg === null || msg === void 0 ? void 0 : msg.ENCODING) || !resourceName || msg.DICT_HASH == null)
74
+ return;
75
+ this.expectedHashByResource.set(resourceName, msg.DICT_HASH);
76
+ // Pre-warm (and kick off a refresh now if the cached metadata is stale).
77
+ this.dictionaryFor(resourceName, msg.DICT_HASH);
78
+ }
79
+ /**
80
+ * Decodes a columnar message in place: dataserver `QUERY_UPDATE` into `msg.ROW` (expected hash from
81
+ * the resource's LOGON_ACK), req/rep reply into `msg.REPLY` (hash on the reply). No-op for row-mode
82
+ * or already decoded messages. Throws when the message cannot be decoded.
83
+ */
84
+ onMessage(msg, resourceName) {
85
+ if (!msg || !msg.ENCODING || msg.ROW || msg.REPLY)
86
+ return;
87
+ const isQueryUpdate = msg.MESSAGE_TYPE === 'QUERY_UPDATE';
88
+ const expectedHash = isQueryUpdate
89
+ ? resourceName && this.expectedHashByResource.get(resourceName)
90
+ : msg.DICT_HASH;
91
+ const dictionary = this.dictionaryFor(resourceName, expectedHash);
92
+ if (!dictionary) {
93
+ throw new Error(`Cannot decode ${msg.ENCODING} ${msg.MESSAGE_TYPE} for '${resourceName}': ` +
94
+ `no column dictionary matching DICT_HASH ${expectedHash}`);
95
+ }
96
+ if (isQueryUpdate)
97
+ msg.ROW = this.decodeQueryUpdate(msg, dictionary);
98
+ else
99
+ msg.REPLY = decodeColumnarReply(msg, dictionary);
100
+ }
101
+ decodeQueryUpdate(msg, dictionary) {
102
+ if (this.wasm) {
103
+ try {
104
+ return decodeColumnarQueryUpdate(msg, dictionary, this.wasm);
105
+ }
106
+ catch (e) {
107
+ // Throws again when the payload itself is bad, which is not a reason to drop the WASM decoder.
108
+ const rows = decodeColumnarQueryUpdate(msg, dictionary);
109
+ logger.warn('SCDB WASM decode failed, using the pure-JS decoder from now on', e);
110
+ this.wasm = undefined;
111
+ return rows;
112
+ }
113
+ }
114
+ return decodeColumnarQueryUpdate(msg, dictionary);
115
+ }
116
+ clear() {
117
+ this.byHash.clear();
118
+ this.expectedHashByResource.clear();
119
+ this.refreshing.clear();
120
+ }
121
+ /**
122
+ * Ordered dictionary for a resource, derived from cached metadata and validated against the
123
+ * server's `DICT_HASH`. Missing or mismatching metadata is refreshed for later requests.
124
+ * Validated results are cached by content hash (never negatives).
125
+ */
126
+ dictionaryFor(resourceName, expectedHash) {
127
+ if (!resourceName)
128
+ return undefined;
129
+ if (expectedHash == null)
130
+ return undefined;
131
+ const cached = this.byHash.get(expectedHash);
132
+ if (cached)
133
+ return cached;
134
+ if (!this.metaCache.hasMetadataFor(resourceName)) {
135
+ this.requestRefresh(resourceName);
136
+ return undefined;
137
+ }
138
+ const names = dictionaryFromMetadata(this.metaCache.getMetadataFor(resourceName));
139
+ if (!names.length)
140
+ return undefined;
141
+ const clientHash = dictionaryHash(names);
142
+ if (clientHash !== expectedHash) {
143
+ logger.warn(`SCDB dictionary hash mismatch for '${resourceName}' (server=${expectedHash} ` +
144
+ `client=${clientHash}); refreshing metadata`);
145
+ this.requestRefresh(resourceName);
146
+ return undefined;
147
+ }
148
+ this.byHash.set(expectedHash, names);
149
+ return names;
150
+ }
151
+ /** Fire-and-forget metadata refresh, deduped per resource while one is in flight. */
152
+ requestRefresh(resourceName) {
153
+ if (!this.metadataRefresher || this.refreshing.has(resourceName))
154
+ return;
155
+ this.refreshing.add(resourceName);
156
+ Promise.resolve(this.metadataRefresher(resourceName))
157
+ .catch(() => undefined)
158
+ .finally(() => this.refreshing.delete(resourceName));
159
+ }
160
+ }
@@ -6,6 +6,8 @@ import { DI } from '@microsoft/fast-foundation';
6
6
  import { from, Observable, of, Subject, Subscription, throwError } from 'rxjs';
7
7
  import { exhaustMap, filter, map, switchMap, takeWhile } from 'rxjs/operators';
8
8
  import { WebSocketSubject } from 'rxjs/webSocket';
9
+ import { getDefaultScdbWasm } from '../datasource/scdb';
10
+ import { MetaCache } from '../metadata';
9
11
  import { Session } from '../session';
10
12
  import { logger } from '../utils';
11
13
  import { withErrorCode } from '../utils/error-code';
@@ -13,6 +15,7 @@ import { ConnectConfig } from './connect.types';
13
15
  import { Http } from './http';
14
16
  import { EventMessageType, MessageBuilder, MessageType, } from './message';
15
17
  import { exponentialScheduler, linearScheduler, MAX_RECONNECT_ATTEMPTS, retryInterval, SocketReconnectStrategy, } from './reconnectStrategy';
18
+ import { resourceNameOf, ScdbStreamDecoder } from './scdbStreamDecoder';
16
19
  import { onOtherTabReauthComplete, SessionRefreshResult, tryRefreshSession, waitForOtherTabReauth, } from './sessionRefresh';
17
20
  import { SocketStatus } from './socket.status';
18
21
  import { Ticker } from './ticker';
@@ -135,10 +138,76 @@ let DefaultSocket = class DefaultSocket {
135
138
  this.defaultInterval = 10000;
136
139
  this.secondsMultiplier = 1000;
137
140
  this.sessionCheckTimeout = 10000;
141
+ this.scdbWasmRequested = false;
138
142
  this.heartbeatIsEnabled = true;
139
143
  this.heartbeatInterval = this.defaultInterval;
144
+ this.pageLifecycleBound = false;
145
+ /** True after freeze/bfcache until resume/pageshow recovery runs. */
146
+ this.suspendedByPageLifecycle = false;
140
147
  this.socketMessages = () => this.wsMessages;
141
148
  }
149
+ /**
150
+ * Chrome terminates WebSockets when a tab is frozen or put in the back-forward cache.
151
+ * Mark disconnected before freeze so datasources observe `false`, then on restore drop
152
+ * stale stream handlers and reconnect (replaying old DATASERVER logons leaves grids stale).
153
+ */
154
+ ensurePageLifecycleListeners() {
155
+ if (this.pageLifecycleBound ||
156
+ typeof window === 'undefined' ||
157
+ typeof document === 'undefined') {
158
+ return;
159
+ }
160
+ this.pageLifecycleBound = true;
161
+ const markSuspended = () => {
162
+ this.suspendedByPageLifecycle = true;
163
+ if (this.status.isConnected) {
164
+ this.status.isConnected = false;
165
+ }
166
+ };
167
+ const recover = () => {
168
+ if (!this.suspendedByPageLifecycle && this.isConnected) {
169
+ return;
170
+ }
171
+ this.recoverAfterPageLifecycle();
172
+ };
173
+ document.addEventListener('freeze', markSuspended);
174
+ document.addEventListener('resume', recover);
175
+ window.addEventListener('pagehide', (event) => {
176
+ if (event.persisted) {
177
+ markSuspended();
178
+ }
179
+ });
180
+ window.addEventListener('pageshow', (event) => {
181
+ if (event.persisted || this.suspendedByPageLifecycle) {
182
+ recover();
183
+ }
184
+ });
185
+ }
186
+ recoverAfterPageLifecycle() {
187
+ this.suspendedByPageLifecycle = false;
188
+ // Stale subscription handlers cannot be resumed after bfcache/freeze.
189
+ this.cleanMessages();
190
+ if (this.isConnected) {
191
+ // Socket already looks up — pulse disconnect so datasources reload streams.
192
+ this.status.isConnected = false;
193
+ DOM.queueUpdate(() => {
194
+ if (!this.status.isConnected) {
195
+ this.status.isConnected = true;
196
+ }
197
+ });
198
+ return;
199
+ }
200
+ if (this.isReconnecting || !this.url) {
201
+ return;
202
+ }
203
+ this.reconnect();
204
+ }
205
+ /** Makes SCDB columnar payloads transparent (no-op unless an encoding was negotiated). */
206
+ get scdbDecoder() {
207
+ var _a;
208
+ (_a = this._scdbDecoder) !== null && _a !== void 0 ? _a : (this._scdbDecoder = new ScdbStreamDecoder(this.metaCache));
209
+ return this._scdbDecoder;
210
+ }
142
211
  get heartbeatLoggingIsEnabled() {
143
212
  var _a, _b;
144
213
  return (_b = (_a = this.connectOptions) === null || _a === void 0 ? void 0 : _a.enableHeartbeatLogging) !== null && _b !== void 0 ? _b : false;
@@ -148,11 +217,16 @@ let DefaultSocket = class DefaultSocket {
148
217
  return (_b = (_a = this.connectOptions) === null || _a === void 0 ? void 0 : _a.enableMessageLogging) !== null && _b !== void 0 ? _b : false;
149
218
  }
150
219
  connect(host = GENESIS_SOCKET_URL, connectOptions, reconnectOptions) {
151
- var _a;
220
+ var _a, _b;
152
221
  this.url = host;
153
222
  this.connectOptions = connectOptions !== null && connectOptions !== void 0 ? connectOptions : this.config.connect;
154
223
  this.reconnectOptions = reconnectOptions !== null && reconnectOptions !== void 0 ? reconnectOptions : this.config.reconnect;
155
- if (!((_a = this.config.isWebSocketExpression) === null || _a === void 0 ? void 0 : _a.test(this.host))) {
224
+ this.ensurePageLifecycleListeners();
225
+ // Pre-warm the WASM fast-path when binary is the app-wide default; per-datasource opt-ins warm it
226
+ // lazily on the first SCDB_V1 payload (see the receive path).
227
+ if (((_a = this.connectOptions) === null || _a === void 0 ? void 0 : _a.dataserverEncoding) === 'SCDB_V1')
228
+ this.ensureScdbWasm();
229
+ if (!((_b = this.config.isWebSocketExpression) === null || _b === void 0 ? void 0 : _b.test(this.host))) {
156
230
  logger.error(`Specified host (${this.host}) is not valid WebSocket url. Connection will not proceed.`);
157
231
  logger.warn(`Make sure the host url starts with wss:// or ws://`);
158
232
  return;
@@ -190,6 +264,7 @@ let DefaultSocket = class DefaultSocket {
190
264
  deserializer: (event) => this.serializer.deserialize(event),
191
265
  });
192
266
  const onNextMessage = (receivedMessage) => __awaiter(this, void 0, void 0, function* () {
267
+ var _a;
193
268
  const responseMessageReceivedLog = `Response Message received for SourceRef: ${receivedMessage.SOURCE_REF} | MessageType: ${receivedMessage.MESSAGE_TYPE}`;
194
269
  this.logMessageTypeFlow(receivedMessage.MESSAGE_TYPE, logger.info, responseMessageReceivedLog);
195
270
  const { SOURCE_REF, MESSAGE_TYPE } = receivedMessage;
@@ -214,6 +289,8 @@ let DefaultSocket = class DefaultSocket {
214
289
  return;
215
290
  }
216
291
  case MessageType.LOGON_ACK:
292
+ // Resolve the SCDB column dictionary (from metadata) before LOGON_ACK is dropped.
293
+ this.scdbDecoder.onLogonAck(receivedMessage, resourceNameOf(messageHandler.sentMessage));
217
294
  return;
218
295
  case MessageType.LOGOFF_ACK: {
219
296
  break;
@@ -230,6 +307,30 @@ let DefaultSocket = class DefaultSocket {
230
307
  break;
231
308
  }
232
309
  }
310
+ // A binary payload lazily warms the WASM fast-path (covers per-datasource opt-ins too).
311
+ if ((receivedMessage === null || receivedMessage === void 0 ? void 0 : receivedMessage.ENCODING) === 'SCDB_V1')
312
+ this.ensureScdbWasm();
313
+ try {
314
+ this.scdbDecoder.onMessage(receivedMessage, resourceNameOf(messageHandler.sentMessage));
315
+ }
316
+ catch (error) {
317
+ logger.error(`Failed to decode ${MESSAGE_TYPE} for SourceRef: ${SOURCE_REF}`, error);
318
+ // The server will not resend this batch, so the stream stops being handled.
319
+ const nack = {
320
+ SOURCE_REF,
321
+ MESSAGE_TYPE: MessageType.MSG_NACK,
322
+ ERROR: [
323
+ { CODE: 'SCDB_DECODE_FAILED', TEXT: String((_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : error) },
324
+ ],
325
+ };
326
+ messageHandler.onReceivedError.call(this, {
327
+ receivedMessage: nack,
328
+ sentMessage: messageHandler.sentMessage,
329
+ });
330
+ this.removeMessageHandler(SOURCE_REF);
331
+ this.wsMessages.next(nack);
332
+ return;
333
+ }
233
334
  if (nacked) {
234
335
  messageHandler.onReceivedError.call(this, {
235
336
  receivedMessage,
@@ -448,6 +549,7 @@ let DefaultSocket = class DefaultSocket {
448
549
  this.wsMessages && this.wsMessages.complete();
449
550
  this.wsMessages = new SocketSubject();
450
551
  this.wsMessageHandlers = new Map();
552
+ this.scdbDecoder.clear();
451
553
  }
452
554
  send(message, needsHandling = true) {
453
555
  if (!this.isConnected) {
@@ -455,6 +557,7 @@ let DefaultSocket = class DefaultSocket {
455
557
  }
456
558
  const sendingMessasgeLog = `Sending Message for SourceRef: ${message.SOURCE_REF} | MessageType: ${message.MESSAGE_TYPE}`;
457
559
  this.logMessageTypeFlow(message.MESSAGE_TYPE, logger.info, sendingMessasgeLog);
560
+ this.scdbDecoder.prepareRequest(message);
458
561
  return new Promise((resolve, reject) => {
459
562
  const onMessage = (msg) => {
460
563
  resolve(msg);
@@ -474,6 +577,7 @@ let DefaultSocket = class DefaultSocket {
474
577
  }
475
578
  const sendingMessageLog = `Sending Message (stream) for SourceRef: ${message.SOURCE_REF} | MessageType: ${message.MESSAGE_TYPE}`;
476
579
  this.logMessageTypeFlow(message.MESSAGE_TYPE, logger.info, sendingMessageLog);
580
+ this.scdbDecoder.prepareRequest(message);
477
581
  this.setMessageHandler(message, onMessage, onError, true);
478
582
  /**
479
583
  * We need to queue these outgoing messages to allow the consumers to subscribe in time. We should review the entire
@@ -513,6 +617,7 @@ let DefaultSocket = class DefaultSocket {
513
617
  }
514
618
  const sendingMessageLog = `Sending Message (stream) for SourceRef: ${message.SOURCE_REF} | MessageType: ${message.MESSAGE_TYPE}`;
515
619
  this.logMessageTypeFlow(message.MESSAGE_TYPE, logger.info, sendingMessageLog);
620
+ this.scdbDecoder.prepareRequest(message);
516
621
  this.setMessageHandler(message, onMessage, onError, true);
517
622
  this.websocket.next(message);
518
623
  return this.wsMessages.pipe(filter((msg) => msg.SOURCE_REF === message.SOURCE_REF));
@@ -528,6 +633,28 @@ let DefaultSocket = class DefaultSocket {
528
633
  removeMessageHandler(sourceRef) {
529
634
  this.wsMessageHandlers.delete(sourceRef);
530
635
  }
636
+ /**
637
+ * Wires the SCDB decoder's metadata-refresh hook, used to fetch a resource's missing or stale
638
+ * metadata. The host passes a force-refresh, e.g. `Connect.getMetadata(resource, false)`.
639
+ */
640
+ setScdbMetadataRefresher(refresher) {
641
+ this.scdbDecoder.setMetadataRefresher(refresher);
642
+ }
643
+ /**
644
+ * Loads the bundled WASM decoder for the `SCDB_V1` binary encoding once (lazy, idempotent). Called
645
+ * eagerly when the app-wide `dataserverEncoding` is binary, and on demand the first time a binary
646
+ * payload is seen (so a per-datasource/grid `encoding: 'SCDB_V1'` also gets the fast-path, not just
647
+ * the app-wide opt-in). On any failure (no WebAssembly, CSP, SSR) we silently keep the pure-JS
648
+ * decoder — output is identical.
649
+ */
650
+ ensureScdbWasm() {
651
+ if (this.scdbWasmRequested)
652
+ return;
653
+ this.scdbWasmRequested = true;
654
+ getDefaultScdbWasm()
655
+ .then((wasm) => this.scdbDecoder.setWasm(wasm))
656
+ .catch((err) => logger.warn('SCDB WASM decoder unavailable, using pure-JS decoder', err));
657
+ }
531
658
  getMessageHandler(sourceRef, messageType) {
532
659
  const gettingMessageHandlerLog = `Getting Message Handler for SourceRef: ${sourceRef} | MessageType: ${messageType}`;
533
660
  this.logMessageTypeFlow(messageType, logger.debug, gettingMessageHandlerLog);
@@ -564,6 +691,9 @@ __decorate([
564
691
  __decorate([
565
692
  Http
566
693
  ], DefaultSocket.prototype, "http", void 0);
694
+ __decorate([
695
+ MetaCache
696
+ ], DefaultSocket.prototype, "metaCache", void 0);
567
697
  __decorate([
568
698
  observable
569
699
  ], DefaultSocket.prototype, "heartbeatIsEnabled", void 0);
@@ -170,6 +170,7 @@ let DefaultDatasource = class DefaultDatasource {
170
170
  MAX_VIEW: this.options.maxView,
171
171
  MOVING_VIEW: this.options.movingView,
172
172
  REVERSE: this.options.reverse,
173
+ ENCODING: this.options.encoding,
173
174
  // REQUEST_SERVER only
174
175
  DISABLE_POLLING: this.options.disablePolling, // component-level only
175
176
  OFFSET: this.options.offset,
@@ -192,6 +193,7 @@ let DefaultDatasource = class DefaultDatasource {
192
193
  MOVING_VIEW: this.allResourceParams.MOVING_VIEW,
193
194
  ORDER_BY: this.allResourceParams.ORDER_BY,
194
195
  REVERSE: this.allResourceParams.REVERSE,
196
+ ENCODING: this.allResourceParams.ENCODING,
195
197
  };
196
198
  }
197
199
  /**
@@ -206,6 +208,7 @@ let DefaultDatasource = class DefaultDatasource {
206
208
  OFFSET: DETAILS.OFFSET,
207
209
  ORDER_BY: DETAILS.ORDER_BY,
208
210
  VIEW_NUMBER: DETAILS.VIEW_NUMBER,
211
+ ENCODING: DETAILS.ENCODING,
209
212
  },
210
213
  REQUEST: this.criteriaOnlyRequest ? {} : (REQUEST !== null && REQUEST !== void 0 ? REQUEST : this.buildRequestFields()),
211
214
  };
@@ -7,3 +7,4 @@ export * from './datasource';
7
7
  export * from './datasource.types';
8
8
  export * from './entityDatasource';
9
9
  export * from './normaliseCriteria';
10
+ export * from './scdb';
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Decodes a base64 string to bytes in both browser (`atob`) and Node/SSR (`Buffer`) runtimes.
3
+ * The SCDB `RBUF` payload (over JSON transports) and the inlined wasm module both arrive as base64.
4
+ */
5
+ export function base64ToBytes(b64) {
6
+ var _a;
7
+ if (typeof atob === 'function') {
8
+ const bin = atob(b64);
9
+ const out = new Uint8Array(bin.length);
10
+ for (let i = 0; i < bin.length; i += 1)
11
+ out[i] = bin.charCodeAt(i);
12
+ return out;
13
+ }
14
+ // Node / SSR (avoids a hard @types/node dependency)
15
+ const buf = (_a = globalThis.Buffer) === null || _a === void 0 ? void 0 : _a.from(b64, 'base64');
16
+ return buf ? Uint8Array.from(buf) : new Uint8Array(0);
17
+ }
@@ -0,0 +1,45 @@
1
+ /* oxlint-disable no-magic-numbers, no-plusplus -- FNV-1a hashing uses fixed prime/offset constants and byte loops */
2
+ /**
3
+ * Dictionary derivation + fingerprinting for the metadata-driven dictionary mechanism.
4
+ *
5
+ * The server no longer ships the column dictionary; instead the client derives it from the resource
6
+ * metadata it already holds (`id = index` into the ordered field list) and validates it against a
7
+ * small hash the server sends with the columnar payload. A columnar message that fails validation
8
+ * is not decoded.
9
+ */
10
+ /**
11
+ * FNV-1a 32-bit hash of the field names joined by '\n', as lowercase 8-char hex. MUST match the
12
+ * Kotlin `ColumnDictionary.contentHash` in genesis-columnar (cross-language vector:
13
+ * ['QUANTITY','PRICE','SYMBOL'] -> '40e6db4f').
14
+ *
15
+ * Hashes UTF-16 code units (`charCodeAt`), matching Kotlin's `Char.code` — NOT the UTF-8 bytes used for
16
+ * on-wire strings. Field names are ASCII in practice so the two coincide; keep both ends on UTF-16 units
17
+ * (do not switch to UTF-8 bytes) or a non-ASCII field name would hash differently across languages.
18
+ */
19
+ export function dictionaryHash(fieldNames) {
20
+ let h = 0x811c9dc5;
21
+ const joined = fieldNames.join('\n');
22
+ for (let i = 0; i < joined.length; i++) {
23
+ h ^= joined.charCodeAt(i);
24
+ h = Math.imul(h, 0x01000193); // 32-bit FNV prime multiply
25
+ }
26
+ return (h >>> 0).toString(16).padStart(8, '0');
27
+ }
28
+ /**
29
+ * Ordered field-name list (the SCDB dictionary) for a resource, from its metadata. The order MUST
30
+ * match the server's, which derives the dictionary per resource type: a DATASERVER hashes its `FIELD`
31
+ * list, a REQUEST_SERVER its `REPLY_FIELD` (⇒ `REPLY.FIELD`) list. Selecting by `TYPE` — rather than
32
+ * "first non-null" — matters because a metadata object can legitimately carry BOTH `FIELD` and
33
+ * `REPLY_FIELD`; picking the wrong one yields a hash that never matches the server's `DICT_HASH`, so
34
+ * no columnar message for that resource can be decoded. Falls back to a lenient scan for unknown types.
35
+ */
36
+ export function dictionaryFromMetadata(metadata) {
37
+ var _a, _b, _c, _d, _e;
38
+ const replyFields = (_a = metadata.REPLY_FIELD) !== null && _a !== void 0 ? _a : (_b = metadata.REPLY) === null || _b === void 0 ? void 0 : _b.FIELD;
39
+ const fields = metadata.TYPE === 'REQUEST_SERVER'
40
+ ? (replyFields !== null && replyFields !== void 0 ? replyFields : [])
41
+ : metadata.TYPE === 'DATASERVER'
42
+ ? ((_c = metadata.FIELD) !== null && _c !== void 0 ? _c : [])
43
+ : ((_e = (_d = metadata.FIELD) !== null && _d !== void 0 ? _d : replyFields) !== null && _e !== void 0 ? _e : []);
44
+ return fields.map((f) => f.NAME);
45
+ }
@@ -0,0 +1,5 @@
1
+ export * from './dictionaryHash';
2
+ export * from './scdbDecoder';
3
+ export * from './scdbjDecoder';
4
+ export * from './scdbWasmDecoder';
5
+ export * from './scdbDecode';
@@ -0,0 +1,15 @@
1
+ {
2
+ "format": "scdb-v1",
3
+ "comment": "Shared cross-language conformance fixture for the SCDB v1 wire format. The canonical input batches are defined in prose in docs/scdb-v1.md and constructed identically in the Kotlin (ScdbConformanceTest) and JavaScript (foundation-ui) test suites. Each entry pins the exact encoded bytes (lowercase hex). Both ends assert encode(case)==hex and decode(hex)==case. Do not edit by hand; regenerate if the format changes and update both decoders.",
4
+ "vectors": {
5
+ "mixed-tristate": "53434431020301310132103930303731393932353437343039393301030000000101c8010100000303402400000000000009020000040005564f442e4c",
6
+ "string-dict": "5343443102030131013201330101030101020641435449564506434c4f534544010102",
7
+ "deletes-only": "534344310202013501360200",
8
+ "empty": "53434431000000",
9
+ "delta-longs": "53434431020301310132013300010002010280c0a8ca9a3a0a0c",
10
+ "delta-longs-highbit": "534344310203013101320133000100020102faffffffffffffffff010202",
11
+ "delta-longs-straddle-2p53": "534344310203013101320133000100020102feffffffffffff1f0404",
12
+ "delta-datetimes": "53434431020301310132013300010002010880a0abfef962d00fb817",
13
+ "delta-longs-negative": "53434431020301310132013300010002010280a8d6b90763ac02"
14
+ }
15
+ }