Jeu de Donjon IA

Module 2 : Implémentation de l’API de jeu

Nous allons commencer par implémenter notre API de jeu. Pour ce faire, nous devons créer 4 API au total :

1. createGame - créera une nouvelle instance de jeu.
2. queryGames - retournera une liste paginée des parties précédemment sauvegardées.
3. saveAction - sauvegardera une action pour une partie donnée.
4. queryActions - retournera une liste paginée de toutes les actions liées à une partie.

Schéma d’API

Pour définir les entrées et sorties de notre API, créons notre schéma avec Zod dans le projet packages/game-api/schema/src comme suit :

types/action.ts

import { z } from 'zod';

export const ActionSchema = z.object({
  playerName: z.string(),
  timestamp: z.string().datetime(),
  role: z.enum(['assistant', 'user']),
  content: z.string(),
});

export type IAction = z.TypeOf<typeof ActionSchema>;

types/common.ts

import { z } from 'zod';

export const QueryInputSchema = z.object({
  cursor: z.string().optional(),
  limit: z.number().optional().default(100),
});

export const createPaginatedQueryOutput = <ItemType extends z.ZodTypeAny>(
  itemSchema: ItemType,
) => {
  return z.object({
    items: z.array(itemSchema),
    cursor: z.string().nullable(),
  });
};

export type IQueryInput = z.TypeOf<typeof QueryInputSchema>;

types/game.ts

import { z } from 'zod';

export const GameSchema = z.object({
  playerName: z.string(),
  genre: z.enum(['zombie', 'superhero', 'medieval']),
  lastUpdated: z.string().datetime(),
});

export type IGame = z.TypeOf<typeof GameSchema>;

index.ts

export * from './procedures/echo.js';
export * from './types/action.js';
export * from './types/common.js';
export * from './types/game.js';

Vous pouvez aussi supprimer le fichier ./procedures/echo.ts car nous ne l’utiliserons pas dans ce projet.

Astuce

Comme vous pouvez le voir ci-dessus, pour chaque schéma défini avec Zod, nous exportons également une interface en utilisant la syntaxe z.TypeOf. Cela permet de convertir notre définition Zod en interface TypeScript sans duplication d’effort !

Modélisation d’entités

Le diagramme entité-relation de notre application est le suivant :

Nous allons implémenter notre base de données dans DynamoDB en utilisant la librairie cliente ElectroDB pour simplifier le développement. Pour commencer, installons d’abord electrodb avec la commande suivante :

pnpm

pnpm add -w electrodb @aws-sdk/client-dynamodb

yarn

yarn add electrodb @aws-sdk/client-dynamodb

npm

npm install --legacy-peer-deps electrodb @aws-sdk/client-dynamodb

bun

bun install electrodb @aws-sdk/client-dynamodb

Note

Toutes les dépendances sont ajoutées au package.json racine car @aws/nx-plugin suit le principe de single version policy. Pour plus d’informations, consultez le guide ts#project.

Créons maintenant les fichiers suivants dans notre dossier packages/game-api/backend/src/entities pour définir nos entités ElectroDB selon le diagramme ER ci-dessus :

action.ts

import { Entity } from 'electrodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

export const createActionEntity = (client?: DynamoDBClient) =>
  new Entity(
    {
      model: {
        entity: 'Action',
        version: '1',
        service: 'game',
      },
      attributes: {
        playerName: { type: 'string', required: true, readOnly: true },
        timestamp: {
          type: 'string',
          required: true,
          readOnly: true,
          set: () => new Date().toISOString(),
          default: () => new Date().toISOString(),
        },
        role: { type: 'string', required: true, readOnly: true },
        content: { type: 'string', required: true, readOnly: true },
      },
      indexes: {
        primary: {
          pk: { field: 'pk', composite: ['playerName'] },
          sk: { field: 'sk', composite: ['timestamp'] },
        },
      },
    },
    { client, table: process.env.TABLE_NAME },
  );

game.ts

import { Entity } from 'electrodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

export const createGameEntity = (client?: DynamoDBClient) =>
  new Entity(
    {
      model: {
        entity: 'Game',
        version: '1',
        service: 'game',
      },
      attributes: {
        playerName: { type: 'string', required: true, readOnly: true },
        genre: { type: 'string', required: true, readOnly: true },
        lastUpdated: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
        },
      },
      indexes: {
        primary: {
          pk: { field: 'pk', composite: ['playerName'] },
          sk: {
            field: 'sk',
            composite: [],
          },
        },
      },
    },
    { client, table: process.env.TABLE_NAME },
  );

ElectroDB est très puissant et nous permet non seulement de définir nos types, mais aussi de fournir des valeurs par défaut comme pour les horodatages ci-dessus. De plus, ElectroDB suit le single-table design, une meilleure pratique avec DynamoDB.

Note

Bien qu’ElectroDB supporte les collections, nous avons choisi de ne pas les utiliser dans ce tutoriel pour simplifier.

Intégration du client DynamoDB dans le contexte tRPC

Comme nous avons besoin d’accéder au client DynamoDB dans chacune de nos procédures, nous voulons créer une instance unique du client que nous pouvons passer via le contexte. Pour ce faire, effectuez les modifications suivantes dans packages/game-api/backend/src :

middleware/dynamodb.ts

middleware/dynamodb.ts

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { initTRPC } from '@trpc/server';

export interface IDynamoDBContext {
  dynamoDb?: DynamoDBClient;
}

export const createDynamoDBPlugin = () => {
  const t = initTRPC.context<IDynamoDBContext>().create();
  return t.procedure.use(async (opts) => {
    const dynamoDb = new DynamoDBClient();

    const response = await opts.next({
      ctx: {
        ...opts.ctx,
        dynamoDb,
      },
    });

    return response;
  });
};

Il s’agit d’un plugin que nous instrumentons pour créer le DynamoDBClient et l’injecter dans le contexte.

middleware/index.ts

middleware/index.ts

import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
import type { APIGatewayProxyEventV2WithIAMAuthorizer } from 'aws-lambda';
import { ILoggerContext } from './logger.js';
import { IMetricsContext } from './metrics.js';
import { ITracerContext } from './tracer.js';
import { IDynamoDBContext } from './dynamodb.js';

export * from './dynamodb.js';
export * from './logger.js';
export * from './metrics.js';
export * from './tracer.js';
export * from './error.js';

export type IMiddlewareContext =
  CreateAWSLambdaContextOptions<APIGatewayProxyEventV2WithIAMAuthorizer> &
    IDynamoDBContext &
    ILoggerContext &
    IMetricsContext &
    ITracerContext;

Nous augmentons notre IMiddlewareContext pour ajouter le IDynamoDBContext.

init.ts

init.ts

import { initTRPC } from '@trpc/server';
import {
  createDynamoDBPlugin,
  createErrorPlugin,
  createLoggerPlugin,
  createMetricsPlugin,
  createTracerPlugin,
  IMiddlewareContext,
} from './middleware/index.js';

process.env.POWERTOOLS_SERVICE_NAME = 'GameApi';
process.env.POWERTOOLS_METRICS_NAMESPACE = 'GameApi';

export type Context = IMiddlewareContext;

export const t = initTRPC.context<Context>().create();

export const publicProcedure = t.procedure
  .unstable_concat(createDynamoDBPlugin())
  .unstable_concat(createLoggerPlugin())
  .unstable_concat(createTracerPlugin())
  .unstable_concat(createMetricsPlugin())
  .unstable_concat(createErrorPlugin());

Le plugin DynamoDB est instrumenté.

Note

Nous utilisons ici l’API unstable_concat qui est sécurisée. Le préfixe unstable_ est présent uniquement car c’est une nouvelle API. Pour plus d’informations, consultez le guide concat.

Définition des procédures

Maintenant, implémentons les méthodes de l’API. Effectuez les modifications suivantes dans packages/game-api/backend/src/procedures :

query-actions.ts

import { createActionEntity } from '../entities/action.js';
import {
  ActionSchema,
  IAction,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from ':dungeon-adventure/game-api-schema';
import { publicProcedure } from '../init.js';
import { z } from 'zod';

export const queryActions = publicProcedure
  .input(QueryInputSchema.extend({ playerName: z.string() }))
  .output(createPaginatedQueryOutput(ActionSchema))
  .query(async ({ input, ctx }) => {
    const actionEntity = createActionEntity(ctx.dynamoDb);
    const result = await actionEntity.query
      .primary({ playerName: input.playerName })
      .go({ cursor: input.cursor, count: input.limit });

    return {
      items: result.data as IAction[],
      cursor: result.cursor,
    };
  });

query-games.ts

import { createGameEntity } from '../entities/game.js';
import {
  GameSchema,
  IGame,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from ':dungeon-adventure/game-api-schema';
import { publicProcedure } from '../init.js';

export const queryGames = publicProcedure
  .input(QueryInputSchema)
  .output(createPaginatedQueryOutput(GameSchema))
  .query(async ({ input, ctx }) => {
    const gameEntity = createGameEntity(ctx.dynamoDb);
    const result = await gameEntity.scan.go({
      cursor: input.cursor,
      count: input.limit,
    });

    return {
      items: result.data as IGame[],
      cursor: result.cursor,
    };
  });

save-action.ts

import { ActionSchema, IAction } from ':dungeon-adventure/game-api-schema';
import { publicProcedure } from '../init.js';
import { createActionEntity } from '../entities/action.js';
import { createGameEntity } from '../entities/game.js';

export const saveAction = publicProcedure
  .input(ActionSchema.omit({ timestamp: true }))
  .output(ActionSchema)
  .mutation(async ({ input, ctx }) => {
    const actionEntity = createActionEntity(ctx.dynamoDb);
    const gameEntity = createGameEntity(ctx.dynamoDb);

    const action = await actionEntity.put(input).go();
    await gameEntity
      .update({ playerName: input.playerName })
      .set({ lastUpdated: action.data.timestamp })
      .go();
    return action.data as IAction;
  });

save-game.ts

import { createGameEntity } from '../entities/game.js';
import { GameSchema, IGame } from ':dungeon-adventure/game-api-schema';
import { publicProcedure } from '../init.js';

export const saveGame = publicProcedure
  .input(GameSchema.omit({ lastUpdated: true }))
  .output(GameSchema)
  .mutation(async ({ input, ctx }) => {
    const gameEntity = createGameEntity(ctx.dynamoDb);

    const result = await gameEntity.put(input).go();
    return result.data as IGame;
  });

Vous pouvez aussi supprimer le fichier echo.ts (dans packages/game-api/backend/src/procedures) car nous ne l’utiliserons pas.

Configuration du routeur

Maintenant que nos procédures sont définies, branchons-les dans notre API. Mettez à jour le fichier comme suit :

packages/game-api/backend/src/router.ts

import {
  awsLambdaRequestHandler,
  CreateAWSLambdaContextOptions,
} from '@trpc/server/adapters/aws-lambda';
import { echo } from './procedures/echo.js';
import { t } from './init.js';
import { APIGatewayProxyEventV2WithIAMAuthorizer } from 'aws-lambda';
import { queryActions } from './procedures/query-actions.js';
import { saveAction } from './procedures/save-action.js';
import { queryGames } from './procedures/query-games.js';
import { saveGame } from './procedures/save-game.js';

export const router = t.router;

export const appRouter = router({
  echo,
  actions: router({
    query: queryActions,
    save: saveAction,
  }),
  games: router({
    query: queryGames,
    save: saveGame,
  }),
});

export const handler = awsLambdaRequestHandler({
  router: appRouter,
  createContext: (
    ctx: CreateAWSLambdaContextOptions<APIGatewayProxyEventV2WithIAMAuthorizer>,
  ) => ctx,
});

export type AppRouter = typeof appRouter;

Infrastructure

La dernière étape consiste à mettre à jour notre infrastructure pour créer la table DynamoDB et accorder les permissions d’accès depuis l’API de jeu. Mettez à jour packages/infra/src comme suit :

constructs/electrodb-table.ts

constructs/electrodb-table.ts

import { CfnOutput } from 'aws-cdk-lib';
import {
  AttributeType,
  BillingMode,
  ProjectionType,
  Table,
  TableProps,
} from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';

export type ElectrodbDynamoTableProps = Omit<
  TableProps,
  'partitionKey' | 'sortKey' | 'billingMode'
>;

export class ElectrodbDynamoTable extends Table {
  constructor(scope: Construct, id: string, props?: ElectrodbDynamoTableProps) {
    super(scope, id, {
      partitionKey: {
        name: 'pk',
        type: AttributeType.STRING,
      },
      sortKey: {
        name: 'sk',
        type: AttributeType.STRING,
      },
      billingMode: BillingMode.PAY_PER_REQUEST,
      ...props,
    });

    this.addGlobalSecondaryIndex({
      indexName: 'gsi1pk-gsi1sk-index',
      partitionKey: {
        name: 'gsi1pk',
        type: AttributeType.STRING,
      },
      sortKey: {
        name: 'gsi1sk',
        type: AttributeType.STRING,
      },
      projectionType: ProjectionType.ALL,
    });

    new CfnOutput(this, 'TableName', { value: this.tableName });
  }
}

stacks/application-stack.ts

stacks/application-stack.ts

import {
  GameApi,
  GameUI,
  StoryApi,
  UserIdentity,
} from ':dungeon-adventure/common-constructs';
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { ElectrodbDynamoTable } from '../constructs/electrodb-table.js';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // The code that defines your stack goes here
    const userIdentity = new UserIdentity(this, 'UserIdentity');

    const electroDbTable = new ElectrodbDynamoTable(this, 'ElectroDbTable');

    const gameApi = new GameApi(this, 'GameApi');
    const storyApi = new StoryApi(this, 'StoryApi');

    gameApi.routerFunction.addEnvironment(
      'TABLE_NAME',
      electroDbTable.tableName,
    );
    // Accorder l'accès en lecture/écriture à DynamoDB
    electroDbTable.grantReadWriteData(gameApi.routerFunction);

    // Accorder à notre rôle authentifié l'accès aux APIs
    [storyApi, gameApi].forEach((api) =>
      api.grantInvokeAccess(userIdentity.identityPool.authenticatedRole),
    );

    // S'assurer que ceci est instancié en dernier pour la configuration automatique
    new GameUI(this, 'GameUI');
  }
}

Déploiement et tests

D’abord, compilons le codebase :

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Astuce

Si vous rencontrez des erreurs de lint, exécutez cette commande pour les corriger automatiquement :

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

Déployez maintenant votre application avec :

pnpm

pnpm nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox

yarn

yarn nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox

npm

npx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox

bun

bunx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox

Le premier déploiement prendra environ 8 minutes. Les suivants prendront ~2 minutes.

Astuce

Pour les modifications de code sur les fonctions Lambda, utilisez le flag --hotswap après compilation pour un déploiement rapide (2-3 secondes) :

pnpm

pnpm nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox --hotswap

yarn

yarn nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox --hotswap

npm

npx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox --hotswap

bun

bunx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox --hotswap

Vous pouvez aussi déployer toutes les stacks en une fois. Cliquez pour plus de détails.

Une fois le déploiement terminé, vous verrez des sorties similaires à ceci (valeurs masquées) :

dungeon-adventure-infra-sandbox
dungeon-adventure-infra-sandbox: deploying... [2/2]

 ✅  dungeon-adventure-infra-sandbox

✨  Temps de déploiement : 354s

Outputs:
dungeon-adventure-infra-sandbox.ElectroDbTableTableNameXXX = dungeon-adventure-infra-sandbox-ElectroDbTableXXX-YYY
dungeon-adventure-infra-sandbox.GameApiGameApiUrlXXX = https://xxx.region.amazonaws.com/
dungeon-adventure-infra-sandbox.GameUIDistributionDomainNameXXX = xxx.cloudfront.net
dungeon-adventure-infra-sandbox.StoryApiStoryApiUrlXXX = https://xxx.execute-api.region.amazonaws.com/
dungeon-adventure-infra-sandbox.UserIdentityUserIdentityIdentityPoolIdXXX = region:xxx
dungeon-adventure-infra-sandbox.UserIdentityUserIdentityUserPoolIdXXX = region_xxx

Testez l’API avec :

• Démarrez une instance locale du backend tRPC et appelez les API via curl
• Appeler l'API déployée avec curl activé pour Sigv4

Local

Démarrez le serveur game-api localement :

pnpm

TABLE_NAME=dungeon-adventure-infra-sandbox-ElectroDbTableXXX-YYY pnpm nx run @dungeon-adventure/game-api-backend:serve

yarn

TABLE_NAME=dungeon-adventure-infra-sandbox-ElectroDbTableXXX-YYY yarn nx run @dungeon-adventure/game-api-backend:serve

npm

TABLE_NAME=dungeon-adventure-infra-sandbox-ElectroDbTableXXX-YYY npx nx run @dungeon-adventure/game-api-backend:serve

bun

TABLE_NAME=dungeon-adventure-infra-sandbox-ElectroDbTableXXX-YYY bunx nx run @dungeon-adventure/game-api-backend:serve

Attention

Utilisez la valeur de sortie dungeon-adventure-infra-sandbox.ElectroDbTableTableNameXXX du déploiement CDK.

Une fois le serveur démarré, appelez-le avec :

curl -X GET http://localhost:2022/games.query\?input="\\{\\}"

Déployé

acurl ap-southeast-2 execute-api -X GET \
  https://xxx.execute-api.region.amazonaws.com/games.query\?input\="\{\}"

Attention

Utilisez la valeur de sortie dungeon-adventure-infra-sandbox.GameApiGameApiUrlXXX et ajustez la région.

Si la commande réussit, vous verrez :

{"result":{"data":{"items":[],"cursor":null}}}

Félicitations. Vous avez déployé votre première API avec tRPC ! 🎉🎉🎉