FileManager

• FileManager
  • Overview
  • Data Structure
    • State Schema
    • File Metadata Structure
    • Enums and Types
  • Core Functionality
    • File Storage Management
    • Entity-Based Organization
    • Security and Validation
  • API Methods
    • Core File Operations
    • Instance Management
  • Key Features

Overview

FileManager is an instance-based class that provides secure file storage and management capabilities for Rio entities. Each FileManager instance is bound to a specific entity (entityType + entityId) to organize file storage by context, supporting comprehensive file operations with validation, metadata tracking, and token-based security.

General Purpose:

• Secure File Storage: Manages file uploads, downloads, and deletions with comprehensive validation
• Entity-Based Organization: Each instance manages files for a specific entity (Member, Company, Tier, etc.)
• Rio Storage Integration: Leverages Rio's native file storage system for Base64-encoded content
• Token Security: Provides secure download access through token-based authentication
• Architectural Pattern: Instance-based with unique instanceId format: entityType_entityId

Data Structure

State Schema

interface FileManagerState {
  private: {
    files: { [fileId: string]: FileMetadata }
    entityType: ClassKey
    entityId: string
    createdAt: Date
    updatedAt: Date
  }
  public: {}
}

File Metadata Structure

interface FileActionHistory {
  action: FileAction
  actor: StateManagerActor
  timestamp: Date
}

interface FileMetadata {
  id: string
  filename: string                    // Generated: entityType_entityId_fileId.ext
  originalFilename: string            // User-provided filename
  fileType: FileType
  mimeType: string
  size: number
  actionHistory: FileActionHistory[]  // Complete audit trail of all file actions
  createdAt: Date
  updatedAt: Date
  status: FileStatus
  isPublic: boolean                   // Flag to mark file as publicly accessible
}

Enums and Types

enum FileType {
  IMAGE = 'image',      // Max 5MB: jpeg, jpg, png, gif, webp
  JSON = 'json',        // Max 5MB: application/json, text/json
  DOCUMENT = 'document' // Max 10MB: pdf, doc, docx, xls, xlsx, txt, csv
}

enum FileAction {
  UPLOAD = 'upload',
  DELETE = 'delete'
}

enum FileStatus {
  ACTIVE = 'active',
  DELETED = 'deleted'
}

Core Functionality

File Storage Management

• Upload Processing: Base64 content validation, MIME type verification, and metadata creation
• File Retrieval: Secure access to file content with comprehensive metadata
• Deletion Management: Soft deletion with status tracking and physical removal from storage
• Download Streaming: Token-based secure downloads with cache headers

Entity-Based Organization

• Instance Binding: Each FileManager instance is dedicated to a specific entity
• Filename Generation: Systematic naming convention: {entityType}_{entityId}_{fileId}.{extension}
• Metadata Tracking: Complete audit trail with actor attribution and timestamp tracking
• File Identification: Support for both fileId and filename-based operations

Security and Validation

• Comprehensive Validation: File format, size limits, and MIME type verification
  • IMAGE: Max 5MB - jpeg, jpg, png, gif, webp
  • JSON: Max 5MB - application/json, text/json
  • DOCUMENT: Max 10MB - pdf, doc, docx, xls, xlsx, txt, csv
• Token Authentication: Secure download access through JWT-based tokens (bypasses standard role authorization)
• Authorization Integration: Universal class access for upload/get/delete operations through RoleManager
• Content Verification: Base64 content analysis and format validation

API Methods

Core File Operations

• uploadFile (WRITE) - Upload files with comprehensive validation and metadata tracking

  • Validates file format, size (5MB for images/JSON, 10MB for documents), and MIME type consistency
  • Supports three file types: IMAGE, JSON, and DOCUMENT
  • Generates unique fileId and systematic filename
  • Stores Base64 content in Rio file storage system
  • Accepts optional isPublic parameter (default: false) to mark files as publicly accessible via getPublicFile endpoint
  • Accepts optional actor parameter for proxied calls (preserves actor when called from other classes)

• getFile (READ) - Retrieve file content as Base64 with complete metadata

  • Supports lookup by fileId or filename
  • Returns comprehensive file metadata and content
  • Validates file status and existence

• deleteFile (WRITE) - Permanently delete files from storage and update metadata

  • Supports deletion by fileId or filename
  • Updates metadata status and removes from Rio storage
  • Provides deletion confirmation with timestamp
  • Accepts optional actor parameter for proxied calls (preserves actor when called from other classes)

• downloadFile (READ) - Download files with cache headers using access tokens

  • Requires valid access token for authentication (no role-based authorization)
  • Token validation includes filename verification for security
  • Optimized delivery with cache control headers

• getPublicFile (READ) - Serve files publicly without authentication

  • Only accessible for files marked as public (isPublic: true) during upload
  • Returns 403 error for non-public files
  • Optimized delivery with 30-minute cache headers
  • No authentication required

Instance Management

• init (INIT) - Initialize FileManager instance for entity-specific file management

  • Binds instance to entityType and entityId
  • Sets up file storage structure and metadata tracking

• getState (INTERNAL) - Retrieve complete instance state for debugging

• getInstanceId (INTERNAL) - Generate instanceId from entity information

Method Types:

• WRITE - Sync state mutation (1-30s) - File operations with immediate metadata updates
• READ - Sync state access (1-30s) - File retrieval and content access
• INIT - Instance initialization with entity binding

Key Features

1. Architecture Pattern: Instance-based class with entity-specific file management using entityType_entityId instanceId format
2. Integration Points: Deep integration with Rio file storage system, RoleManager for authorization, and StateManager for metadata tracking
3. Security Features: Token-based download authentication (bypasses role authorization), public file access control with isPublic flag, comprehensive file validation, universal class access for upload/get/delete operations
4. Data Management: FileStateManager for metadata operations, systematic filename generation, and comprehensive audit trails
5. Performance Features: Base64 content processing, cache headers for downloads and public files, and optimized Rio storage integration
6. External Integrations: Rio native file storage system for persistent file management
7. Validation System: Multi-layer validation including file format, MIME type verification, size limits (5MB for images/JSON, 10MB for documents), and content analysis with support for three file types (IMAGE, JSON, DOCUMENT)
8. Audit/Logging: Complete file operation tracking with actor attribution, timestamps, and status management

Class Relations

The following diagram illustrates how FileManager integrates with other system components: