feat: Add an option to use JSON patches for state updates (#920)

* Add patch transmit

* fix stale state id

* Add test and comment

* add reducer test for coverage

* fix reducer.test.ts

* fix warning and coverage

* add document

* Fix deltalog handling on client

* style: clean up

Co-authored-by: Chris Swithinbank <[email protected]>

Author: larry801

docs/documentation/api/Game.md

@@ -119,5 +119,8 @@
 
   // Disable undo feature for all the moves in the game
   disableUndo: true,
+    
+  // Transfer delta state with JSON Patch in multiplayer
+  deltaState: true,
 }
 ```

package-lock.json

@@ -162,6 +162,7 @@
     "prop-types": "^15.5.10",
     "react-cookies": "^0.1.0",
     "redux": "^4.0.0",
+    "rfc6902": "^4.0.1",
     "socket.io": "^2.4.1",
     "socket.io-client": "^2.3.0",
     "svelte": "^3.24.0",

package.json

@@ -14,10 +14,17 @@ import { ProcessGameConfig } from '../core/game';
 import type { Transport } from './transport/transport';
 import { LocalTransport, Local } from './transport/local';
 import { SocketIOTransport, SocketIO } from './transport/socketio';
-import { update, sync, makeMove, gameEvent } from '../core/action-creators';
+import {
+  update,
+  sync,
+  makeMove,
+  gameEvent,
+  patch,
+} from '../core/action-creators';
 import Debug from './debug/Debug.svelte';
 import { error } from '../core/logger';
 import type { LogEntry, State, SyncInfo } from '../types';
+import type { Operation } from 'rfc6902';
 
 jest.mock('../core/logger', () => ({
   info: jest.fn(),
@@ -370,19 +377,20 @@ test('accepts enhancer for store', () => {
 });
 
 describe('event dispatchers', () => {
+  const clientEvents = [
+    'endTurn',
+    'pass',
+    'endPhase',
+    'setPhase',
+    'endGame',
+    'setActivePlayers',
+    'endStage',
+    'setStage',
+  ];
   test('default', () => {
     const game = {};
     const client = Client({ game });
-    expect(Object.keys(client.events)).toEqual([
-      'endTurn',
-      'pass',
-      'endPhase',
-      'setPhase',
-      'endGame',
-      'setActivePlayers',
-      'endStage',
-      'setStage',
-    ]);
+    expect(Object.keys(client.events)).toEqual(clientEvents);
     expect(client.getState().ctx.turn).toBe(1);
     client.events.endTurn();
     expect(client.getState().ctx.turn).toBe(2);
@@ -396,16 +404,7 @@ describe('event dispatchers', () => {
       },
     };
     const client = Client({ game });
-    expect(Object.keys(client.events)).toEqual([
-      'endTurn',
-      'pass',
-      'endPhase',
-      'setPhase',
-      'endGame',
-      'setActivePlayers',
-      'endStage',
-      'setStage',
-    ]);
+    expect(Object.keys(client.events)).toEqual(clientEvents);
     expect(client.getState().ctx.turn).toBe(1);
     client.events.endTurn();
     expect(client.getState().ctx.turn).toBe(2);
@@ -464,7 +463,7 @@ describe('move dispatchers', () => {
     expect(store.getState().G).toMatchObject({ victory: true });
   });
 
-  test('with undefined playerID - singleplayer mode', () => {
+  test('with undefined playerID - single player mode', () => {
     const store = createStore(reducer, initialState);
     const api = createMoveDispatchers(game.moveNames, store);
     api.B();
@@ -484,7 +483,7 @@ describe('move dispatchers', () => {
     expect(store.getState().G).toMatchObject({ moved: undefined });
   });
 
-  test('with null playerID - singleplayer mode', () => {
+  test('with null playerID - single player mode', () => {
     const store = createStore(reducer, initialState);
     const api = createMoveDispatchers(game.moveNames, store, null);
     api.B();
@@ -552,6 +551,26 @@ describe('log handling', () => {
     expect(client.log).toEqual(deltalog);
   });
 
+  test('patch', () => {
+    const patches = [
+      { op: 'replace', path: '/_stateID', value: 1 },
+    ] as Operation[];
+    const deltalog = [
+      {
+        action: {},
+        _stateID: 0,
+      },
+      {
+        action: {},
+        _stateID: 1,
+      },
+    ] as LogEntry[];
+    const action = patch(0, 1, patches, deltalog);
+    client.store.dispatch(action);
+
+    expect(client.log).toEqual(deltalog);
+  });
+
   test('sync', () => {
     const state = { restore: true };
     const log = ['0', '1'];
@@ -756,6 +775,10 @@ describe('start / stop', () => {
     const client = Client({ game: {}, debug: { target: el } });
     client.start();
     client.stop();
+    expect(error).toHaveBeenCalledTimes(3);
+    expect(error).toHaveBeenCalledWith('disallowed move: B');
+    expect(error).toHaveBeenCalledWith('disallowed move: C');
+    expect(error).toHaveBeenLastCalledWith('disallowed move: A');
   });
 
   test('no error when mounting on null element', () => {
@@ -769,17 +792,29 @@ describe('start / stop', () => {
     const client = Client({ game: {}, debug: { impl: Debug } });
     client.start();
     client.stop();
+    expect(error).toHaveBeenCalledTimes(3);
+    expect(error).toHaveBeenCalledWith('disallowed move: B');
+    expect(error).toHaveBeenCalledWith('disallowed move: C');
+    expect(error).toHaveBeenLastCalledWith('disallowed move: A');
   });
 
   test('production mode', () => {
     process.env.NODE_ENV = 'production';
     const client = Client({ game: {} });
     client.start();
     client.stop();
+    expect(error).toHaveBeenCalledTimes(3);
+    expect(error).toHaveBeenCalledWith('disallowed move: B');
+    expect(error).toHaveBeenCalledWith('disallowed move: C');
+    expect(error).toHaveBeenLastCalledWith('disallowed move: A');
   });
 
   test('try to stop without starting', () => {
     const client = Client({ game: {} });
     client.stop();
+    expect(error).toHaveBeenCalledTimes(3);
+    expect(error).toHaveBeenCalledWith('disallowed move: B');
+    expect(error).toHaveBeenCalledWith('disallowed move: C');
+    expect(error).toHaveBeenLastCalledWith('disallowed move: A');
   });
 });

src/client/client.test.ts

@@ -35,7 +35,11 @@ import type {
   ChatMessage,
 } from '../types';
 
-type ClientAction = ActionShape.Reset | ActionShape.Sync | ActionShape.Update;
+type ClientAction =
+  | ActionShape.Reset
+  | ActionShape.Sync
+  | ActionShape.Update
+  | ActionShape.Patch;
 type Action = CredentialedActionShape.Any | ClientAction;
 
 export interface DebugOpt {
@@ -241,7 +245,7 @@ export class _ClientImpl<G extends any = any> {
           this.log = [];
           break;
         }
-
+        case Actions.PATCH:
         case Actions.UPDATE: {
           let id = -1;
           if (this.log.length > 0) {

src/client/client.ts

@@ -14,6 +14,12 @@ import { InitializeGame } from '../../core/initialize';
 import * as Actions from '../../core/action-types';
 import type { Master } from '../../master/master';
 import type { ChatMessage, State, Store } from '../../types';
+import { error } from '../../core/logger';
+
+jest.mock('../../core/logger', () => ({
+  info: jest.fn(),
+  error: jest.fn(),
+}));
 
 type UpdateArgs = Parameters<Master['onUpdate']>;
 type SyncArgs = Parameters<Master['onSync']>;
@@ -27,8 +33,8 @@ class MockSocket {
     this.emit = jest.fn();
   }
 
-  receive(type: string, arg0?: any, arg1?: any) {
-    this.callbacks[type](arg0, arg1);
+  receive(type: string, ...args) {
+    this.callbacks[type](...args);
   }
 
   on(type: string, callback: (arg0?: any, arg1?: any) => void) {
@@ -219,6 +225,61 @@ describe('multiplayer', () => {
   });
 });
 
+describe('multiplayer delta state', () => {
+  const mockSocket = new MockSocket();
+  const m = new TransportAdapter({ socket: mockSocket });
+  m.connect();
+  const game = { deltaState: true };
+  let store = null;
+
+  beforeEach(() => {
+    const reducer = CreateGameReducer({ game });
+    const initialState = InitializeGame({ game });
+    store = createStore(reducer, initialState);
+    m.setStore(store);
+  });
+
+  test('returns a valid store', () => {
+    expect(store).not.toBe(undefined);
+  });
+
+  test('receive patch', () => {
+    const originalState = JSON.parse(JSON.stringify(store.getState()));
+    mockSocket.receive(
+      'patch',
+      'unknown matchID',
+      0,
+      1,
+      [{ op: 'replace', path: '/_stateID', value: 1 }],
+      []
+    );
+    expect(store.getState()).toMatchObject(originalState);
+    mockSocket.receive(
+      'patch',
+      'default',
+      0,
+      1,
+      [{ op: 'replace', path: '/_stateID', value: 1 }],
+      []
+    );
+    expect(store.getState()._stateID).toBe(1);
+    mockSocket.receive(
+      'patch',
+      'default',
+      1,
+      2,
+      [{ op: 'replace', path: '/_stateIDD', value: 3 }],
+      []
+    );
+    expect(store.getState()._stateID).toBe(1);
+    const args: SyncArgs = ['default', null, undefined, 2];
+    expect(mockSocket.emit).lastCalledWith('sync', ...args);
+    expect(error).lastCalledWith(
+      'Patch [{"op":"replace","path":"/_stateIDD","value":3}] apply failed'
+    );
+  });
+});
+
 describe('server option', () => {
   const hostname = 'host';
   const port = '1234';

src/client/transport/socketio.test.ts

@@ -7,11 +7,13 @@
  */
 
 import * as ioNamespace from 'socket.io-client';
+
 const io = ioNamespace.default;
 
 import * as ActionCreators from '../../core/action-creators';
 import type { Master } from '../../master/master';
 import { Transport } from './transport';
+import type { Operation } from 'rfc6902';
 import type {
   TransportOpts,
   MetadataCallback,
@@ -51,11 +53,13 @@ export class SocketIOTransport extends Transport {
   chatMessageCallback: ChatCallback;
 
   /**
-   * Creates a new Mutiplayer instance.
+   * Creates a new Multiplayer instance.
    * @param {object} socket - Override for unit tests.
    * @param {object} socketOpts - Options to pass to socket.io.
+   * @param {object} store - Redux store
    * @param {string} matchID - The game ID to connect to.
    * @param {string} playerID - The player ID associated with this client.
+   * @param {string} credentials - Authentication credentials
    * @param {string} gameName - The game type (the `name` field in `Game`).
    * @param {string} numPlayers - The number of players.
    * @param {string} server - The game server in the form of 'hostname:port'. Defaults to the server serving the client if not provided.
@@ -120,6 +124,35 @@ export class SocketIOTransport extends Transport {
       }
     }
 
+    // Called when another player makes a move and the
+    // master broadcasts the update as a patch to other clients (including
+    // this one).
+    this.socket.on(
+      'patch',
+      (
+        matchID: string,
+        prevStateID: number,
+        stateID: number,
+        patch: Operation[],
+        deltalog: LogEntry[]
+      ) => {
+        const currentStateID = this.store.getState()._stateID;
+        if (matchID === this.matchID && prevStateID === currentStateID) {
+          const action = ActionCreators.patch(
+            prevStateID,
+            stateID,
+            patch,
+            deltalog
+          );
+          this.store.dispatch(action);
+          // emit sync if patch apply failed
+          if (this.store.getState()._stateID === currentStateID) {
+            this.sync();
+          }
+        }
+      }
+    );
+
     // Called when another player makes a move and the
     // master broadcasts the update to other clients (including
     // this one).

src/client/transport/socketio.ts

@@ -8,6 +8,7 @@
 
 import * as Actions from './action-types';
 import type { SyncInfo, State, LogEntry } from '../types';
+import type { Operation } from 'rfc6902';
 
 /**
  * Generate a move to be dispatched to the game move reducer.
@@ -71,6 +72,28 @@ export const sync = (info: SyncInfo) => ({
   clientOnly: true as const,
 });
 
+/**
+ * Used to update the Redux store's state with patch in response to
+ * an action coming from another player.
+ * @param prevStateID previous stateID
+ * @param stateID stateID after this patch
+ * @param {Operation[]} patch - The patch to apply.
+ * @param {LogEntry[]} deltalog - A log delta.
+ */
+export const patch = (
+  prevStateID: number,
+  stateID: number,
+  patch: Operation[],
+  deltalog: LogEntry[]
+) => ({
+  type: Actions.PATCH as typeof Actions.PATCH,
+  prevStateID,
+  stateID,
+  patch,
+  deltalog,
+  clientOnly: true as const,
+});
+
 /**
  * Used to update the Redux store's state in response to
  * an action coming from another player.

src/core/action-creators.ts

@@ -13,4 +13,5 @@ export const RESET = 'RESET';
 export const SYNC = 'SYNC';
 export const UNDO = 'UNDO';
 export const UPDATE = 'UPDATE';
+export const PATCH = 'PATCH';
 export const PLUGIN = 'PLUGIN';