@dotdo/postgres 0.1.0

package/src/pglite/tiered-vfs.ts

@@ -0,0 +1,33 @@
+/**
+ * TieredVFS - Re-export from canonical storage module
+ *
+ * This file re-exports the consolidated TieredVFS from the storage module.
+ * The canonical implementation is at: packages/postgres/src/storage/tiered-vfs.ts
+ *
+ * Consolidation: postgres-u2ut - Merged graceful degradation features into storage module
+ *
+ * @module pglite/tiered-vfs
+ * @see storage/tiered-vfs for the canonical implementation
+ */
+
+// Re-export everything from the canonical storage module
+export {
+  TieredVFS,
+  createTieredVFS,
+} from '../storage/tiered-vfs'
+
+export type {
+  StorageTier,
+  TierHealth,
+  TierFailure,
+  TierHealthStatus,
+  TierFailureCallback,
+  PageLocation,
+  ReadOptions,
+  WriteOptions,
+  TieredVFSConfig,
+  TieredVFSStats,
+  PromotionEvent,
+  TierEventCallback,
+  DeleteResult,
+} from '../storage/tiered-vfs'

package/src/pglite/tiering-stats.test.ts

@@ -0,0 +1,531 @@
+/**
+ * RED PHASE Tests for Tiering Statistics and Events
+ * Task: postgres-xm8.12 - Tiering Statistics and Events
+ *
+ * Provides comprehensive statistics and event tracking for the
+ * tiered storage system.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  TieringStats,
+  TieringStatsConfig,
+  TieringEvent,
+  TieringSummary,
+  createTieringStats,
+} from './tiering-stats'
+import { CacheLayerStats } from './cache-layer'
+import { R2StorageLayerStats } from './r2-layer'
+import type { StorageTier } from '../storage/tiered-vfs'
+import type { PromotionEvent } from './auto-promotion'
+import type { DemotionEvent } from './auto-demotion'
+
+describe('Tiering Statistics and Events', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('TieringStatsConfig', () => {
+    it('should have optional config fields', () => {
+      const config: TieringStatsConfig = {
+        maxEventHistory: 1000,
+        enableDetailedStats: true,
+      }
+      expect(config.maxEventHistory).toBe(1000)
+      expect(config.enableDetailedStats).toBe(true)
+    })
+
+    it('should support event callback', () => {
+      const onEvent = vi.fn()
+      const config: TieringStatsConfig = {
+        onEvent,
+      }
+      expect(config.onEvent).toBe(onEvent)
+    })
+  })
+
+  describe('createTieringStats()', () => {
+    it('should return a TieringStats instance', () => {
+      const stats = createTieringStats()
+      expect(stats).toBeDefined()
+      expect(stats).toBeInstanceOf(TieringStats)
+    })
+
+    it('should accept optional config', () => {
+      const config: TieringStatsConfig = {
+        maxEventHistory: 500,
+      }
+      const stats = createTieringStats(config)
+      expect(stats).toBeInstanceOf(TieringStats)
+    })
+  })
+
+  describe('TieringStats.recordPromotion()', () => {
+    it('should record promotion events', () => {
+      const stats = createTieringStats()
+
+      const event: PromotionEvent = {
+        key: 'page-123',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 5,
+      }
+
+      stats.recordPromotion(event)
+
+      const summary = stats.getSummary()
+      expect(summary.promotions.total).toBe(1)
+      expect(summary.promotions.successful).toBe(1)
+    })
+
+    it('should track failed promotions separately', () => {
+      const stats = createTieringStats()
+
+      const successEvent: PromotionEvent = {
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      }
+
+      const failEvent: PromotionEvent = {
+        key: 'page-2',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: false,
+        timestamp: Date.now(),
+        accessCount: 3,
+        error: 'Page not found',
+      }
+
+      stats.recordPromotion(successEvent)
+      stats.recordPromotion(failEvent)
+
+      const summary = stats.getSummary()
+      expect(summary.promotions.total).toBe(2)
+      expect(summary.promotions.successful).toBe(1)
+      expect(summary.promotions.failed).toBe(1)
+    })
+
+    it('should track promotions by tier transition', () => {
+      const stats = createTieringStats()
+
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      stats.recordPromotion({
+        key: 'page-2',
+        fromTier: 'warm',
+        toTier: 'hot',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 5,
+      })
+
+      const summary = stats.getSummary()
+      expect(summary.promotions.byTransition['cold->warm']).toBe(1)
+      expect(summary.promotions.byTransition['warm->hot']).toBe(1)
+    })
+  })
+
+  describe('TieringStats.recordDemotion()', () => {
+    it('should record demotion events', () => {
+      const stats = createTieringStats()
+
+      const event: DemotionEvent = {
+        key: 'page-123',
+        fromTier: 'hot',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        reason: 'ttl_expired',
+      }
+
+      stats.recordDemotion(event)
+
+      const summary = stats.getSummary()
+      expect(summary.demotions.total).toBe(1)
+      expect(summary.demotions.successful).toBe(1)
+    })
+
+    it('should track demotions by reason', () => {
+      const stats = createTieringStats()
+
+      stats.recordDemotion({
+        key: 'page-1',
+        fromTier: 'hot',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        reason: 'ttl_expired',
+      })
+
+      stats.recordDemotion({
+        key: 'page-2',
+        fromTier: 'hot',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        reason: 'lru_eviction',
+      })
+
+      const summary = stats.getSummary()
+      expect(summary.demotions.byReason['ttl_expired']).toBe(1)
+      expect(summary.demotions.byReason['lru_eviction']).toBe(1)
+    })
+  })
+
+  describe('TieringStats.recordAccess()', () => {
+    it('should track access by tier', () => {
+      const stats = createTieringStats()
+
+      stats.recordAccess('page-1', 'hot')
+      stats.recordAccess('page-2', 'hot')
+      stats.recordAccess('page-3', 'warm')
+      stats.recordAccess('page-4', 'cold')
+
+      const summary = stats.getSummary()
+      expect(summary.accesses.byTier['hot']).toBe(2)
+      expect(summary.accesses.byTier['warm']).toBe(1)
+      expect(summary.accesses.byTier['cold']).toBe(1)
+    })
+
+    it('should track total accesses', () => {
+      const stats = createTieringStats()
+
+      stats.recordAccess('page-1', 'hot')
+      stats.recordAccess('page-2', 'warm')
+      stats.recordAccess('page-3', 'cold')
+
+      const summary = stats.getSummary()
+      expect(summary.accesses.total).toBe(3)
+    })
+  })
+
+  describe('TieringStats.updateLayerStats()', () => {
+    it('should accept cache layer stats', () => {
+      const stats = createTieringStats()
+
+      const cacheStats: CacheLayerStats = {
+        hits: 100,
+        misses: 50,
+        writes: 30,
+        deletes: 5,
+        bytesRead: 10000,
+        bytesWritten: 5000,
+        errors: 1,
+        hitRatio: 0.67,
+      }
+
+      stats.updateLayerStats('cache', cacheStats)
+
+      const summary = stats.getSummary()
+      expect(summary.layers.cache.hits).toBe(100)
+      expect(summary.layers.cache.hitRatio).toBeCloseTo(0.67, 2)
+    })
+
+    it('should accept R2 layer stats', () => {
+      const stats = createTieringStats()
+
+      const r2Stats: R2StorageLayerStats = {
+        reads: 20,
+        rangeReads: 5,
+        writes: 10,
+        deletes: 2,
+        bytesRead: 2000,
+        bytesWritten: 1000,
+        errors: 0,
+      }
+
+      stats.updateLayerStats('r2', r2Stats)
+
+      const summary = stats.getSummary()
+      expect(summary.layers.r2.reads).toBe(20)
+      expect(summary.layers.r2.rangeReads).toBe(5)
+    })
+  })
+
+  describe('TieringStats.getEventHistory()', () => {
+    it('should return recent events', () => {
+      const stats = createTieringStats()
+
+      vi.setSystemTime(new Date('2026-01-17T12:00:00Z'))
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      vi.setSystemTime(new Date('2026-01-17T12:00:01Z'))
+      stats.recordDemotion({
+        key: 'page-2',
+        fromTier: 'hot',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        reason: 'ttl_expired',
+      })
+
+      const history = stats.getEventHistory()
+      expect(history.length).toBe(2)
+      expect(history[0].type).toBe('promotion')
+      expect(history[1].type).toBe('demotion')
+    })
+
+    it('should limit history to configured max', () => {
+      const stats = createTieringStats({ maxEventHistory: 5 })
+
+      for (let i = 0; i < 10; i++) {
+        stats.recordPromotion({
+          key: `page-${i}`,
+          fromTier: 'cold',
+          toTier: 'warm',
+          success: true,
+          timestamp: Date.now(),
+          accessCount: 3,
+        })
+      }
+
+      const history = stats.getEventHistory()
+      expect(history.length).toBe(5)
+    })
+
+    it('should filter by event type', () => {
+      const stats = createTieringStats()
+
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      stats.recordDemotion({
+        key: 'page-2',
+        fromTier: 'hot',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        reason: 'ttl_expired',
+      })
+
+      const promotions = stats.getEventHistory({ type: 'promotion' })
+      expect(promotions.length).toBe(1)
+      expect(promotions[0].type).toBe('promotion')
+    })
+
+    it('should filter by time range', () => {
+      const stats = createTieringStats()
+
+      vi.setSystemTime(new Date('2026-01-17T12:00:00Z'))
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      vi.setSystemTime(new Date('2026-01-17T12:05:00Z'))
+      stats.recordPromotion({
+        key: 'page-2',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      const recentEvents = stats.getEventHistory({
+        since: new Date('2026-01-17T12:03:00Z').getTime(),
+      })
+      expect(recentEvents.length).toBe(1)
+      expect(recentEvents[0].data.key).toBe('page-2')
+    })
+  })
+
+  describe('TieringStats.getSummary()', () => {
+    it('should return comprehensive summary', () => {
+      const stats = createTieringStats()
+
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      stats.recordDemotion({
+        key: 'page-2',
+        fromTier: 'hot',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        reason: 'ttl_expired',
+      })
+
+      stats.recordAccess('page-3', 'hot')
+
+      const summary = stats.getSummary()
+
+      expect(summary).toHaveProperty('promotions')
+      expect(summary).toHaveProperty('demotions')
+      expect(summary).toHaveProperty('accesses')
+      expect(summary).toHaveProperty('layers')
+      expect(summary).toHaveProperty('timestamp')
+    })
+  })
+
+  describe('TieringStats.reset()', () => {
+    it('should reset all counters', () => {
+      const stats = createTieringStats()
+
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      stats.recordAccess('page-2', 'hot')
+
+      stats.reset()
+
+      const summary = stats.getSummary()
+      expect(summary.promotions.total).toBe(0)
+      expect(summary.accesses.total).toBe(0)
+    })
+
+    it('should clear event history', () => {
+      const stats = createTieringStats()
+
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      stats.reset()
+
+      const history = stats.getEventHistory()
+      expect(history.length).toBe(0)
+    })
+  })
+
+  describe('TieringEvent type', () => {
+    it('should have required fields', () => {
+      const event: TieringEvent = {
+        type: 'promotion',
+        timestamp: Date.now(),
+        data: {
+          key: 'page-123',
+          fromTier: 'cold',
+          toTier: 'warm',
+          success: true,
+          accessCount: 5,
+        },
+      }
+      expect(event.type).toBe('promotion')
+      expect(event.data.key).toBe('page-123')
+    })
+
+    it('should support demotion type', () => {
+      const event: TieringEvent = {
+        type: 'demotion',
+        timestamp: Date.now(),
+        data: {
+          key: 'page-123',
+          fromTier: 'hot',
+          toTier: 'warm',
+          success: true,
+          reason: 'ttl_expired',
+        },
+      }
+      expect(event.type).toBe('demotion')
+      expect(event.data.reason).toBe('ttl_expired')
+    })
+
+    it('should support access type', () => {
+      const event: TieringEvent = {
+        type: 'access',
+        timestamp: Date.now(),
+        data: {
+          key: 'page-123',
+          tier: 'hot',
+        },
+      }
+      expect(event.type).toBe('access')
+      expect(event.data.tier).toBe('hot')
+    })
+  })
+
+  describe('Event callback', () => {
+    it('should call onEvent for promotions', () => {
+      const onEvent = vi.fn()
+      const stats = createTieringStats({ onEvent })
+
+      stats.recordPromotion({
+        key: 'page-1',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 3,
+      })
+
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'promotion',
+        })
+      )
+    })
+
+    it('should call onEvent for demotions', () => {
+      const onEvent = vi.fn()
+      const stats = createTieringStats({ onEvent })
+
+      stats.recordDemotion({
+        key: 'page-1',
+        fromTier: 'hot',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        reason: 'ttl_expired',
+      })
+
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'demotion',
+        })
+      )
+    })
+  })
+})