@od-oneapp/storage 2026.1.1301

package/src/health-check.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Health check utilities for storage providers
+ *
+ * Provides health check functionality to verify storage provider availability
+ * and performance. Useful for monitoring and alerting.
+ *
+ * @module @repo/storage/health-check
+ */
+
+import type { StorageProvider } from '../types';
+
+/**
+ * Health check result with status and metrics
+ */
+export interface HealthCheckResult {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  latencyMs: number;
+  error?: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Check the health of a storage provider
+ *
+ * @param provider - The storage provider to check
+ * @returns Health check result with status and latency
+ */
+export async function checkProviderHealth(provider: StorageProvider): Promise<HealthCheckResult> {
+  const startTime = Date.now();
+
+  try {
+    // Perform a lightweight operation to check provider health
+    // Using list with limit 1 as a health check probe
+    await provider.list({ limit: 1 });
+
+    const latencyMs = Date.now() - startTime;
+
+    // Define health thresholds
+    const HEALTHY_THRESHOLD_MS = 1000; // < 1s is healthy
+    const DEGRADED_THRESHOLD_MS = 3000; // 1-3s is degraded
+
+    let status: 'healthy' | 'degraded' | 'unhealthy';
+    if (latencyMs < HEALTHY_THRESHOLD_MS) {
+      status = 'healthy';
+    } else if (latencyMs < DEGRADED_THRESHOLD_MS) {
+      status = 'degraded';
+    } else {
+      status = 'unhealthy';
+    }
+
+    return {
+      status,
+      latencyMs,
+      details: {
+        provider: provider.constructor.name,
+        threshold_healthy_ms: HEALTHY_THRESHOLD_MS,
+        threshold_degraded_ms: DEGRADED_THRESHOLD_MS,
+      },
+    };
+  } catch (error) {
+    const latencyMs = Date.now() - startTime;
+    return {
+      status: 'unhealthy',
+      latencyMs,
+      error: error instanceof Error ? error.message : String(error),
+      details: {
+        provider: provider.constructor.name,
+      },
+    };
+  }
+}
+
+/**
+ * Perform a comprehensive health check on storage system
+ *
+ * @param provider - The storage provider to check
+ * @returns Detailed health check result
+ */
+export async function storageHealthCheck(provider: StorageProvider): Promise<HealthCheckResult> {
+  return checkProviderHealth(provider);
+}

package/src/multi-storage.ts

@@ -0,0 +1,230 @@
+/**
+ * @fileoverview Multi-storage provider manager
+ *
+ * Manages multiple storage providers with routing and fallback capabilities.
+ * Allows using different providers for different use cases or as backups.
+ *
+ * Features:
+ * - Provider routing based on key patterns
+ * - Fallback to default provider
+ * - Unified API across multiple providers
+ *
+ * @module @repo/storage/multi-storage
+ */
+
+import { CloudflareImagesProvider } from '../providers/cloudflare-images';
+import { CloudflareR2Provider } from '../providers/cloudflare-r2';
+import { VercelBlobProvider } from '../providers/vercel-blob';
+import {
+  type ListOptions,
+  type MultiStorageConfig,
+  type StorageConfig,
+  type StorageObject,
+  type StorageProvider,
+  type UploadOptions,
+} from '../types';
+
+export class MultiStorageManager {
+  private providers: Map<string, StorageProvider> = new Map();
+  private defaultProvider: string;
+  private routing: MultiStorageConfig['routing'];
+
+  constructor(config: MultiStorageConfig) {
+    // Initialize all providers
+    for (const [name, providerConfig] of Object.entries(config.providers)) {
+      this.providers.set(name, this.createProvider(providerConfig));
+    }
+
+    // Set default provider
+    const firstProvider = Object.keys(config.providers)[0];
+    this.defaultProvider = config.defaultProvider ?? firstProvider ?? '';
+    if (!this.defaultProvider) {
+      throw new Error('No storage providers configured');
+    }
+
+    this.routing = config.routing;
+  }
+
+  private createProvider(config: StorageConfig): StorageProvider {
+    switch (config.provider) {
+      case 'multi':
+        throw new Error('Multi provider cannot be nested');
+
+      case 'cloudflare-r2':
+        if (!config.cloudflareR2) {
+          throw new Error('Cloudflare R2 configuration is required');
+        }
+        // Handle array of R2 configs
+        if (Array.isArray(config.cloudflareR2)) {
+          if (config.cloudflareR2.length === 0) {
+            throw new Error('No R2 configurations provided');
+          }
+          const firstR2Config = config.cloudflareR2[0];
+          if (!firstR2Config) {
+            throw new Error('First R2 configuration is undefined');
+          }
+          // Use first one for single provider (backward compatibility)
+          return new CloudflareR2Provider(firstR2Config);
+        }
+        return new CloudflareR2Provider(config.cloudflareR2);
+
+      case 'cloudflare-images':
+        if (!config.cloudflareImages) {
+          throw new Error('Cloudflare Images configuration is required');
+        }
+        return new CloudflareImagesProvider(config.cloudflareImages);
+
+      case 'vercel-blob':
+        if (!config.vercelBlob?.token) {
+          throw new Error('Vercel Blob token is required');
+        }
+        return new VercelBlobProvider(config.vercelBlob.token);
+
+      default:
+        throw new Error(`Unknown storage provider: ${config.provider}`);
+    }
+  }
+
+  private getProviderForKey(key: string): { provider: StorageProvider; providerName: string } {
+    // Check routing rules
+    if (this.routing) {
+      // Check file type routing
+      const extension = key.split('.').pop()?.toLowerCase();
+
+      // Image routing
+      if (this.routing.images && this.isImageFile(extension)) {
+        const provider = this.providers.get(this.routing.images);
+        if (provider) {
+          return { provider, providerName: this.routing.images };
+        }
+      }
+
+      // Document routing
+      if (this.routing.documents && this.isDocumentFile(extension)) {
+        const provider = this.providers.get(this.routing.documents);
+        if (provider) {
+          return { provider, providerName: this.routing.documents };
+        }
+      }
+
+      // Custom routing rules
+      for (const [pattern, providerName] of Object.entries(this.routing)) {
+        if (pattern !== 'images' && pattern !== 'documents' && providerName) {
+          // Simple pattern matching (could be enhanced with regex)
+          if (key.includes(pattern)) {
+            const provider = this.providers.get(providerName);
+            if (provider) {
+              return { provider, providerName };
+            }
+          }
+        }
+      }
+    }
+
+    // Fall back to default provider
+    const provider = this.providers.get(this.defaultProvider);
+    if (!provider) {
+      throw new Error(`Default provider '${this.defaultProvider}' not found`);
+    }
+
+    return { provider, providerName: this.defaultProvider };
+  }
+
+  private isImageFile(extension?: string): boolean {
+    const imageExtensions = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'svg', 'ico'];
+    return extension ? imageExtensions.includes(extension) : false;
+  }
+
+  private isDocumentFile(extension?: string): boolean {
+    const documentExtensions = ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'txt', 'csv'];
+    return extension ? documentExtensions.includes(extension) : false;
+  }
+
+  // Get a specific provider by name
+  getProvider(name: string): StorageProvider | undefined {
+    return this.providers.get(name);
+  }
+
+  // Storage operations that route to appropriate provider
+  async delete(key: string): Promise<void> {
+    const { provider } = this.getProviderForKey(key);
+    return provider.delete(key);
+  }
+
+  async download(key: string): Promise<Blob> {
+    const { provider } = this.getProviderForKey(key);
+    return provider.download(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const { provider } = this.getProviderForKey(key);
+    return provider.exists(key);
+  }
+
+  async getMetadata(key: string): Promise<StorageObject> {
+    const { provider } = this.getProviderForKey(key);
+    return provider.getMetadata(key);
+  }
+
+  async getUrl(key: string, options?: { expiresIn?: number }): Promise<string> {
+    const { provider } = this.getProviderForKey(key);
+    return provider.getUrl(key, options);
+  }
+
+  async list(options?: ListOptions & { provider?: string }): Promise<StorageObject[]> {
+    // If specific provider requested, use it
+    if (options?.provider) {
+      const provider = this.providers.get(options.provider);
+      if (!provider) {
+        throw new Error(`Provider '${options.provider}' not found`);
+      }
+      return provider.list(options);
+    }
+
+    // Otherwise, list from all providers
+    const allResults: StorageObject[] = [];
+    for (const provider of this.providers.values()) {
+      const results = await provider.list(options);
+      allResults.push(...results);
+    }
+    return allResults;
+  }
+
+  async upload(
+    key: string,
+    data: ArrayBuffer | Blob | Buffer | File | ReadableStream,
+    options?: UploadOptions & { provider?: string },
+  ): Promise<StorageObject> {
+    let provider: StorageProvider;
+
+    // If specific provider requested, use it
+    if (options?.provider) {
+      const requestedProvider = this.providers.get(options.provider);
+      if (!requestedProvider) {
+        throw new Error(`Provider '${options.provider}' not found`);
+      }
+      provider = requestedProvider;
+    } else {
+      // Otherwise, use routing logic
+      const { provider: routedProvider } = this.getProviderForKey(key);
+      provider = routedProvider;
+    }
+
+    return provider.upload(key, data, options);
+  }
+
+  // Extended methods for Cloudflare Images
+  async getCloudflareImagesProvider(): Promise<InstanceType<typeof CloudflareImagesProvider> | undefined> {
+    for (const provider of this.providers.values()) {
+      if (provider instanceof CloudflareImagesProvider) {
+        return provider;
+      }
+    }
+    return undefined;
+  }
+
+  // Get all provider names
+  getProviderNames(): string[] {
+    return Array.from(this.providers.keys());
+  }
+}