Forem: Camilo Reyes

DynamoDB Single-Table Design with TypeScript

Camilo Reyes — Wed, 02 Oct 2024 14:22:51 +0000

Single-table design is a powerful approach to modeling data in DynamoDB because it allows you to store all your data in one place. This approach can simplify your data model and reduce the number of tables you need to manage.

In the traditional approach, you create a separate table for each entity in your application. For example, you might have a table for characters and a table for quests. Each table would have its own primary key and attributes. However, in DynamoDB, this can lead to inefficient queries and complex data models with high read and write costs.

In this take, we will build upon two existing tables for quests and characters and combine them into a single table. This will show you how to model complex relationships between entities in a single table with many different access patterns.

Ready? Let’s get started!

Getting Started

The source code for this article is in the GitHub repository. We will use TypeScript to write the code and the AWS SDK to interact with DynamoDB.

To spin up a quick TypeScript project, you can use the following commands:

mkdir node-dynamodb-single-table-design
cd node-dynamodb-single-table-design
npm init -y
npm i typescript @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb ulid
npx tsc --init

Data Model

Let’s start by defining our data model with separate tables. This is a good starting point to understand the entities and their relationships. We will have two tables: quests and characters. To make this concrete, let’s define the attributes for each table using TypeScript interfaces.

// models/character.ts
export interface Character {
  username: string // partition key
  class: string
  guild: string
  inventory: Record<string, number>
  total_play_time: number
}

// models/quest.ts
export interface Quest {
  username: string // partition key
  quest_id: string // sort key
  quest_name: string
  quest_started_at: string
  quest_completed_at?: string
  checkpoints: number[]
  gold: number

The partition keys are the same for both tables, which is the username. The quest_id is the sort key for the quests table.

Note the character has many quests, and each character has many items in their inventory. These relationships are focused on the following access patterns:

Get all quests for a character
Get character by username
Fetch inventory for a character

The key takeaway here is to understand the relationships between entities and access patterns because they will drive design decisions. In DynamoDB, these relationships and access patterns can be exploited to model the data in a single table.

Combining Entities

For single-table design, we can begin by combining the keys into a generic compound primary key. This will allow us to store both entities in the same table.

// models/game.ts
export interface Game {
  partition_key: string;
  sort_key: string;
  type: "Character" | "Quest";
}

Think of this interface as metadata that will help us differentiate between the entities while giving us the flexibility to store them in the same table. The partition_key will have a prefix, like USER#username, and the sort_key will have a prefix, like CHARACTER#username or QUEST#quest_id. Since both initial tables have the same partition key, the generic partition key will be the same for both entities.

The type attribute will help us differentiate between the entities, and TypeScript will help enforce type safety. This gives us both flexibility and powerful type checking.

With the generic compound primary key, we can now declare what the character item and quest item will look like in the single table.

// models/game.ts
export interface CharacterItem extends Game {
  class: string;
  guild: string;
  inventory: Record<string, number>;
  total_play_time: number;
}

export interface QuestItem extends Game {
  quest_name: string;
  quest_started_at: string;
  quest_completed_at?: string;
  checkpoints: number[];
  gold: number;
}

With these interfaces in place, we can express a character in the single table in this way:

{
  partition_key: 'USER#beautifulcoder',
  sort_key: 'CHARACTER#beautifulcoder',
  type: 'Character',
  class: 'Warrior',
  guild: 'Knights of the Round Table',
  inventory: { 'sword': 1, 'shield': 1 },
  total_play_time: 1000
}

The quest item will look like this:

{
  partition_key: 'USER#username',
  sort_key: 'QUEST#01HT7ZKCWJBSEWQRQJPPRFN8MM',
  type: 'Quest',
  quest_name: 'Defeat the Dragon',
  quest_started_at: '2022-01-01T00:00:00Z',
  quest_completed_at: '2022-01-01T01:00:00Z',
  checkpoints: [1, 2, 3],
  gold: 100
}

Each item in the table is optimized specifically for the access patterns we want to support. For example, we can fetch all quests for a character by querying the table with the partition key USER#username. The sort key gives us the ability to filter by the prefix QUEST# to fine-tune the query.

Note: With single-table design, we put heterogeneous data in the same table and use a generic compound primary key to differentiate between entities. This helps reduce the number of round trips to the database and simplifies the data model.

Access Pattern with Frequent Updates

In DynamoDB you get charged for read and write capacity units per table. You can break fast-moving attributes like total_play_time into a separate entity to reduce the cost of updating the entire item.

The character’s inventory likely will not change as frequently as the total_play_time. This allows us to introduce vertical partitioning.

Instead of having a single CharacterItem with all the attributes, we can break it into two entities: CharacterItem and InventoryItem.

// models/game.ts
export interface CharacterItem extends Game {
  class: string;
  guild: string;
  total_play_time: number;
}

export interface InventoryItem extends Game {
  inventory: Record<string, number>;
}

Now a single character item will look like this:

{
  partition_key: 'USER#beautifulcoder',
  sort_key: 'CHARACTER',
  type: 'Character',
  class: 'Warrior',
  guild: 'Knights of the Round Table',
  total_play_time: 1000
}

And the inventory item will look like this:

{
  partition_key: 'USER#beautifulcoder',
  sort_key: 'INVENTORY',
  type: 'Inventory',
  inventory: { 'sword': 1, 'shield': 1 }
}

Be sure to go back to the parent interface Game and update the type attribute to include Inventory.

// models/game.ts
export interface Game {
  partition_key: string;
  sort_key: string;
  type: "Character" | "Quest" | "Inventory";
}

This design allows us to update the total_play_time attribute without affecting the inventory.

Create the Single Table

With the data model in place, we can now create the single table in DynamoDB. We will use the AWS CLI to create the table with the following command:

aws dynamodb create-table \
  --table-name game \
  --attribute-definitions AttributeName=partition_key,AttributeType=S AttributeName=sort_key,AttributeType=S \
  --key-schema AttributeName=partition_key,KeyType=HASH AttributeName=sort_key,KeyType=RANGE \
  --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

Then we can add items to the table using the AWS SDK in TypeScript.

// add-game-items.ts
import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall } from "@aws-sdk/util-dynamodb";
import { ulid } from "ulid";

import type { CharacterItem, InventoryItem, QuestItem } from "./models/game";

const client = new DynamoDBClient();

const addCharacter = async (character: CharacterItem): Promise<void> => {
  await client.send(
    new PutItemCommand({
      TableName: "game",
      Item: marshall(character),
    })
  );
};

const addInventory = async (inventory: InventoryItem): Promise<void> => {
  await client.send(
    new PutItemCommand({
      TableName: "game",
      Item: marshall(inventory),
    })
  );
};

const addQuest = async (quest: QuestItem): Promise<void> => {
  await client.send(
    new PutItemCommand({
      TableName: "game",
      Item: marshall(quest),
    })
  );
};

void addCharacter({
  partition_key: "USER#beautifulcoder",
  sort_key: "CHARACTER",
  type: "Character",
  class: "Mage",
  guild: "Hacker",
  total_play_time: 3600,
});

void addInventory({
  partition_key: "USER#beautifulcoder",
  sort_key: "INVENTORY",
  type: "Inventory",
  inventory: {
    "Mechanical Keyboard": 1,
    "Kaihl Switches": 100,
    Coffee: 100000,
  },
});

const now = new Date();
const twoWeeksFromNow = new Date(Date.now() + 12096e5);
const minuteFromNow = new Date(Date.now() + 60000);

void addQuest({
  partition_key: "USER#beautifulcoder",
  sort_key: `QUEST#${ulid(now.getTime())}`,
  type: "Quest",
  quest_name: "Sole Survivor",
  quest_started_at: now.toISOString(),
  quest_completed_at: twoWeeksFromNow.toISOString(),
  checkpoints: [1, 2, 3, 4, 5],
  gold: 1000,
});

void addQuest({
  partition_key: "USER#beautifulcoder",
  sort_key: `QUEST#${ulid(minuteFromNow.getTime())}`,
  type: "Quest",
  quest_name: "A Lost Cause",
  quest_started_at: now.toISOString(),
  checkpoints: [6, 7, 8, 9, 10],
  gold: 10000,
});

You should see the items added to the table in the AWS Management Console. We recommend having a look at the items in the table to understand how the data is stored in DynamoDB.

Why Single Table Design?

In traditional relational databases, we normalize data to reduce redundancy and improve data integrity. The emphasis is on minimizing pressure on resources like CPU and memory to optimize database performance.

In DynamoDB, the emphasis is on reducing the number of reads and writes to our database to optimize the cost. This is where single-table design shines.

When it comes to fast-moving attributes like total_play_time, do the math. Say, for example, we update the total play time every 30 seconds. If a character item with its inventory takes up 4KB of space, and there are four target indexes, we would incur a cost of 1,920 write capacity units per hour (4KB x 4 x 120). If we break the inventory into a separate entity, we would only incur a cost of 480 write capacity units per hour (1KB x 4 x 120). This is a 75% reduction.

By breaking up entities into smaller pieces via vertical slicing within a single table, we can reduce the cost of updating the entire item when only a few attributes need to be updated. Because DynamoDB charges per table and per read/write capacity unit, this can lead to significant cost savings.

One Table, Many Access Patterns

Each DynamoDB table comes with a cost. You need to configure alarms, monitor metrics, and handle backups and restores. DynamoDB charges based on the provisioned capacity, the amount of data stored, and the number of read and write requests.

DynamoDB does not support joins or complex queries across multiple tables. Each table has its own partition key, and you can only query the partition key and sort key. Joins must be done in the application layer. This means more round trips to the database and more read and write capacity units are consumed when there are multiple tables.

Wrapping Up

In this post, we've seen how by using a single table design, you can reduce the number of tables you need to manage. This can lead to significant cost savings. You can also reduce the number of round trips to the database and simplify the data model.

Happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Grokking DynamoDB with TypeScript

Camilo Reyes — Wed, 07 Aug 2024 11:00:00 +0000

DynamoDB is a fully managed NoSQL database service provided by AWS. It is highly available, scalable, and a great fit for applications that need to handle large amounts of data with low latency. DynamoDB is a key-value document database, meaning that it is schema-less and can store any kind of data. It is also a serverless service, so you don’t have to worry about managing and scaling servers.

In this take, we will model data in DynamoDB using TypeScript. We will start by modeling a simple table with a partition key and some attributes. Then, we will model another table with a composite primary key using a partition key and a sort key. We will also explore secondary indexes and conditional expressions.

Setup and Prerequisites

Our data model will consist of a made-up open-world RPG game. We will model a table for characters and a table for quests. The characters table will have a simple partition key, and the quests table will have a composite primary key.

The access patterns will dictate how we will model this data based on use cases for the game.

As a prerequisite, you should have:

An AWS account with the AWS CLI installed and configured
Node.js installed
npm installed

You can also clone the GitHub repository for this project.

To follow along with the code examples, create a TypeScript project using the following commands:

mkdir node-dynamodb-playground
cd node-dynamodb-playground
npm init -y
npm i typescript @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb ulid
npx tsc --init

Be sure to add the following to your package.json file:

{
  "scripts": {
    "build": "tsc"
  }
}

Ready? Let’s get started!

What Are Access Patterns in DynamoDB?

In DynamoDB, access patterns are the different ways to access your data. They are the queries and scans that you will perform on your tables. These must come directly from your application’s use cases.

For our RPG game, we will have the following access patterns:

Get character by username
Fetch inventory for a character
Fetch characters by guild
Get all quests for a character
Fetch completed quests for a character

Note: The key to modeling data in DynamoDB is to understand your access patterns first and then model your data accordingly.

A common misconception about NoSQL databases is that they are schema-less and, therefore, flexible. While it is true that you can store any kind of data in DynamoDB, it is important to know your access patterns. If you want to keep latencies low, you need to optimize your data model for your access patterns, which means the schema is actually not very flexible.

Now that we have our access patterns, let’s start modeling our data.

Partition Keys

Using the AWS CLI tool, create a new table named characters with a simple partition key.

aws dynamodb create-table \
  --table-name characters \
  --attribute-definitions AttributeName=username,AttributeType=S \
  --key-schema AttributeName=username,KeyType=HASH \
  --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

Then, let’s create a TypeScript interface to model our character.

// models/character.ts

export interface Character {
  username: string;
  class: string;
  guild: string;
  inventory: Record<string, number>;
  total_play_time: number;
}

Now, add a character to the table via TypeScript.

// add-character.ts

import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall } from "@aws-sdk/util-dynamodb";

import type { Character } from "./models/character";

const client = new DynamoDBClient();

const addCharacter = async (character: Character): Promise<void> => {
  await client.send(
    new PutItemCommand({
      TableName: "characters",
      Item: marshall(character),
    })
  );
};

void addCharacter({
  username: "beautifulcoder",
  class: "Mage",
  guild: "Hacker",
  inventory: {
    "Mechanical Keyboard": 1,
    "Kaihl Switches": 100,
    Coffee: 100000,
  },
  total_play_time: 3600,
});

Note that we are using the marshall function from @aws-sdk/util-dynamodb to convert our JavaScript object to a DynamoDB record. In this way, we can use TypeScript interfaces to model our data and then convert this to a DynamoDB record.

DynamoDB supports the following data types:

Scalar types: Number, String, Binary, Boolean, and Null
Document types: Array and JavaScript Object
Set types: Number Set, String Set, and Binary Set

Note: Set types must be unique and do not support duplicates.

The TypeScript interface strictly adheres to our access patterns and DynamoDB data types. We can get a character by username, pulling up their inventory and guild within a single round-trip. One recommendation is to first define the access patterns and then write the TypeScript interfaces to model the data.

Optimizing access patterns will also reduce the number of round-trips to the database, which will help keep latencies low.

Composite Keys

Now, let’s model another table with a composite primary key, using a partition key and a sort key. We will model a table for quests with a composite primary key. This time, we will use a ULID as the sort key to help model and access our data.

aws dynamodb create-table \
  --table-name quests \
  --attribute-definitions AttributeName=username,AttributeType=S AttributeName=quest_id,AttributeType=S \
  --key-schema AttributeName=username,KeyType=HASH AttributeName=quest_id,KeyType=RANGE \
  --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

To model a quest, we will use the following TypeScript interface:

// models/quest.ts

export interface Quest {
  username: string;
  quest_id: string;
  quest_name: string;
  quest_started_at: string;
  quest_completed_at?: string;
  checkpoints: number[];
  gold: number;
}

The quest_completed_at attribute remains optional, because the quest may never be completed. This is one of the benefits of using a NoSQL database. You can store any kind of data and reduce any unnecessary attributes.

Now, add a quest to the table via TypeScript.

// add-quest.ts

import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall } from "@aws-sdk/util-dynamodb";
import { ulid } from "ulid";

import type { Quest } from "./models/quest";

const client = new DynamoDBClient();

const addQuest = async (quest: Quest): Promise<void> => {
  await client.send(
    new PutItemCommand({
      TableName: "quests",
      Item: marshall(quest),
    })
  );
};

const now = new Date();
const twoWeeksFromNow = new Date(Date.now() + 12096e5);
const minuteFromNow = new Date(Date.now() + 60000);

void addQuest({
  username: "beautifulcoder",
  quest_id: ulid(now.getTime()),
  quest_name: "Sole Survivor",
  quest_started_at: now.toISOString(),
  quest_completed_at: twoWeeksFromNow.toISOString(),
  checkpoints: [1, 2, 3, 4, 5],
  gold: 1000,
});

void addQuest({
  username: "beautifulcoder",
  quest_id: ulid(minuteFromNow.getTime()),
  quest_name: "A Lost Cause",
  quest_started_at: now.toISOString(),
  checkpoints: [6, 7, 8, 9, 10],
  gold: 10000,
});

Because we use a ULID as the sort key, DynamoDB will sort the quests by the time they are created. This will help us fetch all quests for a character and easily filter the data based on the time the quest was created.

Secondary Indexes

So far, we have modeled our data based on most of our access patterns. However, we have not yet modeled the access pattern to fetch our characters by guild. We can use a global secondary index to help query the data without a table scan.

aws dynamodb update-table \
  --table-name characters \
  --attribute-definitions AttributeName=guild,AttributeType=S AttributeName=username,AttributeType=S \
  --global-secondary-index-updates file://gsi-guild-username.json

Create a file named gsi-guild-username.json with the following JSON content:

[
  {
    "Create": {
      "IndexName": "gsi-guild-username",
      "KeySchema": [
        {
          "AttributeName": "guild",
          "KeyType": "HASH"
        },
        {
          "AttributeName": "username",
          "KeyType": "RANGE"
        }
      ],
      "Projection": {
        "ProjectionType": "ALL"
      },
      "ProvisionedThroughput": {
        "ReadCapacityUnits": 1,
        "WriteCapacityUnits": 1
      }
    }
  }
]

This global secondary index works much like a partition key and sort key, but with a different primary key. DynamoDB will create a new index with the same data and replicate the data from the main table. All writes must still flow through the primary table because secondary indexes are read-only.

Lastly, to fetch the quests that a character completes, we can filter our data by using a global secondary index. This will maintain the same primary key as the main table, but with a different sort key. This will also exclude any uncompleted quests from the secondary index. DynamoDB will optimize the reads because it does not send any irrelevant data in the queries.

aws dynamodb update-table \
  --table-name quests \
  --attribute-definitions AttributeName=username,AttributeType=S AttributeName=quest_completed_at,AttributeType=S \
  --global-secondary-index-updates file://gsi-username-quest_completed_at.json

Create a file named gsi-username-quest_completed_at.json with the following content:

[
  {
    "Create": {
      "IndexName": "gsi-username-quest_completed_at",
      "KeySchema": [
        {
          "AttributeName": "username",
          "KeyType": "HASH"
        },
        {
          "AttributeName": "quest_completed_at",
          "KeyType": "RANGE"
        }
      ],
      "Projection": {
        "ProjectionType": "ALL"
      },
      "ProvisionedThroughput": {
        "ReadCapacityUnits": 1,
        "WriteCapacityUnits": 1
      }
    }
  }
]

Alternatively, you can use a local secondary index to filter completed quests. Local secondary indexes share the same partition key as the main table and increase the partition size (which is limited to 10 GB). They must also be created with the main table and cannot be added or removed afterward.

Global secondary indexes have their own partition and sort keys, and can filter data across the entire table.

You should now be able to log into the AWS Management Console and see the tables and indexes you have created. You can also add data to the tables and query the data using the console.

Conditional Expressions

With our access patterns modeled, let's take a character and give them more coffee, if they have less than a certain amount of coffee in their inventory. We can use a conditional expression to avoid overwriting data and ensure that we are reading the most recent data.

// conditional-expression.ts

import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall } from "@aws-sdk/util-dynamodb";

const client = new DynamoDBClient();

const moreCoffee = async (username: string): Promise<void> => {
  await client.send(
    new UpdateItemCommand({
      TableName: "characters",
      Key: marshall({ username }),
      UpdateExpression: "SET inventory.Coffee = inventory.Coffee + :moreCoffee",
      ConditionExpression: "inventory.Coffee < :maxCoffee",
      ExpressionAttributeValues: {
        ":maxCoffee": { N: "200000" },
        ":moreCoffee": { N: "10000" },
      },
    })
  );
};

void moreCoffee("beautifulcoder");

Keep in mind that all writes must flow through the primary key in the table. Update expressions can tap into the latest data available and perform conditional writes.

DynamoDB has eventual consistency, so it is important to use conditional expressions to avoid overwriting data via a read race condition. This technique will also help keep latencies low and reduce the number of round-trips to the database.

Wrapping Up

In this post, we've seen that when working with DynamoDB, it is important to model your data based on your access patterns. The goal should be to reduce the number of round-trips to the database and keep latencies low.

DynamoDB is a powerful NoSQL database that can store any form of data and scale to any size. Optimizing for access patterns will help you get the most out of DynamoDB.

Happy scaling!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Develop a Serverless TypeScript API on AWS ECS with Fargate

Camilo Reyes — Wed, 19 Jun 2024 12:00:00 +0000

AWS Fargate is a serverless compute engine that allows you to run containers without managing servers. With Fargate, you no longer have to provision clusters of virtual machines to run ECS containers: this is all done for you.

Fargate has an Amazon ECS construct that can host an API. In this take, we will build a Fargate service using the AWS CDK, put the API in a docker image, and then host it inside Amazon ECS.

The API will be a pizza API and we'll store the data in a DynamoDB table.

Let’s get started!

Why Use Fargate with ECS?

Fargate has some benefits over lambda functions because of provisioned servers. When you have a high volume of traffic, you can save on costs by running containers. These can scale out to as many servers as needed to meet the current demand and avoid paying per request. Once you have millions of requests per day or even per hour, paying per actual load starts to become more cost-effective.

The one gotcha here is that scaling out can become a bit of a hassle because, by the time you spin up a new container, it is already too late to handle the current load. A good technique is to come up with scaling strategies ahead of time, which means you definitely must have a predictable load.

Requirements

Feel free to clone the sample code for this project from GitHub.

Be sure to have the latest version of Node and the AWS CDK Toolkit installed.

> npm install -g aws-cdk

Then, simply spin up a new TypeScript project using the toolkit.

> mkdir node-fargate-api
> cd node-fargate-api
> cdk init --language typescript
> cdk synth

Build the ECR Image

First, install Fastify and DynamoDB in the root package.json file. Then, create an app folder to contain the application.

> npm i fastify @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb --save
> mkdir app

Create the app/api.ts file and add this code snippet:

import Fastify from "fastify";
import {
  DynamoDBClient,
  GetItemCommand,
  PutItemCommand,
} from "@aws-sdk/client-dynamodb";
import { unmarshall } from "@aws-sdk/util-dynamodb";

const client = new DynamoDBClient();

const fastify = Fastify({
  logger: true,
});

fastify.get("/pizzas/:id", async (request, reply) => {
  const { id } = request.params as any;

  const res = await client.send(
    new GetItemCommand({
      TableName: "pizzas",
      Key: { id: { N: id } },
    })
  );

  const item = res.Item;

  if (item === undefined) {
    reply.callNotFound();

    return;
  }

  const pizza = unmarshall(item);
  const { ingredients } = pizza;

  await reply.status(200).send({ ...pizza, ingredients: [...ingredients] });
});

fastify.put("/pizzas/:id", async (request, reply) => {
  const { id } = request.params as any;
  const { name, ingredients } = request.body as any;

  const pizza = {
    id: { N: id },
    name: { S: name },
    ingredients: { SS: ingredients },
  };

  await client.send(
    new PutItemCommand({
      TableName: "pizzas",
      Item: pizza,
    })
  );

  await reply.status(200).send({ id, name, ingredients });
});

fastify.get("/health", async (request, reply) => {
  await reply.status(200).send();
});

const { ADDRESS = "localhost", PORT = 3000 } = process.env;

const start = async (): Promise<void> => {
  try {
    await fastify.listen({ port: Number(PORT), host: ADDRESS });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

void start();

This is a pizza API with GET/PUT endpoints. We store the data in a DynamoDB table.

Note: The host and port come from an environment variable when this runs in Fargate. This guarantees the app runs on 0.0.0.0 and not the loopback IP address. The port number must also be 80 for HTTP traffic.

To upload the app to an ECR image, create a repository in the AWS console.

Log in to AWS and click 'Elastic Container Registry'
Click 'Create repository'
Leave it as Private
Set a name, for example, pizza-fargate-api, and make note of this

Next, create the Dockerfile in the root folder.

FROM node:20-alpine

WORKDIR /usr/src/app

COPY package*.json ./
COPY tsconfig.json ./
COPY app/* ./
RUN npm ci --omit=dev && npm run build
COPY . .

ENV ADDRESS=0.0.0.0 PORT=80

CMD ["node", "app/api.js"]

Note: For this docker build to work, be sure to move typescript and @types/node in the package.json file from dev to just plain dependencies.

For the load balancer to get access to the container, be sure to specify the PORT and ADDRESS. As mentioned, this cannot be the loopback 127.0.0.0 because it does not allow incoming connections from outside the container. In Fastify, this is the default behavior, so we must manually set this IP address.

In ECR, click on the newly created repository, then 'View push commands'. This lists instructions for uploading the docker image to the repository (they are self-explanatory, so we will not repeat them here).

Once the commands complete successfully, the image should appear in the Amazon Elastic Container Registry.

The AWS CDK

Open the node-fargate-api-stack.ts file and drop in this entire code snippet.

import * as cdk from "aws-cdk-lib";
import type { Construct } from "constructs";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import * as ecs from "aws-cdk-lib/aws-ecs";
import * as ecs_patterns from "aws-cdk-lib/aws-ecs-patterns";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as iam from "aws-cdk-lib/aws-iam";
import * as ecr from "aws-cdk-lib/aws-ecr";
import * as logs from "aws-cdk-lib/aws-logs";

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

    const vpc = ec2.Vpc.fromLookup(this, "vpc", {
      vpcId: "VPC_ID",
    });

    const cluster = new ecs.Cluster(this, "cluster", {
      vpc,
    });

    const repository = ecr.Repository.fromRepositoryName(
      this,
      "repository",
      "pizza-fargate-api"
    );

    const service = new ecs_patterns.ApplicationLoadBalancedFargateService(
      this,
      "api",
      {
        cluster,
        cpu: 256,
        desiredCount: 1,
        taskImageOptions: {
          image: ecs.ContainerImage.fromEcrRepository(repository, "latest"),
          containerPort: 80,
          logDriver: new ecs.AwsLogDriver({
            streamPrefix: "api",
            logRetention: logs.RetentionDays.THREE_DAYS,
          }),
        },
        memoryLimitMiB: 512,
        publicLoadBalancer: true,
      }
    );

    const taskCount = service.service.autoScaleTaskCount({ maxCapacity: 5 });
    taskCount.scaleOnCpuUtilization("cpu-scaling", {
      targetUtilizationPercent: 45,
      scaleInCooldown: cdk.Duration.seconds(60),
      scaleOutCooldown: cdk.Duration.seconds(60),
    });

    service.targetGroup.configureHealthCheck({ path: "/health" });

    const table = new dynamodb.Table(this, "table", {
      tableName: "pizzas",
      partitionKey: {
        name: "id",
        type: dynamodb.AttributeType.NUMBER,
      },
    });

    service.taskDefinition.taskRole.addToPrincipalPolicy(
      new iam.PolicyStatement({
        actions: ["dynamodb:*"],
        resources: [table.tableArn],
      })
    );
  }
}

The ApplicationLoadBalancedFargateService construct needs a VPC (which should already exist in your AWS account). The load balancer directs HTTP traffic from the internet to the cluster. This is the reason why it is publicly available.

The DynamoDB table simply declares a main partition key: the number id and table name. The task definition is then granted full access to the DynamoDB table.

The cpu, desiredCount, and memoryLimitMiB set scalability configuration for the service when it first starts. The service uses task definitions to spin up new containers that can handle the load. You can manually scale Fargate by updating the desired task count in your service definition. This CDK also creates auto-scaling policies based on metrics like CPU utilization. Fargate uses CloudWatch alarms to trigger scaling actions based on metrics or events.

For this CDK to work, be sure to update the main entry point in bin/node-fargate-api.ts. Set the account number and region.

Unit Test the CDK

Type cdk synth in a terminal, then inspect the CloudFormation YAML template that will get uploaded to AWS. This has enough information to write unit tests.

Open node-fargate-api.test.ts in the test folder and enter this code snippet.

import * as cdk from "aws-cdk-lib";
import { Template } from "aws-cdk-lib/assertions";
import * as api from "../lib/node-fargate-api-stack";

test("Fargate service created", () => {
  const app = new cdk.App();

  const stack = new api.NodeFargateApiStack(app, "test-stack", {
    env: { account: "0123456789", region: "us-east-1" },
  });

  const template = Template.fromStack(stack);

  template.hasResourceProperties("AWS::ECS::Service", {
    LaunchType: "FARGATE",
    LoadBalancers: [
      {
        ContainerName: "web",
        ContainerPort: 80,
      },
    ],
  });
});

test("DynamoDB table created", () => {
  const app = new cdk.App();

  const stack = new api.NodeFargateApiStack(app, "test-stack", {
    env: { account: "0123456789", region: "us-east-1" },
  });

  const template = Template.fromStack(stack);

  template.hasResourceProperties("AWS::DynamoDB::Table", {
    TableName: "pizzas",
  });
});

This time, it is important to specify the env for each test because the VPC lookup in the stack requires the environment. Luckily, you can mock the account id and region because it is just a unit test. What is important is that the unit test verifies the YAML template since we are creating these specific resources via the CDK.

The Load Balancer

Before we can check that the load balancer works, simply deploy the CDK.

> cdk deploy

Note: If the deploy takes a very long time, it is likely that the load balancer cannot clear the health endpoint check. Simply cancel the deploy, then go back and double-check your CDK.

The CDK should have an output with a publicly accessible URL from the load balancer. You can now hit the two endpoints with CURL.

> curl -i -X PUT -H "Content-Type: application/json" \
  -d "{\"name\":\"Pepperoni Pizza\",\"ingredients\":[\"cheese\",\"tomato\",\"pepperoni\"]}" \
  http://LBNAME-ACCOUNT.REGION.elb.amazonaws.com/pizzas/1

> curl -i -X GET -H "Content-Type: application/json" http://LBNAME-ACCOUTN.REGION.elb.amazonaws.com/pizzas/1

To smack this API with as many requests as possible, write this K6 script and save it as a JavaScript file.

import { check } from "k6";
import http from "k6/http";

export default function () {
  const res = http.get(
    "http://LBNAME-ACCOUNT.REGION.elb.amazonaws.com/pizzas/1"
  );
  check(res, {
    "is status 200": (r) => r.status === 200,
  });
}

Then, run a load test using K6:

k6 run --vus 50 --duration 20m load-test.js

This test simulates 50 users hitting the API at the same time for 20 minutes. The reason you want to go for 20 minutes is because Fargate takes a few minutes to spin up new tasks to handle the current load. This is the reason why Fargate does better with predictable load. By the time the new task spins up, it might already be too late. (In contrast, a lambda function cold starts in mere seconds on the slower end and is therefore more suitable for spiky unpredictable traffic).

The load test might also show some failing requests. This happens because tasks are sometimes too slow to spin up and respond to current incoming traffic.

By the end of the load test, you should see the maximum amount of configured tasks running in your service.

Before we end, be sure to fire a cdk destroy so you don't accrue further EC2 charges. The one downside to Fargate is that you continue to pay for the running service even when there is no traffic.

Wrapping Up

In this post, we built and hosted a Fargate service using AWS CDK and Amazon ECS.

We've seen that Fargate running on ECS can be a great alternative to lambda functions. Given predictable traffic and heavy load, it is possible to save on costs because you are not paying per request.

Happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

AWS Step Functions with Node.js: Build an API

Camilo Reyes — Wed, 25 Oct 2023 11:00:00 +0000

In the first part of this series, we built the asynchronous components of a much larger solution. Today, we will build the API interface that can be consumed in real-time.

Recap

So far, we have set up two step functions to process resumes asynchronously. The first step function takes a resume from an S3 bucket and generates a downloadable URL. The second uses Textract to parse the uploaded resume and find the GitHub profile. Both functions take a few seconds to make this data available for consumption in an SQS queue.

What We’ll Cover In This Part

We will build an API with three endpoints:

A POST endpoint to upload resumes in binary format.
A GET endpoint to check for incoming messages in the SQS queue.
Lastly, a DELETE endpoint to nuke old messages that a recruiter has already looked at.

In this take, we will build our API on top of the preexisting step functions. The API will mostly interact with the state machine, S3, and SQS.

Both the client-facing API and the step functions that run in the background are independent of each other: you can change one solution without changing the other, because step functions can run asynchronously and without blocking.

This models the real world more closely, as recruiters don't sit around waiting for candidates to upload resumes. They can simply check for incoming resumes as they are ready for consumption.

Ready? Let’s go!

Resume API: Deploy with Claudia.js

You should already have a main project folder with two step functions. Simply add a third folder with the resume API.

node-aws-step-functions
`-- look-for-github-profile-step
`-- upload-resume-step
`-- resume-uploader-api

Inside resume-uploader-api, run npm init to initialize a package.json file. Make sure the name property in the JSON matches the folder name. This is what sets the name of the Lambda function and the Gateway API when you deploy the project.

Since we are using Claudia.js to deploy the API, add this dependency to the project:

> npm i claudia@latest --save-dev
> npm i claudia-api-builder@latest --save

Open the package.json file and specify these commands in the scripts section:

"scripts": {
  "start": "claudia create --region us-east-1 --no-optional-dependencies --api-module pub/bundle --runtime nodejs18.x --memory 1536 --arch arm64",
  "deploy": "claudia update --no-optional-dependencies"
}

Here, we specify a 1.5GB allocation in the Lambda function and the ARM Graviton2 chip. Unless your app has specific code that must run on x86, AWS recommends using their custom ARM chip. This much memory allocation helps keep latencies low for the client app. Do not worry about how much memory the app uses; focus instead on CPU cores and perceived latencies for actual users.

Be sure to double-check your region and pick the one that is closest to you.

Add these S3, SQS, and SFN dependencies to the project:

> npm i @aws-sdk/client-s3@latest @aws-sdk/client-sfn@latest @aws-sdk/client-sqs@latest --save

Here is what each dependency is for:

@aws-sdk/client-s3: S3 client that uploaded resumes go in
@aws-sdk/client-sfn: Step functions client to start the asynchronous process
@aws-sdk/client-sqs: SQS client to retrieve and purge messages

Next, create a web.js file and add the following scaffolding:

const {
  PutObjectCommand, // put uploaded resumes in S3
  S3Client,
} = require("@aws-sdk/client-s3");
const {
  SFNClient,
  StartExecutionCommand, // start the state machine
} = require("@aws-sdk/client-sfn");
const {
  SQSClient,
  ReceiveMessageCommand, // receive SQS messages
  PurgeQueueCommand, // purge SQS messeages in the queue
} = require("@aws-sdk/client-sqs");
const ApiBuilder = require("claudia-api-builder");

const api = new ApiBuilder();

// double check the region
const s3Client = new S3Client("us-east-1");
const sfnClient = new SFNClient("us-east-1");
const sqsClient = new SQSClient("us-east-1");

const s3BucketName = "<unique-bucket-name>";
const stateMachineArn = "<state-machine-arn>";
const queueUrl = "<sqs-queue-url>";

// Rest of the codes goes here

module.exports = api;

Assuming you have followed along since the previous post, you should already have an S3 bucket, a state machine, and an SQS queue URL. These values can be found in the AWS console. Double-check that your region is set correctly.

To find the state machine ARN, log in to the AWS console and go to 'Step Functions'. Then, click on your state machine and the ARN should be at the top of the page.

To find the SQS queue URL, go to 'Simple Queue Service' and click on your queue. The URL should be at the top of the page as well.

Add POST Endpoint to the API

In the web.js file, add this POST endpoint to the API:

api.post(
  "/",
  async function (request) {
    const storedFileName = request.queryString.fileName;
    const fileContents = request.body; // binary format 'application/pdf'

    const s3Command = new PutObjectCommand({
      Bucket: s3BucketName,
      Key: storedFileName,
      Body: fileContents,
    });

    await s3Client.send(s3Command);

    const sfnCommand = new StartExecutionCommand({
      input: JSON.stringify({ storedFileName }),
      stateMachineArn,
    });

    await sfnClient.send(sfnCommand);
  },
  {
    success: { code: 204 },
  }
);

This does two things:

Uploads the resume from the request body into an S3 bucket.
Kicks off the asynchronous process via the state machine.

Note that the API returns a 204 No Content response immediately. This is what keeps perceived latencies low because the API does not wait on the state machine to complete. The async/await used here does not logically block the API.

GET Endpoint: Check for Messages

Add this to the same web.js file:

api.get("/", async function () {
  const command = new ReceiveMessageCommand({
    QueueUrl: queueUrl,
  });

  const response = await sqsClient.send(command);

  response.Messages =
    response.Messages?.map((message) => JSON.parse(message.Body)) || []; // fallback to empty list

  return response;
});

Processed resumes eventually end up in the SQS queue. Here, we check for messages in the response object. If there are no messages yet, then we return an empty array.

DELETE Endpoint: Remove Old Messages

Lastly, add this to the web.js file:

api.delete(
  "/",
  async function () {
    const command = new PurgeQueueCommand({
      QueueUrl: queueUrl,
    });

    await sqsClient.send(command);
  },
  {
    success: { code: 204 },
  }
);

The purge command clears the SQS queue of any messages. This lets recruiters clear the queue once they are done reviewing incoming resumes.

All these API endpoints are designed to be fast and completely independent from the complex processing that happens in the background. Before we deploy this to AWS, let’s trim the bundle size so this executes even faster.

Deploy the API on AWS

To create an optimized bundle, install the webpack dependencies:

> npm i webpack@latest webpack-cli@latest --save-dev

Inside the resume-uploader-api folder, create a webpack.config.js file with the following:

const path = require("path");

module.exports = {
  entry: [path.join(__dirname, "web.js")],
  output: {
    path: path.join(__dirname, "pub"),
    filename: "bundle.js",
    libraryTarget: "commonjs",
  },
  target: "node",
  mode: "production",
};

Next, create an .npmignore file to trim the final bundle zip file.

node_modules/
claudia.json
event.json
webpack.config.js

Lastly, open the package.json file and change the dependencies property to optionalDependencies. This is what nukes all dependencies in the node_modules folder so that they are not included in the output file.

With webpack in place, simply run npm start to deploy the API on AWS. Once the deployment completes successfully, make a note of the url property in the JSON output, because you will need this later.

Test the API

Be sure to double-check permissions. Find the resume-uploader-api-executor role in the AWS console under IAM. Add AmazonS3FullAccess, AmazonSQSFullAccess, and AWSStepFunctionsFullAccess permissions to this role.

Because the AWS Gateway already handles binary format, we can simply upload a resume using CURL. As long as we set the content type to application/pdf, the gateway and our deploy tool will handle this automatically.

Now find the ExampleResume.pdf used in the previous post. If you created one yourself, use that instead. Then upload a resume in CURL:

> curl -i -X POST -H "Content-Type: application/pdf" --data-binary "@ExampleResume.pdf" https://<GATEWAY-API-ID>.execute-api.<REGION>.amazonaws.com/latest?fileName=ExampleResume.pdf

This should respond immediately with a 204 HTTP status code. Next, fire another request to check the status of the SQS queue.

> curl -i -X GET -H "Accept: application/json" https://<GATEWAY-API-ID>.execute-api.<REGION>.amazonaws.com/latest

This should return an empty array depending on how fast you type. If this takes you more than a few seconds, the API will respond with a processed resume. Remember, the actual processing is happening in the background. Our API is meant for real-time consumption, so you can come back and check on the queue at any time.

You can clear the queue once you are done reviewing resumes.

> curl -i -X DELETE -H "Accept: application/json" https://<GATEWAY-API-ID>.execute-api.<REGION>.amazonaws.com/latest

If you somehow lose the URL with the GATEWAY-API-ID and REGION, log into the AWS console, go to the API Gateway, and click resume-uploader-api. The Invoke URL can be found under 'Stages' (click on the latest).

Wrapping Up

In part one of this series, we deployed Lambda step functions in AWS using Claudia.js. We then built a state machine, deployed our step function to AWS, and tested it. In this part, we built the API interface.

Asynchronous background processing via step functions helps reduce the perceived latency of complex solutions. The API we put in place simply moves this complexity elsewhere so it does not get blocked and force actual users to wait.

Happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Deploy and Test AWS Step Functions with Node.js

Camilo Reyes — Wed, 11 Oct 2023 11:20:58 +0000

Complex functionality can take a while to load. Users, in general, don't like to wait, so solutions must evolve.

If you are already familiar with async/await in JavaScript, think of await as the place where blocking logically occurs. This forces the algorithm to wait, and technically, it's still synchronous code.

Step functions allow long-running processes to run in the background asynchronously, so the logic does not get blocked and force people to wait.

Let's take a look at how to use AWS step functions with Node.

Our Example: A Resume Uploader

We will be building a resume uploader that curates resumes for a recruiter. First, a resume gets uploaded in S3 and runs asynchronously via step functions. We will use AI tools in AWS like Textract to parse the resume.

Then, the result goes in SQS for asynchronous consumption. The SQS entry will have a direct link to the resume, and a link to the GitHub repo found in the resume.

You can follow along or clone the repo from GitHub. Some familiarity with Node and NPM is expected, but no prior experience with AWS is required.

Ready? Let’s go!

First, fire up a project folder and a couple of sub-folders for each step function. This is the basic folder structure:

node-aws-step-functions
`-- look-for-github-profile-step
`-- upload-resume-step

In each sub-folder, fire up npm init to create a package.json file. Simply make sure the name property in the JSON matches the folder name.

Deploy Your Node.js Lambda Step Functions with Claudia.js

We will use Claudia.js to deploy the Lambda functions for each step. Be sure to add this dev dependency for each sub-folder.

> npm i claudia@latest --save-dev

Also, open both package.json files side-by-side, then specify these commands in the scripts section.

"scripts": {
  "start": "claudia create --region us-east-1 --no-optional-dependencies --handler main.handler --runtime nodejs18.x --memory 1024 --arch arm64",
  "deploy": "claudia update --no-optional-dependencies --handler main.handler"
}

This deploys your Lambda step function in AWS. Double-check the region (here, it’s us-east-1) and ensure it is the one closest to you. Be sure to have proper credentials on your machine to successfully deploy the Lambda function.

Note: Setting up your Lambda function locally to authenticate to AWS is outside the scope of this tutorial.

Next, go into the look-for-github-profile-step project folder and add this dependency:

> npm i @aws-sdk/client-textract@latest --save

Then, go into the upload-resume-step project folder and add these dependencies:

> npm i @aws-sdk/client-s3@latest @aws-sdk/s3-request-presigner@latest --save

With both package.json files taking shape, it’s time to start writing code.

`look-for-github-profile-step`

Create a main.js file inside the look-for-github-profile-step project folder. Implement the code that parses the resume and plucks the GitHub profile URL. This step function is responsible for using Textract (an AI service from AWS) and passing state back to the state machine.

const {
  TextractClient,
  DetectDocumentTextCommand,
} = require("@aws-sdk/client-textract");

const textractClient = new TextractClient({ region: "us-east-1" });

const s3BucketName = "resume-uploader-upload-<unique-name>"; // must be unique

// lambda step function handler function
exports.handler = async (event, _context, callback) => {
  const command = new DetectDocumentTextCommand({
    Document: {
      S3Object: {
        Bucket: s3BucketName,
        Name: event.storedFileName,
      },
    },
  });

  const detectResponse = await textractClient.send(command);

  event.githubProfileUrl = detectResponse.Blocks.find(
    // parser
    (b) => b.BlockType === "WORD" && b.Text.includes("github.com")
  )?.Text;

  callback(null, event); // state machine
};

The Textract client can use S3 to find the uploaded resume and parse the document. Then, we simply nab a word match that includes the GitHub URL.

Run npm start to get this Lambda function on AWS. Once done, be sure to grant AmazonS3FullAccess and AmazonTextractFullAccess permissions to the look-for-github-profile-step-executor role in IAM.

`upload-resume-step`

Next, create a main.js file inside the upload-resume-step project folder. This time, put some code in place that makes the download link available.

const { GetObjectCommand, S3Client } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const s3Client = new S3Client("us-east-1");

const s3BucketName = "resume-uploader-upload-<unique-name>"; // must be unique
const signedUrlExpireSeconds = 24 * 60 * 60; // 1 day

exports.handler = async (event, _context, callback) => {
  const command = new GetObjectCommand({
    Bucket: s3BucketName,
    Key: event.storedFileName,
  });

  event.storedFileUrl = await getSignedUrl(s3Client, command, {
    expiresIn: signedUrlExpireSeconds,
  }); // URL for download

  callback(null, event); // state machine
};

The function that does most of the work here is getSignedUrl, which makes the URL available for download.

Simply run npm start. Once done, be sure to grant AmazonS3FullAccess permissions to the upload-resume-step-executor role in IAM.

Build A State Machine in AWS

The step functions above can run in isolation, but belong in a complex state machine that orchestrates execution. The state machine does this via events and fires one step function at a time. Keep in mind that this is happening in the background, and the only way to interact with the asynchronous process is via the state machine.

In AWS, create a state machine under 'Step Functions'. Pick the 'Write your workflow in code' option, and click 'Express'. Also, click on 'Create a new role' under 'Permissions'. The role is automatically created by the wizard.

Below is the workflow definition for the state machine:

{
  "Comment": "Resume Uploader State Machine",
  "StartAt": "UploadResume",
  "States": {
    "UploadResume": {
      "Type": "Task",
      "Resource": "{UploadResume.Arn}",
      "Next": "LookForGithubProfile"
    },
    "LookForGithubProfile": {
      "Type": "Task",
      "Resource": "{LookForGithubProfile.Arn}",
      "Next": "QueueResume"
    },
    "QueueResume": {
      "Type": "Task",
      "Resource": "arn:aws:states:::sqs:sendMessage",
      "Parameters": {
        "QueueUrl": "{Sqs.Url}",
        "MessageBody": {
          "storedFileUrl.$": "$.storedFileUrl",
          "githubProfileUrl.$": "$.githubProfileUrl"
        }
      },
      "End": true
    }
  }
}

Be sure to specify the correct values for {UploadResume.Arn}, {LookForGithubProfile.Arn}, and {Sqs.Url}.

The Arn is the Amazon Resource Name of a Lambda function, shown on the page's upper right corner.

Lastly, you will need to create an SQS queue and then grant access to SQS from the state machine in IAM. Find the role assigned to the state machine and grant AmazonSQSFullAccess permissions. This is the role automatically created by the state machine create wizard.

Here is how the state machine looks after it's configured correctly:

Add Webpack to Step Functions

A good technique for keeping your Lambda functions small and fast is to bundle assets. This lets the VM spin up quickly and execute the code, which helps with cold starts.

First, add the webpack dependency to both step functions:

> npm i webpack@latest webpack-cli@latest --save-dev

Open both package.json files side-by-side. Edit the start and deploy commands under the scripts section and change the --handler function to --handler pub/bundle.handler. Also, edit the dependencies section name — call it optionalDependencies. This prevents all NPM dependencies from getting added to the bundle via npm pack, which is what the deploy tool uses.

Then, add a bundle command under scripts:

"bundle": "webpack"

With these package.json changes in place, add this webpack.config.js file to both step functions:

const path = require("path");

module.exports = {
  entry: [path.join(__dirname, "main.js")],
  output: {
    path: path.join(__dirname, "pub"),
    filename: "bundle.js",
    libraryTarget: "commonjs",
  },
  target: "node",
  mode: "production",
};

Lastly, create an .npmignore file:

node_modules/
claudia.json
webpack.config.js

This is what bundles all dependencies using the entry point main.js. Webpack will then shake tree dependencies and only add what is necessary to the bundle that gets uploaded on AWS. .npmignore tells npm pack to exclude what is not needed in the final bundle output.

Be sure to run npm run bundle && npm run deploy to get these changes out on both step functions.

Testing the Step Functions

Finally, double-check permissions in IAM. There are two executor roles, and one role assigned to the state machine. If permissions are not set correctly, you'll see failed executions in CloudWatch alongside useful error messages.

Create an S3 bucket with the name resume-uploader-upload-<unique-name>. Due to a limitation in AWS, keep in mind this bucket name must be unique — so add your name or anything else that makes the bucket unique. Double-check that the bucket name matches what is defined in the code.

Then, add a resume in PDF format — for example, ExampleResume.pdf. There is a sample resume in the GitHub repo in case you need one. Since Textract looks for a GitHub profile in the resume, ensure a link is specified.

To test the step functions:

> aws stepfunctions start-execution --state-machine-arn <arn> --input "{\"storedFileName\":\"ExampleResume.pdf\"}"

The ARN is available in AWS under the state machine. This command returns immediately, and you can check on the asynchronous processing via step functions on the AWS console.

The entire asynchronous process can take a few seconds because parsing a resume takes a long time.

Assuming everything executes successfully, the SQS queue should have a message available:

> aws sqs receive-message --queue-url <queue-url>

If nothing shows up in SQS, simply go to 'Step Functions' in AWS and click on your state machine. The console has an 'Executions' tab with status information. There are also logs available via CloudWatch.

Next Up

In this post, we covered how to deploy Lambda step functions in AWS using Claudia.js. We then built a state machine and deployed our step function to AWS, before testing it.

This is only the asynchronous part of a more complex solution. There is an increased demand for low-latency solutions, and users expect no less.

In the next and final part of this series, we will build the client-facing API.

Happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Multithreading with Worker Threads in Node.js

Camilo Reyes — Wed, 12 Jul 2023 12:25:15 +0000

The beauty of Node is that while the main event loop runs in a single thread, some expensive tasks are automatically offloaded to a separate worker pool. These include the I/O-intensive DNS and File System (except fs.FSWatcher()) APIs, as well as the CPU-intensive Crypto and Zlib APIs. All these have a synchronous variation which will block the main thread.

This is generally how Node accomplishes concurrency while running on a single thread. However, our code can contain some computationally complex tasks that will typically block the main thread.

This is where multithreading comes in handy because we can simply run such tasks in a worker thread. The main event loop will keep running and continuously check for incoming events or requests.

In this take, we will explore the ins and outs of multithreading in Node, including some potential pitfalls.

The Basics of Multithreading in Node.js

You can find the completed project that we will build on GitHub.

Also, if you want to learn more about the basics of multithreading before you dive into this post, check out An Introduction to Multithreading in Node.js.

Now, let's get started with the tutorial.

Starting Our Project: Subset Sum Algorithm

To get started, create a new project folder and generate a package.json file.

> mkdir node-worker-threads
> cd node-worker-threads
> npm init

Be sure to edit the package.json file and change the project type to module so that we can use the import/export syntax.

Next, write a CPU-bound algorithm that captures matches when the sum of the subsets equals 0. This is often referred to as the subset sum problem, and it is CPU intensive because it can take a long time to calculate large arrays.

Algorithmic optimizations are not the main focus here, so we can implement the code as succinctly as possible.

Because the output can be very large for big arrays, we will implement event emitters to send matches back in chunks. This way, we avoid sending the end result in one big blob of data (which can cause a block).

Put this code in a file named subsetSum.js:

import { EventEmitter } from "events";

export class SubsetSum extends EventEmitter {
  #sum = 0;
  #set = [];

  constructor(sum, set) {
    super();
    this.#sum = sum;
    this.#set = set;
  }

  start() {
    this.#combine(this.#set, []);
    this.emit("end");
  }

  #combine(set, subset) {
    for (let i = 0; i < set.length; i++) {
      const newSubset = subset.concat(set[i]);
      this.#combine(set.slice(i + 1), newSubset);
      this.#processSubset(newSubset);
    }
  }

  #processSubset(subset) {
    const res = subset.reduce((prev, item) => prev + item, 0);
    if (res === this.#sum) {
      // send matches piecemeal
      this.emit("match", subset);
    }
  }
}

Note that processSubset and combine are marked as private methods. This is because we do not need to expose these members outside of the class. Everything in SubsetSum can be interfaced via the public start method and the constructor.

Build the API Endpoint for Your Node Application

Now, build the API endpoint to play with this algorithm in Node. We can have two endpoints:

One to check if the web server is still alive.
The other to kick off the CPU-heavy calculation.

Put this code in index.js:

import { createServer } from "http";
import { SubsetSum } from "./subsetSum.js";

createServer((req, res) => {
  const url = new URL(req.url, "http://localhost");

  if (url.pathname !== "/subsetSum") {
    res.writeHead(200);
    return res.end("I'm still here!\n");
  }

  const sum = 0;
  const data = JSON.parse(url.searchParams.get("data"));

  res.writeHead(200);

  const subsetSum = new SubsetSum(sum, data);

  subsetSum.on("match", (match) => {
    res.write(`Match: ${JSON.stringify(match)}\n`);
  });
  subsetSum.on("end", () => res.end());
  subsetSum.start()?.catch((err) => console.error(err));
}).listen(8080, () => console.log("Server ready on port 8080"));

Next, fire up cURL with the web server running and check the results.

> curl -G http://localhost:8080/subsetSum --data-urlencode "data=[116,119,101,101,-116,109,101,-105,-102,117,-115,-97,119,-116,-104,-105,115,116,119,101,101,-116,109,101,-105,-102]"

If this takes too long to execute on your machine, simply narrow the length of the input array. While the algorithm is running, hit it with the health check endpoint. The health endpoint is http://localhost:8080 and returns a 200 with a message. Notice the web server chokes and does not respond until it finishes the calculation.

Also, the output comes out in one giant blob, even though we put event emitters in place. This is because CPU-bound operations block the main event loop. The event emitters do not get to send piecemeal data back to the main thread until the algorithm finishes.

To tackle this bottleneck, we will look at worker threads next.

Worker Pool and Worker Threads in Node

First off, install the NPM package called workerpool because this minimizes the amount of code needed to put worker threads in place.

npm i workerpool --save

The implementation is twofold: a worker pool and a worker thread. The worker pool limits the number of worker threads firing side-by-side. The worker thread executes our algorithm in a separate thread outside of the main event loop and proxies emitted events.

Let’s tackle the worker thread first. Put this in subsetSumWorker.js:

import workerpool from "workerpool";
import { SubsetSum } from "./subsetSum.js";

function subsetSumWorker(sum, set) {
  const subsetSum = new SubsetSum(sum, set);

  subsetSum.on("match", (data) => {
    workerpool.workerEmit({ event: "match", data });
  });

  subsetSum.on("end", (data) => {
    workerpool.workerEmit({ event: "end", data });
  });

  subsetSum.start();
}

// register worker thread
workerpool.worker({
  subsetSum: subsetSumWorker,
});

This mostly acts as a wrapper around SubsetSum and rebroadcasts events via workerEmit. Lastly, the worker registers the thread worker in the pool.

To queue up the worker thread in the worker pool, put the following code in subsetSumPool.js:

import { EventEmitter } from "events";
import { dirname, join } from "path";
import { fileURLToPath } from "url";
import workerpool from "workerpool";

const __dirname = dirname(fileURLToPath(import.meta.url));
const workerFile = join(__dirname, "subsetSumWorker.js");
const pool = workerpool.pool(workerFile);

export class SubsetSum extends EventEmitter {
  #sum = 0;
  #set = [];

  constructor(sum, set) {
    super();
    this.#sum = sum;
    this.#set = set;
  }

  async start() {
    await pool.exec("subsetSum", [this.#sum, this.#set], {
      // retransmit event
      on: (payload) => this.emit(payload.event, payload.data),
    });
  }
}

Much like before, the worker pool acts as a wrapper around the worker thread. All emitted events get retransmitted via the on property in the exec method. This is how the main thread can listen for incoming events.

Finally, in the web server index.js file, we only need a single line change:

import { SubsetSum } from "./subsetSumPool.js";

With worker threads working side-by-side, the matches stream rapidly through the console. If we hit the health check concurrently, we get an immediate response because nothing is blocking the main thread.

This implementation uses the default configuration with all CPU cores available minus one, which the main thread can take up.

Keep in mind that worker threads are an abstraction around the underlying OS threads running on multiple CPU cores. We do not get direct control over the low-level details here, but this is how Node achieves multithreading via worker threads.

The key takeaway here is that our algorithm is not blocking the main event loop and fires more than a single CPU to get the job done.

Pitfalls of Multithreading in Node.js

Slap a console.log somewhere in the algorithm — say, inside the if branch where it finds a match.

Change this code in subsetSum.js:

#processSubset (subset) {
  const res = subset.reduce((prev, item) => (prev + item), 0)
  if (res === this.#sum) {
    // blocks!
    console.log('match found ' + subset)
    this.emit('match', subset)
  }
}

Give this change a spin and notice how the main thread completely blocks as soon as the algorithm finishes. Attempting to hit the health check will also simply block until all the console messages execute.

This is because the main thread attempts to marshal console.log messages synchronously and is part of the worker thread design.

A recommendation is to send debug information back to the main thread using an event emitter like debug instead. Then listen for this event and call console.log directly from the main thread.

For example:

// from worker thread - subsetSum.js
this.emit("debug", "match found " + subset);

// from worker pool - subsetSumWorker.js
subsetSum.on("debug", (data) => {
  workerpool.workerEmit({ event: "debug", data });
});

// from main thread - index.js
subsetSum.on("debug", (message) => console.log(message));

This will keep broadcasting messages between the worker thread and the main thread asynchronously, so nothing is blocked.

Wrapping Up

In this post, we explored:

What happens to CPU-heavy algorithms in Node.
How to offload work from the main thread via worker threads and some gotchas.

In Node, worker threads are an exciting new way to offload CPU-bound calculations from the main thread. This unblocks the event loop so other tasks can run concurrently.

Happy multithreading!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

5 Node.js Tools to Learn in 2023

Camilo Reyes — Wed, 08 Feb 2023 15:09:37 +0000

The Node ecosystem comes with a wide variety of tools that have continued to evolve over the years. These tools are delivered via NPM packages and run in the command line, making them accessible to any developer (you do not need a fancy IDE to get the job done).

In this take, we will explore 5 Node tools to learn this year: TypeScript, ES modules, ESLint, the ESLint SpellCheck plugin, and Mocha. These all run via the command line and can help boost your productivity when working on Node projects.

Ready? Let’s go!

The Sample Code

If you want to get a head start, the sample code is a code kata with all the tools discussed in this article. It is an HTML5 game by Christian Clausen called bomb-guy that you can run in the browser. The emphasis will not be on the code itself but on the tools around the code solution.

Feel free to clone the repo — it is available on GitHub. The code is a fork from thedrlambda and has been refactored with all these tools.

Be sure to inspect the package.json file to get a sneak peek of all the cool tools available.

"devDependencies": {
  "@types/mocha": "^10.0.1",
  "@typescript-eslint/eslint-plugin": "^5.47.0",
  "eslint": "^8.30.0",
  "eslint-config-standard-with-typescript": "^24.0.0",
  "eslint-plugin-import": "^2.26.0",
  "eslint-plugin-n": "^15.6.0",
  "eslint-plugin-promise": "^6.1.1",
  "eslint-plugin-spellcheck": "^0.0.20",
  "http-server": "^14.1.1",
  "jsdom": "^20.0.3",
  "jsdom-global": "^3.0.2",
  "mocha": "^10.2.0",
  "ts-node": "^10.9.1",
  "typescript": "^4.9.4"
}

Remember, these all run via the command line, so you do not need a fancy editor or IDE to use them. Simply do npm run build, npm test, or npm start to spin up all the dev tools. This is the typical dev flow for pretty much all Node projects.

We will discuss each tool as a reference guide, show you how to get started, and point out a few gotchas. The emphasis is on playing around with each tool and showing you how to use it.

Let’s start with TypeScript.

TypeScript for Your Node.js Project

I’m sure you’ve already heard this a lot, but if you haven’t tried TypeScript in a project, you really need to. TypeScript adds type safety to your projects and makes it easier to catch mistakes in the code. For this bomb-guy code kata, for example, it’s valuable to rely on the compiler when making a lot of changes.

To get started, be sure to create a package.json file if you don’t already have one via npm init. Then, add the TypeScript dependency.

> npm i typescript --save-dev

At this point, it is possible to add the tsc command as a build script in package.json. If you have a bunch of existing JavaScript files, any file that gets renamed with a .ts extension becomes a TypeScript file, and the compiler does the rest of the work.

Most dev workflows require some tweaking of the compiler configuration. The way you do this is via the initializer.

> npx tsc --init

This creates a tsconfig.json file with the default configuration. Each configuration is well documented within this file so that you can tailor the tool to your needs.

While you are in the configuration file, change the TypeScript configuration so we can talk about the next available tool.

"compilerOptions": {
  "module": "esnext",
  "target": "esnext"
}

Now it is possible to declare strongly typed interfaces and classes.

As an example, let’s say we want to declare an interface every tile class must implement in this bomb-man game. The game is a 2-D style game with many different types of tiles.

interface Tile {
  isGameOver: () => boolean;
  draw: (g: CanvasRenderingContext2D, x: number, y: number) => void;
  move: (x: number, y: number) => void;
  update: (x: number, y: number) => void;
  placeBomb: () => void;
  explode: (x: number, y: number, fire: Tile) => void;
}

Voilà! If you want more information about setting up TypeScript for your Node app, check out the post How to Set Up a Node.js Project with TypeScript.

Next up, let’s see what ES modules have to offer.

ES Modules in Node.js and the Browser

Both Node and the browser have achieved parity via export/import. This module system allows you to simply import code from different files and works natively without transpilers.

In Node, change the package.json file to a module.

"type": "module"

This instructs Node to start using ES modules natively, without the TypeScript transpiler.

In the browser, go to index.html and change the script tag.

<script src="dist/src/index.js" type="module"></script>

This achieves two things:

TypeScript does not nuke the export/import code
The browser can use this same module system to tackle dependencies

One gotcha here is that there is a bit of divergence between TypeScript and the browser. The spec says imported modules must declare a file extension, whereas TypeScript makes the resolution even without an extension like .js.

To tackle this issue, simply declare all dependencies as JavaScript files in your TypeScript code. The compiler is smart enough to know that you mean to declare the import as a JavaScript file.

import { TILE_SIZE, FPS, TPS } from "./constant.js"; // JavaScript file imported

This technique works seamlessly in both Node and the browser.

ESLint with TypeScript for Your Node.js App

The linter tool ESLint statically analyzes code, supports most text editors, and can run in the command line. It adds code smell checks, checks for potential bugs, and even helps style code consistently. We recommend turning on all the features ESLint has to offer.

To get started, initialize the config package:

> npm init @eslint/config

This CLI tool automatically guides you through a set of options where you can customize the configuration. Be sure to pick all three: check syntax, find problems, and enforce code style. Pick the standard, most popular style guide — ESM — as the module system and TypeScript.

The configuration file comes in three flavors: JavaScript, JSON, and YAML. Pick JavaScript because we need to tackle the next gotcha.

For ESLint to work with the TypeScript compiler, it needs parserOptions somewhere in the configuration file. Also, because we are using the ES module system in package.json, we must rename the configuration file to .eslintrc.cjs.

In .eslintrc.cjs be sure to set the parserOptions:

"parserOptions": {
  "project": ["tsconfig.json"],
  "tsconfigRootDir": __dirname, // JavaScript code
  "ecmaVersion": "latest"
}

Note the use of __dirname — this allows the linter to find the tsconfig.json file from anywhere in the project folder structure. This technique is only achievable via the JavaScript configuration file.

Now lint a file in the src folder:

> npx eslint constant.ts

There you have it! Next up is a handy ESLint plugin: SpellCheck.

ESLint Plugin — SpellCheck

ESLint is extensible via plugins. Because there is nothing less annoying than typos in code, let’s install the spellcheck plugin.

npm i eslint-plugin-spellcheck --save-dev

To enable the spellchecker in ESLint, edit the .eslintrc.cjs file:

"plugins": ["spellcheck"],
"rules": {
  "spellcheck/spell-checker": [
    "warn", {
      "skipWords": ["rect", "keydown"]
    }
  ]
}

This fires warnings in ESLint when it finds a spelling mistake. If you have valid words that are not found in the dictionary, just add them to the list in skipWords.

With ESLint, most caught issues trigger an error, and the build will fail until the issue is fixed. This makes the CLI tool ideal for both local development and continuous integration on a build server.

To enable these checks automatically, add ESLint to the prebuild script in package.json.

"scripts": {
  "prebuild": "eslint ."
}

Finally, let’s take a look at Mocha.

Mocha for Testing in Node.js

If you have yet to practice test-driven development (TDD), now is your chance. Mocha integrates seamlessly with all the tools we have covered so far and can run hundreds of unit tests in less than a second.

To get started with Mocha, install the following dependencies:

npm i @types/mocha jsdom jsdom-global ts-node mocha --save-dev

Note the use of ts-node and jsdom in the dependencies. The bomb-guy code kata runs in the browser, so jsdom allows mocking browser elements like the window object without a headless browser.

Because we are using TypeScript, ts-node is an execution engine that directly executes TypeScript on Node without precompiling. These two dependencies are useful for running unit tests in Mocha.

To enable these tools in Mocha, create a .mocharc.json file with the following configuration:

{
  "require": ["jsdom-global/register"],
  "loader": "ts-node/esm",
  "extensions": ["ts"],
  "spec": ["tests/**/*.test.ts"]
}

This tells Mocha to enable three things: jsdom, ts-node with ES modules, and the TypeScript extensions. The spec settings specify where the tests go, and you can use a glob pattern.

Then, write the unit tests using TypeScript. Say we want to test that a player can move around the tiles and place a bomb.

it("move player", () => {
  player.moveRight();
  player.moveDown();
  player.moveDown();
  equal(2, player.x); // assertion library
});

it("place first bomb", () => {
  player.placeBomb();
  map.update();
  equal(1, player.bombs);
});

Note that Mocha does not come with an assertion library.

Thankfully, Node comes with one built-in, so you do not have to add another dependency. If you are already familiar with Chai, the transition will feel seamless.

Lastly, be sure to include Mocha in package.json:

"scripts": {
  "test": "mocha"
}

The .mocharc.json configuration file already tells Mocha how to run the tests. This technique keeps your package.json file clutter-free.

One gotcha is that Mocha does not support ESM in watch mode. Hopefully, this limitation will be tackled in future releases.

Keep in mind, the linter and compiler are separate from running unit tests in your continuous integration pipeline. The execution engine in ts-node is not a compiler and does not do any code checks. So a good technique is to run both ESLint and the TypeScript compiler first, then run unit tests last on the build server.

Wrapping Up

In this post, we explored 5 Node tools to learn this year: TypeScript, ES modules, ESLint, the ESLint SpellCheck plugin, and finally, Mocha for running tests.

These Node tools offer the possibility of tackling code changes without an IDE. The tools are accessible and do not shove specific IDEs or text editors on developers. They are easy to automate and can be included in continuous integration so an entire team can benefit.

Happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Secure Your AWS Lambdas with TypeScript

Camilo Reyes — Wed, 25 Jan 2023 11:44:44 +0000

In the previous part of this series, we optimized our Lambda function. However, our API is open to the public — anyone with the URL can use it and get a response.

In this take, we are going to secure our API using a tool called Amazon Cognito. This will only allow authenticated users access to our endpoints.

Ready? Let’s go!

What Is Cognito?

The AWS cloud has Amazon Cognito, an identity and access management tool. With this, you can create user accounts, manage their credentials, and generate a JWT.

What Is a JWT?

Think of a JWT as an identity card. It identifies you as a real person and grants you basic access to a resource like an endpoint.

JWT stands for JSON Web Token and allows for two parties, like a client and server, to exchange claims. The JWT gets signed using a cryptographic algorithm to ensure that claims cannot be altered after the token is generated. A JWT is also self-contained, meaning it does not depend on database queries or a server session to grant authentication.

We can secure our API with a bearer JWT token. This way, only authenticated users with valid credentials can use our API.

Let’s see how we can set up Amazon Cognito and generate a JWT.

Set Up Amazon Cognito

First, you need to create a user pool on the AWS cloud. Go to AWS and look for Cognito.

Follow these steps:

Click Create user pool
Click Username and Allow users to sign in with a preferred username
Go to Next
Disable MFA, so click No MFA
Disable Enable self-service account recovery
Go to Next
Disable Self-registration
Disable Cognito-assisted verification and confirmation
Skip past Required attributes and Custom attributes
Go to Next
On Email, click Send email with Cognito
Go to Next
Under User pool name, type pizza-api-cognito and make note of this name
On Initial app client, select Other for a custom app
Under App client name, type pizza-api-client
Click Generate a client secret
Expand Advanced app client settings and select ALLOW_USER_PASSWORD_AUTH authentication flow
Disable Token revocation and User existence errors
Go to Next
Click Create user pool

This may feel like a lot of steps to set up a user pool, but you’re really doing two things:

Allowing the username and password auth flow.
Creating a new app client.

MFA, self-service, and token revocation are outside the scope of this article, so we have these options disabled in Amazon Cognito.

Once these steps are complete, note the user pool ID, then click on your user pool.

Set a Username and Password

Now, under Users, click on Create user. Set the username to regular and make a note of it. Go ahead and click on Generate a password so that we can set the password later.

Then, click on Create user.

Note that the confirmation status says Force change password. This is because the password is currently unconfirmed.

To set a new password, run this AWS CLI command:

> aws cognito-idp admin-set-user-password --user-pool-id USER_POOL_ID --username regular --password Passw0rd! --permanent

The password has the following requirements:

A minimum length of 8 characters
Contains at least 1 number
Contains at least 1 special character
Contains at least 1 lowercase character

Be sure to set a more secure password and use that instead of this very insecure password. Replace USER_POOL_ID with the user pool ID from earlier.

Go back to AWS and check that the password is now Confirmed. We now have a legit password to use in the credentials.

Create a Client Secret Hash for AWS Cognito

Next, we’ll need a script that generates a secret hash before generating a JWT. If you do not provide a proper hash, you will see an error because Amazon Cognito cannot verify the secret hash.

Create a file — say, generate-client-hash.js — and write this algorithm:

const crypto = require("crypto");

HMAC_ALGORITHM = "sha256";
HMAC_FORMAT = "hex";
HASH_ENCODING = "base64";

const arguments = process.argv;

const username = arguments[2];
const clientId = arguments[3];
const clientSecret = arguments[4];

const hmac = crypto.createHmac(HMAC_ALGORITHM, clientSecret);
const data = hmac.update(username + clientId);
const genHmac = data.digest(HMAC_FORMAT);
const buff = Buffer.from(genHmac, HMAC_FORMAT);
const hash = buff.toString(HASH_ENCODING);

console.log("secret hash: " + hash);

The algorithm simply creates a base64 encoded hash from the username, client ID, and client secret.

To nab the client ID and secret, go to AWS and then Amazon Cognito, click on your user pool, and click App integration. The pizza-api-client should be at the bottom of the page with the client ID. To reveal the client secret, go to your client, then click Show client secret.

To generate a secret hash, run this command:

> node generate-client-hash.js regular CLIENT_ID CLIENT_SECRET

Make a note of this secret hash before continuing to the next section.

Generate a JWT

Phew, with Amazon Cognito out of the way, this is where the real fun begins.

Simply gather all your necessary inputs: client ID, password, and secret hash, and then do this:

> aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --client-id CLIENT_ID --auth-parameters USERNAME=regular,PASSWORD=PASSWORD,SECRET_HASH=SECRET_HASH

Note the IdToken in the result — this is the bearer JWT token you’ll use for authentication.

Let’s take a quick pause and inspect the token using jwt.io. Copy-paste the JWT into the Debugger to see what’s in the token.

{
  "sub": "26412b5f-7752-4176-a3de-1922b4690097",
  "aud": "4nfibi3q3jivsdoo38save91ku",
  "event_id": "46580b57-dabc-47e3-a4be-6461ab6d1c40",
  "token_use": "id",
  "auth_time": 1665342105,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_1BfH4Jwkp",
  "cognito:username": "regular",
  "exp": 1665345705,
  "iat": 1665342105
}

Because the JWT is also signed by Amazon Cognito, it is impossible to brute force an attack on our endpoint with the bare claims. The beauty of this is that it is self-contained and has sufficient information in the claims to authenticate a real person.

For example:

sub uniquely identifies our Amazon Cognito user
token_use claims this is an ID token
exp sets an absolute expiration.

So, even if somebody somehow gets a hold of this token, it will long have expired by the time this article is published. In Amazon Cognito, the ID token expires an hour after it is generated.

Update the API Gateway in TypeScript

Finally, open up api.ts in the pizza-api code repo. We’ll need to make two changes: register an authorizer, and assign the authorizer to the endpoint.

Do this:

api.registerAuthorizer("pizza-api-cognito", {
  providerARNs: ["USER_POOL_ARN"],
});

api.get("/", () => ["Welcome to AWS"], {
  cognitoAuthorizer: "pizza-api-cognito",
});

The USER_POOL_ARN is a unique identifier you can find on AWS. Simply click on the user pool, and copy-paste the ARN in User pool overview.

With these changes done, it’s time to run npm run update and let Claudia do the rest of the work.

To verify that changes have been made on the API gateway:

Go to AWS, and click API Gateway.
Open up pizza-api and inspect the Authorizers. There should be a pizza-api-cognito authorizer.
Check the API endpoints under Resources. The main / endpoint should have COGNITO_USER_POOLS assigned to the endpoint.

There is the option to manually do all this work on the API gateway, but the Claudia deploy tool automates all these steps for us.

Test It Out!

Fire up CURL to verify that the endpoint is no longer open to the public:

curl -i -H "Accept: application/json" "https://API_GATEWAY_ID.execute-api.us-east-1.amazonaws.com/latest"

This should return a 401 Unauthorized.

Then, if you’re following along, nab the ID token from Cognito (since it has not quite been an hour) and put it in the authorization header:

curl -i -H "Accept: application/json" -H "Authorization: Bearer JWT_ID_TOKEN" "https://API_GATEWAY_ID.execute-api.us-east-1.amazonaws.com/latest"

This should return a 200 with a proper response.

Authentication and Authorization with Amazon Cognito

In general, Amazon Cognito allows you to customize the auth flow via triggers and scopes. The Cognito user pool is standalone and can grant access based on who’s in the pool and what the claims are.

For more complex authorization use cases, it might be best to break users apart into separate pools. This allows for full control over who has more privileges within the system. One nicety of this technique is that Amazon Cognito handles both authentication and authorization, which means your Lambda function does not execute without proper access. This helps in lowering serverless costs.

Note that the API gateway is the one driving authorization because our Lambda function is merely an event instead of a reverse proxy. This technique unlocks the ability to block access without having to execute the Lambda function.

With what we have so far, basic access is granted to the / endpoint. If we wanted higher privileges to call, say, a POST /pizzas to make a pizza, then a separate user pool can handle this requirement.

Final Thoughts on AWS Lambdas with TypeScript

In this series, we built a TypeScript Lambda, improved the dev experience, optimized it, and have now secured it. I hope you’ve found it useful.

The serverless cloud offers many opportunities for developers to iterate quickly and deliver value to happy customers. What is most exciting about this is that it follows the adages from the Unix philosophy that “small is beautiful" and to "make each program do one thing well”.

Happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Optimize Your AWS Lambdas with TypeScript

Camilo Reyes — Wed, 07 Dec 2022 12:34:46 +0000

Last time in this series, we looked at improving the developer experience. As your Lambda function gains more features and dependencies, you may notice that the bundle size begins to grow exponentially. This can negatively affect deployments and cold starts.

A bigger bundle means deployments take longer to upload to the AWS cloud. The JavaScript engine has more work to do before it can execute the Lambda function.

In this take, we will focus on optimizing our Lambda function. We'll explore techniques to reduce the bundle size and minimize startup costs.

Ready? Let’s go!

The Current Situation

To verify the current bundle size, log in to AWS, click on the pizza-api Lambda function, and then check the code tab. With all the work we've done so far, the bundle size sits at around 40 megabytes. Any real-world solution can easily grow to hundreds of megabytes.

First, let’s measure our current situation by deploying the latest code to the AWS cloud. We can use a tool in PowerShell called Measure-Command to figure out how long this takes. Feel free to use a similar tool if you are on Linux/macOS, or simply use a stopwatch.

> Measure-Command { npm run update }

For Linux/macOS, you can use the following command:

> time npm run update

From my local machine, and pointing to the us-east-1 region with a decent internet connection, this update command runs for almost three minutes. That's likely because this is how long it takes to upload 40 megabytes, given my upload speed.

Claudia runs npm pack under the hood and creates a zip file that can be uploaded to the AWS cloud. Even with a compressed bundle, this still takes a few minutes to complete.

Next, fire a curl request to the GET pizza endpoint. Be sure to quit PowerShell or any benchmarking tool before proceeding, since we won’t need a timer on this command.

curl -X GET -i -H "Accept-Type: application/json" -H "Content-Type: application/json" https://API_GATEWAY_API.execute-api.us-east-1.amazonaws.com/latest/pizzas/Pepperoni-Pizza

If you have been following along, you should have a pepperoni pizza already pre-made. Now, log in to AWS, and check the logs via CloudWatch under pizza-api. Look for an entry like the one below:

Duration: 553.07 ms Billed Duration: 554 ms Memory Size: 128 MB Max Memory Used: 79 MB Init Duration: 401.82 ms

Keep this in mind for future reference: the startup costs were around half a second. This is what you’d owe every single time the Lambda function spins up for the first time.

Since this is the serverless cloud, there are no real guarantees on how long the VM stays up.

Claudia Optimizations

Claudia comes with an arsenal of command line flags to tackle these issues. We’ll focus on the following flags:

no-optional-dependencies - with this, optional dependencies in package.json won't be uploaded to the Lambda function
runtime - controls the Node runtime version that will be used and checks on AWS for available runtimes
arch - specifies the architecture used to execute the code
memory - this value must be a multiple of 64 MB and cannot be less than 128 MB

If your goal is to improve cold starts, we recommend setting the runtime to the latest version of Node available (nodejs16.x at the time of writing). The default architecture is x86, so it is okay to stick to this setting. Memory-hungry apps can also take longer to start up, so set this to the minimum threshold of 128.

Since we are also concerned about the bundle size, set the no-optional-dependencies flag in the command line tool. This helps shed a lot of weight during uploads.

With these command line flags in mind, open the package.json file, and change the update command.

{
  "update": "claudia update --cache-api-config apiConfig --no-optional-dependencies --runtime nodejs16.x --arch x86_64 --memory 128"
}

An identical set of flags can also go on the create command, but we’ll leave this as an exercise for you.

TypeScript Optimization of AWS Lambdas

Next, we’ll tackle a couple of optimizations within the code itself.

Pop open the tsconfig.json file and make the following change:

{
  "target": "esnext"
}

By default, the compiler assumes no support for async/await in Node. This adds bloat to the output code because the transpiler builds a state machine in JavaScript that returns a Promise. The output also declares a generator and replaces await with a yield. If you take a peek in the dist folder, you may notice the output JS files declare an awaiter at the top of the file. This happens to every single file that uses async/await.

By setting the target to ESNext, we tell the TypeScript compiler to handle async/await natively in JavaScript.

Because we have taken control of the runtime setting on AWS, it is safe to assume Node 16.x supports async/await. The TypeScript compiler works less, and the output loses weight.

API Payload Optimization

The API response itself carries extra baggage from DynamoDB. Take a look at your response body and notice how every field has a prefix.

{
  "ingredients": { "SS": ["cheese", "pepperoni", "tomato sauce"] },
  "url": { "S": "Pepperoni-Pizza" },
  "name": { "S": "Pepperoni Pizza" }
}

Prefixes like SS and S are field types in DynamoDB. They tell the database to allow only the specified type declared in the prefix. For example, an S is for a string field, and SS is for a set of strings.

Marshaling nukes this extra weight and optimizes the payload in the API response.

Open PizzaDb and make the following changes:

import { unmarshall } from "@aws-sdk/util-dynamodb";

// Inside tastePizza, replace the return with this code
const pizza = unmarshall(pizzaItem);
const { ingredients } = pizza;

return { ...pizza, ingredients: [...ingredients] };

Then, add one more dependency to this project:

npm i @aws-sdk/util-dynamodb --save-dev

The spread operator converts a set type to an array. This is necessary because JSON.stringify does not support sets. You can verify this new behavior by running the unit tests. We’ll leave fixing the test as an exercise for you.

Optimizing AWS Lambdas with Webpack

Time for the pièce de résistance. Out of all the techniques used so far, Webpack will make vast improvements to reduce the bundle size.

Install the following NPM dev packages:

npm i webpack webpack-cli --save-dev

Every bit counts — the goal here is to shake the dependency tree and only import what we need in the final bundle file.

To accomplish this goal, create a webpack.config.js file in the root folder. Webpack automatically knows to read this configuration from this location.

const path = require("path");

module.exports = {
  entry: [path.join(__dirname, "dist/api.js")],
  output: {
    path: path.join(__dirname, "pub"),
    filename: "bundle.js",
    libraryTarget: "commonjs",
  },
  target: "node",
  mode: "production",
};

There are a couple of caveats. First, we instruct Webpack that this is server-side code via the libraryTarget. This uses commonjs to export the API object so Claudia can pick it up and deploy our Lambda function. Also, we must specify the entry point of our app and the output filename.

Because the code gets compiled by TypeScript, we can reference the transpiled output in the dist folder directly without introducing another transpiler like Babel.

Now, open the package.json file and change the scripts:

{
  "preupdate": "npm run bundle",
  "prebundle": "npm run type-check",
  "bundle": "webpack"
}

Finally, change the claudia.json file — set the module property to pub/bundle.

Unfortunately, Claudia does not update the Lambda configuration on AWS with this new module setting. So, go to the pizza-api Lambda function on AWS, edit the runtime settings, and set the Handler to pub/bundle.proxyRouter. This is the new entry point of our Lambda function.

Because NPM dependencies are no longer necessary, we can declare all dependencies as optional. In package.json, simply rename dependencies to optionalDependencies.

The NPM Ignore File

Claudia uses npm pack to create the zipped bundle, and one effective way to explicitly tell it which files to exclude is via .npmignore.

Create the .npmignore file:

@types/
test/
dist/
roles/
node_modules/
claudia.json
tsconfig.json
webpack.config.js

This excludes all extraneous folders and files from the bundle and drastically reduces the size before it uploads to the AWS cloud.

The Optimized Situation

Like before, let’s measure our deployment times:

> Measure-Command { npm run update }

For Linux/macOS, use the following command:

> time npm run update

This time, the deployment completes in under one minute, which is three times faster.

Next, fire a request to the same GET endpoint.

curl -X GET -i -H "Accept-Type: application/json" -H "Content-Type: application/json" https://API_GATEWAY_API.execute-api.us-east-1.amazonaws.com/latest/pizzas/Pepperoni-Pizza

On AWS, check the logs via CloudWatch under pizza-api.

Duration: 548.26 ms Billed Duration: 549 ms Memory Size: 128 MB Max Memory Used: 66 MB Init Duration: 242.30 ms

Note the startup cost and memory used. Our init duration goes from half a second down to a quarter of a second, which makes this twice as fast. The memory used is also lower, likely because the VM does not load megabytes of unused code.

Turns out, the same optimizations that we once applied on the browser can also be applied to the AWS serverless cloud. This is because the bundle size and cold starts are critical to JavaScript performance.

These two are similar because the JavaScript bundled code must spin up, execute, and then die with little overhead and in a sandbox environment.

Next Up: Secure Your AWS Lambdas

Optimizing our Lambda function is all about two things: reducing the bundle size and improving cold starts. What’s nice is that all the optimization techniques you are already familiar with on the browser can also be employed on the serverless cloud.

In the fourth and final part of this series, we’ll look at securing our Lambda function via Cognito.

Until next time!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Node.js 19 Release: What’s New

Camilo Reyes — Tue, 22 Nov 2022 14:46:24 +0000

The Node.js team recently announced the release of version 19. This has the following features:

node --watch (experimental)
KeepAlive by default
Stable WebCrypto
V8 engine updates

In this article, we will explore the major highlights of this release. We recommend downloading the latest Node.js 19 release to follow along.

To verify your version of node:

> node --version

Let's get started!

`node --watch` (Experimental)

This exciting new feature adds a file watcher using the --watch option. Running a Node.js app in watch mode automatically restarts the process when an imported file changes.

To check out this new feature, create two files: index.mjs and import.mjs. This feature only works with Node.js v19.0.0 and v18.11.0+.

In the import.mjs file write:

export const message = "Hello, World";

Then, in the index.mjs file:

import { message } from "./import.mjs";

console.log(message);

Now run:

> node --watch index.mjs

The tool should output that it is running in watch mode. Keep in mind this is an experimental feature so it could change at any time.

Update the import.mjs file on the fly by changing the message:

export const message = "Hello, New World";

Note the process restarts, and the new message now appears on the console. The possibilities here are endless, as you can focus more on your code without worrying about the running process.

For the remainder of this post, run the node executable by itself. This loads a REPL we can use to check out the rest of the new features.

node

HTTP(S)/1.1 `keepAlive` by Default

With this release, Node.js sets the keepAlive header by default, and the duration is set to 5 seconds. This reuses HTTP(S) 1.1 connections, increasing throughput because the header instructs the client on how long to stay connected. The server will also automatically disconnect any idle connections when close() is invoked.

To check out this new feature, create an HTTP server:

const http = require("http");

const requestListener = function (req, res) {
  res.writeHead(200);
  res.end("Hello, World!");
};

const server = http.createServer(requestListener);
server.listen(8080);

You can copy-paste this code into the REPL or type it all out. Once the server is running, run a CURL command:

> curl -i http://localhost:8080

Note the header on the response - Keep-Alive: timeout=5. This instructs the client to reuse connections and keep them open for 5 seconds.

Stable Web Crypto API

The Web Crypto API is now stable. You can access this module via globalThis.crypto or require('node:crypto').

To check out Web Crypto API, try to encrypt - then decrypt - a secret message:

const { subtle, randomBytes } = require("node:crypto");

const iv = randomBytes(16);
const key = await subtle.generatedKey(
  {
    name: "AES-CBC",
    hash: "SHA-256",
    length: 256,
  },
  true,
  ["encrypt", "decrypt"]
);

const secretMessage = "I love node!";
const encrypted = await subtle.encrypt(
  {
    name: "AES-CBC",
    iv: iv,
  },
  key,
  secretMessage
);
const dencrypted = await subtle.decrypt(
  {
    name: "AES-CBC",
    iv: iv,
  },
  key,
  encrypted
);

const dec = new TextDecoder("utf-8");
console.log(dec.decode(decrypted));

You can also use this same API to generate symmetric and asymmetric keys (public and private keys) for your specific security needs. Please note the Ed25519/Ed448/X25519/X448 algorithms are still experimental.

V8 Engine 10.7 Updates with `Intl.NumberFormat` JavaScript API

The V8 engine has been upgraded to version 10.7, which is part of Chromium 107. This version includes a new JavaScript API: Intl.NumberFormat.

This JavaScript API enables language-sensitive number formatting.

const number = 123456.789;

const china = new Intl.NumberFormat("zh-CN", {
  style: "currency",
  currency: "CNY",
});
console.log(china.format(number)); //¥123,456.79

const iraq = new Int.NumberFormat("ar-IQ", {
  style: "currency",
  currency: "IQD",
});
console.log(iraq.format(number)); //١٢٣٬٤٥٧د.ع

const us = new Int.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
});
console.log(us.format(number)); //$123,456.79

The Intl.NumberFormat object has a nice long list of options to support international number formatting.

Node.js 18 Promoted to LTS

Node.js 19 will not be promoted to LTS because only even-numbered releases are promoted to LTS. For production workloads, we recommend LTS releases. However, it is still a good time to play with Node.js 19 and provide feedback to help pave the way for future releases.

As Node.js 18 is being promoted to Active LTS, it is the recommended release for production deployments. According to the release schedule, Node.js 18 reaches end-of-life in April 2025, meaning three years of long-term support and bug fixes before then.

Node.js 18 has features that make upgrading a good choice:

Experimental fetch
Experimental test runner
ECMASCript improvements
V8 upgrade to 10.1

Check out more details in our previous blog, Node.js 18 Release: What’s New.

Wrap Up: Ecosystem Implications and Node.js 19 Release Notes

Node.js 19 continues to narrow the gap between the browser and the server. This is great news for developers who wish to work on the full stack without context-switching between languages.

The experimental watch tool is also exciting because it aids developer productivity within the platform. We hope to see more of these types of improvements in the future.

Stabilizing APIs, upgrading V8, and improving performance via KeepAlive are all signs of a healthy ecosystem that promises to deliver more features in future releases.

To see the full list of changes, be sure to look at the official Node.js 19 release notes.

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

AWS Lambdas with TypeScript: Improve the Dev Experience

Camilo Reyes — Wed, 02 Nov 2022 11:37:48 +0000

In part one of this series, we successfully built a TypeScript Lambda on the AWS cloud. But we left a lot of room for improvement in terms of the developer experience. For starters, the Lambda didn’t run on a local machine, which is cumbersome. The code we wrote is also not testable, which makes refactoring hard or, at least, dangerous.

In this take, let’s focus on improving the developer experience. The goal is to make the code more robust and easier to work with.

Ready? Let’s go!

Run Your Lambda Locally

The endless loop of publishing changes up to the cloud to verify even a minor text change can easily drain developer productivity. Time wasted waiting on the latest upload can be better spent elsewhere, like on the code itself.

In programming, this is also called the feedback loop: the time that elapses when verifying that a change actually works. Right now, our feedback loop is dismal since every republish can take a while. So let’s fix that, shall we?

Note: If you get lost while following along, feel free to check out the GitHub repo, which now has a part two.

First off, install the claudia-local-api NPM package as a dev dependency. Don’t forget to change the directory to your root folder, like pizza-api.

npm i claudia-local-api --save-dev

Open your package.json file and add this to the scripts section:

{
  "preserver": "npm run type-check",
  "server": "claudia-local-api --api-module dist/api.js | bunyan --output short"
}

The technique used in preserver can be called script-chaining. This reuses predefined scripts, so you don’t have to repeat yourself. Try setting all other pre scripts like precreate and preupdate to the same value as preserver. This guarantees at least some consistency across all NPM scripts and makes them more predictable.

Next, run your local server. The claudia-local-api package uses Express to execute your Lambda locally, proxying all requests from the Express server to the Claudia API builder. This is very similar to how the AWS gateway fires events to your Lambda function on the cloud. The Lambda itself does not handle HTTP requests but depends on Express locally or the gateway in AWS to execute.

On the cloud, this also means the AWS gateway does more work. A '401 Unauthorized', for example, does not execute the Lambda, which lowers its cost since you only pay-per-use. Executing the Lambda locally also incurs no cost unless the code uses other AWS resources like S3 storage.

To run your Lambda locally, simply run npm run server. You should see some nice logging from bunyan telling you the app is listening on port 3000.

If you have been following along, you should have a Pepperoni-Pizza already pre-made. We can now taste our pizza locally.

curl -X GET -i -H "Accept-Type: application/json" -H "Content-Type: application/json" http://localhost:3000/pizzas/Pepperoni-Pizza

If you run into any problems when executing your Lambda locally, please check the logs. Typically, the likely issue is that the Claudia API builder can’t find a route match, or Express can’t parse the request properly. Be sure to specify Accept-Type and Content-Type headers to minimize any confusion.

You may be wondering how we can still get Pizza data from DynamoDB. In fact, you can even make new pizzas and taste them locally. This is because the DynamoDB package uses your local AWS credentials file to authenticate on the cloud. The AWS CLI tool also uses this technique to talk to DynamoDB from your local machine.

Running code locally vastly improves the feedback loop. But can we do better?

Hexagonal Architecture for Your TypeScript App

One way to tackle unwieldy code is to separate concerns. You may have noticed everything lives in the api.ts file, which can grow quite large and become harder to change over time.

The hexagonal architecture pattern breaks up the app into ports and adapters, and creates loosely coupled components that can easily connect to external dependencies. This technique works well with Lambdas because we want to keep the implementation minimal and as decoupled as possible.

Therefore, our Lambda function can be broken up into three distinct parts: the AWS gateway event, our Claudia API builder, and the DynamoDB repository.

For example:

Luckily, we get the gateway event for free, which keeps our code minimal. This means we can split the code into two separate concerns.

Create a folder named repositories from the root folder. Then, create a PizzaDb.ts file — this is where the DynamoDB code will go. Imports will not be included, as you can copy-paste this code from the existing app.ts file. For this refactor, you can also rely on the TypeScript compiler.

export const makePizza = async (pizza: any) => {
  // interface
  if (
    !pizza ||
    !pizza.name ||
    !pizza.ingredients ||
    !Array.isArray(pizza.ingredients) ||
    pizza.ingredients.length === 0
  ) {
    throw new Error("To make a pizza include name and ingredients");
  }

  const { name, ingredients } = pizza;
  const pizzaItem = {
    url: { S: slugify(name) },
    name: { S: name },
    ingredients: { SS: ingredients },
  };

  await client.send(
    new PutItemCommand({
      TableName: "pizzas",
      Item: pizzaItem,
    })
  );

  console.log("Pizza is saved!", pizzaItem);
  return pizzaItem;
};

export const tastePizza = async (url: string) => {
  // interface
  const res = await client.send(
    new GetItemCommand({
      TableName: "pizzas",
      Key: { url: { S: url } },
    })
  );
  const pizzaItem = res.Item;

  if (pizzaItem === undefined) throw new Error("Pizza not found!");

  return pizzaItem;
};

This is classic ports and adapters code via an external interface. Note this code is no longer concerned with the raw AWS gateway event, but a pizza object with specific fields. The makePizza and tastePizza functions get exported to the consuming code without much ceremonial code.

On the Claudia API side, simply bring in repository dependencies and hook into the AWS gateway event. You can make this change to the api.ts file now.

import { makePizza, tastePizza } from "./repositories/PizzaDb";

api.post("/pizzas", async (request: any) => await makePizza(request.body), {
  // port code
  success: 201,
  error: 400,
});

api.get(
  "/pizzas/{url}",
  async (request: any) => await tastePizza(request.pathParams.url),
  {
    // port code
    success: 200,
    error: 404,
  }
);

This simplifies our code quite a bit and makes things easier to refactor. The only concern here is the AWS gateway event and the HTTP response. Like before, errors get handled automatically with a proper response. The request event type gets ported over so the adapter code can use it. For example, request.body has the pizza object, and request.pathParams has the url parameter to taste our pizza.

Now our code is more robust and easier to change. One bonus is the ability to test our code. Turns out, clean code and testable code go hand-in-hand. Let’s look at that next.

TypeScript Unit Tests

Before we can start writing unit tests, install the NPM dev dependencies:

npm i @types/chai @types/chai-as-promised @types/mocha @types/sinon chai chai-as-promised mocha sinon ts-node --save-dev

Then, configure your package.json by adding this under scripts:

{
  "test": "mocha --require ts-node/register ./test/*.ts"
}

Now create a test folder, then a PizzaDb.test.ts file inside this test folder.

import chai, { expect } from "chai";
import chaiAsPromised from "chai-as-promised";
import sinon, { SinonStub } from "sinon";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { makePizza } from "../repositories/PizzaDb";

chai.use(chaiAsPromised);

describe("PizzaDb", () => {
  let send: SinonStub;

  let pizzaItem = {
    url: { S: "P" },
    name: { S: "P" },
    ingredients: { SS: ["A", "B"] },
  };

  beforeEach(() => {
    send = sinon.stub(DynamoDBClient.prototype, "send"); // stub
  });

  afterEach(() => {
    send.restore();
  });

  it("makePizza#success", async () => {
    send.resolves();

    const result = await makePizza({
      name: "P",
      ingredients: ["A", "B"],
    });

    expect(result).to.deep.equal(pizzaItem);
  });

  it("makePizza#fail", async () => {
    send.resolves();

    await expect(makePizza({})).to.eventually.be.rejected; // fail
  });
});

makePizza is the system under test, and here we check both the happy path and failure. The stub hijacks the prototype and takes control of the send method. This guarantees no network activity occurs on the AWS cloud or DynamoDB.

Feel free to add more unit tests as you see fit — you can start with tastePizza as a quick exercise. If you need help, check out the GitHub repo.

Go ahead and take a look at your feedback loop. Running npm t gives me results within milliseconds. By running this locally, a full end-to-end test via curl takes a few minutes.

I hope you see what’s happening here. Uploading our code to the AWS cloud and hitting the gateway took roughly ten minutes. Then, we waited a few minutes by running the lambda locally. Now, we are down to fractions of a single second.

This technique helps you keep your eyes on the code and nukes any cognitive load while in the middle of making some rad changes. The goal is to keep you focused and minimize any distractions that tempt your mind to wander.

Local Debugging on the AWS Cloud

Lastly, debugging on the AWS cloud is possible via console.log. console.log works on both your local machine and the cloud.

AWS comes with CloudWatch, which lets you view the logs. You simply upload the latest code, test the app, then check the logs on CloudWatch. The service can take a few seconds to ingest log data, so it requires patience. It can be slow, and one can easily spend hours chasing even trivial bugs.

An alternative is to use your unit tests for local debugging. In an IDE — say, VSCode or WebStorm — you can set a breakpoint anywhere there is test coverage, then check the call stack and local variables. You can freely inspect assumptions in the code and verify your algorithm works as expected. The feedback loop here is much faster because you no longer need to rely on AWS.

One problem with using console.log to debug AWS Lambdas is that it tends to litter unit tests’ output. A simple solution is to install mocha-suppress-logs which only shows logs with failing tests.

npm i mocha-suppress-logs --save-dev

Be sure to make mocha aware of this dependency by adding it to the list in package.json:

{
  "test": "mocha --require ts-node/register,mocha-suppress-logs ./test/*.ts"
}

This works automatically and filters out those pesky logs that add noise to your workflow.

Next Time: Optimize Your AWS Lambdas

The dev experience is all about the feedback loop and how quickly one can iterate through changes. Luckily, the techniques we’ve outlined here will enable you to build a loop that is both fast and effective.

Next up in this series, we’ll look at ways to optimize the Lambda function, so that you can owe even less to Papa Bezos.

Happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

How to Build AWS Lambdas with TypeScript

Camilo Reyes — Wed, 28 Sep 2022 11:31:05 +0000

Serverless computing is an exciting alternative to hosting apps on the AWS cloud. In this four-part series, we’ll run through how to build AWS Lambdas with TypeScript, improve the dev experience, optimize it, and finally, use AWS Cognito for security.

In this take, I would like to take you on a journey to explore AWS Lambdas using TypeScript. We will build a pizza API, use Claudia to help deploy the app, and use the AWS CLI tool to set up a DynamoDB database.

But before we dive into the project, let’s quickly touch on what serverless is and why it’s often a great option for Node.

What Is Serverless?

The concept of serverless computing isn’t exactly new — you only pay-per-use without renting or buying dedicated servers. A serverless app is not long-lived because there are no guarantees on the hardware itself. This means your code runs best when it spins up quickly, does its job, and then dies. The more lightweight the code, the less you pay.

This serverless birth and rebirth mantra is what pushes developers to come up with simpler ways to solve the problem.

Why Node.js Works Well with Serverless

Node is a nice fit for serverless because it is designed to spin up quickly and runs anywhere, including phone hardware. Over the last decade, the JavaScript V8 engine has evolved to run as efficiently as possible, which is great for serverless.

Initial Setup: Build a Pizza API and Your TypeScript Project

The entire sample code for this project is available on GitHub. You can also follow along below — we will guide you step-by-step.

To start building your pizza API, open a console and type:

> mkdir typescript-aws-lambda
> cd typescript-aws-lambda
> mkdir part-1 && cd part-1
> mkdir pizza-api && cd pizza-api

Inside your new folder, execute npm init to create the skeleton project.json file. Be sure to give it a meaningful name, like pizza-api, as it will become the name of your Lambda function once it deploys to AWS.

Note that pizza-api is now the root folder, where you will perform the remaining work.

Next, we'll install Claudia. Claudia is a severless tool that will make it easy for us to deploy our project to AWS Lambda and API Gateway. Install all project dependencies:

> npm i typescript claudia --save-dev
> npm i @aws-sdk/client-dynamodb claudia-api-builder slugify --save

These are both dev and project dependencies. A general good practice is to keep them separate in the package.json file.

Now, initiate a TypeScript config for this project. There are two options:

tsc --init if you have it installed globally.
Or, my preference is to do node_modules/.bin/tsc --init from the root folder.

Once you have a tsconfig.json file, enable outDir and set it to ./dist in the JSON file.

Unfortunately, Claudia does not include type definitions for TypeScript. This problem can be solved by simply defining your own types in the code repo. To do so, create a folder under the root folder @types/claudia-api-builder, then an index.d.ts file. This instructs the compiler to find type definitions for claudia-api-builder under the same codebase.

Put this in index.d.ts:

declare module "claudia-api-builder" {
  export class ApiResponse {
    constructor(response: any, headers: any, code: number);
  }

  export default class ApiBuilder {
    get(route: string, handler: Function, options: any = {}): void;
    post(route: string, handler: Function, options: any = {}): void;
    put(route: string, handler: Function, options: any = {}): void;
    delete(route: string, handler: Function, options: any = {}): void;
    head(route: string, handler: Function, options: any = {}): void;
    patch(route: string, handler: Function, options: any = {}): void;
    registerAuthorizer(name: string, config: any): void;
  }
}

Luckily, the code Claudia exposes is relatively trivial. You create an ApiBuilder, then declare GET/POST endpoints in the API. Claudia takes care of the rest of the work in AWS.

The ApiResponse is also included. This response class is useful for custom API responses, but there is actually a sleeker way of handling responses (so we won’t use this response class).

AWS Configuration

Before we can start playing with Claudia and AWS Lambdas, you will need three things: the AWS CLI tool, an IAM user identity, and programmatic access via a key and secret.

First, download the AWS CLI tool to create a profile folder under the user’s home folder. In Windows, for example, this folder is under C:\Users\<user>\.aws. Inside are two files: config and credentials.

Then, create an AWS account, log in, and make a note of the region. You will want to pick one closest to your physical location. For example, us-east-1 or eu-central-1. Open up the config file and set the region accordingly.

For example:

[default]
region = us-east-1
output = json

Note that the CLI tool uses the default profile in this config file. You can have many profiles, but that is beyond the scope of this guide.

Next, create a user in IAM and assign programmatic access via an access key and secret. Be sure to set the correct group/role, so that you are allowed to create Lambdas and configure the AWS gateway.

This is what your credentials file should look like:

[default]
aws_access_key_id = ACCESS_KEY
aws_secret_access_key = SECRET_ACCESS_KEY

To test the credentials, simply run:

> aws sts get-caller-identity

With this, the aws CLI tool should be able to access the AWS cloud under your account. This is a one-time setup, and you will not have to revisit this configuration. The CLI tool does a good job of staying out of the way without eating your local machine.

Build Your Initial API with TypeScript

Now, let’s move on to the fun part! Create a single endpoint in AWS to test your capabilities in spinning up new Lambdas. This will have a simple greeting response.

Create a file named api.ts in the root folder and put this in place:

import Api from "claudia-api-builder";

const api = new Api();

api.get("/", () => ["Welcome to AWS"]);

There are a couple of things going on here: a route and a callback handler with the proper JSON response. Claudia makes building APIs somewhat easy because it automates the rest of the configuration in AWS. The route translates into an entry in the AWS gateway, and the handler is the actual Lambda function.

You can think of a Lambda as a single event that fires in the AWS cloud. An event can be triggered by pretty much anything — for example, a database change or a JWT authorizer. In this case, the AWS gateway picks up an HTTP request, and it too fires an event to execute your Lambda function.

To automate AWS deployments in Claudia, you will need to run the claudia command. Open up the package.json file and put this in the scripts section:

{
  "precreate": "tsc",
  "preupdate": "tsc",
  "create": "claudia create --region us-east-1 --api-module dist/api",
  "update": "claudia update --cache-api-config apiConfig",
  "type-check": "tsc"
}

The pre prefix guarantees the latest successful build before Claudia deploys. This is a nice technique for developers who are new to TypeScript and forget to run the compiler.

Be sure to specify the correct region that is closest to you in the command line argument.

With this in place, execute npm run create and let Claudia deploy. Claudia uses a zip deploy via npm pack to upload artifacts into the AWS cloud. If everything goes well, there should be an endpoint in the output that you can copy-paste into a browser.

Something like this:

{
  "url": "https://API_GATEWAY_ID.execute-api.us-east-1.amazonaws.com/latest"
}

Connect to DynamoDB and Use Claudia

The next step is to talk to DynamoDB. This requires two things: a role with access to the database and a table on AWS.

The command to create a role fails without a policy document file in roles/dynamodb.json. Create a file under this path and define the role access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "dynamodb:Scan",
        "dynamodb:DeleteItem",
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

To set up a role, run this command via the AWS CLI tool:

> aws iam put-role-policy --role-name pizza-api-executor --policy-name PizzaApiDynamoDB --policy-document file://./roles/dynamodb.json

Next, create the necessary table. We will use a url field as the key in the table. This is the resource locator field used to call the API and is part of the URL (for example, /Pepperoni-Pizza).

> aws dynamodb create-table --table-name pizzas --attribute-definitions AttributeName=url,AttributeType=S --key-schema AttributeName=url,KeyType=HASH --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 --region us-east-1 --query TableDescription.TableArn --output text

Be sure to specify the correct region, the one closest to you.

Create a TypeScript file — api.ts — in the root folder. Then, fill out the import/export code:

import Api from "claudia-api-builder";
import {
  DynamoDBClient,
  GetItemCommand,
  PutItemCommand,
  ScanCommand,
} from "@aws-sdk/client-dynamodb";
import slugify from "slugify";

// The rest of the code goes here

export = api;

Lastly, build the GET/POST endpoints in api.ts. I’ll leave the endpoint that returns all pizzas using a table scan as an exercise for you. You can find the full sample code in the GitHub repo.

api.post(
  "/pizzas",
  async (request: any) => {
    const { body } = request;

    if (
      !body ||
      !body.name ||
      !body.ingredients ||
      !Array.isArray(body.ingredients) ||
      body.ingredients.length === 0
    ) {
      throw new Error("To make a pizza include name and ingredients");
    }

    const pizzaItem = {
      url: { S: slugify(body.name) },
      name: { S: body.name },
      ingredients: { SS: body.ingredients }, // type-sensitive
    };

    await client.send(
      new PutItemCommand({
        TableName: "pizzas",
        Item: pizzaItem,
      })
    );

    console.log("Pizza is saved!", pizzaItem);
    return pizzaItem;
  },
  {
    success: 201,
    error: 400,
  }
);

api.get(
  "/pizzas/{url}",
  async (request: any) => {
    const url = request.pathParams.url;

    const res = await client.send(
      new GetItemCommand({
        TableName: "pizzas",
        Key: { url: { S: url } },
      })
    );
    const pizzaItem = res.Item;

    if (pizzaItem === undefined) throw new Error("Pizza not found!");

    return pizzaItem;
  },
  {
    success: 200,
    error: 404,
  }
);

To update the Lambda in AWS, run the npm run update command. Claudia keys off a claudia.json file and updates the Lambda with the latest code.

Each method takes three parameters: route, handler, and options. The options parameter at the end specifies the status code in the HTTP response. For example, for a GET, it throws an exception when the pizza is missing. Claudia handles this exception automatically and turns it into a '404 Not Found' response. Similarly, with POST, you get a '400 Bad Request' response when an exception gets thrown or '201 Created' when a new resource is available.

The request parameters contain either the body of the request or the pathParams values. These parameters come from the event fired by the AWS gateway, and Claudia makes it easy for you to consume both of them in your Lambda function.

Test Out Your AWS Lambda with CURL

Drumroll, please!

Now we’ll use CURL to test our Lambda. Send a POST request first to make a pizza with a name and ingredients:

> curl -X POST -i -H "Accept-Type: application/json" -H "Content-Type: application/json" -d "{\"name\":\"Pepperoni Pizza\",\"ingredients\":[\"tomato sauce\",\"cheese\",\"pepperoni\"]}" https://API_GATEWAY_ID.execute-api.us-east-1.amazonaws.com/latest/pizzas

Feel free to play around with this. If you forget to add a name or include ingredients in the body, the test will fail. DynamoDB is type-sensitive, so even if you try to put a list of numbers in the ingredients, it fails the request.

Finally, fire a GET to get your tasty pizza:

> curl -X GET -i -H "Accept-Type: application/json" -H "Content-Type: application/json" https://API_GATEWAY_API.execute-api.us-east-1.amazonaws.com/latest/pizzas/Pepperoni-Pizza

Up Next: Improve the Dev Experience

In this post, we explored how to effortlessly build AWS Lambda functions using TypeScript with Claudia.

Next in the series, we’ll look at ways to improve the developer experience, so your code is easier to work with and more robust.

Until then, happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.