@genesislcap/mock-server 15.7.3-alpha-277c463.0 → 15.7.3-alpha-94532c4.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
@@ -97,18 +97,20 @@ CI/local dev. Leave it unset to require an explicit `EVENT_LOGIN_AUTH` POST
97
97
  (validated against `config.auth.users`, same as the WS flow) before
98
98
  `event-login-details` will succeed on a later reload.
99
99
 
100
- WS data traffic (`DATA_LOGON`, `REQ_*`, `META_REQUEST`, `JSON_SCHEMA_REQUEST`,
101
- commit events) requires authentication, like the real server: either the
102
- connection logged in over WS, or the message carries a `SESSION_AUTH_TOKEN`
103
- this server issued over **either** transport — foundation-comms stamps the
104
- stored token onto every outgoing message, which is exactly how a client that
105
- logged in over HTTP (including via `httpAutoLogin`) authenticates its WS
106
- traffic. The WS token-refresh login (`EVENT_LOGIN_AUTH` with only
100
+ An **opt-in** auth gate (`config.auth.requireAuth: true`) rejects WS data
101
+ traffic (`DATA_LOGON`, `REQ_*`, `META_REQUEST`, `JSON_SCHEMA_REQUEST`, commit
102
+ events) with a `NOT_LOGGED_ON` error until the connection logs in over WS or
103
+ the message carries a `SESSION_AUTH_TOKEN` this server issued over **either**
104
+ transport. The WS token-refresh login (`EVENT_LOGIN_AUTH` with only
107
105
  `DETAILS.REFRESH_AUTH_TOKEN`, no credentials — foundation-comms'
108
- `createRefreshTokenMessage`) is honored the same way. Unauthenticated data
109
- messages get a `NOT_LOGGED_ON` error shaped like the target handler's own
110
- error replies. Set `config.auth.requireAuth: false` to switch the gate off
111
- and accept everything.
106
+ `createRefreshTokenMessage`) is honored via the same token registry.
107
+
108
+ The gate is **off by default** for a hard-won reason: clients that log in
109
+ over foundation-auth's HTTP transport send **no** `SESSION_AUTH_TOKEN` on any
110
+ WebSocket message — session storage's `authToken` is never populated by that
111
+ flow, so `message.ts`'s token stamp serializes to nothing (verified from
112
+ browser frame captures). A default-on gate would reject every datasource such
113
+ a client opens. Enable it only for clients that authenticate over WS.
112
114
 
113
115
  ## Protocol coverage
114
116
 
@@ -227,7 +229,15 @@ extracted from for how each was actually found:
227
229
  array, uppercase keys. Throw `NackError` from an event handler or
228
230
  request-reply resolver rather than hand-rolling this shape; a lowercase
229
231
  `{error, details}` object crashes the real client's `.forEach`.
230
- 3. **`DATA_LOGON` snapshot and later live pushes use the identical envelope**
232
+ 3. **Commit-event acks are the GENERIC `EVENT_ACK`/`EVENT_NACK`** — never
233
+ `<EVENT_NAME>_ACK`/`_NACK`. The reply is correlated purely by
234
+ `SOURCE_REF`; real consumers match the MESSAGE_TYPE string exactly
235
+ (`foundation-comms`' `kv.service` checks `=== 'EVENT_ACK'`,
236
+ entity-management and the showcase's `customEvents.ts` check
237
+ `=== 'EVENT_NACK'`). Get this wrong and every successful commit renders
238
+ as a failure toast while every NACK passes as silent success.
239
+ `handleCommitEvent()` (`src/handlers/commitEvent.ts`) does this for you.
240
+ 4. **`DATA_LOGON` snapshot and later live pushes use the identical envelope**
231
241
  (`MESSAGE_TYPE: 'QUERY_UPDATE'`, same `SOURCE_REF`) — the client
232
242
  distinguishes insert/amend/delete purely via each row's
233
243
  `DETAILS.OPERATION` (`'INSERT' | 'MODIFY' | 'DELETE'`, no other vocabulary
@@ -235,7 +245,7 @@ extracted from for how each was actually found:
235
245
  (`src/protocol/rowUpdate.ts`) does this for you — always route pushes
236
246
  through `broadcast()`/`broadcastTableChange()`, never `connection.send()`
237
247
  directly.
238
- 4. **Datasource `init()` needs `TYPE: 'DATASERVER'` plus a non-empty `FIELD`
248
+ 5. **Datasource `init()` needs `TYPE: 'DATASERVER'` plus a non-empty `FIELD`
239
249
  array** or the client silently reports "no fields returned" and gives up.
240
250
  `deriveFields()` (`src/db/metadata.ts`) infers this from the rows' own JS
241
251
  types — falling back to the registration-time seed rows when every live
@@ -245,7 +255,7 @@ extracted from for how each was actually found:
245
255
  whole numbers still infers as `LONG` — if it's semantically a `DOUBLE`
246
256
  (e.g. a NOTIONAL that happens to be round in the seed data), say so via
247
257
  the `fieldTypes` override on the query/request-reply.
248
- 5. **`CRITERIA_MATCH` needs more than `==`.** `compileCriteria()`
258
+ 6. **`CRITERIA_MATCH` needs more than `==`.** `compileCriteria()`
249
259
  (`src/db/criteria.ts`) supports `== != > >= < <= AND OR NOT` (also `&&`/`||`)
250
260
  and parentheses via a small typed grammar (not `eval`/`new Function` — a
251
261
  malformed criteria string can only fail to parse, never execute arbitrary
@@ -263,7 +273,7 @@ extracted from for how each was actually found:
263
273
  responds (unfiltered) rather than leaving the client's grid stuck on
264
274
  "Loading...". Add new `Expr.*` entries to `EXPR_FUNCTIONS` in `criteria.ts`
265
275
  if you hit one that isn't covered yet.
266
- 6. **Composite-key AMEND/DELETE matching needs a fallback beyond the PK.**
276
+ 7. **Composite-key AMEND/DELETE matching needs a fallback beyond the PK.**
267
277
  `Store.findRow()` (`src/db/store.ts`) tries the configured PK field, then
268
278
  any single field that uniquely identifies one row, then the full
269
279
  combination of provided fields — needed for tables where no single field
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@genesislcap/mock-server",
3
- "version": "15.7.3-alpha-277c463.0",
3
+ "version": "15.7.3-alpha-94532c4.0",
4
4
  "description": "Reusable in-memory Genesis WebSocket protocol mock server for client automation/CI, without a JVM or database.",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",
@@ -33,5 +33,5 @@
33
33
  "publishConfig": {
34
34
  "access": "public"
35
35
  },
36
- "gitHead": "3659a1907a981b483ed3a3ad1163bc2ece4e08e7"
36
+ "gitHead": "85a871e7a46382dbfc7cc262a508e0cc95d3b3e3"
37
37
  }
@@ -1,7 +1,7 @@
1
1
  import type { Store } from '../db/store.ts';
2
2
  import type { Connection } from '../protocol/connection.ts';
3
3
  import { NackError } from '../protocol/errors.ts';
4
- import { ERROR_CODE } from '../protocol/messageTypes.ts';
4
+ import { ERROR_CODE, MESSAGE_TYPE } from '../protocol/messageTypes.ts';
5
5
  import type {
6
6
  BroadcastFn,
7
7
  BroadcastTableChangeFn,
@@ -28,9 +28,14 @@ export function handleCommitEvent(
28
28
  const eventName = message.MESSAGE_TYPE;
29
29
  const handler = config.eventHandlers?.[eventName];
30
30
 
31
+ // Replies use the GENERIC EVENT_ACK/EVENT_NACK — correlation is purely via
32
+ // SOURCE_REF. See the note on MESSAGE_TYPE in protocol/messageTypes.ts:
33
+ // real consumers (foundation-comms' kv.service, entity-management) match
34
+ // these names exactly, so a name-suffixed <EVENT>_ACK reads as failure and
35
+ // a <EVENT>_NACK passes as silent success.
31
36
  if (!handler) {
32
37
  connection.reply(message, {
33
- MESSAGE_TYPE: `${eventName}_NACK`,
38
+ MESSAGE_TYPE: MESSAGE_TYPE.EVENT_NACK,
34
39
  ERROR: [
35
40
  { CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `No event handler registered for ${eventName}` },
36
41
  ],
@@ -41,7 +46,7 @@ export function handleCommitEvent(
41
46
  try {
42
47
  const result = handler(message.DETAILS ?? {}, { connection, store, message, ...ctx }) ?? {};
43
48
  connection.reply(message, {
44
- MESSAGE_TYPE: `${eventName}_ACK`,
49
+ MESSAGE_TYPE: MESSAGE_TYPE.EVENT_ACK,
45
50
  GENERATED: result.generated ?? [],
46
51
  });
47
52
  } catch (error) {
@@ -49,6 +54,6 @@ export function handleCommitEvent(
49
54
  error instanceof NackError
50
55
  ? error.errors
51
56
  : [{ CODE: ERROR_CODE.VALIDATION_ERROR, TEXT: (error as Error).message }];
52
- connection.reply(message, { MESSAGE_TYPE: `${eventName}_NACK`, ERROR: errors });
57
+ connection.reply(message, { MESSAGE_TYPE: MESSAGE_TYPE.EVENT_NACK, ERROR: errors });
53
58
  }
54
59
  }
@@ -1,4 +1,13 @@
1
1
  export const MESSAGE_TYPE = {
2
+ // Commit events are acked with the GENERIC pair below — the reply is
3
+ // correlated by SOURCE_REF, not by name. Real Genesis never replies
4
+ // <EVENT_NAME>_ACK/_NACK: foundation-comms' kv.service checks
5
+ // MESSAGE_TYPE === 'EVENT_ACK' exactly, and entity-management (and the
6
+ // showcase's customEvents.ts) check MESSAGE_TYPE === 'EVENT_NACK' exactly.
7
+ // Reply with the name-suffixed form and every successful commit renders as
8
+ // a failure toast while every NACK passes silently.
9
+ EVENT_ACK: 'EVENT_ACK',
10
+ EVENT_NACK: 'EVENT_NACK',
2
11
  EVENT_LOGIN_AUTH: 'EVENT_LOGIN_AUTH',
3
12
  EVENT_LOGIN_AUTH_ACK: 'EVENT_LOGIN_AUTH_ACK',
4
13
  EVENT_LOGIN_AUTH_NACK: 'EVENT_LOGIN_AUTH_NACK',
@@ -11,15 +11,21 @@ import type { GenesisMessage, MockServerConfig } from '../types.ts';
11
11
  import type { Connection } from './connection.ts';
12
12
  import { MESSAGE_TYPE, ERROR_CODE, isCommitEvent, isRequestReply } from './messageTypes.ts';
13
13
 
14
- // Message types a connection may send before authenticating. Everything else
15
- // (data subscriptions, request-replies, metadata, commit events) requires the
16
- // connection to have logged in over WS — or to present a SESSION_AUTH_TOKEN
17
- // this server issued (over either transport), which is how a client that
18
- // logged in over HTTP authenticates its WS traffic: foundation-comms stamps
19
- // the stored token onto every outgoing message. RESOURCES_REQUEST is allowed
20
- // pre-auth so resource discovery can't deadlock a client that fetches it
21
- // before (or while) logging in. Set config.auth.requireAuth = false to skip
22
- // the gate entirely.
14
+ // Message types a connection may send before authenticating when the OPT-IN
15
+ // auth gate (config.auth.requireAuth = true) is enabled. Everything else
16
+ // (data subscriptions, request-replies, metadata, commit events) then
17
+ // requires the connection to have logged in over WS — or to present a
18
+ // SESSION_AUTH_TOKEN this server issued (over either transport).
19
+ // RESOURCES_REQUEST is allowed pre-auth so resource discovery can't deadlock
20
+ // a client that fetches it before (or while) logging in.
21
+ //
22
+ // The gate is OFF by default because real clients can't be assumed to
23
+ // satisfy it: browser frame captures show that after logging in over
24
+ // foundation-auth's HTTP transport, the client sends NO SESSION_AUTH_TOKEN
25
+ // on any WebSocket message (session storage's authToken is never populated
26
+ // by that flow, so message.ts's stamp serializes to nothing) — a default-on
27
+ // gate would reject every datasource with NOT_LOGGED_ON. Enable it only for
28
+ // clients that log in over WS (or stamp tokens on WS traffic).
23
29
  const PRE_AUTH_MESSAGE_TYPES = new Set<string>([
24
30
  MESSAGE_TYPE.EVENT_LOGIN_AUTH,
25
31
  MESSAGE_TYPE.EVENT_LOGOUT,
@@ -60,7 +66,8 @@ function replyNotLoggedOn(message: GenesisMessage, connection: Connection): void
60
66
  return;
61
67
  }
62
68
  if (isCommitEvent(type)) {
63
- connection.reply(message, { MESSAGE_TYPE: `${type}_NACK`, ERROR });
69
+ // Generic, not `${type}_NACK` — see the note in messageTypes.ts.
70
+ connection.reply(message, { MESSAGE_TYPE: MESSAGE_TYPE.EVENT_NACK, ERROR });
64
71
  return;
65
72
  }
66
73
  connection.reply(message, { MESSAGE_TYPE: type, ERROR });
@@ -78,7 +85,7 @@ export function routeMessage(
78
85
  // HEARTBEAT_PONG's IS_AUTHENTICATED reflects an HTTP-issued token straight
79
86
  // away; the gate itself only applies to data traffic.
80
87
  ensureAuthenticated(message, connection, tokens);
81
- const requireAuth = config.auth?.requireAuth ?? true;
88
+ const requireAuth = config.auth?.requireAuth ?? false;
82
89
  if (
83
90
  requireAuth &&
84
91
  !PRE_AUTH_MESSAGE_TYPES.has(message.MESSAGE_TYPE) &&
package/src/types.ts CHANGED
@@ -69,11 +69,14 @@ export interface AuthConfig {
69
69
  // A username to always ack gwf/event-login-details as (skips the login
70
70
  // screen entirely), or `true` to use the first configured user.
71
71
  httpAutoLogin?: string | true;
72
- // Default true: WS data traffic (DATA_LOGON, REQ_*, META/JSON_SCHEMA,
73
- // commit events) is rejected with a NOT_LOGGED_ON error until the
74
- // connection logs in — or presents a SESSION_AUTH_TOKEN this server issued
75
- // over either transport (which is how an HTTP login authenticates WS
76
- // traffic). Set false to accept everything unauthenticated.
72
+ // OPT-IN (default false): when true, WS data traffic (DATA_LOGON, REQ_*,
73
+ // META/JSON_SCHEMA, commit events) is rejected with a NOT_LOGGED_ON error
74
+ // until the connection logs in — or presents a SESSION_AUTH_TOKEN this
75
+ // server issued over either transport. Off by default because clients
76
+ // using foundation-auth's HTTP login send no SESSION_AUTH_TOKEN on WS
77
+ // messages at all (verified from browser frame captures), so a default-on
78
+ // gate rejects their every datasource. Enable only for clients that log in
79
+ // over WS.
77
80
  requireAuth?: boolean;
78
81
  }
79
82
 
@@ -187,8 +187,27 @@ describe('mock server end to end', () => {
187
187
  assert.equal(push.ROW[0].DETAILS.ROW_REF, 'TR001');
188
188
  });
189
189
 
190
- it('rejects data traffic before authentication with NOT_LOGGED_ON', async () => {
190
+ it('acks commit events with the generic EVENT_ACK/EVENT_NACK pair', async () => {
191
191
  const { client } = await setup();
192
+ await client.login();
193
+
194
+ // Real consumers (foundation-comms' kv.service, entity-management) match
195
+ // MESSAGE_TYPE 'EVENT_ACK'/'EVENT_NACK' exactly — never <EVENT>_ACK.
196
+ const ack = await client.request({
197
+ MESSAGE_TYPE: 'EVENT_TRADE_DELETE',
198
+ DETAILS: { TRADE_ID: 'TR001' },
199
+ });
200
+ assert.equal(ack.MESSAGE_TYPE, 'EVENT_ACK');
201
+
202
+ const unknown = await client.request({ MESSAGE_TYPE: 'EVENT_NO_SUCH_THING', DETAILS: {} });
203
+ assert.equal(unknown.MESSAGE_TYPE, 'EVENT_NACK');
204
+ assert.equal(unknown.ERROR?.[0]?.CODE, 'UNKNOWN_RESOURCE');
205
+ });
206
+
207
+ it('rejects data traffic before authentication when requireAuth is opted in', async () => {
208
+ const { client } = await setup((config) => {
209
+ config.auth!.requireAuth = true;
210
+ });
192
211
  const logon = await client.request({
193
212
  MESSAGE_TYPE: 'DATA_LOGON',
194
213
  DETAILS: { DATASOURCE_NAME: 'ALL_TRADES' },
@@ -200,20 +219,20 @@ describe('mock server end to end', () => {
200
219
  assert.equal(rep.ERROR?.[0]?.CODE, 'NOT_LOGGED_ON');
201
220
 
202
221
  const nack = await client.request({ MESSAGE_TYPE: 'EVENT_TRADE_DELETE', DETAILS: {} });
203
- assert.equal(nack.MESSAGE_TYPE, 'EVENT_TRADE_DELETE_NACK');
222
+ assert.equal(nack.MESSAGE_TYPE, 'EVENT_NACK');
204
223
  assert.equal(nack.ERROR?.[0]?.CODE, 'NOT_LOGGED_ON');
205
224
  });
206
225
 
207
- it('accepts everything unauthenticated when auth.requireAuth is false', async () => {
208
- const { client } = await setup((config) => {
209
- config.auth!.requireAuth = false;
210
- });
226
+ it('accepts unauthenticated traffic by default (HTTP-login clients send no WS token)', async () => {
227
+ const { client } = await setup();
211
228
  const reply = await client.request({ MESSAGE_TYPE: 'REQ_TRADE' });
212
229
  assert.equal(reply.REPLY.length, 2);
213
230
  });
214
231
 
215
232
  it('authenticates WS traffic with a token issued by the HTTP login transport', async () => {
216
- const { client, port } = await setup();
233
+ const { client, port } = await setup((config) => {
234
+ config.auth!.requireAuth = true;
235
+ });
217
236
  const response = await fetch(`http://127.0.0.1:${port}/gwf/event-login-details`);
218
237
  assert.equal(response.status, 200);
219
238
  const ack = (await response.json()) as Row;