@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