@causa/workspace-google 0.1.1 → 0.3.0

package/dist/services/firebase-app.js

@@ -0,0 +1,286 @@
+import { ApiKeysClient } from '@google-cloud/apikeys';
+import { IAMCredentialsClient } from '@google-cloud/iam-credentials';
+import { initializeApp as initializeAdminApp, } from 'firebase-admin/app';
+import { initializeApp } from 'firebase/app';
+import * as uuid from 'uuid';
+import { FirebaseAdminServiceAccountNotFoundError, FirebaseApiKeyNotFoundError, NoFirebaseAppFoundError, } from './firebase-app.errors.js';
+import { GoogleApisService } from './google-apis.js';
+/**
+ * The types (platforms) of Firebase apps.
+ * Apps are split by type and cannot be listed globally.
+ */
+const FIREBASE_APP_TYPES = ['androidApps', 'iosApps', 'webApps'];
+/**
+ * A string expected to be found in the display name of API keys automatically created by Firebase.
+ */
+const FIREBASE_AUTOMATIC_KEY_INFO = 'auto created by Firebase';
+/**
+ * A service exposing generic Firebase functionalities based on the workspace configuration.
+ */
+export class FirebaseAppService {
+    /**
+     * The GCP project ID read from the {@link WorkspaceContext} configuration.
+     */
+    projectId;
+    /**
+     * The Firebase auth domain, read from the configuration or inferred from the GCP project ID.
+     */
+    authDomain;
+    /**
+     * The logger to use.
+     */
+    logger;
+    /**
+     * The Firebase API key set in the configuration.
+     * This could be `undefined`, in which case {@link FirebaseAppService.findApiKey} will be called.
+     */
+    confApiKey;
+    /**
+     * The Firebase admin service account for the GCP project, read from the configuration.
+     * This could be `undefined`, in which case {@link FirebaseAppService.findAdminServiceAccount} will be called.
+     */
+    confAdminServiceAccount;
+    /**
+     * The Firebase app ID, read from the configuration.
+     * This could be `undefined`, in which case {@link FirebaseAppService.getAnyAppId} will be called.
+     */
+    confAppId;
+    /**
+     * The {@link GoogleApisService} used to make calls to IAM when listing service accounts.
+     */
+    googleApisService;
+    constructor(context) {
+        this.logger = context.logger;
+        this.googleApisService = context.service(GoogleApisService);
+        const googleConf = context.asConfiguration();
+        this.projectId = googleConf.getOrThrow('google.project');
+        this.confApiKey = googleConf.get('google.firebase.apiKey');
+        this.confAdminServiceAccount = googleConf.get('google.firebase.adminServiceAccount');
+        this.confAppId = googleConf.get('google.firebase.appId');
+        this.authDomain =
+            googleConf.get('google.firebase.authDomain') ??
+                `${this.projectId}.firebaseapp.com`;
+    }
+    /**
+     * The promise resolving to the Firebase API key, in the case it wasn't set in the configuration.
+     */
+    apiKeyPromise;
+    /**
+     * Finds a Firebase API key for the configured GCP project by listing them using the API keys API.
+     * The method used to find the correct API key is a hack, relying on the display name of the key.
+     * This is why it is preferable for the API key to be set manually in the configuration.
+     *
+     * @returns A Firebase API key for the configured GCP project.
+     */
+    async findApiKey() {
+        this.logger.debug(`🛂 'google.firebase.apiKey' is not set. Attempting to fetch the key from Google.`);
+        const keysClient = new ApiKeysClient();
+        const parent = `projects/${this.projectId}/locations/global`;
+        let name;
+        for await (const key of keysClient.listKeysAsync({ parent })) {
+            if (key.displayName?.includes(FIREBASE_AUTOMATIC_KEY_INFO) && key.name) {
+                name = key.name;
+                break;
+            }
+        }
+        if (!name) {
+            throw new FirebaseApiKeyNotFoundError(this.projectId);
+        }
+        const [{ keyString }] = await keysClient.getKeyString({ name });
+        if (!keyString) {
+            throw new Error('Unexpected empty key string returned by the API keys API.');
+        }
+        this.logger.debug(`🛂 Found Firebase API key '${name}': '${keyString}'.`);
+        return keyString;
+    }
+    /**
+     * Returns either the Firebase API key set in the configuration, or one found using the Google APIs.
+     *
+     * @returns The Firebase API key.
+     */
+    async getApiKey() {
+        if (this.confApiKey) {
+            return this.confApiKey;
+        }
+        if (!this.apiKeyPromise) {
+            this.apiKeyPromise = this.findApiKey();
+        }
+        return await this.apiKeyPromise;
+    }
+    /**
+     * The singleton {@link FirebaseApp} created by {@link FirebaseAppService.getApp}.
+     */
+    app;
+    /**
+     * Initializes and returns a {@link FirebaseApp} for the configured GCP project.
+     *
+     * @returns The {@link FirebaseApp}.
+     */
+    async getApp() {
+        if (this.app) {
+            return this.app;
+        }
+        const apiKey = await this.getApiKey();
+        // Due to the async call to get the API key, a parallel call to `getApp` could have created the app already.
+        if (this.app) {
+            return this.app;
+        }
+        const name = uuid.v4();
+        this.app = initializeApp({ projectId: this.projectId, apiKey, authDomain: this.authDomain }, name);
+        return this.app;
+    }
+    /**
+     * The promise resolving to the email of the Firebase-owned service account, in case it wasn't set in the
+     * configuration.
+     */
+    adminServiceAccountPromise;
+    /**
+     * Looks for the automatically-created Firebase admin service account by listing service accounts in the configured
+     * GCP project.
+     * This is a hack which uses the inferred format of the service account name used by Firebase. It is preferred to
+     * manually set the `google.firebase.adminServiceAccount` configuration.
+     *
+     * @returns The email of the Firebase admin service account.
+     */
+    async findAdminServiceAccount() {
+        this.logger.debug(`🛂 'google.firebase.adminServiceAccount' is not set. Listing service accounts in the project to find it.`);
+        const iamClient = await this.googleApisService.getClient('iam', 'v1', {});
+        const request = {
+            name: `projects/${this.projectId}`,
+            pageSize: 100,
+            pageToken: undefined,
+        };
+        do {
+            const { data } = await iamClient.projects.serviceAccounts.list(request);
+            const adminServiceAccount = data.accounts
+                ?.filter((a) => a.email != null)
+                .find(({ email }) => email.match(`^firebase-adminsdk-[\\w]+@${this.projectId}\\.iam\\.gserviceaccount\\.com$`));
+            if (adminServiceAccount) {
+                this.logger.debug(`🛂 Found Firebase admin service account as '${adminServiceAccount.email}'.`);
+                return adminServiceAccount.email;
+            }
+            if (data.nextPageToken) {
+                request.pageToken = data.nextPageToken;
+            }
+        } while (request.pageToken);
+        throw new FirebaseAdminServiceAccountNotFoundError(this.projectId);
+    }
+    /**
+     * Returns the email for the Firebase admin service account, either from the configuration or by listing service
+     * accounts using Google APIs.
+     *
+     * @returns The email for the Firebase admin service account.
+     */
+    async getAdminServiceAccount() {
+        if (this.confAdminServiceAccount) {
+            return this.confAdminServiceAccount;
+        }
+        if (!this.adminServiceAccountPromise) {
+            this.adminServiceAccountPromise = this.findAdminServiceAccount();
+        }
+        return await this.adminServiceAccountPromise;
+    }
+    /**
+     * The singleton {@link FirebaseAdminApp}, created by {@link FirebaseAppService.getAdminAppForAdminServiceAccount}.
+     */
+    adminAppForAdminServiceAccount;
+    /**
+     * Returns a Firebase admin app configured to authenticate as the Firebase admin service account.
+     * Using a service account rather than end user credentials ensures access to all functionalities (e.g. token
+     * signing), which are otherwise unavailable to end users.
+     *
+     * @returns The Firebase admin app.
+     */
+    async getAdminAppForAdminServiceAccount() {
+        if (this.adminAppForAdminServiceAccount) {
+            return this.adminAppForAdminServiceAccount;
+        }
+        const serviceAccountId = await this.getAdminServiceAccount();
+        const credential = await this.makeAdminCredential(serviceAccountId);
+        // Same reasoning as in `getApp()`.
+        if (this.adminAppForAdminServiceAccount) {
+            return this.adminAppForAdminServiceAccount;
+        }
+        const name = uuid.v4();
+        this.adminAppForAdminServiceAccount = initializeAdminApp({
+            projectId: this.projectId,
+            serviceAccountId,
+            credential,
+        }, name);
+        return this.adminAppForAdminServiceAccount;
+    }
+    /**
+     * Creates a {@link Credential} object that can be used when initializing a Firebase admin app.
+     * The returned object generates access tokens for the given service account. The application default credentials (or
+     * any other default authentication method) should provide authorization to sign tokens in the GCP project for this to
+     * work.
+     *
+     * @param serviceAccountId The ID / email of the service account to impersonate.
+     * @returns The {@link Credential} to use with the Firebase admin app.
+     */
+    async makeAdminCredential(serviceAccountId) {
+        const iamCredentialsClient = new IAMCredentialsClient();
+        return {
+            getAccessToken: async () => {
+                const [{ accessToken, expireTime }] = await iamCredentialsClient.generateAccessToken({
+                    name: `projects/-/serviceAccounts/${serviceAccountId}`,
+                    scope: ['https://www.googleapis.com/auth/cloud-platform'],
+                });
+                const expireTimestamp = parseInt(expireTime?.seconds ?? '0') * 1000;
+                const expires_in = Math.floor((expireTimestamp - Date.now()) / 1000);
+                return { access_token: accessToken ?? '', expires_in };
+            },
+        };
+    }
+    /**
+     * Looks for a Firebase app ID using the API and returns the first one found.
+     * This could be the ID of an Android, iOS, or web app.
+     * If no app can be found, an error is returned.
+     *
+     * @param options Options when listing the existing apps.
+     * @returns The first found Firebase app ID.
+     */
+    async getAnyAppId(options = {}) {
+        const appTypes = options.appTypes ?? FIREBASE_APP_TYPES;
+        const firebaseClient = await this.googleApisService.getClient('firebase', 'v1beta1', {});
+        const appIds = await Promise.all(appTypes.map((appType) => this.getFirstApp(firebaseClient, appType)));
+        const appId = appIds.find((id) => id) ?? null;
+        if (!appId) {
+            throw new NoFirebaseAppFoundError(this.projectId);
+        }
+        return appId;
+    }
+    /**
+     * Fetches the first Firebase app of a given type and returns its ID.
+     *
+     * @param client The Firebase API client to use.
+     * @param appType The type of Firebase app to list.
+     * @returns The ID of the first app, or `null` if none could be found.
+     */
+    async getFirstApp(client, appType) {
+        const { data: { apps }, } = await client.projects[appType].list({
+            parent: `projects/${this.projectId}`,
+            pageSize: 1,
+        });
+        return apps ? apps[0]?.appId ?? null : null;
+    }
+    /**
+     * The promise resolving to one of the Firebase App IDs available in the GCP project.
+     * Only set if {@link FirebaseAppService.confAppId} is not set.
+     */
+    appIdPromise;
+    /**
+     * Returns the Firebase App ID, either from the configuration or by listing apps using Google APIs.
+     *
+     * @returns The Firebase App ID.
+     */
+    async getAppId() {
+        if (this.confAppId) {
+            return this.confAppId;
+        }
+        if (!this.appIdPromise) {
+            this.appIdPromise = this.getAnyAppId();
+        }
+        return await this.appIdPromise;
+    }
+}

package/dist/services/firebase-emulator.d.ts

@@ -0,0 +1,35 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { DockerContainerPublish, DockerEmulatorService } from '@causa/workspace-core';
+/**
+ * Options when starting a Firebase emulator.
+ */
+type FirebaseEmulatorStartOptions = Omit<NonNullable<Parameters<DockerEmulatorService['start']>[3]>, 'commandAndArgs'> & NonNullable<Parameters<DockerEmulatorService['waitForAvailability']>[2]>;
+/**
+ * A service providing a way to start emulators exposed by the `firebase` CLI.
+ */
+export declare class FirebaseEmulatorService {
+    /**
+     * The underlying {@link DockerEmulatorService} used to start the emulator.
+     */
+    private readonly dockerEmulatorService;
+    /**
+     * The local ("demo") GCP project used by the emulator.
+     */
+    readonly localGcpProject: string;
+    /**
+     * The version of the Firebase tools to use.
+     */
+    readonly firebaseToolsVersion: string;
+    constructor(context: WorkspaceContext);
+    /**
+     * Starts a Docker container running an emulator using the `firebase` CLI, and waits for it to be available.
+     * The version of the Firebase CLI can be specified using the `google.firebaseTools.version` configuration.
+     *
+     * @param containerName The name of the container to create.
+     * @param firebaseConfFile The path to a local file containing the Firebase configuration.
+     * @param publish A list of at least one port to expose from the container.
+     * @param options Options when starting the Docker container and waiting for it to be available.
+     */
+    start(containerName: string, firebaseConfFile: string, publish: [DockerContainerPublish, ...DockerContainerPublish[]], options?: FirebaseEmulatorStartOptions): Promise<void>;
+}
+export {};

package/dist/services/firebase-emulator.js

@@ -0,0 +1,65 @@
+import { DockerEmulatorService, } from '@causa/workspace-core';
+import { getLocalGcpProject, } from '../configurations/index.js';
+/**
+ * The Docker image providing the `firebase` CLI.
+ */
+const FIREBASE_TOOLS_IMAGE = 'andreysenov/firebase-tools';
+/**
+ * The location of the Firebase configuration file within the container.
+ */
+const FIREBASE_CONTAINER_CONF_FILE = '/home/node/firebase.json';
+/**
+ * A service providing a way to start emulators exposed by the `firebase` CLI.
+ */
+export class FirebaseEmulatorService {
+    /**
+     * The underlying {@link DockerEmulatorService} used to start the emulator.
+     */
+    dockerEmulatorService;
+    /**
+     * The local ("demo") GCP project used by the emulator.
+     */
+    localGcpProject;
+    /**
+     * The version of the Firebase tools to use.
+     */
+    firebaseToolsVersion;
+    constructor(context) {
+        this.dockerEmulatorService = context.service(DockerEmulatorService);
+        this.localGcpProject = getLocalGcpProject(context);
+        this.firebaseToolsVersion =
+            context
+                .asConfiguration()
+                .get('google.firebase.tools.version') ?? 'latest';
+    }
+    /**
+     * Starts a Docker container running an emulator using the `firebase` CLI, and waits for it to be available.
+     * The version of the Firebase CLI can be specified using the `google.firebaseTools.version` configuration.
+     *
+     * @param containerName The name of the container to create.
+     * @param firebaseConfFile The path to a local file containing the Firebase configuration.
+     * @param publish A list of at least one port to expose from the container.
+     * @param options Options when starting the Docker container and waiting for it to be available.
+     */
+    async start(containerName, firebaseConfFile, publish, options = {}) {
+        await this.dockerEmulatorService.start(`${FIREBASE_TOOLS_IMAGE}:${this.firebaseToolsVersion}-node-18-alpine`, containerName, publish, {
+            ...options,
+            mounts: [
+                ...(options.mounts ?? []),
+                {
+                    type: 'bind',
+                    source: firebaseConfFile,
+                    destination: FIREBASE_CONTAINER_CONF_FILE,
+                    readonly: true,
+                },
+            ],
+            commandAndArgs: [
+                'firebase',
+                'emulators:start',
+                '-P',
+                this.localGcpProject,
+            ],
+        });
+        await this.dockerEmulatorService.waitForAvailability(containerName, `http://127.0.0.1:${publish[0].local}/`, options);
+    }
+}

package/dist/services/gcloud-emulator.d.ts

@@ -0,0 +1,55 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { DockerContainerMount, DockerContainerPublish, DockerEmulatorService } from '@causa/workspace-core';
+/**
+ * Options when specifying an availability endpoint when starting an emulator.
+ */
+type AvailabilityEndpointOptions = {
+    /**
+     * The endpoint that should be queried to determine when the emulator is available.
+     */
+    endpoint: string;
+} & NonNullable<Parameters<DockerEmulatorService['waitForAvailability']>[2]>;
+/**
+ * A service providing a way to start emulators exposed by the `gcloud` CLI.
+ */
+export declare class GcloudEmulatorService {
+    /**
+     * The underlying {@link DockerEmulatorService} used to start the emulator.
+     */
+    private readonly dockerEmulatorService;
+    /**
+     * The local ("demo") GCP project used by the emulator.
+     */
+    readonly localGcpProject: string;
+    /**
+     * The version of the `gcloud` CLI (and Docker image) to use.
+     */
+    readonly gcloudVersion: string;
+    constructor(context: WorkspaceContext);
+    /**
+     * Starts an emulator using the Dockerized `gcloud` CLI.
+     * The version of the `gcloud` Docker image can be specified using the `google.gcloud.version` configuration.
+     *
+     * @param emulatorName The name of the emulator, as exposed by the `gcloud` CLI.
+     * @param containerName The name of the Docker container to (re)create.
+     * @param publish A list of at least one port to expose from the container.
+     * @param options Additional options.
+     */
+    start(emulatorName: string, containerName: string, publish: [DockerContainerPublish, ...DockerContainerPublish[]], options?: {
+        /**
+         * A list of Docker volumes to mount.
+         */
+        mounts?: DockerContainerMount[];
+        /**
+         * Arguments that should be added at the end of the `gcloud` command running the emulator.
+         */
+        additionalArguments?: string[];
+        /**
+         * The endpoint that should be queried and for which a 200 response should be received.
+         * If specified, the function will only resolve when the emulator has successfully started.
+         * If not specified, the emulator might still be initializing or might have failed when the function resolves.
+         */
+        availabilityEndpoint?: string | AvailabilityEndpointOptions;
+    }): Promise<void>;
+}
+export {};

package/dist/services/gcloud-emulator.js

@@ -0,0 +1,66 @@
+import { DockerEmulatorService, } from '@causa/workspace-core';
+import { getLocalGcpProject, } from '../configurations/index.js';
+/**
+ * The URI for the Dockerized `gcloud` command, provided by Google.
+ */
+const GCLOUD_DOCKER_IMAGE = `gcr.io/google.com/cloudsdktool/google-cloud-cli`;
+/**
+ * A service providing a way to start emulators exposed by the `gcloud` CLI.
+ */
+export class GcloudEmulatorService {
+    /**
+     * The underlying {@link DockerEmulatorService} used to start the emulator.
+     */
+    dockerEmulatorService;
+    /**
+     * The local ("demo") GCP project used by the emulator.
+     */
+    localGcpProject;
+    /**
+     * The version of the `gcloud` CLI (and Docker image) to use.
+     */
+    gcloudVersion;
+    constructor(context) {
+        this.dockerEmulatorService = context.service(DockerEmulatorService);
+        this.localGcpProject = getLocalGcpProject(context);
+        this.gcloudVersion =
+            context
+                .asConfiguration()
+                .get('google.gcloud.version') ?? 'latest';
+    }
+    /**
+     * Starts an emulator using the Dockerized `gcloud` CLI.
+     * The version of the `gcloud` Docker image can be specified using the `google.gcloud.version` configuration.
+     *
+     * @param emulatorName The name of the emulator, as exposed by the `gcloud` CLI.
+     * @param containerName The name of the Docker container to (re)create.
+     * @param publish A list of at least one port to expose from the container.
+     * @param options Additional options.
+     */
+    async start(emulatorName, containerName, publish, options = {}) {
+        // The `emulators` tag does not have a `latest` version. It is simply `emulators`, which is the default here.
+        const imageVersion = [this.gcloudVersion, 'emulators']
+            .filter((s) => s !== 'latest')
+            .join('-');
+        const dockerImage = `${GCLOUD_DOCKER_IMAGE}:${imageVersion}`;
+        await this.dockerEmulatorService.start(dockerImage, containerName, publish, {
+            commandAndArgs: [
+                'gcloud',
+                'beta',
+                'emulators',
+                emulatorName,
+                'start',
+                `--host-port=0.0.0.0:${publish[0].container}`,
+                `--project=${this.localGcpProject}`,
+                ...(options.additionalArguments ?? []),
+            ],
+            mounts: options.mounts,
+        });
+        if (options.availabilityEndpoint) {
+            const { endpoint, ...waitOptions } = typeof options.availabilityEndpoint === 'string'
+                ? { endpoint: options.availabilityEndpoint }
+                : options.availabilityEndpoint;
+            await this.dockerEmulatorService.waitForAvailability(containerName, endpoint, waitOptions);
+        }
+    }
+}

package/dist/services/google-apis.d.ts

@@ -0,0 +1,34 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { GoogleApis } from 'googleapis';
+import { ApiClient, OptionsOfApiClient } from './google-apis.types.js';
+/**
+ * A service that exposes the lowest level of Google API clients, from `googleapis`.
+ * Those might be needed in last resort, when no higher level client exists for an API.
+ */
+export declare class GoogleApisService {
+    /**
+     * The GCP project ID read from the {@link WorkspaceContext} configuration.
+     */
+    readonly projectId: string;
+    constructor(context: WorkspaceContext);
+    /**
+     * The promise returning the `JSONClient` configured with the {@link GoogleApisService.projectId}.
+     */
+    private authClientPromise;
+    /**
+     * Possibly initializes and returns the auth client to use with Google API clients.
+     *
+     * @returns The auth client.
+     */
+    getAuthClient(): Promise<any>;
+    /**
+     * Creates a new client for one of Google's APIs.
+     * Authentication is automatically configured.
+     *
+     * @param api The name of the Google API.
+     * @param version The version of the API.
+     * @param arg Options passed to the client.
+     * @returns The created client.
+     */
+    getClient<const T extends keyof GoogleApis, const V extends string>(api: T, version: V, arg: Omit<OptionsOfApiClient<T, V>, 'auth' | 'version'>): Promise<ApiClient<T, V>>;
+}

package/dist/services/google-apis.js

@@ -0,0 +1,48 @@
+import { google } from 'googleapis';
+/**
+ * A service that exposes the lowest level of Google API clients, from `googleapis`.
+ * Those might be needed in last resort, when no higher level client exists for an API.
+ */
+export class GoogleApisService {
+    /**
+     * The GCP project ID read from the {@link WorkspaceContext} configuration.
+     */
+    projectId;
+    constructor(context) {
+        const googleConf = context.asConfiguration();
+        this.projectId = googleConf.getOrThrow('google.project');
+    }
+    /**
+     * The promise returning the `JSONClient` configured with the {@link GoogleApisService.projectId}.
+     */
+    authClientPromise;
+    /**
+     * Possibly initializes and returns the auth client to use with Google API clients.
+     *
+     * @returns The auth client.
+     */
+    async getAuthClient() {
+        if (!this.authClientPromise) {
+            const auth = new google.auth.GoogleAuth({
+                projectId: this.projectId,
+                scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+            });
+            this.authClientPromise = auth.getClient();
+        }
+        return await this.authClientPromise;
+    }
+    /**
+     * Creates a new client for one of Google's APIs.
+     * Authentication is automatically configured.
+     *
+     * @param api The name of the Google API.
+     * @param version The version of the API.
+     * @param arg Options passed to the client.
+     * @returns The created client.
+     */
+    async getClient(api, version, arg) {
+        const auth = await this.getAuthClient();
+        const clientFn = google[api];
+        return clientFn({ ...arg, version, auth });
+    }
+}