@whook/gcp-functions NPM

@whook/gcp-functions

Build and deploy to GCP Cloud Functions with Whook.

This module is aimed to help you to build and deploy your Whook server to Google Cloud Functions.

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

Quick setup

Install this module:

npm i @whook/gcp-functions;

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

  // ...

  $.register(
    constant('WHOOK_PLUGINS', [
      ...WHOOK_DEFAULT_PLUGINS,
+      '@whook/gcp-functions',
      '@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/gcp-functions';

// (...)

// 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 GCP 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 {
+    WhookGCPBuildConfig,
+    WhookAPIOperationGCPFunctionConfig
+ } from '@whook/gcp-functions';

declare module 'application-services' {

  // ...

  export interface AppConfig
-    extends WhookBaseConfigs {}
+    extends WhookBaseConfigs,
+      WhookGCPBuildConfig,
+      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 &
+      WhookAPIOperationGCPFunctionConfig &
      WhookAPIOperationCORSConfig
    >;
  }
}

And add the GCP Functions 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 function builds by adding @whook/gcp-functions to your WHOOK_PLUGINS list. It provides you some commands like the testHTTPFunction one:

npx whook testHTTPFunction --name getPing

To get more insights when some errors happens:

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

Deployment

We recommend using Terraform to deploy your 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

initWrapHandlerForGoogleHTTPFunction(services) ⇒ Promise.<Object>

Wrap an handler to make it work with GCP Functions.

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.PARSERS	Object		Request body parsers available
services.STRINGIFYERS	Object		Response body stringifyers available
services.BUFFER_LIMIT	Object		The buffer size limit
services.QUERY_PARSER	Object		The query parser to use
services.obfuscator	Object		A service to hide sensible values
services.errorHandler	Object		A service that changes any error to Whook response
services.log	Object	noop	An optional logging service