@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 WhookGCPFunctionBuildConfig,
+    type WhookGCPFunctionRouteConfig
+ } from '@whook/gcp-functions';

declare module 'application-services' {

  // ...

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

  // ...
}

// ...

declare module '@whook/whook' {
  export interface WhookRouteConfig
    extends WhookBaseRouteConfig,
+      WhookGCPFunctionRouteConfig,
      WhookCORSRouteConfig {}
}

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: '22',
+  },
};

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 testGCPFunctionRoute one:

npx whook testGCPFunctionRoute --name getPing

To get more insights when some errors happens:

DEBUG=whook npm run dev -- testGCPFunctionRoute --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

initWrapRouteHandlerForGoogleHTTPFunction(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.MAIN_DEFINITION	Object		An OpenAPI definitition for that handler
services.DECODERS	Object		Request body decoders available
services.ENCODERS	Object		Response body encoders available
services.PARSERS	Object		Request body parsers available
services.STRINGIFIERS	Object		Response body stringifiers available
services.BUFFER_LIMIT	Object		The buffer size limit
services.queryParserBuilder	Object		A query parser builder from OpenAPI parameters
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

Authors

• Nicolas Froidure

License

MIT