@getstrata/core 2.2.7 → 2.2.9

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @getstrata/core changelog
 
+## 2.2.9
+
+- Support native cancellable transaction acquisition
+
+## 2.2.8
+
+- Add bounded read-only Postgres outbox metrics
+
 ## 2.2.7
 
 - Where an ordinary operation needs SQL because the framework cannot express it

package/dist/core/database/baseRepository.d.ts

@@ -11,6 +11,12 @@ type ExtendedQueryOptions<TEntity extends object> = QueryOptions<TEntity> & {
 interface DatabaseConnection {
     unsafe<T>(query: string, params?: readonly unknown[]): Promise<T[]>;
     begin?<T>(callback: (transaction: DatabaseConnection) => Promise<T>): Promise<T>;
+    /** Optional native cancellable pool checkout; absence must not be silently emulated. */
+    reserve?(options: {
+        signal?: AbortSignal;
+    }): Promise<DatabaseConnection & {
+        release(): void | Promise<void>;
+    }>;
     /** SQLite closes synchronously; pooled drivers return a promise. */
     close?(): void | Promise<void>;
 }

package/dist/core/database/transaction.d.ts

@@ -1,4 +1,9 @@
 import type { DatabaseConnection } from "./baseRepository.ts";
 import { hasActiveTransaction, requestTransactionRollback } from "./transactionControl.ts";
-declare function runInTransaction<TValue>(operation: (connection: DatabaseConnection) => Promise<TValue>): Promise<TValue>;
+interface TransactionOptions {
+    /** Cancel admission/pool checkout only. Does not cancel SQL or an admitted business callback. */
+    acquisitionSignal?: AbortSignal;
+}
+declare function runInTransaction<TValue>(operation: (connection: DatabaseConnection) => Promise<TValue>, options?: TransactionOptions): Promise<TValue>;
+export type { TransactionOptions };
 export { hasActiveTransaction, requestTransactionRollback, runInTransaction };

package/dist/core/events/outbox/index.d.ts

@@ -50,6 +50,8 @@ declare class SqlOutbox {
     /** Operator operation: retains the event and atomically makes one failed delivery eligible. */
     replay(eventId: string, listenerName: string): Promise<void>;
 }
+export type { OutboxMetricState, OutboxMetricsCollector, OutboxMetricsOptions, OutboxMetricsSnapshot, } from "./metrics";
+export { createOutboxMetricsCollector, renderOutboxMetrics } from "./metrics";
 export { createOutboxMigration } from "./migration";
 export type { DurableEvent, DurableListener, SqlOutboxOptions };
 export { SqlOutbox };

package/dist/core/events/outbox/metrics.d.ts

@@ -0,0 +1,27 @@
+type OutboxMetricState = "pending_due" | "pending_waiting" | "processing_active" | "processing_expired" | "processing_unleased" | "failed";
+interface OutboxMetricsSnapshot {
+    sampleLimit: number;
+    states: readonly {
+        state: OutboxMetricState;
+        count: number;
+        capped: boolean;
+        actionableLatenessSeconds: number | null;
+    }[];
+}
+interface OutboxMetricsOptions {
+    timeoutMs?: number;
+    sampleLimit?: number;
+}
+interface OutboxMetricsCollector {
+    collect(): Promise<OutboxMetricsSnapshot>;
+    /** Stop new collection and wait for the underlying transaction to settle. */
+    close(): Promise<void>;
+}
+declare const snapshotQuery: string;
+/** Explicit platform observation, using the same transaction-local RLS bypass as coordination.
+ * Initially Postgres-only: other engines fail rather than receiving a false empty snapshot.
+ */
+declare function createOutboxMetricsCollector(options?: OutboxMetricsOptions): OutboxMetricsCollector;
+declare function renderOutboxMetrics(snapshot: OutboxMetricsSnapshot): string;
+export type { OutboxMetricState, OutboxMetricsCollector, OutboxMetricsOptions, OutboxMetricsSnapshot, };
+export { createOutboxMetricsCollector, renderOutboxMetrics, snapshotQuery };

package/dist/core/queue/queueMetrics.d.ts

@@ -13,3 +13,31 @@ declare function readRedisQueueDepth(redisUrl: string): Promise<QueueDepthMetric
 declare function collectQueueMetrics(): Promise<QueueMetricsSnapshot>;
 export type { QueueDepthMetrics, QueueMetricsSnapshot };
 export { collectQueueMetrics, readRedisQueueDepth };
+interface RedisQueueSnapshotOptions {
+    transport?: "lists" | "streams";
+    /** One deadline for all three priorities, including connection establishment. */
+    timeoutMs?: number;
+}
+interface QueuePrioritySnapshot {
+    priority: "high" | "default" | "low";
+    unfinished: number;
+    ready: number | null;
+    inflight: number;
+    inflightCapped: boolean;
+    retryDue: number;
+    retryWaiting: number;
+    quarantined: number;
+    /** Residence age of the oldest current stream entry, not original job age across retries. */
+    oldestStreamEntryAgeSeconds: number | null;
+}
+interface RedisQueueSnapshot {
+    transport: "lists" | "streams";
+    priorities: readonly QueuePrioritySnapshot[];
+}
+declare const INFLIGHT_SAMPLE_LIMIT = 500;
+/** Shared state, not per-process counters. Throws on missing configuration, failure or timeout. */
+declare function readRedisQueueSnapshot(redisUrl: string, options?: RedisQueueSnapshotOptions): Promise<RedisQueueSnapshot>;
+/** Fixed metric/label vocabulary; no job IDs, tenant IDs, payloads or credentials. */
+declare function renderRedisQueueMetrics(snapshot: RedisQueueSnapshot): string;
+export type { QueuePrioritySnapshot, RedisQueueSnapshot, RedisQueueSnapshotOptions };
+export { INFLIGHT_SAMPLE_LIMIT, readRedisQueueSnapshot, renderRedisQueueMetrics };

package/dist/entries/audit/exportAuditLogs.js

@@ -697,18 +697,35 @@ async function runInSavepoint(connection, operation) {
 function supportsTransactions(connection) {
   return typeof connection.begin === "function";
 }
-async function runInTransaction(operation) {
+async function runInTransaction(operation, options = {}) {
+  const signal = options.acquisitionSignal;
+  signal?.throwIfAborted();
+  const admittedOperation = (connection) => {
+    signal?.throwIfAborted();
+    return operation(connection);
+  };
   const pool = resolveRepositoryConnection();
   if (hasActiveDatabaseConnection()) {
-    return await runInSavepoint(getActiveDatabaseConnection(pool), operation);
+    return await runInSavepoint(getActiveDatabaseConnection(pool), admittedOperation);
   }
   if (!supportsTransactions(pool)) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    return await pool.begin(async (transaction) => {
-      return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await operation(createDatabaseConnection(transaction))))));
-    });
+    if (signal && !pool.reserve)
+      throw new Error("Active database connection does not support cancellable transaction acquisition.");
+    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    const connection = reserved ?? pool;
+    try {
+      signal?.throwIfAborted();
+      if (!supportsTransactions(connection))
+        throw new Error("Reserved database connection does not support transactions.");
+      return await connection.begin(async (transaction) => {
+        return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await admittedOperation(createDatabaseConnection(transaction))))));
+      });
+    } finally {
+      await reserved?.release();
+    }
   }));
 }
 var transactionFrame, outerFrames;

package/dist/entries/auth/scimAuthMiddleware.js

@@ -653,18 +653,35 @@ async function runInSavepoint(connection, operation) {
 function supportsTransactions(connection) {
   return typeof connection.begin === "function";
 }
-async function runInTransaction(operation) {
+async function runInTransaction(operation, options = {}) {
+  const signal = options.acquisitionSignal;
+  signal?.throwIfAborted();
+  const admittedOperation = (connection) => {
+    signal?.throwIfAborted();
+    return operation(connection);
+  };
   const pool = resolveRepositoryConnection();
   if (hasActiveDatabaseConnection()) {
-    return await runInSavepoint(getActiveDatabaseConnection(pool), operation);
+    return await runInSavepoint(getActiveDatabaseConnection(pool), admittedOperation);
   }
   if (!supportsTransactions(pool)) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    return await pool.begin(async (transaction) => {
-      return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await operation(createDatabaseConnection(transaction))))));
-    });
+    if (signal && !pool.reserve)
+      throw new Error("Active database connection does not support cancellable transaction acquisition.");
+    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    const connection = reserved ?? pool;
+    try {
+      signal?.throwIfAborted();
+      if (!supportsTransactions(connection))
+        throw new Error("Reserved database connection does not support transactions.");
+      return await connection.begin(async (transaction) => {
+        return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await admittedOperation(createDatabaseConnection(transaction))))));
+      });
+    } finally {
+      await reserved?.release();
+    }
   }));
 }
 var transactionFrame, outerFrames;

package/dist/entries/jobs/exportAuditLogsJob.js

@@ -697,18 +697,35 @@ async function runInSavepoint(connection, operation) {
 function supportsTransactions(connection) {
   return typeof connection.begin === "function";
 }
-async function runInTransaction(operation) {
+async function runInTransaction(operation, options = {}) {
+  const signal = options.acquisitionSignal;
+  signal?.throwIfAborted();
+  const admittedOperation = (connection) => {
+    signal?.throwIfAborted();
+    return operation(connection);
+  };
   const pool = resolveRepositoryConnection();
   if (hasActiveDatabaseConnection()) {
-    return await runInSavepoint(getActiveDatabaseConnection(pool), operation);
+    return await runInSavepoint(getActiveDatabaseConnection(pool), admittedOperation);
   }
   if (!supportsTransactions(pool)) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    return await pool.begin(async (transaction) => {
-      return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await operation(createDatabaseConnection(transaction))))));
-    });
+    if (signal && !pool.reserve)
+      throw new Error("Active database connection does not support cancellable transaction acquisition.");
+    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    const connection = reserved ?? pool;
+    try {
+      signal?.throwIfAborted();
+      if (!supportsTransactions(connection))
+        throw new Error("Reserved database connection does not support transactions.");
+      return await connection.begin(async (transaction) => {
+        return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await admittedOperation(createDatabaseConnection(transaction))))));
+      });
+    } finally {
+      await reserved?.release();
+    }
   }));
 }
 var transactionFrame, outerFrames;

package/dist/entries/queue/queueMetrics.js

@@ -1377,7 +1377,134 @@ async function collectQueueMetrics() {
     failedCount
   };
 }
+var INFLIGHT_SAMPLE_LIMIT = 500;
+var STREAM_SNAPSHOT = `
+local now = redis.call('TIME')
+local ms = tonumber(now[1])*1000 + math.floor(tonumber(now[2])/1000)
+local size = redis.call('XLEN', KEYS[1])
+local pending = redis.pcall('XPENDING', KEYS[1], ARGV[1], '-', '+', tonumber(ARGV[2])+1)
+if pending.err then
+  if not string.find(pending.err, 'NOGROUP', 1, true) then return redis.error_reply(pending.err) end
+  pending = {}
+end
+local capped = #pending > tonumber(ARGV[2]) and 1 or 0
+local inflight = math.min(#pending, tonumber(ARGV[2]))
+local ready = capped == 1 and -1 or size-inflight
+if ready < 0 and capped == 0 then return redis.error_reply('Inconsistent stream pending state') end
+local retries = redis.call('ZCARD', KEYS[2])
+local due = redis.call('ZCOUNT', KEYS[2], '-inf', ms)
+local first = redis.call('XRANGE', KEYS[1], '-', '+', 'COUNT', 1)
+local age = 0
+if #first > 0 then
+  local timestamp = tonumber(string.match(first[1][1], '^(%d+)-'))
+  age = math.max(0, ms-timestamp)/1000
+end
+return {size+retries, ready, inflight, capped, due, retries-due, redis.call('LLEN', KEYS[3]), tostring(age)}
+`;
+var LIST_SNAPSHOT = `
+local ready = redis.call('LLEN', KEYS[1])
+local inflight = redis.call('LLEN', KEYS[2])
+return {ready+inflight, ready, inflight, 0, 0, 0, redis.call('LLEN', KEYS[3]), '-1'}
+`;
+async function readRedisQueueSnapshot(redisUrl, options = {}) {
+  if (!redisUrl.trim())
+    throw new TypeError("Queue metrics require a Redis URL.");
+  const transport = options.transport ?? resolveRedisQueueTransport();
+  if (transport !== "lists" && transport !== "streams")
+    throw new TypeError("Invalid queue metrics transport.");
+  const timeoutMs = options.timeoutMs ?? 1000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 5000)
+    throw new TypeError("Queue metrics timeout must be between 1 and 5000 milliseconds.");
+  const client = new RedisClient3(redisUrl, { autoReconnect: false });
+  let timer;
+  try {
+    const work = Promise.all(defaultQueueKeys().map(async (key, index) => {
+      const keys = transport === "streams" ? [streamQueueKey(key), streamRetryKey(key), streamDeadLetterKey(key)] : [key, queueProcessingKey(key), queueInvalidKey(key)];
+      const raw = await client.send("EVAL", [
+        transport === "streams" ? STREAM_SNAPSHOT : LIST_SNAPSHOT,
+        "3",
+        ...keys,
+        STREAM_GROUP,
+        String(INFLIGHT_SAMPLE_LIMIT)
+      ]);
+      if (!Array.isArray(raw) || raw.length !== 8)
+        throw new Error("Invalid queue metrics response.");
+      const values = raw.map(Number);
+      if (values.some((value) => !Number.isFinite(value)) || values.slice(0, 7).some((value, i) => !Number.isSafeInteger(value) || value < (i === 1 ? -1 : 0)))
+        throw new Error("Invalid queue metrics values.");
+      const [unfinished, ready, inflight, capped, retryDue, retryWaiting, quarantined, age] = values;
+      if (unfinished === undefined || ready === undefined || inflight === undefined || capped === undefined || retryDue === undefined || retryWaiting === undefined || quarantined === undefined || age === undefined || capped !== 0 && capped !== 1 || age < (transport === "lists" ? -1 : 0))
+        throw new Error("Invalid queue metrics values.");
+      return {
+        priority: index === 0 ? "high" : index === 1 ? "default" : "low",
+        unfinished,
+        ready: ready === -1 ? null : ready,
+        inflight,
+        inflightCapped: capped === 1,
+        retryDue,
+        retryWaiting,
+        quarantined,
+        oldestStreamEntryAgeSeconds: transport === "streams" ? age : null
+      };
+    }));
+    const priorities = await Promise.race([
+      work,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("Queue metrics collection timed out.")), timeoutMs);
+      })
+    ]);
+    return { transport, priorities };
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+    client.close();
+  }
+}
+function renderRedisQueueMetrics(snapshot) {
+  if (snapshot.transport !== "streams" && snapshot.transport !== "lists" || snapshot.priorities.length !== 3 || new Set(snapshot.priorities.map((row) => row.priority)).size !== 3)
+    throw new TypeError("Invalid queue metrics snapshot.");
+  for (const row of snapshot.priorities) {
+    if (!["high", "default", "low"].includes(row.priority) || typeof row.inflightCapped !== "boolean" || [row.unfinished, row.inflight, row.retryDue, row.retryWaiting, row.quarantined].some((value) => !Number.isSafeInteger(value) || value < 0) || row.ready !== null && (!Number.isSafeInteger(row.ready) || row.ready < 0) || row.oldestStreamEntryAgeSeconds !== null && (!Number.isFinite(row.oldestStreamEntryAgeSeconds) || row.oldestStreamEntryAgeSeconds < 0))
+      throw new TypeError("Invalid queue metrics snapshot.");
+  }
+  const lines = [
+    "# HELP strata_queue_collector_success Whether the configured queue collection succeeded.",
+    "# TYPE strata_queue_collector_success gauge",
+    "strata_queue_collector_success 1",
+    "# HELP strata_queue_unfinished_jobs Stream/list entries plus scheduled retries, excluding quarantine and persisted failures.",
+    "# TYPE strata_queue_unfinished_jobs gauge",
+    "# HELP strata_queue_jobs Queue state; inflight_sample is a lower bound when capped.",
+    "# TYPE strata_queue_jobs gauge",
+    "# HELP strata_queue_inflight_sample_capped Whether the inflight sample was truncated; ready is omitted when truncated.",
+    "# TYPE strata_queue_inflight_sample_capped gauge",
+    "# HELP strata_queue_oldest_stream_entry_age_seconds Oldest current stream entry residence age; resets when a retry is promoted.",
+    "# TYPE strata_queue_oldest_stream_entry_age_seconds gauge"
+  ];
+  for (const priority of snapshot.priorities) {
+    const label = `priority="${priority.priority}"`;
+    lines.push(`strata_queue_unfinished_jobs{${label}} ${priority.unfinished}`);
+    const states = {
+      ready: priority.ready,
+      inflight_sample: priority.inflight,
+      retry_due: snapshot.transport === "streams" ? priority.retryDue : null,
+      retry_waiting: snapshot.transport === "streams" ? priority.retryWaiting : null,
+      quarantined: priority.quarantined
+    };
+    for (const [state, value] of Object.entries(states))
+      if (value !== null)
+        lines.push(`strata_queue_jobs{${label},state="${state}"} ${value}`);
+    lines.push(`strata_queue_inflight_sample_capped{${label}} ${Number(priority.inflightCapped)}`);
+    if (priority.oldestStreamEntryAgeSeconds !== null)
+      lines.push(`strata_queue_oldest_stream_entry_age_seconds{${label}} ${priority.oldestStreamEntryAgeSeconds}`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
 export {
+  INFLIGHT_SAMPLE_LIMIT,
   collectQueueMetrics,
-  readRedisQueueDepth
+  readRedisQueueDepth,
+  readRedisQueueSnapshot,
+  renderRedisQueueMetrics
 };

package/dist/entries/tenant/databaseTenantContext.js

@@ -697,18 +697,35 @@ async function runInSavepoint(connection, operation) {
 function supportsTransactions(connection) {
   return typeof connection.begin === "function";
 }
-async function runInTransaction(operation) {
+async function runInTransaction(operation, options = {}) {
+  const signal = options.acquisitionSignal;
+  signal?.throwIfAborted();
+  const admittedOperation = (connection) => {
+    signal?.throwIfAborted();
+    return operation(connection);
+  };
   const pool = resolveRepositoryConnection();
   if (hasActiveDatabaseConnection()) {
-    return await runInSavepoint(getActiveDatabaseConnection(pool), operation);
+    return await runInSavepoint(getActiveDatabaseConnection(pool), admittedOperation);
   }
   if (!supportsTransactions(pool)) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    return await pool.begin(async (transaction) => {
-      return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await operation(createDatabaseConnection(transaction))))));
-    });
+    if (signal && !pool.reserve)
+      throw new Error("Active database connection does not support cancellable transaction acquisition.");
+    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    const connection = reserved ?? pool;
+    try {
+      signal?.throwIfAborted();
+      if (!supportsTransactions(connection))
+        throw new Error("Reserved database connection does not support transactions.");
+      return await connection.begin(async (transaction) => {
+        return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await admittedOperation(createDatabaseConnection(transaction))))));
+      });
+    } finally {
+      await reserved?.release();
+    }
   }));
 }
 var transactionFrame, outerFrames;

package/dist/entries/tenant/tenantDatabaseScope.js

@@ -631,18 +631,35 @@ async function runInSavepoint(connection, operation) {
 function supportsTransactions(connection) {
   return typeof connection.begin === "function";
 }
-async function runInTransaction(operation) {
+async function runInTransaction(operation, options = {}) {
+  const signal = options.acquisitionSignal;
+  signal?.throwIfAborted();
+  const admittedOperation = (connection) => {
+    signal?.throwIfAborted();
+    return operation(connection);
+  };
   const pool = resolveRepositoryConnection();
   if (hasActiveDatabaseConnection()) {
-    return await runInSavepoint(getActiveDatabaseConnection(pool), operation);
+    return await runInSavepoint(getActiveDatabaseConnection(pool), admittedOperation);
   }
   if (!supportsTransactions(pool)) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    return await pool.begin(async (transaction) => {
-      return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await operation(createDatabaseConnection(transaction))))));
-    });
+    if (signal && !pool.reserve)
+      throw new Error("Active database connection does not support cancellable transaction acquisition.");
+    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    const connection = reserved ?? pool;
+    try {
+      signal?.throwIfAborted();
+      if (!supportsTransactions(connection))
+        throw new Error("Reserved database connection does not support transactions.");
+      return await connection.begin(async (transaction) => {
+        return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await admittedOperation(createDatabaseConnection(transaction))))));
+      });
+    } finally {
+      await reserved?.release();
+    }
   }));
 }
 var transactionFrame, outerFrames;

package/dist/framework/public-api.d.ts

@@ -64,6 +64,7 @@ export { loadSeedersFromDirectory, runSeedersFromDirectory, } from "../core/data
 export type { Seeder, SeederDatabase } from "../core/database/seeders/types.ts";
 export { createSqliteConnection } from "../core/database/sqliteConnection.ts";
 export { defineTable } from "../core/database/table.ts";
+export type { TransactionOptions } from "../core/database/transaction.ts";
 export { hasActiveTransaction, requestTransactionRollback, runInTransaction, } from "../core/database/transaction.ts";
 export type { ModelWhere, ModelWriteValues, QueryJoin, QueryJoinOn, QueryOptions, QueryOrder, QuerySelectItem, QueryWhere, } from "../core/database/types.ts";
 export type { WhereNode } from "../core/database/whereBuilder.ts";
@@ -72,8 +73,8 @@ export { BadRequestError, ConflictError, ForbiddenError, HttpError, InternalServ
 export type { EventListener } from "../core/events/eventBus.ts";
 export { EventBus, eventBus, readSharedEventBus } from "../core/events/eventBus.ts";
 export { dispatchModelEvent, modelEventName, runWithDeferredModelEvents, } from "../core/events/index.ts";
-export type { DurableEvent, DurableListener, SqlOutboxOptions, } from "../core/events/outbox/index.ts";
-export { createOutboxMigration, SqlOutbox } from "../core/events/outbox/index.ts";
+export type { DurableEvent, DurableListener, OutboxMetricState, OutboxMetricsCollector, OutboxMetricsOptions, OutboxMetricsSnapshot, SqlOutboxOptions, } from "../core/events/outbox/index.ts";
+export { createOutboxMetricsCollector, createOutboxMigration, renderOutboxMetrics, SqlOutbox, } from "../core/events/outbox/index.ts";
 export { auth, cache, config, events, log, mail, policyGate, queue, storage, } from "../core/facades/index.ts";
 export { createBodySizeLimitMiddleware } from "../core/http/bodySizeLimitMiddleware.ts";
 export { readClientIp, trustForwardedFor } from "../core/http/clientIp.ts";

package/dist/index.js

@@ -730,18 +730,35 @@ async function runInSavepoint(connection, operation) {
 function supportsTransactions(connection) {
   return typeof connection.begin === "function";
 }
-async function runInTransaction(operation) {
+async function runInTransaction(operation, options = {}) {
+  const signal = options.acquisitionSignal;
+  signal?.throwIfAborted();
+  const admittedOperation = (connection) => {
+    signal?.throwIfAborted();
+    return operation(connection);
+  };
   const pool = resolveRepositoryConnection();
   if (hasActiveDatabaseConnection()) {
-    return await runInSavepoint(getActiveDatabaseConnection(pool), operation);
+    return await runInSavepoint(getActiveDatabaseConnection(pool), admittedOperation);
   }
   if (!supportsTransactions(pool)) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    return await pool.begin(async (transaction) => {
-      return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await operation(createDatabaseConnection(transaction))))));
-    });
+    if (signal && !pool.reserve)
+      throw new Error("Active database connection does not support cancellable transaction acquisition.");
+    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    const connection = reserved ?? pool;
+    try {
+      signal?.throwIfAborted();
+      if (!supportsTransactions(connection))
+        throw new Error("Reserved database connection does not support transactions.");
+      return await connection.begin(async (transaction) => {
+        return await runWithDatabaseConnection(transaction, () => transactionFrame.run({ connection: transaction, childActive: false }, () => runWithTransactionScope(async () => commitOrRollbackScope(await admittedOperation(createDatabaseConnection(transaction))))));
+      });
+    } finally {
+      await reserved?.release();
+    }
   }));
 }
 var transactionFrame, outerFrames;
@@ -9164,6 +9181,165 @@ init_databaseTenantContext();
 init_tenantContext();
 init_tenantDatabaseScope();
 
+// ../../src/core/events/outbox/metrics.ts
+init_dialect();
+init_repositoryConnection();
+init_transaction();
+init_databaseTenantContext();
+var specifications = [
+  { state: "pending_due", status: "pending", column: "available_at", predicate: "<=", age: true },
+  {
+    state: "pending_waiting",
+    status: "pending",
+    column: "available_at",
+    predicate: ">",
+    age: false
+  },
+  {
+    state: "processing_active",
+    status: "processing",
+    column: "lease_until",
+    predicate: ">",
+    age: false
+  },
+  {
+    state: "processing_expired",
+    status: "processing",
+    column: "lease_until",
+    predicate: "<=",
+    age: true
+  },
+  {
+    state: "processing_unleased",
+    status: "processing",
+    column: "lease_until",
+    predicate: "IS NULL",
+    age: false
+  },
+  { state: "failed", status: "failed", column: "available_at", predicate: "", age: false }
+];
+var snapshotQuery = `WITH snapshot_clock AS MATERIALIZED (
+  SELECT CAST(EXTRACT(EPOCH FROM clock_timestamp()) * 1000 AS BIGINT) AS now_ms
+), ${specifications.map((spec, index) => `sample_${index} AS (
+  SELECT ${spec.column} AS timestamp_ms FROM strata_outbox_delivery
+  WHERE status = '${spec.status}'${spec.predicate ? ` AND ${spec.column} ${spec.predicate}${spec.predicate === "IS NULL" ? "" : " (SELECT now_ms FROM snapshot_clock)"}` : ""}
+  ORDER BY ${spec.column}, event_id, listener_name LIMIT $1
+)`).join(`,
+`)}
+${specifications.map((spec, index) => `SELECT '${spec.state}' AS state, COUNT(*) AS count,
+  ${spec.age ? `COALESCE(GREATEST(0, (SELECT now_ms FROM snapshot_clock) - MIN(timestamp_ms)), 0)` : "NULL::BIGINT"} AS lateness_ms
+  FROM sample_${index}`).join(`
+UNION ALL
+`)}`;
+function createOutboxMetricsCollector(options = {}) {
+  const timeoutMs = options.timeoutMs ?? 1000;
+  const sampleLimit = options.sampleLimit ?? 500;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 5000)
+    throw new TypeError("Outbox metrics timeout must be between 1 and 5000 milliseconds.");
+  if (!Number.isSafeInteger(sampleLimit) || sampleLimit < 1 || sampleLimit > 1000)
+    throw new TypeError("Outbox metrics sample limit must be between 1 and 1000.");
+  let active;
+  let closed = false;
+  return {
+    async collect() {
+      if (closed)
+        throw new Error("Outbox metrics collector is closed.");
+      if (hasActiveTransaction())
+        throw new Error("Outbox metrics require an independent transaction.");
+      if (currentSqlDialect().driver !== "pgsql")
+        throw new Error("Outbox metrics currently require Postgres.");
+      if (active)
+        throw new Error("Outbox metrics collection is still settling.");
+      const deadline = performance.now() + timeoutMs;
+      let expired = false;
+      const acquisition = new AbortController;
+      let timer;
+      const remaining = () => {
+        const value = Math.floor(deadline - performance.now());
+        if (expired || value < 1)
+          throw new Error("Outbox metrics collection timed out.");
+        return value;
+      };
+      const work = runInTransaction(async () => {
+        await repositoryConnection.unsafe("SELECT set_config('statement_timeout', $1, true)", [`${remaining()}ms`]);
+        await repositoryConnection.unsafe("SET TRANSACTION READ ONLY");
+        return runWithMigrationBypass(async () => {
+          remaining();
+          const rows = await repositoryConnection.unsafe(snapshotQuery, [sampleLimit + 1]);
+          remaining();
+          if (rows.length !== specifications.length)
+            throw new Error("Invalid outbox metrics response.");
+          const states = specifications.map((spec) => {
+            const row = rows.find((value) => value.state === spec.state);
+            const count = Number(row?.count);
+            const lateness = row?.lateness_ms == null ? null : Number(row.lateness_ms);
+            if (!Number.isSafeInteger(count) || count < 0 || count > sampleLimit + 1 || spec.age && (lateness === null || !Number.isFinite(lateness) || lateness < 0))
+              throw new Error("Invalid outbox metrics values.");
+            return {
+              state: spec.state,
+              count: Math.min(count, sampleLimit),
+              capped: count > sampleLimit,
+              actionableLatenessSeconds: lateness === null ? null : lateness / 1000
+            };
+          });
+          return { sampleLimit, states };
+        });
+      }, { acquisitionSignal: acquisition.signal });
+      active = work;
+      work.finally(() => {
+        if (active === work)
+          active = undefined;
+      }).catch(() => {});
+      try {
+        return await Promise.race([
+          work,
+          new Promise((_, reject) => {
+            timer = setTimeout(() => {
+              expired = true;
+              const error = new Error("Outbox metrics collection timed out.");
+              acquisition.abort(error);
+              reject(error);
+            }, timeoutMs);
+          })
+        ]);
+      } finally {
+        if (timer !== undefined)
+          clearTimeout(timer);
+      }
+    },
+    async close() {
+      closed = true;
+      await active?.catch(() => {});
+    }
+  };
+}
+function renderOutboxMetrics(snapshot) {
+  if (!Number.isSafeInteger(snapshot.sampleLimit) || snapshot.sampleLimit < 1 || snapshot.sampleLimit > 1000 || snapshot.states.length !== specifications.length)
+    throw new TypeError("Invalid outbox metrics snapshot.");
+  const lines = [
+    "# HELP strata_outbox_collector_success Whether outbox collection succeeded.",
+    "# TYPE strata_outbox_collector_success gauge",
+    "strata_outbox_collector_success 1",
+    "# HELP strata_outbox_deliveries_sample Bounded per-state delivery count; lower bound when capped.",
+    "# TYPE strata_outbox_deliveries_sample gauge",
+    "# HELP strata_outbox_sample_capped Whether the delivery sample is truncated.",
+    "# TYPE strata_outbox_sample_capped gauge",
+    "# HELP strata_outbox_actionable_lateness_seconds Oldest due-time or expired-lease lateness, not original event age.",
+    "# TYPE strata_outbox_actionable_lateness_seconds gauge"
+  ];
+  for (const spec of specifications) {
+    const row = snapshot.states.find((value) => value.state === spec.state);
+    if (!row || !Number.isSafeInteger(row.count) || row.count < 0 || row.count > snapshot.sampleLimit || typeof row.capped !== "boolean" || row.actionableLatenessSeconds !== null && (!Number.isFinite(row.actionableLatenessSeconds) || row.actionableLatenessSeconds < 0))
+      throw new TypeError("Invalid outbox metrics snapshot.");
+    lines.push(`strata_outbox_deliveries_sample{state="${spec.state}"} ${row.count}`);
+    lines.push(`strata_outbox_sample_capped{state="${spec.state}"} ${Number(row.capped)}`);
+    if (row.actionableLatenessSeconds !== null)
+      lines.push(`strata_outbox_actionable_lateness_seconds{state="${spec.state}"} ${row.actionableLatenessSeconds}`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
 // ../../src/core/events/outbox/migration.ts
 function createOutboxMigration(name, driver, options = {}) {
   const identity = driver === "mysql" ? " CHARACTER SET ascii COLLATE ascii_bin" : "";
@@ -15244,6 +15420,7 @@ export {
   createMysqlPool,
   createNotificationDispatcher,
   createOidcHandshake,
+  createOutboxMetricsCollector,
   createOutboxMigration,
   createProductionQueue,
   createQueue,
@@ -15417,6 +15594,7 @@ export {
   registerShutdownHandler,
   renderKernelErrorChrome,
   renderMarkdownMail,
+  renderOutboxMetrics,
   renderWebErrorHtml,
   repositoryConnection,
   requestIdMiddleware,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/core",
-  "version": "2.2.7",
+  "version": "2.2.9",
   "description": "Strata Bun framework public API",
   "type": "module",
   "license": "MIT",