@causa/runtime-google 0.36.0 → 0.37.0

package/dist/spanner/types.d.ts

@@ -1,6 +1,25 @@
+import type { SpannerReadOnlyTransaction, SpannerReadWriteTransaction } from './entity-manager.js';
 /**
  * A partial Spanner entity instance, where nested objects can also be partial.
  */
 export type RecursivePartialEntity<T> = T extends Date ? T : T extends object ? Partial<T> | {
     [P in keyof T]?: RecursivePartialEntity<T[P]>;
 } : T;
+/**
+ * Option for a function that accepts a Spanner read-only transaction.
+ */
+export type SpannerReadOnlyTransactionOption = {
+    /**
+     * The transaction to use.
+     */
+    readonly transaction?: SpannerReadOnlyTransaction;
+};
+/**
+ * Option for a function that accepts a Spanner read-write transaction.
+ */
+export type SpanerReadWriteTransactionOption = {
+    /**
+     * The transaction to use.
+     */
+    readonly transaction?: SpannerReadWriteTransaction;
+};

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

@@ -1,5 +1,5 @@
 export { SpannerOutboxEvent } from './event.js';
 export { SpannerOutboxTransactionModule } from './module.js';
 export { SpannerOutboxTransactionRunner } from './runner.js';
-export type { SpannerOutboxTransaction } from './runner.js';
+export type { SpannerOutboxTransaction, SpannerOutboxTransactionOption, } from './runner.js';
 export { SpannerOutboxSender } from './sender.js';

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

@@ -8,6 +8,15 @@ import { SpannerOutboxSender } from './sender.js';
  * A {@link SpannerTransaction} that uses an {@link OutboxEventTransaction}.
  */
 export type SpannerOutboxTransaction = SpannerTransaction<OutboxEventTransaction>;
+/**
+ * Option for a function that accepts a {@link SpannerOutboxTransaction}.
+ */
+export type SpannerOutboxTransactionOption = {
+    /**
+     * The transaction to use.
+     */
+    readonly transaction?: SpannerOutboxTransaction;
+};
 /**
  * An {@link OutboxTransactionRunner} that uses a {@link SpannerTransaction} to run transactions.
  * Events are stored in a Spanner table before being published.

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

@@ -63,9 +63,15 @@ export declare class SpannerOutboxSender extends OutboxEventSender {
      */
     readonly index: string | undefined;
     /**
-     * The SQL query used to fetch events from the outbox.
+     * The SQL query used to fetch (non-leased) events from the outbox.
+     * This should be run in a read-only transaction to avoid table-wide locking.
      */
     readonly fetchEventsSql: string;
+    /**
+     * The SQL query used to acquire a lease on events in the outbox.
+     * This is based on event IDs, that are checked again to have a null lease expiration.
+     */
+    readonly acquireLeaseSql: string;
     /**
      * The SQL query used to update events in the outbox after they have been successfully published.
      */
@@ -89,7 +95,7 @@ export declare class SpannerOutboxSender extends OutboxEventSender {
      *
      * @returns The SQL queries used to fetch and update events in the outbox.
      */
-    protected buildSql(): Pick<SpannerOutboxSender, 'fetchEventsSql' | 'successfulUpdateSql' | 'failedUpdateSql'>;
+    protected buildSql(): Pick<SpannerOutboxSender, 'fetchEventsSql' | 'acquireLeaseSql' | 'successfulUpdateSql' | 'failedUpdateSql'>;
     protected fetchEvents(): Promise<OutboxEvent[]>;
     protected updateOutbox(result: OutboxEventPublishResult): Promise<void>;
 }

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

@@ -33,9 +33,15 @@ export class SpannerOutboxSender extends OutboxEventSender {
      */
     index;
     /**
-     * The SQL query used to fetch events from the outbox.
+     * The SQL query used to fetch (non-leased) events from the outbox.
+     * This should be run in a read-only transaction to avoid table-wide locking.
      */
     fetchEventsSql;
+    /**
+     * The SQL query used to acquire a lease on events in the outbox.
+     * This is based on event IDs, that are checked again to have a null lease expiration.
+     */
+    acquireLeaseSql;
     /**
      * The SQL query used to update events in the outbox after they have been successfully published.
      */
@@ -64,6 +70,7 @@ export class SpannerOutboxSender extends OutboxEventSender {
         this.index = options.index;
         ({
             fetchEventsSql: this.fetchEventsSql,
+            acquireLeaseSql: this.acquireLeaseSql,
             successfulUpdateSql: this.successfulUpdateSql,
             failedUpdateSql: this.failedUpdateSql,
         } = this.buildSql());
@@ -76,27 +83,32 @@ export class SpannerOutboxSender extends OutboxEventSender {
     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`;
+        const noLeaseFilter = `\`${this.leaseExpirationColumn}\` IS NULL OR \`${this.leaseExpirationColumn}\` < @currentTime`;
+        let fetchFilter = noLeaseFilter;
         if (this.sharding) {
             const { column, count } = this.sharding;
-            filter = `${column} BETWEEN 0 AND ${count - 1} AND (${filter})`;
+            fetchFilter = `\`${column}\` BETWEEN 0 AND ${count - 1} AND (${fetchFilter})`;
         }
         const fetchEventsSql = `
+      SELECT
+        \`${this.idColumn}\` AS id,
+      FROM
+        ${tableWithIndex}
+      WHERE
+        ${fetchFilter}
+      LIMIT
+        @batchSize
+    `;
+        // This will not be run in the same transaction as `fetchEventsSql`. The `noLeaseFilter` is re-applied to avoid
+        // acquiring a lease on outbox events that have since been leased by another process.
+        const acquireLeaseSql = `
       UPDATE
         ${table}
       SET
         \`${this.leaseExpirationColumn}\` = @leaseExpiration
       WHERE
-        \`${this.idColumn}\` IN (
-          SELECT
-            \`${this.idColumn}\`
-          FROM
-            ${tableWithIndex}
-          WHERE
-            ${filter}
-          LIMIT
-            @batchSize
-        )
+        \`${this.idColumn}\` IN UNNEST(@ids)
+        AND (${noLeaseFilter})
       THEN RETURN
         ${this.entityManager.sqlColumns(this.outboxEventType)}`;
         const successfulUpdateSql = `
@@ -111,18 +123,29 @@ export class SpannerOutboxSender extends OutboxEventSender {
         \`${this.leaseExpirationColumn}\` = NULL
       WHERE
         \`${this.idColumn}\` IN UNNEST(@ids)`;
-        return { fetchEventsSql, successfulUpdateSql, failedUpdateSql };
+        return {
+            fetchEventsSql,
+            acquireLeaseSql,
+            successfulUpdateSql,
+            failedUpdateSql,
+        };
     }
     async fetchEvents() {
+        // Event IDs are first acquired in an (implicit) read-only transaction, to avoid a lock on the entire table.
+        const currentTime = new Date();
+        const eventIds = await this.entityManager.query({
+            sql: this.fetchEventsSql,
+            params: { currentTime, batchSize: this.batchSize },
+        });
+        if (eventIds.length === 0) {
+            return [];
+        }
+        const ids = eventIds.map(({ id }) => id);
         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 });
+            const params = { ids, leaseExpiration, currentTime };
+            return await this.entityManager.query({ transaction, entityType: this.outboxEventType }, { sql: this.acquireLeaseSql, params });
         });
     }
     async updateOutbox(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/runtime-google",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "An extension to the Causa runtime SDK (`@causa/runtime`), providing Google-specific features.",
   "repository": "github:causa-io/runtime-typescript-google",
   "license": "ISC",