@whook/aws-lambda
v16.1.0
Published
Build and deploy to AWS Lambda with Whook.
Downloads
612
Readme
@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
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 |
initWrapHandlerForConsumerLambda(services) ⇒ Promise.<Object>
Wrap an handler to make it work with a consumer AWS Lambda.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description | | --- | --- | --- | --- | | services | Object | | The services the wrapper depends on | | services.ENV | Object | | The process environment | | services.OPERATION_API | Object | | An OpenAPI definitition for that handler | | services.apm | Object | | An application monitoring service | | [services.time] | Object | | An optional time service | | [services.log] | Object | noop | An optional logging service |
initWrapHandlerForCronLambda(services) ⇒ Promise.<Object>
Wrap an handler to make it work with cron AWS Lambda.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description | | --- | --- | --- | --- | | services | Object | | The services the wrapper depends on | | services.ENV | Object | | The process environment | | services.OPERATION_API | Object | | An OpenAPI definitition for that handler | | services.apm | Object | | An application monitoring service | | [services.time] | Object | | An optional time service | | [services.log] | Object | noop | An optional logging service |
initWrapHandlerForConsumerLambda(services) ⇒ Promise.<Object>
Wrap an handler to make it work with a consumer AWS Lambda.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description | | --- | --- | --- | --- | | services | Object | | The services the wrapper depends on | | services.OPERATION_API | Object | | An OpenAPI definitition for that handler | | services.ENV | Object | | The process environment | | services.DEBUG_NODE_ENVS | Object | | The NODE_ENV values that trigger debugging | | services.DECODERS | Object | | Request body decoders available | | services.ENCODERS | Object | | Response body encoders available | | services.PARSED_HEADERS | Object | | A list of headers that should be parsed as JSON | | services.PARSERS | Object | | Request body parsers available | | services.STRINGIFYERS | Object | | Response body stringifyers available | | services.BUFFER_LIMIT | Object | | The buffer size limit | | services.apm | Object | | An application monitoring service | | services.obfuscator | Object | | A service to hide sensible values | | services.errorHandler | Object | | A service that changes any error to Whook response | | [services.time] | Object | | An optional time service | | [services.log] | Object | noop | An optional logging service |
initWrapHandlerForKafkaLambda(services) ⇒ Promise.<Object>
Wrap an handler to make it work with a kafka AWS Lambda.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description | | --- | --- | --- | --- | | services | Object | | The services the wrapper depends on | | services.ENV | Object | | The process environment | | services.OPERATION_API | Object | | An OpenAPI definitition for that handler | | services.apm | Object | | An application monitoring service | | [services.time] | Object | | An optional time service | | [services.log] | Object | noop | An optional logging service |
initWrapHandlerForLogSubscriberLambda(services) ⇒ Promise.<Object>
Wrap an handler to make it work with a log subscriber AWS Lambda.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description | | --- | --- | --- | --- | | services | Object | | The services the wrapper depends on | | services.ENV | Object | | The process environment | | services.OPERATION_API | Object | | An OpenAPI definitition for that handler | | services.apm | Object | | An application monitoring service | | [services.time] | Object | | An optional time service | | [services.log] | Object | noop | An optional logging service |
initWrapHandlerForS3Lambda(services) ⇒ Promise.<Object>
Wrap an handler to make it work with a S3 AWS Lambda.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description | | --- | --- | --- | --- | | services | Object | | The services the wrapper depends on | | services.ENV | Object | | The process environment | | services.OPERATION_API | Object | | An OpenAPI definitition for that handler | | services.apm | Object | | An application monitoring service | | [services.time] | Object | | An optional time service | | [services.log] | Object | noop | An optional logging service |
initWrapHandlerForConsumerLambda(services) ⇒ Promise.<Object>
Wrap an handler to make it work with a transformer AWS Lambda.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description | | --- | --- | --- | --- | | services | Object | | The services the wrapper depends on | | services.ENV | Object | | The process environment | | services.OPERATION_API | Object | | An OpenAPI definitition for that handler | | services.apm | Object | | An application monitoring service | | [services.time] | Object | | An optional time service | | [services.log] | Object | noop | An optional logging service |