@dotdo/postgres 0.1.0

package/src/storage/r2-page-vfs.ts

@@ -0,0 +1,1054 @@
+/**
+ * R2PageVFS - R2 Page-based Virtual File System
+ *
+ * Provides page-level access to R2-backed storage with SWR caching integration.
+ * Optimized for PGLite database pages stored in R2 with efficient caching
+ * through Cloudflare's Cache API.
+ *
+ * Page Storage Format:
+ * - Pages stored at: {prefix}/v{version}/pages/{8-digit-padded-page-number}
+ * - Example: db/v1/pages/00000001, db/v1/pages/00000042
+ * - Default page size: 8192 bytes (8KB, PostgreSQL default)
+ *
+ * Key Features:
+ * - Page-granularity reads with 8-digit padded page numbers
+ * - SWR caching with primary (fresh) and stale cache tiers
+ * - Version-based cache invalidation for safe schema updates
+ * - Batch operations with configurable concurrency
+ * - Comprehensive statistics for monitoring
+ *
+ * @example
+ * ```typescript
+ * import { createR2PageVFS } from './r2-page-vfs'
+ * import { createSWRCacheLayer } from './swr-cache'
+ *
+ * const swrCache = await createSWRCacheLayer({
+ *   baseUrl: 'https://pglite.cache.local',
+ *   primaryTtlSeconds: 60,
+ *   staleTtlSeconds: 3600,
+ * })
+ *
+ * const vfs = createR2PageVFS({
+ *   bucket: env.R2_BUCKET,
+ *   prefix: 'mydb',
+ *   version: '1',
+ *   swrCache,
+ * })
+ *
+ * // Read single page
+ * const result = await vfs.readPage(42, ctx)
+ * if (result.data) {
+ *   console.log(`Page 42: ${result.data.length} bytes, stale: ${result.stale}`)
+ * }
+ *
+ * // Batch read
+ * const pages = await vfs.readPages([1, 2, 3, 4, 5], ctx)
+ * ```
+ *
+ * @module storage/r2-page-vfs
+ */
+
+import type { SWRCacheLayer, ExecutionContext } from './swr-cache'
+
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening the circuit */
+  failureThreshold: number
+  /** Time in ms to wait before attempting to close the circuit */
+  resetTimeoutMs: number
+}
+
+/**
+ * Configuration for R2PageVFS
+ */
+export interface R2PageVFSConfig {
+  /** The R2 bucket binding */
+  bucket: R2Bucket
+  /** Prefix for all keys in the bucket (without trailing slash) */
+  prefix: string
+  /** Version string for cache key namespacing and busting */
+  version: string
+  /** Page size in bytes (default: 8192 for PostgreSQL) */
+  pageSize?: number
+  /** SWR cache layer for tiered caching */
+  swrCache: SWRCacheLayer
+  /** Maximum concurrent R2 operations for batch reads (default: 10) */
+  concurrencyLimit?: number
+  /** Timeout for R2 operations in milliseconds (default: 30000) */
+  timeoutMs?: number
+  /** Number of retries for transient errors (default: 3) */
+  retryCount?: number
+  /** Circuit breaker configuration for R2 failure protection */
+  circuitBreaker?: CircuitBreakerConfig
+}
+
+/**
+ * Result from a single page read operation
+ */
+export interface PageReadResult {
+  /** The page data (null if page doesn't exist) */
+  data: Uint8Array | null
+  /** Whether this was a cache hit */
+  hit: boolean
+  /** Whether the data is stale (from stale cache) */
+  stale: boolean
+  /** Source of the data */
+  source: 'primary-cache' | 'stale-cache' | 'r2' | 'miss'
+  /** Latency of the operation in milliseconds */
+  latencyMs: number
+}
+
+/**
+ * Result from batch page read operation
+ */
+export interface BatchPageResult {
+  /** Map of page number to read result */
+  pages: Map<number, PageReadResult>
+  /** Total latency for the batch operation */
+  totalLatencyMs: number
+  /** Number of cache hits in the batch */
+  cacheHits: number
+  /** Number of R2 reads in the batch */
+  r2Reads: number
+}
+
+/**
+ * Statistics for R2PageVFS operations
+ */
+export interface R2PageVFSStats {
+  /** Number of primary cache hits */
+  primaryCacheHits: number
+  /** Number of stale cache hits */
+  staleCacheHits: number
+  /** Number of complete cache misses */
+  cacheMisses: number
+  /** Number of R2 read operations */
+  r2Reads: number
+  /** Number of R2 errors */
+  r2Errors: number
+  /** Total bytes read */
+  bytesRead: number
+  /** Bytes served from cache */
+  bytesFromCache: number
+  /** Bytes fetched from R2 */
+  bytesFromR2: number
+  /** Number of batch operations */
+  batchOperations: number
+  /** Number of background revalidations triggered */
+  backgroundRevalidations: number
+  /** Number of requests deduplicated via singleflight pattern */
+  deduplicatedRequests: number
+  /** Cache hit ratio (0-1) */
+  cacheHitRatio: number
+  /** Average cache read latency in ms */
+  avgCacheLatencyMs: number
+  /** Average R2 read latency in ms */
+  avgR2LatencyMs: number
+  /** Total errors */
+  errors: number
+  /** Current circuit breaker state */
+  circuitBreakerState: 'closed' | 'open' | 'half-open'
+  /** Number of times the circuit breaker has tripped (opened) */
+  circuitBreakerTrips: number
+}
+
+/**
+ * R2PageVFS interface for page-based R2 access with SWR caching
+ */
+export interface R2PageVFS {
+  /**
+   * Read a single page by page number
+   *
+   * @param pageNumber - The page number to read (0-indexed)
+   * @param ctx - Optional execution context for background revalidation
+   * @returns Page read result with data and metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await vfs.readPage(42, ctx)
+   *
+   * if (result.data) {
+   *   console.log(`Page 42: ${result.data.length} bytes`)
+   *   console.log(`Source: ${result.source}`) // 'primary-cache', 'stale-cache', 'r2', or 'miss'
+   *   console.log(`Latency: ${result.latencyMs}ms`)
+   *
+   *   if (result.stale) {
+   *     console.log('Serving stale data while revalidating in background')
+   *   }
+   * } else {
+   *   console.log('Page not found')
+   * }
+   * ```
+   */
+  readPage(pageNumber: number, ctx?: ExecutionContext): Promise<PageReadResult>
+
+  /**
+   * Read multiple pages in parallel with concurrency control
+   *
+   * @param pageNumbers - Array of page numbers to read
+   * @param ctx - Optional execution context for background revalidation
+   * @returns Batch result with all pages and aggregate stats
+   *
+   * @example
+   * ```typescript
+   * const result = await vfs.readPages([1, 2, 3, 4, 5], ctx)
+   *
+   * console.log(`Total time: ${result.totalLatencyMs}ms`)
+   * console.log(`Cache hits: ${result.cacheHits}`)
+   * console.log(`R2 reads: ${result.r2Reads}`)
+   *
+   * for (const [pageNum, pageResult] of result.pages) {
+   *   if (pageResult.data) {
+   *     console.log(`Page ${pageNum}: ${pageResult.data.length} bytes`)
+   *   }
+   * }
+   * ```
+   */
+  readPages(pageNumbers: number[], ctx?: ExecutionContext): Promise<BatchPageResult>
+
+  /**
+   * Get the latest version string from R2 metadata
+   *
+   * @returns The current version string stored in R2
+   */
+  getLatestVersion(): Promise<string>
+
+  /**
+   * Check if the current version matches the latest in R2
+   *
+   * @returns True if version is current, false if stale
+   */
+  isVersionCurrent(): Promise<boolean>
+
+  /**
+   * Invalidate all cached pages for the current version
+   */
+  invalidateCache(): Promise<void>
+
+  /**
+   * Invalidate a specific page from cache
+   *
+   * @param pageNumber - The page number to invalidate
+   */
+  invalidatePage(pageNumber: number): Promise<void>
+
+  /**
+   * Invalidate a range of pages from cache
+   *
+   * @param startPage - First page number in range (inclusive)
+   * @param endPage - Last page number in range (inclusive)
+   */
+  invalidatePages(startPage: number, endPage: number): Promise<void>
+
+  /**
+   * Get current statistics
+   *
+   * @returns Statistics object with all counters and metrics
+   *
+   * @example
+   * ```typescript
+   * const stats = vfs.getStats()
+   *
+   * console.log(`Cache hit ratio: ${(stats.cacheHitRatio * 100).toFixed(1)}%`)
+   * console.log(`Primary cache hits: ${stats.primaryCacheHits}`)
+   * console.log(`Stale cache hits: ${stats.staleCacheHits}`)
+   * console.log(`R2 reads: ${stats.r2Reads}`)
+   * console.log(`Avg cache latency: ${stats.avgCacheLatencyMs.toFixed(2)}ms`)
+   * console.log(`Avg R2 latency: ${stats.avgR2LatencyMs.toFixed(2)}ms`)
+   * console.log(`Circuit breaker: ${stats.circuitBreakerState}`)
+   * ```
+   */
+  getStats(): R2PageVFSStats
+
+  /**
+   * Reset all statistics counters
+   */
+  resetStats(): void
+
+  /**
+   * Get the current configuration
+   *
+   * @returns The resolved configuration with defaults applied
+   */
+  getConfig(): Required<R2PageVFSConfig>
+}
+
+/**
+ * Utility: Format page number as 8-digit padded string
+ *
+ * @param pageNumber - The page number to format
+ * @returns 8-character padded string (e.g., 1 -> '00000001')
+ *
+ * @example
+ * ```typescript
+ * formatPageKey(1)    // '00000001'
+ * formatPageKey(42)   // '00000042'
+ * formatPageKey(1234) // '00001234'
+ * ```
+ */
+export function formatPageKey(pageNumber: number): string {
+  if (!Number.isInteger(pageNumber) || pageNumber < 0) {
+    throw new Error(`Invalid page number: ${pageNumber}. Must be non-negative integer.`)
+  }
+  if (pageNumber > 99999999) {
+    throw new Error(`Page number ${pageNumber} exceeds maximum of 99999999`)
+  }
+  return pageNumber.toString().padStart(8, '0')
+}
+
+/**
+ * Utility: Build full R2 key for a page
+ *
+ * @param prefix - The bucket prefix
+ * @param version - The version string
+ * @param pageNumber - The page number
+ * @returns Full R2 key path
+ *
+ * @example
+ * ```typescript
+ * buildR2Key('mydb', '1', 42)
+ * // Returns: 'mydb/v1/pages/00000042'
+ * ```
+ */
+export function buildR2Key(prefix: string, version: string, pageNumber: number): string {
+  return `${prefix}/v${version}/pages/${formatPageKey(pageNumber)}`
+}
+
+/**
+ * Utility: Build cache key for SWR layer
+ *
+ * @param version - The version string
+ * @param pageNumber - The page number
+ * @returns Cache key string
+ */
+export function buildCacheKey(version: string, pageNumber: number): string {
+  return `page-v${version}-${formatPageKey(pageNumber)}`
+}
+
+/**
+ * Utility: Parse page number from R2 key
+ *
+ * @param r2Key - The full R2 key
+ * @returns The page number, or null if key format is invalid
+ */
+export function parsePageNumber(r2Key: string): number | null {
+  const match = r2Key.match(/\/pages\/(\d{8})$/)
+  const pageStr = match?.[1]
+  if (!pageStr) {
+    return null
+  }
+  return parseInt(pageStr, 10)
+}
+
+/**
+ * Create initial empty stats object
+ */
+export function createEmptyStats(): R2PageVFSStats {
+  return {
+    primaryCacheHits: 0,
+    staleCacheHits: 0,
+    cacheMisses: 0,
+    r2Reads: 0,
+    r2Errors: 0,
+    bytesRead: 0,
+    bytesFromCache: 0,
+    bytesFromR2: 0,
+    batchOperations: 0,
+    backgroundRevalidations: 0,
+    deduplicatedRequests: 0,
+    cacheHitRatio: 0,
+    avgCacheLatencyMs: 0,
+    avgR2LatencyMs: 0,
+    errors: 0,
+    circuitBreakerState: 'closed',
+    circuitBreakerTrips: 0,
+  }
+}
+
+/**
+ * Default configuration values
+ */
+export const R2_PAGE_VFS_DEFAULTS = {
+  /** PostgreSQL default page size */
+  pageSize: 8192,
+  /** Maximum concurrent R2 operations */
+  concurrencyLimit: 10,
+  /** R2 operation timeout */
+  timeoutMs: 30000,
+  /** Retry count for transient errors */
+  retryCount: 3,
+  /** Default circuit breaker configuration */
+  circuitBreaker: {
+    failureThreshold: 5,
+    resetTimeoutMs: 30000,
+  } as CircuitBreakerConfig,
+} as const
+
+// =============================================================================
+// IMPLEMENTATION
+// =============================================================================
+
+/**
+ * Simple circuit breaker implementation
+ *
+ * Protects against cascading failures by tracking R2 failures and temporarily
+ * blocking requests when the failure rate exceeds a threshold.
+ *
+ * States:
+ * - closed: Normal operation, all requests pass through
+ * - open: Circuit is tripped, requests fail fast without hitting R2
+ * - half-open: After reset timeout, allows one request through to test recovery
+ */
+class CircuitBreaker {
+  private failures = 0
+  private lastFailureTime = 0
+  private state: 'closed' | 'open' | 'half-open' = 'closed'
+  private trips = 0
+
+  constructor(
+    private readonly failureThreshold: number,
+    private readonly resetTimeoutMs: number
+  ) {}
+
+  /**
+   * Check if a request can be executed
+   * @returns true if the circuit allows the request, false if open
+   */
+  canExecute(): boolean {
+    if (this.state === 'closed') return true
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailureTime >= this.resetTimeoutMs) {
+        this.state = 'half-open'
+        return true
+      }
+      return false
+    }
+    // half-open: allow one request through to test recovery
+    return true
+  }
+
+  /**
+   * Record a successful operation, resetting the circuit if needed
+   */
+  recordSuccess(): void {
+    this.failures = 0
+    this.state = 'closed'
+  }
+
+  /**
+   * Record a failed operation, potentially tripping the circuit
+   */
+  recordFailure(): void {
+    this.failures++
+    this.lastFailureTime = Date.now()
+    if (this.failures >= this.failureThreshold) {
+      if (this.state !== 'open') {
+        this.trips++
+      }
+      this.state = 'open'
+    }
+  }
+
+  /**
+   * Get the current circuit state
+   */
+  getState(): 'closed' | 'open' | 'half-open' {
+    // Re-check if we should transition to half-open when queried
+    if (this.state === 'open' && Date.now() - this.lastFailureTime >= this.resetTimeoutMs) {
+      this.state = 'half-open'
+    }
+    return this.state
+  }
+
+  /**
+   * Get the number of times the circuit has tripped
+   */
+  getTrips(): number {
+    return this.trips
+  }
+
+  /**
+   * Reset the circuit breaker to initial state
+   */
+  reset(): void {
+    this.failures = 0
+    this.lastFailureTime = 0
+    this.state = 'closed'
+    this.trips = 0
+  }
+}
+
+/**
+ * Internal stats tracking for latency averaging
+ */
+interface InternalStats extends R2PageVFSStats {
+  /** Total cache latency for averaging */
+  totalCacheLatencyMs: number
+  /** Number of cache operations for averaging */
+  cacheOperationCount: number
+  /** Total R2 latency for averaging */
+  totalR2LatencyMs: number
+  /** R2 operation count for averaging */
+  r2OperationCount: number
+}
+
+/**
+ * Create initial internal stats object
+ */
+function createInternalStats(): InternalStats {
+  return {
+    ...createEmptyStats(),
+    totalCacheLatencyMs: 0,
+    cacheOperationCount: 0,
+    totalR2LatencyMs: 0,
+    r2OperationCount: 0,
+    circuitBreakerState: 'closed',
+    circuitBreakerTrips: 0,
+  }
+}
+
+/**
+ * Create an R2PageVFS instance
+ *
+ * @param config - Configuration for the VFS
+ * @returns Configured R2PageVFS instance
+ *
+ * @example
+ * ```typescript
+ * import { createR2PageVFS } from './r2-page-vfs'
+ * import { createSWRCacheLayer } from './swr-cache'
+ *
+ * const swrCache = await createSWRCacheLayer({
+ *   baseUrl: 'https://pglite.cache.local',
+ *   primaryTtlSeconds: 60,
+ *   staleTtlSeconds: 3600,
+ * })
+ *
+ * const vfs = createR2PageVFS({
+ *   bucket: env.R2_BUCKET,
+ *   prefix: 'mydb',
+ *   version: '1',
+ *   swrCache,
+ *   pageSize: 8192,
+ *   concurrencyLimit: 10,
+ * })
+ *
+ * // Read a database page
+ * const result = await vfs.readPage(42, ctx)
+ * if (result.data) {
+ *   console.log(`Page 42: ${result.data.length} bytes`)
+ *   console.log(`Cache hit: ${result.hit}, Stale: ${result.stale}`)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With circuit breaker configuration
+ * const vfs = createR2PageVFS({
+ *   bucket: env.R2_BUCKET,
+ *   prefix: 'mydb',
+ *   version: '1',
+ *   swrCache,
+ *   circuitBreaker: {
+ *     failureThreshold: 5,
+ *     resetTimeoutMs: 30000,
+ *   },
+ * })
+ * ```
+ */
+export function createR2PageVFS(config: R2PageVFSConfig): R2PageVFS {
+  // Validate configuration
+  if (config.prefix.endsWith('/')) {
+    throw new Error('Prefix must not end with a slash')
+  }
+
+  // Apply defaults
+  const resolvedConfig: Required<R2PageVFSConfig> = {
+    bucket: config.bucket,
+    prefix: config.prefix,
+    version: config.version,
+    pageSize: config.pageSize ?? R2_PAGE_VFS_DEFAULTS.pageSize,
+    swrCache: config.swrCache,
+    concurrencyLimit: config.concurrencyLimit ?? R2_PAGE_VFS_DEFAULTS.concurrencyLimit,
+    timeoutMs: config.timeoutMs ?? R2_PAGE_VFS_DEFAULTS.timeoutMs,
+    retryCount: config.retryCount ?? R2_PAGE_VFS_DEFAULTS.retryCount,
+    circuitBreaker: config.circuitBreaker ?? R2_PAGE_VFS_DEFAULTS.circuitBreaker,
+  }
+
+  // Internal state
+  let stats = createInternalStats()
+
+  // Circuit breaker for R2 failure protection
+  let circuitBreaker = new CircuitBreaker(
+    resolvedConfig.circuitBreaker.failureThreshold,
+    resolvedConfig.circuitBreaker.resetTimeoutMs
+  )
+
+  // Singleflight: track in-flight R2 requests to deduplicate concurrent fetches
+  const inFlight = new Map<number, Promise<Uint8Array | null>>()
+
+  /**
+   * Wire the origin fetcher to the SWR cache layer
+   * This allows SWR to call back to R2 for background revalidation
+   */
+  config.swrCache.setOriginFetcher(async (cacheKey: string) => {
+    // Parse page number from cache key: page-v{version}-{pageNumber}
+    const match = cacheKey.match(/^page-v[^-]+-(\d{8})$/)
+    const pageStr = match?.[1]
+    if (!pageStr) {
+      return null
+    }
+    const pageNumber = parseInt(pageStr, 10)
+    const r2Key = buildR2Key(resolvedConfig.prefix, resolvedConfig.version, pageNumber)
+
+    try {
+      const r2Object = await resolvedConfig.bucket.get(r2Key)
+      if (!r2Object) {
+        return null
+      }
+      const buffer = await r2Object.arrayBuffer()
+      return new Uint8Array(buffer)
+    } catch {
+      return null
+    }
+  })
+
+  /**
+   * Fetch a page from R2 with retry logic and circuit breaker protection
+   */
+  async function fetchFromR2WithRetry(pageNumber: number): Promise<Uint8Array | null> {
+    const r2Key = buildR2Key(resolvedConfig.prefix, resolvedConfig.version, pageNumber)
+
+    // Check circuit breaker before attempting R2 fetch
+    if (!circuitBreaker.canExecute()) {
+      stats.r2Errors++
+      stats.errors++
+      throw new Error('Circuit breaker is open - R2 requests are blocked')
+    }
+
+    let lastError: Error | null = null
+    for (let attempt = 0; attempt < resolvedConfig.retryCount; attempt++) {
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+      try {
+        const r2Object = await Promise.race([
+          resolvedConfig.bucket.get(r2Key),
+          new Promise<never>((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error('R2 operation timed out')), resolvedConfig.timeoutMs)
+          }),
+        ])
+        clearTimeout(timeoutId)
+
+        if (!r2Object) {
+          // Not finding an object is not a failure - circuit breaker records success
+          circuitBreaker.recordSuccess()
+          return null
+        }
+
+        const buffer = await r2Object.arrayBuffer()
+        const data = new Uint8Array(buffer)
+
+        // Validate page size - partial pages are an error
+        if (data.length !== resolvedConfig.pageSize && data.length > 0) {
+          throw new Error(`Invalid page size: expected ${resolvedConfig.pageSize}, got ${data.length}`)
+        }
+
+        // Success - record with circuit breaker
+        circuitBreaker.recordSuccess()
+        return data
+      } catch (error) {
+        clearTimeout(timeoutId)
+        lastError = error instanceof Error ? error : new Error(String(error))
+        // Don't retry on timeout or non-retryable errors
+        if (lastError.message.includes('timed out') || lastError.message.includes('Invalid page size')) {
+          break
+        }
+        // Exponential backoff for retries
+        if (attempt < resolvedConfig.retryCount - 1) {
+          await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 100))
+        }
+      }
+    }
+
+    // Record failure with circuit breaker
+    circuitBreaker.recordFailure()
+    stats.r2Errors++
+    stats.errors++
+    if (lastError) {
+      throw lastError
+    }
+    return null
+  }
+
+  /**
+   * Read a single page with caching
+   */
+  async function readPage(pageNumber: number, ctx?: ExecutionContext): Promise<PageReadResult> {
+    // Validate page number
+    if (!Number.isInteger(pageNumber) || pageNumber < 0) {
+      throw new Error(`Invalid page number: ${pageNumber}. Must be non-negative integer.`)
+    }
+    if (pageNumber > 99999999) {
+      throw new Error(`Page number ${pageNumber} exceeds maximum of 99999999`)
+    }
+
+    const startTime = performance.now()
+    const cacheKey = buildCacheKey(resolvedConfig.version, pageNumber)
+
+    // Try cache first
+    try {
+      const cacheResult = await config.swrCache.get(cacheKey, ctx)
+
+      if (cacheResult.hit && cacheResult.data) {
+        const latencyMs = performance.now() - startTime
+        const dataLength = cacheResult.data.length
+
+        // Update stats
+        stats.bytesRead += dataLength
+        stats.bytesFromCache += dataLength
+        stats.totalCacheLatencyMs += latencyMs
+        stats.cacheOperationCount++
+
+        if (cacheResult.stale) {
+          stats.staleCacheHits++
+          if (cacheResult.revalidating) {
+            stats.backgroundRevalidations++
+          }
+          return {
+            data: cacheResult.data,
+            hit: true,
+            stale: true,
+            source: 'stale-cache',
+            latencyMs,
+          }
+        } else {
+          stats.primaryCacheHits++
+          return {
+            data: cacheResult.data,
+            hit: true,
+            stale: false,
+            source: 'primary-cache',
+            latencyMs,
+          }
+        }
+      }
+    } catch {
+      // Cache error - fall through to R2
+      stats.errors++
+    }
+
+    // Cache miss - fetch from R2
+    stats.cacheMisses++
+
+    // Singleflight: check if there's already an in-flight request for this page
+    const existingRequest = inFlight.get(pageNumber)
+    if (existingRequest) {
+      stats.deduplicatedRequests++
+      try {
+        const data = await existingRequest
+        const totalLatencyMs = performance.now() - startTime
+        if (data) {
+          stats.bytesRead += data.length
+          // Note: bytesFromR2 not incremented since another request fetched it
+          return {
+            data,
+            hit: false,
+            stale: false,
+            source: 'r2', // Was fetched by another request
+            latencyMs: totalLatencyMs,
+          }
+        } else {
+          return {
+            data: null,
+            hit: false,
+            stale: false,
+            source: 'miss',
+            latencyMs: totalLatencyMs,
+          }
+        }
+      } catch {
+        // Original request failed, we'll try our own fetch below
+      }
+    }
+
+    const r2StartTime = performance.now()
+
+    // Start our own fetch and register it in the singleflight map
+    const fetchPromise = fetchFromR2WithRetry(pageNumber)
+    inFlight.set(pageNumber, fetchPromise)
+
+    try {
+      stats.r2Reads++
+      const data = await fetchPromise
+      const r2LatencyMs = performance.now() - r2StartTime
+      const totalLatencyMs = performance.now() - startTime
+
+      stats.totalR2LatencyMs += r2LatencyMs
+      stats.r2OperationCount++
+
+      if (data) {
+        stats.bytesRead += data.length
+        stats.bytesFromR2 += data.length
+
+        // Populate cache with fetched data
+        try {
+          await config.swrCache.put(cacheKey, data)
+        } catch {
+          // Cache write error - non-fatal
+          stats.errors++
+        }
+
+        return {
+          data,
+          hit: false,
+          stale: false,
+          source: 'r2',
+          latencyMs: totalLatencyMs,
+        }
+      } else {
+        return {
+          data: null,
+          hit: false,
+          stale: false,
+          source: 'miss',
+          latencyMs: totalLatencyMs,
+        }
+      }
+    } catch (error) {
+      const totalLatencyMs = performance.now() - startTime
+      // R2 error already counted in fetchFromR2WithRetry
+      // Propagate fatal errors
+      if (error instanceof Error &&
+          (error.message.includes('timed out') || error.message.includes('Invalid page size'))) {
+        throw error
+      }
+      // Return null for network errors
+      return {
+        data: null,
+        hit: false,
+        stale: false,
+        source: 'miss',
+        latencyMs: totalLatencyMs,
+      }
+    } finally {
+      // Clean up the in-flight map
+      inFlight.delete(pageNumber)
+    }
+  }
+
+  /**
+   * Read multiple pages with concurrency control
+   */
+  async function readPages(pageNumbers: number[], ctx?: ExecutionContext): Promise<BatchPageResult> {
+    const startTime = performance.now()
+    stats.batchOperations++
+
+    // Deduplicate page numbers while preserving order
+    const uniquePages = [...new Set(pageNumbers)]
+    const pages = new Map<number, PageReadResult>()
+
+    let cacheHits = 0
+    let r2Reads = 0
+
+    // Process pages with concurrency control
+    const results: Array<{ pageNumber: number; result: PageReadResult }> = []
+
+    // Process in batches based on concurrency limit
+    for (let i = 0; i < uniquePages.length; i += resolvedConfig.concurrencyLimit) {
+      const batch = uniquePages.slice(i, i + resolvedConfig.concurrencyLimit)
+      const batchResults = await Promise.all(
+        batch.map(async (pageNumber) => {
+          const result = await readPage(pageNumber, ctx)
+          return { pageNumber, result }
+        })
+      )
+      results.push(...batchResults)
+    }
+
+    // Build the result map in original request order
+    for (const { pageNumber, result } of results) {
+      pages.set(pageNumber, result)
+      if (result.hit) {
+        cacheHits++
+      }
+      if (result.source === 'r2') {
+        r2Reads++
+      }
+    }
+
+    const totalLatencyMs = performance.now() - startTime
+
+    return {
+      pages,
+      totalLatencyMs,
+      cacheHits,
+      r2Reads,
+    }
+  }
+
+  /**
+   * Get the latest version from R2 metadata
+   */
+  async function getLatestVersion(): Promise<string> {
+    const versionKey = `${resolvedConfig.prefix}/version`
+
+    try {
+      const r2Object = await resolvedConfig.bucket.get(versionKey)
+      if (!r2Object) {
+        throw new Error('Version file not found in R2')
+      }
+      const text = await r2Object.text()
+      return text.trim()
+    } catch (error) {
+      stats.r2Errors++
+      stats.errors++
+      throw error
+    }
+  }
+
+  /**
+   * Check if current version matches latest
+   */
+  async function isVersionCurrent(): Promise<boolean> {
+    try {
+      const latestVersion = await getLatestVersion()
+      return latestVersion === resolvedConfig.version
+    } catch {
+      // If we can't get the latest version, assume current is not current
+      return false
+    }
+  }
+
+  /**
+   * Invalidate all cached pages for the current version
+   */
+  async function invalidateCache(): Promise<void> {
+    // List all pages in R2 for this version and invalidate their cache entries
+    const prefix = `${resolvedConfig.prefix}/v${resolvedConfig.version}/pages/`
+
+    try {
+      let cursor: string | undefined
+      do {
+        // Build list options without undefined values for exactOptionalPropertyTypes
+        const listOptions: { prefix: string; cursor?: string } = { prefix }
+        if (cursor !== undefined) {
+          listOptions.cursor = cursor
+        }
+        const listResult = await resolvedConfig.bucket.list(listOptions)
+
+        // Invalidate each page's cache entry
+        await Promise.all(
+          listResult.objects.map(async (obj) => {
+            const pageNumber = parsePageNumber(obj.key)
+            if (pageNumber !== null) {
+              const cacheKey = buildCacheKey(resolvedConfig.version, pageNumber)
+              await config.swrCache.invalidate(cacheKey)
+            }
+          })
+        )
+
+        cursor = listResult.truncated ? listResult.cursor : undefined
+      } while (cursor)
+    } catch {
+      stats.errors++
+    }
+  }
+
+  /**
+   * Invalidate a specific page from cache
+   */
+  async function invalidatePage(pageNumber: number): Promise<void> {
+    const cacheKey = buildCacheKey(resolvedConfig.version, pageNumber)
+    try {
+      await config.swrCache.invalidate(cacheKey)
+    } catch {
+      stats.errors++
+    }
+  }
+
+  /**
+   * Invalidate a range of pages from cache
+   * Includes safeguards against unbounded memory growth from large ranges
+   */
+  async function invalidatePages(startPage: number, endPage: number): Promise<void> {
+    const MAX_RANGE = 100000
+    const BATCH_SIZE = 1000
+    const pageCount = endPage - startPage + 1
+
+    if (pageCount > MAX_RANGE) {
+      throw new Error(`Page range too large: ${pageCount}. Maximum allowed: ${MAX_RANGE}`)
+    }
+
+    // Process in batches to avoid creating too many promises at once
+    for (let i = startPage; i <= endPage; i += BATCH_SIZE) {
+      const batchEnd = Math.min(i + BATCH_SIZE - 1, endPage)
+      const promises: Promise<void>[] = []
+      for (let pageNumber = i; pageNumber <= batchEnd; pageNumber++) {
+        promises.push(invalidatePage(pageNumber))
+      }
+      await Promise.all(promises)
+    }
+  }
+
+  /**
+   * Get current statistics
+   */
+  function getStats(): R2PageVFSStats {
+    const totalReads = stats.primaryCacheHits + stats.staleCacheHits + stats.cacheMisses
+
+    return {
+      primaryCacheHits: stats.primaryCacheHits,
+      staleCacheHits: stats.staleCacheHits,
+      cacheMisses: stats.cacheMisses,
+      r2Reads: stats.r2Reads,
+      r2Errors: stats.r2Errors,
+      bytesRead: stats.bytesRead,
+      bytesFromCache: stats.bytesFromCache,
+      bytesFromR2: stats.bytesFromR2,
+      batchOperations: stats.batchOperations,
+      backgroundRevalidations: stats.backgroundRevalidations,
+      deduplicatedRequests: stats.deduplicatedRequests,
+      cacheHitRatio: totalReads > 0
+        ? (stats.primaryCacheHits + stats.staleCacheHits) / totalReads
+        : 0,
+      avgCacheLatencyMs: stats.cacheOperationCount > 0
+        ? stats.totalCacheLatencyMs / stats.cacheOperationCount
+        : 0,
+      avgR2LatencyMs: stats.r2OperationCount > 0
+        ? stats.totalR2LatencyMs / stats.r2OperationCount
+        : 0,
+      errors: stats.errors,
+      circuitBreakerState: circuitBreaker.getState(),
+      circuitBreakerTrips: circuitBreaker.getTrips(),
+    }
+  }
+
+  /**
+   * Reset all statistics
+   */
+  function resetStats(): void {
+    stats = createInternalStats()
+    circuitBreaker.reset()
+  }
+
+  /**
+   * Get current configuration
+   */
+  function getConfig(): Required<R2PageVFSConfig> {
+    return { ...resolvedConfig }
+  }
+
+  return {
+    readPage,
+    readPages,
+    getLatestVersion,
+    isVersionCurrent,
+    invalidateCache,
+    invalidatePage,
+    invalidatePages,
+    getStats,
+    resetStats,
+    getConfig,
+  }
+}