@od-oneapp/storage 2026.1.1301

package/src/server.ts

@@ -0,0 +1,666 @@
+/**
+ * @fileoverview Server-side storage exports (non-Next.js)
+ *
+ * This file provides server-side storage functionality for non-Next.js environments.
+ * For Next.js applications, use '@repo/storage/server/next' instead.
+ *
+ * Features:
+ * - Multi-provider storage support (Vercel Blob, Cloudflare R2, Cloudflare Images)
+ * - Storage provider abstraction
+ * - Upload, download, list, and delete operations
+ * - Presigned URL generation
+ * - Multipart upload support
+ *
+ * @module @repo/storage/server
+ */
+
+import { logWarn } from '@repo/shared/logs/server/next';
+
+import { safeEnv } from '../env';
+import { CloudflareImagesProvider } from '../providers/cloudflare-images';
+import { CloudflareR2Provider } from '../providers/cloudflare-r2';
+import { VercelBlobProvider } from '../providers/vercel-blob';
+import {
+  type ListOptions,
+  type MultiStorageConfig,
+  type StorageCapabilities,
+  type StorageConfig,
+  type StorageObject,
+  type StorageProvider,
+  type StorageProviderType,
+  type UploadOptions,
+} from '../types';
+
+import { DEFAULT_STORAGE_CAPABILITIES } from './constants';
+import { MultiStorageManager } from './multi-storage';
+
+
+export { env, safeEnv } from '../env';
+export { CloudflareImagesProvider } from '../providers/cloudflare-images';
+export { CloudflareR2Provider } from '../providers/cloudflare-r2';
+export { VercelBlobProvider } from '../providers/vercel-blob';
+export * from '../types';
+export { MultiStorageManager } from './multi-storage';
+
+// Export multipart utilities
+export {
+  createMultipartUploadManager,
+  getOptimalPartSize,
+  hasMultipartSupport,
+  MultipartUploadManager,
+  type MultipartUploadResult,
+  type MultipartUploadState,
+} from './multipart';
+
+// Export validation utilities
+export {
+  ConfigError,
+  createStorageError,
+  DownloadError,
+  formatFileSize,
+  getErrorCode,
+  getQuotaInfo,
+  isQuotaExceeded,
+  isRetryableError,
+  NetworkError,
+  parseFileSize,
+  ProviderError,
+  StorageError,
+  StorageErrorCode,
+  UploadError,
+  validateFileSize,
+  validateMimeType,
+  validateStorageKey,
+  validateUploadOptions,
+  ValidationError,
+  type QuotaInfo,
+  type ValidationOptions,
+} from './validation';
+
+// Export capabilities utilities
+export {
+  checkProviderSuitability,
+  describeProviderCapabilities,
+  getBestProvider,
+  getCapabilityMatrix,
+  getProviderCapabilities,
+  hasAllCapabilities,
+  hasAnyCapability,
+  hasCapability,
+  validateProviderCapabilities,
+} from './capabilities';
+
+// Export health check utilities
+export { checkProviderHealth, storageHealthCheck } from './health-check';
+export type { HealthCheckResult } from './health-check';
+
+/**
+ * Configuration validation helpers
+ */
+
+/**
+ * Validates storage configuration and returns helpful error messages
+ * @param config - Storage configuration to validate
+ * @returns Validation result with errors if any
+ */
+export function validateStorageConfig(config: StorageConfig): {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Check provider type
+  if (!config.provider) {
+    errors.push('Storage provider is required');
+  }
+
+  // Validate provider-specific configuration
+  switch (config.provider) {
+    case 'multi':
+      errors.push('Multi provider configuration should not be validated here');
+      break;
+
+    case 'vercel-blob':
+      if (!config.vercelBlob?.token) {
+        errors.push('VERCEL_BLOB_READ_WRITE_TOKEN is required for Vercel Blob provider');
+      }
+      break;
+
+    case 'cloudflare-r2':
+      if (!config.cloudflareR2) {
+        errors.push('Cloudflare R2 configuration is required');
+      } else {
+        const r2Config = Array.isArray(config.cloudflareR2)
+          ? config.cloudflareR2[0]
+          : config.cloudflareR2;
+        if (!r2Config) {
+          errors.push('Cloudflare R2 configuration is required');
+        } else {
+          if (!r2Config.accessKeyId) {
+            errors.push('R2_ACCESS_KEY_ID is required for Cloudflare R2 provider');
+          }
+          if (!r2Config.secretAccessKey) {
+            errors.push('R2_SECRET_ACCESS_KEY is required for Cloudflare R2 provider');
+          }
+          if (!r2Config.bucket) {
+            errors.push('R2_BUCKET is required for Cloudflare R2 provider');
+          }
+          if (!r2Config.accountId) {
+            errors.push('R2_ACCOUNT_ID is required for Cloudflare R2 provider');
+          }
+        }
+      }
+      break;
+
+    case 'cloudflare-images':
+      if (!config.cloudflareImages) {
+        errors.push('Cloudflare Images configuration is required');
+      } else {
+        if (!config.cloudflareImages.accountId) {
+          errors.push('CLOUDFLARE_IMAGES_ACCOUNT_ID is required for Cloudflare Images provider');
+        }
+        if (!config.cloudflareImages.apiToken) {
+          errors.push('CLOUDFLARE_IMAGES_API_TOKEN is required for Cloudflare Images provider');
+        }
+      }
+      break;
+
+    default:
+      errors.push(`Unknown storage provider: ${config.provider}`);
+  }
+
+  // Check for common configuration issues
+  if (config.cloudflareR2 && config.cloudflareImages) {
+    warnings.push('Multiple providers configured - consider using multi-provider setup');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Determine storage provider capabilities based on the provided storage configuration.
+ *
+ * @param config - The storage configuration used to infer provider capabilities
+ * @returns A `StorageCapabilities` object describing which features the configured provider supports
+ */
+export function getProviderCapabilitiesFromConfig(config: StorageConfig): StorageCapabilities {
+  switch (config.provider) {
+    case 'multi':
+      return { ...DEFAULT_STORAGE_CAPABILITIES };
+
+    case 'vercel-blob':
+      return {
+        multipart: true,
+        presignedUrls: false,
+        progressTracking: true,
+        abortSignal: true,
+        metadata: true,
+        customDomains: true,
+        edgeCompatible: true,
+        versioning: false,
+        encryption: false,
+        directoryListing: false,
+      };
+
+    case 'cloudflare-r2':
+      return {
+        multipart: true,
+        presignedUrls: true,
+        progressTracking: false,
+        abortSignal: false,
+        metadata: true,
+        customDomains: true,
+        edgeCompatible: false,
+        versioning: false,
+        encryption: false,
+        directoryListing: false,
+      };
+
+    case 'cloudflare-images':
+      return {
+        multipart: false,
+        presignedUrls: false,
+        progressTracking: false,
+        abortSignal: false,
+        metadata: true,
+        customDomains: true,
+        edgeCompatible: false,
+        versioning: false,
+        encryption: false,
+        directoryListing: false,
+      };
+
+    default:
+      return {
+        multipart: false,
+        presignedUrls: false,
+        progressTracking: false,
+        abortSignal: false,
+        metadata: false,
+        customDomains: false,
+        edgeCompatible: false,
+        versioning: false,
+        encryption: false,
+        directoryListing: false,
+      };
+  }
+}
+
+/**
+ * Create a StorageProvider instance based on the provided StorageConfig.
+ *
+ * @param config - Storage configuration specifying `provider` and the provider-specific settings required to instantiate that provider
+ * @returns The instantiated StorageProvider corresponding to `config.provider`
+ * @throws Error if the chosen provider's configuration is missing or incomplete, if a `cloudflare-r2` array is empty, or if `provider` is unrecognized
+ */
+export function createStorageProvider(config: StorageConfig): StorageProvider {
+  switch (config.provider) {
+    case 'multi':
+      throw new Error('Multi provider should be created via MultiStorageManager');
+
+    case 'cloudflare-r2':
+      if (!config.cloudflareR2) {
+        throw new Error('Storage provider configuration is incomplete');
+      }
+      // Support single R2 config
+      if (!Array.isArray(config.cloudflareR2)) {
+        return new CloudflareR2Provider(config.cloudflareR2);
+      }
+      // For array, use first one (backward compatibility)
+      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');
+      }
+      return new CloudflareR2Provider(firstR2Config);
+
+    case 'cloudflare-images':
+      if (!config.cloudflareImages) {
+        throw new Error('Storage provider configuration is incomplete');
+      }
+      return new CloudflareImagesProvider(config.cloudflareImages);
+
+    case 'vercel-blob':
+      if (!config.vercelBlob?.token) {
+        throw new Error('Storage provider configuration is incomplete');
+      }
+      return new VercelBlobProvider(config.vercelBlob.token);
+
+    default:
+      throw new Error(`Unknown storage provider: ${config.provider}`);
+  }
+}
+
+// Singleton storage instance
+let storageInstance: MultiStorageManager | null | StorageProvider = null;
+let hasLoggedWarning = false;
+let multiStorageInstance: MultiStorageManager | null = null;
+
+/**
+ * Test helper to reset singleton state
+ * @internal
+ */
+export function resetStorageState(): void {
+  storageInstance = null;
+  multiStorageInstance = null;
+  hasLoggedWarning = false;
+}
+
+// Mock storage provider for development
+class MockStorageProvider implements StorageProvider {
+  private storage = new Map<
+    string,
+    { data: ArrayBuffer | Blob | Buffer | File | ReadableStream; metadata: StorageObject }
+  >();
+
+  async delete(key: string): Promise<void> {
+    this.storage.delete(key);
+  }
+
+  async download(_key: string): Promise<Blob> {
+    return new Blob(['mock data'], { type: 'text/plain' });
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return this.storage.has(key);
+  }
+
+  async getMetadata(key: string): Promise<StorageObject> {
+    const item = this.storage.get(key);
+    if (!item) {
+      throw new Error(`Object with key ${key} not found`);
+    }
+    return item.metadata;
+  }
+
+  async getUrl(key: string, _options?: { expiresIn?: number }): Promise<string> {
+    return `https://mock-storage.example.com/${key}`;
+  }
+
+  async list(_options?: ListOptions): Promise<StorageObject[]> {
+    return Array.from(this.storage.values()).map(item => item.metadata);
+  }
+
+  async upload(
+    key: string,
+    data: ArrayBuffer | Blob | Buffer | File | ReadableStream,
+    options?: UploadOptions,
+  ): Promise<StorageObject> {
+    const mockObject: StorageObject = {
+      contentType: options?.contentType ?? 'application/octet-stream',
+      key,
+      lastModified: new Date(),
+      size: data instanceof Buffer ? data.length : 1024,
+      url: `https://mock-storage.example.com/${key}`,
+    };
+    this.storage.set(key, { data, metadata: mockObject });
+    return mockObject;
+  }
+}
+
+/**
+ * Return the configured StorageProvider, initializing it on first access if needed.
+ *
+ * @returns The configured StorageProvider; a mock provider when no real provider is configured
+ */
+export function getStorage(): StorageProvider {
+  if (!storageInstance) {
+    return initializeStorage();
+  }
+  return storageInstance;
+}
+
+/**
+ * Initialize and return the application's storage provider from environment configuration.
+ *
+ * Builds a StorageConfig from environment variables, validates it, and instantiates the corresponding StorageProvider. If no provider is configured, a MockStorageProvider is returned.
+ *
+ * @returns The instantiated StorageProvider (a MockStorageProvider when no provider is configured).
+ * @throws Error when required provider environment variables are missing (message: "Storage provider configuration is incomplete").
+ * @throws Error when configuration validation fails (message: "Storage configuration validation failed: <errors>").
+ */
+export function initializeStorage(): StorageProvider {
+  if (storageInstance) {
+    return storageInstance;
+  }
+
+  const env = safeEnv();
+  const provider = env.STORAGE_PROVIDER;
+
+  // Return mock provider if no provider is configured
+  if (!provider) {
+    if (!hasLoggedWarning) {
+      // Storage service runs in mock mode when not configured
+      hasLoggedWarning = true;
+    }
+    storageInstance = new MockStorageProvider();
+    return storageInstance;
+  }
+
+  const config: StorageConfig = {
+    provider: provider as StorageProviderType,
+  };
+
+  // Configure based on provider
+  switch (provider) {
+    case 'multi':
+      throw new Error('Multi provider configuration not supported in getStorage()');
+
+    case 'cloudflare-images':
+      throw new Error('Cloudflare Images provider not supported as primary storage provider');
+
+    case 'cloudflare-r2': {
+      if (
+        !env.R2_ACCOUNT_ID ||
+        !env.R2_ACCESS_KEY_ID ||
+        !env.R2_SECRET_ACCESS_KEY ||
+        !env.R2_BUCKET
+      ) {
+        throw new Error('Storage provider configuration is incomplete');
+      }
+      config.cloudflareR2 = {
+        accessKeyId: env.R2_ACCESS_KEY_ID,
+        accountId: env.R2_ACCOUNT_ID,
+        bucket: env.R2_BUCKET,
+        secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+      };
+      break;
+    }
+    case 'vercel-blob': {
+      if (!env.VERCEL_BLOB_READ_WRITE_TOKEN) {
+        throw new Error('Storage provider configuration is incomplete');
+      }
+      config.vercelBlob = {
+        token: env.VERCEL_BLOB_READ_WRITE_TOKEN,
+      };
+      break;
+    }
+  }
+
+  // Validate configuration before creating provider
+  const validation = validateStorageConfig(config);
+  if (!validation.valid) {
+    throw new Error(`Storage configuration validation failed: ${validation.errors.join(', ')}`);
+  }
+
+  // Log warnings if any
+  if (validation.warnings.length > 0) {
+    logWarn('Storage configuration warnings:', {
+      warnings: validation.warnings,
+      provider: config.provider,
+    });
+  }
+
+  storageInstance = createStorageProvider(config);
+  return storageInstance;
+}
+
+/**
+ * Initialize multi-storage manager with environment variables
+ * @returns Configured multi-storage manager instance
+ */
+export function initializeMultiStorage(): MultiStorageManager {
+  if (multiStorageInstance) {
+    return multiStorageInstance;
+  }
+
+  const env = safeEnv();
+
+  // Check if we have a full storage config JSON
+  if (env.STORAGE_CONFIG) {
+    const config =
+      typeof env.STORAGE_CONFIG === 'string' ? JSON.parse(env.STORAGE_CONFIG) : env.STORAGE_CONFIG;
+    multiStorageInstance = new MultiStorageManager(config);
+    return multiStorageInstance;
+  }
+
+  // Build config from individual env vars
+  const config: MultiStorageConfig = {
+    providers: {},
+  };
+
+  // Add R2 providers from JSON array
+  if (env.R2_CREDENTIALS && Array.isArray(env.R2_CREDENTIALS)) {
+    const r2Configs = env.R2_CREDENTIALS;
+    r2Configs.forEach((r2Config, index: number) => {
+      const name = r2Config.name ?? `r2-${index}`;
+      config.providers[name] = {
+        provider: 'cloudflare-r2',
+        cloudflareR2: r2Config,
+      };
+    });
+  }
+
+  // Add legacy R2 config if present
+  if (env.R2_ACCESS_KEY_ID && env.R2_SECRET_ACCESS_KEY && env.R2_BUCKET && env.R2_ACCOUNT_ID) {
+    config.providers['r2-legacy'] = {
+      provider: 'cloudflare-r2',
+      cloudflareR2: {
+        accessKeyId: env.R2_ACCESS_KEY_ID,
+        accountId: env.R2_ACCOUNT_ID,
+        bucket: env.R2_BUCKET,
+        secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+      },
+    };
+  }
+
+  // Add Cloudflare Images if configured
+  if (env.CLOUDFLARE_IMAGES_API_TOKEN && env.CLOUDFLARE_IMAGES_ACCOUNT_ID) {
+    config.providers['images'] = {
+      provider: 'cloudflare-images',
+      cloudflareImages: {
+        accountId: env.CLOUDFLARE_IMAGES_ACCOUNT_ID,
+        apiToken: env.CLOUDFLARE_IMAGES_API_TOKEN,
+        deliveryUrl: env.CLOUDFLARE_IMAGES_DELIVERY_URL,
+        signingKey: env.CLOUDFLARE_IMAGES_SIGNING_KEY,
+      },
+    };
+  }
+
+  // Add Vercel Blob if configured
+  if (env.VERCEL_BLOB_READ_WRITE_TOKEN) {
+    config.providers['blob'] = {
+      provider: 'vercel-blob',
+      vercelBlob: {
+        token: env.VERCEL_BLOB_READ_WRITE_TOKEN,
+      },
+    };
+  }
+
+  // Set up routing
+  config.routing = {
+    images: 'images', // Route image files to Cloudflare Images if available
+    documents: config.providers['r2-0'] ? 'r2-0' : 'r2-legacy', // Route documents to first R2
+  };
+
+  if (Object.keys(config.providers).length === 0) {
+    // Return mock multi-storage
+    config.providers['mock'] = {
+      provider: 'vercel-blob', // Using mock provider
+      vercelBlob: { token: 'mock' },
+    };
+    multiStorageInstance = new MultiStorageManager(config);
+
+    if (!hasLoggedWarning) {
+      // Multi-storage service runs in mock mode when not configured
+      hasLoggedWarning = true;
+    }
+    return multiStorageInstance;
+  }
+
+  multiStorageInstance = new MultiStorageManager(config);
+  return multiStorageInstance;
+}
+
+/**
+ * Get multi-storage manager instance with lazy initialization
+ * @returns Multi-storage manager instance
+ */
+export function getMultiStorage(): MultiStorageManager {
+  if (!multiStorageInstance) {
+    return initializeMultiStorage();
+  }
+  return multiStorageInstance;
+}
+
+/**
+ * Helper functions for common storage operations
+ * Provides direct access to the primary storage provider methods
+ */
+export const storage = {
+  delete: (key: string) => getStorage().delete(key),
+  download: (key: string) => getStorage().download(key),
+  exists: (key: string) => getStorage().exists(key),
+  getMetadata: (key: string) => getStorage().getMetadata(key),
+  getUrl: (key: string, options?: { expiresIn?: number }) => getStorage().getUrl(key, options),
+  list: (options?: ListOptions) => getStorage().list(options),
+  upload: (
+    key: string,
+    data: ArrayBuffer | Blob | Buffer | File | ReadableStream,
+    options?: UploadOptions,
+  ) => getStorage().upload(key, data, options),
+
+  // Multipart upload helpers
+  createMultipartUpload: (key: string, options?: UploadOptions) => {
+    const provider = getStorage();
+    if (!provider.createMultipartUpload) {
+      throw new Error('Provider does not support multipart uploads');
+    }
+    return provider.createMultipartUpload(key, options);
+  },
+
+  uploadPart: (
+    uploadId: string,
+    partNumber: number,
+    data: ArrayBuffer | Blob | Buffer,
+    options?: UploadOptions,
+  ) => {
+    const provider = getStorage();
+    if (!provider.uploadPart) {
+      throw new Error('Provider does not support multipart uploads');
+    }
+    return provider.uploadPart(uploadId, partNumber, data, options);
+  },
+
+  completeMultipartUpload: (
+    uploadId: string,
+    parts: Array<{ etag: string; partNumber: number }>,
+  ) => {
+    const provider = getStorage();
+    if (!provider.completeMultipartUpload) {
+      throw new Error('Provider does not support multipart uploads');
+    }
+    return provider.completeMultipartUpload(uploadId, parts);
+  },
+
+  abortMultipartUpload: (uploadId: string) => {
+    const provider = getStorage();
+    if (!provider.abortMultipartUpload) {
+      throw new Error('Provider does not support multipart uploads');
+    }
+    return provider.abortMultipartUpload(uploadId);
+  },
+
+  // Presigned URL helper
+  getPresignedUploadUrl: (key: string, options?: { expiresIn?: number; contentType?: string }) => {
+    const provider = getStorage();
+    if (!provider.getPresignedUploadUrl) {
+      throw new Error('Provider does not support presigned URLs');
+    }
+    return provider.getPresignedUploadUrl(key, options);
+  },
+
+  // Capabilities helper
+  getCapabilities: () => {
+    const provider = getStorage();
+    return provider.getCapabilities?.() ?? { ...DEFAULT_STORAGE_CAPABILITIES };
+  },
+};
+
+/**
+ * Multi-storage helper functions
+ * Provides access to multi-storage manager methods with automatic routing
+ */
+export const multiStorage = {
+  delete: (key: string) => getMultiStorage().delete(key),
+  download: (key: string) => getMultiStorage().download(key),
+  exists: (key: string) => getMultiStorage().exists(key),
+  getMetadata: (key: string) => getMultiStorage().getMetadata(key),
+  getProvider: (name: string) => getMultiStorage().getProvider(name),
+  getProviderNames: () => getMultiStorage().getProviderNames(),
+  getUrl: (key: string, options?: { expiresIn?: number }) => getMultiStorage().getUrl(key, options),
+  list: (options?: ListOptions & { provider?: string }) => getMultiStorage().list(options),
+  upload: (
+    key: string,
+    data: ArrayBuffer | Blob | Buffer | File | ReadableStream,
+    options?: UploadOptions & { provider?: string },
+  ) => getMultiStorage().upload(key, data, options),
+};