@relaybus/postgres 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -39,6 +39,41 @@ function inBudgetedTransaction(state, {
   });
 }
 
+// src/transaction-isolation.ts
+var ISOLATION_KEYWORDS = {
+  "read committed": "READ COMMITTED",
+  "repeatable read": "REPEATABLE READ",
+  serializable: "SERIALIZABLE"
+};
+function isolationKeywords(isolationLevel) {
+  const keywords = Object.hasOwn(ISOLATION_KEYWORDS, isolationLevel) ? ISOLATION_KEYWORDS[isolationLevel] : void 0;
+  if (keywords === void 0) {
+    throw new core.ConfigurationError(`Unknown isolation level ${JSON.stringify(isolationLevel)}`);
+  }
+  return keywords;
+}
+function inIsolatedTransaction(state, {
+  work,
+  timeoutMs,
+  isolationLevel
+}) {
+  const { executor } = state;
+  if (executor.transactionWithIsolation !== void 0) {
+    return executor.transactionWithIsolation(work, { isolationLevel, timeoutMs });
+  }
+  const keywords = isolationKeywords(isolationLevel);
+  const budget = budgetSettingsSql({
+    value: "$1",
+    sessionTimeouts: executor.sessionTimeouts === true,
+    scope: "transaction"
+  });
+  return executor.transaction(async (transaction) => {
+    await executor.query(`SET TRANSACTION ISOLATION LEVEL ${keywords}`, [], transaction);
+    await state.query({ sql: budget, parameters: [budgetValue(timeoutMs)], transaction });
+    return work(transaction);
+  });
+}
+
 // src/pg-executor.ts
 var FOREIGN_SESSION_ERRORS = /* @__PURE__ */ new Set(["26000", "42P05"]);
 var STATEMENT_NAME_DIGITS = 24;
@@ -69,14 +104,28 @@ var PgExecutor = class {
    * connection that already keeps this budget only gets `BEGIN`.
    */
   transactionWithBudget(work, timeoutMs) {
+    return this.#transaction(work, this.#budgetStart(timeoutMs, "BEGIN"));
+  }
+  /**
+   * Like {@link PgExecutor.transactionWithBudget} with `BEGIN ISOLATION LEVEL ...`: the level is set
+   * with the `BEGIN` of the same simple query, before the budget's first statement.
+   */
+  transactionWithIsolation(work, { isolationLevel, timeoutMs }) {
+    return this.#transaction(
+      work,
+      this.#budgetStart(timeoutMs, `BEGIN ISOLATION LEVEL ${isolationKeywords(isolationLevel)}`)
+    );
+  }
+  /** How a transaction starts on a connection when it is held to `timeoutMs`; `begin` is the `BEGIN` statement. */
+  #budgetStart(timeoutMs, begin) {
     const value = budgetValue(timeoutMs);
     const settings = (scope) => budgetSettingsSql({ value: `'${value}'`, sessionTimeouts: true, scope });
-    return this.#transaction(work, (client) => {
+    return (client) => {
       if (!this.#keepsSessionBudget()) {
-        return { begin: `BEGIN; ${settings("transaction")}` };
+        return { begin: `${begin}; ${settings("transaction")}` };
       }
-      return this.#sessionValues.get(client) === value ? { begin: "BEGIN" } : { begin: `BEGIN; ${settings("session")}`, sessionValue: value };
-    });
+      return this.#sessionValues.get(client) === value ? { begin } : { begin: `${begin}; ${settings("session")}`, sessionValue: value };
+    };
   }
   #recordSession(client, sessionValue) {
     if (sessionValue === null) {
@@ -230,6 +279,7 @@ function resolvePostgresNames(options = {}) {
     schema,
     quotedSchema,
     events: table("events"),
+    eventsTableName: name("events"),
     deliveries: table("deliveries"),
     keySequences: table("key_sequences"),
     lanes: table("lanes"),
@@ -256,8 +306,17 @@ function laneExpression(keyExpression, eventIdExpression) {
 
 // src/schema.ts
 var SCHEMA_MARKER_DIGITS = 32;
+var PAYLOAD_COLUMNS = `  payload json NOT NULL,
+  headers json NOT NULL DEFAULT '{}'::json,`;
+var JSONB_PAYLOAD_COLUMNS = `  payload jsonb NOT NULL,
+  headers jsonb NOT NULL DEFAULT '{}'::jsonb,`;
 function createPostgresSchemaStatements(options = {}) {
   const names = resolvePostgresNames(options);
+  const statements = schemaBodyStatements(names);
+  statements.push(`COMMENT ON TABLE ${names.lanes} IS '${version040Marker(names, statements)}'`);
+  return statements;
+}
+function schemaBodyStatements(names) {
   const statements = [...eventAndDeliveryStatements(names), ...laneAndCompletionStatements(names)];
   if (names.completionHistory) {
     statements.push(...completionHistoryStatements(names));
@@ -265,7 +324,6 @@ function createPostgresSchemaStatements(options = {}) {
   if (names.schema !== "public") {
     statements.unshift(`CREATE SCHEMA IF NOT EXISTS ${names.quotedSchema}`);
   }
-  statements.push(`COMMENT ON TABLE ${names.lanes} IS '${postgresSchemaMarker(statements)}'`);
   return statements;
 }
 function eventAndDeliveryStatements(names) {
@@ -279,14 +337,14 @@ function eventAndKeySequenceStatements(names) {
   source text NOT NULL,
   key text,
   sequence bigint,
-  payload jsonb NOT NULL,
-  headers jsonb NOT NULL DEFAULT '{}'::jsonb,
+${PAYLOAD_COLUMNS}
   correlation_id text,
   causation_id text,
   occurred_at timestamptz NOT NULL,
   created_at timestamptz NOT NULL,
   handlers text[] NOT NULL DEFAULT '{}'
 )`,
+    upgradePayloadToJson(names),
     `CREATE INDEX IF NOT EXISTS ${names.indexes.eventCreated} ON ${names.events} (created_at, id)`,
     `CREATE TABLE IF NOT EXISTS ${names.keySequences} (
   key text PRIMARY KEY,
@@ -382,6 +440,33 @@ BEGIN
 END
 $relaybus_upgrade$`;
 }
+function upgradePayloadToJson(names) {
+  return `DO $relaybus_payload_json$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_attribute
+    WHERE attrelid = to_regclass('${names.events}') AND attname IN ('payload', 'headers')
+      AND atttypid = 'jsonb'::regtype AND NOT attisdropped
+  ) THEN
+    ALTER TABLE ${names.events}
+      ALTER COLUMN headers DROP DEFAULT,
+      ALTER COLUMN payload TYPE json USING payload::json,
+      ALTER COLUMN headers TYPE json USING headers::json,
+      ALTER COLUMN headers SET DEFAULT '{}'::json;
+  END IF;
+END
+$relaybus_payload_json$`;
+}
+function version040SchemaMarker(options = {}) {
+  const names = resolvePostgresNames(options);
+  return version040Marker(names, schemaBodyStatements(names));
+}
+function version040Marker(names, statements) {
+  const conversion = upgradePayloadToJson(names);
+  return postgresSchemaMarker(
+    statements.filter((statement) => statement !== conversion).map((statement) => statement.replace(PAYLOAD_COLUMNS, JSONB_PAYLOAD_COLUMNS))
+  );
+}
 function createPostgresSchemaSql(options = {}) {
   return `${createPostgresSchemaStatements(options).join(";\n\n")};
 `;
@@ -502,10 +587,38 @@ function withRootPool(executor, root) {
     ...executor.transactionWithBudget === void 0 ? {} : {
       transactionWithBudget: (work, timeoutMs) => executor.transactionWithBudget(work, timeoutMs)
     },
+    ...executor.transactionWithIsolation === void 0 ? {} : {
+      transactionWithIsolation: (work, options) => executor.transactionWithIsolation(work, options)
+    },
+    ...executor.isSerializationFailure === void 0 ? {} : { isSerializationFailure: (error) => executor.isSerializationFailure(error) },
     // eslint-disable-next-line relaybus/max-two-params -- PostgresExecutor port signature
     query: (sql, parameters, transaction, options) => transaction === void 0 ? root.query(sql, parameters, void 0, options) : executor.query(sql, parameters, transaction, options)
   };
 }
+
+// src/serialization-failure.ts
+var SERIALIZATION_FAILURE = "40001";
+var PRISMA_WRITE_CONFLICT = "P2034";
+var CONFLICT_CODES = /* @__PURE__ */ new Set([
+  SERIALIZATION_FAILURE,
+  PRISMA_WRITE_CONFLICT
+]);
+var MAXIMUM_DEPTH = 6;
+var WRAPPED_ERROR_KEYS = ["cause", "driverError", "originalError"];
+function isPostgresSerializationFailure(error, depth = 0) {
+  if (typeof error !== "object" || error === null || depth > MAXIMUM_DEPTH) {
+    return false;
+  }
+  const shape = error;
+  if (CONFLICT_CODES.has(shape.code) || shape.originalCode === SERIALIZATION_FAILURE) {
+    return true;
+  }
+  const meta = shape.meta;
+  if (isPostgresSerializationFailure(meta, depth + 1) || isPostgresSerializationFailure(meta?.driverAdapterError, depth + 1)) {
+    return true;
+  }
+  return WRAPPED_ERROR_KEYS.some((key) => isPostgresSerializationFailure(shape[key], depth + 1));
+}
 function text(row, column) {
   return row[column];
 }
@@ -1446,6 +1559,67 @@ var PostgresMaintenance = class {
     });
   }
 };
+
+// src/postgres-setup.ts
+var PostgresSetup = class {
+  #state;
+  /** The conversion of `jsonb` payload columns. */
+  #payloadUpgrade;
+  constructor(state, options) {
+    this.#state = state;
+    this.#payloadUpgrade = upgradePayloadToJson(resolvePostgresNames(options));
+  }
+  /** Implements {@link PostgresEventStore.setup}. */
+  async run() {
+    if (isCurrent(await this.#schemaState())) {
+      return;
+    }
+    await this.#underSetupLock(async (transaction) => {
+      await this.#run(this.#payloadUpgrade, transaction);
+    });
+    await this.#underSetupLock(async (transaction, schema) => {
+      if (schema.marked) {
+        await this.#run(this.#payloadUpgrade, transaction);
+        return;
+      }
+      for (const statement of this.#state.schemaStatements) {
+        await this.#run(statement, transaction);
+      }
+    });
+  }
+  /**
+   * Runs `work` in a transaction under the setup lock, unless the schema became current. The
+   * payload conversion goes first in a transaction of its own, so it holds no other table lock
+   * while it waits for the event table (a completion locks deliveries before the event rows).
+   */
+  async #underSetupLock(work) {
+    await this.#state.executor.transaction(async (transaction) => {
+      await this.#state.executor.query(
+        this.#state.statements.setup.setupLock,
+        [this.#state.setupLockKey],
+        transaction
+      );
+      const schema = await this.#schemaState(transaction);
+      if (!isCurrent(schema)) {
+        await work(transaction, schema);
+      }
+    });
+  }
+  async #run(statement, transaction) {
+    await this.#state.executor.query(statement, [], transaction);
+  }
+  async #schemaState(transaction) {
+    const rows = await this.#state.executor.query(
+      this.#state.statements.setup.schemaCurrent,
+      [this.#state.schemaMarker],
+      transaction
+    );
+    return { marked: rows[0]["marked"] === true, payloadJson: rows[0]["payload_json"] === true };
+  }
+};
+function isCurrent(schema) {
+  return schema.marked && schema.payloadJson;
+}
 var WAKE_UPS = ["notify", "poll"];
 var DEFAULT_PURGE_BATCH_SIZE = 1e3;
 function resolveStoreSettings(options) {
@@ -1520,8 +1694,8 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
       reserved.sequence - count(*) OVER (PARTITION BY incoming.key)
         + row_number() OVER (PARTITION BY incoming.key ORDER BY incoming.ordinal)
     END AS sequence
-  FROM jsonb_to_recordset($1::jsonb) AS incoming (
-    ordinal int, id text, type text, source text, key text, payload jsonb, headers jsonb,
+  FROM json_to_recordset($1::json) AS incoming (
+    ordinal int, id text, type text, source text, key text, payload json, headers json,
     correlation_id text, causation_id text, occurred_at timestamptz, handlers text[])
   LEFT JOIN reserved ON reserved.key = incoming.key
 )`;
@@ -1532,7 +1706,7 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
   INSERT INTO ${this.#names.events}
     (id, type, source, key, sequence, payload, headers, correlation_id, causation_id, occurred_at, created_at, handlers)
   SELECT incoming.id, incoming.type, incoming.source, incoming.key, incoming.sequence,
-    COALESCE(incoming.payload, 'null'::jsonb), COALESCE(incoming.headers, '{}'::jsonb),
+    COALESCE(incoming.payload, 'null'::json), COALESCE(incoming.headers, '{}'::json),
     incoming.correlation_id, incoming.causation_id, incoming.occurred_at, $2::timestamptz,
     COALESCE(incoming.handlers, '{}')
   FROM incoming
@@ -1585,11 +1759,11 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
     return `INSERT INTO ${this.#names.events}
   (id, type, source, key, sequence, payload, headers, correlation_id, causation_id, occurred_at, created_at, handlers)
 SELECT incoming.id, incoming.type, incoming.source, incoming.key, incoming.sequence,
-  COALESCE(incoming.payload, 'null'::jsonb), COALESCE(incoming.headers, '{}'::jsonb),
+  COALESCE(incoming.payload, 'null'::json), COALESCE(incoming.headers, '{}'::json),
   incoming.correlation_id, incoming.causation_id, incoming.occurred_at, $2::timestamptz,
   COALESCE(incoming.handlers, '{}')
-FROM jsonb_to_recordset($1::jsonb) AS incoming (
-  id text, type text, source text, key text, sequence bigint, payload jsonb, headers jsonb,
+FROM json_to_recordset($1::json) AS incoming (
+  id text, type text, source text, key text, sequence bigint, payload json, headers json,
   correlation_id text, causation_id text, occurred_at timestamptz, handlers text[])
 ORDER BY incoming.id
 ON CONFLICT (id) DO NOTHING
@@ -2839,8 +3013,10 @@ var SetupStatements = class {
     return `relaybus:${this.#names.schema}`;
   }
   /**
-   * Whether the lane table carries `marker` as its comment, that is whether the schema statements
-   * that produce that marker already ran. Takes no table lock. Parameters: `[marker]`.
+   * The state of the schema, taking no table lock. Parameters: `[marker]`. Columns: `marked`, whether
+   * the lane table carries `marker` as its comment (the schema statements that produce it already
+   * ran), and `payload_json`, whether the payload and headers columns of the event table are both
+   * `json` (the conversion of the `jsonb` columns of schemas before 0.4.1 ran).
    */
   get schemaCurrent() {
     return `SELECT EXISTS (
@@ -2849,7 +3025,14 @@ var SetupStatements = class {
   JOIN pg_catalog.pg_description AS d
     ON d.objoid = c.oid AND d.classoid = 'pg_catalog.pg_class'::regclass AND d.objsubid = 0
   WHERE n.nspname = '${this.#names.schema}' AND c.relname = '${this.#names.lanesTableName}' AND d.description = $1::text
-) AS current`;
+) AS marked, (
+  SELECT count(*) FROM pg_catalog.pg_attribute AS a
+  JOIN pg_catalog.pg_class AS c ON c.oid = a.attrelid
+  JOIN pg_catalog.pg_namespace AS n ON n.oid = c.relnamespace
+  WHERE n.nspname = '${this.#names.schema}' AND c.relname = '${this.#names.eventsTableName}'
+    AND a.attname IN ('payload', 'headers') AND a.atttypid = 'pg_catalog.json'::pg_catalog.regtype
+    AND NOT a.attisdropped
+) = 2 AS payload_json`;
   }
   /**
    * Takes the setup lock. Returns a boolean column rather than the `void` of the lock function, which
@@ -2887,6 +3070,7 @@ var PostgresEventStore = class {
   #claims;
   #completion;
   #maintenance;
+  #setup;
   #owned = new OwnedConnections();
   constructor(options) {
     const { purgeBatchSize, wakeUp, queryOptions } = resolveStoreSettings(options);
@@ -2900,7 +3084,7 @@ var PostgresEventStore = class {
       statements,
       schemaStatements,
       setupLockKey: statements.setup.setupLockKey,
-      schemaMarker: postgresSchemaMarker(schemaStatements.slice(0, -1)),
+      schemaMarker: version040SchemaMarker(options),
       purgeBatchSize,
       completionHistory: names.completionHistory,
       logger,
@@ -2924,42 +3108,30 @@ var PostgresEventStore = class {
     this.#claims = new PostgresClaims(state);
     this.#completion = new PostgresCompletion(state);
     this.#maintenance = new PostgresMaintenance(state);
+    this.#setup = new PostgresSetup(state, options);
   }
   /**
    * Creates the schema, tables and indexes if they do not exist. Safe to call
    * from many processes at once: a transaction-scoped advisory lock serializes
    * the DDL, so racing `CREATE TABLE IF NOT EXISTS` statements cannot collide.
-   * When the lane table already carries the marker of the current statements
-   * ({@link postgresSchemaMarker}) nothing runs and no table is locked, so instances
+   * When the lane table already carries the schema marker ({@link version040SchemaMarker})
+   * and the payload columns are `json`, nothing runs and no table is locked, so instances
    * that start next to running dispatchers cannot deadlock with their claims.
    * Skip it (`setupStore: false`) when a migration tool applies
    * `createPostgresSchemaSql()` instead.
    */
   async setup() {
-    if (await this.#schemaIsCurrent()) {
-      return;
-    }
-    await this.#state.executor.transaction(async (transaction) => {
-      await this.#state.executor.query(
-        this.#state.statements.setup.setupLock,
-        [this.#state.setupLockKey],
-        transaction
-      );
-      if (await this.#schemaIsCurrent(transaction)) {
-        return;
-      }
-      for (const statement of this.#state.schemaStatements) {
-        await this.#state.executor.query(statement, [], transaction);
-      }
-    });
+    await this.#setup.run();
   }
-  async #schemaIsCurrent(transaction) {
-    const rows = await this.#state.executor.query(
-      this.#state.statements.setup.schemaCurrent,
-      [this.#state.schemaMarker],
-      transaction
-    );
-    return rows[0]["current"] === true;
+  /** Every level PostgreSQL has (it runs `read uncommitted` as `read committed`, which the bus does not offer). */
+  isolationLevels = core.TRANSACTION_ISOLATION_LEVELS;
+  /**
+   * True for a serialization failure (SQLSTATE `40001`) raised through any executor, including
+   * Prisma's `P2034` and the wrappers of TypeORM and Drizzle; a custom executor can add its own
+   * test with {@link PostgresExecutor.isSerializationFailure}.
+   */
+  isSerializationFailure(error) {
+    return isPostgresSerializationFailure(error) || this.#state.executor.isSerializationFailure?.(error) === true;
   }
   /**
    * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
@@ -2968,6 +3140,9 @@ var PostgresEventStore = class {
    * `transaction_timeout`, all scoped to the transaction. An executor with `transactionWithBudget`
    * (`PgExecutor`) sets them with `BEGIN`, so the budget costs no round trip; on a pool the store
    * created they are kept per connection and sent only when the connection does not have them yet.
+   * With `options.isolationLevel` the transaction runs at that level: `PgExecutor` sends it with
+   * `BEGIN ISOLATION LEVEL ...` (no extra round trip), any other executor as `SET TRANSACTION
+   * ISOLATION LEVEL ...` before the budget statement.
    */
   async transaction(work, options) {
     const own = { wake: false };
@@ -2979,12 +3154,20 @@ var PostgresEventStore = class {
         this.#state.ownTransactions.delete(transaction);
       }
     };
-    const result = await (options === void 0 ? this.#state.executor.transaction(tracked) : inBudgetedTransaction(this.#state, { work: tracked, timeoutMs: options.timeoutMs }));
+    const result = await this.#open(tracked, options);
     if (own.wake) {
       this.#appender.wakeAfterCommit();
     }
     return result;
   }
+  /** Opens the transaction `work` runs in: plain, held to the budget, or at an isolation level too. */
+  #open(work, options) {
+    if (options === void 0) {
+      return this.#state.executor.transaction(work);
+    }
+    const { timeoutMs, isolationLevel } = options;
+    return isolationLevel === void 0 ? inBudgetedTransaction(this.#state, { work, timeoutMs }) : inIsolatedTransaction(this.#state, { work, timeoutMs, isolationLevel });
+  }
   /**
    * Writes the entries in `transaction`, normally with one statement
    * (`AppendStatements.insertFreshEvents`): keyed events reserve their sequence numbers (locking