@dotdo/postgres 0.1.0

package/src/storage/tiered-vfs-swr.ts

@@ -0,0 +1,735 @@
+/**
+ * TieredVFSWithSWR - TieredVFS with Stale-While-Revalidate Cache Integration
+ * Issue: postgres-kpa8 - Cache Layer SWR Integration
+ *
+ * Extends TieredVFS to integrate SWRCacheLayer for improved cache semantics:
+ * - Returns stale data immediately from HOT tier
+ * - Triggers background R2 revalidation
+ * - Tracks fresh vs stale cache hits
+ *
+ * SWR Pattern:
+ * 1. Check SWR primary cache (return immediately if fresh hit)
+ * 2. Check SWR stale cache (return stale + trigger background revalidation)
+ * 3. Fall back to warm (DO) and cold (R2) tiers on miss
+ *
+ * @module storage/tiered-vfs-swr
+ */
+
+import type { CacheLayer } from './cache-layer'
+import type { R2StorageLayer, R2PutOptions } from './r2-layer'
+import type { SWRCacheLayer, ExecutionContext } from './swr-cache'
+import type { StorageTier, TieredVFSStats, PromotionEvent, TierEventCallback, TierHealth, TierFailure } from './tiered-vfs'
+
+/**
+ * SWR-specific metrics for TieredVFS
+ */
+export interface TieredVFSSWRStats {
+  /** Number of fresh cache hits (primary cache) */
+  freshCacheHits: number
+  /** Number of stale cache hits (stale cache, triggered revalidation) */
+  staleCacheHits: number
+  /** Number of background revalidations triggered */
+  backgroundRevalidations: number
+  /** Whether SWR is enabled */
+  enabled: boolean
+}
+
+/**
+ * Extended statistics including SWR metrics
+ */
+export interface TieredVFSWithSWRStats extends TieredVFSStats {
+  /** SWR cache statistics */
+  swr: TieredVFSSWRStats
+}
+
+/**
+ * Options for read operations with SWR support
+ */
+export interface SWRReadOptions {
+  /** Whether to skip promotion after read */
+  skipPromotion?: boolean
+  /** Whether to track access for promotion/demotion decisions */
+  trackAccess?: boolean
+  /** Execution context for background revalidation (required for SWR) */
+  ctx?: ExecutionContext
+}
+
+/**
+ * Options for write operations
+ */
+export interface SWRWriteOptions {
+  /** Target tier for the write */
+  tier?: StorageTier
+  /** Custom metadata to attach */
+  metadata?: Record<string, string>
+  /** Whether to also write to hotter tiers for immediate availability */
+  writeThrough?: boolean
+}
+
+/**
+ * Configuration for TieredVFSWithSWR
+ */
+export interface TieredVFSWithSWRConfig {
+  /** Cache layer for hot tier (used as fallback when SWR misses) */
+  cacheLayer: CacheLayer
+  /** Durable Object storage for warm tier */
+  doStorage: DurableObjectStorage
+  /** R2 layer for cold tier */
+  r2Layer: R2StorageLayer
+  /** SWR cache layer for stale-while-revalidate semantics */
+  swrCacheLayer: SWRCacheLayer
+  /** Page size in bytes (typically 8KB for PGLite) */
+  pageSize: number
+  /** Number of accesses before promoting to hotter tier */
+  promotionThreshold?: number
+  /** Whether to auto-promote on read from cold tiers */
+  autoPromote?: boolean
+}
+
+/**
+ * TieredVFSWithSWR combines SWR caching with the standard tiered storage.
+ *
+ * Read path with SWR:
+ * 1. SWR primary cache (fresh data, immediate return)
+ * 2. SWR stale cache (stale data + background revalidation)
+ * 3. DO Storage (warm tier)
+ * 4. R2 (cold tier)
+ *
+ * When data is found in warm/cold tiers, it's also populated into SWR cache.
+ *
+ * @example
+ * ```typescript
+ * const tieredVFS = await createTieredVFSWithSWR({
+ *   cacheLayer,
+ *   doStorage: ctx.storage,
+ *   r2Layer,
+ *   swrCacheLayer,
+ *   pageSize: 8192,
+ * })
+ *
+ * // Read with SWR semantics - pass execution context for background revalidation
+ * const page = await tieredVFS.readPage('page-123', { ctx })
+ *
+ * // Get SWR-specific stats
+ * const stats = tieredVFS.getStats()
+ * console.log(`Fresh hits: ${stats.swr.freshCacheHits}`)
+ * console.log(`Stale hits: ${stats.swr.staleCacheHits}`)
+ * ```
+ */
+export class TieredVFSWithSWR {
+  private cacheLayer: CacheLayer
+  private doStorage: DurableObjectStorage
+  private r2Layer: R2StorageLayer
+  private swrCacheLayer: SWRCacheLayer
+  private pageSize: number
+  private promotionThreshold: number
+  private autoPromote: boolean
+  private doStats: {
+    reads: number
+    writes: number
+    deletes: number
+    bytesRead: number
+    bytesWritten: number
+  }
+  private promotionStats: {
+    coldToWarm: number
+    warmToHot: number
+  }
+  private demotionStats: {
+    hotToWarm: number
+    warmToCold: number
+  }
+  private swrStats: {
+    freshCacheHits: number
+    staleCacheHits: number
+    backgroundRevalidations: number
+  }
+  private accessCounts: Map<string, number>
+  private onPromotionCallback?: TierEventCallback
+  private onDemotionCallback?: TierEventCallback
+  private _tierHealth: {
+    hot: TierHealth
+    warm: TierHealth
+    cold: TierHealth
+  }
+  private _recentFailures: TierFailure[]
+  private _failureCounts: Record<StorageTier, number>
+
+  constructor(config: TieredVFSWithSWRConfig) {
+    this.cacheLayer = config.cacheLayer
+    this.doStorage = config.doStorage
+    this.r2Layer = config.r2Layer
+    this.swrCacheLayer = config.swrCacheLayer
+    this.pageSize = config.pageSize
+    this.promotionThreshold = config.promotionThreshold ?? 3
+    this.autoPromote = config.autoPromote ?? false
+    this.doStats = {
+      reads: 0,
+      writes: 0,
+      deletes: 0,
+      bytesRead: 0,
+      bytesWritten: 0,
+    }
+    this.promotionStats = {
+      coldToWarm: 0,
+      warmToHot: 0,
+    }
+    this.demotionStats = {
+      hotToWarm: 0,
+      warmToCold: 0,
+    }
+    this.swrStats = {
+      freshCacheHits: 0,
+      staleCacheHits: 0,
+      backgroundRevalidations: 0,
+    }
+    this.accessCounts = new Map()
+    this._tierHealth = {
+      hot: 'healthy',
+      warm: 'healthy',
+      cold: 'healthy',
+    }
+    this._recentFailures = []
+    this._failureCounts = { hot: 0, warm: 0, cold: 0 }
+
+    // Wire R2 as the origin fetcher for SWR background revalidation
+    this.swrCacheLayer.setOriginFetcher(async (key: string) => {
+      return this.r2Layer.get(key)
+    })
+  }
+
+  /**
+   * Set callback for promotion events
+   */
+  onPromotion(callback: TierEventCallback): void {
+    this.onPromotionCallback = callback
+  }
+
+  /**
+   * Set callback for demotion events
+   */
+  onDemotion(callback: TierEventCallback): void {
+    this.onDemotionCallback = callback
+  }
+
+  /**
+   * Increment access count and check if promotion is needed
+   */
+  private trackAccessCount(key: string): number {
+    const count = (this.accessCounts.get(key) ?? 0) + 1
+    this.accessCounts.set(key, count)
+    return count
+  }
+
+  /**
+   * Reset access count for a key
+   */
+  private resetAccessCount(key: string): void {
+    this.accessCounts.delete(key)
+  }
+
+  /**
+   * Read a page from the tiered storage with SWR semantics
+   *
+   * Checks tiers in order:
+   * 1. SWR cache (primary/fresh first, then stale with background revalidation)
+   * 2. Warm tier (DO Storage)
+   * 3. Cold tier (R2)
+   *
+   * When SWR returns stale data, background revalidation fetches fresh data from R2.
+   * Data found in warm/cold tiers is also populated into SWR cache.
+   *
+   * @param key - The page key
+   * @param options - Read options including execution context for SWR
+   * @returns The page data or null if not found
+   */
+  async readPage(key: string, options?: SWRReadOptions): Promise<Uint8Array | null> {
+    const trackAccess = options?.trackAccess ?? true
+    const skipPromotion = options?.skipPromotion ?? false
+
+    // Step 1: Try SWR cache (HOT tier with SWR semantics)
+    const swrResult = await this.swrCacheLayer.get(key, options?.ctx)
+
+    if (swrResult.hit && swrResult.data) {
+      if (swrResult.stale) {
+        this.swrStats.staleCacheHits++
+        if (swrResult.revalidating) {
+          this.swrStats.backgroundRevalidations++
+        }
+      } else {
+        this.swrStats.freshCacheHits++
+      }
+
+      if (trackAccess) {
+        this.trackAccessCount(key)
+      }
+
+      return swrResult.data
+    }
+
+    // Step 2: Try warm tier (DO Storage)
+    const doData = (await this.doStorage.get(key)) as Uint8Array | undefined
+    if (doData) {
+      this.doStats.reads++
+      this.doStats.bytesRead += doData.length
+
+      if (trackAccess) {
+        const accessCount = this.trackAccessCount(key)
+
+        // Check for promotion to hot tier
+        if (!skipPromotion && this.autoPromote && accessCount >= this.promotionThreshold) {
+          await this.promoteToHot(key, doData)
+        }
+      }
+
+      // Populate SWR cache for future requests
+      await this.swrCacheLayer.put(key, doData)
+
+      return doData
+    }
+
+    // Step 3: Try cold tier (R2)
+    const r2Data = await this.r2Layer.get(key)
+    if (r2Data) {
+      if (trackAccess) {
+        const accessCount = this.trackAccessCount(key)
+
+        // Check for promotion to warm tier
+        if (!skipPromotion && this.autoPromote && accessCount >= this.promotionThreshold) {
+          await this.promoteToWarm(key, r2Data)
+        }
+      }
+
+      // Populate SWR cache for future requests
+      await this.swrCacheLayer.put(key, r2Data)
+
+      return r2Data
+    }
+
+    return null
+  }
+
+  /**
+   * Read a page and return which tier it was found in
+   *
+   * @param key - The page key
+   * @param ctx - Optional execution context for SWR background revalidation
+   * @returns The page data and location, or null if not found
+   */
+  async readPageWithLocation(
+    key: string,
+    ctx?: ExecutionContext
+  ): Promise<{ data: Uint8Array; tier: StorageTier; stale?: boolean } | null> {
+    // Try SWR cache first
+    const swrResult = await this.swrCacheLayer.get(key, ctx)
+    if (swrResult.hit && swrResult.data) {
+      if (swrResult.stale) {
+        this.swrStats.staleCacheHits++
+        if (swrResult.revalidating) {
+          this.swrStats.backgroundRevalidations++
+        }
+      } else {
+        this.swrStats.freshCacheHits++
+      }
+      return { data: swrResult.data, tier: 'hot', stale: swrResult.stale }
+    }
+
+    // Try warm tier (DO Storage)
+    const doData = (await this.doStorage.get(key)) as Uint8Array | undefined
+    if (doData) {
+      this.doStats.reads++
+      this.doStats.bytesRead += doData.length
+      return { data: doData, tier: 'warm' }
+    }
+
+    // Try cold tier (R2)
+    const r2Data = await this.r2Layer.get(key)
+    if (r2Data) {
+      return { data: r2Data, tier: 'cold' }
+    }
+
+    return null
+  }
+
+  /**
+   * Write a page to the tiered storage
+   *
+   * By default writes to warm tier (DO Storage).
+   * Also updates SWR cache to ensure consistency.
+   *
+   * @param key - The page key
+   * @param data - The page data
+   * @param options - Write options
+   */
+  async writePage(key: string, data: Uint8Array, options?: SWRWriteOptions): Promise<void> {
+    const tier = options?.tier ?? 'warm'
+
+    switch (tier) {
+      case 'hot':
+        // Write to both DO (for persistence) and Cache/SWR (for speed)
+        await this.doStorage.put(key, data)
+        this.doStats.writes++
+        this.doStats.bytesWritten += data.length
+        await this.cacheLayer.put(key, data, {
+          lastAccessed: Date.now(),
+          accessCount: 1,
+        })
+        // Also update SWR cache
+        await this.swrCacheLayer.put(key, data)
+
+        // Optionally write through to cold tier for durability
+        if (options?.writeThrough) {
+          const r2Options: R2PutOptions = {}
+          if (options.metadata !== undefined) {
+            r2Options.customMetadata = options.metadata
+          }
+          await this.r2Layer.put(key, data, r2Options)
+        }
+        break
+
+      case 'warm':
+        // Write to DO only
+        await this.doStorage.put(key, data)
+        this.doStats.writes++
+        this.doStats.bytesWritten += data.length
+        // Update SWR cache for consistency
+        await this.swrCacheLayer.put(key, data)
+
+        // Optionally write through to cold tier for durability
+        if (options?.writeThrough) {
+          const r2Options: R2PutOptions = {}
+          if (options.metadata !== undefined) {
+            r2Options.customMetadata = options.metadata
+          }
+          await this.r2Layer.put(key, data, r2Options)
+        }
+        break
+
+      case 'cold': {
+        // Write to R2 only (for archival)
+        const r2Options: R2PutOptions = {}
+        if (options?.metadata !== undefined) {
+          r2Options.customMetadata = options.metadata
+        }
+        await this.r2Layer.put(key, data, r2Options)
+        // Invalidate SWR cache since data changed
+        await this.swrCacheLayer.invalidate(key)
+        break
+      }
+    }
+  }
+
+  /**
+   * Delete a page from all tiers including SWR cache
+   *
+   * @param key - The page key
+   */
+  async deletePage(key: string): Promise<void> {
+    // Delete from all tiers in parallel
+    await Promise.all([
+      this.cacheLayer.delete(key),
+      this.swrCacheLayer.invalidate(key),
+      this.doStorage.delete(key).then(() => {
+        this.doStats.deletes++
+      }),
+      this.r2Layer.delete(key),
+    ])
+
+    // Clear access tracking
+    this.resetAccessCount(key)
+  }
+
+  /**
+   * Delete multiple pages from all tiers
+   *
+   * @param keys - The page keys to delete
+   */
+  async deletePages(keys: string[]): Promise<void> {
+    await Promise.all(keys.map((key) => this.deletePage(key)))
+  }
+
+  /**
+   * Locate which tier a page is stored in
+   *
+   * @param key - The page key
+   * @returns Location information
+   */
+  async locatePage(key: string): Promise<{ tier?: StorageTier; found: boolean; key: string }> {
+    // Check SWR cache (hot tier)
+    const inSWR = await this.swrCacheLayer.has(key)
+    if (inSWR) {
+      return { tier: 'hot', found: true, key }
+    }
+
+    // Check standard cache (hot tier fallback)
+    const inCache = await this.cacheLayer.has(key)
+    if (inCache) {
+      return { tier: 'hot', found: true, key }
+    }
+
+    // Check warm tier
+    const doData = (await this.doStorage.get(key)) as Uint8Array | undefined
+    if (doData) {
+      return { tier: 'warm', found: true, key }
+    }
+
+    // Check cold tier
+    const inR2 = await this.r2Layer.has(key)
+    if (inR2) {
+      return { tier: 'cold', found: true, key }
+    }
+
+    return { found: false, key }
+  }
+
+  /**
+   * Promote a page from cold (R2) to warm (DO) tier
+   *
+   * @param key - The page key
+   * @param data - The page data (optional, will be fetched if not provided)
+   */
+  async promoteToWarm(key: string, data?: Uint8Array): Promise<void> {
+    const pageData = data ?? (await this.r2Layer.get(key))
+    if (!pageData) {
+      return
+    }
+
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'cold',
+      toTier: 'warm',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      await this.doStorage.put(key, pageData)
+      this.doStats.writes++
+      this.doStats.bytesWritten += pageData.length
+      this.promotionStats.coldToWarm++
+      this.resetAccessCount(key)
+      event.success = true
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onPromotionCallback?.(event)
+  }
+
+  /**
+   * Promote a page from warm (DO) to hot (SWR Cache) tier
+   *
+   * @param key - The page key
+   * @param data - The page data (optional, will be fetched if not provided)
+   */
+  async promoteToHot(key: string, data?: Uint8Array): Promise<void> {
+    const pageData = data ?? ((await this.doStorage.get(key)) as Uint8Array | undefined)
+    if (!pageData) {
+      return
+    }
+
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'warm',
+      toTier: 'hot',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      // Update both standard cache and SWR cache
+      await this.cacheLayer.put(key, pageData, {
+        lastAccessed: Date.now(),
+        accessCount: this.accessCounts.get(key) ?? 1,
+      })
+      await this.swrCacheLayer.put(key, pageData)
+      this.promotionStats.warmToHot++
+      this.resetAccessCount(key)
+      event.success = true
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onPromotionCallback?.(event)
+  }
+
+  /**
+   * Demote a page from hot (Cache) to warm (DO) tier
+   *
+   * @param key - The page key
+   */
+  async demoteFromHot(key: string): Promise<void> {
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'hot',
+      toTier: 'warm',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      // Delete from both caches - data should already be in DO
+      await this.cacheLayer.delete(key)
+      await this.swrCacheLayer.invalidate(key)
+      this.demotionStats.hotToWarm++
+      event.success = true
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onDemotionCallback?.(event)
+  }
+
+  /**
+   * Demote a page from warm (DO) to cold (R2) tier
+   *
+   * @param key - The page key
+   */
+  async demoteFromWarm(key: string): Promise<void> {
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'warm',
+      toTier: 'cold',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      // 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: Date.now().toString(),
+          },
+        })
+        await this.doStorage.delete(key)
+        this.doStats.deletes++
+        this.demotionStats.warmToCold++
+        event.success = true
+      }
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onDemotionCallback?.(event)
+  }
+
+  /**
+   * Get combined statistics from all tiers including SWR
+   */
+  getStats(): TieredVFSWithSWRStats {
+    return {
+      cache: this.cacheLayer.getStats(),
+      r2: this.r2Layer.getStats(),
+      do: { ...this.doStats },
+      promotions: { ...this.promotionStats },
+      demotions: { ...this.demotionStats },
+      tierHealth: {
+        hot: this._tierHealth.hot,
+        warm: this._tierHealth.warm,
+        cold: this._tierHealth.cold,
+        recentFailures: [...this._recentFailures],
+        failureCounts: { ...this._failureCounts },
+      },
+      swr: {
+        freshCacheHits: this.swrStats.freshCacheHits,
+        staleCacheHits: this.swrStats.staleCacheHits,
+        backgroundRevalidations: this.swrStats.backgroundRevalidations,
+        enabled: true,
+      },
+    }
+  }
+
+  /**
+   * Get SWR-specific statistics
+   */
+  getSWRStats(): TieredVFSSWRStats {
+    return {
+      freshCacheHits: this.swrStats.freshCacheHits,
+      staleCacheHits: this.swrStats.staleCacheHits,
+      backgroundRevalidations: this.swrStats.backgroundRevalidations,
+      enabled: true,
+    }
+  }
+
+  /**
+   * Reset all statistics including SWR
+   */
+  resetStats(): void {
+    this.doStats = {
+      reads: 0,
+      writes: 0,
+      deletes: 0,
+      bytesRead: 0,
+      bytesWritten: 0,
+    }
+    this.promotionStats = {
+      coldToWarm: 0,
+      warmToHot: 0,
+    }
+    this.demotionStats = {
+      hotToWarm: 0,
+      warmToCold: 0,
+    }
+    this.swrStats = {
+      freshCacheHits: 0,
+      staleCacheHits: 0,
+      backgroundRevalidations: 0,
+    }
+    this.accessCounts.clear()
+    this.swrCacheLayer.resetStats()
+  }
+
+  /**
+   * Get the configured page size
+   */
+  getPageSize(): number {
+    return this.pageSize
+  }
+
+  /**
+   * Get the access count for a key
+   */
+  getAccessCount(key: string): number {
+    return this.accessCounts.get(key) ?? 0
+  }
+
+  /**
+   * Get the promotion threshold
+   */
+  getPromotionThreshold(): number {
+    return this.promotionThreshold
+  }
+
+  /**
+   * Set the promotion threshold
+   */
+  setPromotionThreshold(threshold: number): void {
+    this.promotionThreshold = threshold
+  }
+
+  /**
+   * Enable or disable auto-promotion
+   */
+  setAutoPromote(enabled: boolean): void {
+    this.autoPromote = enabled
+  }
+
+  /**
+   * Check if SWR is enabled (always true for this class)
+   */
+  isSWREnabled(): boolean {
+    return true
+  }
+}
+
+/**
+ * Create a new TieredVFSWithSWR instance
+ *
+ * @param config - Configuration for the tiered VFS with SWR
+ * @returns A configured TieredVFSWithSWR instance
+ */
+export function createTieredVFSWithSWR(config: TieredVFSWithSWRConfig): TieredVFSWithSWR {
+  return new TieredVFSWithSWR(config)
+}