@dotdo/postgres 0.1.0

package/src/pglite/auto-demotion.ts

@@ -0,0 +1,385 @@
+/**
+ * Auto-demotion logic (TTL-based)
+ * Task: postgres-xm8.11 - Auto-demotion logic (TTL-based)
+ *
+ * Automatically demotes infrequently accessed pages to colder tiers
+ * based on TTL (time-to-live) and LRU (least recently used) policies.
+ */
+
+import type { CacheLayer } from './cache-layer'
+import type { R2StorageLayer } from './r2-layer'
+import type { StorageTier } from '../storage/tiered-vfs'
+
+/**
+ * Page tracking information
+ */
+interface PageTrackingInfo {
+  /** Current tier of the page */
+  tier: StorageTier
+  /** Timestamp of last access */
+  lastAccess: number
+}
+
+/**
+ * Reason for demotion
+ */
+export type DemotionReason = 'ttl_expired' | 'lru_eviction' | 'manual'
+
+/**
+ * Candidate for demotion
+ */
+export interface DemotionCandidate {
+  /** The page key */
+  key: string
+  /** Current tier */
+  tier: StorageTier
+  /** Timestamp of last access */
+  lastAccess: number
+  /** Age in milliseconds since last access */
+  age: number
+}
+
+/**
+ * Event emitted when a demotion occurs
+ */
+export interface DemotionEvent {
+  /** The page key */
+  key: string
+  /** Source tier */
+  fromTier: StorageTier
+  /** Target tier */
+  toTier: StorageTier
+  /** Whether demotion succeeded */
+  success: boolean
+  /** Timestamp of the demotion */
+  timestamp: number
+  /** Reason for demotion */
+  reason: DemotionReason
+  /** Error message if demotion failed */
+  error?: string
+}
+
+/**
+ * Callback for demotion events
+ */
+export type DemotionCallback = (event: DemotionEvent) => void
+
+/**
+ * Configuration for AutoDemoter
+ */
+export interface AutoDemoterConfig {
+  /** Cache layer for hot tier */
+  cacheLayer: CacheLayer
+  /** Durable Object storage for warm tier */
+  doStorage: DurableObjectStorage
+  /** R2 layer for cold tier */
+  r2Layer: R2StorageLayer
+  /** TTL for hot tier pages in milliseconds */
+  hotTTLMs: number
+  /** TTL for warm tier pages in milliseconds */
+  warmTTLMs: number
+  /** Optional maximum number of pages in hot tier */
+  maxHotPages?: number
+  /** Optional callback for demotion events */
+  onDemotion?: DemotionCallback
+}
+
+/**
+ * AutoDemoter tracks page access and demotes pages to colder tiers
+ * when they exceed TTL or for LRU eviction.
+ */
+export class AutoDemoter {
+  private cacheLayer: CacheLayer
+  private doStorage: DurableObjectStorage
+  private r2Layer: R2StorageLayer
+  private hotTTLMs: number
+  private warmTTLMs: number
+  private maxHotPages?: number
+  private onDemotion?: DemotionCallback
+  private trackingMap: Map<string, PageTrackingInfo>
+
+  constructor(config: AutoDemoterConfig) {
+    this.cacheLayer = config.cacheLayer
+    this.doStorage = config.doStorage
+    this.r2Layer = config.r2Layer
+    this.hotTTLMs = config.hotTTLMs
+    this.warmTTLMs = config.warmTTLMs
+    this.maxHotPages = config.maxHotPages
+    this.onDemotion = config.onDemotion
+    this.trackingMap = new Map()
+  }
+
+  /**
+   * Track a page with its current tier
+   *
+   * @param key - The page key
+   * @param tier - The current tier of the page
+   */
+  trackPage(key: string, tier: StorageTier): void {
+    this.trackingMap.set(key, {
+      tier,
+      lastAccess: Date.now(),
+    })
+  }
+
+  /**
+   * Get tracking info for a page
+   *
+   * @param key - The page key
+   * @returns Page tracking info or null if not tracked
+   */
+  getPageInfo(key: string): PageTrackingInfo | null {
+    return this.trackingMap.get(key) ?? null
+  }
+
+  /**
+   * Get the TTL for a specific tier
+   *
+   * @param tier - The storage tier
+   * @returns TTL in milliseconds
+   */
+  private getTTLForTier(tier: StorageTier): number {
+    switch (tier) {
+      case 'hot':
+        return this.hotTTLMs
+      case 'warm':
+        return this.warmTTLMs
+      case 'cold':
+        return Infinity // Cold tier pages don't expire
+    }
+  }
+
+  /**
+   * Get the target demotion tier for a given tier
+   *
+   * @param tier - The current tier
+   * @returns The target tier for demotion
+   */
+  private getDemotionTarget(tier: StorageTier): StorageTier {
+    switch (tier) {
+      case 'hot':
+        return 'warm'
+      case 'warm':
+        return 'cold'
+      case 'cold':
+        return 'cold' // Already at coldest tier
+    }
+  }
+
+  /**
+   * Check if a page has expired based on its TTL
+   *
+   * @param key - The page key
+   * @returns true if the page has expired
+   */
+  isExpired(key: string): boolean {
+    const info = this.trackingMap.get(key)
+    if (!info) {
+      return false
+    }
+
+    const ttl = this.getTTLForTier(info.tier)
+    const age = Date.now() - info.lastAccess
+    return age >= ttl
+  }
+
+  /**
+   * Find pages that are candidates for demotion
+   *
+   * @param tier - The tier to find candidates in
+   * @param limit - Optional limit on number of candidates
+   * @returns Array of demotion candidates, sorted by age (oldest first)
+   */
+  findDemotionCandidates(tier: StorageTier, limit?: number): DemotionCandidate[] {
+    const now = Date.now()
+    const ttl = this.getTTLForTier(tier)
+    const candidates: DemotionCandidate[] = []
+
+    for (const [key, info] of this.trackingMap.entries()) {
+      if (info.tier !== tier) {
+        continue
+      }
+
+      const age = now - info.lastAccess
+      if (age >= ttl) {
+        candidates.push({
+          key,
+          tier: info.tier,
+          lastAccess: info.lastAccess,
+          age,
+        })
+      }
+    }
+
+    // Sort by age (oldest first)
+    candidates.sort((a, b) => a.lastAccess - b.lastAccess)
+
+    // Apply limit if specified
+    if (limit !== undefined && candidates.length > limit) {
+      return candidates.slice(0, limit)
+    }
+
+    return candidates
+  }
+
+  /**
+   * Demote a page to a colder tier
+   *
+   * @param key - The page key
+   * @param fromTier - Source tier
+   * @param toTier - Target tier
+   * @param reason - Reason for demotion
+   * @returns Demotion event with result
+   */
+  async demote(
+    key: string,
+    fromTier: StorageTier,
+    toTier: StorageTier,
+    reason: DemotionReason = 'ttl_expired'
+  ): Promise<DemotionEvent> {
+    const timestamp = Date.now()
+
+    try {
+      if (fromTier === 'hot' && toTier === 'warm') {
+        // Hot -> Warm: Just delete from cache (data is already in DO)
+        await this.cacheLayer.delete(key)
+      } else if (fromTier === 'warm' && toTier === 'cold') {
+        // Warm -> Cold: Copy to R2, then delete from DO
+        const data = (await this.doStorage.get(key)) as Uint8Array | undefined
+        if (data) {
+          await this.r2Layer.put(key, data, {
+            customMetadata: {
+              demotedAt: timestamp.toString(),
+              demotionReason: reason,
+            },
+          })
+          await this.doStorage.delete(key)
+        }
+      }
+
+      // Remove from tracking
+      this.trackingMap.delete(key)
+
+      const event: DemotionEvent = {
+        key,
+        fromTier,
+        toTier,
+        success: true,
+        timestamp,
+        reason,
+      }
+      this.onDemotion?.(event)
+      return event
+    } catch (error) {
+      const event: DemotionEvent = {
+        key,
+        fromTier,
+        toTier,
+        success: false,
+        timestamp,
+        reason,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      }
+      this.onDemotion?.(event)
+      return event
+    }
+  }
+
+  /**
+   * Run a demotion cycle for a specific tier
+   *
+   * @param tier - The tier to check for demotions
+   * @param batchSize - Maximum number of pages to demote
+   * @returns Array of demotion events
+   */
+  async runDemotionCycle(tier: StorageTier, batchSize?: number): Promise<DemotionEvent[]> {
+    const candidates = this.findDemotionCandidates(tier, batchSize)
+    const targetTier = this.getDemotionTarget(tier)
+    const events: DemotionEvent[] = []
+
+    for (const candidate of candidates) {
+      const event = await this.demote(candidate.key, tier, targetTier, 'ttl_expired')
+      events.push(event)
+    }
+
+    return events
+  }
+
+  /**
+   * Evict the least recently used pages from hot tier
+   *
+   * @param count - Number of pages to evict
+   * @returns Array of demotion events
+   */
+  async evictLRU(count: number): Promise<DemotionEvent[]> {
+    const hotPages: DemotionCandidate[] = []
+    const now = Date.now()
+
+    for (const [key, info] of this.trackingMap.entries()) {
+      if (info.tier === 'hot') {
+        hotPages.push({
+          key,
+          tier: info.tier,
+          lastAccess: info.lastAccess,
+          age: now - info.lastAccess,
+        })
+      }
+    }
+
+    // Sort by last access (oldest first)
+    hotPages.sort((a, b) => a.lastAccess - b.lastAccess)
+
+    const toEvict = hotPages.slice(0, count)
+    const events: DemotionEvent[] = []
+
+    for (const candidate of toEvict) {
+      const event = await this.demote(candidate.key, 'hot', 'warm', 'lru_eviction')
+      events.push(event)
+    }
+
+    return events
+  }
+
+  /**
+   * Remove a page from tracking
+   *
+   * @param key - The page key
+   */
+  untrackPage(key: string): void {
+    this.trackingMap.delete(key)
+  }
+
+  /**
+   * Clear all tracking data
+   */
+  clearTracking(): void {
+    this.trackingMap.clear()
+  }
+
+  /**
+   * Get the number of tracked pages in each tier
+   */
+  getTrackedPageCounts(): Record<StorageTier, number> {
+    const counts: Record<StorageTier, number> = {
+      hot: 0,
+      warm: 0,
+      cold: 0,
+    }
+
+    for (const info of this.trackingMap.values()) {
+      counts[info.tier]++
+    }
+
+    return counts
+  }
+}
+
+/**
+ * Create a new AutoDemoter instance
+ *
+ * @param config - Configuration for the auto-demoter
+ * @returns A configured AutoDemoter instance
+ */
+export function createAutoDemoter(config: AutoDemoterConfig): AutoDemoter {
+  return new AutoDemoter(config)
+}