@causa/workspace-google 1.3.1 → 1.4.0-beta.2

package/dist/graph/rules/terraform/cloud-run-cron-triggers.js

@@ -0,0 +1,67 @@
+import {} from '@causa/workspace-core';
+import { nodeId, scheduledJobId, triggerId, triggerLocator, } from '@causa/workspace-core/graph';
+import { terraformDeploys } from '@causa/workspace-terraform';
+import { CloudRunFact } from '../../cloud-run.js';
+import { blockResource } from '../../terraform-modules.js';
+/**
+ * A `scheduledJob` node per cron trigger of a project, for each Cloud Run module block deploying it with cron triggers
+ * enabled. The module names the job `run-<service>-<trigger>`. The locator is the trigger's. The job `realizes` its
+ * trigger, and `targets` the service the block deploys.
+ *
+ * @param graph The context of the extraction.
+ * @returns The scheduled jobs, and their edges.
+ */
+export async function cloudRunCronTriggers(graph) {
+    const { locator } = graph;
+    const cloudRun = await graph.get(CloudRunFact);
+    const nodes = [];
+    const edges = [];
+    const warnings = [];
+    for (const service of cloudRun) {
+        const source = service.block.declaration;
+        for (const [name, trigger] of service.cronTriggers) {
+            const jobLocator = triggerLocator(service.project.directory, name);
+            const job = `run-${service.name}-${name}`;
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'scheduledJob',
+                locator: jobLocator,
+                name: job,
+                sources: [
+                    source,
+                    await locator.configurationSource(service.project.context, [
+                        'serviceContainer',
+                        'triggers',
+                        name,
+                    ]),
+                ],
+                data: {
+                    resource: await blockResource(graph, service.block, {
+                        type: 'cloudscheduler.googleapis.com/Job',
+                        scope: service.project,
+                        id: [
+                            'projects/',
+                            service.projectPart,
+                            '/locations/',
+                            service.locationPart,
+                            `/jobs/${job}`,
+                        ],
+                    }, warnings),
+                },
+            });
+            edges.push(...terraformDeploys(service.block, nodeId('scheduledJob', jobLocator)), {
+                type: 'realizes',
+                from: scheduledJobId(jobLocator),
+                to: triggerId(service.project.directory, name),
+                sources: [source],
+            }, {
+                type: 'targets',
+                from: scheduledJobId(jobLocator),
+                to: service.id,
+                label: trigger.endpoint?.path,
+                sources: [source],
+            });
+        }
+    }
+    return { nodes, edges, warnings };
+}

package/dist/graph/rules/terraform/cloud-run-grants.d.ts

@@ -0,0 +1,16 @@
+import { type GraphRuleOutput } from '@causa/workspace-core';
+import { type GraphContext } from '@causa/workspace-core/graph';
+/**
+ * The edges granted by the IAM bindings of the Cloud Run module blocks deploying a project.
+ *
+ * - A `publishes` edge from every service of the project to each broker topic of its `outputs.eventTopics`, when any
+ *   block grants the publisher role.
+ * - An `accesses` edge from every service of the project to each datastore of its outputs, when any block grants
+ *   access. Spanner access is granted on each database. Firestore access is granted on
+ *   the whole database, but is declared for the collections listed in the outputs: edges target the collections under
+ *   each listed root.
+ *
+ * @param graph The context of the extraction.
+ * @returns The edges granted by the blocks.
+ */
+export declare function cloudRunGrants(graph: GraphContext): Promise<GraphRuleOutput>;

package/dist/graph/rules/terraform/cloud-run-grants.js

@@ -0,0 +1,118 @@
+import {} from '@causa/workspace-core';
+import { brokerTopicId, databaseId, databaseLocator, ModelFact, tableId, } from '@causa/workspace-core/graph';
+import { CloudRunFact } from '../../cloud-run.js';
+import { FIRESTORE_ENGINE, firestoreCollectionPath, firestoreDatabaseLocator, SPANNER_ENGINE, } from '../../ids.js';
+/**
+ * The edges granted by the IAM bindings of the Cloud Run module blocks deploying a project.
+ *
+ * - A `publishes` edge from every service of the project to each broker topic of its `outputs.eventTopics`, when any
+ *   block grants the publisher role.
+ * - An `accesses` edge from every service of the project to each datastore of its outputs, when any block grants
+ *   access. Spanner access is granted on each database. Firestore access is granted on
+ *   the whole database, but is declared for the collections listed in the outputs: edges target the collections under
+ *   each listed root.
+ *
+ * @param graph The context of the extraction.
+ * @returns The edges granted by the blocks.
+ */
+export async function cloudRunGrants(graph) {
+    const { locator, context } = graph;
+    const [cloudRun, model] = await Promise.all([
+        graph.get(CloudRunFact),
+        graph.get(ModelFact),
+    ]);
+    const edges = [];
+    const warnings = [];
+    const firestoreDatabase = context
+        .asConfiguration()
+        .get('google.firestore.database');
+    const firestorePaths = [...model.entities.values()].flatMap((e) => {
+        const table = e.schema.definition.databases.find((d) => d.engine === FIRESTORE_ENGINE)?.table;
+        const path = table ? firestoreCollectionPath(table) : undefined;
+        return path ? [path] : [];
+    });
+    // What the project declares is granted to all its services as soon as one of its blocks grants it.
+    for (const [project, services] of Map.groupBy(cloudRun, (s) => s.project)) {
+        const configuration = project.context.asConfiguration();
+        const publisherBlocks = services
+            .filter((s) => s.setPubsubPermissions)
+            .map((s) => s.block.declaration);
+        if (publisherBlocks.length > 0) {
+            const topics = configuration.get('serviceContainer.outputs.eventTopics') ?? [];
+            for (const [index, topic] of topics.entries()) {
+                const source = await locator.configurationSource(project.context, [
+                    'serviceContainer',
+                    'outputs',
+                    'eventTopics',
+                    index,
+                ]);
+                for (const service of services) {
+                    edges.push({
+                        type: 'publishes',
+                        from: service.id,
+                        to: brokerTopicId(topic),
+                        sources: [...publisherBlocks, source],
+                    });
+                }
+            }
+        }
+        const outputs = configuration.get('serviceContainer.outputs', {
+            unsafe: true,
+        });
+        const spannerBlocks = services
+            .filter((s) => s.setSpannerPermissions)
+            .map((s) => s.block.declaration);
+        if (spannerBlocks.length > 0) {
+            const databases = (outputs?.[SPANNER_ENGINE] ?? []);
+            for (const [index, database] of databases.entries()) {
+                const source = await locator.configurationSource(project.context, [
+                    'serviceContainer',
+                    'outputs',
+                    SPANNER_ENGINE,
+                    index,
+                ]);
+                for (const service of services) {
+                    edges.push({
+                        type: 'accesses',
+                        from: service.id,
+                        to: databaseId(databaseLocator(SPANNER_ENGINE, database)),
+                        sources: [...spannerBlocks, source],
+                    });
+                }
+            }
+        }
+        const firestoreBlocks = services
+            .filter((s) => s.setFirestorePermissions)
+            .map((s) => s.block.declaration);
+        if (firestoreBlocks.length === 0 || !firestoreDatabase) {
+            continue;
+        }
+        const collections = (outputs?.[FIRESTORE_ENGINE] ?? []);
+        for (const [index, collection] of collections.entries()) {
+            const source = await locator.configurationSource(project.context, [
+                'serviceContainer',
+                'outputs',
+                FIRESTORE_ENGINE,
+                index,
+            ]);
+            const paths = new Set(firestorePaths.filter((p) => p.split('/')[0] === collection));
+            if (paths.size === 0) {
+                warnings.push({
+                    message: `Project '${project.name}' is granted Firestore access for '${collection}' but no schema binds to that collection.`,
+                    sources: [source],
+                });
+            }
+            for (const path of paths) {
+                for (const service of services) {
+                    edges.push({
+                        type: 'accesses',
+                        from: service.id,
+                        to: tableId(firestoreDatabaseLocator(firestoreDatabase), path),
+                        sources: [...firestoreBlocks, source],
+                    });
+                }
+            }
+        }
+    }
+    return { edges, warnings };
+}

package/dist/graph/rules/terraform/cloud-run-module.d.ts

@@ -0,0 +1,6 @@
+import { type GraphRule } from '@causa/workspace-core';
+/**
+ * The resources created by the blocks of the Cloud Run module, each part following a file of the module: the service,
+ * the Pub/Sub, tasks, and cron triggers, and the IAM grants.
+ */
+export declare const cloudRunModule: GraphRule;

package/dist/graph/rules/terraform/cloud-run-module.js

@@ -0,0 +1,29 @@
+import { GraphOriginKind, } from '@causa/workspace-core';
+import { cloudRunCronTriggers } from './cloud-run-cron-triggers.js';
+import { cloudRunGrants } from './cloud-run-grants.js';
+import { cloudRunPubSubTriggers } from './cloud-run-pubsub-triggers.js';
+import { cloudRunServices } from './cloud-run-services.js';
+import { cloudRunTasksTriggers } from './cloud-run-tasks-triggers.js';
+/**
+ * The resources created by the blocks of the Cloud Run module, each part following a file of the module: the service,
+ * the Pub/Sub, tasks, and cron triggers, and the IAM grants.
+ */
+export const cloudRunModule = {
+    name: 'cloudRunModule',
+    kind: GraphOriginKind.Declared,
+    description: 'The resources each Cloud Run module block creates: the `service` realizing the project read back from `configuration_file`, a push `brokerSubscription` per Pub/Sub trigger, a `queue` per task trigger, and a `scheduledJob` per cron trigger, with the edges between them, and the `publishes`, `accesses`, and `enqueues` edges its IAM bindings grant. Each resource is linked by a `deploys` edge from the projects applying the block.',
+    async run(graph) {
+        const outputs = await Promise.all([
+            cloudRunServices(graph),
+            cloudRunPubSubTriggers(graph),
+            cloudRunTasksTriggers(graph),
+            cloudRunCronTriggers(graph),
+            cloudRunGrants(graph),
+        ]);
+        return {
+            nodes: outputs.flatMap((o) => o.nodes ?? []),
+            edges: outputs.flatMap((o) => o.edges ?? []),
+            warnings: outputs.flatMap((o) => o.warnings ?? []),
+        };
+    },
+};

package/dist/graph/rules/terraform/cloud-run-pubsub-triggers.d.ts

@@ -0,0 +1,14 @@
+import { type GraphRuleOutput } from '@causa/workspace-core';
+import { type GraphContext } from '@causa/workspace-core/graph';
+/**
+ * A push `brokerSubscription` per Pub/Sub trigger of a project, for each Cloud Run module block deploying it with
+ * Pub/Sub triggers enabled. The locator is the trigger's. The module names the subscription `run-<service>-<trigger>`.
+ *
+ * Each subscription `realizes` its trigger, `targets` the service its module block deploys, and is delivered to by the
+ * broker topic of its trigger. A topic that no event schema of the workspace defines is created outside of it, and
+ * gets its own `brokerTopic` node.
+ *
+ * @param graph The context of the extraction.
+ * @returns The subscriptions, the external broker topics, and their edges.
+ */
+export declare function cloudRunPubSubTriggers(graph: GraphContext): Promise<GraphRuleOutput>;

package/dist/graph/rules/terraform/cloud-run-pubsub-triggers.js

@@ -0,0 +1,103 @@
+import {} from '@causa/workspace-core';
+import { brokerSubscriptionId, brokerTopicId, ModelFact, nodeId, triggerId, triggerLocator, } from '@causa/workspace-core/graph';
+import { terraformDeploys } from '@causa/workspace-terraform';
+import { CloudRunFact } from '../../cloud-run.js';
+import { blockResource } from '../../terraform-modules.js';
+/**
+ * A push `brokerSubscription` per Pub/Sub trigger of a project, for each Cloud Run module block deploying it with
+ * Pub/Sub triggers enabled. The locator is the trigger's. The module names the subscription `run-<service>-<trigger>`.
+ *
+ * Each subscription `realizes` its trigger, `targets` the service its module block deploys, and is delivered to by the
+ * broker topic of its trigger. A topic that no event schema of the workspace defines is created outside of it, and
+ * gets its own `brokerTopic` node.
+ *
+ * @param graph The context of the extraction.
+ * @returns The subscriptions, the external broker topics, and their edges.
+ */
+export async function cloudRunPubSubTriggers(graph) {
+    const { locator } = graph;
+    const [cloudRun, model] = await Promise.all([
+        graph.get(CloudRunFact),
+        graph.get(ModelFact),
+    ]);
+    const nodes = [];
+    const edges = [];
+    const warnings = [];
+    const subscriptions = new Set();
+    for (const service of cloudRun) {
+        const source = service.block.declaration;
+        for (const [name, trigger] of service.pubsubTriggers) {
+            const subscriptionLocator = triggerLocator(service.project.directory, name);
+            const subscriptionId = brokerSubscriptionId(subscriptionLocator);
+            if (subscriptions.has(subscriptionLocator)) {
+                warnings.push({
+                    message: `Trigger '${name}' of '${service.project.name}' is deployed with Pub/Sub triggers by several module blocks. A single subscription node stands for several subscriptions.`,
+                    sources: [source],
+                });
+            }
+            subscriptions.add(subscriptionLocator);
+            const filter = trigger['google.pubSub']?.filter;
+            const subscription = `run-${service.name}-${name}`;
+            const data = {
+                filter: typeof filter === 'string' ? filter : undefined,
+                resource: await blockResource(graph, service.block, {
+                    type: 'pubsub.googleapis.com/Subscription',
+                    scope: service.project,
+                    id: [
+                        'projects/',
+                        service.projectPart,
+                        `/subscriptions/${subscription}`,
+                    ],
+                }, warnings),
+            };
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'brokerSubscription',
+                locator: subscriptionLocator,
+                name: subscription,
+                sources: [
+                    source,
+                    await locator.configurationSource(service.project.context, [
+                        'serviceContainer',
+                        'triggers',
+                        name,
+                    ]),
+                ],
+                data,
+            });
+            edges.push(...terraformDeploys(service.block, nodeId('brokerSubscription', subscriptionLocator)), {
+                type: 'realizes',
+                from: subscriptionId,
+                to: triggerId(service.project.directory, name),
+                sources: [source],
+            }, {
+                type: 'targets',
+                from: subscriptionId,
+                to: service.id,
+                label: trigger.endpoint?.path,
+                sources: [source],
+            });
+            if (typeof trigger.topic !== 'string') {
+                continue;
+            }
+            const topicSource = await locator.configurationSource(service.project.context, ['serviceContainer', 'triggers', name, 'topic']);
+            edges.push({
+                type: 'delivers',
+                from: brokerTopicId(trigger.topic),
+                to: subscriptionId,
+                sources: [source, topicSource],
+            });
+            if (!model.topics.has(trigger.topic)) {
+                nodes.push({
+                    layer: 'infrastructure',
+                    type: 'brokerTopic',
+                    locator: trigger.topic,
+                    name: trigger.topic,
+                    description: 'A topic no event schema of the workspace defines, created outside of it.',
+                    sources: [topicSource],
+                });
+            }
+        }
+    }
+    return { nodes, edges, warnings };
+}

package/dist/graph/rules/terraform/cloud-run-services.d.ts

@@ -0,0 +1,12 @@
+import { type GraphRuleOutput } from '@causa/workspace-core';
+import { type GraphContext } from '@causa/workspace-core/graph';
+/**
+ * A `service` node per block of the Cloud Run module, and a `realizes` edge from it to the project whose configuration
+ * file the block reads. The service name is the block's `name` argument or the project name, and `platform` is the
+ * project's `serviceContainer.platform`. Blocks whose project cannot be found, and arguments that cannot be evaluated,
+ * are reported.
+ *
+ * @param graph The context of the extraction.
+ * @returns The services, and their edges.
+ */
+export declare function cloudRunServices(graph: GraphContext): Promise<GraphRuleOutput>;

package/dist/graph/rules/terraform/cloud-run-services.js

@@ -0,0 +1,61 @@
+import {} from '@causa/workspace-core';
+import { projectId, serviceLocator, } from '@causa/workspace-core/graph';
+import { terraformDeploys } from '@causa/workspace-terraform';
+import { CloudRunFact } from '../../cloud-run.js';
+import { blockResource } from '../../terraform-modules.js';
+/**
+ * A `service` node per block of the Cloud Run module, and a `realizes` edge from it to the project whose configuration
+ * file the block reads. The service name is the block's `name` argument or the project name, and `platform` is the
+ * project's `serviceContainer.platform`. Blocks whose project cannot be found, and arguments that cannot be evaluated,
+ * are reported.
+ *
+ * @param graph The context of the extraction.
+ * @returns The services, and their edges.
+ */
+export async function cloudRunServices(graph) {
+    const { locator } = graph;
+    const cloudRun = await graph.get(CloudRunFact);
+    const nodes = [];
+    const edges = [];
+    const warnings = [];
+    for (const service of cloudRun) {
+        const source = service.block.declaration;
+        const data = {
+            platform: service.project.context
+                .asConfiguration()
+                .get('serviceContainer.platform'),
+            resource: await blockResource(graph, service.block, {
+                type: 'run.googleapis.com/Service',
+                scope: service.project,
+                id: [
+                    'projects/',
+                    service.projectPart,
+                    '/locations/',
+                    service.locationPart,
+                    `/services/${service.name}`,
+                ],
+            }, warnings),
+        };
+        nodes.push({
+            layer: 'infrastructure',
+            type: 'service',
+            locator: serviceLocator(service.project.directory, service.name),
+            name: service.name,
+            sources: [
+                source,
+                await locator.configurationSource(service.project.context, [
+                    'project',
+                    'name',
+                ]),
+            ],
+            data,
+        });
+        edges.push(...terraformDeploys(service.block, service.id), {
+            type: 'realizes',
+            from: service.id,
+            to: projectId(service.project.directory),
+            sources: [source],
+        });
+    }
+    return { nodes, edges, warnings };
+}

package/dist/graph/rules/terraform/cloud-run-tasks-triggers.d.ts

@@ -0,0 +1,14 @@
+import { type GraphRuleOutput } from '@causa/workspace-core';
+import { type GraphContext } from '@causa/workspace-core/graph';
+/**
+ * The resources a Cloud Run module block creates for the task triggers of a project, when tasks triggers are enabled:
+ *
+ * - A `queue` node per `queue` of the task triggers. The module suffixes the queue name with a random string, such that
+ *   only a prefix of the resource name is known. The locator is the declared name. The queue `realizes` the task
+ *   triggers declaring it, and `targets` the service the block deploys, which is the HTTP target of the tasks.
+ * - An `enqueues` edge from every service of the project to each queue.
+ *
+ * @param graph The context of the extraction.
+ * @returns The queues, and their edges.
+ */
+export declare function cloudRunTasksTriggers(graph: GraphContext): Promise<GraphRuleOutput>;

package/dist/graph/rules/terraform/cloud-run-tasks-triggers.js

@@ -0,0 +1,97 @@
+import {} from '@causa/workspace-core';
+import { nodeId, queueId, triggerId, } from '@causa/workspace-core/graph';
+import { terraformDeploys } from '@causa/workspace-terraform';
+import { CloudRunFact } from '../../cloud-run.js';
+import { blockResource } from '../../terraform-modules.js';
+/**
+ * The resources a Cloud Run module block creates for the task triggers of a project, when tasks triggers are enabled:
+ *
+ * - A `queue` node per `queue` of the task triggers. The module suffixes the queue name with a random string, such that
+ *   only a prefix of the resource name is known. The locator is the declared name. The queue `realizes` the task
+ *   triggers declaring it, and `targets` the service the block deploys, which is the HTTP target of the tasks.
+ * - An `enqueues` edge from every service of the project to each queue.
+ *
+ * @param graph The context of the extraction.
+ * @returns The queues, and their edges.
+ */
+export async function cloudRunTasksTriggers(graph) {
+    const { locator } = graph;
+    const cloudRun = await graph.get(CloudRunFact);
+    const nodes = [];
+    const edges = [];
+    const warnings = [];
+    for (const service of cloudRun) {
+        const source = service.block.declaration;
+        for (const [name, trigger] of service.tasksTriggers) {
+            const queueSource = await locator.configurationSource(service.project.context, ['serviceContainer', 'triggers', name, 'queue']);
+            if (typeof trigger.queue !== 'string') {
+                warnings.push({
+                    message: `Task trigger '${name}' has no queue.`,
+                    sources: [queueSource],
+                });
+                continue;
+            }
+            const resource = await blockResource(graph, service.block, {
+                type: 'cloudtasks.googleapis.com/Queue',
+                scope: service.project,
+                prefix: true,
+                id: [
+                    'projects/',
+                    service.projectPart,
+                    '/locations/',
+                    service.locationPart,
+                    `/queues/${trigger.queue}-`,
+                ],
+            }, warnings);
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'queue',
+                locator: trigger.queue,
+                name: trigger.queue,
+                sources: [source, queueSource],
+                data: { resource },
+            });
+            edges.push(...terraformDeploys(service.block, nodeId('queue', trigger.queue)), {
+                type: 'realizes',
+                from: queueId(trigger.queue),
+                to: triggerId(service.project.directory, name),
+                sources: [source],
+            }, {
+                type: 'targets',
+                from: queueId(trigger.queue),
+                to: service.id,
+                label: trigger.endpoint?.path,
+                sources: [source],
+            });
+        }
+    }
+    for (const services of Map.groupBy(cloudRun, (s) => s.project).values()) {
+        for (const granting of services.filter((s) => s.setTasksPermissions)) {
+            const queues = new Map();
+            for (const [name, trigger] of granting.tasksTriggers) {
+                if (typeof trigger.queue === 'string' && !queues.has(trigger.queue)) {
+                    queues.set(trigger.queue, name);
+                }
+            }
+            for (const [queue, trigger] of queues) {
+                for (const service of services) {
+                    edges.push({
+                        type: 'enqueues',
+                        from: service.id,
+                        to: queueId(queue),
+                        sources: [
+                            granting.block.declaration,
+                            await locator.configurationSource(granting.project.context, [
+                                'serviceContainer',
+                                'triggers',
+                                trigger,
+                                'queue',
+                            ]),
+                        ],
+                    });
+                }
+            }
+        }
+    }
+    return { nodes, edges, warnings };
+}

package/dist/graph/rules/terraform/event-topics.d.ts

@@ -0,0 +1,18 @@
+import { type GraphRule } from '@causa/workspace-core';
+/**
+ * The source of the Causa Terraform module creating the Pub/Sub topics, and the raw events BigQuery tables.
+ */
+export declare const EVENT_TOPICS_MODULE_SOURCE = "causa-io/event-topics-pubsub/google";
+/**
+ * The resources created by the event topics module block.
+ *
+ * - A `brokerTopic` node per event topic, named by the topic ID: the module creates one Pub/Sub topic per topic listed
+ *   by `EventTopicList`. It `realizes` the event topic of the same ID.
+ * - When the block has a raw events dataset (`bigquery_raw_events_dataset`, or
+ *   `google.pubSub.bigQueryStorage.rawEventsDatasetId`), a `database` node for the BigQuery dataset, and for each
+ *   topic:
+ *   - A `table` node, named by the topic ID with `.` and `-` replaced by `_`.
+ *   - A BigQuery `brokerSubscription` node: the module creates one `bq-<topic>` subscription per topic, writing events
+ *     to the topic's raw table. The broker topic `delivers` to it, and it `targets` the table.
+ */
+export declare const eventTopicsModule: GraphRule;