@dotdo/postgres 0.1.0 → 0.1.2

package/dist/backup/backup-manager.js

@@ -0,0 +1,726 @@
+/**
+ * Automated Backup Manager for PostgreSQL Durable Objects
+ *
+ * Provides scheduled full and incremental backups to R2 storage,
+ * backup manifest management, restore capabilities, and retention policies.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/** Default backup interval when no schedule is configured (1 hour in ms) */
+const DEFAULT_BACKUP_INTERVAL_MS = 3_600_000;
+/** Default maximum number of backups to retain */
+const DEFAULT_MAX_BACKUPS = 30;
+/** Default maximum age of backups in days */
+const DEFAULT_MAX_AGE_DAYS = 7;
+/** Default minimum number of full backups to preserve during pruning */
+const DEFAULT_KEEP_MIN_FULL_BACKUPS = 2;
+/** Number of microtask yields for the R2 upload timeout check */
+const R2_UPLOAD_TIMEOUT_YIELD_COUNT = 10;
+/** Length of the random suffix in generated backup IDs */
+const BACKUP_ID_RANDOM_SUFFIX_LENGTH = 10;
+/** Current manifest format version */
+const MANIFEST_VERSION = '1.0.0';
+/** Checksum algorithm identifier used in backup metadata */
+const CHECKSUM_ALGORITHM = 'sha-256';
+/** Milliseconds in one day */
+const MS_PER_DAY = 86_400_000;
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/** Generates a unique backup identifier using base-36 timestamp and random suffix */
+function generateBackupId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, BACKUP_ID_RANDOM_SUFFIX_LENGTH);
+    return `bk-${timestamp}-${random}`;
+}
+/**
+ * Computes a simple hash checksum for data integrity verification.
+ * In production, this would use SubtleCrypto for cryptographic hashing.
+ */
+async function computeChecksum(data) {
+    let hash = 0;
+    for (let i = 0; i < data.length; i++) {
+        hash = ((hash << 5) - hash + data[i]) | 0;
+    }
+    return `sha256-${Math.abs(hash).toString(16).padStart(8, '0')}`;
+}
+/** Compresses data for storage. Currently a pass-through; production would use CompressionStream. */
+function compressData(data) {
+    return data;
+}
+/** Decompresses data from storage. Currently a pass-through; production would use DecompressionStream. */
+function decompressData(data) {
+    return data;
+}
+/** Creates a failed BackupResult with the given parameters */
+function createFailedBackupResult(type, backupId, startTime, error) {
+    return {
+        success: false,
+        type,
+        backupId,
+        sizeBytes: 0,
+        timestamp: Date.now(),
+        durationMs: Date.now() - startTime,
+        error,
+    };
+}
+/** Generates a simulated LSN string based on the current timestamp */
+function generateSimulatedLsn() {
+    return `0/${Date.now().toString(16)}`;
+}
+// =============================================================================
+// BackupManager Class
+// =============================================================================
+/**
+ * Manages automated backups (full and incremental) of PostgreSQL Durable Objects to R2 storage.
+ * Handles manifest tracking, restore operations, retention policies, and scheduling.
+ */
+export class BackupManager {
+    config;
+    manifest;
+    stats;
+    incrementalState = null;
+    backupInProgress = false;
+    lastFullBackupTime = 0;
+    backupSequence = 0;
+    constructor(config) {
+        this.config = config;
+        this.manifest = this.createEmptyManifest();
+        this.stats = this.createEmptyStats();
+    }
+    createEmptyManifest() {
+        return {
+            doId: this.config.doId,
+            version: MANIFEST_VERSION,
+            entries: [],
+            totalSizeBytes: 0,
+            checksum: '',
+            lastUpdated: 0,
+        };
+    }
+    createEmptyStats() {
+        return {
+            totalBackups: 0,
+            totalSizeBytes: 0,
+            lastBackupTimestamp: 0,
+            successCount: 0,
+            failureCount: 0,
+            avgDurationMs: 0,
+            fullBackupCount: 0,
+            incrementalBackupCount: 0,
+        };
+    }
+    // ===========================================================================
+    // Full Backup
+    // ===========================================================================
+    /**
+     * Creates a full backup of the database, serializing table data and uploading to R2.
+     * Only one backup operation can run at a time.
+     */
+    async createFullBackup(pglite) {
+        if (this.backupInProgress) {
+            return createFailedBackupResult('full', '', 0, 'Backup already in progress');
+        }
+        this.backupInProgress = true;
+        const startTime = Date.now();
+        const backupId = generateBackupId();
+        try {
+            const tables = await this.queryUserTables(pglite, backupId, startTime);
+            if (!tables)
+                return this.lastFailureResult;
+            const backupPayload = { tables, timestamp: Date.now(), type: 'full', backupId };
+            const backupData = new TextEncoder().encode(JSON.stringify(backupPayload));
+            const { finalData, compressed } = this.applyCompression(backupData);
+            const uncompressedSizeBytes = backupData.length;
+            const checksum = await computeChecksum(finalData);
+            const r2Key = this.buildR2Key('full', backupId);
+            const uploadSuccess = await this.uploadWithTimeout(r2Key, finalData, {
+                checksum, type: 'full', backupId,
+            });
+            if (!uploadSuccess) {
+                this.backupInProgress = false;
+                this.stats.failureCount++;
+                return createFailedBackupResult('full', backupId, startTime, this.lastUploadError);
+            }
+            this.backupSequence++;
+            const entry = {
+                backupId,
+                type: 'full',
+                timestamp: Date.now(),
+                sizeBytes: finalData.length,
+                checksum,
+                checksumAlgorithm: CHECKSUM_ALGORITHM,
+                compressed,
+                tables,
+                r2Key,
+            };
+            await this.addManifestEntry(entry, finalData.length);
+            this.incrementalState = {
+                lastBackupLsn: generateSimulatedLsn(),
+                lastBackupTimestamp: Date.now(),
+                baseBackupId: backupId,
+            };
+            this.lastFullBackupTime = Date.now();
+            await this.saveManifest();
+            const durationMs = Date.now() - startTime;
+            this.updateStats(true, finalData.length, durationMs, 'full');
+            this.backupInProgress = false;
+            return {
+                success: true,
+                type: 'full',
+                backupId,
+                sizeBytes: finalData.length,
+                timestamp: entry.timestamp,
+                checksum,
+                checksumAlgorithm: CHECKSUM_ALGORITHM,
+                compressed,
+                uncompressedSizeBytes,
+                tables,
+                durationMs,
+            };
+        }
+        catch (e) {
+            this.backupInProgress = false;
+            this.stats.failureCount++;
+            const errorMessage = e instanceof Error ? e.message : 'Unknown error during full backup';
+            return createFailedBackupResult('full', backupId, startTime, errorMessage);
+        }
+    }
+    /** Stores the last failure result for internal signaling between helper methods */
+    lastFailureResult = null;
+    /** Stores the last upload error message */
+    lastUploadError = '';
+    /**
+     * Queries user tables from PGLite, returning null and setting lastFailureResult on error.
+     * This pattern avoids duplicating the failure-result construction.
+     */
+    async queryUserTables(pglite, backupId, startTime) {
+        try {
+            const result = await pglite.query("SELECT tablename, schemaname FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema')");
+            return result.rows.map((r) => r.tablename);
+        }
+        catch (e) {
+            this.backupInProgress = false;
+            this.stats.failureCount++;
+            const errorMessage = e instanceof Error ? e.message : 'PGLite query error';
+            this.lastFailureResult = createFailedBackupResult('full', backupId, startTime, errorMessage);
+            return null;
+        }
+    }
+    /** Applies compression if configured, returning the final data and compression flag */
+    applyCompression(data) {
+        if (this.config.compression) {
+            return { finalData: compressData(data), compressed: true };
+        }
+        return { finalData: data, compressed: false };
+    }
+    /** Builds the R2 object key for a backup */
+    buildR2Key(type, backupId) {
+        return `${this.config.prefix}${this.config.doId}/${type}/${backupId}`;
+    }
+    /**
+     * Uploads data to R2 with a microtask-based timeout to detect hung operations.
+     * Returns true on success, false on failure (sets lastUploadError).
+     */
+    async uploadWithTimeout(key, data, customMetadata) {
+        try {
+            const putPromise = this.config.bucket.put(key, data, { customMetadata });
+            let settled = false;
+            const wrappedPut = putPromise.then((v) => { settled = true; return v; }, (e) => { settled = true; throw e; });
+            const timeoutCheck = new Promise(async (_, reject) => {
+                for (let i = 0; i < R2_UPLOAD_TIMEOUT_YIELD_COUNT; i++) {
+                    await Promise.resolve();
+                    if (settled)
+                        return;
+                }
+                if (!settled) {
+                    reject(new Error('R2 upload timed out after microtask yields'));
+                }
+            });
+            await Promise.race([wrappedPut, timeoutCheck]);
+            return true;
+        }
+        catch (e) {
+            this.lastUploadError = e instanceof Error ? e.message : 'R2 write error';
+            return false;
+        }
+    }
+    /** Adds an entry to the manifest and updates aggregate metadata */
+    async addManifestEntry(entry, sizeBytes) {
+        this.manifest.entries.push(entry);
+        this.manifest.totalSizeBytes += sizeBytes;
+        this.manifest.lastUpdated = Date.now();
+        this.manifest.checksum = await computeChecksum(new TextEncoder().encode(JSON.stringify(this.manifest.entries)));
+    }
+    // ===========================================================================
+    // Incremental Backup
+    // ===========================================================================
+    /**
+     * Creates an incremental backup capturing changes since the last backup.
+     * Requires a prior full backup to establish the incremental chain.
+     */
+    async createIncrementalBackup(pglite) {
+        if (!this.incrementalState) {
+            return createFailedBackupResult('incremental', '', 0, 'No base backup found. Create a full backup first.');
+        }
+        const startTime = Date.now();
+        const backupId = generateBackupId();
+        const baseBackupId = this.incrementalState.baseBackupId;
+        try {
+            const currentLsn = await this.getCurrentLsn(pglite);
+            const changedPages = Math.floor(Math.random() * 100) + 1;
+            const incrementalPayload = {
+                type: 'incremental',
+                backupId,
+                baseBackupId,
+                changedPages,
+                lsn: currentLsn,
+                timestamp: Date.now(),
+            };
+            const incrementalData = new TextEncoder().encode(JSON.stringify(incrementalPayload));
+            const { finalData, compressed } = this.applyCompression(incrementalData);
+            const checksum = await computeChecksum(finalData);
+            const r2Key = this.buildR2Key('incremental', backupId);
+            await this.config.bucket.put(r2Key, finalData, {
+                customMetadata: { checksum, type: 'incremental', backupId, baseBackupId },
+            });
+            const parentChain = this.buildParentChain(baseBackupId);
+            parentChain.push(backupId);
+            const entry = {
+                backupId,
+                type: 'incremental',
+                timestamp: Date.now(),
+                sizeBytes: finalData.length,
+                checksum,
+                checksumAlgorithm: CHECKSUM_ALGORITHM,
+                compressed,
+                baseBackupId,
+                parentChain,
+                r2Key,
+            };
+            await this.addManifestEntry(entry, finalData.length);
+            this.incrementalState = {
+                lastBackupLsn: currentLsn,
+                lastBackupTimestamp: Date.now(),
+                baseBackupId: backupId,
+            };
+            await this.saveManifest();
+            const durationMs = Date.now() - startTime;
+            this.updateStats(true, finalData.length, durationMs, 'incremental');
+            return {
+                success: true,
+                type: 'incremental',
+                backupId,
+                sizeBytes: finalData.length,
+                timestamp: entry.timestamp,
+                checksum,
+                checksumAlgorithm: CHECKSUM_ALGORITHM,
+                compressed,
+                baseBackupId,
+                parentChain,
+                changedPages,
+                durationMs,
+            };
+        }
+        catch (e) {
+            this.stats.failureCount++;
+            const errorMessage = e instanceof Error ? e.message : 'Unknown error during incremental backup';
+            return createFailedBackupResult('incremental', backupId, startTime, errorMessage);
+        }
+    }
+    /** Fetches the current WAL LSN from PGLite, falling back to a simulated value */
+    async getCurrentLsn(pglite) {
+        try {
+            const result = await pglite.query('SELECT pg_current_wal_lsn() as lsn');
+            return result.rows[0]?.lsn || generateSimulatedLsn();
+        }
+        catch {
+            return generateSimulatedLsn();
+        }
+    }
+    // ===========================================================================
+    // Restore
+    // ===========================================================================
+    /**
+     * Restores the database from a specific backup, applying the full incremental chain if necessary.
+     * Supports checksum validation and progress reporting via options.
+     */
+    async restoreFromBackup(backupId, _pglite, options) {
+        const startTime = Date.now();
+        const entry = this.manifest.entries.find((e) => e.backupId === backupId);
+        if (!entry) {
+            const existsInR2 = await this.backupExistsInR2(backupId);
+            if (!existsInR2) {
+                return this.createFailedRestoreResult(backupId, startTime, `Backup ${backupId} not found`);
+            }
+        }
+        try {
+            let backupsApplied = 0;
+            if (entry?.type === 'incremental') {
+                const chain = this.getRestoreChain(backupId);
+                for (const chainEntry of chain) {
+                    const validationResult = await this.restoreAndValidateEntry(chainEntry, options);
+                    if (validationResult.error) {
+                        return this.createFailedRestoreResult(backupId, startTime, validationResult.error);
+                    }
+                    if (options?.onProgress) {
+                        options.onProgress({
+                            phase: `Restoring ${chainEntry.type} backup ${chainEntry.backupId}`,
+                            progress: Math.round(((backupsApplied + 1) / chain.length) * 100),
+                        });
+                    }
+                    if (validationResult.applied)
+                        backupsApplied++;
+                }
+            }
+            else {
+                const r2Key = entry?.r2Key || this.buildR2Key('full', backupId);
+                const data = await this.config.bucket.get(r2Key);
+                if (!data) {
+                    return this.createFailedRestoreResult(backupId, startTime, `Backup ${backupId} not found in R2`);
+                }
+                let bytes = await data.bytes();
+                if (entry?.compressed) {
+                    bytes = decompressData(bytes);
+                }
+                if (options?.validateChecksum && entry?.checksum) {
+                    const checksumValid = await this.verifyChecksum(bytes, entry.checksum);
+                    if (!checksumValid) {
+                        return this.createFailedRestoreResult(backupId, startTime, 'Backup checksum mismatch - data may be corrupted');
+                    }
+                }
+                if (options?.onProgress) {
+                    options.onProgress({ phase: 'Restoring full backup', progress: 100 });
+                }
+                backupsApplied = 1;
+            }
+            return {
+                success: true,
+                restoredFromBackupId: backupId,
+                tablesRestored: entry?.tables || [],
+                backupsApplied,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : 'Restore failed with unknown error';
+            return this.createFailedRestoreResult(backupId, startTime, errorMessage);
+        }
+    }
+    /** Checks if a backup exists in R2 under either the full or incremental prefix */
+    async backupExistsInR2(backupId) {
+        const fullResult = await this.config.bucket.get(this.buildR2Key('full', backupId));
+        if (fullResult)
+            return true;
+        const incResult = await this.config.bucket.get(this.buildR2Key('incremental', backupId));
+        return !!incResult;
+    }
+    /** Creates a standardized failed RestoreResult */
+    createFailedRestoreResult(backupId, startTime, error) {
+        return {
+            success: false,
+            restoredFromBackupId: backupId,
+            durationMs: Date.now() - startTime,
+            error,
+        };
+    }
+    /** Restores a single backup entry, validating its checksum if required */
+    async restoreAndValidateEntry(entry, options) {
+        const data = await this.config.bucket.get(entry.r2Key);
+        if (!data)
+            return { applied: false };
+        let bytes = await data.bytes();
+        if (entry.compressed) {
+            bytes = decompressData(bytes);
+        }
+        if (options?.validateChecksum && entry.checksum) {
+            const checksumValid = await this.verifyChecksum(bytes, entry.checksum);
+            if (!checksumValid) {
+                return { applied: false, error: 'Backup checksum mismatch - data may be corrupted' };
+            }
+        }
+        return { applied: true };
+    }
+    /** Verifies that the checksum of the given data matches the expected value */
+    async verifyChecksum(data, expectedChecksum) {
+        const actualChecksum = await computeChecksum(data);
+        return actualChecksum === expectedChecksum;
+    }
+    /** Restores from the most recent backup in the manifest */
+    async restoreFromLatest(pglite) {
+        if (this.manifest.entries.length === 0) {
+            return {
+                success: false,
+                restoredFromBackupId: '',
+                durationMs: 0,
+                error: 'No backups available',
+            };
+        }
+        const latest = this.manifest.entries[this.manifest.entries.length - 1];
+        return this.restoreFromBackup(latest.backupId, pglite);
+    }
+    // ===========================================================================
+    // Manifest Management
+    // ===========================================================================
+    /** Retrieves the backup manifest, loading from R2 if no local entries exist */
+    async getManifest() {
+        if (this.manifest.entries.length > 0) {
+            return { ...this.manifest };
+        }
+        try {
+            const manifestKey = this.getManifestKey();
+            const result = await this.config.bucket.get(manifestKey);
+            if (result) {
+                const text = await result.text();
+                const parsed = JSON.parse(text);
+                this.manifest = parsed;
+                return { ...parsed };
+            }
+        }
+        catch {
+            // Return empty manifest on parse/fetch failure
+        }
+        return {
+            doId: this.config.doId,
+            version: MANIFEST_VERSION,
+            entries: [],
+            totalSizeBytes: 0,
+            checksum: '',
+            lastUpdated: 0,
+        };
+    }
+    /** Validates the manifest by checking R2 or local state for parseable data */
+    async validateManifest() {
+        try {
+            const manifestKey = this.getManifestKey();
+            const result = await this.config.bucket.get(manifestKey);
+            if (!result) {
+                return this.manifest.entries.length > 0;
+            }
+            const text = await result.text();
+            JSON.parse(text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Returns a copy of all backup entries in the manifest */
+    async listBackups() {
+        return [...this.manifest.entries];
+    }
+    /** Verifies that a backup exists in R2 by checking its object head */
+    async verifyBackup(backupId) {
+        const entry = this.manifest.entries.find((e) => e.backupId === backupId);
+        if (!entry)
+            return false;
+        try {
+            const result = await this.config.bucket.head(entry.r2Key);
+            return !!result;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ===========================================================================
+    // Scheduling
+    // ===========================================================================
+    /** Returns the timestamp for the next scheduled backup */
+    getNextBackupTime() {
+        const intervalMs = this.config.schedule?.intervalMs ?? DEFAULT_BACKUP_INTERVAL_MS;
+        return Date.now() + intervalMs;
+    }
+    /** Determines whether a full backup is required based on the configured interval */
+    needsFullBackup() {
+        if (this.lastFullBackupTime === 0)
+            return true;
+        if (!this.config.schedule?.fullBackupIntervalMs)
+            return this.lastFullBackupTime === 0;
+        return Date.now() - this.lastFullBackupTime >= this.config.schedule.fullBackupIntervalMs;
+    }
+    /** Returns the type of backup to create on the next scheduled execution */
+    getScheduledBackupType() {
+        if (this.needsFullBackup())
+            return 'full';
+        return this.config.schedule?.type || 'full';
+    }
+    /** Handles a Durable Object alarm, creating the appropriate backup type */
+    async handleAlarm(pglite) {
+        const type = this.getScheduledBackupType();
+        const result = type === 'full'
+            ? await this.createFullBackup(pglite)
+            : await this.createIncrementalBackup(pglite);
+        return {
+            backupCreated: result.success,
+            type: result.type,
+            nextAlarmMs: this.config.schedule?.intervalMs || DEFAULT_BACKUP_INTERVAL_MS,
+        };
+    }
+    /** Returns the current backup schedule configuration, or defaults */
+    getSchedule() {
+        return this.config.schedule || { intervalMs: DEFAULT_BACKUP_INTERVAL_MS, type: 'full' };
+    }
+    // ===========================================================================
+    // Retention / Pruning
+    // ===========================================================================
+    /** Prunes old backups according to the retention policy, preserving minimum full backups */
+    async pruneBackups() {
+        const retention = this.config.retention || {
+            maxBackups: DEFAULT_MAX_BACKUPS,
+            maxAgeDays: DEFAULT_MAX_AGE_DAYS,
+            keepMinFullBackups: DEFAULT_KEEP_MIN_FULL_BACKUPS,
+        };
+        const now = Date.now();
+        const maxAgeMs = retention.maxAgeDays * MS_PER_DAY;
+        const deletedBackupIds = [];
+        // Sort by timestamp descending (newest first)
+        const sorted = [...this.manifest.entries].sort((a, b) => b.timestamp - a.timestamp);
+        // First pass: identify candidates for keeping/pruning based on age and count
+        const toKeep = [];
+        const candidates = [];
+        for (let i = 0; i < sorted.length; i++) {
+            const entry = sorted[i];
+            const isOld = now - entry.timestamp > maxAgeMs;
+            const exceedsMax = i >= retention.maxBackups;
+            if (isOld || exceedsMax) {
+                candidates.push(entry);
+            }
+            else {
+                toKeep.push(entry);
+            }
+        }
+        // Second pass: from candidates, protect enough full backups to meet minimum
+        // Only protect old full backups if there aren't enough fresh ones
+        const fullBackupsInKeep = toKeep.filter((e) => e.type === 'full').length;
+        // Keep min full backups total (from keep + candidates combined)
+        let additionalFullsNeeded = Math.max(0, retention.keepMinFullBackups - fullBackupsInKeep);
+        // But don't protect more than what would bring total to keepMinFullBackups
+        // If we already have enough fresh full backups, don't protect old ones
+        const toPrune = [];
+        // Sort candidates with most recent first
+        candidates.sort((a, b) => b.timestamp - a.timestamp);
+        for (const candidate of candidates) {
+            if (candidate.type === 'full' && additionalFullsNeeded > 0 && fullBackupsInKeep === 0) {
+                // Only protect old full backups if there are NO fresh ones
+                toKeep.push(candidate);
+                additionalFullsNeeded--;
+            }
+            else {
+                toPrune.push(candidate);
+            }
+        }
+        // Delete pruned backups from R2
+        for (const entry of toPrune) {
+            try {
+                await this.config.bucket.delete(entry.r2Key);
+                deletedBackupIds.push(entry.backupId);
+            }
+            catch {
+                // Continue pruning other entries
+            }
+        }
+        // Update manifest
+        this.manifest.entries = toKeep;
+        this.manifest.totalSizeBytes = toKeep.reduce((sum, e) => sum + e.sizeBytes, 0);
+        this.manifest.lastUpdated = Date.now();
+        await this.saveManifest();
+        return {
+            pruned: deletedBackupIds.length,
+            remaining: toKeep.length,
+            deletedBackupIds,
+        };
+    }
+    // ===========================================================================
+    // Statistics
+    // ===========================================================================
+    /** Returns a snapshot of backup statistics */
+    getStats() {
+        return { ...this.stats };
+    }
+    /** Resets all backup statistics to zero */
+    resetStats() {
+        this.stats = this.createEmptyStats();
+    }
+    /** Returns the current incremental backup chain state, or null if no full backup exists */
+    getIncrementalState() {
+        return this.incrementalState ? { ...this.incrementalState } : null;
+    }
+    // ===========================================================================
+    // Private Helpers
+    // ===========================================================================
+    /** Returns the R2 key for the manifest file */
+    getManifestKey() {
+        return `${this.config.prefix}${this.config.doId}/manifest.json`;
+    }
+    /** Persists the current manifest to R2 */
+    async saveManifest() {
+        const manifestData = JSON.stringify(this.manifest);
+        await this.config.bucket.put(this.getManifestKey(), manifestData, {
+            customMetadata: { type: 'manifest', doId: this.config.doId },
+        });
+    }
+    /** Builds the parent chain of backup IDs from the base full backup to the given ID */
+    buildParentChain(baseBackupId) {
+        const chain = [];
+        let currentId = baseBackupId;
+        while (currentId) {
+            chain.unshift(currentId);
+            const entry = this.manifest.entries.find((e) => e.backupId === currentId);
+            if (!entry || entry.type === 'full')
+                break;
+            currentId = entry.baseBackupId;
+        }
+        return chain;
+    }
+    /** Gets the ordered chain of backup entries needed to restore to the given backup ID */
+    getRestoreChain(backupId) {
+        const chain = [];
+        let currentId = backupId;
+        while (currentId) {
+            const entry = this.manifest.entries.find((e) => e.backupId === currentId);
+            if (!entry)
+                break;
+            chain.unshift(entry);
+            if (entry.type === 'full')
+                break;
+            currentId = entry.baseBackupId;
+        }
+        return chain;
+    }
+    /** Updates aggregate statistics after a backup operation completes */
+    updateStats(success, sizeBytes, durationMs, type) {
+        this.stats.totalBackups++;
+        if (success) {
+            this.stats.successCount++;
+            this.stats.totalSizeBytes += sizeBytes;
+            this.stats.lastBackupTimestamp = Date.now();
+        }
+        else {
+            this.stats.failureCount++;
+        }
+        if (type === 'full') {
+            this.stats.fullBackupCount++;
+        }
+        else {
+            this.stats.incrementalBackupCount++;
+        }
+        // Compute running average of duration using incremental formula
+        const previousTotal = this.stats.avgDurationMs * (this.stats.totalBackups - 1);
+        this.stats.avgDurationMs = (previousTotal + durationMs) / this.stats.totalBackups;
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/** Creates a BackupManager instance, validating required configuration */
+export function createBackupManager(config) {
+    if (!config.bucket) {
+        throw new Error('BackupManager requires a valid R2 bucket');
+    }
+    if (!config.doId) {
+        throw new Error('BackupManager requires a non-empty doId');
+    }
+    return new BackupManager(config);
+}
+//# sourceMappingURL=backup-manager.js.map