@beignet/provider-db-drizzle 0.0.9

package/src/shared/idempotency-core.ts

@@ -0,0 +1,280 @@
+/**
+ * Dialect-independent idempotency port orchestration.
+ *
+ * Every Drizzle dialect (SQLite, Postgres, MySQL) implements the small
+ * `IdempotencySqlExecutor` seam below; reservation, replay, conflict, and
+ * mutation-guard semantics live here so they stay byte-identical across
+ * dialects. The dialect-specific mutation error class is injected so callers
+ * keep catching the error type their dialect package exports.
+ *
+ * This module must never import dialect database types — only `SQL` from
+ * drizzle-orm and core ports from `@beignet/core`.
+ */
+
+import {
+  createIdempotencyStorageKey,
+  type IdempotencyCompleteInput,
+  type IdempotencyFailInput,
+  type IdempotencyPort,
+  type IdempotencyReservation,
+  type IdempotencyReserveInput,
+  normalizeIdempotencyScope,
+} from "@beignet/core/idempotency";
+import { type SQL, sql } from "drizzle-orm";
+import type { SqlExecutorBase } from "./outbox-core.js";
+import {
+  encodeTimestamp,
+  type IdempotencyRow,
+  idempotencyReservationFromRow,
+} from "./rows.js";
+
+/**
+ * SQL execution seam for the shared idempotency core.
+ */
+export interface IdempotencySqlExecutor
+  extends SqlExecutorBase<IdempotencySqlExecutor> {
+  /**
+   * Insert statement prefix for conflict-tolerant reservation inserts.
+   *
+   * SQLite: `insert or ignore into`. Postgres/MySQL: `insert into`.
+   */
+  insertPrefix: SQL;
+
+  /**
+   * Insert statement suffix for conflict-tolerant reservation inserts.
+   *
+   * SQLite: empty. Postgres: `on conflict (storage_key) do nothing`.
+   * MySQL: `on duplicate key update storage_key = storage_key`.
+   */
+  insertConflictSuffix: SQL;
+}
+
+/**
+ * Options for the shared idempotency core.
+ */
+export interface IdempotencyPortCoreOptions {
+  /**
+   * Clock used by tests and deterministic environments.
+   */
+  now?: () => Date;
+}
+
+/**
+ * Arguments for a dialect's idempotency mutation error class.
+ */
+export interface IdempotencyMutationErrorArgs {
+  action: "complete" | "fail";
+  namespace: string;
+  key: string;
+  scopeKey: string;
+}
+
+/**
+ * Constructor shape for the dialect-specific mutation error class injected
+ * into `createIdempotencyPortCore(...)`.
+ */
+export type IdempotencyMutationErrorConstructor = new (
+  args: IdempotencyMutationErrorArgs,
+) => Error;
+
+/**
+ * Build the mutation error message. Shared so the wording is identical
+ * across every dialect's mutation error class.
+ */
+export function formatIdempotencyMutationErrorMessage(
+  args: IdempotencyMutationErrorArgs,
+): string {
+  return `Idempotency ${args.action} for key "${args.key}" in namespace "${args.namespace}" matched no in-progress reservation with this fingerprint. The reservation may be missing, expired, already completed or released, or reserved with a different fingerprint.`;
+}
+
+function nowFrom(options: IdempotencyPortCoreOptions): Date {
+  return options.now?.() ?? new Date();
+}
+
+function assertNonEmptyString(name: string, value: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
+
+function assertIdempotencyTtl(ttlSec: number | undefined): void {
+  if (ttlSec === undefined) return;
+  if (!Number.isInteger(ttlSec) || ttlSec <= 0) {
+    throw new Error("ttlSec must be a positive integer when provided");
+  }
+}
+
+function resolveIdempotencyExpiresAt(
+  ttlSec: number | undefined,
+  now: Date,
+): Date | null {
+  assertIdempotencyTtl(ttlSec);
+  return ttlSec === undefined ? null : new Date(now.getTime() + ttlSec * 1000);
+}
+
+function validateReserveInput(input: IdempotencyReserveInput): void {
+  assertNonEmptyString("namespace", input.namespace);
+  assertNonEmptyString("key", input.key);
+  assertNonEmptyString("fingerprint", input.fingerprint);
+  assertIdempotencyTtl(input.ttlSec);
+}
+
+function validateMutationInput(
+  input: IdempotencyCompleteInput | IdempotencyFailInput,
+): void {
+  assertNonEmptyString("namespace", input.namespace);
+  assertNonEmptyString("key", input.key);
+  assertNonEmptyString("fingerprint", input.fingerprint);
+}
+
+/**
+ * Create the dialect-independent idempotency port orchestration on top of a
+ * dialect's `IdempotencySqlExecutor`.
+ *
+ * The port accepts both root databases and transaction clients (via the
+ * executor), so applications can expose root idempotency for ordinary
+ * retry-safe commands and transaction-scoped idempotency from Unit of Work.
+ */
+export function createIdempotencyPortCore(
+  executor: IdempotencySqlExecutor,
+  options: IdempotencyPortCoreOptions,
+  MutationErrorClass: IdempotencyMutationErrorConstructor,
+): IdempotencyPort {
+  /**
+   * Verify that an idempotency mutation matched an in-progress reservation.
+   *
+   * Like `reserve(...)`, a missing `rowsAffected` from the driver is treated
+   * as success; the assertion only fires when the driver positively reports
+   * that no row matched.
+   */
+  function assertIdempotencyMutationSucceeded(
+    action: "complete" | "fail",
+    input: IdempotencyCompleteInput | IdempotencyFailInput,
+    rowsAffected: number | undefined,
+  ): void {
+    if (rowsAffected === undefined || rowsAffected > 0) {
+      return;
+    }
+
+    throw new MutationErrorClass({
+      action,
+      namespace: input.namespace,
+      key: input.key,
+      scopeKey: normalizeIdempotencyScope(input.scope),
+    });
+  }
+
+  async function reserveWith(
+    tx: IdempotencySqlExecutor,
+    input: IdempotencyReserveInput,
+  ): Promise<IdempotencyReservation> {
+    validateReserveInput(input);
+
+    const now = nowFrom(options);
+    const nowIso = encodeTimestamp(now);
+    const expiresAt = resolveIdempotencyExpiresAt(input.ttlSec, now);
+    const storageKey = createIdempotencyStorageKey(input);
+    const scopeKey = normalizeIdempotencyScope(input.scope);
+
+    await tx.run(sql`delete from ${tx.table}
+      where storage_key = ${storageKey}
+        and expires_at is not null
+        and expires_at <= ${nowIso}`);
+
+    const rowsAffected = await tx.run(sql`${tx.insertPrefix} ${tx.table} (
+      storage_key,
+      namespace,
+      idempotency_key,
+      scope_key,
+      fingerprint,
+      status,
+      result_json,
+      reserved_at,
+      completed_at,
+      expires_at,
+      updated_at
+    ) values (
+      ${storageKey},
+      ${input.namespace},
+      ${input.key},
+      ${scopeKey},
+      ${input.fingerprint},
+      'in-progress',
+      null,
+      ${nowIso},
+      null,
+      ${expiresAt ? encodeTimestamp(expiresAt) : null},
+      ${nowIso}
+    )${tx.insertConflictSuffix}`);
+
+    if (rowsAffected === undefined || rowsAffected > 0) {
+      return {
+        status: "reserved",
+        namespace: input.namespace,
+        key: input.key,
+        scopeKey,
+        fingerprint: input.fingerprint,
+        reservedAt: now,
+        expiresAt,
+      };
+    }
+
+    const row = (await tx.row(
+      sql`select * from ${tx.table} where storage_key = ${storageKey}`,
+    )) as IdempotencyRow | undefined;
+    if (!row) {
+      throw new Error(
+        `Idempotency reservation "${input.key}" could not be read after insert conflict.`,
+      );
+    }
+
+    return idempotencyReservationFromRow(row, input.fingerprint);
+  }
+
+  return {
+    reserve(input) {
+      const transactional = executor.withTransaction((tx) =>
+        reserveWith(tx, input),
+      );
+      if (transactional !== undefined) {
+        return transactional;
+      }
+
+      return reserveWith(executor, input);
+    },
+
+    async complete(input) {
+      validateMutationInput(input);
+
+      const nowIso = encodeTimestamp(nowFrom(options));
+      const storageKey = createIdempotencyStorageKey(input);
+      const serializedResult = JSON.stringify(input.result);
+      const resultJson =
+        serializedResult === undefined ? null : serializedResult;
+
+      const rowsAffected = await executor.run(sql`update ${executor.table}
+        set
+          status = 'completed',
+          result_json = ${resultJson},
+          completed_at = ${nowIso},
+          updated_at = ${nowIso}
+        where storage_key = ${storageKey}
+          and fingerprint = ${input.fingerprint}
+          and status = 'in-progress'`);
+
+      assertIdempotencyMutationSucceeded("complete", input, rowsAffected);
+    },
+
+    async fail(input) {
+      validateMutationInput(input);
+
+      const storageKey = createIdempotencyStorageKey(input);
+      const rowsAffected = await executor.run(sql`delete from ${executor.table}
+        where storage_key = ${storageKey}
+          and fingerprint = ${input.fingerprint}
+          and status = 'in-progress'`);
+
+      assertIdempotencyMutationSucceeded("fail", input, rowsAffected);
+    },
+  };
+}

package/src/shared/identifiers.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared SQL identifier helpers used by every Drizzle dialect in this
+ * package. Identifiers are validated before quoting so table names from
+ * options can never inject SQL.
+ */
+
+/**
+ * Assert that a SQL identifier only contains safe characters.
+ *
+ * @throws Error when the identifier contains anything beyond
+ *   `[A-Za-z0-9_]` or starts with a digit.
+ */
+export function assertSafeIdentifier(name: string): void {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Unsafe SQL identifier "${name}".`);
+  }
+}
+
+/**
+ * Quote a validated SQL identifier with the dialect's identifier quote.
+ *
+ * - SQLite and Postgres use `"`.
+ * - MySQL uses `` ` ``.
+ */
+export function quoteIdentifier(name: string, quote: '"' | "`"): string {
+  assertSafeIdentifier(name);
+  return `${quote}${name.replaceAll(quote, `${quote}${quote}`)}${quote}`;
+}

package/src/shared/instrumentation.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared devtools instrumentation helpers for Drizzle database providers.
+ */
+
+import type { ProviderInstrumentation } from "@beignet/core/providers";
+import type { Logger } from "drizzle-orm";
+
+/**
+ * Summarize a SQL query for devtools event summaries: collapse whitespace
+ * and truncate long statements.
+ */
+export function summarizeQuery(query: string): string {
+  const normalized = query.replace(/\s+/g, " ").trim();
+  return normalized.length > 120
+    ? `${normalized.slice(0, 117)}...`
+    : normalized;
+}
+
+/**
+ * Create a Drizzle logger that records `db.query` custom instrumentation
+ * events for every executed query.
+ *
+ * Returns `undefined` when instrumentation is disabled so providers can skip
+ * installing a logger entirely.
+ */
+export function createDbQueryLogger(
+  instrumentation: ProviderInstrumentation,
+  portName: string,
+): Logger | undefined {
+  if (!instrumentation.isEnabled()) {
+    return undefined;
+  }
+
+  return {
+    logQuery(query: string, params: unknown[]) {
+      instrumentation.custom({
+        name: "db.query",
+        label: "Database query",
+        summary: summarizeQuery(query),
+        details: {
+          query,
+          params: params.length > 0 ? "[redacted]" : [],
+          paramsCount: params.length,
+          portName,
+        },
+      });
+    },
+  };
+}

package/src/shared/outbox-core.ts

@@ -0,0 +1,322 @@
+/**
+ * Dialect-independent outbox port orchestration.
+ *
+ * Every Drizzle dialect (SQLite, Postgres, MySQL) implements the small
+ * `OutboxSqlExecutor` seam below; the complete enqueue/claim/deliver/fail
+ * workflow lives here so the semantics stay byte-identical across dialects.
+ *
+ * This module must never import dialect database types — only `SQL` from
+ * drizzle-orm and core ports from `@beignet/core`.
+ */
+
+import {
+  type ClaimedOutboxMessage,
+  createOutboxMessage,
+  DEFAULT_OUTBOX_LEASE_MS,
+  OutboxClaimError,
+  type OutboxEnqueueInput,
+  type OutboxMessage,
+  type OutboxMessageStatus,
+  type OutboxPort,
+  serializeOutboxError,
+} from "@beignet/core/outbox";
+import { type SQL, sql } from "drizzle-orm";
+import {
+  encodeTimestamp,
+  type OutboxRow,
+  rowToClaimedMessage,
+} from "./rows.js";
+
+/**
+ * Minimal SQL execution seam a dialect implements to back the shared
+ * database executor cores.
+ *
+ * @template TSelf - The concrete executor interface, so `withTransaction`
+ *   hands the callback a transaction-scoped executor of the same shape.
+ */
+export interface SqlExecutorBase<TSelf> {
+  /**
+   * The quoted table name as a raw SQL fragment, e.g.
+   * `sql.raw(quoteIdentifier(tableName, '"'))`.
+   */
+  table: SQL;
+
+  /**
+   * Execute a query and return all rows as plain column-name keyed records.
+   */
+  rows(query: SQL): Promise<Record<string, unknown>[]>;
+
+  /**
+   * Execute a query and return the first row, or `undefined` when no row
+   * matched.
+   */
+  row(query: SQL): Promise<Record<string, unknown> | undefined>;
+
+  /**
+   * Execute a mutation and return the number of affected rows, or
+   * `undefined` when the driver does not report it.
+   */
+  run(query: SQL): Promise<number | undefined>;
+
+  /**
+   * Run `fn` inside a database transaction with a transaction-scoped
+   * executor. Return `undefined` (synchronously) when the executor is
+   * already transaction-scoped or the client cannot open a transaction; the
+   * core then runs the work directly on this executor.
+   */
+  withTransaction<R>(fn: (tx: TSelf) => Promise<R>): Promise<R> | undefined;
+}
+
+/**
+ * SQL execution seam for the shared outbox core.
+ */
+export interface OutboxSqlExecutor extends SqlExecutorBase<OutboxSqlExecutor> {
+  /**
+   * Row-locking suffix appended to the eligible-message select.
+   *
+   * SQLite: empty. Postgres/MySQL: ` for update skip locked`.
+   */
+  claimLockSuffix: SQL;
+}
+
+/**
+ * Options for the shared outbox core.
+ */
+export interface OutboxPortCoreOptions {
+  /**
+   * Clock used by tests and deterministic environments.
+   */
+  now?: () => Date;
+}
+
+function nowFrom(options: OutboxPortCoreOptions): Date {
+  return options.now?.() ?? new Date();
+}
+
+function createClaimToken(): string {
+  return crypto.randomUUID();
+}
+
+async function getOutboxRow(
+  executor: OutboxSqlExecutor,
+  id: string,
+): Promise<OutboxRow | undefined> {
+  const row = await executor.row(
+    sql`select * from ${executor.table} where id = ${id}`,
+  );
+  return row as OutboxRow | undefined;
+}
+
+function assertClaimedRowSucceeded(
+  row: OutboxRow | undefined,
+  input: { id: string; expectedStatus: OutboxMessageStatus },
+): void {
+  if (!row || row.status !== input.expectedStatus || row.claim_token !== null) {
+    throw new OutboxClaimError({
+      id: input.id,
+      message: `Outbox message "${input.id}" is not claimed by this worker.`,
+    });
+  }
+}
+
+/**
+ * Verify that a claim-token-guarded outbox update matched a row.
+ *
+ * When the driver reports `rowsAffected`, trust it: a verification re-read
+ * would race with legitimate re-claims (for example, a concurrent worker can
+ * re-claim a message immediately after `markFailed` returns it to `pending`)
+ * and report a spurious claim failure. The re-read only runs as a fallback for
+ * drivers that do not report `rowsAffected`.
+ */
+async function assertOutboxMutationSucceeded(
+  executor: OutboxSqlExecutor,
+  input: { id: string; expectedStatus: OutboxMessageStatus },
+  rowsAffected: number | undefined,
+): Promise<void> {
+  if (rowsAffected !== undefined) {
+    if (rowsAffected <= 0) {
+      throw new OutboxClaimError({
+        id: input.id,
+        message: `Outbox message "${input.id}" is not claimed by this worker.`,
+      });
+    }
+    return;
+  }
+
+  assertClaimedRowSucceeded(await getOutboxRow(executor, input.id), input);
+}
+
+/**
+ * Create the dialect-independent outbox port orchestration on top of a
+ * dialect's `OutboxSqlExecutor`.
+ *
+ * Claiming uses a claim-token lease so concurrent workers can safely compete
+ * for eligible messages.
+ */
+export function createOutboxPortCore(
+  executor: OutboxSqlExecutor,
+  options: OutboxPortCoreOptions = {},
+): OutboxPort {
+  async function claimWith(
+    tx: OutboxSqlExecutor,
+    input: { limit: number; now: Date; leaseMs: number },
+  ): Promise<ClaimedOutboxMessage[]> {
+    const nowIso = encodeTimestamp(input.now);
+    const lockedUntilIso = encodeTimestamp(
+      new Date(input.now.getTime() + input.leaseMs),
+    );
+    const rows = (await tx.rows(sql`select * from ${tx.table}
+      where (
+        (status = 'pending' and available_at <= ${nowIso})
+        or (status = 'claimed' and locked_until is not null and locked_until <= ${nowIso})
+      )
+      order by available_at asc, created_at asc
+      limit ${input.limit}${tx.claimLockSuffix}`)) as unknown as OutboxRow[];
+    const claimed: ClaimedOutboxMessage[] = [];
+
+    for (const row of rows) {
+      const claimToken = createClaimToken();
+      const rowsAffected = await tx.run(sql`update ${tx.table}
+        set
+          status = 'claimed',
+          attempts = attempts + 1,
+          claimed_at = ${nowIso},
+          locked_until = ${lockedUntilIso},
+          claim_token = ${claimToken},
+          updated_at = ${nowIso}
+        where id = ${row.id}
+          and (
+            (status = 'pending' and available_at <= ${nowIso})
+            or (status = 'claimed' and locked_until is not null and locked_until <= ${nowIso})
+          )`);
+      if (rowsAffected !== undefined && rowsAffected <= 0) {
+        continue;
+      }
+
+      const claimedRow = (await tx.row(
+        sql`select * from ${tx.table} where id = ${row.id} and claim_token = ${claimToken}`,
+      )) as OutboxRow | undefined;
+      if (claimedRow) {
+        claimed.push(rowToClaimedMessage(claimedRow));
+      }
+    }
+
+    return claimed;
+  }
+
+  return {
+    async enqueue(input: OutboxEnqueueInput): Promise<OutboxMessage> {
+      const message = createOutboxMessage(input, {
+        now: nowFrom(options),
+      });
+      const nowIso = encodeTimestamp(message.createdAt);
+
+      await executor.run(sql`insert into ${executor.table} (
+        id,
+        kind,
+        name,
+        payload_json,
+        status,
+        attempts,
+        max_attempts,
+        available_at,
+        claimed_at,
+        locked_until,
+        claim_token,
+        delivered_at,
+        last_error_json,
+        created_at,
+        updated_at
+      ) values (
+        ${message.id},
+        ${message.kind},
+        ${message.name},
+        ${JSON.stringify(message.payload)},
+        ${message.status},
+        ${message.attempts},
+        ${message.maxAttempts},
+        ${encodeTimestamp(message.availableAt)},
+        null,
+        null,
+        null,
+        null,
+        null,
+        ${nowIso},
+        ${nowIso}
+      )`);
+
+      return message;
+    },
+
+    async claimBatch(input) {
+      const limit = input.limit;
+      if (!Number.isInteger(limit) || limit <= 0) {
+        throw new Error("limit must be a positive integer");
+      }
+      const now = input.now ?? nowFrom(options);
+      const leaseMs = input.leaseMs ?? DEFAULT_OUTBOX_LEASE_MS;
+      if (!Number.isInteger(leaseMs) || leaseMs <= 0) {
+        throw new Error("leaseMs must be a positive integer");
+      }
+      const claimInput = { limit, now, leaseMs };
+
+      const transactional = executor.withTransaction((tx) =>
+        claimWith(tx, claimInput),
+      );
+      if (transactional !== undefined) {
+        return transactional;
+      }
+
+      return claimWith(executor, claimInput);
+    },
+
+    async markDelivered(input) {
+      const nowIso = encodeTimestamp(input.now ?? nowFrom(options));
+      const rowsAffected = await executor.run(sql`update ${executor.table}
+        set
+          status = 'delivered',
+          delivered_at = ${nowIso},
+          claimed_at = null,
+          locked_until = null,
+          claim_token = null,
+          updated_at = ${nowIso}
+        where id = ${input.id}
+          and status = 'claimed'
+          and claim_token = ${input.claimToken}`);
+
+      await assertOutboxMutationSucceeded(
+        executor,
+        { id: input.id, expectedStatus: "delivered" },
+        rowsAffected,
+      );
+    },
+
+    async markFailed(input) {
+      const now = input.now ?? nowFrom(options);
+      const nowIso = encodeTimestamp(now);
+      const status: OutboxMessageStatus = input.deadLetter
+        ? "deadLettered"
+        : "pending";
+      const availableAt = input.retryAt ?? now;
+
+      const rowsAffected = await executor.run(sql`update ${executor.table}
+        set
+          status = ${status},
+          available_at = ${encodeTimestamp(availableAt)},
+          claimed_at = null,
+          locked_until = null,
+          claim_token = null,
+          last_error_json = ${JSON.stringify(serializeOutboxError(input.error))},
+          updated_at = ${nowIso}
+        where id = ${input.id}
+          and status = 'claimed'
+          and claim_token = ${input.claimToken}`);
+
+      await assertOutboxMutationSucceeded(
+        executor,
+        { id: input.id, expectedStatus: status },
+        rowsAffected,
+      );
+    },
+  };
+}