@causa/runtime-google 1.5.3 → 1.6.0

package/README.md

@@ -82,12 +82,22 @@ The `PubSubPublisherModule` provides the `PubSub` client, as well as the `PubSub
 
 The `PubSubPublisher` requires the `PUBSUB_TOPIC_*` environment variables to be set for all the topics a service is expected to publish to. The name of the environment variables should be prefixed with `PUBSUB_TOPIC_`, followed by the topic full name in upper case, and using `_` as the only punctuation. For example, `my-domain.my-topic.v1` would become `PUBSUB_TOPIC_MY_DOMAIN_MY_TOPIC_V1`.
 
-For services being triggered by Pub/Sub messages, the `PubSubEventHandlerModule` can be used to automatically parse Pub/Sub messages coming from HTTP requests made by a Pub/Sub push subscription. Any route with a parameter decorated with `@EventBody` will trigger the `PubSubEventHandlerInterceptor`, and will receive the parsed event pushed by Pub/Sub.
+For services being triggered by Pub/Sub messages, the `PubSubEventHandlerInterceptor` automatically parses Pub/Sub messages coming from HTTP requests made by a Pub/Sub push subscription. If the interceptor is set up at the application level, any route with a parameter decorated with `@EventBody` will trigger the interceptor, and will receive the parsed event pushed by Pub/Sub. The `PubSubEventHandlerInterceptor.withSerializer` method should be used to create the interceptor with the desired serializer. It also allows defining whether the interceptor `isDefault`, i.e. whether `@UseEventHandler` is required on route handlers to apply the interceptor.
 
 The `PubSubHealthIndicator` is a `HealthIndicator` which can be used in a health check controller, such as the `GoogleHealthcheckModule`. It attempts to list topics using the Pub/Sub client to check connectivity to the Pub/Sub API.
 
 To test publishers, the `PubSubFixture` handles the creation and deletion of temporary topics, and provides `expect*` utilities to check for published messages. To test event handlers, it also provides the `makeRequester()` utility, which returns a function that can be used to make HTTP requests in the same way a Pub/Sub push subscription would.
 
+### Cloud Tasks
+
+The `CloudTasksEventHandlerInterceptor` handles HTTP requests triggered by Cloud Tasks. It parses task metadata from request headers into a `CloudTasksInfo` object, and validates the request body against the type decorated with `@EventBody`. The `@CloudTasksEventInfo` decorator can be used on a route handler parameter to retrieve the parsed `CloudTasksInfo`. The `CloudTasksEventHandlerInterceptor.withOptions` static method can be used to create the interceptor, defining whether it `isDefault`.
+
+### Cloud Scheduler
+
+The `CloudSchedulerEventHandlerInterceptor` handles HTTP requests triggered by Cloud Scheduler jobs. It parses scheduler job metadata from request headers into a `CloudSchedulerInfo` object. The `@CloudSchedulerEventInfo` decorator can be used on a route handler parameter to retrieve the parsed `CloudSchedulerInfo`. The `CloudSchedulerEventHandlerInterceptor.withOptions` static method can be used to create the interceptor, defining whether it `isDefault`.
+
+Because Cloud Scheduler jobs are often configured to not send a body, the `@EventBody` parameter can be typed as a plain `object`. In that case, body parsing and validation are skipped, and an empty object is returned.
+
 ### Spanner
 
 The `SpannerEntityManager` is an entity manager having some similarities with TypeORM, but with a much more limited feature set. It handles entity classes decorated using `@SpannerTable` and `@SpannerColumn`.

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './firestore/index.js';
 export * from './identity-platform/index.js';
 export * from './logging/index.js';
 export * from './pubsub/index.js';
+export * from './scheduler/index.js';
 export * from './spanner/index.js';
 export * from './tasks/index.js';
 export * from './transaction/index.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from './firestore/index.js';
 export * from './identity-platform/index.js';
 export * from './logging/index.js';
 export * from './pubsub/index.js';
+export * from './scheduler/index.js';
 export * from './spanner/index.js';
 export * from './tasks/index.js';
 export * from './transaction/index.js';

package/dist/pubsub/interceptor.d.ts

@@ -1,5 +1,5 @@
 import { type ObjectSerializer } from '@causa/runtime';
-import { BaseEventHandlerInterceptor, Logger, type ParsedEventRequest } from '@causa/runtime/nestjs';
+import { BaseEventHandlerInterceptor, type EventHandlerInterceptorOptions, Logger, type ParsedEventRequest } from '@causa/runtime/nestjs';
 import { type ExecutionContext, type Type } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import type { Request } from 'express';
@@ -34,7 +34,7 @@ declare class PubSubMessage {
  */
 export declare class PubSubEventHandlerInterceptor extends BaseEventHandlerInterceptor {
     protected readonly serializer: ObjectSerializer;
-    constructor(serializer: ObjectSerializer, reflector: Reflector, logger: Logger);
+    constructor(serializer: ObjectSerializer, reflector: Reflector, logger: Logger, options?: EventHandlerInterceptorOptions);
     /**
      * Parses the given request as the payload of a Pub/Sub push request.
      *
@@ -53,8 +53,9 @@ export declare class PubSubEventHandlerInterceptor extends BaseEventHandlerInter
      * This can be used with the `UseInterceptors` decorator.
      *
      * @param serializer The {@link ObjectSerializer} to use to deserialize the event data.
+     * @param options Options for the interceptor.
      * @returns A class that can be used as an interceptor for Pub/Sub event handlers.
      */
-    static withSerializer(serializer: ObjectSerializer): Type<PubSubEventHandlerInterceptor>;
+    static withSerializer(serializer: ObjectSerializer, options?: EventHandlerInterceptorOptions): Type<PubSubEventHandlerInterceptor>;
 }
 export {};

package/dist/pubsub/interceptor.js

@@ -82,8 +82,8 @@ __decorate([
  */
 let PubSubEventHandlerInterceptor = PubSubEventHandlerInterceptor_1 = class PubSubEventHandlerInterceptor extends BaseEventHandlerInterceptor {
     serializer;
-    constructor(serializer, reflector, logger) {
-        super(PUBSUB_EVENT_HANDLER_ID, reflector, logger);
+    constructor(serializer, reflector, logger, options = {}) {
+        super(PUBSUB_EVENT_HANDLER_ID, reflector, logger, options);
         this.serializer = serializer;
         this.logger.setContext(PubSubEventHandlerInterceptor_1.name);
     }
@@ -138,12 +138,13 @@ let PubSubEventHandlerInterceptor = PubSubEventHandlerInterceptor_1 = class PubS
      * This can be used with the `UseInterceptors` decorator.
      *
      * @param serializer The {@link ObjectSerializer} to use to deserialize the event data.
+     * @param options Options for the interceptor.
      * @returns A class that can be used as an interceptor for Pub/Sub event handlers.
      */
-    static withSerializer(serializer) {
+    static withSerializer(serializer, options = {}) {
         let PubSubEventHandlerInterceptorWithSerializer = class PubSubEventHandlerInterceptorWithSerializer extends PubSubEventHandlerInterceptor_1 {
             constructor(reflector, logger) {
-                super(serializer, reflector, logger);
+                super(serializer, reflector, logger, options);
             }
         };
         PubSubEventHandlerInterceptorWithSerializer = __decorate([
@@ -156,6 +157,6 @@ let PubSubEventHandlerInterceptor = PubSubEventHandlerInterceptor_1 = class PubS
 PubSubEventHandlerInterceptor = PubSubEventHandlerInterceptor_1 = __decorate([
     Injectable(),
     __metadata("design:paramtypes", [Object, Reflector,
-        Logger])
+        Logger, Object])
 ], PubSubEventHandlerInterceptor);
 export { PubSubEventHandlerInterceptor };

package/dist/pubsub/testing.d.ts

@@ -2,6 +2,7 @@ import { type ObjectSerializer } from '@causa/runtime';
 import type { AppFixture, EventFixture, Fixture, NestJsModuleOverrider } from '@causa/runtime/nestjs/testing';
 import { PubSub, Subscription, Topic } from '@google-cloud/pubsub';
 import { type Type } from '@nestjs/common';
+import 'jest-extended';
 /**
  * A received Pub/Sub message that was deserialized.
  */
@@ -28,6 +29,22 @@ export type ExpectMessageOptions = {
      * Defaults to `2000`.
      */
     timeout?: number;
+    /**
+     * When `true`, the received messages must exactly match the expected messages (same members), rather than merely
+     * including all of them.
+     * Defaults to `false`.
+     */
+    exact?: boolean;
+};
+/**
+ * Options for the {@link PubSubFixture.expectEvent} method.
+ */
+export type ExpectEventOptions = ExpectMessageOptions & {
+    /**
+     * The attributes expected to have been published with the event.
+     * This may contain only a subset of the attributes.
+     */
+    attributes?: Record<string, string>;
 };
 /**
  * Options when making a request to an endpoint handling Pub/Sub events using an {@link EventRequester}.
@@ -124,6 +141,23 @@ export declare class PubSubFixture implements Fixture, EventFixture {
          */
         expectedStatus?: number;
     }): EventRequester;
+    /**
+     * Gets the received messages for the specified topic.
+     *
+     * @param topic The original name of the event topic.
+     * @returns The received messages.
+     */
+    getReceivedMessages(topic: string): ReceivedPubSubEvent[];
+    /**
+     * Checks that the given messages have been published to the specified topic.
+     * Each expected message must match a distinct received message.
+     *
+     * @param topic The original name of the event topic.
+     * @param expectedMessages The messages expected to have been published.
+     *   Each can be an `expect` expression, e.g. `expect.objectContaining({})`.
+     * @param options Options for the expectation.
+     */
+    expectMessages(topic: string, expectedMessages: Partial<ReceivedPubSubEvent>[], options?: ExpectMessageOptions): Promise<void>;
     /**
      * Checks that the given message has been published to the specified topic.
      *
@@ -133,6 +167,16 @@ export declare class PubSubFixture implements Fixture, EventFixture {
      * @param options Options for the expectation.
      */
     expectMessage(topic: string, expectedMessage: any, options?: ExpectMessageOptions): Promise<void>;
+    /**
+     * Uses {@link PubSubFixture.expectMessages} to check that the given events have been published to the specified
+     * topic. Each element in `expectedEvents` is the payload of a message, i.e. the `event` property.
+     * If `attributes` are provided, all events are expected to share those attributes.
+     *
+     * @param topic The original name of the event topic.
+     * @param expectedEvents The events expected to have been published.
+     * @param options Options for the expectation.
+     */
+    expectEvents(topic: string, expectedEvents: any[], options?: ExpectEventOptions): Promise<void>;
     /**
      * Uses {@link PubSubFixture.expectMessage} to check that the given event has been published to the specified
      * topic. The `expectedEvent` is the payload of the message, i.e. the `event` property.
@@ -141,13 +185,7 @@ export declare class PubSubFixture implements Fixture, EventFixture {
      * @param expectedEvent The event expected to have been published.
      * @param options Options for the expectation.
      */
-    expectEvent(topic: string, expectedEvent: any, options?: ExpectMessageOptions & {
-        /**
-         * The attributes expected to have been published with the event.
-         * This may contain only a subset of the attributes.
-         */
-        attributes?: Record<string, string>;
-    }): Promise<void>;
+    expectEvent(topic: string, expectedEvent: any, options?: ExpectEventOptions): Promise<void>;
     /**
      * Checks that no message has been published to the given topic.
      * By default, because publishing (and receiving) the messages is asynchronous, a small delay is added before checking

package/dist/pubsub/testing.js

@@ -1,6 +1,7 @@
 import { JsonObjectSerializer } from '@causa/runtime';
 import { Message, PubSub, Subscription, Topic } from '@google-cloud/pubsub';
 import { HttpStatus } from '@nestjs/common';
+import 'jest-extended';
 import { setTimeout } from 'timers/promises';
 import * as uuid from 'uuid';
 import { getConfigurationKeyForTopic } from './configuration.js';
@@ -143,30 +144,46 @@ export class PubSubFixture {
         };
     }
     /**
-     * Checks that the given message has been published to the specified topic.
+     * Gets the received messages for the specified topic.
      *
      * @param topic The original name of the event topic.
-     * @param expectedMessage The message expected to have been published.
-     *   This can be an `expect` expression, e.g. `expect.objectContaining({})`.
-     * @param options Options for the expectation.
+     * @returns The received messages.
      */
-    async expectMessage(topic, expectedMessage, options = {}) {
+    getReceivedMessages(topic) {
         const fixture = this.topics[topic];
         if (!fixture) {
             throw new Error(`Fixture for topic '${topic}' does not exist.`);
         }
-        const timeoutTime = new Date().getTime() + (options.timeout ?? DEFAULT_EXPECT_TIMEOUT);
+        return fixture.messages;
+    }
+    /**
+     * Checks that the given messages have been published to the specified topic.
+     * Each expected message must match a distinct received message.
+     *
+     * @param topic The original name of the event topic.
+     * @param expectedMessages The messages expected to have been published.
+     *   Each can be an `expect` expression, e.g. `expect.objectContaining({})`.
+     * @param options Options for the expectation.
+     */
+    async expectMessages(topic, expectedMessages, options = {}) {
+        const timeoutTime = Date.now() + (options.timeout ?? DEFAULT_EXPECT_TIMEOUT);
         while (true) {
+            const actualMessages = this.getReceivedMessages(topic);
             try {
-                expect(fixture.messages).toContainEqual(expectedMessage);
+                if (options.exact) {
+                    expect(actualMessages).toIncludeSameMembers(expectedMessages);
+                }
+                else {
+                    expect(actualMessages).toIncludeAllMembers(expectedMessages);
+                }
                 return;
             }
             catch (e) {
-                if (new Date().getTime() >= timeoutTime) {
-                    if (fixture.messages.length === 1) {
-                        // This throws with a clearer message than `toContainEqual` because the single received message is actually
-                        // compared to the expected message.
-                        expect(fixture.messages[0]).toEqual(expectedMessage);
+                if (Date.now() >= timeoutTime) {
+                    if (expectedMessages.length === 1 && actualMessages.length === 1) {
+                        // This throws with a clearer message because the single received message is actually compared to the
+                        // expected message.
+                        expect(actualMessages[0]).toEqual(expectedMessages[0]);
                     }
                     throw e;
                 }
@@ -174,6 +191,30 @@ export class PubSubFixture {
             }
         }
     }
+    /**
+     * Checks that the given message has been published to the specified topic.
+     *
+     * @param topic The original name of the event topic.
+     * @param expectedMessage The message expected to have been published.
+     *   This can be an `expect` expression, e.g. `expect.objectContaining({})`.
+     * @param options Options for the expectation.
+     */
+    async expectMessage(topic, expectedMessage, options = {}) {
+        await this.expectMessages(topic, [expectedMessage], options);
+    }
+    /**
+     * Uses {@link PubSubFixture.expectMessages} to check that the given events have been published to the specified
+     * topic. Each element in `expectedEvents` is the payload of a message, i.e. the `event` property.
+     * If `attributes` are provided, all events are expected to share those attributes.
+     *
+     * @param topic The original name of the event topic.
+     * @param expectedEvents The events expected to have been published.
+     * @param options Options for the expectation.
+     */
+    async expectEvents(topic, expectedEvents, options = {}) {
+        const attributes = expect.objectContaining(options.attributes ?? {});
+        await this.expectMessages(topic, expectedEvents.map((event) => expect.objectContaining({ event, attributes })), options);
+    }
     /**
      * Uses {@link PubSubFixture.expectMessage} to check that the given event has been published to the specified
      * topic. The `expectedEvent` is the payload of the message, i.e. the `event` property.
@@ -183,10 +224,7 @@ export class PubSubFixture {
      * @param options Options for the expectation.
      */
     async expectEvent(topic, expectedEvent, options = {}) {
-        await this.expectMessage(topic, expect.objectContaining({
-            event: expectedEvent,
-            attributes: expect.objectContaining(options.attributes ?? {}),
-        }), options);
+        await this.expectEvents(topic, [expectedEvent], options);
     }
     /**
      * Checks that no message has been published to the given topic.
@@ -197,15 +235,11 @@ export class PubSubFixture {
      * @param options Options for the expectation.
      */
     async expectNoMessage(topic, options = {}) {
-        const fixture = this.topics[topic];
-        if (!fixture) {
-            throw new Error(`Fixture for topic '${topic}' does not exist.`);
-        }
         const delay = options.delay ?? DEFAULT_EXPECT_NO_MESSAGE_DELAY;
         if (delay > 0) {
             await setTimeout(delay);
         }
-        const numMessages = fixture.messages.length;
+        const numMessages = this.getReceivedMessages(topic).length;
         if (numMessages > 0) {
             throw new Error(`Expected 0 messages in '${topic}' but found ${numMessages}.`);
         }
@@ -236,5 +270,6 @@ export class PubSubFixture {
     async delete() {
         await Promise.all(Object.keys(this.topics).map((t) => this.deleteTopic(t)));
         await this.pubSub.close();
+        this.appFixture = undefined;
     }
 }

package/dist/scheduler/cloud-scheduler-info.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Information about a Cloud Scheduler job, extracted from HTTP headers.
+ */
+export declare class CloudSchedulerInfo {
+    /**
+     * The name of the Cloud Scheduler job.
+     */
+    readonly jobName: string;
+    /**
+     * The scheduled time for the job execution.
+     */
+    readonly scheduleTime?: Date;
+}

package/dist/scheduler/cloud-scheduler-info.js

@@ -0,0 +1,36 @@
+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 { AllowMissing, IsDateType } from '@causa/runtime';
+import { Expose } from 'class-transformer';
+import { IsString } from 'class-validator';
+/**
+ * Information about a Cloud Scheduler job, extracted from HTTP headers.
+ */
+export class CloudSchedulerInfo {
+    /**
+     * The name of the Cloud Scheduler job.
+     */
+    jobName;
+    /**
+     * The scheduled time for the job execution.
+     */
+    scheduleTime;
+}
+__decorate([
+    Expose({ name: 'x-cloudscheduler-jobname' }),
+    IsString(),
+    __metadata("design:type", String)
+], CloudSchedulerInfo.prototype, "jobName", void 0);
+__decorate([
+    Expose({ name: 'x-cloudscheduler-scheduletime' }),
+    IsDateType(),
+    AllowMissing(),
+    __metadata("design:type", Date)
+], CloudSchedulerInfo.prototype, "scheduleTime", void 0);

package/dist/scheduler/index.d.ts

@@ -0,0 +1,3 @@
+export { CloudSchedulerInfo } from './cloud-scheduler-info.js';
+export { CLOUD_SCHEDULER_EVENT_HANDLER_ID, CloudSchedulerEventHandlerInterceptor, } from './interceptor.js';
+export { CloudSchedulerEventInfo } from './scheduler-event-info.decorator.js';

package/dist/scheduler/index.js

@@ -0,0 +1,3 @@
+export { CloudSchedulerInfo } from './cloud-scheduler-info.js';
+export { CLOUD_SCHEDULER_EVENT_HANDLER_ID, CloudSchedulerEventHandlerInterceptor, } from './interceptor.js';
+export { CloudSchedulerEventInfo } from './scheduler-event-info.decorator.js';

package/dist/scheduler/interceptor.d.ts

@@ -0,0 +1,34 @@
+import { BaseEventHandlerInterceptor, type EventHandlerInterceptorOptions, Logger, type ParsedEventRequest } from '@causa/runtime/nestjs';
+import { type ExecutionContext, type Type } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Request } from 'express';
+import { CloudSchedulerInfo } from './cloud-scheduler-info.js';
+/**
+ * The ID of the Cloud Scheduler event handler interceptor, that can be passed to the `UseEventHandler` decorator.
+ */
+export declare const CLOUD_SCHEDULER_EVENT_HANDLER_ID = "google.cloudScheduler";
+/**
+ * The interceptor that should be added to controllers handling Cloud Scheduler events.
+ *
+ * Because Cloud Scheduler jobs are often configured to not send a body, the `@EventBody` parameter of route handlers
+ * can be typed as a plain `object`. In that case, body parsing and validation are skipped, and an empty object is
+ * returned.
+ */
+export declare class CloudSchedulerEventHandlerInterceptor extends BaseEventHandlerInterceptor {
+    constructor(reflector: Reflector, logger: Logger, options?: EventHandlerInterceptorOptions);
+    /**
+     * Parses the Cloud Scheduler request, extracting job information from headers.
+     *
+     * @param request The express request object.
+     * @returns The parsed Cloud Scheduler information.
+     */
+    protected parseCloudSchedulerRequest(request: Request): Promise<CloudSchedulerInfo>;
+    protected parseEventFromContext(context: ExecutionContext, dataType: Type): Promise<ParsedEventRequest>;
+    /**
+     * Creates a Cloud Scheduler event handler interceptor class with the given options.
+     *
+     * @param options Options for the interceptor.
+     * @returns The Cloud Scheduler event handler interceptor class.
+     */
+    static withOptions(options: EventHandlerInterceptorOptions): Type<CloudSchedulerEventHandlerInterceptor>;
+}

package/dist/scheduler/interceptor.js

@@ -0,0 +1,98 @@
+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);
+};
+var CloudSchedulerEventHandlerInterceptor_1;
+import { ValidationError, parseObject, validatorOptions } from '@causa/runtime';
+import { BadRequestErrorDto, BaseEventHandlerInterceptor, Logger, throwHttpErrorResponse, } from '@causa/runtime/nestjs';
+import { Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { CloudSchedulerInfo } from './cloud-scheduler-info.js';
+/**
+ * The ID of the Cloud Scheduler event handler interceptor, that can be passed to the `UseEventHandler` decorator.
+ */
+export const CLOUD_SCHEDULER_EVENT_HANDLER_ID = 'google.cloudScheduler';
+/**
+ * The interceptor that should be added to controllers handling Cloud Scheduler events.
+ *
+ * Because Cloud Scheduler jobs are often configured to not send a body, the `@EventBody` parameter of route handlers
+ * can be typed as a plain `object`. In that case, body parsing and validation are skipped, and an empty object is
+ * returned.
+ */
+let CloudSchedulerEventHandlerInterceptor = CloudSchedulerEventHandlerInterceptor_1 = class CloudSchedulerEventHandlerInterceptor extends BaseEventHandlerInterceptor {
+    constructor(reflector, logger, options = {}) {
+        super(CLOUD_SCHEDULER_EVENT_HANDLER_ID, reflector, logger, options);
+        this.logger.setContext(CloudSchedulerEventHandlerInterceptor_1.name);
+    }
+    /**
+     * Parses the Cloud Scheduler request, extracting job information from headers.
+     *
+     * @param request The express request object.
+     * @returns The parsed Cloud Scheduler information.
+     */
+    async parseCloudSchedulerRequest(request) {
+        try {
+            const info = await parseObject(CloudSchedulerInfo, request.headers, {
+                ...validatorOptions,
+                forbidNonWhitelisted: false,
+            });
+            this.logger.info('Successfully parsed Cloud Scheduler request.');
+            return info;
+        }
+        catch (error) {
+            this.logger.error({
+                error: error.stack,
+                ...(error instanceof ValidationError
+                    ? { validationMessages: error.validationMessages }
+                    : {}),
+            }, 'Received invalid Cloud Scheduler request.');
+            throwHttpErrorResponse(new BadRequestErrorDto());
+        }
+    }
+    async parseEventFromContext(context, dataType) {
+        const request = context
+            .switchToHttp()
+            .getRequest();
+        request.cloudSchedulerInfo = await this.parseCloudSchedulerRequest(request);
+        // This supports `@EventBody()` decorating a plain object type. This can be useful as bodies are often not needed
+        // for Cloud Scheduler jobs.
+        if (dataType === Object) {
+            return { attributes: {}, body: {} };
+        }
+        return await this.wrapParsing(async () => {
+            const body = await parseObject(dataType, request.body, {
+                forbidNonWhitelisted: false,
+            });
+            return { attributes: {}, body };
+        });
+    }
+    /**
+     * Creates a Cloud Scheduler event handler interceptor class with the given options.
+     *
+     * @param options Options for the interceptor.
+     * @returns The Cloud Scheduler event handler interceptor class.
+     */
+    static withOptions(options) {
+        let CloudSchedulerEventHandlerInterceptorWithOptions = class CloudSchedulerEventHandlerInterceptorWithOptions extends CloudSchedulerEventHandlerInterceptor_1 {
+            constructor(reflector, logger) {
+                super(reflector, logger, options);
+            }
+        };
+        CloudSchedulerEventHandlerInterceptorWithOptions = __decorate([
+            Injectable(),
+            __metadata("design:paramtypes", [Reflector, Logger])
+        ], CloudSchedulerEventHandlerInterceptorWithOptions);
+        return CloudSchedulerEventHandlerInterceptorWithOptions;
+    }
+};
+CloudSchedulerEventHandlerInterceptor = CloudSchedulerEventHandlerInterceptor_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [Reflector,
+        Logger, Object])
+], CloudSchedulerEventHandlerInterceptor);
+export { CloudSchedulerEventHandlerInterceptor };

package/dist/scheduler/scheduler-event-info.decorator.d.ts

@@ -0,0 +1,14 @@
+import type { CloudSchedulerInfo } from './cloud-scheduler-info.js';
+/**
+ * Additional information expected to be present on an express request that was parsed as a Cloud Scheduler request.
+ */
+export type RequestWithCloudSchedulerInfo = {
+    /**
+     * Information about the Cloud Scheduler job.
+     */
+    cloudSchedulerInfo: CloudSchedulerInfo;
+};
+/**
+ * Decorates a route handler's parameter to populate it with information about the Cloud Scheduler job.
+ */
+export declare const CloudSchedulerEventInfo: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/scheduler/scheduler-event-info.decorator.js

@@ -0,0 +1,10 @@
+import { createParamDecorator } from '@nestjs/common';
+/**
+ * Decorates a route handler's parameter to populate it with information about the Cloud Scheduler job.
+ */
+export const CloudSchedulerEventInfo = createParamDecorator((_data, ctx) => {
+    const request = ctx
+        .switchToHttp()
+        .getRequest();
+    return request.cloudSchedulerInfo;
+});

package/dist/scheduler/testing.d.ts

@@ -0,0 +1,41 @@
+import type { AppFixture, Fixture } from '@causa/runtime/nestjs/testing';
+import type { CloudSchedulerInfo } from './cloud-scheduler-info.js';
+/**
+ * Options when making a request to an endpoint handling Cloud Scheduler events using a {@link CloudSchedulerEventRequester}.
+ */
+export type CloudSchedulerEventRequesterOptions = {
+    /**
+     * The expected status code when making the request.
+     * Default is `200`.
+     */
+    readonly expectedStatus?: number;
+    /**
+     * The information about the Cloud Scheduler job to include in the request headers.
+     * If not provided, default values will be used.
+     */
+    readonly jobInfo?: Partial<CloudSchedulerInfo>;
+};
+/**
+ * A function that makes a query to an endpoint handling Cloud Scheduler events and tests the response.
+ */
+export type CloudSchedulerEventRequester = (event?: object, options?: CloudSchedulerEventRequesterOptions) => Promise<void>;
+/**
+ * A utility class for testing Cloud Scheduler event handlers.
+ */
+export declare class CloudSchedulerFixture implements Fixture {
+    /**
+     * The parent {@link AppFixture}.
+     */
+    private appFixture;
+    init(appFixture: AppFixture): Promise<undefined>;
+    /**
+     * Creates a {@link CloudSchedulerEventRequester} for an endpoint handling Cloud Scheduler events.
+     *
+     * @param endpoint The endpoint to query.
+     * @param options Options when creating the requester.
+     * @returns The {@link CloudSchedulerEventRequester}.
+     */
+    makeRequester(endpoint: string, options?: CloudSchedulerEventRequesterOptions): CloudSchedulerEventRequester;
+    clear(): Promise<void>;
+    delete(): Promise<void>;
+}

package/dist/scheduler/testing.js

@@ -0,0 +1,48 @@
+import { HttpStatus } from '@nestjs/common';
+/**
+ * A utility class for testing Cloud Scheduler event handlers.
+ */
+export class CloudSchedulerFixture {
+    /**
+     * The parent {@link AppFixture}.
+     */
+    appFixture;
+    async init(appFixture) {
+        this.appFixture = appFixture;
+    }
+    /**
+     * Creates a {@link CloudSchedulerEventRequester} for an endpoint handling Cloud Scheduler events.
+     *
+     * @param endpoint The endpoint to query.
+     * @param options Options when creating the requester.
+     * @returns The {@link CloudSchedulerEventRequester}.
+     */
+    makeRequester(endpoint, options = {}) {
+        return async (event, requestOptions) => {
+            const jobInfo = {
+                jobName: 'jobName',
+                ...options.jobInfo,
+                ...requestOptions?.jobInfo,
+            };
+            const headers = {
+                'x-cloudscheduler-jobname': jobInfo.jobName,
+            };
+            if (jobInfo.scheduleTime !== undefined) {
+                headers['x-cloudscheduler-scheduletime'] =
+                    jobInfo.scheduleTime.toISOString();
+            }
+            const expectedStatus = requestOptions?.expectedStatus ??
+                options.expectedStatus ??
+                HttpStatus.OK;
+            await this.appFixture.request
+                .post(endpoint)
+                .set(headers)
+                .send(event)
+                .expect(expectedStatus);
+        };
+    }
+    async clear() { }
+    async delete() {
+        this.appFixture = undefined;
+    }
+}

package/dist/spanner/entity-manager.d.ts

@@ -2,7 +2,7 @@ import { Database } from '@google-cloud/spanner';
 import type { ExecuteSqlRequest, TimestampBounds } from '@google-cloud/spanner/build/src/transaction.js';
 import { type Type } from '@nestjs/common';
 import { SpannerTableCache } from './table-cache.js';
-import type { SpannerKey, SpannerReadOnlyTransaction, SpannerReadOnlyTransactionOption, SpannerReadWriteTransaction, SpannerReadWriteTransactionOption, SqlParamType, SqlStatement } from './types.js';
+import type { SpannerKey, SpannerReadOnlyTransaction, SpannerReadOnlyTransactionOption, SpannerReadWriteTransaction, SpannerReadWriteTransactionOption, SqlParamFieldType, SqlParamType, SqlStatement } from './types.js';
 /**
  * Options for {@link SpannerEntityManager.snapshot}.
  */
@@ -291,6 +291,13 @@ export declare class SpannerEntityManager {
     static readonly ParamTypeJsonArray: SqlParamType;
     static readonly ParamTypeTimestampArray: SqlParamType;
     static readonly ParamTypeDateArray: SqlParamType;
+    static ParamTypeStructArray(...fields: SqlParamFieldType[]): {
+        type: string;
+        child: {
+            type: string;
+            fields: SqlParamFieldType[];
+        };
+    };
     /**
      * Converts the given entity or array of entities to Spanner objects, grouping them by table name.
      *

package/dist/spanner/entity-manager.js

@@ -12,7 +12,7 @@ import { Database, Snapshot } from '@google-cloud/spanner';
 import { Injectable } from '@nestjs/common';
 import { copyInstanceWithMissingColumnsToNull, instanceToSpannerObject, spannerObjectToInstance, updateInstanceByColumn, } from './conversion.js';
 import { convertSpannerToEntityError } from './error-converter.js';
-import { InvalidArgumentError, TransactionFinishedError } from './errors.js';
+import { InvalidArgumentError, TemporarySpannerError, TransactionFinishedError, } from './errors.js';
 import { SpannerTableCache } from './table-cache.js';
 /**
  * A class that manages access to entities stored in a Cloud Spanner database.
@@ -241,7 +241,11 @@ let SpannerEntityManager = class SpannerEntityManager {
                             transaction.end();
                         }
                     }
-                    throw error;
+                    // If the error was already converted and detected as temporary, the original Spanner error is thrown such
+                    // that the Spanner client can apply its retry logic. If it decides not to retry, the error will be
+                    // converted again outside the transaction.
+                    const isTemporaryWithCause = error instanceof TemporarySpannerError && error.cause;
+                    throw isTemporaryWithCause ? error.cause : error;
                 }
             });
         }
@@ -383,6 +387,9 @@ let SpannerEntityManager = class SpannerEntityManager {
         type: 'array',
         child: { type: 'date' },
     };
+    static ParamTypeStructArray(...fields) {
+        return { type: 'array', child: { type: 'struct', fields } };
+    }
     /**
      * Converts the given entity or array of entities to Spanner objects, grouping them by table name.
      *

package/dist/spanner/error-converter.js

@@ -1,7 +1,7 @@
-import { EntityAlreadyExistsError } from '@causa/runtime';
+import { EntityAlreadyExistsError, RetryableError } from '@causa/runtime';
 import { SessionPoolExhaustedError } from '@google-cloud/spanner/build/src/session-pool.js';
 import { status } from '@grpc/grpc-js';
-import { InvalidArgumentError, InvalidQueryError, TemporarySpannerError, } from './errors.js';
+import { InvalidArgumentError, InvalidQueryError, TemporarySpannerError, UnexpectedSpannerError, } from './errors.js';
 /**
  * Converts an error thrown by Spanner to an entity error or a Spanner error subclass.
  *
@@ -9,6 +9,11 @@ import { InvalidArgumentError, InvalidQueryError, TemporarySpannerError, } from
  * @returns The specific error, or undefined if it could not be converted.
  */
 export function convertSpannerToEntityError(error) {
+    // Those are errors that have already been converted (or that don't come from Spanner).
+    if (error instanceof RetryableError ||
+        error instanceof UnexpectedSpannerError) {
+        return;
+    }
     // Those are not gRPC errors and are thrown by the session pool.
     if (error instanceof SessionPoolExhaustedError ||
         error.message == 'Timeout occurred while acquiring session.') {
@@ -31,7 +36,9 @@ export function convertSpannerToEntityError(error) {
         case status.UNAVAILABLE:
         case status.ABORTED:
         case status.RESOURCE_EXHAUSTED:
-            return new TemporarySpannerError(error.message, error.code);
+            return new TemporarySpannerError(error.message, error.code, {
+                cause: error,
+            });
         default:
             return;
     }

package/dist/spanner/errors.d.ts

@@ -45,7 +45,7 @@ export declare class InvalidArgumentError extends UnexpectedSpannerError {
  */
 export declare class TemporarySpannerError extends RetryableError {
     readonly code?: status | undefined;
-    constructor(message: string, code?: status | undefined);
+    constructor(message: string, code?: status | undefined, options?: ErrorOptions);
     /**
      * Creates a new {@link TemporarySpannerError} that can be thrown to retry a transaction using the Spanner client
      * retry mechanism.

package/dist/spanner/errors.js

@@ -57,8 +57,8 @@ export class InvalidArgumentError extends UnexpectedSpannerError {
  */
 export class TemporarySpannerError extends RetryableError {
     code;
-    constructor(message, code) {
-        super(message);
+    constructor(message, code, options) {
+        super(message, undefined, options);
         this.code = code;
     }
     /**

package/dist/spanner/types.d.ts

@@ -1,6 +1,12 @@
 import { protos, Snapshot, Transaction } from '@google-cloud/spanner';
 import type { Type } from '@google-cloud/spanner/build/src/codec.js';
 export type SqlParamType = Type;
+/**
+ * The type of a single `STRUCT` field in a Spanner SQL parameter.
+ */
+export type SqlParamFieldType = Type & {
+    name: string;
+};
 export declare const SpannerRequestPriority: typeof protos.google.spanner.v1.RequestOptions.Priority;
 /**
  * A key for a Spanner row.

package/dist/tasks/cloud-tasks-info.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Information about a Cloud Tasks task, extracted from HTTP headers.
+ */
+export declare class CloudTasksInfo {
+    /**
+     * The name of the queue.
+     */
+    readonly queueName: string;
+    /**
+     * The short name of the task, or a unique system-generated ID if no name was specified at creation.
+     */
+    readonly taskName: string;
+    /**
+     * The number of times this task has been retried. For the first attempt, this value is `0`.
+     */
+    readonly retryCount: number;
+    /**
+     * The total number of times that the task has received a response from the handler.
+     */
+    readonly executionCount: number;
+    /**
+     * The schedule time of the task.
+     */
+    readonly eta: Date;
+    /**
+     * The HTTP response code from the previous retry.
+     * Only present if this is a retry attempt.
+     */
+    readonly previousResponse?: number;
+    /**
+     * The reason for retrying the task.
+     * Only present if this is a retry attempt.
+     */
+    readonly retryReason?: string;
+}

package/dist/tasks/cloud-tasks-info.js

@@ -0,0 +1,90 @@
+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 { AllowMissing } from '@causa/runtime';
+import { Expose, Transform } from 'class-transformer';
+import { IsDate, IsInt, IsString, Min } from 'class-validator';
+/**
+ * Information about a Cloud Tasks task, extracted from HTTP headers.
+ */
+export class CloudTasksInfo {
+    /**
+     * The name of the queue.
+     */
+    queueName;
+    /**
+     * The short name of the task, or a unique system-generated ID if no name was specified at creation.
+     */
+    taskName;
+    /**
+     * The number of times this task has been retried. For the first attempt, this value is `0`.
+     */
+    retryCount;
+    /**
+     * The total number of times that the task has received a response from the handler.
+     */
+    executionCount;
+    /**
+     * The schedule time of the task.
+     */
+    eta;
+    /**
+     * The HTTP response code from the previous retry.
+     * Only present if this is a retry attempt.
+     */
+    previousResponse;
+    /**
+     * The reason for retrying the task.
+     * Only present if this is a retry attempt.
+     */
+    retryReason;
+}
+__decorate([
+    Expose({ name: 'x-cloudtasks-queuename' }),
+    IsString(),
+    __metadata("design:type", String)
+], CloudTasksInfo.prototype, "queueName", void 0);
+__decorate([
+    Expose({ name: 'x-cloudtasks-taskname' }),
+    IsString(),
+    __metadata("design:type", String)
+], CloudTasksInfo.prototype, "taskName", void 0);
+__decorate([
+    Expose({ name: 'x-cloudtasks-taskretrycount' }),
+    Transform(({ value }) => parseInt(value)),
+    IsInt(),
+    Min(0),
+    __metadata("design:type", Number)
+], CloudTasksInfo.prototype, "retryCount", void 0);
+__decorate([
+    Expose({ name: 'x-cloudtasks-taskexecutioncount' }),
+    Transform(({ value }) => parseInt(value)),
+    IsInt(),
+    Min(0),
+    __metadata("design:type", Number)
+], CloudTasksInfo.prototype, "executionCount", void 0);
+__decorate([
+    Expose({ name: 'x-cloudtasks-tasketa' }),
+    Transform(({ value }) => new Date(parseFloat(value) * 1000)),
+    IsDate(),
+    __metadata("design:type", Date)
+], CloudTasksInfo.prototype, "eta", void 0);
+__decorate([
+    Expose({ name: 'x-cloudtasks-taskpreviousresponse' }),
+    Transform(({ value }) => (value !== undefined ? parseInt(value) : undefined)),
+    IsInt(),
+    AllowMissing(),
+    __metadata("design:type", Number)
+], CloudTasksInfo.prototype, "previousResponse", void 0);
+__decorate([
+    Expose({ name: 'x-cloudtasks-taskretryreason' }),
+    IsString(),
+    AllowMissing(),
+    __metadata("design:type", String)
+], CloudTasksInfo.prototype, "retryReason", void 0);

package/dist/tasks/index.d.ts

@@ -1,4 +1,7 @@
+export { CloudTasksInfo } from './cloud-tasks-info.js';
 export * from './errors.js';
+export { CLOUD_TASKS_EVENT_HANDLER_ID, CloudTasksEventHandlerInterceptor, } from './interceptor.js';
 export { CloudTasksModule } from './module.js';
 export { CloudTasksScheduler, HttpMethod } from './scheduler.js';
 export type { HttpRequest, Task } from './scheduler.js';
+export { CloudTasksEventInfo } from './task-event-info.decorator.js';

package/dist/tasks/index.js

@@ -1,3 +1,6 @@
+export { CloudTasksInfo } from './cloud-tasks-info.js';
 export * from './errors.js';
+export { CLOUD_TASKS_EVENT_HANDLER_ID, CloudTasksEventHandlerInterceptor, } from './interceptor.js';
 export { CloudTasksModule } from './module.js';
 export { CloudTasksScheduler, HttpMethod } from './scheduler.js';
+export { CloudTasksEventInfo } from './task-event-info.decorator.js';

package/dist/tasks/interceptor.d.ts

@@ -0,0 +1,30 @@
+import { BaseEventHandlerInterceptor, type EventHandlerInterceptorOptions, Logger, type ParsedEventRequest } from '@causa/runtime/nestjs';
+import { type ExecutionContext, type Type } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Request } from 'express';
+import { CloudTasksInfo } from './cloud-tasks-info.js';
+/**
+ * The ID of the Cloud Tasks event handler interceptor, that can passed to the `UseEventHandler` decorator.
+ */
+export declare const CLOUD_TASKS_EVENT_HANDLER_ID = "google.cloudTasks";
+/**
+ * The interceptor that should be added to controllers handling Cloud Tasks events.
+ */
+export declare class CloudTasksEventHandlerInterceptor extends BaseEventHandlerInterceptor {
+    constructor(reflector: Reflector, logger: Logger, options?: EventHandlerInterceptorOptions);
+    /**
+     * Parses the Cloud Tasks request, extracting task information from headers.
+     *
+     * @param request The express request object.
+     * @returns The parsed Cloud Tasks information.
+     */
+    protected parseCloudTasksRequest(request: Request): Promise<CloudTasksInfo>;
+    protected parseEventFromContext(context: ExecutionContext, dataType: Type): Promise<ParsedEventRequest>;
+    /**
+     * Creates a Cloud Tasks event handler interceptor class with the given options.
+     *
+     * @param options Options for the interceptor.
+     * @returns The Cloud Tasks event handler interceptor class.
+     */
+    static withOptions(options: EventHandlerInterceptorOptions): Type<CloudTasksEventHandlerInterceptor>;
+}

package/dist/tasks/interceptor.js

@@ -0,0 +1,90 @@
+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);
+};
+var CloudTasksEventHandlerInterceptor_1;
+import { ValidationError, parseObject, validatorOptions } from '@causa/runtime';
+import { BadRequestErrorDto, BaseEventHandlerInterceptor, Logger, throwHttpErrorResponse, } from '@causa/runtime/nestjs';
+import { Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { CloudTasksInfo } from './cloud-tasks-info.js';
+/**
+ * The ID of the Cloud Tasks event handler interceptor, that can passed to the `UseEventHandler` decorator.
+ */
+export const CLOUD_TASKS_EVENT_HANDLER_ID = 'google.cloudTasks';
+/**
+ * The interceptor that should be added to controllers handling Cloud Tasks events.
+ */
+let CloudTasksEventHandlerInterceptor = CloudTasksEventHandlerInterceptor_1 = class CloudTasksEventHandlerInterceptor extends BaseEventHandlerInterceptor {
+    constructor(reflector, logger, options = {}) {
+        super(CLOUD_TASKS_EVENT_HANDLER_ID, reflector, logger, options);
+        this.logger.setContext(CloudTasksEventHandlerInterceptor_1.name);
+    }
+    /**
+     * Parses the Cloud Tasks request, extracting task information from headers.
+     *
+     * @param request The express request object.
+     * @returns The parsed Cloud Tasks information.
+     */
+    async parseCloudTasksRequest(request) {
+        try {
+            const info = await parseObject(CloudTasksInfo, request.headers, {
+                ...validatorOptions,
+                forbidNonWhitelisted: false,
+            });
+            this.assignEventId(info.taskName);
+            this.logger.info('Successfully parsed Cloud Tasks request.');
+            return info;
+        }
+        catch (error) {
+            this.logger.error({
+                error: error.stack,
+                ...(error instanceof ValidationError
+                    ? { validationMessages: error.validationMessages }
+                    : {}),
+            }, 'Received invalid Cloud Tasks request.');
+            throwHttpErrorResponse(new BadRequestErrorDto());
+        }
+    }
+    async parseEventFromContext(context, dataType) {
+        const request = context
+            .switchToHttp()
+            .getRequest();
+        request.cloudTasksInfo = await this.parseCloudTasksRequest(request);
+        return await this.wrapParsing(async () => {
+            const body = await parseObject(dataType, request.body, {
+                forbidNonWhitelisted: false,
+            });
+            return { attributes: {}, body };
+        });
+    }
+    /**
+     * Creates a Cloud Tasks event handler interceptor class with the given options.
+     *
+     * @param options Options for the interceptor.
+     * @returns The Cloud Tasks event handler interceptor class.
+     */
+    static withOptions(options) {
+        let CloudTasksEventHandlerInterceptorWithOptions = class CloudTasksEventHandlerInterceptorWithOptions extends CloudTasksEventHandlerInterceptor_1 {
+            constructor(reflector, logger) {
+                super(reflector, logger, options);
+            }
+        };
+        CloudTasksEventHandlerInterceptorWithOptions = __decorate([
+            Injectable(),
+            __metadata("design:paramtypes", [Reflector, Logger])
+        ], CloudTasksEventHandlerInterceptorWithOptions);
+        return CloudTasksEventHandlerInterceptorWithOptions;
+    }
+};
+CloudTasksEventHandlerInterceptor = CloudTasksEventHandlerInterceptor_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [Reflector,
+        Logger, Object])
+], CloudTasksEventHandlerInterceptor);
+export { CloudTasksEventHandlerInterceptor };

package/dist/tasks/task-event-info.decorator.d.ts

@@ -0,0 +1,14 @@
+import type { CloudTasksInfo } from './cloud-tasks-info.js';
+/**
+ * Additional information expected to be present on an express request that was parsed as a Cloud Tasks request.
+ */
+export type RequestWithCloudTasksInfo = {
+    /**
+     * Information about the Cloud Tasks task.
+     */
+    cloudTasksInfo: CloudTasksInfo;
+};
+/**
+ * Decorates a route handler's parameter to populate it with information about the Cloud Tasks task.
+ */
+export declare const CloudTasksEventInfo: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/tasks/task-event-info.decorator.js

@@ -0,0 +1,8 @@
+import { createParamDecorator } from '@nestjs/common';
+/**
+ * Decorates a route handler's parameter to populate it with information about the Cloud Tasks task.
+ */
+export const CloudTasksEventInfo = createParamDecorator((_data, ctx) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.cloudTasksInfo;
+});

package/dist/tasks/testing.d.ts

@@ -0,0 +1,41 @@
+import type { AppFixture, Fixture } from '@causa/runtime/nestjs/testing';
+import type { CloudTasksInfo } from './cloud-tasks-info.js';
+/**
+ * Options when making a request to an endpoint handling Cloud Tasks events using a {@link CloudTasksEventRequester}.
+ */
+export type CloudTasksEventRequesterOptions = {
+    /**
+     * The expected status code when making the request.
+     * Default is `200`.
+     */
+    readonly expectedStatus?: number;
+    /**
+     * The information about the Cloud Tasks task to include in the request headers.
+     * If not provided, default values will be used.
+     */
+    readonly taskInfo?: Partial<CloudTasksInfo>;
+};
+/**
+ * A function that makes a query to an endpoint handling Cloud Tasks events and tests the response.
+ */
+export type CloudTasksEventRequester = (event: object, options?: CloudTasksEventRequesterOptions) => Promise<void>;
+/**
+ * A utility class for testing Cloud Tasks event handlers.
+ */
+export declare class CloudTasksFixture implements Fixture {
+    /**
+     * The parent {@link AppFixture}.
+     */
+    private appFixture;
+    init(appFixture: AppFixture): Promise<undefined>;
+    /**
+     * Creates a {@link CloudTasksEventRequester} for an endpoint handling Cloud Tasks events.
+     *
+     * @param endpoint The endpoint to query.
+     * @param options Options when creating the requester.
+     * @returns The {@link CloudTasksEventRequester}.
+     */
+    makeRequester(endpoint: string, options?: CloudTasksEventRequesterOptions): CloudTasksEventRequester;
+    clear(): Promise<void>;
+    delete(): Promise<void>;
+}

package/dist/tasks/testing.js

@@ -0,0 +1,59 @@
+import { HttpStatus } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+/**
+ * A utility class for testing Cloud Tasks event handlers.
+ */
+export class CloudTasksFixture {
+    /**
+     * The parent {@link AppFixture}.
+     */
+    appFixture;
+    async init(appFixture) {
+        this.appFixture = appFixture;
+    }
+    /**
+     * Creates a {@link CloudTasksEventRequester} for an endpoint handling Cloud Tasks events.
+     *
+     * @param endpoint The endpoint to query.
+     * @param options Options when creating the requester.
+     * @returns The {@link CloudTasksEventRequester}.
+     */
+    makeRequester(endpoint, options = {}) {
+        return async (event, requestOptions) => {
+            const taskInfo = {
+                queueName: 'queueName',
+                taskName: randomUUID(),
+                retryCount: 0,
+                executionCount: 0,
+                eta: new Date(),
+                ...options.taskInfo,
+                ...requestOptions?.taskInfo,
+            };
+            const headers = {
+                'x-cloudtasks-queuename': taskInfo.queueName,
+                'x-cloudtasks-taskname': taskInfo.taskName,
+                'x-cloudtasks-taskretrycount': String(taskInfo.retryCount),
+                'x-cloudtasks-taskexecutioncount': String(taskInfo.executionCount),
+                'x-cloudtasks-tasketa': (taskInfo.eta.getTime() / 1000).toFixed(3),
+            };
+            if (taskInfo.previousResponse !== undefined) {
+                headers['x-cloudtasks-taskpreviousresponse'] = String(taskInfo.previousResponse);
+            }
+            if (taskInfo.retryReason !== undefined) {
+                headers['x-cloudtasks-taskretryreason'] = taskInfo.retryReason;
+            }
+            const expectedStatus = requestOptions?.expectedStatus ??
+                options.expectedStatus ??
+                HttpStatus.OK;
+            await this.appFixture.request
+                .post(endpoint)
+                .set(headers)
+                .send(event)
+                .expect(expectedStatus);
+        };
+    }
+    async clear() { }
+    async delete() {
+        this.appFixture = undefined;
+    }
+}

package/dist/testing.js

@@ -3,7 +3,9 @@ import { VersionedEntityFixture } from '@causa/runtime/testing';
 import { FirestoreFixture } from './firestore/testing.js';
 import { AuthUsersFixture } from './identity-platform/testing.js';
 import { PubSubFixture } from './pubsub/testing.js';
+import { CloudSchedulerFixture } from './scheduler/testing.js';
 import { SpannerFixture } from './spanner/testing.js';
+import { CloudTasksFixture } from './tasks/testing.js';
 import { AppCheckFixture, FirebaseFixture } from './testing.js';
 import { FirestorePubSubTransactionRunner, SpannerOutboxTransactionRunner, } from './transaction/index.js';
 export * from './app-check/testing.js';
@@ -34,5 +36,7 @@ export function createGoogleFixtures(options = {}) {
         new PubSubFixture(options.pubSubTopics ?? {}),
         ...(disableAppCheck ? [new AppCheckFixture()] : []),
         ...versionedEntityFixture,
+        new CloudTasksFixture(),
+        new CloudSchedulerFixture(),
     ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/runtime-google",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "An extension to the Causa runtime SDK (`@causa/runtime`), providing Google-specific features.",
   "repository": {
     "type": "git",
@@ -32,15 +32,15 @@
     "test:cov": "npm run test -- --coverage"
   },
   "dependencies": {
-    "@causa/runtime": "^1.5.0",
+    "@causa/runtime": "^1.6.0",
     "@google-cloud/precise-date": "^5.0.0",
-    "@google-cloud/pubsub": "^5.2.1",
-    "@google-cloud/spanner": "^8.4.0",
+    "@google-cloud/pubsub": "^5.2.2",
+    "@google-cloud/spanner": "^8.5.0",
     "@google-cloud/tasks": "^6.2.1",
     "@grpc/grpc-js": "^1.14.3",
-    "@nestjs/common": "^11.1.11",
+    "@nestjs/common": "^11.1.12",
     "@nestjs/config": "^4.0.2",
-    "@nestjs/core": "^11.1.11",
+    "@nestjs/core": "^11.1.12",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/terminus": "^11.0.0",
     "class-transformer": "^0.5.1",
@@ -49,31 +49,31 @@
     "firebase-admin": "^13.6.0",
     "jsonwebtoken": "^9.0.3",
     "passport-http-bearer": "^1.0.1",
-    "pino": "^10.1.1",
+    "pino": "^10.3.0",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@nestjs/testing": "^11.1.11",
-    "@swc/core": "^1.15.8",
+    "@nestjs/testing": "^11.1.12",
+    "@swc/core": "^1.15.10",
     "@swc/jest": "^0.2.39",
     "@tsconfig/node20": "^20.1.8",
     "@types/jest": "^30.0.0",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^20.19.28",
+    "@types/node": "^20.19.30",
     "@types/passport-http-bearer": "^1.0.42",
     "@types/supertest": "^6.0.3",
     "@types/uuid": "^11.0.0",
     "dotenv": "^17.2.3",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-prettier": "^5.5.5",
     "jest": "^30.2.0",
     "jest-extended": "^7.0.0",
     "pino-pretty": "^13.1.3",
     "rimraf": "^6.1.2",
     "supertest": "^7.2.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.52.0",
+    "typescript-eslint": "^8.53.1",
     "uuid": "^13.0.0"
   }
 }