@causa/runtime-google 0.33.1 → 0.35.0

package/dist/transaction/spanner-outbox/module.js

@@ -0,0 +1,91 @@
+import { EVENT_PUBLISHER_INJECTION_NAME, Logger } from '@causa/runtime/nestjs';
+import { ConfigService } from '@nestjs/config';
+import { SpannerEntityManager } from '../../spanner/index.js';
+import { SpannerOutboxEvent } from './event.js';
+import { SpannerOutboxTransactionRunner } from './runner.js';
+import { SpannerOutboxSender, } from './sender.js';
+/**
+ * Combines options passed to the module with the configuration (from the environment).
+ *
+ * @param options Options passed to the module.
+ * @param config The {@link ConfigService} to use.
+ * @returns The parsed {@link SpannerOutboxSenderOptions}.
+ */
+function parseSenderOptions(options, config) {
+    function validateIntOrUndefined(name) {
+        const strValue = config.get(name);
+        if (strValue === undefined) {
+            return undefined;
+        }
+        const value = parseInt(strValue);
+        if (isNaN(value)) {
+            throw new Error(`Environment variable ${name} must be a number.`);
+        }
+        return value;
+    }
+    const batchSize = validateIntOrUndefined('SPANNER_OUTBOX_BATCH_SIZE');
+    const pollingInterval = validateIntOrUndefined('SPANNER_OUTBOX_POLLING_INTERVAL');
+    const idColumn = config.get('SPANNER_OUTBOX_ID_COLUMN');
+    const leaseExpirationColumn = config.get('SPANNER_OUTBOX_LEASE_EXPIRATION_COLUMN');
+    const index = config.get('SPANNER_OUTBOX_INDEX');
+    const shardingColumn = config.get('SPANNER_OUTBOX_SHARDING_COLUMN');
+    const shardingCount = validateIntOrUndefined('SPANNER_OUTBOX_SHARDING_COUNT');
+    const leaseDuration = validateIntOrUndefined('SPANNER_OUTBOX_LEASE_DURATION');
+    const sharding = shardingColumn && shardingCount
+        ? { column: shardingColumn, count: shardingCount }
+        : undefined;
+    const envOptions = {
+        batchSize,
+        pollingInterval,
+        idColumn,
+        leaseExpirationColumn,
+        index,
+        sharding,
+        leaseDuration,
+    };
+    return { ...envOptions, ...options };
+}
+/**
+ * The module providing the {@link SpannerOutboxTransactionRunner}.
+ * This assumes the `SpannerModule` and an {@link EventPublisher} are available (as well as the `LoggerModule`).
+ */
+export class SpannerOutboxTransactionModule {
+    /**
+     * Initializes the {@link SpannerOutboxTransactionModule} with the given options.
+     * The returned module is always global.
+     *
+     * @param options Options for the {@link SpannerOutboxTransactionModule}.
+     * @returns The module.
+     */
+    static forRoot(options = {}) {
+        const { outboxEventType, ...senderOptions } = {
+            outboxEventType: SpannerOutboxEvent,
+            ...options,
+        };
+        return {
+            module: SpannerOutboxTransactionModule,
+            global: true,
+            providers: [
+                {
+                    provide: SpannerOutboxSender,
+                    useFactory: (entityManager, publisher, logger, config) => {
+                        const options = parseSenderOptions(senderOptions, config);
+                        return new SpannerOutboxSender(entityManager, outboxEventType, publisher, logger, options);
+                    },
+                    inject: [
+                        SpannerEntityManager,
+                        EVENT_PUBLISHER_INJECTION_NAME,
+                        Logger,
+                        ConfigService,
+                    ],
+                },
+                {
+                    provide: SpannerOutboxTransactionRunner,
+                    useFactory: (entityManager, sender, logger) => new SpannerOutboxTransactionRunner(entityManager, outboxEventType, sender, logger),
+                    inject: [SpannerEntityManager, SpannerOutboxSender, Logger],
+                },
+            ],
+            exports: [SpannerOutboxTransactionRunner],
+        };
+    }
+}

package/dist/transaction/spanner-outbox/runner.d.ts

@@ -0,0 +1,19 @@
+import { OutboxTransactionRunner, type OutboxEvent, type OutboxEventTransaction } from '@causa/runtime';
+import { Logger } from '@causa/runtime/nestjs';
+import type { Type } from '@nestjs/common';
+import { SpannerEntityManager } from '../../spanner/index.js';
+import { SpannerTransaction } from '../spanner-transaction.js';
+import { SpannerOutboxSender } from './sender.js';
+/**
+ * A {@link SpannerTransaction} that uses an {@link OutboxEventTransaction}.
+ */
+export type SpannerOutboxTransaction = SpannerTransaction<OutboxEventTransaction>;
+/**
+ * An {@link OutboxTransactionRunner} that uses a {@link SpannerTransaction} to run transactions.
+ * Events are stored in a Spanner table before being published.
+ */
+export declare class SpannerOutboxTransactionRunner extends OutboxTransactionRunner<SpannerOutboxTransaction> {
+    readonly entityManager: SpannerEntityManager;
+    constructor(entityManager: SpannerEntityManager, outboxEventType: Type<OutboxEvent>, sender: SpannerOutboxSender, logger: Logger);
+    protected runStateTransaction<RT>(eventTransaction: OutboxEventTransaction, runFn: (transaction: SpannerOutboxTransaction) => Promise<RT>): Promise<RT>;
+}

package/dist/transaction/spanner-outbox/runner.js

@@ -0,0 +1,31 @@
+import { OutboxTransactionRunner, } from '@causa/runtime';
+import { Logger } from '@causa/runtime/nestjs';
+import { SpannerEntityManager } from '../../spanner/index.js';
+import { SpannerStateTransaction } from '../spanner-state-transaction.js';
+import { SpannerTransaction } from '../spanner-transaction.js';
+import { throwRetryableInTransactionIfNeeded } from '../spanner-utils.js';
+import { SpannerOutboxSender } from './sender.js';
+/**
+ * An {@link OutboxTransactionRunner} that uses a {@link SpannerTransaction} to run transactions.
+ * Events are stored in a Spanner table before being published.
+ */
+export class SpannerOutboxTransactionRunner extends OutboxTransactionRunner {
+    entityManager;
+    constructor(entityManager, outboxEventType, sender, logger) {
+        super(outboxEventType, sender, logger);
+        this.entityManager = entityManager;
+    }
+    async runStateTransaction(eventTransaction, runFn) {
+        return await this.entityManager.transaction(async (dbTransaction) => {
+            const stateTransaction = new SpannerStateTransaction(this.entityManager, dbTransaction);
+            const transaction = new SpannerTransaction(stateTransaction, eventTransaction);
+            try {
+                return await runFn(transaction);
+            }
+            catch (error) {
+                await throwRetryableInTransactionIfNeeded(error);
+                throw error;
+            }
+        });
+    }
+}

package/dist/transaction/spanner-outbox/sender.d.ts

@@ -0,0 +1,95 @@
+import { OutboxEventSender, type EventPublisher, type OutboxEvent, type OutboxEventPublishResult, type OutboxEventSenderOptions } from '@causa/runtime';
+import { Logger } from '@causa/runtime/nestjs';
+import type { Type } from '@nestjs/common';
+import { SpannerEntityManager } from '../../spanner/index.js';
+/**
+ * Sharding options for the {@link SpannerOutboxSender}.
+ */
+export type SpannerOutboxSenderShardingOptions = {
+    /**
+     * The name of the column used for sharding.
+     */
+    readonly column: string;
+    /**
+     * The number of shards.
+     */
+    readonly count: number;
+};
+/**
+ * Options for the {@link SpannerOutboxSender}.
+ */
+export type SpannerOutboxSenderOptions = OutboxEventSenderOptions & {
+    /**
+     * Sharding options.
+     * If not set, queries to fetch events will not use sharding.
+     */
+    readonly sharding?: SpannerOutboxSenderShardingOptions;
+    /**
+     * The name of the column used to store the event ID.
+     * Defaults to `id`.
+     */
+    readonly idColumn?: string;
+    /**
+     * The name of the column used to store the lease expiration.
+     * Defaults to `leaseExpiration`.
+     */
+    readonly leaseExpirationColumn?: string;
+    /**
+     * The index used to fetch events.
+     */
+    readonly index?: string;
+};
+/**
+ * An {@link OutboxEventSender} that uses a Spanner table to store events.
+ */
+export declare class SpannerOutboxSender extends OutboxEventSender {
+    readonly entityManager: SpannerEntityManager;
+    readonly outboxEventType: Type<OutboxEvent>;
+    /**
+     * Sharding options.
+     * If `null`, queries to fetch events will not use sharding.
+     */
+    readonly sharding: SpannerOutboxSenderShardingOptions | undefined;
+    /**
+     * The name of the column used for the {@link OutboxEvent.id} property.
+     */
+    readonly idColumn: string;
+    /**
+     * The name of the column used for the {@link OutboxEvent.leaseExpiration} property.
+     */
+    readonly leaseExpirationColumn: string;
+    /**
+     * The index used to fetch events.
+     */
+    readonly index: string | undefined;
+    /**
+     * The SQL query used to fetch events from the outbox.
+     */
+    readonly fetchEventsSql: string;
+    /**
+     * The SQL query used to update events in the outbox after they have been successfully published.
+     */
+    readonly successfulUpdateSql: string;
+    /**
+     * The SQL query used to update events in the outbox after they have failed to be published.
+     */
+    readonly failedUpdateSql: string;
+    /**
+     * Creates a new {@link SpannerOutboxSender}.
+     *
+     * @param entityManager The {@link SpannerEntityManager} to use to access the outbox.
+     * @param outboxEventType The type for the Spanner table used to store outbox events.
+     * @param publisher The {@link EventPublisher} to use to publish events.
+     * @param logger The {@link Logger} to use.
+     * @param options Options for the {@link SpannerOutboxSender}.
+     */
+    constructor(entityManager: SpannerEntityManager, outboxEventType: Type<OutboxEvent>, publisher: EventPublisher, logger: Logger, options?: SpannerOutboxSenderOptions);
+    /**
+     * Builds the SQL queries used to fetch and update events in the outbox based on the options.
+     *
+     * @returns The SQL queries used to fetch and update events in the outbox.
+     */
+    protected buildSql(): Pick<SpannerOutboxSender, 'fetchEventsSql' | 'successfulUpdateSql' | 'failedUpdateSql'>;
+    protected fetchEvents(): Promise<OutboxEvent[]>;
+    protected updateOutbox(result: OutboxEventPublishResult): Promise<void>;
+}

package/dist/transaction/spanner-outbox/sender.js

@@ -0,0 +1,150 @@
+import { OutboxEventSender, } from '@causa/runtime';
+import { Logger } from '@causa/runtime/nestjs';
+import { SpannerEntityManager } from '../../spanner/index.js';
+/**
+ * The default name for the {@link OutboxEvent.id} column.
+ */
+const DEFAULT_ID_COLUMN = 'id';
+/**
+ * The default name for the {@link OutboxEvent.leaseExpiration} column.
+ */
+const DEFAULT_LEASE_EXPIRATION_COLUMN = 'leaseExpiration';
+/**
+ * An {@link OutboxEventSender} that uses a Spanner table to store events.
+ */
+export class SpannerOutboxSender extends OutboxEventSender {
+    entityManager;
+    outboxEventType;
+    /**
+     * Sharding options.
+     * If `null`, queries to fetch events will not use sharding.
+     */
+    sharding;
+    /**
+     * The name of the column used for the {@link OutboxEvent.id} property.
+     */
+    idColumn;
+    /**
+     * The name of the column used for the {@link OutboxEvent.leaseExpiration} property.
+     */
+    leaseExpirationColumn;
+    /**
+     * The index used to fetch events.
+     */
+    index;
+    /**
+     * The SQL query used to fetch events from the outbox.
+     */
+    fetchEventsSql;
+    /**
+     * The SQL query used to update events in the outbox after they have been successfully published.
+     */
+    successfulUpdateSql;
+    /**
+     * The SQL query used to update events in the outbox after they have failed to be published.
+     */
+    failedUpdateSql;
+    /**
+     * Creates a new {@link SpannerOutboxSender}.
+     *
+     * @param entityManager The {@link SpannerEntityManager} to use to access the outbox.
+     * @param outboxEventType The type for the Spanner table used to store outbox events.
+     * @param publisher The {@link EventPublisher} to use to publish events.
+     * @param logger The {@link Logger} to use.
+     * @param options Options for the {@link SpannerOutboxSender}.
+     */
+    constructor(entityManager, outboxEventType, publisher, logger, options = {}) {
+        super(publisher, logger, options);
+        this.entityManager = entityManager;
+        this.outboxEventType = outboxEventType;
+        this.sharding = options.sharding;
+        this.idColumn = options.idColumn ?? DEFAULT_ID_COLUMN;
+        this.leaseExpirationColumn =
+            options.leaseExpirationColumn ?? DEFAULT_LEASE_EXPIRATION_COLUMN;
+        this.index = options.index;
+        ({
+            fetchEventsSql: this.fetchEventsSql,
+            successfulUpdateSql: this.successfulUpdateSql,
+            failedUpdateSql: this.failedUpdateSql,
+        } = this.buildSql());
+    }
+    /**
+     * Builds the SQL queries used to fetch and update events in the outbox based on the options.
+     *
+     * @returns The SQL queries used to fetch and update events in the outbox.
+     */
+    buildSql() {
+        const table = this.entityManager.sqlTableName(this.outboxEventType);
+        const tableWithIndex = this.entityManager.sqlTableName(this.outboxEventType, { index: this.index });
+        let filter = `${this.leaseExpirationColumn} IS NULL OR ${this.leaseExpirationColumn} < @currentTime`;
+        if (this.sharding) {
+            const { column, count } = this.sharding;
+            filter = `${column} BETWEEN 0 AND ${count - 1} AND (${filter})`;
+        }
+        const fetchEventsSql = `
+      UPDATE
+        ${table}
+      SET
+        \`${this.leaseExpirationColumn}\` = @leaseExpiration
+      WHERE
+        \`${this.idColumn}\` IN (
+          SELECT
+            \`${this.idColumn}\`
+          FROM
+            ${tableWithIndex}
+          WHERE
+            ${filter}
+          LIMIT
+            @batchSize
+        )
+      THEN RETURN
+        ${this.entityManager.sqlColumns(this.outboxEventType)}`;
+        const successfulUpdateSql = `
+      DELETE FROM
+        ${table}
+      WHERE
+        \`${this.idColumn}\` IN UNNEST(@ids)`;
+        const failedUpdateSql = `
+      UPDATE
+        ${table}
+      SET
+        \`${this.leaseExpirationColumn}\` = NULL
+      WHERE
+        \`${this.idColumn}\` IN UNNEST(@ids)`;
+        return { fetchEventsSql, successfulUpdateSql, failedUpdateSql };
+    }
+    async fetchEvents() {
+        return await this.entityManager.transaction(async (transaction) => {
+            const currentTime = new Date();
+            const leaseExpiration = new Date(currentTime.getTime() + this.leaseDuration);
+            const params = {
+                leaseExpiration,
+                currentTime,
+                batchSize: this.batchSize,
+            };
+            return await this.entityManager.query({ transaction, entityType: this.outboxEventType }, { sql: this.fetchEventsSql, params });
+        });
+    }
+    async updateOutbox(result) {
+        const successfulSends = [];
+        const failedSends = [];
+        Object.entries(result).forEach(([id, success]) => (success ? successfulSends : failedSends).push(id));
+        const batchUpdates = [];
+        if (successfulSends.length > 0) {
+            batchUpdates.push({
+                sql: this.successfulUpdateSql,
+                params: { ids: successfulSends },
+            });
+        }
+        if (failedSends.length > 0) {
+            batchUpdates.push({
+                sql: this.failedUpdateSql,
+                params: { ids: failedSends },
+            });
+        }
+        if (batchUpdates.length === 0) {
+            return;
+        }
+        await this.entityManager.transaction((transaction) => transaction.batchUpdate(batchUpdates));
+    }
+}

package/dist/transaction/spanner-pubsub/index.d.ts

@@ -1,4 +1,2 @@
 export { SpannerPubSubTransactionModule } from './module.js';
 export { SpannerPubSubTransactionRunner } from './runner.js';
-export { SpannerStateTransaction } from './state-transaction.js';
-export { SpannerPubSubTransaction } from './transaction.js';

package/dist/transaction/spanner-pubsub/index.js

@@ -1,4 +1,2 @@
 export { SpannerPubSubTransactionModule } from './module.js';
 export { SpannerPubSubTransactionRunner } from './runner.js';
-export { SpannerStateTransaction } from './state-transaction.js';
-export { SpannerPubSubTransaction } from './transaction.js';

package/dist/transaction/spanner-pubsub/runner.d.ts

@@ -2,12 +2,12 @@ import { TransactionRunner } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
 import { PubSubPublisher } from '../../pubsub/index.js';
 import { SpannerEntityManager } from '../../spanner/index.js';
-import { SpannerPubSubTransaction } from './transaction.js';
+import { SpannerTransaction } from '../spanner-transaction.js';
 /**
  * A {@link TransactionRunner} that uses Spanner for state and Pub/Sub for events.
  * A Spanner transaction is used as the main transaction. If it succeeds, events are published to Pub/Sub outside of it.
  */
-export declare class SpannerPubSubTransactionRunner extends TransactionRunner<SpannerPubSubTransaction> {
+export declare class SpannerPubSubTransactionRunner extends TransactionRunner<SpannerTransaction> {
     readonly entityManager: SpannerEntityManager;
     readonly publisher: PubSubPublisher;
     private readonly logger;
@@ -19,5 +19,5 @@ export declare class SpannerPubSubTransactionRunner extends TransactionRunner<Sp
      * @param logger The {@link Logger} to use.
      */
     constructor(entityManager: SpannerEntityManager, publisher: PubSubPublisher, logger: Logger);
-    run<T>(runFn: (transaction: SpannerPubSubTransaction) => Promise<T>): Promise<[T]>;
+    run<T>(runFn: (transaction: SpannerTransaction) => Promise<T>): Promise<[T]>;
 }

package/dist/transaction/spanner-pubsub/runner.js

@@ -7,23 +7,20 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { BufferEventTransaction, TransactionOldTimestampError, TransactionRunner, } from '@causa/runtime';
+var SpannerPubSubTransactionRunner_1;
+import { BufferEventTransaction, TransactionRunner } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
 import { Injectable } from '@nestjs/common';
-import { setTimeout } from 'timers/promises';
 import { PubSubPublisher } from '../../pubsub/index.js';
-import { SpannerEntityManager, TemporarySpannerError, } from '../../spanner/index.js';
-import { SpannerStateTransaction } from './state-transaction.js';
-import { SpannerPubSubTransaction } from './transaction.js';
-/**
- * The delay, in milliseconds, over which a timestamp issue is deemed irrecoverable.
- */
-const ACCEPTABLE_PAST_DATE_DELAY = 25000;
+import { SpannerEntityManager } from '../../spanner/index.js';
+import { SpannerStateTransaction } from '../spanner-state-transaction.js';
+import { SpannerTransaction } from '../spanner-transaction.js';
+import { throwRetryableInTransactionIfNeeded } from '../spanner-utils.js';
 /**
  * A {@link TransactionRunner} that uses Spanner for state and Pub/Sub for events.
  * A Spanner transaction is used as the main transaction. If it succeeds, events are published to Pub/Sub outside of it.
  */
-let SpannerPubSubTransactionRunner = class SpannerPubSubTransactionRunner extends TransactionRunner {
+let SpannerPubSubTransactionRunner = SpannerPubSubTransactionRunner_1 = class SpannerPubSubTransactionRunner extends TransactionRunner {
     entityManager;
     publisher;
     logger;
@@ -39,6 +36,7 @@ let SpannerPubSubTransactionRunner = class SpannerPubSubTransactionRunner extend
         this.entityManager = entityManager;
         this.publisher = publisher;
         this.logger = logger;
+        this.logger.setContext(SpannerPubSubTransactionRunner_1.name);
     }
     async run(runFn) {
         this.logger.info('Creating a Spanner Pub/Sub transaction.');
@@ -46,28 +44,15 @@ let SpannerPubSubTransactionRunner = class SpannerPubSubTransactionRunner extend
             const stateTransaction = new SpannerStateTransaction(this.entityManager, dbTransaction);
             // This must be inside the Spanner transaction because staged messages should be cleared when the transaction is retried.
             const eventTransaction = new BufferEventTransaction(this.publisher);
-            const transaction = new SpannerPubSubTransaction(stateTransaction, eventTransaction);
+            const transaction = new SpannerTransaction(stateTransaction, eventTransaction);
             try {
                 const result = await runFn(transaction);
                 this.logger.info('Committing the Spanner transaction.');
                 return { result, eventTransaction };
             }
             catch (error) {
-                // `TransactionOldTimestampError`s indicate that the transaction is using a timestamp older than what is
-                // observed in the state (Spanner).
-                // Throwing a `SpannerTransactionOldTimestampError` will cause the transaction to be retried with a newer
-                // timestamp.
-                if (!(error instanceof TransactionOldTimestampError)) {
-                    throw error;
-                }
-                const delay = error.delay ?? Infinity;
-                if (delay >= ACCEPTABLE_PAST_DATE_DELAY) {
-                    throw error;
-                }
-                if (delay > 0) {
-                    await setTimeout(delay);
-                }
-                throw TemporarySpannerError.retryableInTransaction(error.message);
+                await throwRetryableInTransactionIfNeeded(error);
+                throw error;
             }
         });
         this.logger.info('Publishing Pub/Sub events.');
@@ -75,7 +60,7 @@ let SpannerPubSubTransactionRunner = class SpannerPubSubTransactionRunner extend
         return [result];
     }
 };
-SpannerPubSubTransactionRunner = __decorate([
+SpannerPubSubTransactionRunner = SpannerPubSubTransactionRunner_1 = __decorate([
     Injectable(),
     __metadata("design:paramtypes", [SpannerEntityManager,
         PubSubPublisher,

package/dist/transaction/{spanner-pubsub/state-transaction.d.ts → spanner-state-transaction.d.ts}

@@ -1,20 +1,19 @@
 import type { FindReplaceStateTransaction } from '@causa/runtime';
-import { Transaction as SpannerTransaction } from '@google-cloud/spanner';
 import type { Type } from '@nestjs/common';
-import { SpannerEntityManager } from '../../spanner/index.js';
+import { SpannerEntityManager, type SpannerReadWriteTransaction } from '../spanner/index.js';
 /**
  * A {@link FindReplaceStateTransaction} that uses Spanner for state storage.
  */
 export declare class SpannerStateTransaction implements FindReplaceStateTransaction {
     readonly entityManager: SpannerEntityManager;
-    readonly transaction: SpannerTransaction;
+    readonly transaction: SpannerReadWriteTransaction;
     /**
      * Creates a new {@link SpannerStateTransaction}.
      *
      * @param entityManager The {@link SpannerEntityManager} to use to access entities in the state.
-     * @param transaction The {@link SpannerTransaction} to use for the transaction.
+     * @param transaction The {@link SpannerReadWriteTransaction} to use for the transaction.
      */
-    constructor(entityManager: SpannerEntityManager, transaction: SpannerTransaction);
+    constructor(entityManager: SpannerEntityManager, transaction: SpannerReadWriteTransaction);
     replace<T extends object>(entity: T): Promise<void>;
     deleteWithSameKeyAs<T extends object>(type: Type<T>, key: Partial<T>): Promise<void>;
     findOneWithSameKeyAs<T extends object>(type: Type<T>, entity: Partial<T>): Promise<T | undefined>;

package/dist/transaction/{spanner-pubsub/state-transaction.js → spanner-state-transaction.js}

@@ -1,5 +1,4 @@
-import { Transaction as SpannerTransaction } from '@google-cloud/spanner';
-import { SpannerEntityManager } from '../../spanner/index.js';
+import { SpannerEntityManager, } from '../spanner/index.js';
 /**
  * A {@link FindReplaceStateTransaction} that uses Spanner for state storage.
  */
@@ -10,7 +9,7 @@ export class SpannerStateTransaction {
      * Creates a new {@link SpannerStateTransaction}.
      *
      * @param entityManager The {@link SpannerEntityManager} to use to access entities in the state.
-     * @param transaction The {@link SpannerTransaction} to use for the transaction.
+     * @param transaction The {@link SpannerReadWriteTransaction} to use for the transaction.
      */
     constructor(entityManager, transaction) {
         this.entityManager = entityManager;

package/dist/transaction/spanner-transaction.d.ts

@@ -0,0 +1,16 @@
+import { type EventTransaction, Transaction } from '@causa/runtime';
+import { SpannerEntityManager, type SpannerReadWriteTransaction } from '../spanner/index.js';
+import { SpannerStateTransaction } from './spanner-state-transaction.js';
+/**
+ * A {@link Transaction} that uses Spanner for state storage, and any available {@link EventTransaction} implementation.
+ */
+export declare class SpannerTransaction<ET extends EventTransaction = EventTransaction> extends Transaction<SpannerStateTransaction, ET> {
+    /**
+     * The underlying {@link SpannerTransaction} used by the state transaction.
+     */
+    get spannerTransaction(): SpannerReadWriteTransaction;
+    /**
+     * The underlying {@link SpannerEntityManager} used by the state transaction.
+     */
+    get entityManager(): SpannerEntityManager;
+}

package/dist/transaction/spanner-transaction.js

@@ -0,0 +1,20 @@
+import { Transaction } from '@causa/runtime';
+import { SpannerEntityManager, } from '../spanner/index.js';
+import { SpannerStateTransaction } from './spanner-state-transaction.js';
+/**
+ * A {@link Transaction} that uses Spanner for state storage, and any available {@link EventTransaction} implementation.
+ */
+export class SpannerTransaction extends Transaction {
+    /**
+     * The underlying {@link SpannerTransaction} used by the state transaction.
+     */
+    get spannerTransaction() {
+        return this.stateTransaction.transaction;
+    }
+    /**
+     * The underlying {@link SpannerEntityManager} used by the state transaction.
+     */
+    get entityManager() {
+        return this.stateTransaction.entityManager;
+    }
+}

package/dist/transaction/spanner-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks if the given error is a `TransactionOldTimestampError` and throws a `TemporarySpannerError` such that the
+ * transaction can be retried by the runner.
+ * If the {@link TransactionOldTimestampError.delay} is too large, the error is deemed irrecoverable and nothing is
+ * thrown (it is up to the caller to handle the error).
+ *
+ * @param error The error to test.
+ */
+export declare function throwRetryableInTransactionIfNeeded(error: unknown): Promise<void>;

package/dist/transaction/spanner-utils.js

@@ -0,0 +1,31 @@
+import { TransactionOldTimestampError } from '@causa/runtime';
+import { setTimeout } from 'timers/promises';
+import { TemporarySpannerError } from '../spanner/index.js';
+/**
+ * The delay, in milliseconds, over which a timestamp issue is deemed irrecoverable.
+ */
+const ACCEPTABLE_PAST_DATE_DELAY = 25000;
+/**
+ * Checks if the given error is a `TransactionOldTimestampError` and throws a `TemporarySpannerError` such that the
+ * transaction can be retried by the runner.
+ * If the {@link TransactionOldTimestampError.delay} is too large, the error is deemed irrecoverable and nothing is
+ * thrown (it is up to the caller to handle the error).
+ *
+ * @param error The error to test.
+ */
+export async function throwRetryableInTransactionIfNeeded(error) {
+    // `TransactionOldTimestampError`s indicate that the transaction is using a timestamp older than what is
+    // observed in the state (Spanner).
+    if (!(error instanceof TransactionOldTimestampError)) {
+        return;
+    }
+    const delay = error.delay ?? Infinity;
+    if (delay >= ACCEPTABLE_PAST_DATE_DELAY) {
+        return;
+    }
+    if (delay > 0) {
+        await setTimeout(delay);
+    }
+    // Throwing a `TemporarySpannerError` will cause the transaction to be retried with a newer timestamp.
+    throw TemporarySpannerError.retryableInTransaction(error.message);
+}