feat: Add game method to validate setup data (#831)

Add a `validateSetupData` method to the game object, which — if provided — is called by the API server when creating a match to check that the `setupData` sent to the server is valid.

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

Author: c-w

docs/documentation/api/Game.md

@@ -10,6 +10,12 @@
   // passed through the Game Creation API.
   setup: (ctx, setupData) => G,
 
+  // Optional function to validate the setupData before
+  // matches are created. If this returns a value,
+  // an error will be reported to the user and match
+  // creation is aborted.
+  validateSetupData: (setupData, numPlayers) => 'setupData is not valid!',
+
   moves: {
     // short-form move.
     A: (G, ctx) => {},

src/server/api.test.ts

@@ -102,6 +102,19 @@ describe('.createRouter', () => {
                 }
               : {},
         },
+        {
+          name: 'validate',
+          setup: (_, setupData) =>
+            setupData
+              ? {
+                  numTokens: setupData.tokens,
+                }
+              : {},
+          validateSetupData: (setupData, numPlayers) =>
+            numPlayers == 2 && setupData.tokens !== 2
+              ? 'Two player games must use two tokens'
+              : undefined,
+        },
       ];
     });
 
@@ -226,6 +239,34 @@ describe('.createRouter', () => {
         });
       });
 
+      describe('with setupData validation', () => {
+        test('creates game if validation passes', async () => {
+          response = await request(app.callback())
+            .post('/games/validate/create')
+            .send({
+              numPlayers: 2,
+              setupData: {
+                tokens: 2,
+              },
+            });
+
+          expect(response.status).toEqual(200);
+        });
+
+        test('returns error if validation fails', async () => {
+          response = await request(app.callback())
+            .post('/games/validate/create')
+            .send({
+              numPlayers: 2,
+              setupData: {
+                tokens: 3,
+              },
+            });
+
+          expect(response.status).toEqual(400);
+        });
+      });
+
       describe('with unlisted option', () => {
         beforeEach(async () => {
           response = await request(app.callback())

src/server/api.ts

@@ -124,6 +124,10 @@ export const createRouter = ({
     const game = games.find(g => g.name === gameName);
     if (!game) ctx.throw(404, 'Game ' + gameName + ' not found');
 
+    const setupDataError =
+      game.validateSetupData && game.validateSetupData(setupData, numPlayers);
+    if (setupDataError !== undefined) ctx.throw(400, setupDataError);
+
     const matchID = await CreateMatch({
       db,
       game,

src/types.ts

@@ -231,13 +231,21 @@ interface PhaseMap<G extends any = any, CtxWithPlugins extends Ctx = Ctx> {
   [phaseName: string]: PhaseConfig<G, CtxWithPlugins>;
 }
 
-export interface Game<G extends any = any, CtxWithPlugins extends Ctx = Ctx> {
+export interface Game<
+  G extends any = any,
+  CtxWithPlugins extends Ctx = Ctx,
+  SetupData extends any = any
+> {
   name?: string;
   minPlayers?: number;
   maxPlayers?: number;
   disableUndo?: boolean;
   seed?: string | number;
-  setup?: (ctx: CtxWithPlugins, setupData?: any) => any;
+  setup?: (ctx: CtxWithPlugins, setupData?: SetupData) => any;
+  validateSetupData?: (
+    setupData: SetupData | undefined,
+    numPlayers: number
+  ) => string | undefined;
   moves?: MoveMap<G, CtxWithPlugins>;
   phases?: PhaseMap<G, CtxWithPlugins>;
   turn?: TurnConfig<G, CtxWithPlugins>;