@causa/workspace-google 0.3.0 → 0.3.1

package/README.md

@@ -1 +1,116 @@
 # `@causa/workspace-google` module
+
+This repository contains the source code for the `@causa/workspace-google` Causa module. It provides many GCP-related utilities and implementations for `cs` commands. For more information about the Causa CLI `cs`, checkout [its repository](https://github.com/causa-io/cli).
+
+## ➕ Requirements
+
+The Google module requires [Docker](https://www.docker.com/) in order to run local emulators of GCP services.
+
+Although not required, the [`gcloud`](https://cloud.google.com/sdk/gcloud) CLI might be useful, e.g. to set up credentials that will be used by the Causa Google module.
+
+## 🎉 Installation
+
+Add `@causa/workspace-google` to your Causa configuration in `causa.modules`.
+
+## 🔧 Configuration
+
+For all the Google-related configuration in your Causa files, look at [the schema for the `GoogleConfiguration`](./src/configurations/google.ts).
+
+## ✨ Supported project types and commands
+
+### Project types
+
+The following Causa `project.type`s are supported:
+
+- `serviceContainer`, with `google.cloudRun` as the `serviceContainer.platform`. This will ensure the built Docker images are pushed to the repository set in `google.cloudRun.dockerRepository`.
+- `serverlessFunctions`, with `google.cloudFunctions` as the `serverlessFunctions.platform`. This will push functions archives to the Cloud Storage bucket set in `google.cloudFunctions.archivesStorageLocation`.
+
+### Emulators
+
+The following emulators are implemented:
+
+- `google.firebaseStorage`: The Firebase Storage emulator from the Firebase tools. It supports setting the corresponding security rules. See the `cs google firebaseStorage mergeRules` documentation for more details.
+- `google.firestore`: The Firestore emulator from the `gcloud` tools. If supports setting the corresponding security rules. See the `cs google firestore mergeRules` documentation for more details.
+- `google.identityPlatform`: The Identity Platform (Firebase Auth) emulator from the Firebase tools.
+- `google.pubSub`: The Pub/Sub emulator from the `gcloud` tools. It automatically creates the topics for all event topics found in the Causa workspace. `events.broker` must be set to `google.pubSub` for this.
+- `google.spanner`: The Spanner emulator. It automatically creates all the Spanner databases defined in the Causa workspace, and sets up their DDLs. See the `google.spanner` [configuration](./src/configurations/google.ts) for more details.
+
+### Secrets backend
+
+This module implements the `google.secretManager` secret backend, allowing fetching secrets from the Google Secret Manager service. Here are some example of how secrets with the `google.secretManager` backend should be defined:
+
+```yaml
+secrets:
+  simpleSecret:
+    id: simple-secret
+  secretWithProject:
+    id: projects/gcp-project/secrets/my-secret
+  secretWithVersion:
+    id: projects/gcp-project/secrets/my-secret/versions/12
+```
+
+When the GCP project is not specified in the secret ID, it is inferred from `google.secretManager.project`, or `google.project` (in this order). This allows defining the GCP project a single time if needed.
+
+## 🔨 Custom `google` commands
+
+This modules adds a new command to the CLI: `cs google`. Here is the list of subcommands that are exposed.
+
+### App Check
+
+The `cs google appCheck genToken` command generates an App Check token, which can be used to authenticate calls to APIs that are protected by Firebase App Check.
+
+A token is generated for a specific Firebase application. This can be set using the `-a, --app <app>` argument. If it is not set, any Firebase application will be selected automatically using the Firebase API.
+
+An App Check token must be signed using an admin service account in the same project as the app. Firebase automatically creates such an account when it is initialized from a GCP project. This command can take care of automatically finding this account. However, if you want to save on API calls, the email for any service account with Firebase admin permissions can be set in `google.firebase.adminServiceAccount`.
+
+### Enable services
+
+The `cs google enableServices` command will enable all the GCP services defined in `google.services`. This command is also exposed as an infrastructure processors, under the name `GoogleServicesEnable`.
+
+### Firebase Storage
+
+The `cs google firebaseStorage mergeRules` command merges several Firebase security rules files together into a single file that can be used as configuration for both the Firebase Storage emulator, and the Firebase Storage production service.
+
+Input files are found using the glob patterns defined in `google.firebaseStorage.securityRuleFiles`. Input files should not include the header, i.e. they should defined what is **inside**:
+
+```
+rules_version = '2';
+
+service firebase.storage {
+  match /b/{bucket}/o {
+    // Only include what is inside those brackets.
+  }
+}
+```
+
+The output Firebase security rules file can be set in `google.firebaseStorage.securityRuleFile`.
+
+### Firestore
+
+The `cs google firestore mergeRules` command merges several Firebase security rules files together into a single file that can be used as configuration for both the Firestore emulator, and the Firestore production service.
+
+This command is extremely similar to `cs google firebaseStorage mergeRules`. Input files are defined in `google.firestore.securityRuleFiles`, and the output file is defined in `google.firestore.securityRuleFile`.
+
+### Identity Platform
+
+The `cs google identityPlatform genToken` command generates an Identity Platform (formerly Firebase Auth) ID token, which can be used to authenticate calls to API protected by Identity Platform.
+
+This command is similar to `cs google appCheck genToken` in that it requires a service account with Firebase admin permissions to sign the token. See the corresponding command for more information.
+
+## 🧱 Infrastructure processors
+
+The Google module provides several infrastructure processors, which can be used to set up the Causa workspace before running infrastructure-related operations.
+
+### `GoogleFirebaseStorageMergeRules`
+
+[GoogleFirebaseStorageMergeRules](./src/functions/google-firebase-storage-merge-rules.ts) is the same underlying function as the `cs google firebaseStorage mergeRules` command. It allows preparing the Firebase Storage security rules before possibly deploying them along with the infrastructure. See the corresponding command for more details.
+
+### `GoogleFirestoreMergeRules`
+
+[GoogleFirestoreMergeRules](./src/functions/google-firestore-merge-rules.ts) is the same underlying function as the `cs google firestore mergeRules` command. It allows preparing the Firestore security rules before possibly deploying them along with the infrastructure. See the corresponding command for more details.
+
+### `GoogleServicesEnable`
+
+[GoogleServicesEnable](./src/functions/google-services-enable.ts) is the same underlying function as the `cs google enableServices` command. It enables GCP services before preparing or deploying the infrastructure.
+
+Although infrastructure as code tools usually expose this feature as well (e.g. the [`google_project_service`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_project_service) Terraform resource), it might be more convenient to enable all the required services before running those tools. It avoids having to define dependencies between the services and all the actual resources being deployed.

package/dist/configurations/google.d.ts

@@ -5,35 +5,35 @@ export type GoogleConfiguration = {
     /**
      * Configuration for everything Google / GCP-related.
      */
-    google?: {
+    readonly google?: {
         /**
          * The ID of the default GCP project used when performing operations.
          */
-        project?: string;
+        readonly project?: string;
         /**
          * The ID of a local GCP project (which does not exist on GCP).
          * This is for example used by emulators. It should usually start with `demo-` to be compatible with some emulators.
          */
-        localProject?: string;
+        readonly localProject?: string;
         /**
          * The list of GCP services on which the project depends.
          * This is useful to automatically enable those services in the GCP project.
          */
-        services?: string[];
+        readonly services?: string[];
         /**
          * Configuration for the `gcloud` command.
          * This applies to Dockerized calls to `gcloud` using the official `gcloud` Docker image.
          */
-        gcloud?: {
+        readonly gcloud?: {
             /**
              * The version of the `gcloud` command.
              */
-            version?: string;
+            readonly version?: string;
         };
         /**
          * Configuration for the Firebase project.
          */
-        firebase?: {
+        readonly firebase?: {
             /**
              * An existing service account that can be used to sign Identity Platform custom token.
              * Generating custom tokens by signing them using end-user credentials does not work with Identity Platform.
@@ -42,156 +42,174 @@ export type GoogleConfiguration = {
              * If this is not set and is needed by an operation, an attempt will be made to find this service account in the
              * current `google.project`.
              */
-            adminServiceAccount?: string;
+            readonly adminServiceAccount?: string;
             /**
              * The Firebase API key used by clients. Used to perform requests to Firebase as an end user.
              * This can be found in the GCP or Firebase Console.
              * If this is not set and is needed by an operation, an attempt will be made to find the key automatically using
              * the API.
              */
-            apiKey?: string;
+            readonly apiKey?: string;
             /**
              * The Firebase app ID used by clients.
              * This can be found in the Firebase Console. Each platform (Android, iOS, Web) has its own app ID.
              * If this is not set and is needed by an operation, an attempt will be made to find the first eligible app ID
              * using the Firebase API.
              */
-            appId?: string;
+            readonly appId?: string;
             /**
              * The domain name for the project.
              * If not set, this default to `<GCP project>.firebaseapp.com`.
              */
-            authDomain?: string;
+            readonly authDomain?: string;
             /**
              * Configuration for Firebase tools (the CLI).
              * This applies to Dockerized calls to the `firebase` CLI.
              */
-            tools?: {
+            readonly tools?: {
                 /**
                  * The version of the CLI to use.
                  */
-                version?: string;
+                readonly version?: string;
             };
         };
         /**
          * Configuration for the Secret Manager service.
          */
-        secretManager?: {
+        readonly secretManager?: {
             /**
              * The ID of the default GCP project referenced when fetching secrets.
              */
-            project?: string;
+            readonly project?: string;
         };
         /**
          * Configuration for the Firebase Storage service.
          */
-        firebaseStorage?: {
+        readonly firebaseStorage?: {
             /**
              * Configuration for the emulator.
              */
-            emulator?: {
+            readonly emulator?: {
                 /**
                  * The name of the local Docker container running the emulator.
                  */
-                containerName?: string;
+                readonly containerName?: string;
             };
             /**
              * A list of glob patterns to find files in the workspace defining Firebase Storage security rules.
              */
-            securityRuleFiles?: string[];
+            readonly securityRuleFiles?: string[];
             /**
              * The file path, relative to the workspace root, where the merged security rules file is written.
              */
-            securityRuleFile?: string;
+            readonly securityRuleFile?: string;
         };
         /**
          * Configuration for the Identity Platform (formerly Firebase Auth) service.
          */
-        identityPlatform?: {
+        readonly identityPlatform?: {
             /**
              * Configuration for the emulator.
              */
-            emulator?: {
+            readonly emulator?: {
                 /**
                  * The name of the local Docker container running the emulator.
                  */
-                containerName?: string;
+                readonly containerName?: string;
             };
         };
         /**
          * Configuration for the Firestore service.
          */
-        firestore?: {
+        readonly firestore?: {
             /**
              * Configuration for the emulator.
              */
-            emulator?: {
+            readonly emulator?: {
                 /**
                  * The name of the local Docker container running the emulator.
                  */
-                containerName?: string;
+                readonly containerName?: string;
             };
             /**
              * A list of glob patterns to find files in the workspace defining Firestore security rules.
              */
-            securityRuleFiles?: string[];
+            readonly securityRuleFiles?: string[];
             /**
              * The file path, relative to the workspace root, where the merged security rules file is written.
              */
-            securityRuleFile?: string;
+            readonly securityRuleFile?: string;
         };
         /**
          * Configuration for the Pub/Sub service.
          */
-        pubSub?: {
+        readonly pubSub?: {
             /**
              * Configuration for the emulator.
              */
-            emulator?: {
+            readonly emulator?: {
                 /**
                  * The name of the local Docker container running the emulator.
                  */
-                containerName?: string;
+                readonly containerName?: string;
             };
         };
         /**
          * Configuration for the Spanner service.
          */
-        spanner?: {
+        readonly spanner?: {
             /**
              * Configuration for the emulator.
              */
-            emulator?: {
+            readonly emulator?: {
                 /**
                  * The name of the local Docker container running the emulator.
                  */
-                containerName?: string;
+                readonly containerName?: string;
                 /**
                  * The version of the Spanner emulator Docker image to use.
                  */
-                version?: string;
+                readonly version?: string;
                 /**
                  * The name of the Spanner instance that will automatically be created in the emulator.
                  */
-                instanceName?: string;
+                readonly instanceName?: string;
             };
             /**
              * Defines how DDLs are found for the Spanner databases in the workspace.
              */
-            ddls?: {
+            readonly ddls?: {
                 /**
                  * The format string using groups from the regular expression used to make the database names.
                  */
-                format?: string;
+                readonly format?: string;
                 /**
                  * A list of glob patterns used to find SQL files containing DDL statements for the Spanner databases.
                  */
-                globs?: string[];
+                readonly globs?: string[];
                 /**
                  * The regular expression used to extract groups from the SQL file paths.
                  */
-                regularExpression?: string;
+                readonly regularExpression?: string;
             };
         };
+        /**
+         * Configuration for Cloud Functions.
+         */
+        readonly cloudFunctions?: {
+            /**
+             * The Cloud Storage URI where Cloud Functions archives should be uploaded.
+             */
+            readonly archivesStorageLocation?: string;
+        };
+        /**
+         * Configuration for Cloud Run containers.
+         */
+        readonly cloudRun?: {
+            /**
+             * The Docker repository where Cloud Run containers should be uploaded.
+             */
+            readonly dockerRepository?: string;
+        };
     };
 };

package/dist/functions/emulator-start-spanner.js

@@ -98,9 +98,7 @@ export class EmulatorStartForSpanner extends EmulatorStart {
             context.logger.info(`🗃️ Creating Spanner emulator database '${database.id}'.`);
             // Discarding `DROP TABLE` statements as the emulator does not seem to handle them properly.
             const ddls = database.ddls.filter((statement) => !statement.toUpperCase().startsWith('DROP TABLE'));
-            const [_, operation] = await instance.createDatabase(database.id, {
-                schema: ddls,
-            });
+            const operation = (await instance.createDatabase(database.id, { schema: ddls }))[1];
             await operation.promise();
         }));
         return databases.length === 0

package/dist/functions/project-get-artefact-destination-cloud-functions.js

@@ -7,7 +7,9 @@ import { ProjectGetArtefactDestination, } from '@causa/workspace-core';
 export class ProjectGetArtefactDestinationForCloudFunctions extends ProjectGetArtefactDestination {
     async _call(context) {
         const projectName = context.getOrThrow('project.name');
-        const archivesStorageLocation = context.getOrThrow('google.cloudFunctions.archivesStorageLocation');
+        const archivesStorageLocation = context
+            .asConfiguration()
+            .getOrThrow('google.cloudFunctions.archivesStorageLocation');
         return `${archivesStorageLocation}/${projectName}/${this.tag}.zip`;
     }
     _supports(context) {

package/dist/functions/project-get-artefact-destination-cloud-run.js

@@ -6,7 +6,9 @@ import { ProjectGetArtefactDestination, } from '@causa/workspace-core';
 export class ProjectGetArtefactDestinationForCloudRun extends ProjectGetArtefactDestination {
     async _call(context) {
         const projectName = context.getOrThrow('project.name');
-        const dockerRepository = context.getOrThrow('google.cloudRun.dockerRepository');
+        const dockerRepository = context
+            .asConfiguration()
+            .getOrThrow('google.cloudRun.dockerRepository');
         return `${dockerRepository}/${projectName}:${this.tag}`;
     }
     _supports(context) {

package/dist/services/secret-manager.js

@@ -13,9 +13,9 @@ export class GoogleSecretManagerService {
      */
     client;
     constructor(context) {
+        const conf = context.asConfiguration();
         this.defaultProject =
-            context.get('google.secretManager.project') ??
-                context.get('google.project');
+            conf.get('google.secretManager.project') ?? conf.get('google.project');
         this.client = new SecretManagerServiceClient();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/workspace-google",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The Causa workspace module providing many functionalities related to GCP and its services.",
   "repository": "github:causa-io/workspace-module-google",
   "license": "ISC",
@@ -29,18 +29,18 @@
     "test:cov": "npm run test -- --coverage"
   },
   "dependencies": {
-    "@causa/cli": ">= 0.3.3 < 1.0.0",
-    "@causa/workspace": ">= 0.7.0 < 1.0.0",
-    "@causa/workspace-core": ">= 0.6.0 < 1.0.0",
+    "@causa/cli": ">= 0.4.0 < 1.0.0",
+    "@causa/workspace": ">= 0.10.0 < 1.0.0",
+    "@causa/workspace-core": ">= 0.7.0 < 1.0.0",
     "@google-cloud/apikeys": "^0.2.2",
     "@google-cloud/iam-credentials": "^2.0.4",
-    "@google-cloud/pubsub": "^3.7.0",
+    "@google-cloud/pubsub": "^3.7.1",
     "@google-cloud/secret-manager": "^4.2.2",
     "@google-cloud/service-usage": "^2.2.2",
-    "@google-cloud/spanner": "^6.10.1",
-    "@google-cloud/storage": "^6.10.1",
+    "@google-cloud/spanner": "^6.11.0",
+    "@google-cloud/storage": "^6.11.0",
     "class-validator": "^0.14.0",
-    "firebase": "^9.22.1",
+    "firebase": "^9.22.2",
     "firebase-admin": "^11.9.0",
     "globby": "^13.1.4",
     "google-gax": "^3.6.0",
@@ -51,13 +51,14 @@
     "@tsconfig/node18": "^2.0.1",
     "@types/jest": "^29.5.2",
     "@types/node": "^18.16.16",
-    "@types/uuid": "^9.0.1",
+    "@types/uuid": "^9.0.2",
+    "@typescript-eslint/eslint-plugin": "^5.59.9",
     "copyfiles": "^2.4.1",
-    "eslint": "^8.41.0",
+    "eslint": "^8.42.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-prettier": "^4.2.1",
     "jest": "^29.5.0",
-    "jest-extended": "^3.2.4",
+    "jest-extended": "^4.0.0",
     "rimraf": "^5.0.1",
     "ts-jest": "^29.1.0",
     "ts-node": "^10.9.1",