TuneRipper/SESSION_MANAGEMENT.md

Session Management Implementation

This document describes the session management feature implemented for TuneRipper to organize MP3 files by user sessions, including automatic ZIP file creation and management.

Overview

The session management system automatically creates and manages user sessions to organize downloaded files in separate directories. Each session gets its own subdirectory under the downloads folder, with automatic ZIP file creation and updates.

Key Features

1. Automatic Session Creation: When the app starts, it creates or retrieves an existing session ID
2. Session-Based File Organization: All MP3 files are stored in /downloads/{sessionId}/ directories
3. Automatic ZIP File Management: Session ZIP files are created/updated automatically after each successful download
4. Download All in ZIP: Users can download all session files in a single ZIP archive
5. Session Persistence: Session IDs are stored in browser's localStorage
6. Session Validation: Server validates session IDs and handles expired sessions
7. Backward Compatibility: Legacy endpoints still work for existing files

Architecture Changes

Server-Side (TuneRipper.Api)

New Services

• ISessionService: Interface for session management operations
• SessionService: Implementation handling session creation, validation, and cleanup
  • Creates unique 16-character session IDs
  • Manages session directories under /downloads/{sessionId}/
  • Automatic cleanup of expired sessions (24-hour timeout)
  • Background timer for periodic cleanup

Updated Services

• VideoService: Enhanced with ZIP file management
  • Automatically creates/updates session ZIP files after successful MP3 downloads
  • Uses System.IO.Compression for ZIP operations
  • Creates user-friendly filenames within ZIP archives
  • Handles ZIP creation errors gracefully without breaking main process

Updated Controllers

• VideoController: Now accepts and manages session IDs in processing requests
• DownloadController: Enhanced with session-aware endpoints and ZIP download support
• SessionController: New controller for session CRUD operations

New Endpoints

POST /api/session/create               - Create new session
GET  /api/session/validate/{sessionId} - Validate existing session  
POST /api/session/refresh/{sessionId}  - Refresh session timeout

GET  /api/download/{sessionId}/{jobId} - Session-aware file download
GET  /api/download/info/{sessionId}/{jobId} - Session-aware file info
DELETE /api/download/{sessionId}/{jobId} - Session-aware file deletion

GET  /api/download/zip/{sessionId}     - Download session ZIP file
GET  /api/download/zip/info/{sessionId} - Get session ZIP file information

GET  /api/video/jobs/{sessionId}       - Get jobs for specific session

File Organization

downloads/
??? legacy_files.mp3              # Legacy files (root level)
??? {sessionId1}/                 # Session 1 directory
?   ??? {jobId}_video_title.mp3  # Session 1 MP3 files
?   ??? {jobId}_video_title.mp3
?   ??? session_{sessionId1}.zip  # Automatic ZIP containing all MP3s
??? {sessionId2}/                 # Session 2 directory
    ??? {jobId}_video_title.mp3  # Session 2 MP3 files
    ??? {jobId}_video_title.mp3
    ??? session_{sessionId2}.zip  # Automatic ZIP containing all MP3s

ZIP File Management

• Automatic Creation: ZIP files are created/updated after each successful MP3 download
• User-Friendly Names: Files within ZIP use clean titles instead of job IDs
• Atomic Updates: Old ZIP is deleted before creating new one to ensure consistency
• Error Handling: ZIP creation failures don't interrupt main download process
• Efficient Storage: Only MP3 files are included in ZIP archives

Client-Side (TuneRipper)

New Services

• IClientSessionService: Interface for client-side session management
• ClientSessionService: Implementation handling browser-side session storage
  • Manages session ID in localStorage
  • Validates sessions with server
  • Automatic session creation when needed

Updated Components

• Home.razor: Enhanced to use session management and ZIP downloads
  • Displays current session ID (truncated)
  • Includes session ID in processing requests
  • Constructs session-aware download URLs
  • "Download All in ZIP" Button: Prominently displayed when multiple files exist
  • ZIP file information display (file count, size)
  • Loading states for ZIP preparation

Updated API Service

• TuneRipperApiService: Extended with session-aware methods and ZIP support
  • Session creation and validation
  • Session-aware file downloads
  • Session-specific job queries
  • ZIP download methods: DownloadSessionZipAsync(), GetSessionZipInfoAsync()

Data Flow

1. App Initialization:

   Client loads ? Check localStorage for sessionId ? Validate with server ? Create new if invalid
   

2. Video Processing:

   User submits URL ? Include sessionId in request ? Server processes to session directory ? Update ZIP file
   

3. File Download (Individual):

   User clicks download ? Use session-aware URL ? Server serves from session directory
   

4. ZIP Download (All Files):

   User clicks "Download All in ZIP" ? Server serves session ZIP file ? Browser downloads ZIP
   

ZIP File Features

Automatic ZIP Management

1. Creation Trigger: ZIP file is created/updated after each successful MP3 download
2. Content: Contains all MP3 files in the session with user-friendly names
3. Naming Convention: session_{sessionId}.zip
4. Download Name: TuneRipper_Session_{sessionId_prefix}.zip

User Interface

1. Visibility: "Download All in ZIP" button appears when 2+ files exist in session
2. Information Display: Shows file count and ZIP file size
3. Visual Design: Distinctive purple gradient button with package icon
4. Loading States: Shows "Preparing ZIP..." during download initiation
5. Responsive: Adapts to mobile screen sizes

Technical Implementation

1. Server-Side: Uses System.IO.Compression.ZipFile for ZIP operations
2. Client-Side: Direct browser download via JavaScript window.open()
3. Error Handling: Graceful fallback if ZIP is not available
4. Performance: ZIP creation happens asynchronously without blocking UI

Session Lifecycle

1. Creation: 16-character unique ID generated
2. Storage: Stored in browser localStorage and server memory
3. Validation: Checked on each request, 24-hour timeout
4. ZIP Management: ZIP files created/updated automatically with each download
5. Cleanup: Automatic background cleanup of expired sessions and their ZIP files
6. Directory Management: Session directories and ZIP files created/deleted as needed

Backward Compatibility

• Legacy download endpoints still function
• Old files remain accessible through fallback logic
• Gradual migration as users create new sessions
• No ZIP files created for legacy sessions

Configuration

Session Settings

• Timeout: 24 hours (configurable in SessionService)
• Cleanup Interval: 1 hour (configurable in SessionService)
• Directory Structure: /downloads/{sessionId}/
• ZIP Naming: session_{sessionId}.zip

ZIP Settings

• Compression: Default ZIP compression
• Content: MP3 files only (excludes temporary files)
• Entry Names: User-friendly titles extracted from file names
• Update Strategy: Replace entire ZIP file on each update

Security Considerations

• Session IDs are random and non-guessable
• Server validates all session operations
• Automatic cleanup prevents disk space accumulation
• No sensitive data stored in sessions
• ZIP files are only accessible with valid session IDs

Monitoring and Logging

• Session creation/validation logged
• File operations include session context
• ZIP creation/update operations logged
• Cleanup operations logged with statistics
• Error handling for session and ZIP failures

Future Enhancements

1. Database Storage: Replace in-memory session storage with persistent storage
2. ZIP Compression Options: Allow users to choose compression levels
3. Selective ZIP Downloads: Allow users to choose which files to include in ZIP
4. ZIP Password Protection: Optional password protection for ZIP files
5. Session Sharing: Allow sharing sessions between devices
6. Session Analytics: Track usage patterns and statistics
7. Extended Metadata: Store additional session information
8. Admin Interface: Management interface for session administration

API Examples

Create Session

POST /api/session/create
Response: { "sessionId": "abc123def456", "message": "Session created successfully" }

Process Video with Session

POST /api/video/process
{ "url": "https://youtube.com/watch?v=...", "sessionId": "abc123def456", "format": "mp3" }

Download Individual File

GET /api/download/abc123def456/job-id-123
Response: Binary audio file

Download Session ZIP

GET /api/download/zip/abc123def456
Response: Binary ZIP file containing all session MP3s

Get ZIP Information

GET /api/download/zip/info/abc123def456
Response: {
  "sessionId": "abc123def456",
  "zipFileName": "session_abc123def456.zip",
  "fileSize": "15.2 MB",
  "mp3FilesCount": 5,
  "downloadUrl": "/api/download/zip/abc123def456"
}

User Experience

New User Flow

1. User visits site ? Session created automatically
2. User downloads videos ? Files organized in session, ZIP updated
3. User sees "Download All in ZIP" button ? Can download all files at once
4. User returns later ? Session restored from localStorage

Benefits for Users

• Organization: All downloads from a session grouped together
• Convenience: Single-click download of all files via ZIP
• Efficiency: No need to download files individually
• Clean Downloads: Files in ZIP have user-friendly names
• Session Persistence: Downloads available across browser sessions