@genesislcap/mock-server 15.7.3-alpha-94532c4.0 → 15.31.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 +246 -40
- package/dist/db/criteria.d.ts +5 -0
- package/dist/db/criteria.js +327 -0
- package/dist/db/metadata.d.ts +3 -0
- package/dist/db/metadata.js +35 -0
- package/dist/db/store.d.ts +28 -0
- package/dist/db/store.js +254 -0
- package/dist/handlers/auth.d.ts +10 -0
- package/dist/handlers/auth.js +121 -0
- package/dist/handlers/commitEvent.d.ts +8 -0
- package/dist/handlers/commitEvent.js +40 -0
- package/dist/handlers/dataLogon.d.ts +5 -0
- package/dist/handlers/dataLogon.js +56 -0
- package/dist/handlers/heartbeat.d.ts +3 -0
- package/dist/handlers/heartbeat.js +16 -0
- package/dist/handlers/http.d.ts +4 -0
- package/dist/handlers/http.js +179 -0
- package/dist/handlers/jsonSchema.d.ts +5 -0
- package/dist/handlers/jsonSchema.js +94 -0
- package/dist/handlers/meta.d.ts +4 -0
- package/dist/handlers/meta.js +42 -0
- package/dist/handlers/requestReply.d.ts +4 -0
- package/dist/handlers/requestReply.js +68 -0
- package/dist/handlers/resourceAuth.d.ts +5 -0
- package/dist/handlers/resourceAuth.js +27 -0
- package/dist/handlers/resources.d.ts +3 -0
- package/dist/handlers/resources.js +34 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +5 -0
- package/dist/launch.d.ts +20 -0
- package/dist/launch.js +164 -0
- package/dist/protocol/connection.d.ts +25 -0
- package/dist/protocol/connection.js +36 -0
- package/dist/protocol/errors.d.ts +17 -0
- package/dist/protocol/errors.js +16 -0
- package/dist/protocol/messageTypes.d.ts +28 -0
- package/dist/protocol/messageTypes.js +42 -0
- package/dist/protocol/router.d.ts +6 -0
- package/dist/protocol/router.js +101 -0
- package/dist/protocol/rowUpdate.d.ts +4 -0
- package/dist/protocol/rowUpdate.js +17 -0
- package/dist/server.d.ts +23 -0
- package/dist/server.js +328 -0
- package/dist/types.d.ts +142 -0
- package/dist/types.js +4 -0
- package/package.json +16 -7
- package/src/db/criteria.ts +75 -21
- package/src/db/store.ts +126 -29
- package/src/handlers/auth.ts +32 -6
- package/src/handlers/commitEvent.ts +4 -1
- package/src/handlers/dataLogon.ts +23 -7
- package/src/handlers/heartbeat.ts +16 -3
- package/src/handlers/http.ts +43 -2
- package/src/handlers/jsonSchema.ts +21 -5
- package/src/handlers/meta.ts +11 -3
- package/src/handlers/requestReply.ts +22 -8
- package/src/handlers/resourceAuth.ts +37 -0
- package/src/handlers/resources.ts +8 -1
- package/src/index.ts +9 -0
- package/src/launch.ts +220 -0
- package/src/protocol/connection.ts +4 -1
- package/src/protocol/router.ts +2 -2
- package/src/protocol/rowUpdate.ts +5 -4
- package/src/server.ts +150 -22
- package/src/types.ts +124 -3
- package/license.txt +0 -46
- package/test/criteria.test.ts +0 -174
- package/test/jsonSchema.test.ts +0 -38
- package/test/metadata.test.ts +0 -49
- package/test/server.test.ts +0 -308
- package/test/store.test.ts +0 -181
- package/tsconfig.json +0 -18
package/README.md
CHANGED
|
@@ -3,30 +3,29 @@
|
|
|
3
3
|
A reusable, in-memory Genesis Framework WebSocket protocol server for client
|
|
4
4
|
automation and local dev — no JVM, no database, starts in milliseconds.
|
|
5
5
|
|
|
6
|
-
Written in TypeScript
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
Type-check with `
|
|
28
|
-
(`tsc --noEmit`
|
|
29
|
-
compiles or reads the emitted output (there isn't any, `noEmit: true`).
|
|
6
|
+
Written in TypeScript; **development and tests run straight from source**
|
|
7
|
+
under either runtime (`node --experimental-strip-types` on Node >=22.6, or
|
|
8
|
+
`bun run` — this package deliberately avoids Bun-only APIs like `Bun.serve`
|
|
9
|
+
in favor of `node:http` + the `ws` package, which both support identically).
|
|
10
|
+
All relative imports use explicit `.ts` extensions
|
|
11
|
+
(`import { X } from './foo.ts'`) because Node's type-stripping resolver
|
|
12
|
+
requires the literal extension match; `allowImportingTsExtensions` keeps
|
|
13
|
+
`tsc` happy with that.
|
|
14
|
+
|
|
15
|
+
**Consumers get compiled JavaScript.** The `build` script (`tsc -p
|
|
16
|
+
tsconfig.build.json`, with `rewriteRelativeImportExtensions` turning the
|
|
17
|
+
`.ts` specifiers into `.js`) emits `dist/`, and the package's
|
|
18
|
+
`main`/`types`/`exports` point there. This is not optional polish: Node
|
|
19
|
+
**refuses** to strip types for files inside a real (non-symlinked)
|
|
20
|
+
`node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so a
|
|
21
|
+
published package shipping only `.ts` is unusable with plain `node` outside
|
|
22
|
+
this monorepo. The `exports` map keeps a `"bun"` condition on `src/index.ts`
|
|
23
|
+
so Bun users still run the source directly. In-repo, `npm run bootstrap`
|
|
24
|
+
builds `dist` (via `lerna run build --no-private`); when hacking on the
|
|
25
|
+
engine against a consumer, keep `pnpm --filter @genesislcap/mock-server build:watch` running.
|
|
26
|
+
|
|
27
|
+
Type-check with `pnpm --filter @genesislcap/mock-server typecheck`
|
|
28
|
+
(`tsc --noEmit` over src + tests).
|
|
30
29
|
|
|
31
30
|
This package is the **protocol engine only**: message routing, `SOURCE_REF`
|
|
32
31
|
correlation, `CRITERIA_MATCH` evaluation, subscription/broadcast plumbing, and
|
|
@@ -78,6 +77,184 @@ const server = createMockServer(config);
|
|
|
78
77
|
server.start(9064);
|
|
79
78
|
```
|
|
80
79
|
|
|
80
|
+
## Project-fidelity features
|
|
81
|
+
|
|
82
|
+
Beyond the basic table/view/query plumbing in the example above, the config
|
|
83
|
+
covers the server-side behaviors real projects lean on:
|
|
84
|
+
|
|
85
|
+
- **Computed request-replies** — for request servers that calculate rather
|
|
86
|
+
than read (date calculations, holiday validate/roll, premium schedules,
|
|
87
|
+
keyed composite lookups), give the `RequestReplyDef` a `resolver` instead
|
|
88
|
+
of a `source`. It receives `{ request, message, user, store }` (the keyed
|
|
89
|
+
`REQUEST` fields, the raw message, the requesting user, the live store) and
|
|
90
|
+
returns the `REPLY` rows verbatim; throw `NackError` for a
|
|
91
|
+
protocol-correct error. Set `metadataRows` (a representative sample reply)
|
|
92
|
+
so `META_REQUEST` can still derive `REPLY_FIELD`:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
requestReplies: {
|
|
96
|
+
DATE_CALC: {
|
|
97
|
+
resolver: ({ request }) => [computeDates(request.DATE, request.CALENDAR)],
|
|
98
|
+
metadataRows: [{ INPUT_DATE: '20260101', RESULT_DATE: '20260105' }],
|
|
99
|
+
},
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- **Query filters (where-clause equivalent)** — `QueryDef.filter` narrows a
|
|
104
|
+
dataserver query the way the real query's filter clause does (keep template
|
|
105
|
+
rows out of a main-entries query, CANCELLED out of a blotter). Applied to
|
|
106
|
+
both the `DATA_LOGON` snapshot and live pushes, before any client
|
|
107
|
+
`CRITERIA_MATCH`:
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
queries: {
|
|
111
|
+
ALL_TRADES: { source: 'TRADE_VIEW', filter: (row) => row.TRADE_STATUS !== 'CANCELLED' },
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- **Permissioning (auth maps / hideFields)** — `auth` on a query or
|
|
116
|
+
request-reply scopes what each user sees. `rowFilter(row, user)` drops rows
|
|
117
|
+
(snapshots, live pushes, and `REQ_` replies); `hideFields` (a list, or a
|
|
118
|
+
function of the user) strips columns from rows **and** from `META_REQUEST`
|
|
119
|
+
field metadata, so e.g. sales users never see the trader side of mirrored
|
|
120
|
+
columns. `user` is `{ userName, profile, permission }` for the requesting
|
|
121
|
+
connection:
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
queries: {
|
|
125
|
+
ALL_RFQS: {
|
|
126
|
+
source: 'RFQ_VIEW',
|
|
127
|
+
auth: {
|
|
128
|
+
rowFilter: (row, user) => user.profile.includes('TRADER') || row.SIDE === 'SALES',
|
|
129
|
+
hideFields: (user) => (user.profile.includes('TRADER') ? [] : ['TRADER_PX']),
|
|
130
|
+
},
|
|
131
|
+
},
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
- **Join predicates and anti-joins** — a view join takes a `where(joinRow,
|
|
136
|
+
baseRow)` predicate for matches the `on` equality alone can't express
|
|
137
|
+
(side-specific price joins), and `antiJoins` keeps only base rows with NO
|
|
138
|
+
match (the `USER_WITHOUT_DETAIL` pattern):
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
views: {
|
|
142
|
+
RFQ_SALES_VIEW: {
|
|
143
|
+
base: 'RFQ',
|
|
144
|
+
joins: [{ table: 'RFQ_PRICE', on: ['RFQ_ID', 'RFQ_ID'], select: { SALES_PX: 'PX' },
|
|
145
|
+
where: (price) => price.SIDE === 'SALES' }],
|
|
146
|
+
},
|
|
147
|
+
USER_WITHOUT_DETAIL: {
|
|
148
|
+
base: 'USER',
|
|
149
|
+
antiJoins: [{ table: 'USER_DETAIL', on: ['USER_NAME', 'USER_NAME'] }],
|
|
150
|
+
},
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
- **Composite primary keys** — `pkField` accepts an array
|
|
155
|
+
(`pkField: ['RFQ_ID', 'SIDE']`). Rows are identified by the fields' values
|
|
156
|
+
joined with `'|'` (so values must not contain `'|'`), which becomes the
|
|
157
|
+
`ROW_REF` — no synthetic key column, nothing extra in grids. Event handlers
|
|
158
|
+
on composite tables pass `store.rowKey(table, row)` to
|
|
159
|
+
`broadcastTableChange`; sequence generation still requires a single
|
|
160
|
+
`pkField`.
|
|
161
|
+
|
|
162
|
+
## Running several servers in parallel (and one-command dev stacks)
|
|
163
|
+
|
|
164
|
+
Every `createMockServer()` instance is fully isolated — its own store,
|
|
165
|
+
connections, sessions, and tokens — so parallel test workers/shards can each
|
|
166
|
+
run their own server in one process or many. The only shared resource is
|
|
167
|
+
ports; don't hand-assign them, use `listen()`:
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
const server = createMockServer(config);
|
|
171
|
+
const port = await server.listen(); // port 0 -> OS picks a free one
|
|
172
|
+
// hand `ws://localhost:${port}` to this worker's client
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
To boot a **mock server + client dev process as one command** (and N such
|
|
176
|
+
pairs side by side), use `launchStack` — it starts the server on an
|
|
177
|
+
ephemeral port, spawns the client command with `API_HOST` pointed at it, and
|
|
178
|
+
ties the lifetimes (client exit stops the server; one Ctrl+C tears down the
|
|
179
|
+
pair):
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
// mock-server/src/dev.ts
|
|
183
|
+
import { launchStack } from '@genesislcap/mock-server';
|
|
184
|
+
import { config } from './config.ts';
|
|
185
|
+
|
|
186
|
+
await launchStack({ config, clientCommand: 'pnpm run dev:vite' });
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`clientEnv: (port) => ({ ... })` adds per-instance env on top of the default
|
|
190
|
+
`API_HOST` (e.g. to pin the client dev server's own port; vite's default
|
|
191
|
+
auto-increment already avoids collisions otherwise). Pass
|
|
192
|
+
`tieLifetimes: false` to manage shutdown yourself (e.g. inside a test
|
|
193
|
+
runner).
|
|
194
|
+
|
|
195
|
+
### Shutdown, and why there is a watchdog process
|
|
196
|
+
|
|
197
|
+
A client dev command is normally a launcher itself (`genx` -> `vite` ->
|
|
198
|
+
`esbuild`), so shutdown has to reach the whole tree, not just the pid that
|
|
199
|
+
was spawned. `launchStack` therefore starts the client as its own process
|
|
200
|
+
group leader and signals the **group**: SIGINT first, then SIGKILL after
|
|
201
|
+
`clientExitGraceMs` (default 5s) for anything that ignores it. `stop()`
|
|
202
|
+
resolves once the tree is actually down, not merely signalled. SIGINT,
|
|
203
|
+
SIGTERM, SIGHUP and process exit all take that same path.
|
|
204
|
+
|
|
205
|
+
None of that can run if the launcher itself is SIGKILLed — and then the
|
|
206
|
+
client is reparented to init and keeps holding its port, invisible on an
|
|
207
|
+
ephemeral-port setup. So `launchStack` also spawns a tiny detached watchdog
|
|
208
|
+
that polls for the launcher and takes the client's group down when it
|
|
209
|
+
disappears; the watchdog exits as soon as either side is gone, so it can
|
|
210
|
+
never outlive the pair it watches. Set `tieLifetimes: false` and you own all
|
|
211
|
+
of this yourself — no watchdog is started.
|
|
212
|
+
|
|
213
|
+
## Extension points
|
|
214
|
+
|
|
215
|
+
For everything the protocol handlers don't cover, three hooks avoid ever
|
|
216
|
+
having to monkey-patch the engine:
|
|
217
|
+
|
|
218
|
+
- **`config.httpRoutes`** — extra HTTP endpoints on the engine's shared
|
|
219
|
+
`http.Server` (e.g. a project's `GET pbi/configs`). Tried before the
|
|
220
|
+
built-in login/SSO handlers, so they can also override those. A string
|
|
221
|
+
`path` matches `pathname.endsWith(path)` (tolerating any gateway prefix);
|
|
222
|
+
a RegExp is tested against the full pathname:
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
httpRoutes: [{
|
|
226
|
+
method: 'GET',
|
|
227
|
+
path: 'pbi/configs',
|
|
228
|
+
handler: (req, res) => {
|
|
229
|
+
res.writeHead(200, { 'Content-Type': 'application/json' });
|
|
230
|
+
res.end(JSON.stringify({ CONFIGS: [...] }));
|
|
231
|
+
},
|
|
232
|
+
}]
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
- **`config.onMessage`** — called for every parsed WS message before routing.
|
|
236
|
+
Return a message to continue routing with it (possibly rewritten — e.g.
|
|
237
|
+
normalizing a criteria dialect), `false` if the hook fully handled it
|
|
238
|
+
(reply via `ctx.connection.reply`), or nothing to route the original:
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
onMessage: (message, { connection }) => {
|
|
242
|
+
if (message.MESSAGE_TYPE === 'CUSTOM_PING') {
|
|
243
|
+
connection.reply(message, { MESSAGE_TYPE: 'CUSTOM_PONG' });
|
|
244
|
+
return false;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
- **`config.defaultEventHandler`** — fallback for commit events with no
|
|
250
|
+
registered handler, so a project with dozens of events can adopt
|
|
251
|
+
incrementally (`defaultEventHandler: () => ({})` acks everything
|
|
252
|
+
unhandled) instead of enumerating ack-only handlers. Unregistered events
|
|
253
|
+
NACK with `UNKNOWN_RESOURCE` when unset. Note `RESOURCES_REQUEST` only
|
|
254
|
+
lists *named* events (`eventHandlers` + `eventSchemas` keys) — if the
|
|
255
|
+
client's resource gate blocks an event served only by the default handler,
|
|
256
|
+
name it in `config.eventSchemas` or `config.resources`.
|
|
257
|
+
|
|
81
258
|
## Two auth transports
|
|
82
259
|
|
|
83
260
|
Genesis client apps built on `@genesislcap/foundation-auth`'s login UI don't
|
|
@@ -105,6 +282,16 @@ transport. The WS token-refresh login (`EVENT_LOGIN_AUTH` with only
|
|
|
105
282
|
`DETAILS.REFRESH_AUTH_TOKEN`, no credentials — foundation-comms'
|
|
106
283
|
`createRefreshTokenMessage`) is honored via the same token registry.
|
|
107
284
|
|
|
285
|
+
`GET gwf/sso/list` is served too: foundation-auth's login screen fetches it
|
|
286
|
+
whenever SSO is toggled on, and treats a failed fetch as fatal — red "Failed
|
|
287
|
+
to fetch identity providers" **and** the credentials form hidden — while an
|
|
288
|
+
empty `IDPS` list is rejected as well ("Identity provider list empty").
|
|
289
|
+
Configure real entries via `config.auth.ssoIdentityProviders`
|
|
290
|
+
(`{ ID, DESCRIPTION, TYPE }`, foundation-auth's `IDENTITY_PROVIDER` DTO);
|
|
291
|
+
when unset the mock serves one non-functional placeholder so the login
|
|
292
|
+
screen still renders with SSO enabled. Clicking a provider navigates to the
|
|
293
|
+
real SSO login URL, which the mock does not implement.
|
|
294
|
+
|
|
108
295
|
The gate is **off by default** for a hard-won reason: clients that log in
|
|
109
296
|
over foundation-auth's HTTP transport send **no** `SESSION_AUTH_TOKEN` on any
|
|
110
297
|
WebSocket message — session storage's `authToken` is never populated by that
|
|
@@ -152,6 +339,16 @@ every field on that table. This covers naming variants like
|
|
|
152
339
|
`config.eventSchemas['<eventName>'] = { table, pkOnly, fieldTypes }` for
|
|
153
340
|
names that don't follow the convention.
|
|
154
341
|
|
|
342
|
+
The `FEATURE` doesn't have to be an event name. It also resolves, in order:
|
|
343
|
+
an entry in `config.eventSchemas`, a **resource name** (a `config.queries` or
|
|
344
|
+
`config.requestReplies` key, via its `source` — `'ALL_TRADES'` →
|
|
345
|
+
`TRADE_VIEW`), and a bare **table name** (`'TRADE'`). Both matter in practice:
|
|
346
|
+
`<entity-management resourceName="COUNTERPARTY">` asks by table and the
|
|
347
|
+
showcase's react-client Admin page does that, while the FAST-Element client's
|
|
348
|
+
grids ask by query name (`ALL_USERS`, `ALL_PROFILES`, `ALL_TRADES`). Resolve
|
|
349
|
+
only event names and those requests error with `UNKNOWN_RESOURCE` and the form
|
|
350
|
+
renders no fields — the same dead button as above, from the other direction.
|
|
351
|
+
|
|
155
352
|
Everything else `<entity-management>` needs — resource discovery
|
|
156
353
|
(`RESOURCES_REQUEST`), grid metadata (`META_REQUEST`), row data (`DATA_LOGON`
|
|
157
354
|
or `REQ_<name>` depending on `datasourceType`), and the actual
|
|
@@ -256,23 +453,32 @@ extracted from for how each was actually found:
|
|
|
256
453
|
(e.g. a NOTIONAL that happens to be round in the seed data), say so via
|
|
257
454
|
the `fieldTypes` override on the query/request-reply.
|
|
258
455
|
6. **`CRITERIA_MATCH` needs more than `==`.** `compileCriteria()`
|
|
259
|
-
(`src/db/criteria.ts`) supports `== != > >= < <= AND OR NOT` (also
|
|
260
|
-
and parentheses via a small typed grammar (not
|
|
261
|
-
malformed criteria string can only fail to
|
|
262
|
-
JS). It
|
|
263
|
-
|
|
264
|
-
`foundation-criteria`'s `serialisers.ts`
|
|
265
|
-
filter
|
|
266
|
-
|
|
456
|
+
(`src/db/criteria.ts`) supports `== != > >= < <= AND OR NOT` (also
|
|
457
|
+
`&&`/`||`/`!`) and parentheses via a small typed grammar (not
|
|
458
|
+
`eval`/`new Function` — a malformed criteria string can only fail to
|
|
459
|
+
parse, never execute arbitrary JS). It understands both function-call
|
|
460
|
+
dialects real clients emit: the `Expr.<fn>(field, value)` form from
|
|
461
|
+
`foundation-criteria`'s `serialisers.ts` / `foundation-ui`'s date-range
|
|
462
|
+
filter, and the `<FIELD>.<fn>(value)` method-call form project filter
|
|
463
|
+
builders generate (e.g. `DEAL_CURRENCIES.containsIgnoreCase('USD')`) —
|
|
464
|
+
both share the same functions: `contains`, `containsIgnoreCase` (substring
|
|
465
|
+
on strings, membership on array-valued fields), the Java/Groovy string
|
|
466
|
+
methods `equals`, `equalsIgnoreCase`, `startsWith`, `endsWith` (pbc-notify-ui's
|
|
467
|
+
inbox subscribes with `((ALERT_STATUS.equals("NEW")))`, and an unsupported
|
|
468
|
+
method makes the whole criteria fail to compile — the filter is dropped and
|
|
469
|
+
the grid shows every row), `dateIsToday`,
|
|
470
|
+
`dateIsEqual`, `dateIsGreaterEqual`, `dateIsLessEqual`, `dateTimeIsEqual`,
|
|
267
471
|
`dateTimeIsGreaterEqual`, `dateTimeIsLessEqual`, `dateTimeIsAfter`,
|
|
268
472
|
`dateTimeIsBefore` (`dateIs*` compares by calendar day, `dateTimeIs*` by
|
|
269
|
-
full timestamp
|
|
270
|
-
`
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
473
|
+
full timestamp). Date literals accept `'YYYYMMDD-HH:MM[:SS[.mmm]]'` — the
|
|
474
|
+
milliseconds matter: `getGroovyDateFormat()` emits them, and a parser that
|
|
475
|
+
rejects them makes every `dateTimeIs*` comparison silently false, so a
|
|
476
|
+
grid whose default filter is "Today" renders as an empty screen with no
|
|
477
|
+
warning. Any criteria this grammar still doesn't cover fails open instead
|
|
478
|
+
of crashing the handler: `compileCriteria()` logs a warning and returns a
|
|
479
|
+
match-all predicate, so `DATA_LOGON` still responds (unfiltered) rather
|
|
480
|
+
than leaving the client's grid stuck on "Loading...". Add new entries to
|
|
481
|
+
`EXPR_FUNCTIONS` in `criteria.ts` if you hit one that isn't covered yet.
|
|
276
482
|
7. **Composite-key AMEND/DELETE matching needs a fallback beyond the PK.**
|
|
277
483
|
`Store.findRow()` (`src/db/store.ts`) tries the configured PK field, then
|
|
278
484
|
any single field that uniquely identifies one row, then the full
|
|
@@ -298,7 +504,7 @@ never held that `ROW_REF` ignores the message.
|
|
|
298
504
|
|
|
299
505
|
## Tests
|
|
300
506
|
|
|
301
|
-
`
|
|
507
|
+
`pnpm --filter @genesislcap/mock-server test` runs the unit tests for
|
|
302
508
|
the criteria grammar, store, metadata inference, and event-table inference
|
|
303
509
|
plus end-to-end WS/HTTP tests (auth gating, filtered-subscription DELETE
|
|
304
510
|
delivery, keyed `REQ_*` lookups, session reuse, clean shutdown) via
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { Row } from '../types.ts';
|
|
2
|
+
export type Predicate = (record: Row) => boolean;
|
|
3
|
+
/** Compiles a CRITERIA_MATCH string into a predicate function(record) => boolean. */
|
|
4
|
+
export declare function compileCriteria(criteria?: string | null): Predicate;
|
|
5
|
+
export declare function filterByCriteria(rows: Row[], criteria?: string | null): Row[];
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
// Evaluator for Genesis CRITERIA_MATCH expressions, e.g.:
|
|
2
|
+
// TRADE_STATUS == 'CONFIRMED' AND QUANTITY > 100
|
|
3
|
+
// NOT (SIDE == 'SELL') OR PRICE >= 100.5
|
|
4
|
+
// Expr.dateTimeIsGreaterEqual(TRADE_DATE, '20240101-00:00:00') && COUNTERPARTY_ID == 'CPTY001'
|
|
5
|
+
//
|
|
6
|
+
// Supports: == = != <> > >= < <=, AND OR NOT (also && || !), parentheses,
|
|
7
|
+
// string/number/boolean literals, bare field identifiers, and two
|
|
8
|
+
// function-call dialects real clients emit:
|
|
9
|
+
// - `Expr.<fn>(field, value)` — foundation-criteria's serialisers.ts
|
|
10
|
+
// (grid date/text filters);
|
|
11
|
+
// - `<FIELD>.<fn>(value)` method-call form — e.g.
|
|
12
|
+
// `DEAL_CURRENCIES.containsIgnoreCase('USD')`, as emitted by
|
|
13
|
+
// project-level filter builders. Same EXPR_FUNCTIONS, with the receiver
|
|
14
|
+
// field as the implicit first argument.
|
|
15
|
+
// Deliberately NOT eval()/new Function() — this parses a small typed grammar
|
|
16
|
+
// so a malformed or hostile criteria string can only fail to parse, never
|
|
17
|
+
// execute arbitrary JS.
|
|
18
|
+
const TOKEN_RE = /\s*(&&|\|\||<=|>=|!=|<>|==|=|<|>|!|\(|\)|,|'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?|[A-Za-z_][A-Za-z0-9_.]*)/g;
|
|
19
|
+
function tokenize(input) {
|
|
20
|
+
const tokens = [];
|
|
21
|
+
let match;
|
|
22
|
+
let lastIndex = 0;
|
|
23
|
+
TOKEN_RE.lastIndex = 0;
|
|
24
|
+
while ((match = TOKEN_RE.exec(input))) {
|
|
25
|
+
if (match.index !== lastIndex) {
|
|
26
|
+
throw new Error(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
|
|
27
|
+
}
|
|
28
|
+
tokens.push(match[1]);
|
|
29
|
+
lastIndex = TOKEN_RE.lastIndex;
|
|
30
|
+
}
|
|
31
|
+
if (lastIndex !== input.length) {
|
|
32
|
+
throw new Error(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
|
|
33
|
+
}
|
|
34
|
+
return tokens;
|
|
35
|
+
}
|
|
36
|
+
function parseLiteral(token) {
|
|
37
|
+
if (/^['"]/.test(token))
|
|
38
|
+
return token.slice(1, -1).replace(/\\(.)/g, '$1');
|
|
39
|
+
if (/^-?\d+(?:\.\d+)?$/.test(token))
|
|
40
|
+
return Number(token);
|
|
41
|
+
if (token === 'true')
|
|
42
|
+
return true;
|
|
43
|
+
if (token === 'false')
|
|
44
|
+
return false;
|
|
45
|
+
if (token === 'null')
|
|
46
|
+
return null;
|
|
47
|
+
return undefined; // not a literal -> treat as a field reference
|
|
48
|
+
}
|
|
49
|
+
const COMPARATORS = new Set(['==', '=', '!=', '<>', '<', '<=', '>', '>=']);
|
|
50
|
+
// Genesis date/datetime values serialize as 'YYYYMMDD-HH:MM[:SS[.mmm]]' —
|
|
51
|
+
// foundation-criteria's serialisers.ts formatDate stops at seconds, but
|
|
52
|
+
// getGroovyDateFormat() emits milliseconds too, and a parser that rejects
|
|
53
|
+
// them makes every Expr.dateTimeIs* comparison silently false (date-filtered
|
|
54
|
+
// grids render zero rows with no warning). Row values may already be epoch
|
|
55
|
+
// millis (number) or an ISO string. Returns null if unparseable.
|
|
56
|
+
function parseGenesisDateTime(value) {
|
|
57
|
+
if (typeof value === 'number')
|
|
58
|
+
return value;
|
|
59
|
+
if (typeof value !== 'string')
|
|
60
|
+
return null;
|
|
61
|
+
const match = value.match(/^(\d{4})(\d{2})(\d{2})-(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/);
|
|
62
|
+
if (match) {
|
|
63
|
+
const MS_DIGITS = 3; // '.5' means 500ms, not 5ms — right-pad to full precision
|
|
64
|
+
const [, y, mo, d, h, mi, s, ms] = match;
|
|
65
|
+
return Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s ?? '0'), Number((ms ?? '0').padEnd(MS_DIGITS, '0')));
|
|
66
|
+
}
|
|
67
|
+
const parsed = Date.parse(value);
|
|
68
|
+
return Number.isNaN(parsed) ? null : parsed;
|
|
69
|
+
}
|
|
70
|
+
const HOURS_PER_DAY = 24;
|
|
71
|
+
const MINUTES_PER_HOUR = 60;
|
|
72
|
+
const SECONDS_PER_MINUTE = 60;
|
|
73
|
+
const MS_PER_SECOND = 1000;
|
|
74
|
+
const MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
|
|
75
|
+
function toEpochDay(value) {
|
|
76
|
+
const epoch = parseGenesisDateTime(value);
|
|
77
|
+
return epoch === null ? null : Math.floor(epoch / MS_PER_DAY);
|
|
78
|
+
}
|
|
79
|
+
// Expr.<fn>(field, value) function-call criteria, as emitted by
|
|
80
|
+
// foundation-criteria's serialisers.ts (contains/containsIgnoreCase/dateIs*)
|
|
81
|
+
// and foundation-ui's date-range filter.ts (dateTimeIsAfter/dateTimeIsBefore,
|
|
82
|
+
// which operator-map.ts maps onto the same >=/<= semantics as
|
|
83
|
+
// dateTimeIsGreaterEqual/dateTimeIsLessEqual). `dateIs*` compares by calendar
|
|
84
|
+
// day (UTC), `dateTimeIs*` compares full timestamps.
|
|
85
|
+
const EXPR_FUNCTIONS = {
|
|
86
|
+
// Multi-value fields (e.g. DEAL_CURRENCIES) may hold an array — treat
|
|
87
|
+
// "contains" as membership there, substring match on strings.
|
|
88
|
+
contains: (record, args, resolve) => {
|
|
89
|
+
const value = resolve(args[0], record);
|
|
90
|
+
const needle = resolve(args[1], record);
|
|
91
|
+
if (typeof needle !== 'string')
|
|
92
|
+
return false;
|
|
93
|
+
if (Array.isArray(value))
|
|
94
|
+
return value.some((v) => typeof v === 'string' && v === needle);
|
|
95
|
+
return typeof value === 'string' && value.includes(needle);
|
|
96
|
+
},
|
|
97
|
+
containsIgnoreCase: (record, args, resolve) => {
|
|
98
|
+
const value = resolve(args[0], record);
|
|
99
|
+
const needle = resolve(args[1], record);
|
|
100
|
+
if (typeof needle !== 'string')
|
|
101
|
+
return false;
|
|
102
|
+
const lowered = needle.toLowerCase();
|
|
103
|
+
if (Array.isArray(value)) {
|
|
104
|
+
return value.some((v) => typeof v === 'string' && v.toLowerCase() === lowered);
|
|
105
|
+
}
|
|
106
|
+
return typeof value === 'string' && value.toLowerCase().includes(lowered);
|
|
107
|
+
},
|
|
108
|
+
// Groovy/Java String methods the client emits in the FIELD.method(args)
|
|
109
|
+
// form — e.g. pbc-notify-ui's inbox subscribes with
|
|
110
|
+
// `((ALERT_STATUS.equals("NEW")))`. Without these the criteria fails to
|
|
111
|
+
// compile, the filter is dropped, and the grid shows every row instead of
|
|
112
|
+
// the filtered set.
|
|
113
|
+
equals: (record, args, resolve) => resolve(args[0], record) === resolve(args[1], record),
|
|
114
|
+
equalsIgnoreCase: (record, args, resolve) => {
|
|
115
|
+
const value = resolve(args[0], record);
|
|
116
|
+
const other = resolve(args[1], record);
|
|
117
|
+
if (typeof value !== 'string' || typeof other !== 'string')
|
|
118
|
+
return value === other;
|
|
119
|
+
return value.toLowerCase() === other.toLowerCase();
|
|
120
|
+
},
|
|
121
|
+
startsWith: (record, args, resolve) => {
|
|
122
|
+
const value = resolve(args[0], record);
|
|
123
|
+
const prefix = resolve(args[1], record);
|
|
124
|
+
return typeof value === 'string' && typeof prefix === 'string' && value.startsWith(prefix);
|
|
125
|
+
},
|
|
126
|
+
endsWith: (record, args, resolve) => {
|
|
127
|
+
const value = resolve(args[0], record);
|
|
128
|
+
const suffix = resolve(args[1], record);
|
|
129
|
+
return typeof value === 'string' && typeof suffix === 'string' && value.endsWith(suffix);
|
|
130
|
+
},
|
|
131
|
+
dateIsToday: (record, args, resolve) => {
|
|
132
|
+
const day = toEpochDay(resolve(args[0], record));
|
|
133
|
+
return day !== null && day === toEpochDay(Date.now());
|
|
134
|
+
},
|
|
135
|
+
dateIsEqual: (record, args, resolve) => compareByDay(record, args, resolve, (a, b) => a === b),
|
|
136
|
+
dateIsGreaterEqual: (record, args, resolve) => compareByDay(record, args, resolve, (a, b) => a >= b),
|
|
137
|
+
dateIsLessEqual: (record, args, resolve) => compareByDay(record, args, resolve, (a, b) => a <= b),
|
|
138
|
+
dateTimeIsEqual: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a === b),
|
|
139
|
+
dateTimeIsGreaterEqual: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a >= b),
|
|
140
|
+
dateTimeIsLessEqual: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a <= b),
|
|
141
|
+
dateTimeIsAfter: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a >= b),
|
|
142
|
+
dateTimeIsBefore: (record, args, resolve) => compareByTime(record, args, resolve, (a, b) => a <= b),
|
|
143
|
+
};
|
|
144
|
+
function compareByDay(record, args, resolve, cmp) {
|
|
145
|
+
const a = toEpochDay(resolve(args[0], record));
|
|
146
|
+
const b = toEpochDay(resolve(args[1], record));
|
|
147
|
+
return a !== null && b !== null && cmp(a, b);
|
|
148
|
+
}
|
|
149
|
+
function compareByTime(record, args, resolve, cmp) {
|
|
150
|
+
const a = parseGenesisDateTime(resolve(args[0], record));
|
|
151
|
+
const b = parseGenesisDateTime(resolve(args[1], record));
|
|
152
|
+
return a !== null && b !== null && cmp(a, b);
|
|
153
|
+
}
|
|
154
|
+
class Parser {
|
|
155
|
+
tokens;
|
|
156
|
+
pos = 0;
|
|
157
|
+
constructor(tokens) {
|
|
158
|
+
this.tokens = tokens;
|
|
159
|
+
}
|
|
160
|
+
get position() {
|
|
161
|
+
return this.pos;
|
|
162
|
+
}
|
|
163
|
+
peek() {
|
|
164
|
+
return this.tokens[this.pos];
|
|
165
|
+
}
|
|
166
|
+
next() {
|
|
167
|
+
const token = this.tokens[this.pos];
|
|
168
|
+
this.pos += 1;
|
|
169
|
+
return token;
|
|
170
|
+
}
|
|
171
|
+
parseExpression() {
|
|
172
|
+
return this.parseOr();
|
|
173
|
+
}
|
|
174
|
+
parseOr() {
|
|
175
|
+
let left = this.parseAnd();
|
|
176
|
+
while (this.peek() === '||' || this.peek()?.toUpperCase() === 'OR') {
|
|
177
|
+
this.next();
|
|
178
|
+
const right = this.parseAnd();
|
|
179
|
+
const prev = left;
|
|
180
|
+
left = (record) => prev(record) || right(record);
|
|
181
|
+
}
|
|
182
|
+
return left;
|
|
183
|
+
}
|
|
184
|
+
parseAnd() {
|
|
185
|
+
let left = this.parseNot();
|
|
186
|
+
while (this.peek() === '&&' || this.peek()?.toUpperCase() === 'AND') {
|
|
187
|
+
this.next();
|
|
188
|
+
const right = this.parseNot();
|
|
189
|
+
const prev = left;
|
|
190
|
+
left = (record) => prev(record) && right(record);
|
|
191
|
+
}
|
|
192
|
+
return left;
|
|
193
|
+
}
|
|
194
|
+
parseNot() {
|
|
195
|
+
const next = this.peek();
|
|
196
|
+
if (next === '!' || next?.toUpperCase() === 'NOT') {
|
|
197
|
+
this.next();
|
|
198
|
+
const operand = this.parseNot();
|
|
199
|
+
return (record) => !operand(record);
|
|
200
|
+
}
|
|
201
|
+
return this.parseComparison();
|
|
202
|
+
}
|
|
203
|
+
parseComparison() {
|
|
204
|
+
if (this.peek() === '(') {
|
|
205
|
+
this.next();
|
|
206
|
+
const inner = this.parseExpression();
|
|
207
|
+
if (this.next() !== ')')
|
|
208
|
+
throw new Error('Missing closing parenthesis in criteria');
|
|
209
|
+
return inner;
|
|
210
|
+
}
|
|
211
|
+
const leftToken = this.next();
|
|
212
|
+
if (leftToken === undefined) {
|
|
213
|
+
throw new Error('Expected operand on the left side of comparison');
|
|
214
|
+
}
|
|
215
|
+
// Both function-call dialects arrive as one dotted token followed by '(':
|
|
216
|
+
// 'Expr.containsIgnoreCase' (foundation-criteria) or
|
|
217
|
+
// 'DEAL_CURRENCIES.containsIgnoreCase' (field method-call form).
|
|
218
|
+
if (leftToken.includes('.') && this.peek() === '(') {
|
|
219
|
+
return this.parseFunctionCall(leftToken);
|
|
220
|
+
}
|
|
221
|
+
const op = this.peek();
|
|
222
|
+
if (!op || !COMPARATORS.has(op)) {
|
|
223
|
+
throw new Error(`Expected comparator, got: ${op}`);
|
|
224
|
+
}
|
|
225
|
+
this.next();
|
|
226
|
+
const rightToken = this.next();
|
|
227
|
+
if (rightToken === undefined) {
|
|
228
|
+
throw new Error('Expected operand on the right side of comparison');
|
|
229
|
+
}
|
|
230
|
+
const resolveLeft = (record) => this.resolveValue(leftToken, record);
|
|
231
|
+
const resolveRight = (record) => this.resolveValue(rightToken, record);
|
|
232
|
+
return (record) => {
|
|
233
|
+
const a = resolveLeft(record);
|
|
234
|
+
const b = resolveRight(record);
|
|
235
|
+
switch (op) {
|
|
236
|
+
case '==':
|
|
237
|
+
case '=':
|
|
238
|
+
return a === b;
|
|
239
|
+
case '!=':
|
|
240
|
+
case '<>':
|
|
241
|
+
return a !== b;
|
|
242
|
+
case '>':
|
|
243
|
+
return a > b;
|
|
244
|
+
case '>=':
|
|
245
|
+
return a >= b;
|
|
246
|
+
case '<':
|
|
247
|
+
return a < b;
|
|
248
|
+
case '<=':
|
|
249
|
+
return a <= b;
|
|
250
|
+
default:
|
|
251
|
+
return false;
|
|
252
|
+
}
|
|
253
|
+
};
|
|
254
|
+
}
|
|
255
|
+
resolveValue(token, record) {
|
|
256
|
+
const literal = parseLiteral(token);
|
|
257
|
+
if (literal !== undefined)
|
|
258
|
+
return literal;
|
|
259
|
+
return record[token];
|
|
260
|
+
}
|
|
261
|
+
parseFunctionCall(name) {
|
|
262
|
+
this.next(); // consume '('
|
|
263
|
+
const args = [];
|
|
264
|
+
if (this.peek() !== ')') {
|
|
265
|
+
const arg = this.next();
|
|
266
|
+
if (arg === undefined)
|
|
267
|
+
throw new Error(`Unterminated argument list in ${name}(...)`);
|
|
268
|
+
args.push(arg);
|
|
269
|
+
while (this.peek() === ',') {
|
|
270
|
+
this.next();
|
|
271
|
+
const nextArg = this.next();
|
|
272
|
+
if (nextArg === undefined)
|
|
273
|
+
throw new Error(`Unterminated argument list in ${name}(...)`);
|
|
274
|
+
args.push(nextArg);
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
if (this.next() !== ')')
|
|
278
|
+
throw new Error(`Missing closing parenthesis in ${name}(...)`);
|
|
279
|
+
// 'Expr.<fn>(field, value)' passes args through as-is; the method-call
|
|
280
|
+
// form '<FIELD>.<fn>(value)' makes the receiver field the implicit first
|
|
281
|
+
// argument, so both dialects share EXPR_FUNCTIONS.
|
|
282
|
+
const dotIndex = name.lastIndexOf('.');
|
|
283
|
+
const receiver = name.slice(0, dotIndex);
|
|
284
|
+
const fnName = name.slice(dotIndex + 1);
|
|
285
|
+
const handler = EXPR_FUNCTIONS[fnName];
|
|
286
|
+
if (!handler)
|
|
287
|
+
throw new Error(`Unsupported criteria function: ${name}`);
|
|
288
|
+
const allArgs = receiver === 'Expr' ? args : [receiver, ...args];
|
|
289
|
+
const resolve = (token, record) => this.resolveValue(token, record);
|
|
290
|
+
return (record) => handler(record, allArgs, resolve);
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
/** Compiles a CRITERIA_MATCH string into a predicate function(record) => boolean. */
|
|
294
|
+
export function compileCriteria(criteria) {
|
|
295
|
+
if (!criteria || typeof criteria !== 'string' || criteria.trim() === '') {
|
|
296
|
+
return () => true;
|
|
297
|
+
}
|
|
298
|
+
// Real Genesis clients can emit CRITERIA_MATCH syntax this grammar doesn't
|
|
299
|
+
// cover yet (e.g. function-call criteria like Expr.dateTimeIsGreaterEqual(...)
|
|
300
|
+
// from date-range filters). Failing open — matching everything and logging —
|
|
301
|
+
// keeps DATA_LOGON/broadcast working (unfiltered) instead of crashing the
|
|
302
|
+
// handler and leaving the client's grid stuck on "Loading...".
|
|
303
|
+
try {
|
|
304
|
+
const tokens = tokenize(criteria.trim());
|
|
305
|
+
const parser = new Parser(tokens);
|
|
306
|
+
const predicate = parser.parseExpression();
|
|
307
|
+
if (parser.position !== tokens.length) {
|
|
308
|
+
throw new Error(`Unexpected trailing tokens in criteria: ${criteria}`);
|
|
309
|
+
}
|
|
310
|
+
return predicate;
|
|
311
|
+
}
|
|
312
|
+
catch (error) {
|
|
313
|
+
console.warn(`[mock-server] Unsupported CRITERIA_MATCH syntax, ignoring filter: ${criteria}`, error);
|
|
314
|
+
return () => true;
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
export function filterByCriteria(rows, criteria) {
|
|
318
|
+
const predicate = compileCriteria(criteria);
|
|
319
|
+
return rows.filter((row) => {
|
|
320
|
+
try {
|
|
321
|
+
return predicate(row);
|
|
322
|
+
}
|
|
323
|
+
catch {
|
|
324
|
+
return false;
|
|
325
|
+
}
|
|
326
|
+
});
|
|
327
|
+
}
|