DEV Community: Cox65

Boost local development with AWS AppSync Simulator🚀✨

Cox65 — Mon, 13 Nov 2023 21:26:25 +0000

Hi there! 👊

In this article I will explain you how to simulate AWS AppSync in local when you are not fully using Amplify or Serverless framework.

In which case you shouldn’t read this article?

If you are fully using Amplify CLI, you should be able to use amplify mock command to simulate AppSync so… you can stop reading here ^^

If you are using Serverless ⚡ framework, you should be able to use the serverless-appsync-simulator plugin to cover your need.

In any other cases, you are at the right place :)

If you are still reading, let’s go!

What we will do through this article is building an Amplify AppSync simulator without using Amplify CLI at all. In fact, we will only pick the simulator which is interesting for us and use it.

We will configure the simulator with a simple GraphQL Schema (Books and authors data model) and Lambda data sources in charge of retrieving data.

Here is the model, dataset and GraphQL schema we will use:

export type Author = {
    id: number,
    name: string
}

export type Book = {
    id: number
    title: string
    authorId: number
}

import { Author } from "../types/author";

export const authors: Author[] = [{
    id: 1,
    name: "Jessica J. Cano"
},
{
    id: 2,
    name: "Peter L. Garcia"
}]

import { Book } from "../types/book";

export const books: Book[] = [
    {
        id: 1,
        title: "Assassin Of The Eclipse",
        authorId: 1
    },
    {
        id: 2,
        title: "Wolves Of The Great",
        authorId: 1
    },
    {
        id: 3,
        title: "Revenge With Wings",
        authorId: 2
    }
]

type Book {
  title: String
  author: Author
}

type Author {
  name: String
  books: [Book]
}

type Query {
  books: [Book]
  authors: [Author]
}

type Mutation {
  addBook(title: String, author: String): Book
}

Pre-requisites

You have node and npm installed.
You have a simple typescript project ready! (package.json with typescript and @types/node dependencies, tsconfig.json properly configured…)

Add dependencies

First we will add some development dependencies in our project

npm install --save-dev ts-node ts-node-dev @types/aws-lambda

ts-node-dev: It will help us to start the simulator and have hot reload capabilities

@types/lambda: Add some Typescript types related to AWS Lambda that I will use in this example

And, finally, we will add the famous Amplify AppSync simulator package

npm install amplify-appsync-simulator

Create lambda handlers for resolvers

We will build handlers for our query operations and to resolve nested fields.

import { authors } from "../data/authors";

export const handler = () => authors;

import { books } from "../data/books";

export const handler = () => books;

import { AppSyncResolverEvent } from "aws-lambda";
import { books } from "../data/books";
import { Author } from "../types/author";

export const handler = (event: AppSyncResolverEvent<object, Author>) => {
    const author = event.source
    return books.filter((book) => book.authorId === author.id)
}

import { AppSyncResolverEvent } from "aws-lambda";
import { authors } from "../data/authors";
import { Book } from "../types/book";

export const handler = (event: AppSyncResolverEvent<object, Book>) => {
    const book = event.source

    return authors.find((author) => author.id === book.authorId)
}

Create request/response mapping templates

Now we will create VTL files for our request and response mapping templates. These VTL files will have to be passed to the simulator as string so I created a function to read them from the filesystem.

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": $util.toJson($context)
}

#if($ctx.error)
     $util.error($ctx.error.message, $ctx.error.type, $ctx.result)
 #end
 $util.toJson($ctx.result)

Build the AppSync Simulator 🚀

Here is the interesting part! We will create the AppSync Simulator with all the configuration we have prepared before.

💡Tips: One interesting aspect is that, if you are using AWS CDK, you can share some pieces between the way you configure the simulator and the way your build your constructs.

import {
    AmplifyAppSyncSimulator,
    AmplifyAppSyncSimulatorAuthenticationType,
    AmplifyAppSyncSimulatorConfig,
} from 'amplify-appsync-simulator'

import { handler as queryBooksHandler } from './resolvers/queryBooks'
import { handler as queryAuthorsHandler } from './resolvers/queryAuthors'
import { handler as bookAuthorHandler } from './resolvers/bookAuthor'
import { handler as authorBooksHandler } from './resolvers/authorBooks'
import { schema } from "./schema"
import { readVTL } from './vtl/readVTL'
import { resolversConfig } from './resolversConfig'


class AppSyncSimulator {
    httpPort: number
    wssPort: number

    constructor(httpPort: number, wssPort: number) {
        this.httpPort = httpPort
        this.wssPort = wssPort
    }

    async start() {
        const simulatorConfig: AmplifyAppSyncSimulatorConfig = {
            appSync: {
                defaultAuthenticationType: {
                    authenticationType: AmplifyAppSyncSimulatorAuthenticationType.AMAZON_COGNITO_USER_POOLS,
                    cognitoUserPoolConfig: {},
                },
                name: 'api-local',
                additionalAuthenticationProviders: [],
            },
            schema: { content: schema },
            mappingTemplates: [
                {
                    path: 'lambdaRequestMappingTemplate.vtl',
                    content: readVTL("lambdaRequestMappingTemplate.vtl"),
                },
                {
                    path: 'lambdaResponseMappingTemplate.vtl',
                    content: readVTL("lambdaResponseMappingTemplate.vtl"),
                }
            ],
            dataSources: [
                {
                    type: 'AWS_LAMBDA',
                    name: 'QueryBooksDataSource',
                    invoke: queryBooksHandler,
                },
                {
                    type: 'AWS_LAMBDA',
                    name: 'QueryAuthorsDataSource',
                    invoke: queryAuthorsHandler,
                },
                {
                    type: 'AWS_LAMBDA',
                    name: 'BookAuthorDataSource',
                    invoke: bookAuthorHandler,
                }, {
                    type: 'AWS_LAMBDA',
                    name: 'AuthorBooksDataSource',
                    invoke: authorBooksHandler,
                }
            ],
            resolvers: resolversConfig,
        }
        const amplifySimulator = new AmplifyAppSyncSimulator({
            port: this.httpPort,
            wsPort: this.wssPort,
        })
        await amplifySimulator.start()
        await amplifySimulator.init(simulatorConfig)
    }
}

const httpPort = 4000
const wsPort = 4001
const simulator = new AppSyncSimulator(httpPort, wsPort)
simulator.start().then(() => {
    console.log(`🚀 App Sync Simulator started at http://localhost:${httpPort}/graphql`)
})

And we can finally run our simulator ✨

➜ npx ts-node-dev src/main.ts

[INFO] 13:46:46 ts-node-dev ver. 2.0.0 (using ts-node ver. 10.9.1, typescript ver. 4.9.4)
🚀 App Sync Simulator started at http://localhost:4000/graphql

Testing our GraphQL API

By accessing http://localhost:4000/, you can access directly the built-in Amplify GraphiQL Explorer

AppSync Simulator Starter Kit

As usual in my articles, the related repository 😉
GitHub - DevWaveX/appsync-simulator-starter-kit: Starter kit for using AppSync simulator

I hope you enjoyed reading from me! See you soon 🤘

⚡ Serverless REST API on AWS with FastAPI ⚡

Cox65 — Thu, 02 Nov 2023 22:46:00 +0000

Hi there! 👊

In this article, I will explain you how to deploy, in minutes, FastAPI on AWS using Serverless.

As usual in all my articles, you will find at the end a link to a working example on my Github.

Pre-requisites

I assume you have at least Python 3.7+ and npm installed.

Install and configure AWS CLI

You need to install the AWS CLI and configure your credentials. You can follow this link for instructions.

Install Serverless Framework

Then you will have to install the Serverless framework via npm. See instructions here.

FastAPI Application

Build the application

First of all, we will build our FastAPI application. Add fastapi dependency in your requirements.txt and install it.
Then you can create your FastAPI application:

from fastapi import FastAPI
from starlette.middleware.cors import CORSMiddleware
from fastapi_aws_starter_kit.routers.health_check_api import router as hc_router
from fastapi_aws_starter_kit.config import PROJECT_NAME, API_VERSION

# Declare the application
app = FastAPI(title=PROJECT_NAME, debug=False, version=API_VERSION)


app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)


@app.get(path="/health", description="Health check")
def health_check():
    return {"status": "OK"}


app.include_router(hc_router)

Deploy FastAPI on AWS

To deploy our API in AWS, we will leverage API Gateway and Lambda services and use Serverless framework capabilities to easily create all resources we need.

Lambda handler with Mangum

In order to build the handler for our Lambda which will be called by our API Gateway, we will use Mangum which is an ASGI adapter for API Gateway and Lambda (perfect for our FastAPI application 🍾)

Add mangum to your dependencies and build the handler as follow:

from mangum import Mangum
from fastapi_aws_starter_kit.fastapi_app import app

handler = Mangum(app=app)

Configure serverless.yaml

Serverless configuration is pretty easy, here is what I did as a simple example:

org: cox65
app: fastapi-aws-starter-kit
service: fastapi-aws-starter-kit
package:
  individually: true
provider:
  name: aws
  runtime: python3.12
  region: eu-west-1
  httpApi:
    cors: true
  timeout: 10
  memorySize: 128
plugins:
  - serverless-python-requirements
  - serverless-offline
functions:
  app:
    package:
      patterns:
        - "fastapi_aws_starter_kit/**"
    handler: fastapi_aws_starter_kit.handler.handler
    events:
      - http:
          method: any
          path: /{proxy+}
          cors: true
custom:
  pythonRequirements:
    dockerizePip: true

As you can see I’m using 2 plugins:

serverless-python-requirements: It will bundle your python dependencies specified in your requirements.txt
serverless-offline: It will allow to run our infrastructure locally by running sls offline command.

Deploy your API

To deploy your API on AWS, you just need to perform:

sls deploy

Run your API in local

If you want to run your API in local, you have two options.
Either you can run an uvicorn web server like this:

import os
import uvicorn

if __name__ == "__main__":
    uvicorn.run(
        "fastapi_app:app",
        host="127.0.0.1",
        port=5000,
        reload=True,
    )

Either, and this what I recommend as we are using Serverless, you can use serverless-offline plugin I just mentionned before.

    ➜ sls offline
    Running "serverless" from node_modules
    Using local credentials. Add provider credentials via dashboard: https://app.serverless.com//providers

    Starting Offline at stage dev (eu-west-1)

    Offline [http for lambda] listening on http://localhost:3002
    Function names exposed for local invocation by aws-sdk:
               * app: fastapi-aws-starter-kit-dev-app

       ┌───────────────────────────────────────────────────────────────────────┐
       │                                                                       │
       │   ANY | http://localhost:3000/{proxy*}                                │
       │   POST | http://localhost:3000/2015-03-31/functions/app/invocations   │
       │                                                                       │
       └───────────────────────────────────────────────────────────────────────┘

    Server ready: http://localhost:3000 🚀

And that’s it ! 🚀

FastAPI AWS Starter Kit

Here the the repository related to this article:
GitHub - DevWaveX/fastapi-aws-starter-kit: Starter kit to deploy FastAPI as an AWS serverless…

I hope you enjoyed reading this article and that it will help you in your next projects ! 🤘

If you liked it, don’t forget to clap, share and subscribe 😉