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
```http
POST /api/session/create
Response: { "sessionId": "abc123def456", "message": "Session created successfully" }
```

### Process Video with Session
```http
POST /api/video/process
{ "url": "https://youtube.com/watch?v=...", "sessionId": "abc123def456", "format": "mp3" }
```

### Download Individual File
```http
GET /api/download/abc123def456/job-id-123
Response: Binary audio file
```

### Download Session ZIP
```http
GET /api/download/zip/abc123def456
Response: Binary ZIP file containing all session MP3s
```

### Get ZIP Information
```http
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