velocious 1.0.596 → 1.0.597

package/build/database/tenants/migration-pending-inspector.js

@@ -0,0 +1,77 @@
+// @ts-check
+
+import MigrationsLedger from "../migrations-ledger.js"
+import TenantIterator from "../../tenants/tenant-iterator.js"
+import restArgsError from "../../utils/rest-args-error.js"
+
+export default class TenantMigrationPendingInspector {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+   * @param {string} args.identifier - Tenant database identifier.
+   * @param {number[]} args.migrationVersions - Applicable migration versions.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.tenants - Existing tenant descriptors.
+   */
+  constructor({configuration, identifier, migrationVersions, tenants, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.configuration = configuration
+    this.identifier = identifier
+    this.migrationVersions = migrationVersions.map((version) => `${version}`)
+    this.tenants = tenants
+  }
+
+  /**
+   * Reads every existing tenant ledger and reports aggregate pending state.
+   * @returns {Promise<{hasPendingMigrations: boolean, identifier: string, migrationCount: number, pendingTenantCount: number, tenantCount: number}>} - Deploy preflight result.
+   */
+  async inspect() {
+    let pendingTenantCount = 0
+
+    for (const tenant of this.tenants) {
+      if (await this.tenantHasPendingMigrations(tenant)) pendingTenantCount++
+    }
+
+    return {
+      hasPendingMigrations: pendingTenantCount > 0,
+      identifier: this.identifier,
+      migrationCount: this.migrationVersions.length,
+      pendingTenantCount,
+      tenantCount: this.tenants.length
+    }
+  }
+
+  /**
+   * Reads one tenant's existing migration ledger without preparing or changing it.
+   * @param {ReturnType<typeof JSON.parse>} tenant - Tenant descriptor.
+   * @returns {Promise<boolean>} - Whether the tenant has an applicable pending migration.
+   */
+  async tenantHasPendingMigrations(tenant) {
+    return await this.configuration.runWithTenant(tenant, async () => {
+      const tenantLabel = TenantIterator.tenantLabel(tenant)
+
+      if (!this.configuration.isDatabaseIdentifierActive(this.identifier)) {
+        throw new Error(`Tenant database identifier ${this.identifier} is inactive for tenant: ${tenantLabel}`)
+      }
+
+      try {
+        return await this.configuration.ensureConnections({
+          databaseIdentifiers: [this.identifier],
+          name: `Tenant migration pending preflight: ${this.identifier}`
+        }, async (dbs) => {
+          const db = dbs[this.identifier]
+
+          if (!db) throw new Error(`Tenant database identifier ${this.identifier} did not open a connection`)
+          if (!await MigrationsLedger.tableExists(db)) throw new Error(`${MigrationsLedger.tableName()} ledger does not exist`)
+
+          const appliedVersions = new Set(await MigrationsLedger.appliedVersions(db))
+
+          return this.migrationVersions.some((version) => !appliedVersions.has(version))
+        })
+      } catch (error) {
+        throw new Error(`Could not read ${MigrationsLedger.tableName()} for tenant ${tenantLabel}`, {cause: error})
+      }
+    })
+  }
+}

package/build/environment-handlers/base.js

@@ -19,6 +19,14 @@ import {validateTimeZone} from "../time-zone.js"
  */
 
 export default class VelociousEnvironmentHandlerBase {
+  /**
+   * Resolves the configured database pool type for the current runtime context.
+   * Browser and ordinary server contexts retain the application configuration.
+   * @param {{configuredPoolType: typeof import("../database/pool/base.js").default, databaseIdentifier: string}} args - Configured pool and logical database identifier.
+   * @returns {typeof import("../database/pool/base.js").default} - Pool type for this context.
+   */
+  resolveTestSharedTransactionPoolType({configuredPoolType}) { return configuredPoolType }
+
   /**
    * Node test runtimes may replace a physical child connection with a broker
    * proxy. Other environments never participate in this test-only protocol.

package/build/environment-handlers/node.js

@@ -32,6 +32,7 @@ import path from "path"
 import {AsyncLocalStorage as NodeAsyncLocalStorage} from "node:async_hooks"
 import {timingSafeEqual} from "node:crypto"
 import requireContext from "require-context"
+import AsyncTrackedMultiConnectionPool from "../database/pool/async-tracked-multi-connection.js"
 import InitializerFromRequireContext from "../database/initializer-from-require-context.js"
 import toImportSpecifier from "../utils/to-import-specifier.js"
 import {validateTimeZone} from "../time-zone.js"
@@ -64,6 +65,19 @@ function pathWithinAllowedPrefixes(filePath, allowedPathPrefixes) {
 }
 
 export default class VelociousEnvironmentHandlerNode extends Base{
+  /**
+   * Gives concurrent shared-transaction child jobs independent proxy sessions.
+   * A configured single-connection pool shares mutable transaction state between
+   * async jobs, while the broker requires one root-transaction lease per socket.
+   * @param {{configuredPoolType: typeof import("../database/pool/base.js").default, databaseIdentifier: string}} args - Configured pool and logical database identifier.
+   * @returns {typeof import("../database/pool/base.js").default} - Pool type for this context.
+   */
+  resolveTestSharedTransactionPoolType({configuredPoolType, databaseIdentifier}) {
+    if (!sharedTransactionBrokerConfig(databaseIdentifier)) return configuredPoolType
+
+    return AsyncTrackedMultiConnectionPool
+  }
+
   /**
    * Creates a test-only child proxy when TestRunner supplied an active broker.
    * @param {{DriverClass: typeof import("../database/drivers/base.js").default, config: import("../configuration-types.js").DatabaseConfigurationType, configuration: import("../configuration.js").default, databaseIdentifier: string}} args - Connection details.

package/build/mailer/backends/resend-smtp.js

@@ -0,0 +1,121 @@
+// @ts-check
+
+import SmtpMailerBackend from "./smtp.js"
+import VelociousError from "../../velocious-error.js"
+import {deliveryOperationFromPayload} from "../delivery-operation.js"
+
+const PROVIDER_KIND = "resend-smtp"
+const RETENTION_MS = 24 * 60 * 60 * 1000
+const IDEMPOTENCY_HEADER = "Resend-Idempotency-Key"
+
+/**
+ * Checks whether a value contains an SMTP header control character.
+ * @param {string} value - Header value.
+ * @returns {boolean} - Whether a control character is present.
+ */
+function containsHeaderValueControlCharacter(value) {
+  for (const character of value) {
+    const codePoint = character.charCodeAt(0)
+
+    if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) return true
+  }
+
+  return false
+}
+
+/**
+ * Keeps the provider-owned operation header out of caller payloads.
+ * @param {import("../index.js").MailerDeliveryPayload} payload - Mail payload.
+ * @returns {void}
+ */
+function rejectReservedHeaderOverride(payload) {
+  if (Object.keys(payload.headers || {}).some((name) => name.toLowerCase() === IDEMPOTENCY_HEADER.toLowerCase())) {
+    throw VelociousError.safe(`Reserved mail header ${IDEMPOTENCY_HEADER} is owned by ResendSmtpMailerBackend required delivery operations.`, {
+      code: "mail-delivery-idempotency-header-reserved"
+    })
+  }
+}
+
+/**
+ * Resend SMTP transport with Resend's documented 24-hour idempotency header.
+ */
+export default class ResendSmtpMailerBackend extends SmtpMailerBackend {
+  /**
+   * Resolves the SMTP sender before it becomes part of the immutable digest.
+   * @param {object} args - Preparation input.
+   * @param {import("../index.js").MailerDeliveryPayload} args.payload - Rendered payload.
+   * @returns {import("../index.js").MailerDeliveryPayload} - Provider-ready payload.
+   */
+  prepareDeliveryOperationPayload({payload}) {
+    const from = payload.from || this.defaultFrom
+
+    if (!from) {
+      throw VelociousError.safe("Required Resend mail delivery needs a from address.", {
+        code: "mail-delivery-from-missing"
+      })
+    }
+
+    return {...payload, from}
+  }
+
+  /**
+   * Advertises the provider-specific guarantee used by required operations.
+   * @returns {import("../index.js").MailerDeliveryIdempotencyCapability} - Capability.
+   */
+  deliveryIdempotencyCapability() {
+    return {providerKind: PROVIDER_KIND, retentionMs: RETENTION_MS}
+  }
+
+  /**
+   * Validates Resend's documented length and SMTP header-value safety contract.
+   * @param {object} args - Validation input.
+   * @param {import("../index.js").MailerDeliveryOperationRequest | import("../index.js").MailerDeliveryOperation} args.deliveryOperation - Operation.
+   * @param {import("../index.js").MailerDeliveryPayload} args.payload - Rendered or persisted mail payload.
+   * @returns {void}
+   */
+  validateDeliveryOperation({deliveryOperation, payload}) {
+    if (
+      typeof deliveryOperation.id !== "string" ||
+      deliveryOperation.id.length < 1 ||
+      deliveryOperation.id.length > 256 ||
+      containsHeaderValueControlCharacter(deliveryOperation.id)
+    ) {
+      throw VelociousError.safe("Resend idempotency keys must contain between 1 and 256 characters without control characters.", {
+        code: "mail-delivery-idempotency-key-invalid"
+      })
+    }
+
+    rejectReservedHeaderOverride(payload)
+  }
+
+  /**
+   * Injects the framework-owned Resend operation header before generic SMTP serialization.
+   * @param {object} args - Delivery args.
+   * @param {import("../index.js").MailerDeliveryPayload} args.payload - Mail payload.
+   * @param {import("../../configuration.js").default} [args.configuration] - Active configuration.
+   * @returns {Promise<void>} - Resolves when accepted and shut down.
+   */
+  async deliver({payload, configuration}) {
+    const headers = payload.headers || {}
+
+    if (payload.deliveryOperation) {
+      this.validateDeliveryOperation({deliveryOperation: payload.deliveryOperation, payload})
+    } else {
+      rejectReservedHeaderOverride(payload)
+    }
+    const operation = deliveryOperationFromPayload(payload)
+
+    if (!operation) {
+      await super.deliver({payload, configuration})
+      return
+    }
+
+    await super.deliver({
+      configuration,
+      payload: {
+        ...payload,
+        headers: {...headers, [IDEMPOTENCY_HEADER]: operation.id}
+      }
+    })
+  }
+}

package/build/mailer/base.js

@@ -3,9 +3,16 @@
 import ejs from "ejs"
 import {incorporate} from "incorporator"
 import * as inflection from "inflection"
+import BackgroundJobsClient from "../background-jobs/client.js"
 import configurationResolver from "../configuration-resolver.js"
 import restArgsError from "../utils/rest-args-error.js"
 import MailerDelivery from "./delivery.js"
+import MailerDeliveryOperationStore from "./delivery-operation-store.js"
+import {
+  deliveryOperationFromPayload,
+  prepareRequiredDeliveryPayload,
+  requireDeliveryIdempotencyCapability
+} from "./delivery-operation.js"
 
 /**
  * Deliveries store.
@@ -66,16 +73,6 @@ function inferActionName(mailerClass, stack) {
   return actionName
 }
 
-/**
- * Runs is testing environment.
- * @returns {Promise<boolean>} - Whether the current environment is test.
- */
-async function isTestingEnvironment() {
-  const configuration = await configurationResolver()
-
-  return configuration.getEnvironment() === "test"
-}
-
 /**
  * Base mailer with view rendering and delivery helpers.
  */
@@ -241,10 +238,13 @@ export class VelociousMailerBase {
   /**
    * Runs enqueue payload.
    * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+   * @param {import("./index.js").MailerDeliveryLaterOptions} [options] - Delivery execution options.
    * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
    */
-  async _enqueuePayload(payload) {
-    return await enqueuePayload(payload)
+  async _enqueuePayload(payload, options) {
+    const configuration = await this._getConfiguration()
+
+    return await enqueuePayload(payload, {...options, configuration})
   }
 }
 
@@ -287,14 +287,22 @@ export function getDeliveryHandler() {
  * @returns {Promise<import("./index.js").MailerDeliveryPayload | ReturnType<typeof JSON.parse>>} - Handler result.
  */
 export async function deliverPayload(payload) {
-  if (await isTestingEnvironment()) {
+  const configuration = await configurationResolver()
+  const backend = configuration.getMailerBackend()
+  const deliveryOperation = deliveryOperationFromPayload(payload)
+
+  if (deliveryOperation) {
+    const capability = requireDeliveryIdempotencyCapability({backend, deliveryOperation, payload})
+    const operationStore = new MailerDeliveryOperationStore({configuration})
+
+    await operationStore.beginAttempt({capability, payload})
+  }
+
+  if (configuration.getEnvironment() === "test") {
     deliveriesStore.push(payload)
     return payload
   }
 
-  const configuration = await configurationResolver()
-  const backend = configuration.getMailerBackend()
-
   if (backend?.deliver) {
     return await backend.deliver({payload, configuration})
   }
@@ -311,15 +319,37 @@ export async function deliverPayload(payload) {
 /**
  * Runs the enqueuePayload helper.
  * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+ * @param {object} [options] - Enqueue options.
+ * @param {import("../configuration.js").default} [options.configuration] - Owning configuration.
+ * @param {import("./index.js").MailerDeliveryOperationRequest} [options.deliveryOperation] - Required provider-backed operation.
  * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
  */
-export async function enqueuePayload(payload) {
-  if (await isTestingEnvironment()) {
-    deliveriesStore.push(payload)
-    return payload
+export async function enqueuePayload(payload, {configuration: suppliedConfiguration, deliveryOperation} = {}) {
+  const configuration = suppliedConfiguration || await configurationResolver()
+  let persistedPayload = payload
+
+  if (deliveryOperation) {
+    const backend = configuration.getMailerBackend()
+    const operationPayload = typeof backend?.prepareDeliveryOperationPayload === "function"
+      ? backend.prepareDeliveryOperationPayload({payload})
+      : payload
+    const capability = requireDeliveryIdempotencyCapability({backend, deliveryOperation, payload: operationPayload})
+
+    persistedPayload = prepareRequiredDeliveryPayload({capability, deliveryOperation, payload: operationPayload})
   }
 
-  const {default: mailDeliveryJob} = await import("../jobs/mail-delivery.js")
+  if (configuration.getEnvironment() === "test") {
+    deliveriesStore.push(persistedPayload)
+    return persistedPayload
+  }
 
-  return await mailDeliveryJob.performLater(payload)
+  const {default: mailDeliveryJob} = await import("../jobs/mail-delivery.js")
+  const client = new BackgroundJobsClient({configuration})
+  const jobOptions = mailDeliveryJob._withQueue(deliveryOperation ? {idempotencyKey: deliveryOperation.id} : undefined)
+
+  return await client.enqueue({
+    args: [persistedPayload],
+    jobName: mailDeliveryJob.jobName(),
+    options: jobOptions
+  })
 }

package/build/mailer/delivery-operation-store.js

@@ -0,0 +1,152 @@
+// @ts-check
+
+import BackgroundJobsStore from "../background-jobs/store.js"
+import VelociousError from "../velocious-error.js"
+import {
+  MAIL_DELIVERY_OPERATIONS_TABLE,
+  mailDeliveryOperationKey,
+  validateAttemptPayload
+} from "./delivery-operation.js"
+
+/**
+ * Durable first-attempt and retention guard for required mail operations.
+ */
+export default class MailerDeliveryOperationStore {
+  /**
+   * Creates a durable mail-operation state guard.
+   * @param {object} args - Store input.
+   * @param {import("../configuration.js").default} args.configuration - Active configuration.
+   * @param {() => number} [args.clock] - Explicit clock dependency.
+   */
+  constructor({configuration, clock = () => Date.now()}) {
+    this.backgroundJobsStore = new BackgroundJobsStore({configuration})
+    this.clock = clock
+    this.configuration = configuration
+  }
+
+  /**
+   * Atomically starts the provider retention clock once and rejects expired attempts.
+   * @param {object} args - Attempt input.
+   * @param {import("./index.js").MailerDeliveryIdempotencyCapability} args.capability - Current backend capability.
+   * @param {import("./index.js").MailerDeliveryPayload} args.payload - Persisted payload.
+   * @returns {Promise<{expiresAtMs: number, firstAttemptStartedAtMs: number}>} - Attempt window.
+   */
+  async beginAttempt({capability, payload}) {
+    const operation = validateAttemptPayload({capability, payload})
+    const nowMs = this.clock()
+
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0) throw new Error("Mailer delivery operation clock must return a non-negative safe integer")
+
+    const databaseIdentifier = this.backgroundJobsStore.getDatabaseIdentifier()
+
+    return await this.configuration.ensureConnections({
+      databaseIdentifiers: [databaseIdentifier],
+      name: "Mailer delivery operation attempt"
+    }, async (dbs) => {
+      const db = dbs[databaseIdentifier]
+
+      if (db.insideTransaction()) {
+        throw VelociousError.safe("Required mail delivery cannot start inside an existing database transaction.", {
+          code: "mail-delivery-idempotency-transaction-active"
+        })
+      }
+
+      await this.backgroundJobsStore.ensureSchema(db)
+
+      return await db.transaction(async () => {
+        const operationKey = mailDeliveryOperationKey(operation.id)
+
+        // A value-preserving structured update obtains the row's write lock on
+        // every driver before we inspect or initialize the one-shot timestamp.
+        await db.update({
+          tableName: MAIL_DELIVERY_OPERATIONS_TABLE,
+          data: {operation_key: operationKey},
+          conditions: {operation_key: operationKey}
+        })
+        let row = await this._operationRow(db, operation.id)
+
+        if (!row) throw new Error("Required mail delivery operation is not durably registered")
+        this._validateRow({operation, row})
+
+        let firstAttemptStartedAtMs = numberOrNull(row.first_attempt_started_at_ms)
+
+        if (firstAttemptStartedAtMs === null) {
+          await db.update({
+            tableName: MAIL_DELIVERY_OPERATIONS_TABLE,
+            data: {first_attempt_started_at_ms: nowMs},
+            conditions: {operation_key: operationKey}
+          })
+          row = await this._operationRow(db, operation.id)
+          firstAttemptStartedAtMs = row ? numberOrNull(row.first_attempt_started_at_ms) : null
+
+          if (firstAttemptStartedAtMs === null) throw new Error("Failed to durably start mail delivery provider retention")
+        }
+
+        const expiresAtMs = firstAttemptStartedAtMs + operation.providerRetentionMs
+
+        if (nowMs >= expiresAtMs) {
+          throw VelociousError.safe("The required mail delivery idempotency window expired before another attempt.", {
+            code: "mail-delivery-idempotency-expired",
+            details: {
+              expiresAtMs,
+              firstAttemptStartedAtMs,
+              operationId: operation.id,
+              providerKind: operation.providerKind
+            }
+          })
+        }
+
+        return {expiresAtMs, firstAttemptStartedAtMs}
+      })
+    })
+  }
+
+  /**
+   * Loads one operation by its fixed-size digest key.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} operationId - Operation id.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>> | null>} - Row or null.
+   */
+  async _operationRow(db, operationId) {
+    const rows = await db
+      .newQuery()
+      .from(MAIL_DELIVERY_OPERATIONS_TABLE)
+      .where({operation_key: mailDeliveryOperationKey(operationId)})
+      .limit(1)
+      .results()
+
+    return rows[0] ? /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (rows[0]) : null
+  }
+
+  /**
+   * Validates immutable durable fields without including mail content in failures.
+   * @param {object} args - Validation input.
+   * @param {import("./index.js").MailerDeliveryOperation} args.operation - Persisted payload operation.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.row - Durable operation row.
+   * @returns {void}
+   */
+  _validateRow({operation, row}) {
+    const matches = String(row.operation_id) === operation.id
+      && String(row.payload_digest) === operation.payloadDigest
+      && String(row.provider_kind) === operation.providerKind
+      && numberOrNull(row.provider_retention_ms) === operation.providerRetentionMs
+
+    if (!matches) {
+      throw VelociousError.safe("The durable mail delivery operation does not match the persisted payload or provider.", {
+        code: "mail-delivery-idempotency-conflict"
+      })
+    }
+  }
+}
+
+/**
+ * Normalizes a database integer.
+ * @param {ReturnType<typeof JSON.parse>} value - Database value.
+ * @returns {number | null} - Number or null.
+ */
+function numberOrNull(value) {
+  if (value === null || value === undefined || value === "") return null
+  const number = Number(value)
+
+  return Number.isNaN(number) ? null : number
+}