bunqueue 2.8.42 → 2.8.44

package/README.md

@@ -181,10 +181,10 @@ anywhere in your stack — add a job from TypeScript, process it from Python:
 | Where your code runs | Install |
 | -------------------- | ------- |
 | **Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers** | [`npm install bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) |
-| **Python ≥ 3.9** | PyPI coming soon — today: `pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"` |
-| **PHP ≥ 8.1** | Packagist coming soon — today: use [`sdk/php`](./sdk/php) |
+| **Python ≥ 3.9** | [`pip install bunqueue-client`](https://pypi.org/project/bunqueue-client/) |
+| **PHP ≥ 8.1** | [`composer require bunqueue/client`](https://packagist.org/packages/bunqueue/client) |
 | **Go ≥ 1.26.5** | `go get github.com/egeominotti/bunqueue/sdk/go` |
-| **Rust ≥ 1.85** | crates.io coming soon — today: use [`sdk/rust`](./sdk/rust) as a path dependency |
+| **Rust ≥ 1.85** | [`cargo add bunqueue-client`](https://crates.io/crates/bunqueue-client) |
 | **Elixir ≥ 1.15** | Hex coming soon — today: use [`sdk/elixir`](./sdk/elixir) as a path dependency |
 
 ```typescript

package/dist/application/latencyTracker.js

@@ -11,11 +11,11 @@ export class LatencyTracker {
     /** Generate Prometheus output for all histograms */
     toPrometheus() {
         return [
-            this.push.toPrometheus('bunqueue_push_duration_ms', 'Push operation latency in milliseconds'),
+            this.push.toPrometheus('bunqueue_push_duration_seconds', 'Push operation latency in seconds', 0.001),
             '',
-            this.pull.toPrometheus('bunqueue_pull_duration_ms', 'Pull operation latency in milliseconds'),
+            this.pull.toPrometheus('bunqueue_pull_duration_seconds', 'Pull operation latency in seconds', 0.001),
             '',
-            this.ack.toPrometheus('bunqueue_ack_duration_ms', 'Ack operation latency in milliseconds'),
+            this.ack.toPrometheus('bunqueue_ack_duration_seconds', 'Ack operation latency in seconds', 0.001),
         ].join('\n');
     }
     /** Get average latencies */

package/dist/application/metricsExporter.d.ts

@@ -5,6 +5,8 @@
 import type { WorkerManager } from './workerManager';
 import type { WebhookManager } from './webhookManager';
 import type { PerQueueStats } from './statsManager';
+import { type SystemMetrics } from './prometheusOperationalMetrics';
+export type { OperationalMetrics, SystemMetrics } from './prometheusOperationalMetrics';
 /** Stats data structure */
 export interface QueueStats {
     waiting: number;
@@ -22,4 +24,4 @@ export interface QueueStats {
     cronPending: number;
 }
 /** Generate Prometheus metrics */
-export declare function generatePrometheusMetrics(stats: QueueStats, workerManager: WorkerManager, webhookManager: WebhookManager, perQueueStats?: Map<string, PerQueueStats>): string;
+export declare function generatePrometheusMetrics(stats: QueueStats, workerManager: WorkerManager, webhookManager: WebhookManager, perQueueStats?: Map<string, PerQueueStats>, systemMetrics?: SystemMetrics): string;

package/dist/application/metricsExporter.js

@@ -3,10 +3,22 @@
  * Prometheus metrics generation
  */
 import { latencyTracker } from './latencyTracker';
+import { appendOperationalMetrics } from './prometheusOperationalMetrics';
+function escapeLabel(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('\n', '\\n').replaceAll('"', '\\"');
+}
 /** Generate Prometheus metrics */
-export function generatePrometheusMetrics(stats, workerManager, webhookManager, perQueueStats) {
+export function generatePrometheusMetrics(stats, workerManager, webhookManager, perQueueStats, systemMetrics) {
     const workerStats = workerManager.getStats();
     const webhookStats = webhookManager.getStats();
+    const memory = process.memoryUsage();
+    const system = systemMetrics ?? {
+        storageDegraded: false,
+        storageDiskFull: false,
+        processHeapUsedBytes: memory.heapUsed,
+        processHeapTotalBytes: memory.heapTotal,
+        processResidentMemoryBytes: memory.rss,
+    };
     const lines = [
         '# HELP bunqueue_jobs_waiting Number of jobs waiting in queue',
         '# TYPE bunqueue_jobs_waiting gauge',
@@ -52,18 +64,26 @@ export function generatePrometheusMetrics(stats, workerManager, webhookManager,
         '# TYPE bunqueue_uptime_seconds gauge',
         `bunqueue_uptime_seconds ${Math.floor(stats.uptime / 1000)}`,
         '',
-        '# HELP bunqueue_cron_jobs_total Total number of cron jobs',
-        '# TYPE bunqueue_cron_jobs_total gauge',
-        `bunqueue_cron_jobs_total ${stats.cronJobs}`,
+        '# HELP bunqueue_cron_jobs_registered Number of registered cron jobs',
+        '# TYPE bunqueue_cron_jobs_registered gauge',
+        `bunqueue_cron_jobs_registered ${stats.cronJobs}`,
         '',
-        '# HELP bunqueue_workers_total Total number of registered workers',
-        '# TYPE bunqueue_workers_total gauge',
-        `bunqueue_workers_total ${workerStats.total}`,
+        '# HELP bunqueue_workers_registered Number of registered workers',
+        '# TYPE bunqueue_workers_registered gauge',
+        `bunqueue_workers_registered ${workerStats.total}`,
         '',
         '# HELP bunqueue_workers_active Number of active workers',
         '# TYPE bunqueue_workers_active gauge',
         `bunqueue_workers_active ${workerStats.active}`,
         '',
+        '# HELP bunqueue_worker_active_jobs Number of jobs currently processed by workers',
+        '# TYPE bunqueue_worker_active_jobs gauge',
+        `bunqueue_worker_active_jobs ${workerStats.activeJobs}`,
+        '',
+        '# HELP bunqueue_worker_concurrency_slots Configured worker concurrency capacity',
+        '# TYPE bunqueue_worker_concurrency_slots gauge',
+        `bunqueue_worker_concurrency_slots ${workerStats.concurrencySlots}`,
+        '',
         '# HELP bunqueue_workers_processed_total Total jobs processed by workers',
         '# TYPE bunqueue_workers_processed_total counter',
         `bunqueue_workers_processed_total ${workerStats.totalProcessed}`,
@@ -72,52 +92,79 @@ export function generatePrometheusMetrics(stats, workerManager, webhookManager,
         '# TYPE bunqueue_workers_failed_total counter',
         `bunqueue_workers_failed_total ${workerStats.totalFailed}`,
         '',
-        '# HELP bunqueue_webhooks_total Total number of webhooks',
-        '# TYPE bunqueue_webhooks_total gauge',
-        `bunqueue_webhooks_total ${webhookStats.total}`,
+        '# HELP bunqueue_webhooks_registered Number of registered webhooks',
+        '# TYPE bunqueue_webhooks_registered gauge',
+        `bunqueue_webhooks_registered ${webhookStats.total}`,
         '',
         '# HELP bunqueue_webhooks_enabled Number of enabled webhooks',
         '# TYPE bunqueue_webhooks_enabled gauge',
         `bunqueue_webhooks_enabled ${webhookStats.enabled}`,
+        '',
+        '# HELP bunqueue_storage_degraded Whether persistent storage is degraded',
+        '# TYPE bunqueue_storage_degraded gauge',
+        `bunqueue_storage_degraded ${system.storageDegraded ? 1 : 0}`,
+        '',
+        '# HELP bunqueue_storage_disk_full Whether persistent storage reported a full disk',
+        '# TYPE bunqueue_storage_disk_full gauge',
+        `bunqueue_storage_disk_full ${system.storageDiskFull ? 1 : 0}`,
+        '',
+        '# HELP bunqueue_process_heap_used_bytes Process heap bytes currently used',
+        '# TYPE bunqueue_process_heap_used_bytes gauge',
+        `bunqueue_process_heap_used_bytes ${system.processHeapUsedBytes}`,
+        '',
+        '# HELP bunqueue_process_heap_total_bytes Total process heap bytes',
+        '# TYPE bunqueue_process_heap_total_bytes gauge',
+        `bunqueue_process_heap_total_bytes ${system.processHeapTotalBytes}`,
+        '',
+        '# HELP bunqueue_process_resident_memory_bytes Process resident memory size in bytes',
+        '# TYPE bunqueue_process_resident_memory_bytes gauge',
+        `bunqueue_process_resident_memory_bytes ${system.processResidentMemoryBytes}`,
     ];
+    if (system.sqliteDatabaseSizeBytes !== undefined) {
+        lines.push('', '# HELP bunqueue_sqlite_database_size_bytes SQLite database file size in bytes', '# TYPE bunqueue_sqlite_database_size_bytes gauge', `bunqueue_sqlite_database_size_bytes ${system.sqliteDatabaseSizeBytes}`);
+    }
     // Per-queue metrics
     if (perQueueStats && perQueueStats.size > 0) {
         lines.push('');
         lines.push('# HELP bunqueue_queue_jobs_waiting Number of waiting jobs per queue');
         lines.push('# TYPE bunqueue_queue_jobs_waiting gauge');
         for (const [queue, qs] of perQueueStats) {
-            lines.push(`bunqueue_queue_jobs_waiting{queue="${queue}"} ${qs.waiting}`);
+            lines.push(`bunqueue_queue_jobs_waiting{queue="${escapeLabel(queue)}"} ${qs.waiting}`);
         }
         lines.push('');
         lines.push('# HELP bunqueue_queue_jobs_prioritized Number of prioritized jobs per queue');
         lines.push('# TYPE bunqueue_queue_jobs_prioritized gauge');
         for (const [queue, qs] of perQueueStats) {
-            lines.push(`bunqueue_queue_jobs_prioritized{queue="${queue}"} ${qs.prioritized}`);
+            lines.push(`bunqueue_queue_jobs_prioritized{queue="${escapeLabel(queue)}"} ${qs.prioritized}`);
         }
         lines.push('');
         lines.push('# HELP bunqueue_queue_jobs_delayed Number of delayed jobs per queue');
         lines.push('# TYPE bunqueue_queue_jobs_delayed gauge');
         for (const [queue, qs] of perQueueStats) {
-            lines.push(`bunqueue_queue_jobs_delayed{queue="${queue}"} ${qs.delayed}`);
+            lines.push(`bunqueue_queue_jobs_delayed{queue="${escapeLabel(queue)}"} ${qs.delayed}`);
         }
         lines.push('');
         lines.push('# HELP bunqueue_queue_jobs_active Number of active jobs per queue');
         lines.push('# TYPE bunqueue_queue_jobs_active gauge');
         for (const [queue, qs] of perQueueStats) {
-            lines.push(`bunqueue_queue_jobs_active{queue="${queue}"} ${qs.active}`);
+            lines.push(`bunqueue_queue_jobs_active{queue="${escapeLabel(queue)}"} ${qs.active}`);
         }
         lines.push('');
         lines.push('# HELP bunqueue_queue_jobs_dlq Number of DLQ jobs per queue');
         lines.push('# TYPE bunqueue_queue_jobs_dlq gauge');
         for (const [queue, qs] of perQueueStats) {
-            lines.push(`bunqueue_queue_jobs_dlq{queue="${queue}"} ${qs.dlq}`);
+            lines.push(`bunqueue_queue_jobs_dlq{queue="${escapeLabel(queue)}"} ${qs.dlq}`);
         }
     }
+    appendOperationalMetrics(lines, {
+        ...system,
+        perQueueMetricsExported: system.perQueueMetricsExported ?? perQueueStats?.size ?? 0,
+    });
     // Append latency histograms
     const histogramOutput = latencyTracker.toPrometheus();
     if (histogramOutput) {
         lines.push('');
         lines.push(histogramOutput);
     }
-    return lines.join('\n');
+    return `${lines.join('\n')}\n`;
 }

package/dist/application/prometheusOperationalMetrics.d.ts

@@ -0,0 +1,31 @@
+import { type BackupMetrics } from '../infrastructure/backup/backupTelemetry';
+/** Runtime/storage gauges which are not part of queue state. */
+export interface SystemMetrics {
+    storageDegraded: boolean;
+    storageDiskFull: boolean;
+    sqliteDatabaseSizeBytes?: number;
+    processHeapUsedBytes: number;
+    processHeapTotalBytes: number;
+    processResidentMemoryBytes: number;
+    processCpuSeconds?: number;
+    processStartTimeSeconds?: number;
+    perQueueMetricsExported?: number;
+    perQueueMetricsOmitted?: number;
+    operational?: OperationalMetrics;
+}
+/** Server components that are owned outside QueueManager. */
+export interface OperationalMetrics {
+    backup?: BackupMetrics;
+    connections?: {
+        tcp: number;
+        websocket: number;
+        sse: number;
+    };
+}
+/** Select a deterministic bounded prefix and report exact conservation. */
+export declare function selectPrometheusQueues(queueNames: Iterable<string>, requestedLimit: number): {
+    selected: Set<string>;
+    omitted: number;
+};
+/** Append bounded operational and standard process collectors. */
+export declare function appendOperationalMetrics(lines: string[], system: SystemMetrics): void;

package/dist/application/prometheusOperationalMetrics.js

@@ -0,0 +1,53 @@
+import { VERSION } from '../shared/version';
+import { EMPTY_BACKUP_METRICS } from '../infrastructure/backup/backupTelemetry';
+const PROCESS_START_TIME_SECONDS = Date.now() / 1000 - process.uptime();
+/** Select a deterministic bounded prefix and report exact conservation. */
+export function selectPrometheusQueues(queueNames, requestedLimit) {
+    const names = [...queueNames];
+    const limit = Number.isFinite(requestedLimit) ? Math.max(0, Math.floor(requestedLimit)) : 0;
+    const selected = new Set(names.slice(0, limit));
+    return { selected, omitted: names.length - selected.size };
+}
+function escapeLabel(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('\n', '\\n').replaceAll('"', '\\"');
+}
+function metric(lines, name, help, type, value) {
+    lines.push('', `# HELP ${name} ${help}`, `# TYPE ${name} ${type}`, `${name} ${value}`);
+}
+/** Append bounded operational and standard process collectors. */
+export function appendOperationalMetrics(lines, system) {
+    const cpu = system.processCpuSeconds ?? cpuSeconds();
+    const processStart = system.processStartTimeSeconds ?? PROCESS_START_TIME_SECONDS;
+    const backup = system.operational?.backup ?? EMPTY_BACKUP_METRICS;
+    const connections = system.operational?.connections ?? { tcp: 0, websocket: 0, sse: 0 };
+    const bunVersion = typeof Bun === 'undefined' ? 'unknown' : Bun.version;
+    lines.push('', '# HELP bunqueue_build_info Build and runtime identity', '# TYPE bunqueue_build_info gauge', `bunqueue_build_info{bun_version="${escapeLabel(bunVersion)}",version="${escapeLabel(VERSION)}"} 1`);
+    metric(lines, 'process_cpu_seconds_total', 'Total process CPU time in seconds', 'counter', cpu);
+    metric(lines, 'process_start_time_seconds', 'Start time of the process since the Unix epoch in seconds', 'gauge', processStart);
+    metric(lines, 'process_resident_memory_bytes', 'Resident memory size in bytes', 'gauge', system.processResidentMemoryBytes);
+    metric(lines, 'process_heap_bytes', 'Process heap size in bytes', 'gauge', system.processHeapTotalBytes);
+    lines.push('', '# HELP bunqueue_connections Current server connections by bounded transport', '# TYPE bunqueue_connections gauge', `bunqueue_connections{transport="tcp"} ${connections.tcp}`, `bunqueue_connections{transport="websocket"} ${connections.websocket}`, `bunqueue_connections{transport="sse"} ${connections.sse}`);
+    metric(lines, 'bunqueue_queue_metrics_exported', 'Queue names included in labelled Prometheus series', 'gauge', system.perQueueMetricsExported ?? 0);
+    metric(lines, 'bunqueue_queue_metrics_omitted', 'Queue names omitted by the Prometheus cardinality limit', 'gauge', system.perQueueMetricsOmitted ?? 0);
+    appendBackupMetrics(lines, backup);
+}
+function appendBackupMetrics(lines, backup) {
+    metric(lines, 'bunqueue_backup_enabled', 'Whether scheduled S3 backup is enabled', 'gauge', +backup.enabled);
+    metric(lines, 'bunqueue_backup_scheduler_running', 'Whether the scheduled S3 backup timer is running', 'gauge', +backup.schedulerRunning);
+    metric(lines, 'bunqueue_backup_in_progress', 'Whether an S3 backup is in progress', 'gauge', +backup.inProgress);
+    metric(lines, 'bunqueue_backup_interval_seconds', 'Configured S3 backup interval in seconds', 'gauge', backup.intervalSeconds);
+    metric(lines, 'bunqueue_backup_retention', 'Configured number of S3 backups to retain', 'gauge', backup.retention);
+    metric(lines, 'bunqueue_backup_attempts_total', 'S3 backup attempts started', 'counter', backup.attemptsTotal);
+    metric(lines, 'bunqueue_backup_successes_total', 'Successful S3 backup attempts', 'counter', backup.successesTotal);
+    metric(lines, 'bunqueue_backup_failures_total', 'Failed S3 backup attempts', 'counter', backup.failuresTotal);
+    metric(lines, 'bunqueue_backup_overlap_rejections_total', 'S3 backup requests rejected because another backup was active', 'counter', backup.overlapRejectionsTotal);
+    metric(lines, 'bunqueue_backup_consecutive_failures', 'Consecutive failed S3 backup attempts', 'gauge', backup.consecutiveFailures);
+    metric(lines, 'bunqueue_backup_last_success_timestamp_seconds', 'Unix timestamp of the last successful S3 backup, or zero', 'gauge', backup.lastSuccessTimestampSeconds);
+    metric(lines, 'bunqueue_backup_last_failure_timestamp_seconds', 'Unix timestamp of the last failed S3 backup, or zero', 'gauge', backup.lastFailureTimestampSeconds);
+    metric(lines, 'bunqueue_backup_last_duration_seconds', 'Duration of the last S3 backup attempt', 'gauge', backup.lastDurationSeconds);
+    metric(lines, 'bunqueue_backup_last_size_bytes', 'Compressed size of the last successful S3 backup', 'gauge', backup.lastSizeBytes);
+}
+function cpuSeconds() {
+    const usage = process.cpuUsage();
+    return (usage.user + usage.system) / 1_000_000;
+}

package/dist/application/queueManager.d.ts

@@ -11,6 +11,7 @@ import type { DlqConfig, DlqEntry, DlqFilter, DlqStats } from '../domain/types/d
 import { Shard } from '../domain/queue/shard';
 import { WebhookManager } from './webhookManager';
 import { WorkerManager } from './workerManager';
+import { type OperationalMetrics } from './metricsExporter';
 import { type SetLike } from '../shared/lru';
 import type { QueueManagerConfig } from './types';
 import * as statsMgr from './statsManager';
@@ -53,6 +54,7 @@ export declare class QueueManager {
     private recoveryStats;
     private readonly maxLogsPerJob;
     private readonly metrics;
+    private operationalMetricsProvider;
     private readonly perQueueMetrics;
     private readonly startTime;
     private readonly backgroundTaskHandles;
@@ -251,6 +253,8 @@ export declare class QueueManager {
     clearLogs(jobId: JobId, keepLogs?: number): void;
     getPerQueueStats(): Map<string, statsMgr.PerQueueStats>;
     getPrometheusMetrics(): string;
+    /** Attach metrics owned by server components outside the queue state machine. */
+    setOperationalMetricsProvider(provider: () => OperationalMetrics): void;
     addCron(input: CronJobInput): CronJob;
     /** Remove an orphaned cron job from the queue by its uniqueKey */
     private removeOrphanedCronJob;
@@ -363,6 +367,8 @@ export declare class QueueManager {
         error: string | null;
         since: number | null;
     };
+    /** Persist pending buffered writes before an external SQLite snapshot. */
+    flushPersistence(): number;
     compactMemory(): void;
     shutdown(): void;
 }

package/dist/application/queueManager.js

@@ -25,6 +25,7 @@ import * as queryOps from './operations/queryOperations';
 import * as dlqOps from './dlqManager';
 import * as logsOps from './jobLogsManager';
 import { generatePrometheusMetrics } from './metricsExporter';
+import { selectPrometheusQueues } from './prometheusOperationalMetrics';
 import { LRUMap, BoundedSet, BoundedMap } from '../shared/lru';
 import { DEFAULT_CONFIG } from './types';
 import * as lockMgr from './lockManager';
@@ -98,6 +99,7 @@ export class QueueManager {
         totalCompleted: { value: 0n },
         totalFailed: { value: 0n },
     };
+    operationalMetricsProvider = null;
     // LRU-bounded so high-cardinality / dynamically-named queues cannot grow it
     // without bound. Live queues stay resident (recently accessed on every
     // ack/fail); only long-idle ephemeral names are evicted. obliterate() also
@@ -1081,7 +1083,24 @@ export class QueueManager {
         return statsMgr.getPerQueueStats(this.contextFactory.getStatsContext(), this.queueNamesCache);
     }
     getPrometheusMetrics() {
-        return generatePrometheusMetrics(this.getStats(), this.workerManager, this.webhookManager, this.getPerQueueStats());
+        const storageStatus = this.getStorageStatus();
+        const memory = process.memoryUsage();
+        const queueSelection = selectPrometheusQueues(this.queueNamesCache, this.config.maxPrometheusQueues);
+        return generatePrometheusMetrics(this.getStats(), this.workerManager, this.webhookManager, statsMgr.getPerQueueStats(this.contextFactory.getStatsContext(), queueSelection.selected), {
+            storageDegraded: storageStatus.diskFull,
+            storageDiskFull: storageStatus.diskFull,
+            ...(this.storage && { sqliteDatabaseSizeBytes: this.storage.getSize() }),
+            processHeapUsedBytes: memory.heapUsed,
+            processHeapTotalBytes: memory.heapTotal,
+            processResidentMemoryBytes: memory.rss,
+            perQueueMetricsExported: queueSelection.selected.size,
+            perQueueMetricsOmitted: queueSelection.omitted,
+            operational: this.operationalMetricsProvider?.(),
+        });
+    }
+    /** Attach metrics owned by server components outside the queue state machine. */
+    setOperationalMetricsProvider(provider) {
+        this.operationalMetricsProvider = provider;
     }
     // ============ Cron Operations ============
     addCron(input) {
@@ -1620,6 +1639,10 @@ export class QueueManager {
             return { diskFull: false, error: null, since: null };
         return this.storage.getDiskFullStatus();
     }
+    /** Persist pending buffered writes before an external SQLite snapshot. */
+    flushPersistence() {
+        return this.storage?.flushWriteBuffer() ?? 0;
+    }
     compactMemory() {
         statsMgr.compactMemory(this.contextFactory.getStatsContext());
         this.dashboardEmit?.('memory:compacted', {});

package/dist/application/types.d.ts

@@ -21,6 +21,8 @@ export interface QueueManagerConfig {
     maxJobLogs?: number;
     maxCustomIds?: number;
     maxWaitingDeps?: number;
+    /** Maximum queue label values emitted in one Prometheus scrape; zero disables them. */
+    maxPrometheusQueues?: number;
     cleanupIntervalMs?: number;
     jobTimeoutCheckMs?: number;
     dependencyCheckMs?: number;
@@ -34,6 +36,7 @@ export declare const DEFAULT_CONFIG: {
     maxJobLogs: number;
     maxCustomIds: number;
     maxWaitingDeps: number;
+    maxPrometheusQueues: number;
     cleanupIntervalMs: number;
     jobTimeoutCheckMs: number;
     dependencyCheckMs: number;

package/dist/application/types.js

@@ -7,6 +7,7 @@ export const DEFAULT_CONFIG = {
     maxJobLogs: 10_000,
     maxCustomIds: 50_000,
     maxWaitingDeps: 10_000,
+    maxPrometheusQueues: 100,
     cleanupIntervalMs: 10_000,
     jobTimeoutCheckMs: 5_000,
     dependencyCheckMs: 30_000, // Safety fallback only; event-driven handles fast path

package/dist/application/workerManager.d.ts

@@ -56,5 +56,6 @@ export declare class WorkerManager {
         totalProcessed: number;
         totalFailed: number;
         activeJobs: number;
+        concurrencySlots: number;
     };
 }

package/dist/application/workerManager.js

@@ -202,10 +202,12 @@ export class WorkerManager {
     getStats() {
         const now = Date.now();
         let activeWorkers = 0;
-        // Only iterate once for active count (time-based, can't use counter)
+        let concurrencySlots = 0;
+        // Only iterate once for time-based active count and configured capacity.
         for (const worker of this.workers.values()) {
             if (now - worker.lastSeen < WORKER_TIMEOUT_MS) {
                 activeWorkers++;
+                concurrencySlots += worker.concurrency;
             }
         }
         return {
@@ -214,6 +216,7 @@ export class WorkerManager {
             totalProcessed: this.totalProcessedCounter,
             totalFailed: this.totalFailedCounter,
             activeJobs: this.totalActiveJobsCounter,
+            concurrencySlots,
         };
     }
 }

package/dist/cli/output.js

@@ -144,7 +144,8 @@ function formatStats(stats) {
         lines.push(`  Total Failed:    ${str(stats.totalFailed)}`);
     }
     if (stats.uptime !== undefined) {
-        lines.push('', `  ${color('Uptime:', colors.cyan)}      ${str(stats.uptime)}s`);
+        const uptimeSeconds = typeof stats.uptime === 'number' ? Math.floor(stats.uptime / 1000) : stats.uptime;
+        lines.push('', `  ${color('Uptime:', colors.cyan)}      ${str(uptimeSeconds)}s`);
     }
     if (stats.pushPerSec !== undefined) {
         lines.push(`  Push/sec:    ${str(stats.pushPerSec)}`);

package/dist/config/resolve.d.ts

@@ -18,6 +18,7 @@ export interface ResolvedConfig {
     dataPath: string | undefined;
     corsOrigins: string[];
     requireAuthForMetrics: boolean;
+    maxPrometheusQueues: number;
     s3BackupEnabled: boolean;
     shutdownTimeoutMs: number;
     statsIntervalMs: number;

package/dist/config/resolve.js

@@ -24,12 +24,16 @@ export function resolveServerConfig(fileConfig) {
             Bun.env.SQLITE_PATH,
         corsOrigins: fc?.cors?.origins ?? Bun.env.CORS_ALLOW_ORIGIN?.split(',').filter(Boolean) ?? [],
         requireAuthForMetrics: fc?.auth?.requireAuthForMetrics ?? Bun.env.METRICS_AUTH === 'true',
+        maxPrometheusQueues: nonNegativeInteger(fc?.telemetry?.maxPrometheusQueues ?? parseInt(Bun.env.METRICS_MAX_QUEUES ?? '100', 10), 100),
         s3BackupEnabled: fc?.backup?.enabled ??
             (Bun.env.S3_BACKUP_ENABLED === '1' || Bun.env.S3_BACKUP_ENABLED === 'true'),
         shutdownTimeoutMs: fc?.timeouts?.shutdown ?? parseInt(Bun.env.SHUTDOWN_TIMEOUT_MS ?? '30000', 10),
         statsIntervalMs: fc?.timeouts?.stats ?? parseInt(Bun.env.STATS_INTERVAL_MS ?? '300000', 10),
     };
 }
+function nonNegativeInteger(value, fallback) {
+    return Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
+}
 /**
  * Resolve server TLS options from resolved config. Returns null when TLS is
  * not configured; throws when only one of cert/key is set (fail fast at
@@ -81,12 +85,18 @@ export function resolveCloudConfig(fileConfig, dataPath) {
 /** Resolve S3 backup config: config file > env vars */
 export function resolveBackupConfig(fileConfig, databasePath) {
     const fc = fileConfig?.backup;
+    const virtualHostedStyle = Bun.env.S3_VIRTUAL_HOSTED_STYLE;
     return {
         enabled: fc?.enabled ?? (Bun.env.S3_BACKUP_ENABLED === '1' || Bun.env.S3_BACKUP_ENABLED === 'true'),
         accessKeyId: fc?.accessKeyId ?? Bun.env.S3_ACCESS_KEY_ID ?? Bun.env.AWS_ACCESS_KEY_ID ?? '',
         secretAccessKey: fc?.secretAccessKey ?? Bun.env.S3_SECRET_ACCESS_KEY ?? Bun.env.AWS_SECRET_ACCESS_KEY ?? '',
+        sessionToken: fc?.sessionToken ?? Bun.env.S3_SESSION_TOKEN ?? Bun.env.AWS_SESSION_TOKEN,
         bucket: fc?.bucket ?? Bun.env.S3_BUCKET ?? Bun.env.AWS_BUCKET ?? '',
         endpoint: fc?.endpoint ?? Bun.env.S3_ENDPOINT ?? Bun.env.AWS_ENDPOINT,
+        virtualHostedStyle: fc?.virtualHostedStyle ??
+            (virtualHostedStyle === undefined
+                ? undefined
+                : virtualHostedStyle === '1' || virtualHostedStyle === 'true'),
         region: fc?.region ?? Bun.env.S3_REGION ?? Bun.env.AWS_REGION ?? S3_DEFAULTS.region,
         intervalMs: fc?.interval ?? (parseInt(Bun.env.S3_BACKUP_INTERVAL ?? '', 10) || S3_DEFAULTS.intervalMs),
         retention: fc?.retention ?? (parseInt(Bun.env.S3_BACKUP_RETENTION ?? '', 10) || S3_DEFAULTS.retention),

package/dist/config/types.d.ts

@@ -22,6 +22,10 @@ export interface BunqueueConfig {
     storage?: {
         dataPath?: string;
     };
+    telemetry?: {
+        /** Maximum queue label values exposed to Prometheus; zero disables per-queue series. */
+        maxPrometheusQueues?: number;
+    };
     cors?: {
         origins?: string[];
     };
@@ -35,8 +39,10 @@ export interface BunqueueConfig {
         bucket?: string;
         accessKeyId?: string;
         secretAccessKey?: string;
+        sessionToken?: string;
         region?: string;
         endpoint?: string;
+        virtualHostedStyle?: boolean;
         interval?: number;
         retention?: number;
         prefix?: string;

package/dist/infrastructure/backup/backupTelemetry.d.ts

@@ -0,0 +1,30 @@
+import type { BackupResult } from './s3BackupConfig';
+/** Bounded, label-free backup metrics exposed to Prometheus. */
+export interface BackupMetrics {
+    enabled: boolean;
+    schedulerRunning: boolean;
+    inProgress: boolean;
+    intervalSeconds: number;
+    retention: number;
+    attemptsTotal: number;
+    successesTotal: number;
+    failuresTotal: number;
+    overlapRejectionsTotal: number;
+    consecutiveFailures: number;
+    lastSuccessTimestampSeconds: number;
+    lastFailureTimestampSeconds: number;
+    lastDurationSeconds: number;
+    lastSizeBytes: number;
+}
+export declare const EMPTY_BACKUP_METRICS: BackupMetrics;
+/** State machine for backup attempts; all transitions preserve counter conservation. */
+export declare class BackupTelemetry {
+    private readonly metrics;
+    constructor(enabled: boolean, intervalMs: number, retention: number);
+    setSchedulerRunning(running: boolean): void;
+    tryStart(): boolean;
+    succeed(result: BackupResult, durationMs: number, nowMs?: number): void;
+    fail(durationMs: number, nowMs?: number): void;
+    snapshot(): BackupMetrics;
+    private finish;
+}

package/dist/infrastructure/backup/backupTelemetry.js

@@ -0,0 +1,63 @@
+export const EMPTY_BACKUP_METRICS = {
+    enabled: false,
+    schedulerRunning: false,
+    inProgress: false,
+    intervalSeconds: 0,
+    retention: 0,
+    attemptsTotal: 0,
+    successesTotal: 0,
+    failuresTotal: 0,
+    overlapRejectionsTotal: 0,
+    consecutiveFailures: 0,
+    lastSuccessTimestampSeconds: 0,
+    lastFailureTimestampSeconds: 0,
+    lastDurationSeconds: 0,
+    lastSizeBytes: 0,
+};
+/** State machine for backup attempts; all transitions preserve counter conservation. */
+export class BackupTelemetry {
+    metrics;
+    constructor(enabled, intervalMs, retention) {
+        this.metrics = {
+            ...EMPTY_BACKUP_METRICS,
+            enabled,
+            intervalSeconds: intervalMs / 1000,
+            retention,
+        };
+    }
+    setSchedulerRunning(running) {
+        this.metrics.schedulerRunning = running;
+    }
+    tryStart() {
+        if (this.metrics.inProgress) {
+            this.metrics.overlapRejectionsTotal++;
+            return false;
+        }
+        this.metrics.inProgress = true;
+        this.metrics.attemptsTotal++;
+        return true;
+    }
+    succeed(result, durationMs, nowMs = Date.now()) {
+        this.finish(durationMs);
+        this.metrics.successesTotal++;
+        this.metrics.consecutiveFailures = 0;
+        this.metrics.lastSuccessTimestampSeconds = nowMs / 1000;
+        this.metrics.lastSizeBytes = result.compressedSize ?? result.size ?? 0;
+    }
+    fail(durationMs, nowMs = Date.now()) {
+        this.finish(durationMs);
+        this.metrics.failuresTotal++;
+        this.metrics.consecutiveFailures++;
+        this.metrics.lastFailureTimestampSeconds = nowMs / 1000;
+    }
+    snapshot() {
+        return { ...this.metrics };
+    }
+    finish(durationMs) {
+        if (!this.metrics.inProgress) {
+            throw new Error('Cannot finish backup telemetry without an active attempt');
+        }
+        this.metrics.inProgress = false;
+        this.metrics.lastDurationSeconds = Math.max(durationMs, 0) / 1000;
+    }
+}

package/dist/infrastructure/backup/index.d.ts

@@ -1,4 +1,4 @@
 /**
  * Backup Module Exports
  */
-export { S3BackupManager, type S3BackupConfig, type BackupResult } from './s3Backup';
+export { S3BackupManager, type S3BackupConfig, type BackupResult, type BackupMetrics, } from './s3Backup';

package/dist/infrastructure/backup/index.js

@@ -1,4 +1,4 @@
 /**
  * Backup Module Exports
  */
-export { S3BackupManager } from './s3Backup';
+export { S3BackupManager, } from './s3Backup';