bunqueue 2.8.42 → 2.8.44

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

@@ -5,7 +5,9 @@
  * Supports: AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, etc.
  */
 import { type S3BackupConfig, type BackupResult, type BackupItem } from './s3BackupConfig';
+import { type BackupMetrics } from './backupTelemetry';
 export type { S3BackupConfig, BackupResult } from './s3BackupConfig';
+export type { BackupMetrics } from './backupTelemetry';
 /**
  * S3 Backup Manager
  * Handles automated and manual backups to S3-compatible storage
@@ -14,15 +16,15 @@ export declare class S3BackupManager {
     private readonly config;
     private readonly client;
     private readonly flushBeforeBackup?;
+    private readonly telemetry;
     private backupInterval;
     private initialBackupTimeout;
-    private isBackupInProgress;
     private dashboardEmit;
     /** Set the dashboard event emitter callback */
     setDashboardEmit(callback: (event: string, data: Record<string, unknown>) => void): void;
     constructor(config: Partial<S3BackupConfig> & {
         databasePath: string;
-        flushBeforeBackup?: () => Promise<void>;
+        flushBeforeBackup?: () => void | Promise<void>;
     });
     /**
      * Create configuration from environment variables
@@ -66,4 +68,6 @@ export declare class S3BackupManager {
         retention: number;
         isRunning: boolean;
     };
+    /** Snapshot label-free backup telemetry for the Prometheus collector. */
+    getMetrics(): BackupMetrics;
 }

package/dist/infrastructure/backup/s3Backup.js

@@ -8,6 +8,7 @@ import { S3Client } from 'bun';
 import { backupLog } from '../../shared/logger';
 import { DEFAULTS, configFromEnv, validateConfig, } from './s3BackupConfig';
 import { performBackup, listBackups, restoreBackup, cleanupOldBackups } from './s3BackupOperations';
+import { BackupTelemetry } from './backupTelemetry';
 /**
  * S3 Backup Manager
  * Handles automated and manual backups to S3-compatible storage
@@ -16,9 +17,9 @@ export class S3BackupManager {
     config;
     client;
     flushBeforeBackup;
+    telemetry;
     backupInterval = null;
     initialBackupTimeout = null;
-    isBackupInProgress = false;
     dashboardEmit = null;
     /** Set the dashboard event emitter callback */
     setDashboardEmit(callback) {
@@ -29,21 +30,27 @@ export class S3BackupManager {
             enabled: config.enabled ?? false,
             accessKeyId: config.accessKeyId ?? '',
             secretAccessKey: config.secretAccessKey ?? '',
+            sessionToken: config.sessionToken,
             bucket: config.bucket ?? '',
             endpoint: config.endpoint,
+            virtualHostedStyle: config.virtualHostedStyle,
             region: config.region ?? DEFAULTS.region,
             intervalMs: config.intervalMs ?? DEFAULTS.intervalMs,
             retention: config.retention ?? DEFAULTS.retention,
             prefix: config.prefix ?? DEFAULTS.prefix,
             databasePath: config.databasePath,
+            timeoutMs: config.timeoutMs,
         };
         this.flushBeforeBackup = config.flushBeforeBackup;
+        this.telemetry = new BackupTelemetry(this.config.enabled, this.config.intervalMs, this.config.retention);
         // Initialize S3 client
         this.client = new S3Client({
             accessKeyId: this.config.accessKeyId,
             secretAccessKey: this.config.secretAccessKey,
+            sessionToken: this.config.sessionToken,
             bucket: this.config.bucket,
             endpoint: this.config.endpoint,
+            virtualHostedStyle: this.config.virtualHostedStyle,
             region: this.config.region,
         });
     }
@@ -84,6 +91,7 @@ export class S3BackupManager {
                 backupLog.error('Scheduled backup failed', { error: String(err) });
             });
         }, this.config.intervalMs);
+        this.telemetry.setSchedulerRunning(true);
     }
     /**
      * Stop automated backup scheduler
@@ -97,17 +105,18 @@ export class S3BackupManager {
             clearInterval(this.backupInterval);
             this.backupInterval = null;
         }
+        this.telemetry.setSchedulerRunning(false);
     }
     /**
      * Perform a backup
      */
     async backup() {
-        if (this.isBackupInProgress) {
+        if (!this.telemetry.tryStart()) {
             return { success: false, error: 'Backup already in progress' };
         }
-        this.isBackupInProgress = true;
-        this.dashboardEmit?.('storage:backup-started', { bucket: this.config.bucket });
+        const startedAt = Date.now();
         try {
+            this.dashboardEmit?.('storage:backup-started', { bucket: this.config.bucket });
             if (this.flushBeforeBackup) {
                 await this.flushBeforeBackup();
             }
@@ -118,36 +127,36 @@ export class S3BackupManager {
                     bucket: this.config.bucket,
                     key: result.key,
                 });
+                this.telemetry.succeed(result, Date.now() - startedAt);
             }
             else {
                 this.dashboardEmit?.('storage:backup-failed', {
                     bucket: this.config.bucket,
                     error: result.error,
                 });
+                this.telemetry.fail(Date.now() - startedAt);
             }
             return result;
         }
         catch (err) {
+            this.telemetry.fail(Date.now() - startedAt);
             this.dashboardEmit?.('storage:backup-failed', {
                 bucket: this.config.bucket,
                 error: String(err),
             });
             throw err;
         }
-        finally {
-            this.isBackupInProgress = false;
-        }
     }
     /**
      * List available backups
      */
-    async listBackups() {
+    listBackups() {
         return listBackups(this.config, this.client);
     }
     /**
      * Restore from a backup
      */
-    async restore(key) {
+    restore(key) {
         return restoreBackup(key, this.config, this.client);
     }
     /**
@@ -163,4 +172,8 @@ export class S3BackupManager {
             isRunning: this.backupInterval !== null,
         };
     }
+    /** Snapshot label-free backup telemetry for the Prometheus collector. */
+    getMetrics() {
+        return this.telemetry.snapshot();
+    }
 }

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

@@ -10,10 +10,14 @@ export interface S3BackupConfig {
     accessKeyId: string;
     /** S3 secret access key */
     secretAccessKey: string;
+    /** Temporary credential session token */
+    sessionToken?: string;
     /** S3 bucket name */
     bucket: string;
     /** S3 endpoint (optional, for non-AWS S3-compatible services) */
     endpoint?: string;
+    /** Use bucket-name-in-host S3 requests */
+    virtualHostedStyle?: boolean;
     /** S3 region (optional, default: us-east-1) */
     region?: string;
     /** Backup interval in milliseconds (default: 6 hours) */
@@ -31,7 +35,10 @@ export interface S3BackupConfig {
 export interface BackupResult {
     success: boolean;
     key?: string;
+    /** Uncompressed SQLite database size in bytes */
     size?: number;
+    /** Uploaded gzip object size in bytes */
+    compressedSize?: number;
     duration?: number;
     error?: string;
 }

package/dist/infrastructure/backup/s3BackupConfig.js

@@ -13,12 +13,17 @@ export const DEFAULTS = {
  * Create configuration from environment variables
  */
 export function configFromEnv(databasePath) {
+    const virtualHostedStyle = Bun.env.S3_VIRTUAL_HOSTED_STYLE;
     return {
         enabled: Bun.env.S3_BACKUP_ENABLED === '1' || Bun.env.S3_BACKUP_ENABLED === 'true',
         accessKeyId: Bun.env.S3_ACCESS_KEY_ID ?? Bun.env.AWS_ACCESS_KEY_ID ?? '',
         secretAccessKey: Bun.env.S3_SECRET_ACCESS_KEY ?? Bun.env.AWS_SECRET_ACCESS_KEY ?? '',
+        sessionToken: Bun.env.S3_SESSION_TOKEN ?? Bun.env.AWS_SESSION_TOKEN,
         bucket: Bun.env.S3_BUCKET ?? Bun.env.AWS_BUCKET ?? '',
         endpoint: Bun.env.S3_ENDPOINT ?? Bun.env.AWS_ENDPOINT,
+        virtualHostedStyle: virtualHostedStyle === undefined
+            ? undefined
+            : virtualHostedStyle === '1' || virtualHostedStyle === 'true',
         region: Bun.env.S3_REGION ?? Bun.env.AWS_REGION ?? DEFAULTS.region,
         intervalMs: parseInt(Bun.env.S3_BACKUP_INTERVAL ?? '', 10) || DEFAULTS.intervalMs,
         retention: parseInt(Bun.env.S3_BACKUP_RETENTION ?? '', 10) || DEFAULTS.retention,

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

@@ -0,0 +1,23 @@
+/**
+ * Shared I/O helpers for S3 backup operations.
+ */
+import type { S3Client } from 'bun';
+export declare const DEFAULT_S3_TIMEOUT_MS = 30000;
+/** Race a promise against a timeout and always release the timeout handle. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+/** Retry an async operation with exponential backoff (500ms, 1000ms, 2000ms). */
+export declare function withRetry<T>(fn: () => Promise<T>, label: string, maxRetries?: number, baseDelayMs?: number): Promise<T>;
+/** Give every retry attempt its own configured operation timeout. */
+export declare function retryWithTimeout<T>(fn: () => Promise<T>, timeoutMs: number, label: string): Promise<T>;
+/** Async gzip compression using Web Streams. */
+export declare function gzipAsync(data: Uint8Array): Promise<Uint8Array>;
+/** Async gzip decompression using Web Streams. */
+export declare function gunzipAsync(data: Uint8Array): Promise<Uint8Array>;
+export declare function sha256(data: Uint8Array): string;
+/**
+ * Remove a payload that failed to publish, then its now-orphaned metadata.
+ *
+ * A locally timed-out PUT may still complete because Bun's S3 write cannot be
+ * aborted. In that case metadata must remain so a late payload is still paired.
+ */
+export declare function cleanupFailedPayload(client: S3Client, key: string, timeoutMs: number, uploadError: unknown): Promise<void>;

package/dist/infrastructure/backup/s3BackupIo.js

@@ -0,0 +1,106 @@
+/**
+ * Shared I/O helpers for S3 backup operations.
+ */
+import { backupLog } from '../../shared/logger';
+export const DEFAULT_S3_TIMEOUT_MS = 30_000;
+/** Race a promise against a timeout and always release the timeout handle. */
+export async function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${ms}ms`));
+        }, ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+/** Check if an error is transient and worth retrying. */
+function isTransientError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    return (lower.includes('connection reset') ||
+        lower.includes('econnreset') ||
+        lower.includes('timeout') ||
+        lower.includes('etimedout') ||
+        lower.includes('econnrefused') ||
+        lower.includes('socket hang up') ||
+        lower.includes('network') ||
+        lower.includes('503') ||
+        lower.includes('500') ||
+        lower.includes('502') ||
+        lower.includes('504') ||
+        lower.includes('service unavailable') ||
+        lower.includes('internal server error') ||
+        lower.includes('bad gateway') ||
+        lower.includes('gateway timeout') ||
+        lower.includes('transient'));
+}
+/** Retry an async operation with exponential backoff (500ms, 1000ms, 2000ms). */
+export async function withRetry(fn, label, maxRetries = 3, baseDelayMs = 500) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxRetries || !isTransientError(error)) {
+                throw error;
+            }
+            const delay = baseDelayMs * Math.pow(2, attempt);
+            backupLog.warn(`${label} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`, { error: error instanceof Error ? error.message : String(error) });
+            await Bun.sleep(delay);
+        }
+    }
+    throw lastError;
+}
+/** Give every retry attempt its own configured operation timeout. */
+export function retryWithTimeout(fn, timeoutMs, label) {
+    return withRetry(() => withTimeout(fn(), timeoutMs, label), label);
+}
+/** Async gzip compression using Web Streams. */
+export async function gzipAsync(data) {
+    const stream = new Blob([data])
+        .stream()
+        .pipeThrough(new CompressionStream('gzip'));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+/** Async gzip decompression using Web Streams. */
+export async function gunzipAsync(data) {
+    const stream = new Blob([data])
+        .stream()
+        .pipeThrough(new DecompressionStream('gzip'));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+export function sha256(data) {
+    const hasher = new Bun.CryptoHasher('sha256');
+    hasher.update(data);
+    return hasher.digest('hex');
+}
+/**
+ * Remove a payload that failed to publish, then its now-orphaned metadata.
+ *
+ * A locally timed-out PUT may still complete because Bun's S3 write cannot be
+ * aborted. In that case metadata must remain so a late payload is still paired.
+ */
+export async function cleanupFailedPayload(client, key, timeoutMs, uploadError) {
+    if (uploadError instanceof Error && uploadError.message.includes('timed out after')) {
+        return;
+    }
+    try {
+        await retryWithTimeout(() => client.delete(key), timeoutMs, 'S3 failed payload cleanup');
+        await retryWithTimeout(() => client.delete(`${key}.meta.json`), timeoutMs, 'S3 orphaned metadata cleanup');
+    }
+    catch (error) {
+        backupLog.warn('Failed to clean incomplete backup publication', {
+            key,
+            error: String(error),
+        });
+    }
+}

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

@@ -1,22 +1,13 @@
 /**
- * S3 Backup Operations
- * Core backup, restore, list, and cleanup operations
+ * S3 backup, restore, listing, and retention operations.
  */
 import type { S3Client } from 'bun';
-import type { S3BackupConfig, BackupResult, BackupItem } from './s3BackupConfig';
-/**
- * Perform a backup to S3
- */
+import type { BackupItem, BackupResult, S3BackupConfig } from './s3BackupConfig';
+/** Create and publish a consistent SQLite backup. */
 export declare function performBackup(config: S3BackupConfig, client: S3Client): Promise<BackupResult>;
-/**
- * List available backups
- */
+/** List every backup object under the configured prefix. */
 export declare function listBackups(config: S3BackupConfig, client: S3Client): Promise<BackupItem[]>;
-/**
- * Restore from a backup
- */
+/** Download, validate, and atomically install a backup. */
 export declare function restoreBackup(key: string, config: S3BackupConfig, client: S3Client): Promise<BackupResult>;
-/**
- * Clean up old backups based on retention policy
- */
+/** Delete backup pairs beyond the configured retention count. */
 export declare function cleanupOldBackups(config: S3BackupConfig, client: S3Client): Promise<void>;