@genesislcap/mock-server 15.49.0 → 15.50.0

package/src/server.ts

@@ -1,9 +1,11 @@
 import http from 'node:http';
 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 { 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 type {
@@ -65,8 +67,9 @@ export function createMockServer(config: MockServerConfig): MockServer {
   // grids reflect inserts/amends/deletes without the client re-querying.
   // DELETE rows are PK-only stubs (see broadcastTableChange), so a criteria
   // predicate would evaluate against missing fields and drop the push —
-  // leaving the client holding a ghost row. Deliver every DELETE instead: a
-  // client that never held that ROW_REF ignores it.
+  // leaving the client holding a ghost row. A DELETE therefore skips the
+  // predicate; which subscriptions it reaches is decided by what each client
+  // holds (trackClientView), or, in legacy mode, it reaches all of them.
   // 'error' is kept distinct from 'no-match' because only a clean no-match may
   // be turned into a DELETE below; a broken predicate must not evict rows.
   function evaluateSubscription(
@@ -103,6 +106,57 @@ export function createMockServer(config: MockServerConfig): MockServer {
     return operation === 'MODIFY' ? 'DELETE' : null;
   }
 
+  // Decides what one 'gsf' subscription's client gets for a live change, from
+  // what that client holds — as the real dataserver does with its client
+  // index — and keeps the subscription's pending/held sets up to date.
+  // `operation` is the change after the query filter and CRITERIA_MATCH
+  // (a MODIFY that left them arrives as a DELETE); the user's rowFilter is
+  // applied here too, so leaving it counts as leaving the subscription.
+  // - A row still waiting for MORE_ROWS (past the page, or past MAX_VIEW) is
+  //   never pushed: the client has never seen it. A change replaces the
+  //   waiting copy in place, so the page later delivers current values; a
+  //   DELETE drops it.
+  // - A held row gets the MODIFY, or a DELETE when it is gone or out of scope.
+  // - A row the client doesn't hold that is (now) in scope is pushed as an
+  //   INSERT and becomes held: a brand-new row, or one a MODIFY brought back
+  //   into the criteria. Out of scope, the client is told nothing.
+  // An INSERT is pushed even when the view already holds MAX_VIEW rows; the
+  // real server would also evict the oldest row in the same frame (moving
+  // view), which this engine doesn't, so the view can grow past MAX_VIEW.
+  // A row without a ROW_REF can't be matched to anything the client holds,
+  // so changes to it aren't pushed.
+  // Returns the operation to push, or null to push nothing.
+  function trackClientView(
+    subscription: Subscription,
+    connection: Connection,
+    query: QueryDef | undefined,
+    operation: RowOperation,
+    row: Row,
+    rowRef: unknown,
+  ): RowOperation | null {
+    const key = pendingKey(rowRef);
+    const pending = subscription.pending;
+    const held = subscription.held;
+    if (key === undefined || !pending || !held) return null;
+    const permitted =
+      operation === 'DELETE'
+        ? undefined
+        : applyResourceAuth([row], query?.auth, requestingUser(connection))[0];
+    if (pending.has(key)) {
+      if (permitted) pending.set(key, stampRow(permitted, rowRef, 'INSERT'));
+      else pending.delete(key);
+      return null;
+    }
+    if (held.has(key)) {
+      if (permitted) return 'MODIFY';
+      held.delete(key);
+      return 'DELETE';
+    }
+    if (!permitted) return null;
+    held.add(key);
+    return 'INSERT';
+  }
+
   const broadcast: BroadcastFn = (resourceName, operation, row) => {
     const query = config.queries?.[resourceName];
     // The query's own filter (where-clause equivalent) applies to live pushes
@@ -111,7 +165,6 @@ export function createMockServer(config: MockServerConfig): MockServer {
     // rather than dropped: a swallowed removal leaves the client rendering the
     // row with its stale pre-modify values until a full reload. An INSERT
     // outside the filter is simply dropped (the client never held it).
-    // DELETEs always go through: dropping an unknown ROW_REF is a no-op.
     let effectiveOperation = operation;
     if (operation !== 'DELETE' && query?.filter && !query.filter(row)) {
       if (operation !== 'MODIFY') return;
@@ -120,34 +173,43 @@ export function createMockServer(config: MockServerConfig): MockServer {
     for (const connection of connections) {
       for (const [sourceRef, subscription] of connection.subscriptions) {
         if (subscription.resourceName !== resourceName) continue;
-        const rowOperation = resolveSubscriptionOperation(
+        const resolved = resolveSubscriptionOperation(
           subscription,
           sourceRef,
           effectiveOperation,
           row,
         );
-        if (rowOperation === null) continue;
+        if (resolved === null) continue;
         // Per-user permissioning (auth maps / hideFields equivalent): the
         // ROW_REF is computed from the unstripped row, since pk fields may
         // themselves be hidden from this user.
         const rowRef = subscription.getRowRef(row);
+        const rowOperation = subscription.held
+          ? trackClientView(subscription, connection, query, resolved, row, rowRef)
+          : resolved;
+        if (rowOperation === null) continue;
         let outRow = row;
-        if (rowOperation !== operation) {
-          // Converted to 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.
-          outRow = query ? store.rowStubFromKey(query.source, rowRef as string) : row;
-        } else if (rowOperation !== 'DELETE' && query?.auth) {
+        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') {
+            outRow = query ? store.rowStubFromKey(query.source, rowRef as string) : row;
+          }
+        } else if (query?.auth) {
           const [permitted] = applyResourceAuth([row], query.auth, requestingUser(connection));
           if (!permitted) continue;
           outRow = permitted;
         }
         subscription.sequenceId += 1;
+        // A live push carries neither MORE_ROWS nor ROWS_COUNT on the real
+        // server — those describe the snapshot. Legacy mode sent ROWS_COUNT: 1.
         connection.send({
           MESSAGE_TYPE: 'QUERY_UPDATE',
           SOURCE_REF: sourceRef,
           ROW: [stampRow(outRow, rowRef, rowOperation)],
-          ROWS_COUNT: 1,
+          ...(isLegacyFidelity(config) ? { ROWS_COUNT: 1 } : {}),
           SEQUENCE_ID: subscription.sequenceId,
         });
       }

package/src/types.ts

@@ -214,7 +214,20 @@ export type OnMessageHook = (
   ctx: OnMessageCtx,
 ) => GenesisMessage | false | void;
 
+// How closely the wire envelopes follow the real server. 'gsf' (the default)
+// matches GSF 8.15.x: LOGON_ACK before the snapshot, dataserver paging
+// (MAX_ROWS / MAX_VIEW / MORE_ROWS), LOGOFF_ACK, FEATURE_ACK /
+// JSON_SCHEMA_FEATURE_ACK, and the router's MSG_NACK for unknown resources and
+// missing/duplicate subscriptions. 'legacy' restores the envelopes this engine
+// sent up to 15.47 (every row in one snapshot, no LOGON_ACK/LOGOFF_ACK, typed
+// UNKNOWN_RESOURCE replies that RESOLVE the client's pending promise where
+// MSG_NACK rejects it) — an escape hatch for consumers built against those,
+// to be removed in a later release.
+export type FidelityMode = 'gsf' | 'legacy';
+
 export interface MockServerConfig {
+  // Defaults to 'gsf'. See FidelityMode and the README's "Wire fidelity".
+  fidelity?: FidelityMode;
   tables?: Record<string, TableDef>;
   views?: Record<string, ViewDef>;
   queries?: Record<string, QueryDef>;
@@ -223,7 +236,8 @@ export interface MockServerConfig {
   // Fallback for commit events with no registered handler — lets a project
   // with many events adopt incrementally (e.g. `() => ({})` acks everything
   // unhandled) instead of enumerating ack-only handlers. Unregistered events
-  // NACK with UNKNOWN_RESOURCE when this is unset.
+  // get the router's MSG_NACK 404 when this is unset (EVENT_NACK with
+  // UNKNOWN_RESOURCE under fidelity: 'legacy').
   defaultEventHandler?: EventHandler;
   eventSchemas?: Record<string, EventSchemaOverride>;
   auth?: AuthConfig;