@dotdo/postgres 0.1.0

package/src/worker/wal-retention.ts

@@ -0,0 +1,1075 @@
+/**
+ * WAL Retention Policy Management
+ * Task: postgres-yzu - Configurable WAL retention policy
+ *
+ * Implements configurable retention policies for WAL data in R2 storage:
+ * - Time-based retention (keep last N days)
+ * - Size-based retention (keep last N MB)
+ * - LSN-based retention (keep from LSN X)
+ * - Automatic cleanup of old WAL segments
+ * - Legal hold support to prevent deletion
+ * - Configuration via DO options or environment variables
+ */
+
+import type { R2WALStorage } from './wal-r2'
+
+/**
+ * Retention policy types
+ */
+export type RetentionPolicyType = 'time' | 'size' | 'lsn' | 'combined'
+
+/**
+ * Time-based retention configuration
+ * Keep WAL data for a specified duration
+ */
+export interface TimeBasedRetention {
+  /** Retention type identifier */
+  type: 'time'
+  /** Minimum retention duration in milliseconds */
+  minRetentionMs?: number | undefined
+  /** Maximum retention duration in milliseconds (hard cap) */
+  maxRetentionMs: number
+}
+
+/**
+ * Size-based retention configuration
+ * Keep WAL data up to a specified size limit
+ */
+export interface SizeBasedRetention {
+  /** Retention type identifier */
+  type: 'size'
+  /** Maximum storage size in bytes */
+  maxSizeBytes: number
+  /** Whether to evict oldest segments first (default: true) */
+  evictOldestFirst?: boolean | undefined
+}
+
+/**
+ * LSN-based retention configuration
+ * Keep WAL data from a specific LSN
+ */
+export interface LSNBasedRetention {
+  /** Retention type identifier */
+  type: 'lsn'
+  /** Minimum LSN to retain (all data from this LSN onward is kept) */
+  minLsn: bigint | string
+}
+
+/**
+ * Combined retention policy
+ * Applies multiple retention rules; data must satisfy ALL rules to be retained
+ */
+export interface CombinedRetention {
+  /** Retention type identifier */
+  type: 'combined'
+  /** Time-based component (optional) */
+  time?: Omit<TimeBasedRetention, 'type'> | undefined
+  /** Size-based component (optional) */
+  size?: Omit<SizeBasedRetention, 'type'> | undefined
+  /** LSN-based component (optional) */
+  lsn?: Omit<LSNBasedRetention, 'type'> | undefined
+}
+
+/**
+ * Union type for all retention policies
+ */
+export type RetentionPolicy =
+  | TimeBasedRetention
+  | SizeBasedRetention
+  | LSNBasedRetention
+  | CombinedRetention
+
+/**
+ * Legal hold configuration
+ * Prevents deletion of WAL data regardless of retention policy
+ */
+export interface LegalHold {
+  /** Whether legal hold is active */
+  enabled: boolean
+  /** Reason for legal hold (for auditing) */
+  reason?: string | undefined
+  /** When the legal hold was applied */
+  appliedAt?: number | undefined
+  /** Who applied the legal hold */
+  appliedBy?: string | undefined
+  /** Optional expiry time for the legal hold */
+  expiresAt?: number | undefined
+}
+
+/**
+ * Full WAL retention configuration
+ */
+export interface WALRetentionConfig {
+  /** The retention policy to apply */
+  policy: RetentionPolicy
+  /** Legal hold settings (overrides retention policy) */
+  legalHold?: LegalHold
+  /** How often to run automatic cleanup (in milliseconds, default: 1 hour) */
+  cleanupIntervalMs?: number
+  /** Whether to enable automatic cleanup (default: true) */
+  autoCleanup?: boolean
+  /** Minimum age before a segment can be deleted (safety buffer, default: 5 minutes) */
+  minAgeBeforeDeleteMs?: number
+  /** Dry run mode - report what would be deleted without actually deleting */
+  dryRun?: boolean
+  /** Callback for retention events */
+  onRetentionEvent?: (event: RetentionEvent) => void
+}
+
+/**
+ * Retention event types for monitoring
+ */
+export type RetentionEventType =
+  | 'cleanup_started'
+  | 'cleanup_completed'
+  | 'segment_deleted'
+  | 'segment_retained'
+  | 'legal_hold_prevented_deletion'
+  | 'cleanup_error'
+  | 'policy_changed'
+
+/**
+ * Retention event for monitoring
+ */
+export interface RetentionEvent {
+  /** Event type */
+  type: RetentionEventType
+  /** Timestamp of the event */
+  timestamp: number
+  /** Additional details */
+  details?: Record<string, unknown> | undefined
+}
+
+/**
+ * Segment metadata for retention evaluation
+ */
+export interface SegmentInfo {
+  /** R2 object key */
+  key: string
+  /** Segment creation timestamp */
+  createdAt: number
+  /** Compressed size in bytes */
+  sizeBytes: number
+  /** Start LSN of the segment */
+  startLsn: bigint
+  /** End LSN of the segment */
+  endLsn: bigint
+  /** Number of entries in the segment */
+  entryCount: number
+}
+
+/**
+ * Result of a cleanup operation
+ */
+export interface CleanupResult {
+  /** Whether the cleanup was successful */
+  success: boolean
+  /** Number of segments deleted */
+  segmentsDeleted: number
+  /** Total bytes freed */
+  bytesFreed: number
+  /** Number of segments retained */
+  segmentsRetained: number
+  /** Total bytes retained */
+  bytesRetained: number
+  /** LSN range of deleted segments */
+  deletedLsnRange?: { start: bigint; end: bigint } | undefined
+  /** Duration of cleanup operation in milliseconds */
+  durationMs: number
+  /** Reason if cleanup was skipped or failed */
+  reason?: string | undefined
+  /** Error message if cleanup failed */
+  error?: string | undefined
+}
+
+/**
+ * Retention statistics
+ */
+export interface RetentionStats {
+  /** Total cleanup operations performed */
+  totalCleanups: number
+  /** Successful cleanup operations */
+  successfulCleanups: number
+  /** Failed cleanup operations */
+  failedCleanups: number
+  /** Total segments deleted */
+  totalSegmentsDeleted: number
+  /** Total bytes freed */
+  totalBytesFreed: number
+  /** Last cleanup timestamp */
+  lastCleanupAt: number | null
+  /** Last cleanup result */
+  lastCleanupResult: CleanupResult | null
+  /** Current storage usage in bytes */
+  currentStorageBytes: number
+  /** Current segment count */
+  currentSegmentCount: number
+  /** Oldest segment timestamp */
+  oldestSegmentAt: number | null
+  /** Newest segment timestamp */
+  newestSegmentAt: number | null
+  /** Legal hold active status */
+  legalHoldActive: boolean
+}
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+  cleanupIntervalMs: 60 * 60 * 1000, // 1 hour
+  autoCleanup: true,
+  minAgeBeforeDeleteMs: 5 * 60 * 1000, // 5 minutes
+  dryRun: false,
+}
+
+/**
+ * Helper to convert duration string to milliseconds
+ * Supports: 30d (days), 12h (hours), 30m (minutes), 60s (seconds)
+ */
+export function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+(?:\.\d+)?)\s*(d|h|m|s|ms)$/i)
+  if (!match) {
+    throw new Error(`Invalid duration format: ${duration}. Use format like "30d", "12h", "30m", "60s", or "1000ms"`)
+  }
+
+  const value = parseFloat(match[1]!)
+  const unit = match[2]!.toLowerCase()
+
+  switch (unit) {
+    case 'd':
+      return value * 24 * 60 * 60 * 1000
+    case 'h':
+      return value * 60 * 60 * 1000
+    case 'm':
+      return value * 60 * 1000
+    case 's':
+      return value * 1000
+    case 'ms':
+      return value
+    default:
+      throw new Error(`Unknown duration unit: ${unit}`)
+  }
+}
+
+/**
+ * Helper to convert size string to bytes
+ * Supports: 100B (bytes), 10KB, 10MB, 10GB, 10TB
+ */
+export function parseSize(size: string): number {
+  const match = size.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|TB)$/i)
+  if (!match) {
+    throw new Error(`Invalid size format: ${size}. Use format like "100B", "10KB", "10MB", "10GB", or "10TB"`)
+  }
+
+  const value = parseFloat(match[1]!)
+  const unit = match[2]!.toUpperCase()
+
+  switch (unit) {
+    case 'B':
+      return value
+    case 'KB':
+      return value * 1024
+    case 'MB':
+      return value * 1024 * 1024
+    case 'GB':
+      return value * 1024 * 1024 * 1024
+    case 'TB':
+      return value * 1024 * 1024 * 1024 * 1024
+    default:
+      throw new Error(`Unknown size unit: ${unit}`)
+  }
+}
+
+/**
+ * Create a time-based retention policy
+ *
+ * @example
+ * ```typescript
+ * // Keep WAL for 30 days
+ * const policy = createTimeRetention('30d')
+ *
+ * // Keep WAL for minimum 7 days, maximum 90 days
+ * const policy = createTimeRetention('90d', '7d')
+ * ```
+ */
+export function createTimeRetention(maxRetention: string, minRetention?: string): TimeBasedRetention {
+  return {
+    type: 'time',
+    maxRetentionMs: parseDuration(maxRetention),
+    minRetentionMs: minRetention ? parseDuration(minRetention) : undefined,
+  }
+}
+
+/**
+ * Create a size-based retention policy
+ *
+ * @example
+ * ```typescript
+ * // Keep up to 1GB of WAL data
+ * const policy = createSizeRetention('1GB')
+ *
+ * // Keep up to 500MB, evicting newest first (unusual)
+ * const policy = createSizeRetention('500MB', false)
+ * ```
+ */
+export function createSizeRetention(maxSize: string, evictOldestFirst = true): SizeBasedRetention {
+  return {
+    type: 'size',
+    maxSizeBytes: parseSize(maxSize),
+    evictOldestFirst,
+  }
+}
+
+/**
+ * Create an LSN-based retention policy
+ *
+ * @example
+ * ```typescript
+ * // Keep all WAL from LSN 1000 onward
+ * const policy = createLsnRetention(1000n)
+ * const policy = createLsnRetention('1000')
+ * ```
+ */
+export function createLsnRetention(minLsn: bigint | string): LSNBasedRetention {
+  return {
+    type: 'lsn',
+    minLsn,
+  }
+}
+
+/**
+ * Create a combined retention policy
+ *
+ * @example
+ * ```typescript
+ * // Keep WAL for 30 days OR up to 1GB, whichever is more restrictive
+ * const policy = createCombinedRetention({
+ *   time: { maxRetentionMs: 30 * 24 * 60 * 60 * 1000 },
+ *   size: { maxSizeBytes: 1024 * 1024 * 1024 },
+ * })
+ * ```
+ */
+export function createCombinedRetention(options: {
+  time?: Omit<TimeBasedRetention, 'type'>
+  size?: Omit<SizeBasedRetention, 'type'>
+  lsn?: Omit<LSNBasedRetention, 'type'>
+}): CombinedRetention {
+  return {
+    type: 'combined',
+    ...options,
+  }
+}
+
+/**
+ * WAL Retention Manager
+ *
+ * Manages WAL retention policies and automatic cleanup for R2 storage.
+ * Supports multiple retention strategies and legal hold.
+ *
+ * @example
+ * ```typescript
+ * const retention = new WALRetentionManager(storage, {
+ *   policy: createTimeRetention('30d'),
+ *   autoCleanup: true,
+ *   cleanupIntervalMs: 60 * 60 * 1000, // 1 hour
+ * })
+ *
+ * // Start automatic cleanup
+ * retention.startAutoCleanup()
+ *
+ * // Manual cleanup
+ * const result = await retention.cleanup()
+ * console.log(`Deleted ${result.segmentsDeleted} segments, freed ${result.bytesFreed} bytes`)
+ *
+ * // Apply legal hold
+ * retention.setLegalHold({ enabled: true, reason: 'Investigation' })
+ * ```
+ */
+export class WALRetentionManager {
+  private storage: R2WALStorage
+  private config: Required<Omit<WALRetentionConfig, 'onRetentionEvent' | 'legalHold'>> & {
+    onRetentionEvent?: (event: RetentionEvent) => void
+    legalHold?: LegalHold
+  }
+  private stats: RetentionStats = {
+    totalCleanups: 0,
+    successfulCleanups: 0,
+    failedCleanups: 0,
+    totalSegmentsDeleted: 0,
+    totalBytesFreed: 0,
+    lastCleanupAt: null,
+    lastCleanupResult: null,
+    currentStorageBytes: 0,
+    currentSegmentCount: 0,
+    oldestSegmentAt: null,
+    newestSegmentAt: null,
+    legalHoldActive: false,
+  }
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null
+  private cleanupInProgress = false
+
+  constructor(storage: R2WALStorage, config: WALRetentionConfig) {
+    this.storage = storage
+    // Build config without undefined values for exactOptionalPropertyTypes
+    // Explicitly construct the full config object type
+    type FullConfig = Required<Omit<WALRetentionConfig, 'onRetentionEvent' | 'legalHold'>> & {
+      onRetentionEvent?: (event: RetentionEvent) => void
+      legalHold?: LegalHold
+    }
+    const fullConfig: FullConfig = {
+      policy: config.policy,
+      cleanupIntervalMs: config.cleanupIntervalMs ?? DEFAULT_CONFIG.cleanupIntervalMs,
+      autoCleanup: config.autoCleanup ?? DEFAULT_CONFIG.autoCleanup,
+      minAgeBeforeDeleteMs: config.minAgeBeforeDeleteMs ?? DEFAULT_CONFIG.minAgeBeforeDeleteMs,
+      dryRun: config.dryRun ?? DEFAULT_CONFIG.dryRun,
+    }
+    if (config.onRetentionEvent !== undefined) {
+      fullConfig.onRetentionEvent = config.onRetentionEvent
+    }
+    if (config.legalHold !== undefined) {
+      fullConfig.legalHold = config.legalHold
+    }
+    this.config = fullConfig
+
+    if (config.legalHold?.enabled) {
+      this.stats.legalHoldActive = true
+    }
+  }
+
+  /**
+   * Get current retention configuration
+   */
+  getConfig(): WALRetentionConfig {
+    return { ...this.config }
+  }
+
+  /**
+   * Update retention configuration
+   */
+  setConfig(config: Partial<WALRetentionConfig>): void {
+    const oldPolicy = this.config.policy
+
+    if (config.policy !== undefined) {
+      this.config.policy = config.policy
+    }
+    if (config.cleanupIntervalMs !== undefined) {
+      this.config.cleanupIntervalMs = config.cleanupIntervalMs
+    }
+    if (config.autoCleanup !== undefined) {
+      this.config.autoCleanup = config.autoCleanup
+    }
+    if (config.minAgeBeforeDeleteMs !== undefined) {
+      this.config.minAgeBeforeDeleteMs = config.minAgeBeforeDeleteMs
+    }
+    if (config.dryRun !== undefined) {
+      this.config.dryRun = config.dryRun
+    }
+    if (config.onRetentionEvent !== undefined) {
+      this.config.onRetentionEvent = config.onRetentionEvent
+    }
+    if (config.legalHold !== undefined) {
+      this.config.legalHold = config.legalHold
+      this.stats.legalHoldActive = config.legalHold?.enabled ?? false
+    }
+
+    // Emit policy changed event
+    if (config.policy && config.policy !== oldPolicy) {
+      this.emitEvent({
+        type: 'policy_changed',
+        timestamp: Date.now(),
+        details: {
+          oldPolicy: oldPolicy.type,
+          newPolicy: config.policy.type,
+        },
+      })
+    }
+
+    // Restart auto cleanup if interval changed
+    if (config.cleanupIntervalMs !== undefined && this.cleanupInterval) {
+      this.stopAutoCleanup()
+      if (this.config.autoCleanup) {
+        this.startAutoCleanup()
+      }
+    }
+  }
+
+  /**
+   * Set legal hold status
+   */
+  setLegalHold(hold: LegalHold): void {
+    this.config.legalHold = {
+      ...hold,
+      appliedAt: hold.appliedAt ?? Date.now(),
+    }
+    this.stats.legalHoldActive = hold.enabled
+  }
+
+  /**
+   * Get current legal hold status
+   */
+  getLegalHold(): LegalHold | undefined {
+    return this.config.legalHold
+  }
+
+  /**
+   * Check if legal hold is active
+   */
+  isLegalHoldActive(): boolean {
+    const hold = this.config.legalHold
+    if (!hold || !hold.enabled) {
+      return false
+    }
+
+    // Check if legal hold has expired
+    if (hold.expiresAt && Date.now() > hold.expiresAt) {
+      return false
+    }
+
+    return true
+  }
+
+  /**
+   * Get retention statistics
+   */
+  getStats(): RetentionStats {
+    return { ...this.stats }
+  }
+
+  /**
+   * Start automatic cleanup based on configured interval
+   */
+  startAutoCleanup(): void {
+    if (this.cleanupInterval) {
+      return // Already running
+    }
+
+    // Run initial cleanup
+    void this.cleanup().catch((error) => {
+      console.error('[WALRetentionManager] Initial cleanup error:', error)
+    })
+
+    // Schedule periodic cleanup
+    this.cleanupInterval = setInterval(async () => {
+      try {
+        await this.cleanup()
+      } catch (error) {
+        console.error('[WALRetentionManager] Periodic cleanup error:', error)
+      }
+    }, this.config.cleanupIntervalMs)
+  }
+
+  /**
+   * Stop automatic cleanup
+   */
+  stopAutoCleanup(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval)
+      this.cleanupInterval = null
+    }
+  }
+
+  /**
+   * Check if auto cleanup is running
+   */
+  isAutoCleanupRunning(): boolean {
+    return this.cleanupInterval !== null
+  }
+
+  /**
+   * Emit a retention event
+   */
+  private emitEvent(event: RetentionEvent): void {
+    if (this.config.onRetentionEvent) {
+      try {
+        this.config.onRetentionEvent(event)
+      } catch (error) {
+        console.error('[WALRetentionManager] Event listener error:', error)
+      }
+    }
+  }
+
+  /**
+   * Get all segment information from storage
+   */
+  private async getSegmentInfos(): Promise<SegmentInfo[]> {
+    const segments: SegmentInfo[] = []
+    let cursor: string | undefined
+
+    do {
+      // Build options without undefined values for exactOptionalPropertyTypes
+      const listOptions: { cursor?: string } = {}
+      if (cursor !== undefined) {
+        listOptions.cursor = cursor
+      }
+      const result = await this.storage.listSegmentsWithInfo(listOptions)
+
+      for (const seg of result.segments) {
+        segments.push({
+          key: seg.key,
+          createdAt: seg.createdAt,
+          sizeBytes: seg.size,
+          startLsn: seg.startLsn,
+          endLsn: seg.endLsn,
+          entryCount: seg.entryCount,
+        })
+      }
+
+      cursor = result.cursor
+    } while (cursor)
+
+    // Sort by creation time (oldest first)
+    return segments.sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  /**
+   * Evaluate whether a segment should be retained based on the retention policy
+   */
+  private shouldRetain(
+    segment: SegmentInfo,
+    now: number,
+    policy: RetentionPolicy,
+    cumulativeSize: number
+  ): boolean {
+    const age = now - segment.createdAt
+
+    // Never delete segments younger than minAgeBeforeDeleteMs
+    if (age < this.config.minAgeBeforeDeleteMs) {
+      return true
+    }
+
+    switch (policy.type) {
+      case 'time': {
+        // Must be within maxRetentionMs
+        if (age > policy.maxRetentionMs) {
+          return false
+        }
+        // If minRetentionMs is set, must retain at least that long
+        if (policy.minRetentionMs && age < policy.minRetentionMs) {
+          return true
+        }
+        return true
+      }
+
+      case 'size': {
+        // If evicting oldest first, check cumulative size
+        if (policy.evictOldestFirst !== false) {
+          return cumulativeSize + segment.sizeBytes <= policy.maxSizeBytes
+        } else {
+          // Evicting newest first is unusual but supported
+          return true // Will be handled in reverse order
+        }
+      }
+
+      case 'lsn': {
+        const minLsn = typeof policy.minLsn === 'string' ? BigInt(policy.minLsn) : policy.minLsn
+        return segment.endLsn >= minLsn
+      }
+
+      case 'combined': {
+        // All applicable conditions must be satisfied
+        let retain = true
+
+        if (policy.time) {
+          const timePolicy: TimeBasedRetention = { type: 'time', ...policy.time }
+          retain = retain && this.shouldRetain(segment, now, timePolicy, cumulativeSize)
+        }
+
+        if (policy.size && retain) {
+          const sizePolicy: SizeBasedRetention = { type: 'size', ...policy.size }
+          retain = retain && this.shouldRetain(segment, now, sizePolicy, cumulativeSize)
+        }
+
+        if (policy.lsn && retain) {
+          const lsnPolicy: LSNBasedRetention = { type: 'lsn', ...policy.lsn }
+          retain = retain && this.shouldRetain(segment, now, lsnPolicy, cumulativeSize)
+        }
+
+        return retain
+      }
+
+      default:
+        return true
+    }
+  }
+
+  /**
+   * Run cleanup based on retention policy
+   */
+  async cleanup(): Promise<CleanupResult> {
+    // Prevent concurrent cleanup operations
+    if (this.cleanupInProgress) {
+      return {
+        success: false,
+        segmentsDeleted: 0,
+        bytesFreed: 0,
+        segmentsRetained: 0,
+        bytesRetained: 0,
+        durationMs: 0,
+        reason: 'Cleanup already in progress',
+      }
+    }
+
+    this.cleanupInProgress = true
+    const startTime = performance.now()
+
+    this.emitEvent({
+      type: 'cleanup_started',
+      timestamp: Date.now(),
+      details: {
+        policy: this.config.policy.type,
+        dryRun: this.config.dryRun,
+      },
+    })
+
+    try {
+      // Check for legal hold
+      if (this.isLegalHoldActive()) {
+        this.emitEvent({
+          type: 'legal_hold_prevented_deletion',
+          timestamp: Date.now(),
+          details: {
+            reason: this.config.legalHold?.reason,
+          },
+        })
+
+        return {
+          success: true,
+          segmentsDeleted: 0,
+          bytesFreed: 0,
+          segmentsRetained: 0,
+          bytesRetained: 0,
+          durationMs: performance.now() - startTime,
+          reason: 'Legal hold active',
+        }
+      }
+
+      // Get all segments
+      const segments = await this.getSegmentInfos()
+
+      if (segments.length === 0) {
+        return {
+          success: true,
+          segmentsDeleted: 0,
+          bytesFreed: 0,
+          segmentsRetained: 0,
+          bytesRetained: 0,
+          durationMs: performance.now() - startTime,
+        }
+      }
+
+      const now = Date.now()
+      const toDelete: SegmentInfo[] = []
+      const toRetain: SegmentInfo[] = []
+      let cumulativeSize = 0
+
+      // For size-based retention with oldest-first eviction, we need to process in reverse
+      // to calculate cumulative size from newest to oldest
+      if (
+        this.config.policy.type === 'size' ||
+        (this.config.policy.type === 'combined' && this.config.policy.size)
+      ) {
+        // Calculate total size first
+        const storageStats = this.storage.getStats()
+        const totalSize = storageStats.bytesWritten
+
+        // Process from newest to oldest
+        const segmentsReversed = [...segments].reverse()
+        let retainedSize = 0
+
+        for (const segment of segmentsReversed) {
+          // Estimate segment size from storage stats
+          segment.sizeBytes = Math.floor(totalSize / segments.length) // Rough estimate
+
+          if (this.shouldRetain(segment, now, this.config.policy, retainedSize)) {
+            toRetain.unshift(segment) // Add to front to maintain order
+            retainedSize += segment.sizeBytes
+          } else {
+            toDelete.unshift(segment)
+          }
+        }
+      } else {
+        // Process in chronological order for time and LSN-based retention
+        for (const segment of segments) {
+          if (this.shouldRetain(segment, now, this.config.policy, cumulativeSize)) {
+            toRetain.push(segment)
+            cumulativeSize += segment.sizeBytes
+          } else {
+            toDelete.push(segment)
+          }
+        }
+      }
+
+      // Calculate statistics
+      let bytesFreed = 0
+      let bytesRetained = 0
+
+      for (const segment of toDelete) {
+        bytesFreed += segment.sizeBytes
+      }
+
+      for (const segment of toRetain) {
+        bytesRetained += segment.sizeBytes
+      }
+
+      // Delete segments (unless dry run)
+      if (!this.config.dryRun && toDelete.length > 0) {
+        const keysToDelete = toDelete.map((s) => s.key)
+        await this.storage.deleteSegments(keysToDelete)
+
+        // Emit events for each deleted segment
+        for (const key of keysToDelete) {
+          this.emitEvent({
+            type: 'segment_deleted',
+            timestamp: Date.now(),
+            details: { key },
+          })
+        }
+      }
+
+      // Build result
+      const deletedLsnRange =
+        toDelete.length > 0
+          ? {
+              start: toDelete[0]!.startLsn,
+              end: toDelete[toDelete.length - 1]!.endLsn,
+            }
+          : undefined
+
+      const result: CleanupResult = {
+        success: true,
+        segmentsDeleted: toDelete.length,
+        bytesFreed,
+        segmentsRetained: toRetain.length,
+        bytesRetained,
+        deletedLsnRange,
+        durationMs: performance.now() - startTime,
+      }
+
+      // Update statistics
+      this.stats.totalCleanups++
+      this.stats.successfulCleanups++
+      this.stats.totalSegmentsDeleted += toDelete.length
+      this.stats.totalBytesFreed += bytesFreed
+      this.stats.lastCleanupAt = Date.now()
+      this.stats.lastCleanupResult = result
+      this.stats.currentStorageBytes = bytesRetained
+      this.stats.currentSegmentCount = toRetain.length
+
+      if (toRetain.length > 0) {
+        this.stats.oldestSegmentAt = toRetain[0]!.createdAt
+        this.stats.newestSegmentAt = toRetain[toRetain.length - 1]!.createdAt
+      } else {
+        this.stats.oldestSegmentAt = null
+        this.stats.newestSegmentAt = null
+      }
+
+      this.emitEvent({
+        type: 'cleanup_completed',
+        timestamp: Date.now(),
+        details: {
+          segmentsDeleted: toDelete.length,
+          bytesFreed,
+          segmentsRetained: toRetain.length,
+          durationMs: result.durationMs,
+          dryRun: this.config.dryRun,
+        },
+      })
+
+      return result
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+
+      this.stats.totalCleanups++
+      this.stats.failedCleanups++
+
+      this.emitEvent({
+        type: 'cleanup_error',
+        timestamp: Date.now(),
+        details: { error: errorMessage },
+      })
+
+      return {
+        success: false,
+        segmentsDeleted: 0,
+        bytesFreed: 0,
+        segmentsRetained: 0,
+        bytesRetained: 0,
+        durationMs: performance.now() - startTime,
+        error: errorMessage,
+      }
+    } finally {
+      this.cleanupInProgress = false
+    }
+  }
+
+  /**
+   * Get the estimated time until next cleanup
+   */
+  getNextCleanupIn(): number | null {
+    if (!this.cleanupInterval || !this.stats.lastCleanupAt) {
+      return null
+    }
+
+    const elapsed = Date.now() - this.stats.lastCleanupAt
+    return Math.max(0, this.config.cleanupIntervalMs - elapsed)
+  }
+
+  /**
+   * Force an immediate cleanup (ignores interval)
+   */
+  async forceCleanup(): Promise<CleanupResult> {
+    return this.cleanup()
+  }
+
+  /**
+   * Preview what would be cleaned up without actually deleting
+   */
+  async previewCleanup(): Promise<{
+    segmentsToDelete: SegmentInfo[]
+    segmentsToRetain: SegmentInfo[]
+    bytesToFree: number
+    bytesToRetain: number
+  }> {
+    const segments = await this.getSegmentInfos()
+    const now = Date.now()
+    const toDelete: SegmentInfo[] = []
+    const toRetain: SegmentInfo[] = []
+    let cumulativeSize = 0
+
+    for (const segment of segments) {
+      if (this.shouldRetain(segment, now, this.config.policy, cumulativeSize)) {
+        toRetain.push(segment)
+        cumulativeSize += segment.sizeBytes
+      } else {
+        toDelete.push(segment)
+      }
+    }
+
+    let bytesToFree = 0
+    let bytesToRetain = 0
+
+    for (const segment of toDelete) {
+      bytesToFree += segment.sizeBytes
+    }
+
+    for (const segment of toRetain) {
+      bytesToRetain += segment.sizeBytes
+    }
+
+    return {
+      segmentsToDelete: toDelete,
+      segmentsToRetain: toRetain,
+      bytesToFree,
+      bytesToRetain,
+    }
+  }
+}
+
+/**
+ * Create a WAL retention manager with default time-based retention
+ *
+ * @example
+ * ```typescript
+ * const retention = createWALRetentionManager(storage, '30d')
+ * retention.startAutoCleanup()
+ * ```
+ */
+export function createWALRetentionManager(
+  storage: R2WALStorage,
+  retention: string | WALRetentionConfig
+): WALRetentionManager {
+  const config: WALRetentionConfig =
+    typeof retention === 'string'
+      ? { policy: createTimeRetention(retention) }
+      : retention
+
+  return new WALRetentionManager(storage, config)
+}
+
+/**
+ * Parse retention configuration from environment variables
+ *
+ * Supported environment variables:
+ * - WAL_RETENTION_TYPE: 'time' | 'size' | 'lsn' | 'combined'
+ * - WAL_RETENTION_MAX_TIME: Duration string (e.g., '30d', '12h')
+ * - WAL_RETENTION_MIN_TIME: Duration string (e.g., '7d')
+ * - WAL_RETENTION_MAX_SIZE: Size string (e.g., '1GB', '500MB')
+ * - WAL_RETENTION_MIN_LSN: LSN value
+ * - WAL_RETENTION_AUTO_CLEANUP: 'true' | 'false'
+ * - WAL_RETENTION_CLEANUP_INTERVAL: Duration string (e.g., '1h')
+ * - WAL_RETENTION_DRY_RUN: 'true' | 'false'
+ *
+ * @example
+ * ```typescript
+ * // In your Worker
+ * const config = parseRetentionConfigFromEnv(env)
+ * const retention = new WALRetentionManager(storage, config)
+ * ```
+ */
+export function parseRetentionConfigFromEnv(env: Record<string, string | undefined>): WALRetentionConfig {
+  const type = (env.WAL_RETENTION_TYPE as RetentionPolicyType) || 'time'
+
+  let policy: RetentionPolicy
+
+  switch (type) {
+    case 'time':
+      policy = {
+        type: 'time',
+        maxRetentionMs: env.WAL_RETENTION_MAX_TIME
+          ? parseDuration(env.WAL_RETENTION_MAX_TIME)
+          : 30 * 24 * 60 * 60 * 1000, // Default: 30 days
+        minRetentionMs: env.WAL_RETENTION_MIN_TIME
+          ? parseDuration(env.WAL_RETENTION_MIN_TIME)
+          : undefined,
+      }
+      break
+
+    case 'size':
+      policy = {
+        type: 'size',
+        maxSizeBytes: env.WAL_RETENTION_MAX_SIZE
+          ? parseSize(env.WAL_RETENTION_MAX_SIZE)
+          : 1024 * 1024 * 1024, // Default: 1GB
+      }
+      break
+
+    case 'lsn':
+      policy = {
+        type: 'lsn',
+        minLsn: env.WAL_RETENTION_MIN_LSN || '0',
+      }
+      break
+
+    case 'combined':
+      policy = {
+        type: 'combined',
+        time: env.WAL_RETENTION_MAX_TIME
+          ? {
+              maxRetentionMs: parseDuration(env.WAL_RETENTION_MAX_TIME),
+              minRetentionMs: env.WAL_RETENTION_MIN_TIME
+                ? parseDuration(env.WAL_RETENTION_MIN_TIME)
+                : undefined,
+            }
+          : undefined,
+        size: env.WAL_RETENTION_MAX_SIZE
+          ? { maxSizeBytes: parseSize(env.WAL_RETENTION_MAX_SIZE) }
+          : undefined,
+        lsn: env.WAL_RETENTION_MIN_LSN
+          ? { minLsn: env.WAL_RETENTION_MIN_LSN }
+          : undefined,
+      }
+      break
+
+    default:
+      policy = { type: 'time', maxRetentionMs: 30 * 24 * 60 * 60 * 1000 }
+  }
+
+  return {
+    policy,
+    autoCleanup: env.WAL_RETENTION_AUTO_CLEANUP !== 'false',
+    cleanupIntervalMs: env.WAL_RETENTION_CLEANUP_INTERVAL
+      ? parseDuration(env.WAL_RETENTION_CLEANUP_INTERVAL)
+      : DEFAULT_CONFIG.cleanupIntervalMs,
+    dryRun: env.WAL_RETENTION_DRY_RUN === 'true',
+  }
+}