@causa/workspace-google 0.3.1 → 0.5.0

package/dist/functions/google-spanner/write-databases.js

@@ -0,0 +1,73 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { WorkspaceFunction, } from '@causa/workspace';
+import { CAUSA_FOLDER } from '@causa/workspace/initialization';
+import { AllowMissing } from '@causa/workspace/validation';
+import { IsBoolean } from 'class-validator';
+import { mkdir, rm, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { GoogleSpannerListDatabases } from './list-databases.js';
+/**
+ * The default directory where Spanner database configurations are written, relative to the workspace root.
+ */
+const DEFAULT_DATABASE_CONFIGURATIONS_DIRECTORY = join(CAUSA_FOLDER, 'spanner-databases');
+/**
+ * A function that uses {@link GoogleSpannerListDatabases} to find all the Spanner databases in the workspace, and
+ * writes their configurations to a directory.
+ * The `google.spanner.databaseConfigurationsDirectory` configuration can be used to specify the output location of the
+ * database configurations.
+ * This function returns a partial configuration, such that it can be used as a processor.
+ */
+export class GoogleSpannerWriteDatabases extends WorkspaceFunction {
+    tearDown;
+    /**
+     * Returns the path to the directory where Spanner databases configurations should be written.
+     * It is either fetched from the workspace configuration, or the default value is used.
+     *
+     * @param context The {@link WorkspaceContext}.
+     * @returns The path to the directory where database configurations should be written.
+     */
+    getConfigurationsDirectory(context) {
+        return (context
+            .asConfiguration()
+            .get('google.spanner.databaseConfigurationsDirectory') ??
+            DEFAULT_DATABASE_CONFIGURATIONS_DIRECTORY);
+    }
+    async _call(context) {
+        const databaseConfigurationsDirectory = this.getConfigurationsDirectory(context);
+        const absoluteDir = join(context.rootPath, databaseConfigurationsDirectory);
+        await rm(absoluteDir, { recursive: true, force: true });
+        if (this.tearDown) {
+            context.logger.debug(`️🗃️ Tore down Spanner database configurations directory '${absoluteDir}'.`);
+            return { configuration: {} };
+        }
+        context.logger.info('🗃️ Listing and writing Spanner database configurations.');
+        const databases = await context.call(GoogleSpannerListDatabases, {});
+        await mkdir(absoluteDir, { recursive: true });
+        context.logger.debug(`🗃️ Writing configurations for Spanner databases: ${databases
+            .map((d) => `'${d.id}'`)
+            .join(', ')}.`);
+        await Promise.all(databases.map((database) => writeFile(join(absoluteDir, `${database.id}.json`), JSON.stringify(database))));
+        context.logger.debug(`🗃️ Wrote Spanner database configurations in '${absoluteDir}'.`);
+        return {
+            configuration: {
+                google: { spanner: { databaseConfigurationsDirectory } },
+            },
+        };
+    }
+    _supports() {
+        return true;
+    }
+}
+__decorate([
+    IsBoolean(),
+    AllowMissing(),
+    __metadata("design:type", Boolean)
+], GoogleSpannerWriteDatabases.prototype, "tearDown", void 0);

package/dist/functions/index.js

@@ -1,24 +1,14 @@
-import { EmulatorStartForFirebaseStorage } from './emulator-start-firebase-storage.js';
-import { EmulatorStartForFirestore } from './emulator-start-firestore.js';
-import { EmulatorStartForIdentityPlatform } from './emulator-start-identity-platform.js';
-import { EmulatorStartForPubSub } from './emulator-start-pubsub.js';
-import { EmulatorStartForSpanner } from './emulator-start-spanner.js';
-import { EmulatorStopForFirebaseStorage } from './emulator-stop-firebase-storage.js';
-import { EmulatorStopForFirestore } from './emulator-stop-firestore.js';
-import { EmulatorStopForIdentityPlatform } from './emulator-stop-identity-platform.js';
-import { EmulatorStopForPubSub } from './emulator-stop-pubsub.js';
-import { EmulatorStopForSpanner } from './emulator-stop-spanner.js';
-import { GoogleAppCheckGenerateToken } from './google-app-check-generate-token.js';
-import { GoogleFirebaseStorageMergeRules } from './google-firebase-storage-merge-rules.js';
-import { GoogleFirestoreMergeRules } from './google-firestore-merge-rules.js';
-import { GoogleIdentityPlatformGenerateCustomToken } from './google-identity-platform-generate-custom-token.js';
-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 { 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';
+import { EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, } from './emulator/index.js';
+import { EventTopicBrokerCreateTopicForPubSub, EventTopicBrokerCreateTriggerForCloudRun, EventTopicBrokerDeleteTopicForPubSub, EventTopicBrokerDeleteTriggerResourceForCloudRunInvokerRole, EventTopicBrokerDeleteTriggerResourceForPubSubSubscription, EventTopicBrokerDeleteTriggerResourceForServiceAccount, EventTopicBrokerGetTopicIdForPubSub, EventTopicBrokerPublishEventsForGoogle, } from './event-topic/index.js';
+import { GoogleAppCheckGenerateToken } from './google-app-check/index.js';
+import { GoogleFirebaseStorageMergeRules } from './google-firebase-storage/index.js';
+import { GoogleFirestoreMergeRules } from './google-firestore/index.js';
+import { GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, } from './google-identity-platform/index.js';
+import { GooglePubSubWriteTopics } from './google-pubsub/index.js';
+import { GoogleServicesEnable } from './google-services/index.js';
+import { GoogleSpannerListDatabases, GoogleSpannerWriteDatabases, } from './google-spanner/index.js';
+import { ProjectGetArtefactDestinationForCloudFunctions, ProjectGetArtefactDestinationForCloudRun, ProjectPushArtefactForCloudFunctions, } from './project/index.js';
+import { SecretFetchForGoogleSecretManager } from './secret/index.js';
 export function registerFunctions(context) {
-    context.registerFunctionImplementations(EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, GoogleAppCheckGenerateToken, GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, GoogleServicesEnable, GoogleSpannerListDatabases, ProjectGetArtefactDestinationForCloudFunctions, ProjectGetArtefactDestinationForCloudRun, ProjectPushArtefactForCloudFunctions, SecretFetchForGoogleSecretManager);
+    context.registerFunctionImplementations(EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, EventTopicBrokerCreateTopicForPubSub, EventTopicBrokerCreateTriggerForCloudRun, EventTopicBrokerDeleteTopicForPubSub, EventTopicBrokerDeleteTriggerResourceForCloudRunInvokerRole, EventTopicBrokerDeleteTriggerResourceForPubSubSubscription, EventTopicBrokerDeleteTriggerResourceForServiceAccount, EventTopicBrokerGetTopicIdForPubSub, EventTopicBrokerPublishEventsForGoogle, GoogleAppCheckGenerateToken, GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, GooglePubSubWriteTopics, GoogleServicesEnable, GoogleSpannerListDatabases, GoogleSpannerWriteDatabases, ProjectGetArtefactDestinationForCloudFunctions, ProjectGetArtefactDestinationForCloudRun, ProjectPushArtefactForCloudFunctions, SecretFetchForGoogleSecretManager);
 }

package/dist/functions/project/index.d.ts

@@ -0,0 +1,3 @@
+export { ProjectGetArtefactDestinationForCloudFunctions } from './get-artefact-destination-cloud-functions.js';
+export { ProjectGetArtefactDestinationForCloudRun } from './get-artefact-destination-cloud-run.js';
+export { ProjectPushArtefactForCloudFunctions } from './push-artefact-cloud-functions.js';

package/dist/functions/project/index.js

@@ -0,0 +1,3 @@
+export { ProjectGetArtefactDestinationForCloudFunctions } from './get-artefact-destination-cloud-functions.js';
+export { ProjectGetArtefactDestinationForCloudRun } from './get-artefact-destination-cloud-run.js';
+export { ProjectPushArtefactForCloudFunctions } from './push-artefact-cloud-functions.js';

package/dist/functions/{project-push-artefact-cloud-functions.js → project/push-artefact-cloud-functions.js}

@@ -1,6 +1,6 @@
 import { ArtefactAlreadyExistsError, ProjectPushArtefact, } from '@causa/workspace-core';
 import { rm } from 'fs/promises';
-import { CloudStorageService } from '../services/index.js';
+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

package/dist/functions/{secret-fetch-secret-manager.js → secret/fetch-secret-manager.js}

@@ -1,5 +1,5 @@
 import { InvalidSecretDefinitionError, SecretFetch, } from '@causa/workspace';
-import { GoogleSecretManagerService } from '../services/index.js';
+import { GoogleSecretManagerService } from '../../services/index.js';
 /**
  * The regular expression used to match the (Secret Manager) secret ID/name, and possibly its version and project.
  * [projects/<projectId>/secrets]<secretName>[/versions/<version>]

package/dist/functions/secret/index.d.ts

@@ -0,0 +1 @@
+export { SecretFetchForGoogleSecretManager } from './fetch-secret-manager.js';

package/dist/functions/secret/index.js

@@ -0,0 +1 @@
+export { SecretFetchForGoogleSecretManager } from './fetch-secret-manager.js';

package/dist/services/bigquery.d.ts

@@ -0,0 +1,16 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { BigQuery } from '@google-cloud/bigquery';
+/**
+ * A service that provides access to BigQuery.
+ */
+export declare class BigQueryService {
+    /**
+     * The BigQuery client configured with the GCP project ID.
+     */
+    readonly bigQuery: BigQuery;
+    /**
+     * The GCP project ID.
+     */
+    readonly projectId: string;
+    constructor(context: WorkspaceContext);
+}

package/dist/services/bigquery.js

@@ -0,0 +1,19 @@
+import { BigQuery } from '@google-cloud/bigquery';
+/**
+ * A service that provides access to BigQuery.
+ */
+export class BigQueryService {
+    /**
+     * The BigQuery client configured with the GCP project ID.
+     */
+    bigQuery;
+    /**
+     * The GCP project ID.
+     */
+    projectId;
+    constructor(context) {
+        const googleConf = context.asConfiguration();
+        this.projectId = googleConf.getOrThrow('google.project');
+        this.bigQuery = new BigQuery({ projectId: this.projectId });
+    }
+}

package/dist/services/cloud-run-pubsub-trigger.d.ts

@@ -0,0 +1,101 @@
+import { WorkspaceContext } from '@causa/workspace';
+/**
+ * A service that manages (creates) Pub/Sub triggers pointing to Cloud Run services.
+ * This is used for backfilling operations. The reason it is a service is to persist temporary service accounts and IAM
+ * grants, such that they can be reused within the same backfilling operation.
+ */
+export declare class CloudRunPubSubTriggerService {
+    /**
+     * The service managing Cloud Run resources.
+     */
+    private readonly cloudRunService;
+    /**
+     * The service managing Pub/Sub resources.
+     */
+    private readonly pubSubService;
+    /**
+     * The service managing IAM permissions.
+     */
+    private readonly iamService;
+    /**
+     * A set of IAM bindings that have already been created.
+     * This is used to avoid creating the same bindings multiple times within a single backfill operation.
+     * An IAM binding allows the service account used by Pub/Sub for a single backfill operation to invoke a Cloud Run
+     * service. The format of strings in this set is the one used to reference bindings during deletion as well, i.e.
+     * `projects/<projectId>/locations/<location>/services/<name>/invokerBindings/<serviceAccountEmail>`.
+     */
+    private readonly invokerBindingIds;
+    /**
+     * A map of backfill IDs to promises resolving to the service account email used by Pub/Sub to invoke Cloud Run
+     * services for the backfill.
+     */
+    private readonly backfillInvokerServiceAccounts;
+    /**
+     * The logger used by this service.
+     */
+    private readonly logger;
+    /**
+     * The ID of the GCP project in which resources should be created.
+     */
+    readonly projectId: string;
+    constructor(context: WorkspaceContext);
+    /**
+     * Creates a service account that should be used by Pub/Sub to invoke Cloud Run services for a given backfill
+     * operation.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @returns The service account email that should be used by Pub/Sub when pushing messages to Cloud Run services,
+     *   along with the corresponding resource ID that should be deleted as part of the backfill cleaning.
+     */
+    private createBackfillInvokerServiceAccount;
+    /**
+     * Gets or creates a service account that should be used by Pub/Sub to invoke Cloud Run services for a given backfill
+     * operation.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @returns The service account email that should be used by Pub/Sub when pushing messages to Cloud Run services.
+     *   If `resourceId` is not `null`, it should be added to the list of resources to delete as part of the backfill
+     *   cleaning.
+     */
+    private getBackfillInvokerServiceAccount;
+    /**
+     * Grants the invoker role to a service account for a given Cloud Run service.
+     * This is used to allow Pub/Sub to invoke the Cloud Run service.
+     * If a resource ID string is returned, it should be added to the list of resources to delete as part of the backfill
+     * cleaning.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     * @param pubSubServiceAccount The service account email for which the invoker role should be granted.
+     * @returns The resource ID of the IAM binding that was created, or `null` if the binding already existed.
+     */
+    private grantPubSubInvokerRole;
+    /**
+     * Creates a Pub/Sub subscription that will push messages to a Cloud Run service.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @param topicId The ID of the Pub/Sub topic to subscribe to.
+     * @param serviceId The ID of the Cloud Run service to invoke.
+     * @param path The HTTP endpoint of the Cloud Run service to invoke.
+     * @param serviceAccountEmail The service account email that should be used by Pub/Sub when pushing messages to the
+     *   Cloud Run service.
+     * @returns The ID of the Pub/Sub subscription that was created. It should be added to the list of resources to delete
+     *   as part of the backfill cleaning.
+     */
+    private createSubscription;
+    /**
+     * Creates a Pub/Sub trigger (push subscription) pointing to a Cloud Run service.
+     * This requires several resources, such as:
+     * - A service account that should be used by Pub/Sub to invoke Cloud Run services for the backfill.
+     * - An IAM binding allowing the service account to invoke the Cloud Run service.
+     * - A Pub/Sub subscription that will push messages to the Cloud Run service.
+     * The IDs of these resources are returned, and should be deleted as part of the backfill cleaning.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @param topicId The ID of the Pub/Sub topic to subscribe to.
+     * @param serviceId The ID of the Cloud Run service to invoke.
+     * @param path The HTTP endpoint of the Cloud Run service to invoke.
+     * @returns The IDs of the resources that were created. They should be added to the list of resources to delete as
+     *   part of the backfill cleaning.
+     */
+    create(backfillId: string, topicId: string, serviceId: string, path: string): Promise<string[]>;
+}

package/dist/services/cloud-run-pubsub-trigger.js

@@ -0,0 +1,177 @@
+import { EventTopicTriggerCreationError } from '@causa/workspace-core';
+import { Subscription } from '@google-cloud/pubsub';
+import { randomBytes } from 'crypto';
+import { CloudRunService } from './cloud-run.js';
+import { IamService } from './iam.js';
+import { PubSubService } from './pubsub.js';
+/**
+ * A service that manages (creates) Pub/Sub triggers pointing to Cloud Run services.
+ * This is used for backfilling operations. The reason it is a service is to persist temporary service accounts and IAM
+ * grants, such that they can be reused within the same backfilling operation.
+ */
+export class CloudRunPubSubTriggerService {
+    /**
+     * The service managing Cloud Run resources.
+     */
+    cloudRunService;
+    /**
+     * The service managing Pub/Sub resources.
+     */
+    pubSubService;
+    /**
+     * The service managing IAM permissions.
+     */
+    iamService;
+    /**
+     * A set of IAM bindings that have already been created.
+     * This is used to avoid creating the same bindings multiple times within a single backfill operation.
+     * An IAM binding allows the service account used by Pub/Sub for a single backfill operation to invoke a Cloud Run
+     * service. The format of strings in this set is the one used to reference bindings during deletion as well, i.e.
+     * `projects/<projectId>/locations/<location>/services/<name>/invokerBindings/<serviceAccountEmail>`.
+     */
+    invokerBindingIds = new Set();
+    /**
+     * A map of backfill IDs to promises resolving to the service account email used by Pub/Sub to invoke Cloud Run
+     * services for the backfill.
+     */
+    backfillInvokerServiceAccounts = {};
+    /**
+     * The logger used by this service.
+     */
+    logger;
+    /**
+     * The ID of the GCP project in which resources should be created.
+     */
+    projectId;
+    constructor(context) {
+        this.cloudRunService = context.service(CloudRunService);
+        this.pubSubService = context.service(PubSubService);
+        this.iamService = context.service(IamService);
+        this.logger = context.logger;
+        this.projectId = context
+            .asConfiguration()
+            .getOrThrow('google.project');
+    }
+    /**
+     * Creates a service account that should be used by Pub/Sub to invoke Cloud Run services for a given backfill
+     * operation.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @returns The service account email that should be used by Pub/Sub when pushing messages to Cloud Run services,
+     *   along with the corresponding resource ID that should be deleted as part of the backfill cleaning.
+     */
+    async createBackfillInvokerServiceAccount(backfillId) {
+        const serviceAccountId = `backfill-pubsub-${backfillId}`;
+        const bindings = await this.pubSubService.getPushServiceAccountBindings();
+        this.logger.info(`🛂 Creating Pub/Sub backfilling service account '${serviceAccountId}'.`);
+        const serviceAccount = await this.iamService.createServiceAccount(this.projectId, serviceAccountId, { bindings });
+        return {
+            serviceAccountEmail: serviceAccount.email ?? '',
+            resourceId: serviceAccount.name ?? null,
+        };
+    }
+    /**
+     * Gets or creates a service account that should be used by Pub/Sub to invoke Cloud Run services for a given backfill
+     * operation.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @returns The service account email that should be used by Pub/Sub when pushing messages to Cloud Run services.
+     *   If `resourceId` is not `null`, it should be added to the list of resources to delete as part of the backfill
+     *   cleaning.
+     */
+    async getBackfillInvokerServiceAccount(backfillId) {
+        const existingServiceAccountPromise = this.backfillInvokerServiceAccounts[backfillId];
+        if (existingServiceAccountPromise) {
+            return {
+                serviceAccountEmail: await existingServiceAccountPromise,
+                resourceId: null,
+            };
+        }
+        const creationPromise = this.createBackfillInvokerServiceAccount(backfillId);
+        this.backfillInvokerServiceAccounts[backfillId] = creationPromise.then((result) => result.serviceAccountEmail);
+        return await creationPromise;
+    }
+    /**
+     * Grants the invoker role to a service account for a given Cloud Run service.
+     * This is used to allow Pub/Sub to invoke the Cloud Run service.
+     * If a resource ID string is returned, it should be added to the list of resources to delete as part of the backfill
+     * cleaning.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     * @param pubSubServiceAccount The service account email for which the invoker role should be granted.
+     * @returns The resource ID of the IAM binding that was created, or `null` if the binding already existed.
+     */
+    async grantPubSubInvokerRole(serviceId, pubSubServiceAccount) {
+        const invokerBindingId = `${serviceId}/invokerBindings/${pubSubServiceAccount}`;
+        if (this.invokerBindingIds.has(invokerBindingId)) {
+            return null;
+        }
+        this.invokerBindingIds.add(invokerBindingId);
+        this.logger.info(`🛂 Granting invoker IAM role to backfilling service account '${pubSubServiceAccount}' for Cloud Run service '${serviceId}'.`);
+        await this.cloudRunService.addInvokerBinding(serviceId, pubSubServiceAccount);
+        return invokerBindingId;
+    }
+    /**
+     * Creates a Pub/Sub subscription that will push messages to a Cloud Run service.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @param topicId The ID of the Pub/Sub topic to subscribe to.
+     * @param serviceId The ID of the Cloud Run service to invoke.
+     * @param path The HTTP endpoint of the Cloud Run service to invoke.
+     * @param serviceAccountEmail The service account email that should be used by Pub/Sub when pushing messages to the
+     *   Cloud Run service.
+     * @returns The ID of the Pub/Sub subscription that was created. It should be added to the list of resources to delete
+     *   as part of the backfill cleaning.
+     */
+    async createSubscription(backfillId, topicId, serviceId, path, serviceAccountEmail) {
+        const serviceUri = await this.cloudRunService.getServiceUri(serviceId);
+        const pushEndpoint = `${serviceUri}${path}`;
+        const subscriptionId = Subscription.formatName_(this.projectId, `backfill-${backfillId}-${randomBytes(3).toString('hex')}`);
+        this.logger.info(`📫 Creating Pub/Sub subscription '${subscriptionId}' for Cloud Run service '${serviceId}'.`);
+        await this.pubSubService.pubSub.createSubscription(topicId, subscriptionId, {
+            pushConfig: { pushEndpoint, oidcToken: { serviceAccountEmail } },
+            expirationPolicy: {},
+            ackDeadlineSeconds: 60 * 10,
+            retryPolicy: {
+                minimumBackoff: { seconds: 1, nanos: 0 },
+                maximumBackoff: { seconds: 60, nanos: 0 },
+            },
+        });
+        return subscriptionId;
+    }
+    /**
+     * Creates a Pub/Sub trigger (push subscription) pointing to a Cloud Run service.
+     * This requires several resources, such as:
+     * - A service account that should be used by Pub/Sub to invoke Cloud Run services for the backfill.
+     * - An IAM binding allowing the service account to invoke the Cloud Run service.
+     * - A Pub/Sub subscription that will push messages to the Cloud Run service.
+     * The IDs of these resources are returned, and should be deleted as part of the backfill cleaning.
+     *
+     * @param backfillId The ID of the backfilling operation.
+     * @param topicId The ID of the Pub/Sub topic to subscribe to.
+     * @param serviceId The ID of the Cloud Run service to invoke.
+     * @param path The HTTP endpoint of the Cloud Run service to invoke.
+     * @returns The IDs of the resources that were created. They should be added to the list of resources to delete as
+     *   part of the backfill cleaning.
+     */
+    async create(backfillId, topicId, serviceId, path) {
+        const resourceIds = [];
+        try {
+            const pubSubInvokerServiceAccount = await this.getBackfillInvokerServiceAccount(backfillId);
+            if (pubSubInvokerServiceAccount.resourceId) {
+                resourceIds.push(pubSubInvokerServiceAccount.resourceId);
+            }
+            const { serviceAccountEmail } = pubSubInvokerServiceAccount;
+            const iamResourceId = await this.grantPubSubInvokerRole(serviceId, serviceAccountEmail);
+            if (iamResourceId) {
+                resourceIds.push(iamResourceId);
+            }
+            const subscriptionId = await this.createSubscription(backfillId, topicId, serviceId, path, serviceAccountEmail);
+            resourceIds.push(subscriptionId);
+            return resourceIds;
+        }
+        catch (error) {
+            throw new EventTopicTriggerCreationError(error, resourceIds);
+        }
+    }
+}

package/dist/services/cloud-run.d.ts

@@ -0,0 +1,35 @@
+import { ServicesClient } from '@google-cloud/run';
+/**
+ * A service to manage Cloud Run services.
+ */
+export declare class CloudRunService {
+    /**
+     * The Cloud Run client.
+     */
+    readonly servicesClient: ServicesClient;
+    constructor();
+    /**
+     * Retrieves the URI at which a Cloud Run service is available and can be requested.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     *   This should be in the format `projects/<projectId>/locations/<location>/services/<name>`.
+     * @returns The URI at which the service is available.
+     */
+    getServiceUri(serviceId: string): Promise<string>;
+    /**
+     * Allows a service account to call a Cloud Run service by editing the IAM policy bindings.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     *   This should be in the format `projects/<projectId>/locations/<location>/services/<name>`.
+     * @param serviceAccountEmail The email of the service account that should be allowed to call the service.
+     */
+    addInvokerBinding(serviceId: string, serviceAccountEmail: string): Promise<void>;
+    /**
+     * Removes a service account from the list of allowed invokers of a Cloud Run service.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     *   This should be in the format `projects/<projectId>/locations/<location>/services/<name>`.
+     * @param serviceAccountEmail The email of the service account that should be removed from the allowed invokers.
+     */
+    removeInvokerBinding(serviceId: string, serviceAccountEmail: string): Promise<void>;
+}

package/dist/services/cloud-run.js

@@ -0,0 +1,72 @@
+import { ServicesClient } from '@google-cloud/run';
+/**
+ * The role used to allow a service account to call a Cloud Run service.
+ */
+const INVOKER_ROLE = 'roles/run.invoker';
+/**
+ * A service to manage Cloud Run services.
+ */
+export class CloudRunService {
+    /**
+     * The Cloud Run client.
+     */
+    servicesClient;
+    constructor() {
+        this.servicesClient = new ServicesClient();
+    }
+    /**
+     * Retrieves the URI at which a Cloud Run service is available and can be requested.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     *   This should be in the format `projects/<projectId>/locations/<location>/services/<name>`.
+     * @returns The URI at which the service is available.
+     */
+    async getServiceUri(serviceId) {
+        const [service] = await this.servicesClient.getService({ name: serviceId });
+        return service.uri ?? '';
+    }
+    /**
+     * Allows a service account to call a Cloud Run service by editing the IAM policy bindings.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     *   This should be in the format `projects/<projectId>/locations/<location>/services/<name>`.
+     * @param serviceAccountEmail The email of the service account that should be allowed to call the service.
+     */
+    async addInvokerBinding(serviceId, serviceAccountEmail) {
+        const [policy] = await this.servicesClient.getIamPolicy({
+            resource: serviceId,
+        });
+        const members = [`serviceAccount:${serviceAccountEmail}`];
+        const binding = { role: INVOKER_ROLE, members };
+        policy.bindings = [...(policy.bindings ?? []), binding];
+        await this.servicesClient.setIamPolicy({
+            resource: serviceId,
+            policy,
+        });
+    }
+    /**
+     * Removes a service account from the list of allowed invokers of a Cloud Run service.
+     *
+     * @param serviceId The ID of the Cloud Run service.
+     *   This should be in the format `projects/<projectId>/locations/<location>/services/<name>`.
+     * @param serviceAccountEmail The email of the service account that should be removed from the allowed invokers.
+     */
+    async removeInvokerBinding(serviceId, serviceAccountEmail) {
+        const [policy] = await this.servicesClient.getIamPolicy({
+            resource: serviceId,
+        });
+        policy.bindings = (policy.bindings ?? []).flatMap((binding) => {
+            if (binding.role !== INVOKER_ROLE || binding.condition) {
+                return binding;
+            }
+            // `includes` ensures that deleted service accounts (in the form of `deleted:serviceAccount:...`) are also removed
+            // from the list.
+            binding.members = binding.members?.filter((member) => !member.includes(`serviceAccount:${serviceAccountEmail}`));
+            return binding.members?.length ? binding : [];
+        });
+        await this.servicesClient.setIamPolicy({
+            resource: serviceId,
+            policy,
+        });
+    }
+}

package/dist/services/iam.d.ts

@@ -0,0 +1,43 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { iam_v1 } from 'googleapis';
+/**
+ * A service for interacting with the IAM API.
+ */
+export declare class IamService {
+    /**
+     * The underlying {@link GoogleApisService} used to get the IAM client.
+     */
+    private readonly googleApisService;
+    /**
+     * A promise that resolves to the singleton IAM client.
+     */
+    private iam;
+    constructor(context: WorkspaceContext);
+    /**
+     * Gets or creates the singleton IAM client.
+     *
+     * @returns The singleton IAM client.
+     */
+    private getIam;
+    /**
+     * Creates a service account, optionally setting the IAM policy bindings for it.
+     *
+     * @param projectId The ID of the project in which to create the service account.
+     * @param accountId The ID of the service account to create.
+     * @param options Additional options when creating the account.
+     * @returns The created service account.
+     */
+    createServiceAccount(projectId: string, accountId: string, options?: {
+        /**
+         * The IAM policy bindings to set for the service account after its creation.
+         */
+        bindings?: iam_v1.Schema$Binding[];
+    }): Promise<iam_v1.Schema$ServiceAccount>;
+    /**
+     * Deletes a service account.
+     *
+     * @param name The full resource name of the service account to delete, in the format
+     *   `projects/<projectId>/serviceAccounts/<accountId>`.
+     */
+    deleteServiceAccount(name: string): Promise<void>;
+}