@genesislcap/mock-server 15.51.0 → 15.52.0

package/src/server.ts

@@ -3,11 +3,11 @@ import { WebSocketServer, type WebSocket } from 'ws';
 import { Store } from './db/store.ts';
 import { pendingKey } from './handlers/dataLogon.ts';
 import { createHttpRequestListener } from './handlers/http.ts';
-import { applyResourceAuth, requestingUser } from './handlers/resourceAuth.ts';
+import { permittedQueryRow, requestingUser } from './handlers/resourceAuth.ts';
 import { Connection, type Subscription } from './protocol/connection.ts';
 import { isLegacyFidelity } from './protocol/fidelity.ts';
 import { routeMessage } from './protocol/router.ts';
-import { stampRow, type RowOperation } from './protocol/rowUpdate.ts';
+import { dataserverRow, stampRow, type RowOperation } from './protocol/rowUpdate.ts';
 import type {
   BroadcastFn,
   BroadcastTableChangeFn,
@@ -141,9 +141,10 @@ export function createMockServer(config: MockServerConfig): MockServer {
     const permitted =
       operation === 'DELETE'
         ? undefined
-        : applyResourceAuth([row], query?.auth, requestingUser(connection))[0];
+        : permittedQueryRow(row, query?.auth, requestingUser(connection), subscription.fieldNames);
     if (pending.has(key)) {
-      if (permitted) pending.set(key, stampRow(permitted, rowRef, 'INSERT'));
+      if (permitted)
+        pending.set(key, stampRow(dataserverRow(permitted, row, query?.fields), rowRef, 'INSERT'));
       else pending.delete(key);
       return null;
     }
@@ -153,11 +154,22 @@ export function createMockServer(config: MockServerConfig): MockServer {
       return 'DELETE';
     }
     if (!permitted) return null;
+    // Under ORDER_BY, a new row that sorts among the waiting ones waits too,
+    // so MORE_ROWS pages stay in order.
+    if (
+      subscription.queueInsert?.(
+        key,
+        stampRow(dataserverRow(permitted, row, query?.fields), rowRef, 'INSERT'),
+        row,
+      )
+    )
+      return null;
+
     held.add(key);
     return 'INSERT';
   }
 
-  const broadcast: BroadcastFn = (resourceName, operation, row) => {
+  function pushChange(resourceName: string, operation: RowOperation, row: Row): void {
     const query = config.queries?.[resourceName];
     // The query's own filter (where-clause equivalent) applies to live pushes
     // too — a row the snapshot would exclude must not leak in via broadcast.
@@ -188,19 +200,27 @@ export function createMockServer(config: MockServerConfig): MockServer {
           ? trackClientView(subscription, connection, query, resolved, row, rowRef)
           : resolved;
         if (rowOperation === null) continue;
+        const legacy = isLegacyFidelity(config);
         let outRow = row;
         if (rowOperation === 'DELETE') {
-          // A change turned into a DELETE: send the row identity only — it is
-          // all the client needs to drop the row, and the full row may carry
-          // columns this user's hideFields strips. (A real DELETE's row is a
-          // stub already.)
-          if (operation !== 'DELETE') {
+          // GSF's DELETE row is DETAILS {OPERATION, ROW_REF} and nothing else.
+          // Legacy mode sent the pk fields: the stub it was given for a real
+          // DELETE, or one rebuilt from the key for a change that left the
+          // subscription (the full row may carry columns hideFields strips).
+          if (!legacy) outRow = {};
+          else if (operation !== 'DELETE') {
             outRow = query ? store.rowStubFromKey(query.source, rowRef as string) : row;
           }
-        } else if (query?.auth) {
-          const [permitted] = applyResourceAuth([row], query.auth, requestingUser(connection));
+        } else {
+          // Only the subscription's columns, minus the ones this user can't see.
+          const permitted = permittedQueryRow(
+            row,
+            query?.auth,
+            requestingUser(connection),
+            subscription.fieldNames,
+          );
           if (!permitted) continue;
-          outRow = permitted;
+          outRow = dataserverRow(permitted, row, query?.fields);
         }
         subscription.sequenceId += 1;
         // A live push carries neither MORE_ROWS nor ROWS_COUNT on the real
@@ -208,12 +228,33 @@ export function createMockServer(config: MockServerConfig): MockServer {
         connection.send({
           MESSAGE_TYPE: 'QUERY_UPDATE',
           SOURCE_REF: sourceRef,
-          ROW: [stampRow(outRow, rowRef, rowOperation)],
-          ...(isLegacyFidelity(config) ? { ROWS_COUNT: 1 } : {}),
+          ROW: [stampRow(outRow, rowRef, rowOperation, legacy)],
+          ...(legacy ? { ROWS_COUNT: 1 } : {}),
           SEQUENCE_ID: subscription.sequenceId,
         });
       }
     }
+  }
+
+  // Pushes an unsolicited row update to every subscription on the resource
+  // (see pushChange). A DELETE given as a pk-only row is resolved to the
+  // record(s) removed from that key that no broadcast has announced yet —
+  // their RECORD_IDs are the ROW_REFs a client may hold — and those are
+  // consumed, so a later delete of a re-inserted key names its own record.
+  const broadcast: BroadcastFn = (resourceName, operation, row) => {
+    const source = config.queries?.[resourceName]?.source;
+    if (operation !== 'DELETE' || !source) {
+      pushChange(resourceName, operation, row);
+      return;
+    }
+    const removed = store.takeRemovedRecordsFor(source, row);
+    if (isLegacyFidelity(config)) {
+      pushChange(resourceName, operation, row);
+      return;
+    }
+    const records = row.RECORD_ID === undefined || row.RECORD_ID === null ? removed : [row];
+    if (records.length === 0) records.push(row);
+    for (const record of records) pushChange(resourceName, 'DELETE', record);
   };
 
   // Event handlers mutate one table (e.g. TRADE) but grids may be subscribed to
@@ -221,8 +262,26 @@ export function createMockServer(config: MockServerConfig): MockServer {
   // query resource backed by that table — directly or via a view — and pushes
   // the (re-joined, for views) row to each one's subscribers. `pk` is the
   // store key: the single pk field's value, or store.rowKey(...) for
-  // composite-keyed tables.
+  // composite-keyed tables. ROW_REF is the record's RECORD_ID, so a DELETE is
+  // broadcast with every record the key lost that no broadcast announced yet
+  // (Store.takeRemovedRows; held-rows tracking drops the ones a client
+  // doesn't hold), and a record replaced under the same key (deleted, then
+  // re-inserted, before one broadcast) gets a DELETE of its old ROW_REF before
+  // the new one goes out. A view row is built from the changed base row
+  // alone, so it is found whatever the view's own pkField; a MODIFY that takes
+  // it out of the view (an anti-join) is pushed as a DELETE. Legacy ROW_REFs
+  // are the key itself, so there a DELETE is the pk stub and a replacement is
+  // the one INSERT/MODIFY, as before.
   const broadcastTableChange: BroadcastTableChangeFn = (tableName, operation, pk) => {
+    const legacy = isLegacyFidelity(config);
+    const current = operation === 'DELETE' ? undefined : store.getRow(tableName, pk);
+    let removed = store
+      .takeRemovedRows(tableName, pk)
+      .filter((record) => record.RECORD_ID !== current?.RECORD_ID);
+    // A DELETE broadcast before the row is removed still names it.
+    const live = store.getRow(tableName, pk);
+    if (operation === 'DELETE' && removed.length === 0 && live) removed = [live];
+    if (legacy) removed = [];
     for (const [queryName, query] of Object.entries(config.queries ?? {})) {
       const isDirect = query.source === tableName;
       const view = store.views.get(query.source);
@@ -242,23 +301,38 @@ export function createMockServer(config: MockServerConfig): MockServer {
 
       if (isViewJoiningTable) {
         for (const viewRow of store.getViewRows(query.source)) {
-          broadcast(queryName, 'MODIFY', viewRow);
+          pushChange(queryName, 'MODIFY', viewRow);
         }
         continue;
       }
 
-      let row: Row | undefined;
+      // The removed base records carry the RECORD_ID a view row's ROW_REF
+      // comes from too; the DELETE body is DETAILS only either way.
+      for (const record of removed) pushChange(queryName, 'DELETE', record);
       if (operation === 'DELETE') {
-        const stub = store.rowStubFromKey(query.source, pk);
-        row = Object.keys(stub).length > 0 ? stub : undefined;
-      } else if (isDirect) {
-        row = store.getRow(tableName, pk);
-      } else {
-        row = store
-          .getViewRows(query.source)
-          .find((r) => String(store.getRowRef(query.source, r)) === String(pk));
+        if (legacy) {
+          const stub = store.rowStubFromKey(query.source, pk);
+          if (Object.keys(stub).length > 0) pushChange(queryName, 'DELETE', stub);
+        }
+        continue;
+      }
+      if (!current) continue;
+      if (isDirect) {
+        pushChange(queryName, operation, current);
+        continue;
+      }
+      const viewRow = store.getViewRows(query.source, { [tableName]: [current] })[0];
+      if (viewRow) {
+        pushChange(queryName, operation, viewRow);
+      } else if (operation === 'MODIFY') {
+        pushChange(
+          queryName,
+          'DELETE',
+          legacy
+            ? store.rowStubFromKey(query.source, store.getRowRef(query.source, current) as string)
+            : current,
+        );
       }
-      if (row) broadcast(queryName, operation, row);
     }
   };
 

package/src/types.ts

@@ -4,6 +4,7 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Store } from './db/store.ts';
+import type { NackErrorInput } from './protocol/errors.ts';
 
 export type Row = Record<string, any>;
 
@@ -14,6 +15,76 @@ export interface GenesisMessage {
   [key: string]: any;
 }
 
+// The Genesis dictionary field types (global.genesis.dictionary.Field.Type).
+export type GenesisFieldType =
+  | 'STRING'
+  | 'ENUM'
+  | 'INT'
+  | 'SHORT'
+  | 'LONG'
+  | 'DOUBLE'
+  | 'BIGDECIMAL'
+  | 'BOOLEAN'
+  | 'DATE'
+  | 'DATETIME'
+  | 'NANO_TIMESTAMP'
+  | 'RAW';
+
+// One column of a table, as the project's tables dictionary declares it
+// (`field("NAME", STRING(100)).notNull()`). META_REQUEST and
+// JSON_SCHEMA_REQUEST are built from these when a table declares them; see the
+// README's "Declared schema".
+export interface FieldDef {
+  name: string;
+  type: GenesisFieldType;
+  // Default true, as in the dictionary (`.notNull()` makes it false). Primary
+  // key and generated fields default to false.
+  nullable?: boolean;
+  // ENUM values, in dictionary order.
+  values?: string[];
+  // The dictionary `.default(...)`. A non-null field with a default is
+  // optional in event schemas.
+  default?: unknown;
+  // STRING column size (`STRING(100)`): MAX_LENGTH / maxLength.
+  maxSize?: number;
+  // `metadata { minLength = 0 }`: MIN_LENGTH / minLength.
+  minLength?: number;
+  // Replaces the DESCRIPTION / description the real server fills with the
+  // field's JVM class (kotlin.String, org.joda.time.DateTime, ...). Leave it
+  // unset for DATE/DATETIME: foundation-forms recognises dates partly by that
+  // class name.
+  description?: string;
+  // Defaults to the name in title case ('COUNTERPARTY_ID' -> 'Counterparty Id').
+  title?: string;
+  // Whether an event payload may leave it out (OPTIONAL, and not in the JSON
+  // schema's `required`). The real server makes a field optional only when
+  // its class property has a default. Unset: a table field is optional when
+  // it is nullable, generated or has a default (the generated DAO defaults
+  // all of those); a custom DTO field only when it has a `default` — set
+  // `optional: true` for a Kotlin default the metadata can't show, such as
+  // `val enabled: Boolean? = true`.
+  optional?: boolean;
+}
+
+// A field the database fills on insert. Declares the shape only: metadata
+// marks it NULLABLE:false, OPTIONAL:true and leaves it out of `required`.
+// Value generation still comes from `sequencePrefix` (single-field keys).
+// A table with `sequencePrefix` gets its key marked as a SEQUENCE without
+// declaring it here.
+export interface GeneratedFieldDef {
+  field: string;
+  kind: 'SEQUENCE' | 'AUTO_INCREMENT';
+  prefix?: string;
+}
+
+// A table or dataserver-query index (`indices { unique("A") }`). FIELDS is
+// sent space-separated (`'A B'`).
+export interface IndexDef {
+  name: string;
+  fields: string[];
+  unique?: boolean;
+}
+
 export interface TableDef {
   // A single field, or several for composite-keyed tables (e.g. PRICE keyed
   // by [RFQ_ID, SIDE]). Composite rows are identified by the fields' values
@@ -23,9 +94,28 @@ export interface TableDef {
   pkField: string | string[];
   sequencePrefix?: string;
   sequenceWidth?: number;
+  // How generated pk values look. See SequenceFormat.
+  sequenceFormat?: SequenceFormat;
   rows?: Row[];
+  // Declared columns, in dictionary order. When present they are the schema:
+  // metadata, JSON schemas and dataserver rows follow them (missing values go
+  // out as null), even with no rows at all. When absent, field metadata is
+  // inferred from the rows (src/db/metadata.ts).
+  fields?: FieldDef[];
+  generated?: GeneratedFieldDef[];
+  // Table indices. Declared for later items (ORDER_BY, duplicate keys); a
+  // dataserver query only reports the indices on its own QueryDef.indexes, as
+  // the real dataserver does.
+  indexes?: IndexDef[];
 }
 
+// 'prefix' (the default): sequencePrefix + a counter padded to sequenceWidth
+// ('TR001'). 'genesis': the platform's id format (genesis-db IdStrategy.java)
+// — the counter padded to 15 digits, the sequence id (sequencePrefix, two
+// characters in a GSF dictionary), then location 'LO' and system '1':
+// '000000000000001TRLO1'.
+export type SequenceFormat = 'prefix' | 'genesis';
+
 export interface JoinDef {
   table: string;
   on: [string, string];
@@ -53,6 +143,16 @@ export interface ViewDef {
   joins?: JoinDef[];
   antiJoins?: AntiJoinDef[];
   derived?: Record<string, (row: Row) => any>;
+  // Types of the `derived` fields (`derivedField("TOTAL", DOUBLE)`): a type,
+  // or a full field definition without its name. Columns from the base table
+  // and from `joins[].select` take their declared types from their source
+  // tables; a derived field with no entry here is inferred from the rows.
+  derivedTypes?: Record<string, GenesisFieldType | Omit<FieldDef, 'name'>>;
+  // The view's fields { } block: the only columns it exposes, in this order
+  // (base, joined and derived alike). Unset: every base column, then each
+  // join's select, then the derived fields. Keep the key fields in it — they
+  // are the ROW_REF.
+  fields?: string[];
 }
 
 // The authenticated identity a resource-level auth hook sees. userName is
@@ -76,7 +176,17 @@ export interface ResourceAuthDef {
 
 export interface QueryDef {
   source: string;
+  // Overrides the TYPE of named fields, declared or inferred.
   fieldTypes?: Record<string, string>;
+  // The query's `fields { }` block: the only columns it exposes, in this
+  // order, in rows and in META_REQUEST. Names the source doesn't have are
+  // dropped from metadata. RECORD_ID and TIMESTAMP reach dataserver rows only
+  // when named here.
+
+  fields?: string[];
+  // The query's `indices { }` block, reported as META_REQUEST INDEXES. With
+  // none, INDEXES is the default [{NAME: null, FIELDS: 'RECORD_ID'}].
+  indexes?: IndexDef[];
   // Server-side where-clause equivalent, applied before any client
   // CRITERIA_MATCH — to both the DATA_LOGON snapshot and live pushes. Use it
   // for things the real query's filter/where clause does (e.g. keep template
@@ -110,12 +220,35 @@ export interface RequestReplyDef {
   fieldTypes?: Record<string, string>;
   filter?: (row: Row) => boolean;
   auth?: ResourceAuthDef;
+  // `criteriaOnlyRequest = true` in the request server's config: META_REQUEST
+  // then reports REQUEST_FIELD: [], CRITERIA_ONLY_REQUEST: true,
+  // SORTABLE_FIELDS and CRITERIA_FIELDS, and adds RECORD_ID and TIMESTAMP to
+  // REPLY_FIELD. Metadata only for now: OFFSET paging is not implemented, and
+  // grid-pro's server-side and infinite row models page a criteria-only
+  // resource with OFFSET.
+  criteriaOnly?: boolean;
+  // The request block's fields (REQUEST_FIELD, and the JSON schema's REQUEST).
+  // Defaults to the source's primary key, as for a GPAL requestReply(TABLE).
+  requestFields?: string[];
 }
 
+// How META_REQUEST / JSON_SCHEMA_REQUEST describe an event whose name doesn't
+// follow EVENT_<TABLE>_<VERB>: the table (or view) its DETAILS take, and
+// whether only the key fields are sent (a delete).
 export interface EventSchemaOverride {
   table?: string;
   pkOnly?: boolean;
   fieldTypes?: Record<string, string>;
+  // The event's own DETAILS class, for an event that takes a custom DTO
+  // (`eventHandler<MyInput>`) rather than a table row. Described as the real
+  // server describes a non-table class: no titles, lengths, ranges or
+  // genesis types; `nullable`, `default` and `optional` as declared. A
+  // nullable field is still mandatory unless it has a default or
+  // `optional: true` (Kotlin `val x: T?` must be sent; `val x: T? = null`
+  // needn't be). `table` then only names where its ENUM columns come from.
+  fields?: FieldDef[];
+  // The DTO's class name, reported as the event's DESCRIPTION.
+  className?: string;
 }
 
 export interface ResourceItem {
@@ -181,7 +314,11 @@ export interface EventHandlerCtx {
   broadcastTableChange: BroadcastTableChangeFn;
 }
 
-export type EventHandlerResult = { generated?: Row[] } | void;
+// `warnings` turns the reply into an EVENT_NACK carrying them in WARNING
+// (with an empty ERROR), as a GSF handler's warning-only EventNack does.
+// Return them from a handler that has not written anything yet: the mock has
+// no transaction to roll back, and doesn't honour IGNORE_WARNINGS yet.
+export type EventHandlerResult = { generated?: Row[]; warnings?: NackErrorInput[] } | void;
 
 export type EventHandler = (details: Row, ctx: EventHandlerCtx) => EventHandlerResult;
 
@@ -245,11 +382,18 @@ export interface MockServerConfig {
   httpRoutes?: HttpRouteDef[];
   onMessage?: OnMessageHook;
   productName?: string;
+  // The Genesis application name, as in the generated enum classes the real
+  // server names in event metadata
+  // (global.genesis.gen.dao.enums.<appName>.<table>.<Field>). Unset: the
+  // segment is left out. Nothing a client does depends on it.
+  appName?: string;
 }
 
+// A META_REQUEST FIELD / REQUEST_FIELD / REPLY_FIELD entry.
 export interface FieldMetadata {
   NAME: string;
   TYPE: string;
+  VALID_VALUES?: string[];
 }
 
 // Minimal shape both `ws`'s WebSocket and Bun's ServerWebSocket satisfy —