@getstrata/bootstrap 2.2.9 → 2.2.10

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @getstrata/bootstrap changelog
 
+## 2.2.10
+
+- Add bounded OpenTelemetry SDK health observations and selected native transaction-acquisition histograms through explicit metrics options.
+- Add bounded Postgres failed-job counts using ORM ID projections, with schema guards, native acquisition deadlines and read-only collector draining.
+- Observe Streams retry promotion lateness using Redis time; cancellation cleanup sentinels omit unavailable age instead of reporting age since epoch.
+- Generate typed runtimeMetrics opt-in and provider-owned SQL collector draining, including startup cleanup; HTTP-only defaults and borrowed tracing ownership remain intact.
+- Keep additional SQL observation dialects, sustained operational qualification and encryption rotation explicit follow-up work.
+
 ## 2.2.9
 
 - Support native cancellable transaction acquisition

package/dist/bootstrap/metricsRoutes.d.ts

@@ -1,5 +1,7 @@
+import { type TransactionAcquisitionMetrics } from "@getstrata/core/database/transaction";
 import { type OutboxMetricsCollector } from "@getstrata/core/events/outbox";
-import { type RedisQueueSnapshotOptions } from "@getstrata/core/queue/queueMetrics";
+import { type FailedJobMetricsCollector, type RedisQueueSnapshotOptions } from "@getstrata/core/queue/queueMetrics";
+import { type TracingRuntime } from "@getstrata/core/tracing/tracingMiddleware";
 interface MetricsRoutesOptions {
     /** Opt in to shared Redis queue observations; no database or failed-job scan. */
     queue?: RedisQueueSnapshotOptions & {
@@ -7,9 +9,17 @@ interface MetricsRoutesOptions {
     };
     /** Explicit platform outbox observation; caller owns collector shutdown. */
     outbox?: Pick<OutboxMetricsCollector, "collect">;
+    /** Read an existing runtime; scraping never initializes tracing or flushes spans. */
+    tracing?: Pick<TracingRuntime, "metrics">;
+    /** Fixed process-local observations; scrape does not reserve a database connection. */
+    transactionAcquisition?: Pick<TransactionAcquisitionMetrics, "snapshot">;
+    /** Explicit global failed-job observation; caller owns collector shutdown. */
+    failedJobs?: Pick<FailedJobMetricsCollector, "collect">;
 }
 declare function createMetricsRoutes(options?: MetricsRoutesOptions): {
     "/metrics": (request: Request) => Promise<Response>;
 };
+export type { MetricsRuntime, MetricsRuntimeOptions } from "./metricsRuntime";
+export { createMetricsRuntime } from "./metricsRuntime";
 export type { MetricsRoutesOptions };
 export { createMetricsRoutes };

package/dist/bootstrap/metricsRuntime.d.ts

@@ -0,0 +1,21 @@
+import { type OutboxMetricsOptions } from "@getstrata/core/events/outbox";
+import { type FailedJobMetricsOptions } from "@getstrata/core/queue/queueMetrics";
+import type { MetricsRoutesOptions } from "./metricsRoutes";
+interface MetricsRuntimeOptions {
+    queue?: MetricsRoutesOptions["queue"];
+    outbox?: OutboxMetricsOptions;
+    failedJobs?: FailedJobMetricsOptions;
+    /** Borrowed: the existing tracing provider retains flush/shutdown ownership. */
+    tracing?: MetricsRoutesOptions["tracing"];
+    /** Borrowed: callers choose which transactions to instrument. */
+    transactionAcquisition?: MetricsRoutesOptions["transactionAcquisition"];
+}
+interface MetricsRuntime {
+    readonly options: Readonly<MetricsRoutesOptions>;
+    /** Drain owned SQL observations after HTTP admission stops and requests drain, before pool closure. */
+    close(): Promise<void>;
+}
+/** Lazy, explicit observations only: no schema provisioning, worker or tracing initialization. */
+declare function createMetricsRuntime(options?: MetricsRuntimeOptions): MetricsRuntime;
+export type { MetricsRuntime, MetricsRuntimeOptions };
+export { createMetricsRuntime };

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

@@ -28,6 +28,8 @@ export { checkDatabase, checkRedis, createHealthRoutes, pingDatabase } from "./h
 export { type RouteModelAuthorization, securedBindRouteModel, securedBindRouteModelByKey, } from "./http/securedRouteModelBinding.ts";
 export { createHttpKernel, type HttpKernel, type MiddlewareGroupName } from "./httpKernel.ts";
 export { resolveMembershipService } from "./membershipService.ts";
+export type { MetricsRoutesOptions, MetricsRuntime, MetricsRuntimeOptions, } from "./metricsRoutes.ts";
+export { createMetricsRoutes, createMetricsRuntime } from "./metricsRoutes.ts";
 export { prefixRouteMap } from "./prefixRouteMap.ts";
 export { coreProviders } from "./providers/index.ts";
 export { default as tracingProvider } from "./providers/tracing.ts";

package/dist/entries/metricsRoutes.js

@@ -1,13 +1,50 @@
 // @bun
 // ../../src/bootstrap/metricsRoutes.ts
 import { timingSafeEqual } from "crypto";
+import {
+  renderTransactionAcquisitionMetrics
+} from "@getstrata/core/database/transaction";
 import { renderOutboxMetrics } from "@getstrata/core/events/outbox";
 import { prometheusRegistry } from "@getstrata/core/metrics/prometheus";
 import {
   readRedisQueueSnapshot,
+  renderFailedJobMetrics,
   renderRedisQueueMetrics
 } from "@getstrata/core/queue/queueMetrics";
 import { isProductionEnv } from "@getstrata/core/runtime/appEnv";
+import {
+  renderTracingMetrics
+} from "@getstrata/core/tracing/tracingMiddleware";
+
+// ../../src/bootstrap/metricsRuntime.ts
+import {
+  createOutboxMetricsCollector
+} from "@getstrata/core/events/outbox";
+import {
+  createFailedJobMetricsCollector
+} from "@getstrata/core/queue/queueMetrics";
+function createMetricsRuntime(options = {}) {
+  const outbox = options.outbox ? createOutboxMetricsCollector(options.outbox) : undefined;
+  const failedJobs = options.failedJobs ? createFailedJobMetricsCollector(options.failedJobs) : undefined;
+  let closing;
+  return {
+    options: Object.freeze({
+      queue: options.queue ? { ...options.queue } : undefined,
+      outbox,
+      failedJobs,
+      tracing: options.tracing,
+      transactionAcquisition: options.transactionAcquisition
+    }),
+    close() {
+      closing ??= Promise.all([outbox?.close(), failedJobs?.close()]).then(() => {
+        return;
+      });
+      return closing;
+    }
+  };
+}
+
+// ../../src/bootstrap/metricsRoutes.ts
 function tokensMatch(left, right) {
   const leftBuffer = Buffer.from(left);
   const rightBuffer = Buffer.from(right);
@@ -31,7 +68,7 @@ function authorizeMetrics(request) {
 function createMetricsRoutes(options = {}) {
   let collection;
   const collect = () => {
-    if (!options.queue && !options.outbox)
+    if (!options.queue && !options.outbox && !options.tracing && !options.transactionAcquisition && !options.failedJobs)
       return Promise.resolve("");
     const failure = (name) => `# HELP strata_${name}_collector_success Whether the configured ${name} collection succeeded.
 # TYPE strata_${name}_collector_success gauge
@@ -39,7 +76,10 @@ strata_${name}_collector_success 0
 `;
     collection ??= Promise.all([
       options.queue ? readRedisQueueSnapshot(options.queue.redisUrl, options.queue).then(renderRedisQueueMetrics).catch(() => failure("queue")) : Promise.resolve(""),
-      options.outbox ? Promise.resolve().then(() => options.outbox?.collect()).then((snapshot) => snapshot ? renderOutboxMetrics(snapshot) : "").catch(() => failure("outbox")) : Promise.resolve("")
+      options.outbox ? Promise.resolve().then(() => options.outbox?.collect()).then((snapshot) => snapshot ? renderOutboxMetrics(snapshot) : "").catch(() => failure("outbox")) : Promise.resolve(""),
+      options.tracing ? Promise.resolve().then(() => options.tracing ? renderTracingMetrics(options.tracing.metrics()) : "").catch(() => failure("tracing")) : Promise.resolve(""),
+      options.transactionAcquisition ? Promise.resolve().then(() => options.transactionAcquisition ? renderTransactionAcquisitionMetrics(options.transactionAcquisition.snapshot()) : "").catch(() => failure("database_acquisition")) : Promise.resolve(""),
+      options.failedJobs ? Promise.resolve().then(() => options.failedJobs?.collect()).then((snapshot) => snapshot ? renderFailedJobMetrics(snapshot) : "").catch(() => failure("queue_failed_job")) : Promise.resolve("")
     ]).then((parts) => parts.join("")).finally(() => {
       collection = undefined;
     });
@@ -61,5 +101,6 @@ strata_${name}_collector_success 0
   };
 }
 export {
-  createMetricsRoutes
+  createMetricsRoutes,
+  createMetricsRuntime
 };

package/dist/index.js

@@ -1648,9 +1648,110 @@ import {
 } from "@getstrata/core/http/securedRouteModelBinding";
 // ../../src/bootstrap/membershipService.ts
 import { resolveMembershipService } from "@getstrata/core/auth/membershipService";
+// ../../src/bootstrap/metricsRoutes.ts
+import { timingSafeEqual } from "crypto";
+import {
+  renderTransactionAcquisitionMetrics
+} from "@getstrata/core/database/transaction";
+import { renderOutboxMetrics } from "@getstrata/core/events/outbox";
+import { prometheusRegistry } from "@getstrata/core/metrics/prometheus";
+import {
+  readRedisQueueSnapshot,
+  renderFailedJobMetrics,
+  renderRedisQueueMetrics
+} from "@getstrata/core/queue/queueMetrics";
+import { isProductionEnv } from "@getstrata/core/runtime/appEnv";
+import {
+  renderTracingMetrics
+} from "@getstrata/core/tracing/tracingMiddleware";
+
+// ../../src/bootstrap/metricsRuntime.ts
+import {
+  createOutboxMetricsCollector
+} from "@getstrata/core/events/outbox";
+import {
+  createFailedJobMetricsCollector
+} from "@getstrata/core/queue/queueMetrics";
+function createMetricsRuntime(options = {}) {
+  const outbox = options.outbox ? createOutboxMetricsCollector(options.outbox) : undefined;
+  const failedJobs = options.failedJobs ? createFailedJobMetricsCollector(options.failedJobs) : undefined;
+  let closing;
+  return {
+    options: Object.freeze({
+      queue: options.queue ? { ...options.queue } : undefined,
+      outbox,
+      failedJobs,
+      tracing: options.tracing,
+      transactionAcquisition: options.transactionAcquisition
+    }),
+    close() {
+      closing ??= Promise.all([outbox?.close(), failedJobs?.close()]).then(() => {
+        return;
+      });
+      return closing;
+    }
+  };
+}
+
+// ../../src/bootstrap/metricsRoutes.ts
+function tokensMatch(left, right) {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  if (leftBuffer.length !== rightBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(leftBuffer, rightBuffer);
+}
+function authorizeMetrics(request) {
+  const expected = process.env.METRICS_TOKEN?.trim();
+  const authorization = request.headers.get("authorization") ?? "";
+  const presented = authorization.startsWith("Bearer ") ? authorization.slice("Bearer ".length) : "";
+  if (expected) {
+    return presented.length > 0 && tokensMatch(presented, expected);
+  }
+  if (isProductionEnv()) {
+    return false;
+  }
+  return true;
+}
+function createMetricsRoutes(options = {}) {
+  let collection;
+  const collect = () => {
+    if (!options.queue && !options.outbox && !options.tracing && !options.transactionAcquisition && !options.failedJobs)
+      return Promise.resolve("");
+    const failure = (name) => `# HELP strata_${name}_collector_success Whether the configured ${name} collection succeeded.
+# TYPE strata_${name}_collector_success gauge
+strata_${name}_collector_success 0
+`;
+    collection ??= Promise.all([
+      options.queue ? readRedisQueueSnapshot(options.queue.redisUrl, options.queue).then(renderRedisQueueMetrics).catch(() => failure("queue")) : Promise.resolve(""),
+      options.outbox ? Promise.resolve().then(() => options.outbox?.collect()).then((snapshot) => snapshot ? renderOutboxMetrics(snapshot) : "").catch(() => failure("outbox")) : Promise.resolve(""),
+      options.tracing ? Promise.resolve().then(() => options.tracing ? renderTracingMetrics(options.tracing.metrics()) : "").catch(() => failure("tracing")) : Promise.resolve(""),
+      options.transactionAcquisition ? Promise.resolve().then(() => options.transactionAcquisition ? renderTransactionAcquisitionMetrics(options.transactionAcquisition.snapshot()) : "").catch(() => failure("database_acquisition")) : Promise.resolve(""),
+      options.failedJobs ? Promise.resolve().then(() => options.failedJobs?.collect()).then((snapshot) => snapshot ? renderFailedJobMetrics(snapshot) : "").catch(() => failure("queue_failed_job")) : Promise.resolve("")
+    ]).then((parts) => parts.join("")).finally(() => {
+      collection = undefined;
+    });
+    return collection;
+  };
+  return {
+    "/metrics": async (request) => {
+      if (!authorizeMetrics(request)) {
+        return new Response("Not Found", { status: 404 });
+      }
+      return new Response(prometheusRegistry.renderMetrics() + await collect(), {
+        status: 200,
+        headers: {
+          "content-type": "text/plain; version=0.0.4; charset=utf-8",
+          "cache-control": "no-store"
+        }
+      });
+    }
+  };
+}
 // ../../src/bootstrap/secretsGuard.ts
 import { getDefaultDatabasePool as getDefaultDatabasePool2 } from "@getstrata/core/database/defaultConnection";
-import { envFlagEnabled as envFlagEnabled3, isProductionEnv } from "@getstrata/core/runtime/appEnv";
+import { envFlagEnabled as envFlagEnabled3, isProductionEnv as isProductionEnv2 } from "@getstrata/core/runtime/appEnv";
 import { isViewsMode, parseFrontendMode } from "@getstrata/core/runtime/frontendMode";
 import {
   assertPostgresRoleCannotBypassRls,
@@ -1829,7 +1930,7 @@ function assertPublicAppUrl(env) {
   }
 }
 function assertProductionSecrets(env = process.env) {
-  if (!isProductionEnv(env)) {
+  if (!isProductionEnv2(env)) {
     return;
   }
   assertNoPlaceholderSecrets(env);
@@ -2087,7 +2188,7 @@ import {
 import { currentSqlDialect, sqlTimestamp } from "@getstrata/core/database/dialect";
 import { readRequestCookie } from "@getstrata/core/http/cookies";
 import { currentRequestMeta as currentRequestMeta3 } from "@getstrata/core/http/requestMetaContext";
-import { isProductionEnv as isProductionEnv2 } from "@getstrata/core/runtime/appEnv";
+import { isProductionEnv as isProductionEnv3 } from "@getstrata/core/runtime/appEnv";
 import { timingSafeCompareString } from "@getstrata/core/security/timingSafeCompare";
 import { runWithMigrationBypassForIdentifier } from "@getstrata/core/tenant/databaseTenantContext";
 function sqlPlaceholder(index) {
@@ -2217,7 +2318,7 @@ class CookieSessionStore {
     return sessionId;
   }
   withSecureFlag(header) {
-    if (!isProductionEnv2()) {
+    if (!isProductionEnv3()) {
       return header;
     }
     return header.includes("Secure") ? header : `${header}; Secure`;
@@ -2371,6 +2472,8 @@ export {
   createCsrfProtection,
   createHealthRoutes,
   createHttpKernel,
+  createMetricsRoutes,
+  createMetricsRuntime,
   createRouteKernel,
   createWebRoutes,
   createWebServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/bootstrap",
-  "version": "2.2.9",
+  "version": "2.2.10",
   "description": "Strata application bootstrap: HttpKernel, DI, web session helpers",
   "type": "module",
   "license": "MIT",
@@ -190,7 +190,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@getstrata/core": "^2.2.9",
+    "@getstrata/core": "^2.2.10",
     "typescript": "^5.9.0 || ^6.0.0 || ^7.0.0"
   },
   "engines": {