@wildo-ai/saas-backend-lib 1.0.1

package/src/files/storage/file-storage-path-resolver.backend.service.ts

@@ -0,0 +1,289 @@
+/**
+ * File Storage Path Resolver
+ *
+ * Composes `StorageUploadOptions` from `z_file()` `FilePathBinding` metadata
+ * and an optional resource instance.
+ *
+ * This service is the single place that evaluates the declarative
+ * `FilePathBinding` (authored in schema code) into the concrete
+ * folder path + file name the storage provider will use.
+ *
+ * When nothing is configured, returns `undefined` — the provider
+ * falls back to the legacy `{fileId}` key behavior.
+ */
+
+import { injectable, inject } from 'inversify';
+import type { FileSchemaMetadata, FilePathBinding, FilePathBindingContext, FileMultipleFilePolicy } from '@wildo-ai/zod-decorators';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { StorageUploadOptions } from './file-storage-provider.types';
+
+const DEFAULT_MULTIPLE_TEMPLATE = '{field}_{ts}_{uuid}.{ext}';
+
+@injectable()
+export class FileStoragePathResolverBackendService {
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger)
+    private readonly logger: LoggerService,
+  ) {
+    this.logDebug = this.logger.debugByType('FileStoragePathResolverBackendService');
+    this.logger.setDebugTypeLogging('FileStoragePathResolverBackendService', false);
+  }
+
+  /**
+   * Resolve `StorageUploadOptions` from field metadata and optional resource context.
+   *
+   * @param fileId             - Unique file identifier (UUID)
+   * @param fieldName          - The z_file field name (e.g. 'personna', 'avatar')
+   * @param fileMetadata       - `FileSchemaMetadata` from z_file() field detection
+   * @param applicationId      - Application identifier from execution context
+   * @param originalFileName   - Original uploaded filename (for extension / template)
+   * @param resourceInstance   - Optional parent resource object
+   */
+  resolve(
+    fileId: string,
+    fieldName: string,
+    fileMetadata: FileSchemaMetadata,
+    applicationId: string,
+    originalFileName?: string,
+    resourceInstance?: Record<string, unknown>,
+  ): StorageUploadOptions | undefined {
+    const binding = fileMetadata.filePathBinding;
+    if (!binding) {
+      return undefined;
+    }
+
+    const ctx: FilePathBindingContext = {
+      relatedObject: resourceInstance,
+      fileMetadata,
+      applicationId,
+    };
+
+    let folderPath = this.resolveFolderPath(binding, ctx);
+    const resolvedFileName = this.resolveFileName(binding, fileMetadata, ctx, fileId, fieldName, originalFileName);
+
+    if (fileMetadata.multiple && binding.multipleFilePolicy) {
+      const sub = binding.multipleFilePolicy.subfolder ?? fieldName;
+      folderPath = folderPath ? `${folderPath}/${sub}` : sub;
+    }
+
+    const result: StorageUploadOptions = {};
+    if (folderPath) result.folderPath = sanitizePath(folderPath);
+    if (resolvedFileName) {
+      const sanitized = sanitizePathSegment(resolvedFileName);
+      if (sanitized !== resolvedFileName) {
+        this.logDebug('fileName was sanitized (slashes replaced with underscores)', {
+          original: resolvedFileName,
+          sanitized,
+          fieldName,
+        });
+      }
+      result.fileName = sanitized;
+    }
+    if (binding.includeApplicationId !== undefined) result.includeApplicationId = binding.includeApplicationId;
+
+    if (Object.keys(result).length === 0) {
+      return undefined;
+    }
+
+    this.logDebug('Resolved storage path', {
+      fileId,
+      fieldName,
+      folderPath: result.folderPath,
+      fileName: result.fileName,
+      includeApplicationId: result.includeApplicationId,
+    });
+
+    return result;
+  }
+
+  private resolveFolderPath(binding: FilePathBinding, ctx: FilePathBindingContext): string | undefined {
+    if (!binding.folderPath) {
+      return undefined;
+    }
+
+    let raw: string | undefined;
+
+    if (typeof binding.folderPath === 'function') {
+      try {
+        raw = binding.folderPath(ctx);
+      } catch (error) {
+        this.logDebug('filePathBinding.folderPath function threw — falling back to no folder path', {
+          error: error instanceof Error ? error.message : String(error),
+          applicationId: ctx.applicationId,
+        });
+        return undefined;
+      }
+    } else {
+      raw = binding.folderPath;
+    }
+
+    const trimmed = raw?.trim();
+    return trimmed || undefined;
+  }
+
+  private resolveFileName(
+    binding: FilePathBinding,
+    fileMetadata: FileSchemaMetadata,
+    ctx: FilePathBindingContext,
+    fileId: string,
+    fieldName: string,
+    originalFileName?: string,
+  ): string | undefined {
+    if (fileMetadata.multiple) {
+      if (binding.multipleFilePolicy) {
+        return this.resolveMultipleFileName(
+          binding.multipleFilePolicy,
+          ctx,
+          fileId,
+          fieldName,
+          originalFileName,
+        );
+      }
+      // multiple: true without multipleFilePolicy — ignore static fileName to
+      // prevent all files overwriting the same path. Each file gets its fileId.
+      return undefined;
+    }
+
+    if (!binding.fileName) {
+      return undefined;
+    }
+
+    let raw: string | undefined;
+
+    if (typeof binding.fileName === 'function') {
+      try {
+        raw = binding.fileName(ctx);
+      } catch (error) {
+        this.logDebug('filePathBinding.fileName function threw — falling back to fileId', {
+          error: error instanceof Error ? error.message : String(error),
+          fieldName,
+          applicationId: ctx.applicationId,
+        });
+        return undefined;
+      }
+    } else if (binding.fileName.includes('{ext}')) {
+      const ext = originalFileName ? extractExtension(originalFileName) : '';
+      raw = binding.fileName.replace('{ext}', ext);
+    } else {
+      raw = binding.fileName;
+    }
+
+    const trimmed = raw?.trim();
+    return trimmed || undefined;
+  }
+
+  /**
+   * Resolve a multiple-file name.
+   *
+   * When `multipleFilePolicy.subfolder` is set, it is appended to the
+   * folder path instead of being part of the file name — the caller
+   * receives it via the folderPath in the final `StorageUploadOptions`.
+   *
+   * Template placeholders: {field}, {ts}, {uuid}, {ext}, {original}
+   */
+  private resolveMultipleFileName(
+    policy: FileMultipleFilePolicy,
+    ctx: FilePathBindingContext,
+    fileId: string,
+    fieldName: string,
+    originalFileName?: string,
+  ): string {
+    const template = policy.fileNameTemplate;
+
+    if (typeof template === 'function') {
+      try {
+        const result = template(ctx, { fileId, fieldName, originalFileName })?.trim();
+        return result || fileId;
+      } catch (error) {
+        this.logDebug('multipleFilePolicy.fileNameTemplate function threw — falling back to fileId', {
+          error: error instanceof Error ? error.message : String(error),
+          fieldName,
+          fileId,
+        });
+        return fileId;
+      }
+    }
+
+    const tpl = template ?? DEFAULT_MULTIPLE_TEMPLATE;
+
+    const now = new Date();
+    const ts = [
+      now.getFullYear(),
+      pad2(now.getMonth() + 1),
+      pad2(now.getDate()),
+      '_',
+      pad2(now.getHours()),
+      pad2(now.getMinutes()),
+      pad2(now.getSeconds()),
+    ].join('');
+
+    const shortUuid = fileId.replace(/-/g, '').slice(0, 8);
+    const ext = originalFileName ? extractExtension(originalFileName) : '';
+    const original = originalFileName
+      ? slugify(extractNameWithoutExtension(originalFileName))
+      : fieldName;
+
+    const resolved = tpl
+      .replace('{field}', fieldName)
+      .replace('{ts}', ts)
+      .replace('{uuid}', shortUuid)
+      .replace('{ext}', ext)
+      .replace('{original}', original);
+
+    return resolved.trim() || fileId;
+  }
+}
+
+function pad2(n: number): string {
+  return n < 10 ? '0' + n : String(n);
+}
+
+function extractExtension(filename: string): string {
+  const dotIndex = filename.lastIndexOf('.');
+  if (dotIndex < 1) return '';
+  return filename.slice(dotIndex + 1).toLowerCase();
+}
+
+function extractNameWithoutExtension(filename: string): string {
+  const dotIndex = filename.lastIndexOf('.');
+  if (dotIndex < 1) return filename;
+  return filename.slice(0, dotIndex);
+}
+
+/**
+ * Convert a string to a filesystem-safe slug.
+ * Exported for use in `filePathBinding.folderPath` resolver functions.
+ */
+export function slugify(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+}
+
+/**
+ * Sanitize a full path (may contain forward slashes).
+ * Strips leading/trailing slashes and whitespace, collapses consecutive slashes,
+ * removes empty segments.
+ */
+function sanitizePath(input: string): string {
+  return input
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/\/+/g, '/')
+    .replace(/^\/|\/$/g, '');
+}
+
+/**
+ * Sanitize a single path segment (no slashes allowed).
+ * Trims whitespace and replaces forward/back slashes with underscores.
+ */
+function sanitizePathSegment(input: string): string {
+  return input
+    .trim()
+    .replace(/[/\\]/g, '_');
+}

package/src/files/storage/file-storage-provider.types.ts

@@ -0,0 +1,188 @@
+/**
+ * File Storage Provider Interface
+ *
+ * Abstracts storage operations behind a unified interface.
+ * The Wildo-managed MinIO/S3 provider is the default implementation.
+ * Future providers (OneDrive, Google Drive, Dropbox, local-directory) implement the same interface.
+ *
+ * Services inject `IFileStorageProvider` via the `FileStorageRouterBackendService`.
+ */
+
+import { Readable } from 'stream';
+import type { FileStorageAccepted } from '@wildo-ai/zod-decorators';
+import type { File } from '@wildo-ai/saas-models';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+
+export type StoredFileStorageTarget = Pick<File, 'fileId' | 'storageProvider' | 'storageRef'>;
+
+/**
+ * Optional parameters for upload operations.
+ *
+ * All path segments are pre-composed by the caller
+ * (typically `FileStoragePathResolverBackendService`); the provider
+ * only concatenates them onto its own root.
+ */
+export interface StorageUploadOptions {
+  /**
+   * Composed relative folder path for organizing files within
+   * the provider's namespace.
+   *
+   * When set, the provider stores the blob at
+   * `<providerRoot>/[applicationId/]<folderPath>/<fileName|fileId>`.
+   *
+   * Forward-slash separated, no leading or trailing slash.
+   * @example 'specs/icps/big_companies'
+   * @example 'avatars'
+   */
+  folderPath?: string;
+
+  /**
+   * Explicit file name to use instead of the fileId.
+   * When omitted, the provider falls back to the fileId (UUID).
+   * @example 'personna.md'
+   * @example 'avatar.png'
+   */
+  fileName?: string;
+
+  /**
+   * Override the provider's default applicationId inclusion behavior.
+   *
+   * - `true`  → always include applicationId in the path
+   * - `false` → never include applicationId in the path
+   * - `undefined` → use the provider's default
+   *   (S3 defaults to true, local directory defaults to false)
+   */
+  includeApplicationId?: boolean;
+}
+
+/**
+ * Result of a successful file upload.
+ */
+export interface StorageUploadResult {
+  /** Unique storage reference (provider-specific key) */
+  storageRef: string;
+  /** Storage provider identifier */
+  provider: FileStorageAccepted;
+}
+
+/**
+ * Result of a file download.
+ */
+export interface StorageDownloadResult {
+  /** Readable stream of file content */
+  stream: Readable;
+  /** Content type (MIME type) */
+  contentType: string;
+  /** File size in bytes */
+  size: number;
+  /** ETag for caching */
+  etag?: string;
+  /** Last modification date */
+  lastModified?: Date;
+}
+
+/**
+ * Storage metadata for a file.
+ */
+export interface StorageFileMetadata {
+  /** Content type (MIME type) */
+  contentType: string;
+  /** File size in bytes */
+  size: number;
+  /** ETag for caching */
+  etag?: string;
+  /** Last modification date */
+  lastModified?: Date;
+}
+
+/**
+ * Health check result for a storage provider.
+ */
+export interface StorageProviderHealthResult {
+  healthy: boolean;
+  latency: number;
+  error?: string;
+}
+
+/**
+ * Unified storage provider interface.
+ *
+ * All file storage providers must implement this interface.
+ * Operations are scoped by executionContext for multi-tenant isolation.
+ */
+export interface IFileStorageProvider {
+  /** Provider identifier — must match a FileStorageAccepted enum value */
+  readonly providerId: FileStorageAccepted;
+
+  /**
+   * Whether this provider has the required configuration to operate.
+   * Returns false when env vars / credentials are absent.
+   */
+  isConfigured(): boolean;
+
+  /**
+   * Eagerly initialize the provider (connect, verify bucket/container).
+   * Called at startup for fail-fast. If not called, providers may lazy-init.
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Check provider health (connectivity, bucket reachability).
+   */
+  healthCheck(): Promise<StorageProviderHealthResult>;
+
+  /**
+   * Upload a file to storage.
+   *
+   * @param fileStream - Readable stream of file content
+   * @param fileId - Unique file identifier
+   * @param mimeType - MIME type of the file
+   * @param size - File size in bytes
+   * @param executionContext - Execution context (for auth/tenant scoping)
+   * @param options - Optional upload options
+   * @returns Storage upload result with provider-specific reference
+   */
+  upload(
+    fileStream: Readable,
+    fileId: string,
+    mimeType: string,
+    size: number,
+    executionContext: ExecutionContext<any>,
+    options?: StorageUploadOptions,
+  ): Promise<StorageUploadResult>;
+
+  /**
+   * Download a file from storage.
+   *
+   * @param fileId - File identifier
+   * @param executionContext - Execution context
+   * @returns Download result with stream and metadata
+   */
+  download(
+    file: StoredFileStorageTarget,
+    executionContext: ExecutionContext<any>,
+  ): Promise<StorageDownloadResult>;
+
+  /**
+   * Delete a file from storage.
+   *
+   * @param fileId - File identifier
+   * @param executionContext - Execution context
+   */
+  delete(
+    file: StoredFileStorageTarget,
+    executionContext: ExecutionContext<any>,
+  ): Promise<void>;
+
+  /**
+   * Get file metadata without downloading.
+   *
+   * @param fileId - File identifier
+   * @param executionContext - Execution context
+   * @returns File metadata
+   */
+  getMetadata(
+    file: StoredFileStorageTarget,
+    executionContext: ExecutionContext<any>,
+  ): Promise<StorageFileMetadata>;
+}

package/src/files/storage/file-storage-router.backend.service.ts

@@ -0,0 +1,172 @@
+/**
+ * File Storage Router Backend Service
+ *
+ * Selects the appropriate IFileStorageProvider based on:
+ * 1. Schema-declared `storageAccepted` (from z_file({ storageAccepted: [...] }))
+ * 2. Provider availability (isConfigured() check)
+ *
+ * Registered providers:
+ * - Wildo-managed (MinIO/S3) — default, used when no storageAccepted is specified
+ * - Local directory — filesystem-backed storage via STORAGE_LOCAL_BASE_DIR
+ *
+ * Resolution is strict: when `storageAccepted` is explicitly declared, only
+ * those providers are considered. A CONFIGURATION error is thrown when none
+ * of the declared providers are configured (no silent fallback to S3).
+ * When `storageAccepted` is omitted, Wildo-managed is the default and must
+ * be configured, otherwise a CONFIGURATION error is thrown.
+ */
+
+import { injectable, inject } from 'inversify';
+import { ErrorType, ErrorCustomMessageReference } from '@wildo-ai/saas-models';
+import { FileStorageAccepted } from '@wildo-ai/zod-decorators';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { IFileStorageProvider, StorageProviderHealthResult } from './file-storage-provider.types';
+
+@injectable()
+export class FileStorageRouterBackendService {
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  /** Map of providerId → IFileStorageProvider for O(1) lookup */
+  private readonly providerMap: Map<string, IFileStorageProvider>;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger)
+    private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)
+    private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.FileStorageProvider_WildoManaged)
+    private readonly wildoManagedProvider: IFileStorageProvider,
+    @inject(SAAS_SERVICE_TYPES.FileStorageProvider_LocalDirectory)
+    private readonly localDirectoryProvider: IFileStorageProvider,
+  ) {
+    this.logDebug = this.logger.debugByType('FileStorageRouterBackendService');
+    this.logger.setDebugTypeLogging('FileStorageRouterBackendService', false);
+
+    this.providerMap = new Map<string, IFileStorageProvider>();
+    this.providerMap.set(FileStorageAccepted.WILDO_MANAGED, this.wildoManagedProvider);
+    this.providerMap.set(FileStorageAccepted.LOCAL_DIRECTORY, this.localDirectoryProvider);
+  }
+
+  /**
+   * Resolve the appropriate storage provider for a given set of accepted providers.
+   *
+   * Resolution:
+   * - `storageAccepted` undefined/empty → default to Wildo-managed (must be configured)
+   * - `storageAccepted` specified → first configured match wins; if none configured → CONFIGURATION error
+   *
+   * Strict: when providers are explicitly declared, no silent fallback to an
+   * un-requested provider occurs. This prevents data landing in unexpected storage.
+   *
+   * @param storageAccepted - Accepted storage providers from z_file() schema (undefined = Wildo-managed)
+   * @returns The resolved storage provider
+   * @throws CONFIGURATION error when no suitable configured provider is found
+   */
+  resolveProvider(storageAccepted?: FileStorageAccepted[]): IFileStorageProvider {
+    if (!storageAccepted || storageAccepted.length === 0) {
+      if (!this.wildoManagedProvider.isConfigured()) {
+        throw this.errorBuilder.buildError(
+          ErrorType.CONFIGURATION,
+          undefined,
+          {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+              message: 'No storageAccepted specified and default Wildo-managed storage is not configured. ' +
+                'Set STORAGE_ENDPOINT, STORAGE_ACCESS_KEY, STORAGE_SECRET_KEY or specify storageAccepted in z_file().',
+            },
+          }
+        );
+      }
+      return this.wildoManagedProvider;
+    }
+
+    // Try to find a registered AND configured provider matching the schema preferences (in order)
+    for (const preferred of storageAccepted) {
+      const provider = this.providerMap.get(preferred);
+      if (provider && provider.isConfigured()) {
+        return provider;
+      }
+    }
+
+    // The developer explicitly declared accepted providers but none are configured.
+    // Strict behavior: do NOT silently fall back to a provider they didn't request.
+    const configuredProviders = Array.from(this.providerMap.entries())
+      .filter(([, p]) => p.isConfigured())
+      .map(([id]) => id);
+
+    throw this.errorBuilder.buildError(
+      ErrorType.CONFIGURATION,
+      undefined,
+      {
+        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+        context: {
+          message: 'None of the requested storage providers are configured. ' +
+            'Ensure the corresponding environment variables are set for at least one of the declared providers.',
+          requestedProviders: storageAccepted,
+          configuredProviders,
+        },
+      }
+    );
+  }
+
+  /**
+   * Get the default storage provider (Wildo-managed).
+   * Use this when no schema-level preference is set.
+   */
+  getDefaultProvider(): IFileStorageProvider {
+    return this.wildoManagedProvider;
+  }
+
+  getProviderById(providerId: string): IFileStorageProvider | undefined {
+    return this.providerMap.get(providerId);
+  }
+
+  /**
+   * Eagerly initialize all configured storage providers.
+   * Call at startup to fail fast on misconfiguration.
+   * Providers that are not configured are skipped.
+   */
+  async initialize(): Promise<void> {
+    for (const [providerId, provider] of this.providerMap) {
+      if (!provider.isConfigured()) {
+        this.logDebug('Skipping unconfigured storage provider', { providerId });
+        continue;
+      }
+      this.logDebug('Initializing storage provider', { providerId });
+      await provider.initialize();
+      this.logDebug('Storage provider initialized', { providerId });
+    }
+  }
+
+  /**
+   * Run health checks on all configured providers.
+   */
+  async healthCheck(): Promise<StorageProviderHealthResult> {
+    let totalLatency = 0;
+    for (const [providerId, provider] of this.providerMap) {
+      if (!provider.isConfigured()) {
+        continue;
+      }
+      const result = await provider.healthCheck();
+      totalLatency += result.latency;
+      if (!result.healthy) {
+        return { healthy: false, latency: totalLatency, error: `${providerId}: ${result.error}` };
+      }
+    }
+    return { healthy: true, latency: totalLatency };
+  }
+
+  /**
+   * Check if at least one storage provider is configured.
+   * Returns false when the app doesn't use file features.
+   */
+  isConfigured(): boolean {
+    for (const provider of this.providerMap.values()) {
+      if (provider.isConfigured()) {
+        return true;
+      }
+    }
+    return false;
+  }
+}