Forem: Mark Tse

Using dotenv with the Serverless Framework

Mark Tse — Tue, 27 Apr 2021 13:30:00 +0000

In my previous post, I advised that the serverless-dotenv-plugin will no longer be able to load environment variables in time to resolve env variables in your service files (e.g. serverless.yml). In this post, I want to go into details on how you can use dotenv without the plugin.

With the Serverless Framework, you can use the file variable to dynamically evaluate variables by executing JavaScript code. Leveraging this feature, you can get the Serverless Framework to run any arbitrary code, such as calling dotenv to load environment variables! See how MY_ENV_VAR is loaded into the framework below:

.env.local:

MY_ENV_VAR=loaded-by-dotenv

configs.js:

const dotenv = require('dotenv');

module.exports = async ({ options, resolveConfigurationProperty }) => {
  // Load env vars into Serverless environment
  // You can do more complicated env var resolution with dotenv here
  const envVars = dotenv.config({ path: '.env.local' }).parsed;
  return envVars;
};

serverless.yml:

service: my-service
# Required to use the new variables engine
# https://www.serverless.com/framework/docs/providers/aws/guide/variables#exporting-a-function
variablesResolutionMode: 20210219

custom:
  dotenvVars: ${file(configs.js)}

functions:
  hello:
    handler: src/hello.handler
    environment:
      MY_ENV_VAR: ${env:MY_ENV_VAR}

When the Serverless Framework sees ${file(configs.js)}, the variables resolver will call the function exported in configs.js. The JavaScript code there includes a call to dotenv.config(), which will load all environment variables defined in .env.local. Because this loads the environment variables into the process, plugins will also have access to them.

With a for loop, you can load multiple dotenv files (e.g. .env and .env.local), or with options.stage, you can load files based on the value of the --stage parameter. You can also load any dotenv plugins you may be interested in using, such as dotenv-expand. Because you are able to execute arbitrary JavaScript code, you are only limited by what you can do in JavaScript!

You can find a full example is available at neverendingqs/serverless-dotenv-example. Got questions or want to see more content like this? Check out neverendingqs/ask-me-anything!

AWS Lambda: Always Allocate (At Least) 1024 MB

Mark Tse — Fri, 16 Apr 2021 15:30:00 +0000

When using AWS Lambda, you are billed for every millisecond your Lambda function takes to run, depending on how much memory you have allocated. A function configured for 256 MB of memory will cost twice as much as a function configured for 128 MB of memory per millisecond. At first, it may seem that you should allocate as little memory as possible to reduce costs. However, the memory configuration also controls how much CPU power, network bandswidth, and disk I/O you get, and that plays a major role in how long your function takes to execute. Functions that take less time to execute reduces how much you get billed for its invocation.

In a presentation by Harrell Stiles during re:Invent, he benchmarked that the same function allocated with 1024 MB of memory ran over 10 times faster for only $0.00001 more than the 128 MB equivalent, and outperformed the same function allocated with 256 MB and 512 MB of memory. This is due to the additional CPU power that was allocated behind the scenes to the function, which allowed it to complete its task faster. If the function had relied on network and/or disk I/O, it could have also benefited from the increased network and disk bandswidth.

The same presentation noted that Lambda functions allocated with at least 1.8 GB of memory also becomes multi-core. This is useful for improving the performance of functions that make network and/or disk I/O requests. Even if you are using Node.js, the extra core allows for more operating system level threads managed by the underlying libuv library to run, and you should see performance improvements as a result.

As a caveat, if your Lambda function's main goal is to start and wait for another process (e.g. a long web request), you should allocate as little memory as possible, since the extra memory would only increase cost without decreasing the wait time. Alternatively, consider doing things asynchronously (e.g. with a callback) so that the Lambda function can halt after making the request.

In the end, if you need to be precise about the performance and/or cost of your application, you need to test the different memory configurations yourself. In most cases, you should allocate at least 1.8 GB of memory for network and/or I/O heavy functions and at least 1024 MB of memory for all other functions.

Major changes to serverless-dotenv-plugin

Mark Tse — Tue, 30 Mar 2021 14:30:00 +0000

The Serverless Framework has a new variables engine starting inserverless@2.26.0. This is part of a larger initiative by the Serverless Framework team that will come into effect in serverless>=3.0.0.

The biggest impact with these changes is that plugins will not get initialized until after env variables are resolved. This meansserverless-dotenv-plugin is no longer able to load environment variables in time for them to be used in your service file (i.e. serverless.yml). However, the plugin will continue to load environment variables into all your functions using dotenv.

If you need to load environment variables to be used in your service, you will either need to use the built-in dotenvfunctionality or wire up dotenv yourself. You can see an example of how to wire up dotenvyourself atneverendingqs/serverless-dotenv-example.

I’m happy to address any questions or comments in the discussions section on GitHub or below. I’m also happy to answer any Serverless Framework questions you may have at neverendingqs/ask-me-anything.

Getting the Request ID of a Lambda Invocation when Using Promises With the AWS SDK

Mark Tse — Mon, 31 Aug 2020 02:30:00 +0000

Every invocation of an AWS Lambda function is associated with a request ID. Searching the CloudWatch logs with the request ID is the quickest way to find the logs of a given invocation.

To get the request ID when using the JavaScript AWS SDK, you can access the $response property of the response:

const AWS = require('aws-sdk');
const lambda = new AWS.Lambda();

const response = await lambda.invoke({
  ...
}).promise();

const requestId = response.$response.requestId;

The entire response object from the HTTP request is available to you via the $response object. Also, the $response object is available across almost all API calls, not just lambda.invoke().promise().

If you ever want to track down the results of a single invocation among many, consider logging the response ID.

Run arbitrary commands via a comment and commit the changes

Mark Tse — Sun, 30 Aug 2020 01:15:11 +0000

DISCLAIMER: the Run terminal command GitHub Action allows for arbtrary code execution by any user allowed to comment on your issues or pull requests. You should probably never use this except to explore what GitHub Actions could do.

To avoid security issues, replace the use of the Run terminal command GitHub Action with something that validates input or with something that always runs the same command.

My Workflow

This workflow allows you to run any command and commit the changes back into a pull request. For example, you can run /terminal npm version patch --no-git-tag-version to bump the patch version of your Node package.

This workflow:

Only runs on new pull request comments and only if the comment starts with /terminal
Acknowledges comments that start with /terminal by reacting with a +1
Determines what pull request the comment came from and gets the corresponding branch name
Checks out the code at that branch
Runs the command, commits the changes, and pushes it back to the branch

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

on:
  issue_comment:
    types: [created]

jobs:
  run-and-update:
    if: contains(github.event.comment.html_url, '/pull/') && startsWith( github.event.comment.body, '/terminal ' )
    runs-on: ubuntu-latest
    steps:
      - name: Acknowledge command
        uses: actions/github-script@v3
        with:
          script: |
            github.reactions.createForIssueComment({
              comment_id: context.payload.comment.id,
              owner: context.repo.owner,
              repo: context.repo.repo,
              content: '+1',
            });
      - id: get-ref
        name: Get branch name
        uses: actions/github-script@v3
        with:
          result-encoding: string
          script: |
            const response = await github.pulls.get({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.payload.issue.number
            });

            return response.data.head.ref;
      - uses: actions/checkout@v2
        with:
          ref: ${{ steps.get-ref.outputs.result }}
      - uses: actions/setup-node@v1
        with:
          node-version: '12'
      - id: terminal
        uses: neverendingqs/gh-action-terminal@main
      - run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com

          git commit -am "chore: update after '${COMMAND}'."
          git push
        env:
          COMMAND: ${{ steps.terminal.outputs.command }}

Additional Resources / Info

GitHub Action for Updating All NPM Dependencies at Once

Mark Tse — Mon, 24 Aug 2020 02:06:19 +0000

My Workflow

I recently created a JavaScript GitHub Action that allows anyone to search Stack Overflow via an issue or pull request comment. To keep its dependencies up-to-date, I could turn to Dependabot, but they currently do not support grouped updates, which means if multiple dependencies require an update, I have to review each one individually.

Instead, I turned to an existing GitHub Action I've built, Update Node Dependencies. This action:

Uses npm-check-updates to update all dependencies to their latest version
Runs npm audit --fix to fix any remaining security issues (if any)
Does a package version bump (patch)
Uses hub to create a new pull request with these changes

Since I am using @zeit/ncc to build my JavaScript action, I also configured a pre-commit script to run to ensure all dependency updates make it into the code GitHub Actions runs (in dist/).

The workflow is scheduled to run weekly, but can also be manually triggered. I leave Dependabot security alerts turned on so that I am alerted of severe security issues and can respond to them immediately by manually triggering the workflow outside of its schedule.

All this put together means I can keep my dependencies up-to-date with only one pull request a week while still having the ability to respond to security issues immediately!

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

name: Scheduled Node Dependencies Update (npm)
on:
  schedule:
    - cron:  '0 15 * * 2'
  workflow_dispatch:
jobs:
  update-deps:
    name: Update Node dependencies using npm
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - uses: neverendingqs/gh-action-node-update-deps@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          bump-version: patch
          pre-commit-script: npm run build

neverendingqs / gh-action-ask-stackoverflow

Search Stack Overflow on issues and pull requests using this GitHub Action.

gh-action-ask-stackoverflow

Search Stack Overflow on issues and pull requests using this GitHub Action.

Usage

Set up a workflow to pull in this action:

on:
  issue_comment:
    types: [created]

jobs:
  ask-stackoverflow:
    runs-on: ubuntu-latest
    steps:
      - uses: neverendingqs/gh-action-ask-stackoverflow@master
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

‌‌‌‌ ‌‌‌‌‌ ‌‌‌‌ ‌‌‌‌ ‌‌‌‌ ‌‌‌‌‌ ‌‌‌ ‌‌‌‌ ‌‌‌‌‌ ‌‌‌‌‌ ‌‌‌‌ ‌‌‌‌‌

Then search anything on Stack Overflow using the /so command, and the action will post back with the top 3 matching results, each with the top 3 answers.

Try it out by running the /so command on this issue or pull request!

View on GitHub

Additional Resources / Info

Stack Overflow Search GitHub Action

Mark Tse — Sun, 23 Aug 2020 02:51:40 +0000

My Workflow

I created a new GitHub action that allows anyone to search on Stack Overflow via an issue or pull request comment. I created a workflow that uses this action so that you can try it out on this issue or pull request!

Usage: /so <query>

Submission Category:

Wacky Wildcards

Yaml File or Link to Code

on:
  issue_comment:
    types: [created]

jobs:
  ask-stackoverflow:
    runs-on: ubuntu-latest
    steps:
      - uses: neverendingqs/gh-action-ask-stackoverflow@master
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

neverendingqs / gh-action-ask-stackoverflow

Search Stack Overflow on issues and pull requests using this GitHub Action.

gh-action-ask-stackoverflow

Search Stack Overflow on issues and pull requests using this GitHub Action.

Usage

Set up a workflow to pull in this action:

on:
  issue_comment:
    types: [created]

jobs:
  ask-stackoverflow:
    runs-on: ubuntu-latest
    steps:
      - uses: neverendingqs/gh-action-ask-stackoverflow@master
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

‌‌‌‌ ‌‌‌‌‌ ‌‌‌‌ ‌‌‌‌ ‌‌‌‌ ‌‌‌‌‌ ‌‌‌ ‌‌‌‌ ‌‌‌‌‌ ‌‌‌‌‌ ‌‌‌‌ ‌‌‌‌‌

Then search anything on Stack Overflow using the /so command, and the action will post back with the top 3 matching results, each with the top 3 answers.

Try it out by running the /so command on this issue or pull request!

View on GitHub

Additional Resources / Info

Using GitHub Actions to Keep Another GitHub Action's Image Up-to-Date

Mark Tse — Sun, 16 Aug 2020 18:51:10 +0000

My Workflow

gh-action-node-update-deps is a GitHub action for keeping dependencies up-to-date. Each time it runs, it installs the latest version of a few dependencies (Git, curl, hub). To improve performance, I created a custom Docker image with these dependencies already installed.

To keep this Docker image and all the installed dependencies up-to-date, I created a GitHub Actions workflow to schedule a recurring build of this image, which use a cron trigger and:

Submission Category:

DIY Deployments

Yaml File or Link to Code

name: Publish to Docker

on:
  schedule:
    - cron:  '0 * * * *'
  workflow_dispatch:

jobs:
  publish-to-docker:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - run: |
        git config user.name github-actions[bot]
        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
        git commit --allow-empty -m "chore: update image (automated)."
        git push
    - uses: docker/build-push-action@v1
      with:
        username: neverendingqs
        password: ${{ secrets.DOCKER_ACCESS_TOKEN }}
        repository: ${{ env.GITHUB_REPOSITORY }}
        add_git_labels: true
        tag_with_ref: true
        tag_with_sha: true

Additional Resources / Info

The repository that hosts the Dockerfile and GitHub Actions workflow: node-lts-git-hub-image
The GitHub Action using this Docker image: gh-action-node-update-deps

Using Proxy’s get() Trap for Easy Defaults and Even method_missing!

Mark Tse — Tue, 23 Jul 2019 11:00:00 +0000

Proxy’shandler.get() trap is very powerful. Here are some examples of what it can do.

Counter

Need to keep a counter of something? The following example shows how many of each animal appears in a list.

const animals = [
  'dog', 'cat', 'mouse', 'cat', 'dog',
  'dog', 'mouse', 'cat', 'cat', 'dog',
  'mouse', 'cat', 'mouse', 'dog', 'dog'
];

const counter = new Proxy({}, {
  get: (obj, property) => obj[property] || 0
});

animals.forEach(animal => counter[animal] += 1);

console.log(JSON.stringify(counter, null, 2));

{
  "dog": 6,
  "cat": 5,
  "mouse": 4
}

Arrays

Or how about grouping things together in an object of arrays?

const data = {
  posts: [
    { name: 'post1', tags: ['tag1', 'tag2', 'tag3'] },
    { name: 'post2', tags: ['tag2', 'tag5', 'tag7'] },
    { name: 'post3', tags: ['tag3', 'tag6', 'tag7'] },
    { name: 'post3', tags: ['tag2', 'tag3', 'tag6'] },
    { name: 'post3', tags: ['tag1', 'tag4', 'tag5'] }
  ]
};

const postsByTag = new Proxy({}, {
  get: (obj, property) => obj[property] || []
});

data.posts.forEach(post =>
  post.tags.forEach(tag =>
    postsByTag[tag] = postsByTag[tag].concat(post.name)
  )
);

console.log(JSON.stringify(postsByTag, null, 2));

{
  "tag1": [
    "post1",
    "post3"
  ],
  "tag2": [
    "post1",
    "post2",
    "post3"
  ],
  "tag3": [
    "post1",
    "post3",
    "post3"
  ],
  "tag5": [
    "post2",
    "post3"
  ],
  "tag7": [
    "post2",
    "post3"
  ],
  "tag6": [
    "post3",
    "post3"
  ],
  "tag4": [
    "post3"
  ]
}

Ruby’s `method_missing`

You can even imitate Ruby’s method_missing by making decisions on the fly!

const greeter = new Proxy({}, {
  get: (obj, property) => {
    if(property.startsWith('print')) {
      const toPrint = property.split('_').slice(1);
      return () => toPrint.forEach(p => console.log(obj[p]));
    } else {
      return obj[property];
    }
  }
});

greeter.firstName = 'Jane';
greeter.lastName = 'Doe';
greeter.helloWorld = () => console.log('Hello World');

greeter.helloWorld();
greeter.print_firstName_lastName();

Hello World
Jane
Doe

These are only a small set of examples of the handler.get() trap. What are some things you have done with the Proxy object?

Waste GUIDs Even Faster with Waste Some GUIDs!

Mark Tse — Mon, 08 Jul 2019 18:00:00 +0000

What can be better than being able to indulge in your deepest and most base desire of wasting GUIDs one at a time? The ability to waste multiple GUIDs at a time of course!

With the magic of Vue.js, I have created the ultimate GUID wasting machine: Waste Some GUIDs! Go ahead, start wasting those GUIDs. You deserve it!

Because everything is better in Vue.js.

Many GUIDs were wasted in the making of this post.

API Gateway WebSocket APIs with the Serverless Framework

Mark Tse — Mon, 01 Jul 2019 16:00:00 +0000

I recently built a web application in JavaScript that leveraged WebSockets to display live data from a server. I used AWS API Gateway WebSocket APIs in the back-end and the WebSocket API in the front-end. I also used the Serverless Framework ("Serverless" for short) to deploy the back-end.

In this post, I will do a quick walkthrough of a simple WebSocket application I wrote. Although I will be sharing snippets of Serverless configuration, the examples should be informative enough to apply it to the deployment method you are using.

Back-End

The backend consists of an API Gateway WebSockets API, some Lambda functions, and a persistent store.

Routing WebSocket Messages

The first thing I had to do was create a WebSocket API and configure the three predefined routes:

# serverless.yml
functions:
  # Create a Lambda function that responds to messages for the predefined routes
  websocket:
    handler: src/websocket.handler
    events:
      - websocket:
          # Handles new connection requests
          route: $connect

      - websocket:
          # Route messages here if '$request.body.action' is 'routeA'.
          # You can adjust which property to use for routing by adjusting
          # 'websocketsApiRouteSelectionExpression'.
          route: routeA

      - websocket:
          # Handles all unrouted messages
          route: $default

      - websocket:
          # Handles disconnect messages
          route: $disconnect

Serverless will configure API Gateway to call the Lambda function defined at src/websocket.handler whenever it receives a message. The function should look something like this:

// src/websocket.js
exports.handler = async function(event, context) {
  const { requestContext: { routeKey }} = event;
  switch(routeKey) {
    case '$connect':
      ...
      break;

    case '$disconnect':
      ...
      break;

    case 'routeA':
      ...
      break;

    case '$default':
    default:
      ...
  }

  // Return a 200 status to tell API Gateway the message was processed
  // successfully.
  // Otherwise, API Gateway will return a 500 to the client.
  return { statusCode: 200 };
}

I chose to handle messages from any route in the same Lambda function, but you can instead split that out into more than one function. For more details on how to do that in Serverless, see their WebSocket documentation.

WebSocket Sessions

When a WebSocket client requests a new connection, API Gateway assigns a connection ID to that session and invokes your $connect Lambda function with the ID in the event payload (event.requestContext.connectionId). You can use that right away to start sending messages to the client in the same function invocation. If you would like to send messages at a later time, you need to store the connection ID somewhere.

In the code example, I used DynamoDB to store the connection ID:

// src/websocket.js
case '$connect':
  await dynamodb.put({
    TableName: connectionTable,
    Item: {
      connectionId,
      // Expire the connection an hour later. This is optional, but recommended.
      // You will have to decide how often to time out and/or refresh the ttl.
      ttl: parseInt((Date.now() / 1000) + 3600)
    }
  }).promise();
  break;

This allows the broadcast Lambda function to get a list of all connected WebSocket clients when broadcasting a message.

I also made sure to clean up sessions as clients close their WebSocket connections:

// src/websocket.js
case '$disconnect':
  await dynamodb.delete({
    TableName: connectionTable,
    Key: { connectionId }
  }).promise();
  break;

Using the ApiGatewayManagementApi Class

To send a message back to the client, you need to use the ApiGatewayManagementApi class. Unlike other AWS services where you provide the resource location when calling an instance method (e.g. the S3 bucket name for putObject() or the DynamoDB table name for putItem()), you need to provide the URL to your WebSocket API on class creation:

const apig = new AWS.ApiGatewayManagementApi({
  endpoint: // your WebSocket API endpoint here
});

You can then use postToConnection() to send messages to the client:

await apig.postToConnection({
  ConnectionId: connectionId,
  Data: body
}).promise();

The endpoint follows a specific format and you can use CloudFormation's join and reference functions to format it:

# serverless.yml
# <logical ID of the WebSocket API>.execute-api.<AWS region>.amazonaws.com/<stage>
APIG_ENDPOINT:
  Fn::Join:
    - ''
    - - Ref: WebsocketsApi
      - .execute-api.
      - Ref: AWS::Region
      - .amazonaws.com/
      - ${self:custom.stage}

If you do not provide an endpoint when creating a new ApiGatewayManagementApi object, you will get an error like the following when you call postToConnection():

{
    "errorMessage": "Inaccessible host: `execute-api.us-east-1.amazonaws.com'. This service may not be available in the `us-east-1' region.",
    "errorType": "Error",
    "stackTrace": [
        "UnknownEndpoint: Inaccessible host: `execute-api.us-east-1.amazonaws.com'. This service may not be available in the `us-east-1' region.",
        "    at Request.ENOTFOUND_ERROR (/serverless-websocket-example/node_modules/aws-sdk/lib/event_listeners.js:494:46)",
        "    at Request.callListeners (/serverless-websocket-example/node_modules/aws-sdk/lib/sequential_executor.js:106:20)",
        "    at Request.emit (/serverless-websocket-example/node_modules/aws-sdk/lib/sequential_executor.js:78:10)",
        "    at Request.emit (/serverless-websocket-example/node_modules/aws-sdk/lib/request.js:683:14)",
        "    at ClientRequest.error (/serverless-websocket-example/node_modules/aws-sdk/lib/event_listeners.js:333:22)",
        "    at ClientRequest.<anonymous> (/serverless-websocket-example/node_modules/aws-sdk/lib/http/node.js:96:19)",
        "    at ClientRequest.emit (events.js:189:13)",
        "    at ClientRequest.EventEmitter.emit (domain.js:441:20)",
        "    at TLSSocket.socketErrorListener (_http_client.js:392:9)",
        "    at TLSSocket.emit (events.js:189:13)",
        "    at TLSSocket.EventEmitter.emit (domain.js:441:20)",
        "    at emitErrorNT (internal/streams/destroy.js:82:8)",
        "    at emitErrorAndCloseNT (internal/streams/destroy.js:50:3)",
        "    at process._tickCallback (internal/process/next_tick.js:63:19)"
    ]
}

Also, if you are not using the nodejs10.x runtime, you might get the following error:

{
    "errorMessage": "AWS.ApiGatewayManagementApi is not a constructor",
    "errorType": "TypeError",
    "stackTrace": [
        "Module._compile (module.js:652:30)",
        "Object.Module._extensions..js (module.js:663:10)",
        "Module.load (module.js:565:32)",
        "tryModuleLoad (module.js:505:12)",
        "Function.Module._load (module.js:497:3)",
        "Module.require (module.js:596:17)",
        "require (internal/module.js:11:18)"
    ]
}

The AWS JavaScript SDK introduced the ApiGatewayManagementApi class in v2.379.0, but the nodejs8.10 runtime only has v2.290.0 of the SDK. If you are using nodejs8.10, you either have to switch to using nodejs10.x (nodejs10.x is currently at v2.437.0) or bundle your own version of aws-sdk. See AWS's Lambda runtime documentation for more details, including information around other language runtimes.

Creating an Authorizer Lambda Function

An authorizer Lambda function is optional (but recommended). It gets called before the $connect Lambda function gets called to make a decision around authorization. For example, you can check for a token in the Authorization header and reject the request if the token is invalid.

In the sample code, I created a very simple authorizer Lambda function that does an uninteresting check:

// src/authorizer.js
function createAuthorizedResponse(resource) {
  return {
    principalId: 'me',
    policyDocument: {
      Version: '2012-10-17',
      Statement: [{
        Action: 'execute-api:Invoke',
        Effect: 'Allow',
        Resource: resource
      }]
    }
  };
}

exports.handler = async function(event, context) {
  // For debug purposes only.
  // You should not log any sensitive information in production.
  console.log("EVENT: \n" + JSON.stringify(event, null, 2));

  const { headers, methodArn } = event;

  // This is for demo purposes only.
  // This check is probably not valuable in production.
  if(headers['X-Forwarded-Proto'] === 'https') {
    return createAuthorizedResponse(methodArn);
  } else {
    throw new Error('Unauthorized');
  }
}

For REST APIs, you can configure an authorizer Lambda function for any route. For WebSocket APIs, only the $connect route can have an authorizer function associated with it. If you try to configure other routes with an authorizer function, you get an error like the following:

An error occurred: routeAWebsocketsRoute - Currently, authorization is restricted to the $connect route only (Service: AmazonApiGatewayV2; Status Code: 400; Error Code: BadRequestException; Request ID: a04ea057-954f-436f-962e-3946639f3d15).

This implies authorization is only checked on initial connection, and that the connection ID is the only authorization check for messages sent to other routes. You should protect it like you would a session ID.

If you have an existing session management system for your application that also makes authorization decisions, it must associate the current session with the connection ID assigned by API Gateway. Discussing how to do this is out-of-scope of this post, but you may want to take a look at how you can pass context from the authorizer Lambda function to the Lambda function handling $connect messages.

If the authorizer Lambda function rejects the connection request, the WebSocket client will receive a 401.

Front-End

The front-end code is centered around the WebSocket class:

// The endpoint's protocol is either 'ws://' or 'wss://'.
// The preferred protocol is 'wss://'.
const websocket = new WebSocket(endpoint);

There are four events / event handlers of interest:

close / onclose
error / onerror
message / onmessage
open / onopen

To listen to any of these events, create a corresponding function for it:

websocket.onmessage = ({ data }) => {
  // handle the message
};

onmessage is the most important one, as that is where you handle new messages from the server, while onopen, onerror, and onclose are useful for managing the application's state. onclose is also useful so that you know when API Gateway closes the connection, as it does so upon inactivity.

Each event has different properties available, and details are available on the HTML Living Standard page.

As a side note, WebSocket sends a $disconnect message to the server on page reload or close, so you do not have to close the connection yourself in those scenarios.

Conclusion

In this post, I did a quick walkthrough of what I learned when building a simple WebSocket application. Feel free to use any of the working sample code and please let me know of any questions or comments below!

Express.js on Netlify

Mark Tse — Sat, 08 Sep 2018 15:00:00 +0000

Netlify started off as a service for hosting static websites. Not only was it an amazing service from the start, managing the hosting infrastructure so you can focus on putting your website together, but they have since added support for those looking to go beyond a static site. AWS (Amazon Web Services) Lambda functions, their most recent add-on, means developers now have the freedom to run arbitrary back-end code to support their website without having to leave Netlify.

However, if you come from an Express.js background, you may not be interested in working with or have the time to learn a new technology stack. In this post, I will show how you can build an Express.js application on top of Lambda functions. If you are using another web framework (e.g. Koa.js), stick around! The contents of this post should also apply to any web framework built upon Node.js’s http module.

Although I will be referring to only AWS Lambda functions in this post, I really mean the API Gateway API and Lambda integration, which Netlify functions has abstracted away for us.

Quick Introduction to Lambda Functions

Imagine a function that updates a database in a web application that is running on a server:

function updateDatabase(data) {
  ... // update the database
  return newValue;
}

and imagine that it was tied to a route:

app.post('/updatestate', (res, req) => {
  const newValue = updateDatabase(res.body);
  req.json(newValue);
});

How many servers do you need to serve the /updatestate endpoint? Do you know when to add servers during high-load periods and when to scale down to save money?

The idea behind Lambda functions is that you simply pay for what you need and do not have to worry about responding to changes in load to your application. If nothing is happening, you do not pay at all. If the number of requests spike, AWS automatically scales for you in the background to match that load. All you have to do is provide the code you want Lambda to execute upon each request. In our example that would be the equivalent of updateDatabase(), which would look something like this:

'use strict';
function updateDatabase(data) {
  ... // update the database
  return newValue;
}

exports.handler = function(event, context, callback) {
  if(event.httpMethod === 'POST' && event.path === '/my/path') {
    const requestBody = JSON.parse(event.body);
    const newValue = updateDatabase(requestBody);
    callback(null, {
      statusCode: 200,
      body: newValue
    });
  } else {
    callback(null, {
      statusCode: 400,
      body: {}
    });
  }
}

Lambda will call the handler function for each request. The event object is Lambda’s way of representing the incoming request, and the callback(err, data)function is how you tell Lambda what response to send back.

Express.js via serverless-http

Express.js is a web framework that is built on the http module, simplifying route management as described in Understanding Express.js by Evan Hahn. If you look at the following example from that article, you will notice that you have to manage routing when using http, similar to when using Lambda functions:

var http = require("http");

http.createServer(function(req, res) {
  // Homepage
  if (req.url === "/") {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.end("Welcome to the homepage!");
  }

  // About page
  else if (req.url === "/about") {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.end("Welcome to the about page!");
  }

  // 404'd!
  else {
    res.writeHead(404, { "Content-Type": "text/plain" });
    res.end("404 error! File not found.");
  }
}).listen(1337, "localhost");

Going back to our Lambda function, you will notice that the event object andcallback function are very similar to Express.js’s req and res object, in that they facilitate getting information about the request and returning a response to the client. In fact, it is similar enough that a library exists to translate between the two:serverless-http.

With serverless-http, you can do something like this:

'use strict';
const express = require('express');
const serverless = require('serverless-http');
const app = express();
const bodyParser = require('body-parser');

function updateDatabase(data) {
  ... // update the database
  return newValue;
}

app.use(bodyParser);
app.post('/updatestate', (res, req) => {
  const newValue = updateDatabase(res.body);
  req.json(newValue);
});

module.exports.handler = serverless(app);

The key is that last bit, where serverless-http acts as a decorator and translates Lambda’s event into something Express.js can use, and req back to a proper call to Lambda’s callback(err, data).

Benefits

Using serverless-http and Express.js on top of Lambda functions simplifies the routing decision code, similiar to why you would use Express.js over the httpmodule. It also allows you to use your favourite Express.js patterns and middleware for your Netlify websites without having to leave Netlify.

Limitations

There are several limitations to this approach.

Resource Limits

Netlify’s Lambda functions have a 128 MB memory and 10 seconds execution limit. In terms of processing power (CPU), AWS does not disclose that value, but it is proportional to how much memory is allocated to the Lambda function. There is also 512 MB of temporary disk space available across all memory configurations.

These limits mean you will not be able to have any large or long-running back-end requests. If you bypass those limits, the Lambda function stops executing immediately with an error, which translates to a 500 HTTP status code. You can see the full set of limits on AWS’s developer guide.

Interestingly enough, 1024 MB Lambda functions are more price-effective than 128 MB Lambda functions and they run in a shorter time. If you are a heavy user of Lambda functions, you may want to contact sales as per their documentation to request 1024 MB functions.

Statelessness

AWS makes no guarantees that any instance of a Lambda function will be reused for multiple requests, and can create a new instance at any time. This means you can not expect any in-memory state or file system content to persist across requests. For more details, I recommend looking at the developer guide.

Static Files

Netlify requires that each Lambda function’s code to be self-contained in one file. This means you are unable to serve any static files from Express.js, and that any view templates will have to be embedded in JavaScript files.

Database

Behind most web applications is a database. Netlify does not provide a database service (yet), so if you need a persistent data store, such as for session management, you will have to bring your own at this time.

Keep in mind that there are no guarantees that subsequent calls will reuse an instance of your Lambda function, so do not rely on in-memory caches (e.g. do not use memorystore to manage your sessions).

Conclusion

In this post, I have showed how you can use Express.js with Lambda functions and outlined the limitations with this approach. If you are interested in exploring this topic further, I have a very simple deploy-ready sample at neverendingqs/netlify-express that you can get started with.

Let me know what you think by leaving a comment below!