Juego de Mazmorra con IA

Módulo 2: Implementación de la API del juego

Comenzaremos implementando nuestra Game API. Para esto necesitamos crear 4 APIs en total:

1. createGame - esto creará una nueva instancia del juego.
2. queryGames - devolverá una lista paginada de juegos guardados anteriormente.
3. saveAction - guardará una acción para un juego específico.
4. queryActions - devolverá una lista paginada de todas las acciones relacionadas con un juego.

Esquema de la API

Para definir las entradas y salidas de nuestra API, crearemos nuestro esquema usando Zod dentro del proyecto packages/game-api/schema/src de la siguiente manera:

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';

También puedes eliminar el archivo ./procedures/echo.ts ya que no lo usaremos en este proyecto.

Consejo

Como se muestra arriba, para cada esquema que definimos en Zod, también exportamos una interfaz usando la sintaxis z.TypeOf. ¡Esto convierte nuestra definición de Zod en una interfaz de Typescript sin duplicar esfuerzos!

Modelado de entidades

El diagrama ER de nuestra aplicación es el siguiente:

Implementaremos nuestra base de datos en DynamoDB usando la biblioteca cliente ElectroDB. Para comenzar, primero necesitamos instalar electrodb ejecutando el siguiente comando:

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

Nota

Todas las dependencias se agregan al package.json raíz ya que @aws/nx-plugin sigue el principio de política de versión única. Para más información, consulta la guía de proyectos TypeScript.

Ahora creemos los siguientes archivos en nuestra carpeta packages/game-api/backend/src/entities para definir nuestras entidades ElectroDB según el diagrama ER anterior:

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 es muy potente y nos permite no solo definir tipos, sino también proveer valores por defecto como los timestamps anteriores. Además, ElectroDB sigue el diseño de tabla única, considerada mejor práctica con DynamoDB.

Nota

Aunque ElectroDB soporta colecciones, no las usaremos en este tutorial por simplicidad.

Añadiendo el cliente DynamoDB al contexto de tRPC

Como necesitamos acceso al cliente DynamoDB en cada procedimiento, crearemos una instancia única del cliente que pasaremos mediante el contexto. Para esto, realiza los siguientes cambios en 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;
  });
};

Este es un plugin que instrumentamos para crear el DynamoDBClient e inyectarlo en el contexto.

middleware/index.ts

middleware/index.ts

import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
import type { APIGatewayProxyEvent } 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<APIGatewayProxyEvent> &
    IDynamoDBContext &
    ILoggerContext &
    IMetricsContext &
    ITracerContext;

Aumentamos nuestro IMiddlewareContext para añadir el 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
  .concat(createDynamoDBPlugin())
  .concat(createLoggerPlugin())
  .concat(createTracerPlugin())
  .concat(createMetricsPlugin())
  .concat(createErrorPlugin());

El plugin de DynamoDB queda instrumentado.

Nota

La API concat vincula nuestro middleware a los procedimientos. Para más detalles, consulta la guía de concat.

Definiendo nuestros procedimientos

Ahora implementaremos los métodos de la API. Para esto, realiza los siguientes cambios en 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;
  });

También puedes eliminar el archivo echo.ts (de packages/game-api/backend/src/procedures) ya que no lo usaremos.

Configuración del router

Con los procedimientos definidos, conectémoslos a nuestra API. Actualiza el siguiente archivo:

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 { APIGatewayProxyEvent } 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<APIGatewayProxyEvent>,
  ) => ctx,
  responseMeta: () => ({
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': '*',
    },
  }),
});

export type AppRouter = typeof appRouter;

Infraestructura

El paso final es actualizar nuestra infraestructura para crear la tabla DynamoDB y otorgar permisos a la Game API. Actualiza packages/infra/src como sigue:

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);

    const userIdentity = new UserIdentity(this, 'UserIdentity');

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

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this).build(),
      integrations: GameApi.defaultIntegrations(this)
        .withDefaultOptions({
          environment: {
            TABLE_NAME: electroDbTable.tableName,
          },
        })
        .build(),
    });

    // Grant read/write access to each procedure's lambda handler according to the permissions it requires
    electroDbTable.grantReadData(gameApi.integrations['actions.query'].handler);
    electroDbTable.grantReadData(gameApi.integrations['games.query'].handler);
    electroDbTable.grantReadWriteData(
      gameApi.integrations['actions.save'].handler,
    );
    electroDbTable.grantReadWriteData(
      gameApi.integrations['games.save'].handler,
    );

    const storyApi = new StoryApi(this, 'StoryApi', {
      integrations: StoryApi.defaultIntegrations(this).build(),
    });

    // grant our authenticated role access to invoke our APIs
    [storyApi, gameApi].forEach((api) =>
      api.grantInvokeAccess(userIdentity.identityPool.authenticatedRole),
    );

    // Ensure this is instantiated last so our runtime-config.json can be automatically configured
    new GameUI(this, 'GameUI');
  }
}

Nota

Nota que como cada procedimiento se sirve con una función lambda independiente, podemos aplicar el principio de mínimo privilegio asignando solo los permisos necesarios.

Despliegue y pruebas

Primero, construyamos el código:

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

Consejo

Si encuentras errores de linting, ejecuta este comando para corregirlos automáticamente:

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

Ahora puedes desplegar la aplicación con:

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

El primer despliegue tomará ~8 minutos. Los siguientes tomarán ~2 minutos.

Consejo

Para cambios en código lambda, usa el flag --hotswap tras construir para despliegues rápidos (2-3 segundos):

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

También puedes desplegar todos los stacks. Haz clic para más detalles.

Tras el despliegue, verás salidas similares a:

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

 ✅  dungeon-adventure-infra-sandbox

✨  Deployment time: 354s

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

Podemos probar la API mediante:

• Iniciar una instancia local del backend tRPC y usar curl.
• Llamar a la API desplegada usando curl con Sigv4

Local

Inicia el servidor local game-api con:

pnpm

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

yarn

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

npm

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

bun

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

Precaución

Usa el valor dungeon-adventure-infra-sandbox.ElectroDbTableTableNameXXX de la salida de CDK para reemplazar el marcador.

Una vez iniciado, prueba con:

curl -X GET 'http://localhost:2022/games.query?input=%7B%7D'

Desplegado

acurl ap-southeast-2 execute-api -X GET 'https://xxx.execute-api.ap-southeast-2.amazonaws.com/prod/games.query?input=%7B%7D'

Precaución

Usa el valor dungeon-adventure-infra-sandbox.GameApiGameApiEndpointXXX de CDK y ajusta la región.

Nota

El %7B%7D es un objeto JSON vacío ({}) codificado en URI.

Si todo funciona, verás:

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

¡Felicidades, has construido y desplegado tu primera API usando tRPC! 🎉🎉🎉