@whook/aws-lambda

Build and deploy to AWS Lambda with Whook.

This module is aimed to help you to build and deploy your Whook server to AWS Lambda.

You can find a complete setup with a Terraform deployment example in this pull request.

Quick setup

Install this module:

npm i @whook/aws-lambda;

Add the plugin to the src/index.ts main file:

  // ...

  $.register(
    constant('WHOOK_PLUGINS', [
      ...WHOOK_DEFAULT_PLUGINS,
+      '@whook/aws-lambda',
      '@whook/cors',
    ]),
  );

  // ...

Tweak the 2 build functions in your src/build.ts main file:

import {
  // (...)
-  DEFAULT_INITIALIZER_PATH_MAP,
-  runBuild as runBaseBuild,
-  prepareBuildEnvironment as prepareBaseBuildEnvironment,
  // (...)
} from '@whook/whook';
+import {
+  DEFAULT_BUILD_INITIALIZER_PATH_MAP,
+  runBuild as runBaseBuild,
+  prepareBuildEnvironment as prepareBaseBuildEnvironment,
+} from '@whook/aws-lambda';

// (...)

// The `prepareBuildEnvironment` create the build
//  environment
export async function prepareBuildEnvironment(
  $: Knifecycle = new Knifecycle(),
): Promise<Knifecycle> {
  $ = await prepareEnvironment($);

  // (...)

-  // Usually, here you call the installed build env
-  // $ = await prepareBaseBuildEnvironment($);
+  // Calling the AWS specific build env
+  $ = await prepareBaseBuildEnvironment($);

  // The build often need to know were initializers
  //  can be found to create a static build and
  //  remove the need to create an injector
  $.register(
    constant('INITIALIZER_PATH_MAP', {
      // (...)
-      ...DEFAULT_INITIALIZER_PATH_MAP,
+      ...DEFAULT_BUILD_INITIALIZER_PATH_MAP,
    }),
  );

  // (...)

}

Declare this module types in your src/whook.d.ts type definitions:

+ import type { WhookCompilerConfig } from '@whook/whook';
+ import type {
+   WhookAWSLambdaBuildConfig,
+   WhookAPIOperationAWSLambdaConfig
+ } from '@whook/aws-lambda';

declare module 'application-services' {

  // ...

  export interface AppConfig
-    extends WhookBaseConfigs {}
+    extends WhookBaseConfigs,
+      WhookAWSLambdaBuildConfig,
+      WhookCompilerConfig {}
}

// ...

declare module '@whook/whook' {
  export interface WhookAPIHandlerDefinition<
    T extends Record<string, unknown> = Record<string, unknown>,
    U extends {
      [K in keyof U]: K extends `x-${string}` ? Record<string, unknown> : never;
    } = unknown,
    V extends Record<string, unknown> = Record<string, unknown>,
  > extends WhookBaseAPIHandlerDefinition<T, U> {
    operation: U & WhookAPIOperation<
        T &
+       WhookAPIOperationAWSLambdaConfig<V> &
      WhookAPIOperationCORSConfig
    >;
  }

}

And add the AWS Lambda config (usually in src/config/common/config.js):

// ...
import type { AppConfig } from 'application-services';

// ...

const CONFIG: AppConfig = {
  // ...
+  COMPILER_OPTIONS: {
+    externalModules: [],
+    target: '20',
+  },
};

export default CONFIG;

Build

To build your functions:

# Build all functions
npm run build

# Build only one function
npm run build -- getPing

Debug

You can easily test your functions builds by adding @whook/aws-lambda to your WHOOK_PLUGINS list. It provides you some commands like the testHTTPLambda one:

npx whook testHTTPLambda --name getPing

To get more insights when some errors happens:

DEBUG=whook npm run whook-dev -- testHTTPLambda --name getPing

Deployment

We recommend using Terraform to deploy your lambda functions.

There is a complete example on how to deploy your functions in this pull request.

API

Functions

initHandler(services) ⇒ Promise.<function()>: Initialize one Whook handler
initWrapHandlerForConsumerLambda(services) ⇒ Promise.<Object>: Wrap an handler to make it work with a consumer AWS Lambda.
initWrapHandlerForCronLambda(services) ⇒ Promise.<Object>: Wrap an handler to make it work with cron AWS Lambda.
initWrapHandlerForConsumerLambda(services) ⇒ Promise.<Object>: Wrap an handler to make it work with a consumer AWS Lambda.
initWrapHandlerForKafkaLambda(services) ⇒ Promise.<Object>: Wrap an handler to make it work with a kafka AWS Lambda.
initWrapHandlerForLogSubscriberLambda(services) ⇒ Promise.<Object>: Wrap an handler to make it work with a log subscriber AWS Lambda.
initWrapHandlerForS3Lambda(services) ⇒ Promise.<Object>: Wrap an handler to make it work with a S3 AWS Lambda.
initWrapHandlerForConsumerLambda(services) ⇒ Promise.<Object>: Wrap an handler to make it work with a transformer AWS Lambda.

initHandler(services) ⇒ `Promise.<function()>`

Initialize one Whook handler

Kind: global function
Returns: Promise.<function()> - A promise of the HANDLERS hash.

Param	Type	Default	Description
services	`Object`		The services `$autoload` depends on
services.WRAPPERS	`Array`		An optional list of wrappers to inject
[services.log]	`Object`	`noop`	An optional logging service
services.HANDLERS	`Object`		The rest is a hash of handlers mapped by their operation id