@getstrata/core 2.2.8 → 2.2.10

package/dist/entries/tenant/databaseTenantContext.js

@@ -129,6 +129,9 @@ function unwrapTransactionRollback(error, depth = 0) {
   }
   return unwrapTransactionRollback(error.cause, depth + 1);
 }
+function hasActiveTransaction() {
+  return hasActiveDatabaseConnection() && (transactionScopes.getStore()?.rollback.length ?? 0) > 0;
+}
 function requestTransactionRollback() {
   const state = transactionScopes.getStore();
   const index = state ? state.rollback.length - 1 : -1;
@@ -344,6 +347,55 @@ var init_deferredModelEvents = __esm(() => {
   deferredModelEvents = createAsyncContextStore("@getstrata/deferredModelEvents");
 });
 
+// ../../src/core/database/acquisitionMetrics.ts
+async function observeTransactionAcquisition(metrics, acquire, signal) {
+  const state = states.get(metrics);
+  if (!state)
+    throw new TypeError("Transaction acquisition metrics must be created by the framework factory.");
+  const started = performance.now();
+  state.inflight++;
+  let outcome = "acquired";
+  try {
+    return await acquire();
+  } catch (error) {
+    outcome = signal?.aborted ? "aborted" : "failed";
+    throw error;
+  } finally {
+    state.inflight--;
+    const elapsed = Math.max(0, performance.now() - started) / 1000;
+    const histogram = state.outcomes[outcomes.indexOf(outcome)];
+    if (histogram) {
+      histogram.count++;
+      histogram.sumSeconds += elapsed;
+      for (let index = 0;index < ACQUISITION_BUCKETS_SECONDS.length; index++) {
+        const bound = ACQUISITION_BUCKETS_SECONDS[index];
+        if (bound !== undefined && elapsed <= bound)
+          histogram.buckets[index] = (histogram.buckets[index] ?? 0) + 1;
+      }
+    }
+  }
+}
+var ACQUISITION_BUCKETS_SECONDS, outcomes, metricsBrand, states;
+var init_acquisitionMetrics = __esm(() => {
+  ACQUISITION_BUCKETS_SECONDS = [
+    0.001,
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1,
+    2.5,
+    5,
+    10
+  ];
+  outcomes = ["acquired", "failed", "aborted"];
+  metricsBrand = Symbol("transaction acquisition metrics");
+  states = new WeakMap;
+});
+
 // ../../src/core/database/connection.ts
 function createDatabaseConnection(source) {
   return {
@@ -697,28 +749,51 @@ 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))))));
-    });
+    let reserved;
+    if (signal || options.acquisitionMetrics) {
+      if (!pool.reserve)
+        throw new Error(signal ? "Active database connection does not support cancellable transaction acquisition." : "Active database connection does not support observable transaction acquisition.");
+      const reserve = pool.reserve.bind(pool);
+      reserved = options.acquisitionMetrics ? await observeTransactionAcquisition(options.acquisitionMetrics, () => reserve({ signal }), signal) : await reserve({ signal });
+    }
+    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;
 var init_transaction = __esm(() => {
   init_deferredModelEvents();
   init_asyncContextStore();
+  init_acquisitionMetrics();
   init_connection();
   init_connectionContext();
   init_repositoryConnection();
   init_transactionControl();
+  init_acquisitionMetrics();
   transactionFrame = createAsyncContextStore("@getstrata/transactionFrame");
   outerFrames = new WeakMap;
 });

package/dist/entries/tenant/tenantDatabaseScope.js

@@ -52,6 +52,9 @@ function unwrapTransactionRollback(error, depth = 0) {
   }
   return unwrapTransactionRollback(error.cause, depth + 1);
 }
+function hasActiveTransaction() {
+  return hasActiveDatabaseConnection() && (transactionScopes.getStore()?.rollback.length ?? 0) > 0;
+}
 function requestTransactionRollback() {
   const state = transactionScopes.getStore();
   const index = state ? state.rollback.length - 1 : -1;
@@ -278,6 +281,55 @@ var init_deferredModelEvents = __esm(() => {
   deferredModelEvents = createAsyncContextStore("@getstrata/deferredModelEvents");
 });
 
+// ../../src/core/database/acquisitionMetrics.ts
+async function observeTransactionAcquisition(metrics, acquire, signal) {
+  const state = states.get(metrics);
+  if (!state)
+    throw new TypeError("Transaction acquisition metrics must be created by the framework factory.");
+  const started = performance.now();
+  state.inflight++;
+  let outcome = "acquired";
+  try {
+    return await acquire();
+  } catch (error) {
+    outcome = signal?.aborted ? "aborted" : "failed";
+    throw error;
+  } finally {
+    state.inflight--;
+    const elapsed = Math.max(0, performance.now() - started) / 1000;
+    const histogram = state.outcomes[outcomes.indexOf(outcome)];
+    if (histogram) {
+      histogram.count++;
+      histogram.sumSeconds += elapsed;
+      for (let index = 0;index < ACQUISITION_BUCKETS_SECONDS.length; index++) {
+        const bound = ACQUISITION_BUCKETS_SECONDS[index];
+        if (bound !== undefined && elapsed <= bound)
+          histogram.buckets[index] = (histogram.buckets[index] ?? 0) + 1;
+      }
+    }
+  }
+}
+var ACQUISITION_BUCKETS_SECONDS, outcomes, metricsBrand, states;
+var init_acquisitionMetrics = __esm(() => {
+  ACQUISITION_BUCKETS_SECONDS = [
+    0.001,
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1,
+    2.5,
+    5,
+    10
+  ];
+  outcomes = ["acquired", "failed", "aborted"];
+  metricsBrand = Symbol("transaction acquisition metrics");
+  states = new WeakMap;
+});
+
 // ../../src/core/database/connection.ts
 function createDatabaseConnection(source) {
   return {
@@ -631,28 +683,51 @@ 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))))));
-    });
+    let reserved;
+    if (signal || options.acquisitionMetrics) {
+      if (!pool.reserve)
+        throw new Error(signal ? "Active database connection does not support cancellable transaction acquisition." : "Active database connection does not support observable transaction acquisition.");
+      const reserve = pool.reserve.bind(pool);
+      reserved = options.acquisitionMetrics ? await observeTransactionAcquisition(options.acquisitionMetrics, () => reserve({ signal }), signal) : await reserve({ signal });
+    }
+    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;
 var init_transaction = __esm(() => {
   init_deferredModelEvents();
   init_asyncContextStore();
+  init_acquisitionMetrics();
   init_connection();
   init_connectionContext();
   init_repositoryConnection();
   init_transactionControl();
+  init_acquisitionMetrics();
   transactionFrame = createAsyncContextStore("@getstrata/transactionFrame");
   outerFrames = new WeakMap;
 });

package/dist/entries/tracing/tracingMiddleware.js

@@ -48,10 +48,10 @@ import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-ho
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace";
 import {
   AlwaysOffSampler,
   AlwaysOnSampler,
-  BatchSpanProcessor,
   ParentBasedSampler,
   TraceIdRatioBasedSampler
 } from "@opentelemetry/sdk-trace-base";
@@ -143,6 +143,172 @@ function sdkClientClassName() {
   return fromName ? `${fromName}Client` : "AppClient";
 }
 
+// ../../src/core/tracing/health.ts
+import {
+  createNoopMeter
+} from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
+function observeExportDeadline(state, timeoutMillis) {
+  const deadline = setTimeout(() => {
+    state.exportDeadlineExceededBatches++;
+  }, timeoutMillis);
+  deadline.unref();
+  return deadline;
+}
+function createTracingHealth(enabled, exporterConfigured, timeoutMillis) {
+  const state = {
+    enabled,
+    exporterConfigured,
+    active: true,
+    queueSize: null,
+    queueCapacity: null,
+    droppedSpans: 0,
+    exportedBatches: 0,
+    failedBatches: 0,
+    exportedSpans: 0,
+    failedSpans: 0,
+    exportDeadlineExceededBatches: 0,
+    flushFailures: 0,
+    shutdownFailures: 0
+  };
+  let exportQueueFullSpans = 0;
+  let queueCallback;
+  const noop = createNoopMeter();
+  const meter = {
+    createGauge: noop.createGauge.bind(noop),
+    createHistogram: noop.createHistogram.bind(noop),
+    createObservableGauge: noop.createObservableGauge.bind(noop),
+    createObservableCounter: noop.createObservableCounter.bind(noop),
+    addBatchObservableCallback: noop.addBatchObservableCallback.bind(noop),
+    removeBatchObservableCallback: noop.removeBatchObservableCallback.bind(noop),
+    createCounter(name, options) {
+      if (name !== "otel.sdk.processor.span.processed")
+        return noop.createCounter(name, options);
+      return {
+        add(value, attributes) {
+          if (attributes?.["error.type"] === "queue_full")
+            state.droppedSpans += value;
+        }
+      };
+    },
+    createUpDownCounter(name, options) {
+      if (name !== "otel.sdk.processor.span.queue.capacity")
+        return noop.createUpDownCounter(name, options);
+      return {
+        add(value) {
+          state.queueCapacity = (state.queueCapacity ?? 0) + value;
+        }
+      };
+    },
+    createObservableUpDownCounter(name, options) {
+      if (name !== "otel.sdk.processor.span.queue.size")
+        return noop.createObservableUpDownCounter(name, options);
+      return {
+        addCallback(callback) {
+          queueCallback = callback;
+        },
+        removeCallback(callback) {
+          if (queueCallback === callback)
+            queueCallback = undefined;
+        }
+      };
+    }
+  };
+  const meterProvider = { getMeter: () => meter };
+  return {
+    state,
+    meterProvider,
+    snapshot() {
+      let queueSize = null;
+      queueCallback?.({
+        observe(value) {
+          queueSize = value;
+        }
+      });
+      return {
+        ...state,
+        queueSize,
+        droppedSpans: Math.max(0, state.droppedSpans - exportQueueFullSpans)
+      };
+    },
+    wrap(exporter) {
+      return {
+        export(spans, callback) {
+          const count = spans.length;
+          let completed = false;
+          const deadline = observeExportDeadline(state, timeoutMillis);
+          const finish = (success) => {
+            completed = true;
+            clearTimeout(deadline);
+            if (success) {
+              state.exportedBatches++;
+              state.exportedSpans += count;
+            } else {
+              state.failedBatches++;
+              state.failedSpans += count;
+            }
+          };
+          try {
+            exporter.export(spans, (result) => {
+              if (completed)
+                return;
+              finish(result.code === ExportResultCode.SUCCESS);
+              if (result.error?.name === "queue_full")
+                exportQueueFullSpans += count;
+              callback(result);
+            });
+          } catch (error) {
+            if (!completed)
+              finish(false);
+            throw error;
+          }
+        },
+        shutdown: () => exporter.shutdown(),
+        ...exporter.forceFlush ? { forceFlush: exporter.forceFlush.bind(exporter) } : {}
+      };
+    }
+  };
+}
+function renderTracingMetrics(snapshot) {
+  for (const key of ["enabled", "exporterConfigured", "active"])
+    if (typeof snapshot[key] !== "boolean")
+      throw new TypeError("Invalid tracing metrics.");
+  const values = {
+    strata_tracing_enabled: Number(snapshot.enabled),
+    strata_tracing_exporter_configured: Number(snapshot.exporterConfigured),
+    strata_tracing_active: Number(snapshot.active),
+    strata_tracing_queue_size: snapshot.queueSize,
+    strata_tracing_queue_capacity: snapshot.queueCapacity,
+    strata_tracing_dropped_spans_total: snapshot.droppedSpans,
+    strata_tracing_exported_batches_total: snapshot.exportedBatches,
+    strata_tracing_failed_batches_total: snapshot.failedBatches,
+    strata_tracing_exported_spans_total: snapshot.exportedSpans,
+    strata_tracing_failed_spans_total: snapshot.failedSpans,
+    strata_tracing_export_deadline_exceeded_batches_total: snapshot.exportDeadlineExceededBatches,
+    strata_tracing_flush_failures_total: snapshot.flushFailures,
+    strata_tracing_shutdown_failures_total: snapshot.shutdownFailures
+  };
+  let output = `# HELP strata_tracing_collector_success Whether tracing observation succeeded.
+# TYPE strata_tracing_collector_success gauge
+strata_tracing_collector_success 1
+`;
+  for (const [name, value] of Object.entries(values)) {
+    if (value === null) {
+      if (name === "strata_tracing_queue_size" || name === "strata_tracing_queue_capacity")
+        continue;
+      throw new TypeError("Invalid tracing metrics.");
+    }
+    if (!Number.isSafeInteger(value) || value < 0)
+      throw new TypeError("Invalid tracing metrics.");
+    const type = name.endsWith("_total") ? "counter" : "gauge";
+    output += `# HELP ${name} Process-local tracing ${name.slice(15).replaceAll("_", " ")}.
+# TYPE ${name} ${type}
+${name} ${value}
+`;
+  }
+  return output;
+}
+
 // ../../src/core/tracing/otel.ts
 function numberOption(value, fallback, name, max = 1e6) {
   const result = value ?? fallback;
@@ -193,11 +359,14 @@ function createTracingRuntime(options = {}) {
       throw new TypeError("Invalid tracing collector endpoint.");
   }
   const exporter = disabled ? undefined : options.exporter ?? (endpoint ? new OTLPTraceExporter({ url: endpoint, timeoutMillis: timeout, concurrencyLimit: 1 }) : undefined);
+  const health = createTracingHealth(!disabled, exporter !== undefined, timeout);
   const provider = new NodeTracerProvider({
     resource: resourceFromAttributes({ "service.name": options.serviceName ?? otelServiceName() }),
     sampler,
     spanProcessors: exporter ? [
-      new BatchSpanProcessor(exporter, {
+      new BatchSpanProcessor({
+        exporter: health.wrap(exporter),
+        selfObsMeterProvider: health.meterProvider,
         maxQueueSize: queueSize,
         maxExportBatchSize: batchSize,
         scheduledDelayMillis: delay,
@@ -217,8 +386,21 @@ function createTracingRuntime(options = {}) {
     tracer: provider.getTracer("@getstrata/http"),
     propagator: new W3CTraceContextPropagator,
     run: (parent, callback) => context.with(parent, callback),
-    forceFlush: () => provider.forceFlush(),
-    shutdown: () => shutdown ??= provider.shutdown()
+    metrics: () => health.snapshot(),
+    async forceFlush() {
+      try {
+        await provider.forceFlush();
+      } catch (error) {
+        health.state.flushFailures++;
+        throw error;
+      }
+    },
+    shutdown: () => shutdown ??= provider.shutdown().catch((error) => {
+      health.state.shutdownFailures++;
+      throw error;
+    }).finally(() => {
+      health.state.active = false;
+    })
   };
 }
 var runtimeKey = Symbol.for("@getstrata/otel-runtime");
@@ -319,5 +501,6 @@ export {
   acquireTracingRuntime,
   createTracingMiddleware,
   createTracingRuntime,
-  getTracingRuntime
+  getTracingRuntime,
+  renderTracingMetrics
 };

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

@@ -32,6 +32,8 @@ export { CACHE_TAGS } from "../core/cache/tags.ts";
 export { ConfigStore, createServiceToken, ServiceContainer, type ServiceToken, } from "../core/contracts/container.ts";
 export type { ServiceProvider } from "../core/contracts/di.ts";
 export { resolveService } from "../core/contracts/di.ts";
+export type { TransactionAcquisitionMetrics, TransactionAcquisitionSnapshot, } from "../core/database/acquisitionMetrics.ts";
+export { createTransactionAcquisitionMetrics, renderTransactionAcquisitionMetrics, } from "../core/database/acquisitionMetrics.ts";
 export type { DatabaseConnection } from "../core/database/baseRepository.ts";
 export { default as BaseRepository } from "../core/database/baseRepository.ts";
 export { bindDatabaseConnection, getBoundDatabaseConnection, resetBoundDatabaseConnection, } from "../core/database/bindConnection.ts";
@@ -64,6 +66,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";
@@ -127,6 +130,8 @@ export { PrometheusRegistry, prometheusRegistry } from "../core/metrics/promethe
 export type { DatabaseNotificationPayload, DatabaseNotificationStore, MailNotificationMessage, Notifiable, NotificationChannelName, } from "../core/notifications/index.ts";
 export { createNotificationDispatcher, Notification, NotificationDispatcher, } from "../core/notifications/index.ts";
 export type { CursorPaginatedResult, KeysetColumn, KeysetCursor, KeysetOptions, PaginatedResult, PaginationMeta, } from "../core/pagination/index.ts";
+export type { FailedJobMetricsCollector, FailedJobMetricsOptions, FailedJobMetricsSnapshot, } from "../core/queue/failedJobMetrics.ts";
+export { createFailedJobMetricsCollector, renderFailedJobMetrics, } from "../core/queue/failedJobMetrics.ts";
 export type { Queue, QueuePriority } from "../core/queue/index.ts";
 export { AsyncQueue, createQueue, Job, SyncQueue } from "../core/queue/index.ts";
 export { JobRegistry } from "../core/queue/jobRegistry.ts";
@@ -154,6 +159,8 @@ export { currentTenant, currentTenantId, runWithTenant, tenantContext, } from ".
 export { isInsideTenantDatabaseScope, runWithTenantDatabase, } from "../core/tenant/tenantDatabaseScope.ts";
 export type { PublicTenancyOptions, TenantMiddlewareOptions, TenantResolver, } from "../core/tenant/tenantMiddleware.ts";
 export { auditChecksum, createTenantMiddleware, DEFAULT_TENANT, normalizeTenantHostname, resolveUserTenantId, } from "../core/tenant/tenantMiddleware.ts";
+export type { TracingMetricsSnapshot } from "../core/tracing/health.ts";
+export { renderTracingMetrics } from "../core/tracing/health.ts";
 export type { TraceContext } from "../core/tracing/traceContext.ts";
 export { currentTraceId, runWithTraceContext, traceContextStorage, } from "../core/tracing/traceContext.ts";
 export type { TracingOptions, TracingRuntime } from "../core/tracing/tracingMiddleware.ts";