Aquanow Admin-site Lambda

Backend APIs for Aquanow Admin Site

Why webpack

• Webpack as compiler and bundler, so we can control code size, quality, linting.
• Webpack, Babel & Eslint work together as an abstract layer give us more control over source code and final output. Eventually result in a uniformed development practice across organization which helps developers focus on business logic.

Prerequisites

AWS

Serverless command requires valid AWS credentials and AWS profiles(default aquaNow-DEV). If you come from auqanow-admin-site, you should already have those configured. Otherwise, refer to this link for details.

Dependencies

If you are the first time working on this repo make sure node version aligned with AWS environments and install dependencies

npm ci

Development

Local function invocation

npm start

This will start up an emulated API gateway on your local environment(default http://localhost:3000). After that you can send request directly to the gateway to test your function. Please keep in mind some API call will still be sent to online environments, i.e. S3, DynamoDB etc. Thus this is not a fully isolated local environment. For more information, please refer to serverless-offline and serverless-webpack plugins.

You can also invoke individual function by using OOTB serverless command invoke local -f <Function name> --path <JSON payload path>.

Environment variables

We don't use .env file to host environment variables. All variables will be hosted in serverless.yml file, custom block.

Breakpoints & local Debugging

You can configure your IDE to attach debug process to nodejs for local breakpoints & debugging. Here is an example for VSCode:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Serverless Offline",
      "program": "${workspaceRoot}/node_modules/serverless/bin/serverless",
      "args": [
        "offline",
        "--noTimeout",
        "--noAuth",
        "--stage=DEV"
      ],
      "sourceMaps": true,
      "runtimeArgs": ["--lazy"],
      "protocol": "inspector",
      "runtimeExecutable": "node",
      "env": {
        // Here we set some environment vars that should be set locally.
        // They can and will overwrite the ones coming from your serverless.yml
      },
      "windows": {
        "program": "${workspaceRoot}\\node_modules\\serverless\\bin\\serverless"
      },
      "console": "integratedTerminal"
    },
  ]
}

Unit Testing

npm test

Do not write unit test against any online environment. Write pure function, extract business logic from handler and mock the dependencies. Testing should be done prior to any staging/prod deployment.

Integration testing

We are still working on the template of integration testing. Integration testing will be performed against online environment.

Deployment

We are using 3 different AWS environments:

• DEV (development/QA)
• STAGING (staging/UAT)
• PROD (production/live)

In manual deployment to non-dev environment, please do not deploy each function separately to avoid inconsistent versions within same service.

sls deploy -f <FunctionName> -s <Stage(Uppercase)>

Troubleshooting

Configuration change not detected when deploying new version

This problem seems to be caused by manual updating config values on AWS console, so that CF is not able to detect the changes anymore. To avoid this issue, it is important to only update configs by deploy serverless.yml. If you find how to fix this issue, please update this documentation. #6956

JavaScript heap out of memory when packaging artifacts

This is due to a memory leak issue in serverless-webpack plugin when compiling artifacts with node_modules dependencies. This can be resolved by adjusting max space usage by node(default 1.7 GB)

export NODE_OPTIONS=--max-old-space-size=4096
npx serverless package

TODO

• [x] Serverless-offline
• [x] Properly handle environment variables
• [x] Remove layer usage in every function
• [x] Remove husky and precommit hook, use webpack for eslint & type check
• [x] Better unit testing suite
• [x] Standardize Eslint rules for Lambda repos
• [ ] Properly log and monitor error event
• [ ] momentjs migrate to dayjs for smaller bundle size
• [ ] Add serverless test functionality
• [ ] Prevent manual update configuration(CI/CD) which causes future CF changes not being detected

====== postponed =======

• [ ] Migrate to Typescript (Team are not ready for migration yet)
• [ ] aws-sdk upgrade to v3 to help tree-shaking (Use native aws-sdk for now)