@causa/workspace-google 0.2.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/google-app-check-generate-token.js

@@ -21,7 +21,7 @@ const TOKEN_TTL = 3600;
 /**
  * Generates a new AppCheck token.
  */
-let GoogleAppCheckGenerateToken = class GoogleAppCheckGenerateToken extends WorkspaceFunction {
+export let GoogleAppCheckGenerateToken = class GoogleAppCheckGenerateToken extends WorkspaceFunction {
     /**
      * The ID of the Firebase app for which the token will be generated.
      * If `undefined`, a Firebase app ID will be found in the configuration or using the API.
@@ -64,4 +64,3 @@ If the Firebase app ID is not specified, it will:
         outputFn: (token) => console.log(token),
     })
 ], GoogleAppCheckGenerateToken);
-export { GoogleAppCheckGenerateToken };

package/dist/functions/google-firebase-storage-merge-rules.js

@@ -27,7 +27,7 @@ const DEFAULT_FIREBASE_STORAGE_SECURITY_RULE_FILE = 'storage.rules';
  * Returns a configuration with `google.firebaseStorage.securityRuleFile` set, such that the function can be used as a
  * processor.
  */
-let GoogleFirebaseStorageMergeRules = class GoogleFirebaseStorageMergeRules extends WorkspaceFunction {
+export let GoogleFirebaseStorageMergeRules = class GoogleFirebaseStorageMergeRules extends WorkspaceFunction {
     tearDown;
     async _call(context) {
         if (this.tearDown) {
@@ -69,4 +69,3 @@ Input files are looked for in the workspace using the globs defined in google.fi
         outputFn: ({ securityRuleFile }) => console.log(securityRuleFile),
     })
 ], GoogleFirebaseStorageMergeRules);
-export { GoogleFirebaseStorageMergeRules };

package/dist/functions/google-firestore-merge-rules.js

@@ -27,7 +27,7 @@ const DEFAULT_FIRESTORE_SECURITY_RULE_FILE = 'firestore.rules';
  * Returns a configuration with `google.firestore.securityRuleFile` set, such that the function can be used as a
  * processor.
  */
-let GoogleFirestoreMergeRules = class GoogleFirestoreMergeRules extends WorkspaceFunction {
+export let GoogleFirestoreMergeRules = class GoogleFirestoreMergeRules extends WorkspaceFunction {
     tearDown;
     async _call(context) {
         if (this.tearDown) {
@@ -69,4 +69,3 @@ Input files are looked for in the workspace using the globs defined in google.fi
         outputFn: ({ securityRuleFile }) => console.log(securityRuleFile),
     })
 ], GoogleFirestoreMergeRules);
-export { GoogleFirestoreMergeRules };

package/dist/functions/google-identity-platform-generate-token.js

@@ -21,7 +21,7 @@ import { GoogleIdentityPlatformGenerateCustomToken } from './google-identity-pla
  * For this function to succeed, the `google.project` should be set, which usually means setting the environment in the
  * context. Also `google.firebase` children can be used to configure (and speed up) how tokens are generated.
  */
-let GoogleIdentityPlatformGenerateToken = class GoogleIdentityPlatformGenerateToken extends WorkspaceFunction {
+export let GoogleIdentityPlatformGenerateToken = class GoogleIdentityPlatformGenerateToken extends WorkspaceFunction {
     /**
      * The ID of the user for which the token will be generated.
      */
@@ -71,4 +71,3 @@ Optional custom claims can be included in the signed token.`,
         outputFn: (token) => console.log(token),
     })
 ], GoogleIdentityPlatformGenerateToken);
-export { GoogleIdentityPlatformGenerateToken };

package/dist/functions/google-services-enable.js

@@ -20,7 +20,7 @@ const MAX_SERVICE_BATCH = 20;
 /**
  * Enables GCP services defined in `google.services` for the GCP project defined in `google.project`.
  */
-let GoogleServicesEnable = class GoogleServicesEnable extends WorkspaceFunction {
+export let GoogleServicesEnable = class GoogleServicesEnable extends WorkspaceFunction {
     tearDown;
     async _call(context) {
         if (this.tearDown) {
@@ -72,4 +72,3 @@ They will be enabled in the 'google.project' GCP project.`,
         outputFn: ({ services }) => console.log(services.join('\n')),
     })
 ], GoogleServicesEnable);
-export { GoogleServicesEnable };

package/dist/functions/index.js

@@ -15,8 +15,10 @@ import { GoogleIdentityPlatformGenerateCustomToken } from './google-identity-pla
 import { GoogleIdentityPlatformGenerateToken } from './google-identity-platform-generate-token.js';
 import { GoogleServicesEnable } from './google-services-enable.js';
 import { GoogleSpannerListDatabases } from './google-spanner-list-databases.js';
-import { ProjectGetArtefactDestinationForServiceContainer } from './project-get-artefact-destination-service-container.js';
+import { ProjectGetArtefactDestinationForCloudFunctions } from './project-get-artefact-destination-cloud-functions.js';
+import { ProjectGetArtefactDestinationForCloudRun } from './project-get-artefact-destination-cloud-run.js';
+import { ProjectPushArtefactForCloudFunctions } from './project-push-artefact-cloud-functions.js';
 import { SecretFetchForGoogleSecretManager } from './secret-fetch-secret-manager.js';
 export function registerFunctions(context) {
-    context.registerFunctionImplementations(EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, GoogleAppCheckGenerateToken, GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, GoogleServicesEnable, GoogleSpannerListDatabases, ProjectGetArtefactDestinationForServiceContainer, SecretFetchForGoogleSecretManager);
+    context.registerFunctionImplementations(EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, GoogleAppCheckGenerateToken, GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, GoogleServicesEnable, GoogleSpannerListDatabases, ProjectGetArtefactDestinationForCloudFunctions, ProjectGetArtefactDestinationForCloudRun, ProjectPushArtefactForCloudFunctions, SecretFetchForGoogleSecretManager);
 }

package/dist/functions/project-get-artefact-destination-cloud-functions.d.ts

@@ -0,0 +1,11 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { ProjectGetArtefactDestination } from '@causa/workspace-core';
+/**
+ * Implements the {@link ProjectGetArtefactDestination} function for Cloud Functions projects.
+ * Cloud Functions archives are stored in a Google Cloud Storage bucket, the destination of which must be
+ * defined in the `google.cloudFunctions.archivesStorageLocation` configuration.
+ */
+export declare class ProjectGetArtefactDestinationForCloudFunctions extends ProjectGetArtefactDestination {
+    _call(context: WorkspaceContext): Promise<string>;
+    _supports(context: WorkspaceContext): boolean;
+}

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

@@ -0,0 +1,20 @@
+import { ProjectGetArtefactDestination, } from '@causa/workspace-core';
+/**
+ * Implements the {@link ProjectGetArtefactDestination} function for Cloud Functions projects.
+ * Cloud Functions archives are stored in a Google Cloud Storage bucket, the destination of which must be
+ * defined in the `google.cloudFunctions.archivesStorageLocation` configuration.
+ */
+export class ProjectGetArtefactDestinationForCloudFunctions extends ProjectGetArtefactDestination {
+    async _call(context) {
+        const projectName = context.getOrThrow('project.name');
+        const archivesStorageLocation = context
+            .asConfiguration()
+            .getOrThrow('google.cloudFunctions.archivesStorageLocation');
+        return `${archivesStorageLocation}/${projectName}/${this.tag}.zip`;
+    }
+    _supports(context) {
+        const conf = context.asConfiguration();
+        return (conf.get('project.type') === 'serverlessFunctions' &&
+            conf.get('serverlessFunctions.platform') === 'google.cloudFunctions');
+    }
+}

package/dist/functions/{project-get-artefact-destination-service-container.d.ts → project-get-artefact-destination-cloud-run.d.ts}

@@ -4,7 +4,7 @@ import { ProjectGetArtefactDestination } from '@causa/workspace-core';
  * Implements the {@link ProjectGetArtefactDestination} function for Cloud Run services.
  * The destination Docker repository is expected to be defined in `google.cloudRun.dockerRepository`.
  */
-export declare class ProjectGetArtefactDestinationForServiceContainer extends ProjectGetArtefactDestination {
+export declare class ProjectGetArtefactDestinationForCloudRun extends ProjectGetArtefactDestination {
     _call(context: WorkspaceContext): Promise<string>;
     _supports(context: WorkspaceContext): boolean;
 }

package/dist/functions/{project-get-artefact-destination-service-container.js → project-get-artefact-destination-cloud-run.js}

@@ -3,10 +3,12 @@ import { ProjectGetArtefactDestination, } from '@causa/workspace-core';
  * Implements the {@link ProjectGetArtefactDestination} function for Cloud Run services.
  * The destination Docker repository is expected to be defined in `google.cloudRun.dockerRepository`.
  */
-export class ProjectGetArtefactDestinationForServiceContainer extends ProjectGetArtefactDestination {
+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/functions/project-push-artefact-cloud-functions.d.ts

@@ -0,0 +1,11 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { ProjectPushArtefact } from '@causa/workspace-core';
+/**
+ * Implements the {@link ProjectPushArtefact} function for Cloud Functions projects.
+ * This copies the local archive of the Cloud Functions project to the Google Cloud Storage URI set in
+ * {@link ProjectPushArtefact.destination}.
+ */
+export declare class ProjectPushArtefactForCloudFunctions extends ProjectPushArtefact {
+    _call(context: WorkspaceContext): Promise<string>;
+    _supports(context: WorkspaceContext): boolean;
+}

package/dist/functions/project-push-artefact-cloud-functions.js

@@ -0,0 +1,31 @@
+import { ArtefactAlreadyExistsError, ProjectPushArtefact, } from '@causa/workspace-core';
+import { rm } from 'fs/promises';
+import { CloudStorageService } from '../services/index.js';
+/**
+ * Implements the {@link ProjectPushArtefact} function for Cloud Functions projects.
+ * This copies the local archive of the Cloud Functions project to the Google Cloud Storage URI set in
+ * {@link ProjectPushArtefact.destination}.
+ */
+export class ProjectPushArtefactForCloudFunctions extends ProjectPushArtefact {
+    async _call(context) {
+        context.logger.info(`🚚 Pushing Cloud Functions archive to Cloud Storage.`);
+        const storageService = context.service(CloudStorageService);
+        const destination = storageService.getFileFromGsUri(this.destination);
+        if (!this.overwrite) {
+            const [exists] = await destination.exists();
+            if (exists) {
+                throw new ArtefactAlreadyExistsError(this.destination);
+            }
+        }
+        await destination.bucket.upload(this.artefact, { destination });
+        context.logger.info(`🚚 Successfully pushed archive to '${this.destination}'.`);
+        context.logger.debug(`🔥 Removing local artefact '${this.artefact}'.`);
+        await rm(this.artefact);
+        return this.destination;
+    }
+    _supports(context) {
+        const conf = context.asConfiguration();
+        return (conf.get('project.type') === 'serverlessFunctions' &&
+            conf.get('serverlessFunctions.platform') === 'google.cloudFunctions');
+    }
+}

package/dist/services/index.d.ts

@@ -4,3 +4,5 @@ export { FirebaseEmulatorService } from './firebase-emulator.js';
 export { GcloudEmulatorService } from './gcloud-emulator.js';
 export { GoogleApisService } from './google-apis.js';
 export { GoogleSecretManagerService } from './secret-manager.js';
+export * from './storage.errors.js';
+export { CloudStorageService } from './storage.js';

package/dist/services/index.js

@@ -4,3 +4,5 @@ export { FirebaseEmulatorService } from './firebase-emulator.js';
 export { GcloudEmulatorService } from './gcloud-emulator.js';
 export { GoogleApisService } from './google-apis.js';
 export { GoogleSecretManagerService } from './secret-manager.js';
+export * from './storage.errors.js';
+export { CloudStorageService } from './storage.js';

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/dist/services/storage.d.ts

@@ -0,0 +1,33 @@
+import { File, Storage } from '@google-cloud/storage';
+/**
+ * A service for interacting with Google Cloud Storage.
+ * It exposes a singleton instance of the Google Cloud Storage client.
+ */
+export declare class CloudStorageService {
+    readonly storage: Storage;
+    constructor();
+    /**
+     * Parses a Google Cloud Storage URI into a bucket and path.
+     * Cloud Storage URIs are of the form `gs://<bucket>/<path>`.
+     *
+     * @param uri The Google Cloud Storage URI.
+     * @returns The name of the Google Cloud Storage bucket and the path within the bucket.
+     */
+    parseGsUri(uri: string): {
+        /**
+         * The name of the Google Cloud Storage bucket.
+         */
+        readonly bucket: string;
+        /**
+         * The path within the bucket.
+         */
+        readonly path: string;
+    };
+    /**
+     * Parses a Google Cloud Storage URI into a {@link File}.
+     *
+     * @param uri The Google Cloud Storage URI.
+     * @returns The {@link File} at the given URI.
+     */
+    getFileFromGsUri(uri: string): File;
+}

package/dist/services/storage.errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * An error thrown when the Cloud Storage URI is invalid.
+ * Cloud Storage URIs are of the form `gs://<bucket>/<path>`.
+ */
+export declare class InvalidCloudStorageUriError extends Error {
+    readonly uri: string;
+    constructor(uri: string);
+}

package/dist/services/storage.errors.js

@@ -0,0 +1,11 @@
+/**
+ * An error thrown when the Cloud Storage URI is invalid.
+ * Cloud Storage URIs are of the form `gs://<bucket>/<path>`.
+ */
+export class InvalidCloudStorageUriError extends Error {
+    uri;
+    constructor(uri) {
+        super(`Invalid Google Cloud Storage URI: '${uri}'.`);
+        this.uri = uri;
+    }
+}

package/dist/services/storage.js

@@ -0,0 +1,36 @@
+import { Storage } from '@google-cloud/storage';
+import { InvalidCloudStorageUriError } from './storage.errors.js';
+/**
+ * A service for interacting with Google Cloud Storage.
+ * It exposes a singleton instance of the Google Cloud Storage client.
+ */
+export class CloudStorageService {
+    storage;
+    constructor() {
+        this.storage = new Storage();
+    }
+    /**
+     * Parses a Google Cloud Storage URI into a bucket and path.
+     * Cloud Storage URIs are of the form `gs://<bucket>/<path>`.
+     *
+     * @param uri The Google Cloud Storage URI.
+     * @returns The name of the Google Cloud Storage bucket and the path within the bucket.
+     */
+    parseGsUri(uri) {
+        const match = uri.match(/^gs:\/\/([^/]+)\/(.*)$/);
+        if (!match) {
+            throw new InvalidCloudStorageUriError(uri);
+        }
+        return { bucket: match[1], path: match[2] };
+    }
+    /**
+     * Parses a Google Cloud Storage URI into a {@link File}.
+     *
+     * @param uri The Google Cloud Storage URI.
+     * @returns The {@link File} at the given URI.
+     */
+    getFileFromGsUri(uri) {
+        const { bucket, path } = this.parseGsUri(uri);
+        return this.storage.bucket(bucket).file(path);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/workspace-google",
-  "version": "0.2.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,19 @@
     "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.4.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.6.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.0",
+    "@google-cloud/spanner": "^6.11.0",
+    "@google-cloud/storage": "^6.11.0",
     "class-validator": "^0.14.0",
-    "firebase": "^9.22.0",
-    "firebase-admin": "^11.8.0",
+    "firebase": "^9.22.2",
+    "firebase-admin": "^11.9.0",
     "globby": "^13.1.4",
     "google-gax": "^3.6.0",
     "googleapis": "^118.0.0",
@@ -48,18 +49,19 @@
   },
   "devDependencies": {
     "@tsconfig/node18": "^2.0.1",
-    "@types/jest": "^29.5.1",
-    "@types/node": "^18.16.14",
-    "@types/uuid": "^9.0.1",
+    "@types/jest": "^29.5.2",
+    "@types/node": "^18.16.16",
+    "@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",
-    "typescript": "^5.0.4"
+    "typescript": "^5.1.3"
   }
 }