@genesislcap/mock-server 15.52.0 → 15.53.0

package/src/handlers/resources.ts

@@ -1,3 +1,4 @@
+import { crudEventNames } from '../db/schema.ts';
 import type { Connection } from '../protocol/connection.ts';
 import { MESSAGE_TYPE } from '../protocol/messageTypes.ts';
 import type { GenesisMessage, MockServerConfig, ResourceItem } from '../types.ts';
@@ -19,6 +20,8 @@ function deriveResources(config: MockServerConfig): ResourceItem[] {
   }
   const eventNames = new Set([
     ...Object.keys(config.eventHandlers ?? {}),
+    // The generic CRUD events tables register through TableDef.events.
+    ...crudEventNames(config),
     // Events served only by eventSchemas + defaultEventHandler still need to
     // be discoverable, or the client-side resource gate blocks them before
     // the commit is ever sent.

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
   AuthUser,
   BroadcastFn,
   BroadcastTableChangeFn,
+  CrudEventVerb,
   EventHandler,
   EventHandlerCtx,
   EventHandlerResult,

package/src/protocol/fieldTypes.ts

@@ -93,6 +93,13 @@ export function daoClassOf(table: string): string {
   return `global.genesis.gen.dao.${pascalCase(table)}`;
 }
 
+// The generated entity class of a view (ViewEntityGenerator.kt PACKAGE_NAME,
+// GSF v8.15.29): what a request server over the view names in
+// PARAMETRIC_TYPE.
+export function viewEntityClassOf(view: string): string {
+  return `global.genesis.gen.view.entity.${pascalCase(view)}`;
+}
+
 // The generated enum class of an ENUM column.
 export function enumClassOf(table: string | undefined, field: string, appName?: string): string {
   const segments = ['global.genesis.gen.dao.enums'];

package/src/protocol/msgNack.ts

@@ -1,6 +1,18 @@
 import type { Row } from '../types.ts';
+import type { NackErrorEntry } from './errors.ts';
 import { MESSAGE_TYPE } from './messageTypes.ts';
 
+// A service's own MSG_NACK (genesis-messages MsgNack): how a request server
+// answers a request it fails, GSF 8.15.x. Unlike the router's frame below, its
+// items are GenesisErrors (@type, a string CODE, TEXT, STATUS_CODE), there is
+// a WARNING list and no DETAILS. Recorded: a criteria-only REQ_ without
+// REQUEST answers {WARNING: [], ERROR: [{'@type': 'StandardError', CODE:
+// 'INTERNAL_ERROR', TEXT: 'Unexpected server error', STATUS_CODE: '500
+// Internal Server Error'}], MESSAGE_TYPE: 'MSG_NACK'}.
+export function serviceMsgNack(errors: NackErrorEntry[], warnings: NackErrorEntry[] = []): Row {
+  return { WARNING: warnings, ERROR: errors, MESSAGE_TYPE: MESSAGE_TYPE.MSG_NACK };
+}
+
 const HTTP_NOT_FOUND = 404;
 const HTTP_CONFLICT = 409;
 

package/src/protocol/schemaValidation.ts

@@ -0,0 +1,208 @@
+// Inbound schema validation, as GSF runs it on every event before any handler
+// sees it: GenesisMessageDecoder validates the whole message against the
+// event's JSON schema (the INBOUND that JSON_SCHEMA_REQUEST serves) and
+// answers each failure with a FieldError VALIDATION_ERROR. GSF 8.15.29 uses
+// networknt json-schema-validator 2.0.1, configured by
+// GenesisJsonSchemaFactory (draft 2019-09, PathType.LEGACY,
+// losslessNarrowing). This is the subset of that validator the engine's own
+// event schemas need: type, const, enum, oneOf, properties, required,
+// additionalProperties, minLength / maxLength, minimum / maximum and pattern.
+// Texts, locations and their order follow networknt's output, checked by
+// running the real validator on the recorded showcase schemas
+// (test/schemaValidation.test.ts pins the cases).
+//
+// Order: at each schema, `type` and then `properties` are checked first and
+// every other keyword after them in the schema's key order; `properties` in
+// their key order; unknown properties in the instance's order. A failed
+// `type` doesn't stop the rest (an enum still reports its own error).
+// `oneOf` with no valid branch reports itself, then every branch's errors.
+
+import type { NackErrorInput } from './errors.ts';
+
+type Schema = Record<string, any>;
+
+export interface SchemaError {
+  keyword: string;
+  // PathType.LEGACY: '$', '$.DETAILS', '$.DETAILS.NAME'.
+  instanceLocation: string;
+  // The missing property, for `required`; the unknown one, for
+  // `additionalProperties`.
+  property?: string;
+  message: string;
+}
+
+// networknt's JsonType names. With losslessNarrowing a number with no
+// fraction is an integer (1.0 included, which JSON.parse makes 1 anyway).
+function jsonTypeOf(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'number';
+  return typeof value;
+}
+
+function matchesType(value: unknown, type: string): boolean {
+  const actual = jsonTypeOf(value);
+  return actual === type || (type === 'number' && actual === 'integer');
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (isObject(a) && isObject(b)) {
+    const keys = Object.keys(a);
+    return (
+      keys.length === Object.keys(b).length &&
+      keys.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key]))
+    );
+  }
+  return false;
+}
+
+// networknt evaluates these before a schema's other keywords, whatever their
+// position; the rest go in key order.
+const FIRST_KEYWORDS = ['type', 'properties'];
+
+// String lengths count code points, as Java's codePointCount does.
+const codePoints = (text: string) => [...text].length;
+
+interface KeywordCheck {
+  arg: any;
+  schema: Schema;
+  value: unknown;
+  location: string;
+  errors: SchemaError[];
+  fail(message: string, property?: string): void;
+}
+
+const NOT_DEFINED =
+  'is not defined in the schema and the schema does not allow additional properties';
+
+// One check per keyword, each a no-op on values it doesn't apply to (string
+// keywords on non-strings, object keywords on non-objects, ...).
+const KEYWORDS: Record<string, (check: KeywordCheck) => void> = {
+  type({ arg, value, fail }) {
+    if (typeof arg === 'string' && !matchesType(value, arg)) {
+      fail(`${jsonTypeOf(value)} found, ${arg} expected`);
+    }
+  },
+  const({ arg, value, fail }) {
+    if (!deepEqual(value, arg)) fail(`must be the constant value '${String(arg)}'`);
+  },
+  enum({ arg, value, fail }) {
+    if (Array.isArray(arg) && !arg.some((candidate) => deepEqual(value, candidate))) {
+      const values = arg.map((item) => JSON.stringify(item)).join(', ');
+      fail(`does not have a value in the enumeration [${values}]`);
+    }
+  },
+  minLength({ arg, value, fail }) {
+    if (typeof value === 'string' && codePoints(value) < arg) {
+      fail(`must be at least ${arg} characters long`);
+    }
+  },
+  maxLength({ arg, value, fail }) {
+    if (typeof value === 'string' && codePoints(value) > arg) {
+      fail(`must be at most ${arg} characters long`);
+    }
+  },
+  minimum({ arg, value, fail }) {
+    if (typeof value === 'number' && value < arg) fail(`must have a minimum value of ${arg}`);
+  },
+  maximum({ arg, value, fail }) {
+    if (typeof value === 'number' && value > arg) fail(`must have a maximum value of ${arg}`);
+  },
+  // JSON Schema patterns are unanchored: '[0-9]+' accepts 'x1y'.
+  pattern({ arg, value, fail }) {
+    if (typeof value === 'string' && !new RegExp(arg, 'u').test(value)) {
+      fail(`does not match the regex pattern ${arg}`);
+    }
+  },
+  oneOf({ arg, value, location, errors, fail }) {
+    if (!Array.isArray(arg)) return;
+    const results = arg.map((branch: Schema) => validateSchema(branch, value, location));
+    const valid = results.flatMap((result, index) => (result.length === 0 ? [index] : []));
+    if (valid.length === 1) return;
+    if (valid.length > 1) {
+      fail(
+        `must be valid to one and only one schema, but ${valid.length} are valid with indexes '${valid.join(', ')}'`,
+      );
+      return;
+    }
+    fail('must be valid to one and only one schema, but 0 are valid');
+    errors.push(...results.flat());
+  },
+  properties({ arg, value, location, errors }) {
+    if (!isObject(value) || !isObject(arg)) return;
+    for (const [name, propertySchema] of Object.entries(arg)) {
+      if (!Object.hasOwn(value, name)) continue;
+      errors.push(...validateSchema(propertySchema as Schema, value[name], `${location}.${name}`));
+    }
+  },
+  required({ arg, value, fail }) {
+    if (!isObject(value) || !Array.isArray(arg)) return;
+    for (const name of arg) {
+      if (!Object.hasOwn(value, name)) fail(`required property '${name}' not found`, name);
+    }
+  },
+  additionalProperties({ arg, schema, value, location, errors, fail }) {
+    if (!isObject(value) || (arg !== false && !isObject(arg))) return;
+    const known = isObject(schema.properties) ? schema.properties : {};
+    for (const name of Object.keys(value)) {
+      if (Object.hasOwn(known, name)) continue;
+      if (arg === false) fail(`property '${name}' ${NOT_DEFINED}`, name);
+      else errors.push(...validateSchema(arg, value[name], `${location}.${name}`));
+    }
+  },
+  // Anything else is an annotation (description, title, default, readOnly,
+  // genesisType, $schema, $defs, ...) and validates nothing; networknt
+  // doesn't enforce readOnly unless asked to.
+};
+
+export function validateSchema(schema: Schema, value: unknown, location = '$'): SchemaError[] {
+  const errors: SchemaError[] = [];
+  if (!isObject(schema)) return errors;
+  const keywords = Object.keys(schema);
+  const ordered = [
+    ...FIRST_KEYWORDS.filter((keyword) => keywords.includes(keyword)),
+    ...keywords.filter((keyword) => !FIRST_KEYWORDS.includes(keyword)),
+  ];
+  for (const keyword of ordered) {
+    if (!Object.hasOwn(KEYWORDS, keyword)) continue;
+    KEYWORDS[keyword]({
+      arg: schema[keyword],
+      schema,
+      value,
+      location,
+      errors,
+      fail: (message, property) =>
+        errors.push({
+          keyword,
+          instanceLocation: location,
+          ...(property !== undefined ? { property } : {}),
+          message,
+        }),
+    });
+  }
+  return errors;
+}
+
+// GenesisMessageDecoder's FieldError for each failure: TEXT is the error's
+// toString() ("<location>: <message>"), FIELD the missing property for
+// `required` and otherwise the last segment of the location (so an unknown
+// DETAILS property names 'DETAILS'), PATH the location.
+export function schemaFieldErrors(errors: SchemaError[]): NackErrorInput[] {
+  return errors.map((error) => ({
+    '@type': 'FieldError',
+    CODE: 'VALIDATION_ERROR',
+    TEXT: `${error.instanceLocation}: ${error.message}`,
+    FIELD:
+      error.keyword === 'required'
+        ? error.property
+        : error.instanceLocation.slice(error.instanceLocation.lastIndexOf('.') + 1),
+    PATH: error.instanceLocation,
+  }));
+}

package/src/server.ts

@@ -1,6 +1,7 @@
 import http from 'node:http';
 import { WebSocketServer, type WebSocket } from 'ws';
 import { Store } from './db/store.ts';
+import { crudEventHandler } from './handlers/crudEvents.ts';
 import { pendingKey } from './handlers/dataLogon.ts';
 import { createHttpRequestListener } from './handlers/http.ts';
 import { permittedQueryRow, requestingUser } from './handlers/resourceAuth.ts';
@@ -384,8 +385,11 @@ export function createMockServer(config: MockServerConfig): MockServer {
     return config.requestReplies?.[resourceName];
   }
 
+  // An eventHandlers entry, else the generic CRUD handler a table registers
+  // (TableDef.events) — so extendEventHandler can wrap a generic event; the
+  // wrapper is then an explicit handler, which wins.
   function getEventHandler(eventName: string): EventHandler | undefined {
-    return config.eventHandlers?.[eventName];
+    return config.eventHandlers?.[eventName] ?? crudEventHandler(eventName, config);
   }
 
   // augment(current) => replacement. `current` is undefined if nothing was

package/src/types.ts

@@ -66,17 +66,22 @@ export interface FieldDef {
   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.
+// A field the database fills on insert when the record leaves it out (a
+// supplied value is kept). Metadata marks it NULLABLE:false, OPTIONAL:true
+// and leaves it out of `required`. A SEQUENCE mints values like the key's
+// sequence (`prefix`, else the table's sequencePrefix, in its
+// sequenceFormat); an AUTO_INCREMENT counts up from the highest seeded value
+// (1 when there is none). A table with `sequencePrefix` gets its key
+// generated as a SEQUENCE without declaring it here.
 export interface GeneratedFieldDef {
   field: string;
   kind: 'SEQUENCE' | 'AUTO_INCREMENT';
   prefix?: string;
 }
 
+// The verbs of the generic CRUD events (see TableDef.events).
+export type CrudEventVerb = 'INSERT' | 'MODIFY' | 'DELETE';
+
 // A table or dataserver-query index (`indices { unique("A") }`). FIELDS is
 // sent space-separated (`'A B'`).
 export interface IndexDef {
@@ -103,10 +108,22 @@ export interface TableDef {
   // 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.
+  // Table indices. The generic CRUD events NACK DUPLICATE_KEY on a unique
+  // one, and a unique index over exactly the key fields names the primary
+  // key (else '<TABLE>_BY_<fields>'). A dataserver query only reports the
+  // indices on its own QueryDef.indexes, as the real dataserver does.
   indexes?: IndexDef[];
+  // Registers generic CRUD event handlers for this table —
+  // EVENT_<TABLE>_INSERT, EVENT_<TABLE>_MODIFY, EVENT_<TABLE>_DELETE — the
+  // ones Genesis Create generates (entityDb.insert / modify / delete, no
+  // onValidate): insert the record (generating sequence and auto-increment
+  // fields, GENERATED listing them all; DUPLICATE_KEY on a taken key), modify
+  // or delete it by its primary key (RECORD_NOT_FOUND), ack VALIDATE without
+  // writing, push the change live. They are listed in RESOURCES and described
+  // by META_REQUEST / JSON_SCHEMA_REQUEST like any registered event. An
+  // eventHandlers entry of the same name wins. See the README's "Generic CRUD
+  // events".
+  events?: CrudEventVerb[];
 }
 
 // 'prefix' (the default): sequencePrefix + a counter padded to sequenceWidth
@@ -210,26 +227,41 @@ export interface RequestReplyDef {
   // (`resolver`) — for request servers that calculate rather than read (date
   // calculations, holiday validate/roll, premium schedules, composite
   // lookups). A resolver receives the REQUEST fields and returns the REPLY
-  // rows verbatim; throw NackError for a protocol-correct error reply. When
-  // both are set, resolver wins. With resolver only, set `metadataRows` (a
-  // representative sample reply) or `fieldTypes` so META_REQUEST can still
-  // derive REPLY_FIELD metadata.
+  // rows verbatim; throw NackError for a protocol-correct error reply (a
+  // MSG_NACK). When both are set, resolver wins. With resolver only, set
+  // `metadataRows` (a representative sample reply) or `fieldTypes` so
+  // META_REQUEST can still derive REPLY_FIELD metadata.
   source?: string;
   resolver?: (ctx: RequestReplyResolverCtx) => Row[];
   metadataRows?: Row[];
   fieldTypes?: Record<string, string>;
+  // The request server's `filter { }` / `where { }` clause. With `filter` or
+  // `auth`, a criteria-only server reads past the rows they drop, and
+  // NEXT_OFFSET says where it stopped (README: Request servers).
   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.
+  // `criteriaOnlyRequest = true` in the request server's config. REQUEST must
+  // then be present (an object; its fields are ignored), DETAILS.OFFSET pages,
+  // DETAILS.ORDER_BY sorts by fields, and every REP_ carries MORE_ROWS (plus
+  // NEXT_OFFSET while there are more). META_REQUEST reports REQUEST_FIELD: [],
+  // CRITERIA_ONLY_REQUEST: true, SORTABLE_FIELDS and CRITERIA_FIELDS. Without
+  // it, REQUEST's fields select rows (exact values, `*` wildcards,
+  // FIELD_FROM/FIELD_TO ranges; an array runs each) and OFFSET is ignored.
+  // See the README's "Request servers".
   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[];
+  // The reply block (`reply { }` in GPAL): REP_ rows carry exactly these
+  // columns, in this order, null when unset, and so do REPLY_FIELD and the JSON
+  // schema's REPLY. Names a declared source doesn't have are dropped.
+  // RECORD_ID and TIMESTAMP are sent only when named here. Unset: every column
+  // of the source followed by RECORD_ID and TIMESTAMP, as GSF sends a table
+  // entity. Ignored with a resolver.
+  fields?: string[];
+  // `config { maxRows = N }`: the most rows a REP_ carries when the request
+  // names no DETAILS.MAX_ROWS. Default 10000 (RequestReply.DEFAULT_MAXIMUM_ROWS).
+  rowLimit?: number;
 }
 
 // How META_REQUEST / JSON_SCHEMA_REQUEST describe an event whose name doesn't
@@ -312,6 +344,12 @@ export interface EventHandlerCtx {
   message: GenesisMessage;
   broadcast: BroadcastFn;
   broadcastTableChange: BroadcastTableChangeFn;
+  // `VALIDATE: true` on the message: the client asks whether the event would
+  // succeed. GSF then runs only the handler's onValidate and answers its NACK,
+  // or an EVENT_ACK with GENERATED: [] — nothing is written. A handler that
+  // writes should run its checks and return before writing when this is set;
+  // the generic CRUD events do.
+  validate: boolean;
 }
 
 // `warnings` turns the reply into an EVENT_NACK carrying them in WARNING