feat(@whook/example): add Google Cloud Functions build

Author: nfroidure

package-lock.json

@@ -129,6 +129,7 @@ DEV_MODE=1
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "<current_version>",
     "@whook/cors": "<current_version>",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/swagger-ui": "<current_version>",
     "@whook/whook": "<current_version>",
     "application-services": "^7.0.2",
@@ -140,6 +141,7 @@ DEV_MODE=1
     "ya-json-schema-types": "^1.0.1",
     "ya-open-api-types": "^1.2.0",
     "pkg-dir": "^8.0.0",
+    "js-yaml": "^4.1.0",
     "strict-qs": "^8.0.3",
     "type-fest": "^4.33.0",
     "yerror": "^8.0.0",
@@ -437,6 +439,7 @@ DEV_MODE=1
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "<current_version>",
     "@whook/cors": "<current_version>",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/swagger-ui": "<current_version>",
     "@whook/whook": "<current_version>",
     "application-services": "^7.0.2",
@@ -448,6 +451,7 @@ DEV_MODE=1
     "ya-json-schema-types": "^1.0.1",
     "ya-open-api-types": "^1.2.0",
     "pkg-dir": "^8.0.0",
+    "js-yaml": "^4.1.0",
     "strict-qs": "^8.0.3",
     "type-fest": "^4.33.0",
     "yerror": "^8.0.0",
@@ -783,6 +787,7 @@ DEV_MODE=1
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "<current_version>",
     "@whook/cors": "<current_version>",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/swagger-ui": "<current_version>",
     "@whook/whook": "<current_version>",
     "application-services": "^7.0.2",
@@ -794,6 +799,7 @@ DEV_MODE=1
     "ya-json-schema-types": "^1.0.1",
     "ya-open-api-types": "^1.2.0",
     "pkg-dir": "^8.0.0",
+    "js-yaml": "^4.1.0",
     "strict-qs": "^8.0.3",
     "type-fest": "^4.33.0",
     "yerror": "^8.0.0",
@@ -1112,6 +1118,7 @@ DEV_MODE=1
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "<current_version>",
     "@whook/cors": "<current_version>",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/swagger-ui": "<current_version>",
     "@whook/whook": "<current_version>",
     "application-services": "^7.0.2",
@@ -1123,6 +1130,7 @@ DEV_MODE=1
     "ya-json-schema-types": "^1.0.1",
     "ya-open-api-types": "^1.2.0",
     "pkg-dir": "^8.0.0",
+    "js-yaml": "^4.1.0",
     "strict-qs": "^8.0.3",
     "type-fest": "^4.33.0",
     "yerror": "^8.0.0",

packages/whook-create/src/services/__snapshots__/createWhook.test.ts.snap

@@ -161,6 +161,7 @@ describe('initCreateWhook', () => {
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "<current_version>",
     "@whook/cors": "<current_version>",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/http-router": "<current_version>",
     "@whook/http-server": "<current_version>",
     "@whook/http-transaction": "<current_version>",
@@ -169,6 +170,7 @@ describe('initCreateWhook', () => {
     "application-services": "^7.0.2",
     "common-services": "^17.0.1",
     "http-auth-utils": "^6.0.1",
+    "js-yaml": "^4.1.0",
     "jwt-service": "^11.0.2",
     "knifecycle": "^19.0.0",
     "node-cron": "^3.0.3",
@@ -357,6 +359,7 @@ describe('initCreateWhook', () => {
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "<current_version>",
     "@whook/cors": "<current_version>",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/http-router": "<current_version>",
     "@whook/http-server": "<current_version>",
     "@whook/http-transaction": "<current_version>",
@@ -365,6 +368,7 @@ describe('initCreateWhook', () => {
     "application-services": "^7.0.2",
     "common-services": "^17.0.1",
     "http-auth-utils": "^6.0.1",
+    "js-yaml": "^4.1.0",
     "jwt-service": "^11.0.2",
     "knifecycle": "^19.0.0",
     "node-cron": "^3.0.3",
@@ -538,6 +542,7 @@ describe('initCreateWhook', () => {
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "<current_version>",
     "@whook/cors": "<current_version>",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/http-router": "<current_version>",
     "@whook/http-server": "<current_version>",
     "@whook/http-transaction": "<current_version>",
@@ -546,6 +551,7 @@ describe('initCreateWhook', () => {
     "application-services": "^7.0.2",
     "common-services": "^17.0.1",
     "http-auth-utils": "^6.0.1",
+    "js-yaml": "^4.1.0",
     "jwt-service": "^11.0.2",
     "knifecycle": "^19.0.0",
     "node-cron": "^3.0.3",

packages/whook-create/src/services/createWhook.test.ts

@@ -259,7 +259,7 @@ Per convention a Whook server build file must export
 The `runBuild` function is intended to build the
  project.
 
-[See in context](./src/build.ts#L15-L19)
+[See in context](./src/build.ts#L17-L21)
 
 
 
@@ -268,7 +268,7 @@ The `runBuild` function is intended to build the
 The `prepareBuildEnvironment` create the build
  environment
 
-[See in context](./src/build.ts#L27-L31)
+[See in context](./src/build.ts#L29-L33)
 
 
 
@@ -288,15 +288,15 @@ The `src/config/common/config.ts` one allows to add common
 
 Whook provides several types you may extend here.
 
-[See in context](./src/whook.d.ts#L26-L29)
+[See in context](./src/whook.d.ts#L31-L34)
 
 
 
 #### 2.1.1. AppEnvVars
 
 The process environment can be typed by extending this type.
 
-[See in context](./src/whook.d.ts#L32-L35)
+[See in context](./src/whook.d.ts#L37-L40)
 
 
 
@@ -305,7 +305,7 @@ The process environment can be typed by extending this type.
 The configuration is typed so that you are sure you cannot
  produce a bad configuration for your API.
 
-[See in context](./src/whook.d.ts#L43-L47)
+[See in context](./src/whook.d.ts#L48-L52)
 
 
 
@@ -315,15 +315,15 @@ Here we export a custom API handler config type in order
  to allow using the various plugins installed that deal
  with the routes.
 
-[See in context](./src/whook.d.ts#L59-L64)
+[See in context](./src/whook.d.ts#L67-L72)
 
 
 
 #### 2.1.3. WhookMain
 
 Here we export a main config to type AppEnv.
 
-[See in context](./src/whook.d.ts#L70-L73)
+[See in context](./src/whook.d.ts#L79-L82)
 
 
 
@@ -534,7 +534,7 @@ Here we export a custom API handler config type in order
  to allow using the various plugins installed that deal
  with the routes.
 
-[See in context](./src/whook.d.ts#L81-L86)
+[See in context](./src/whook.d.ts#L90-L95)
 
 
 

packages/whook-example/ARCHITECTURE.md

@@ -102,6 +102,64 @@ Debug `knifecycle` internals (dependency injection issues):
 DEBUG=knifecycle npm run dev
 ```
 
+## Deploying with Google Cloud Functions
+
+Create a project and save its credentials to `.credentials.json`.
+
+Then install Terraform:
+```sh
+wget https://releases.hashicorp.com/terraform/0.12.24/terraform_0.12.24_linux_amd64.zip
+mkdir .bin
+unzip -d .bin terraform_0.12.24_linux_amd64.zip
+rm terraform_0.12.24_linux_amd64.zip
+```
+
+Then initialize the Terraform configuration:
+```sh
+.bin/terraform init ./terraform;
+```
+
+Create a new workspace:
+```sh
+.bin/terraform workspace new staging
+```
+
+Build the functions:
+```sh
+NODE_ENV=staging npm run build
+```
+
+Build the Whook commands Terraform depends on:
+```sh
+npm run compile
+```
+
+Plan the deployment:
+```sh
+.bin/terraform plan -var="project_id=my-project-1664" \
+ -out=terraform.plan terraform
+```
+
+Apply changes:
+```sh
+# parallelism may be necessary to avoid hitting
+#  timeouts with a slow connection
+.bin/terraform apply -parallelism=1 terraform.plan
+```
+
+Finally retrieve the API URL and enjoy!
+```sh
+.bin/terraform -var="project_id=my-project-1664" \
+ output api_url
+```
+
+## Testing the GCP Functions
+
+```sh
+JWT_SECRET=lol APP_ENV=local npm run dev -- testGCPFunctionRoute \
+ --name putEcho --parameters '{ "body": { "echo": "Hey!" } }'
+```
+
 [//]: # (::contents:end)
 
 # Authors

packages/whook-example/README.md

@@ -81,6 +81,7 @@
     "@types/node-cron": "^3.0.11",
     "@whook/authorization": "^18.1.0",
     "@whook/cors": "^18.1.0",
+    "@whook/gcp-functions": "^18.1.0",
     "@whook/swagger-ui": "^18.1.0",
     "@whook/whook": "^18.1.0",
     "application-services": "^7.0.2",
@@ -92,6 +93,7 @@
     "ya-json-schema-types": "^1.0.1",
     "ya-open-api-types": "^1.2.0",
     "pkg-dir": "^8.0.0",
+    "js-yaml": "^4.1.0",
     "strict-qs": "^8.0.3",
     "type-fest": "^4.33.0",
     "yerror": "^8.0.0",

packages/whook-example/package.json

@@ -0,0 +1,47 @@
+import { describe, beforeAll, test } from '@jest/globals';
+import { exec } from 'child_process';
+import { YError } from 'yerror';
+
+describe('build should work', () => {
+  let env = 'JWT_SECRET=test ';
+
+  beforeAll(async () => {
+    const { stdout } = await execCommand(
+      `sed -e 's/^//' .env.${process.env.NODE_ENV} || echo ""`,
+    );
+
+    env += stdout.trim();
+  });
+
+  [
+    ['getPing', '{}'],
+    ['getOpenAPI', '{}'],
+    [
+      'getParameters',
+      '{ "aHeader": "true", "pathParam1":"4", "pathParam2":"a,b,c,d" }',
+    ],
+    ['getTime', '{}'],
+    ['getDelay', '{ "duration": 1 }'],
+    ['putEcho', '{"body": { "echo": "YOLO!" }}'],
+  ].forEach(([operationId, parameters]) => {
+    test(`with ${operationId} route functions`, async () => {
+      await execCommand(
+        `${env} npx whook testGCPFunctionRoute --name ${operationId} --parameters '${parameters}'`,
+      );
+    });
+  });
+});
+
+async function execCommand(
+  command,
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    exec(command, (err, stdout, stderr) => {
+      if (err) {
+        reject(YError.wrap(err, 'E_COMMAND_FAILURE', stdout, stderr));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}

packages/whook-example/src/build.test.ts

@@ -8,9 +8,11 @@ import { prepareEnvironment } from './index.js';
 import {
   DEFAULT_BUILD_INITIALIZER_PATH_MAP,
   initBuildConstants,
+} from '@whook/whook';
+import {
   runBuild as runBaseBuild,
   prepareBuildEnvironment as prepareBaseBuildEnvironment,
-} from '@whook/whook';
+} from '@whook/gcp-functions';
 
 /* Architecture Note #1.2.1: The `runBuild` function
 
@@ -56,7 +58,7 @@ export async function prepareBuildEnvironment<T extends Knifecycle>(
 
   // Finally, some constants can be serialized instead of being
   //  initialized in the target build saving some time at boot
-  $.register(alsoInject([], initBuildConstants));
+  $.register(alsoInject(['DEFINITIONS'], initBuildConstants));
 
   return $;
 }

packages/whook-example/src/build.ts

@@ -23,8 +23,9 @@ On air 🚀🌕
 ",
   "stdout": "
 
-# Provided by "@whook/example": 1 commands
+# Provided by "@whook/example": 2 commands
 - printEnv: A command printing every env values
+- terraformValues: A command printing functions informations for Terraform
 
 
 # Provided by "@whook/whook": 7 commands
@@ -37,6 +38,10 @@ On air 🚀🌕
 - route: Runs the given server route for testing purpose
 
 
+# Provided by "@whook/gcp-functions": 1 commands
+- testGCPFunctionRoute: A command for testing a GCP function route
+
+
 # Provided by "@whook/cors": none