TuneRipper/SESSION_MANAGEMENT.md

# Session Management Implementation

This document describes the session management feature implemented for TuneRipper to organize MP3 files by user sessions.

## 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.

## 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. **Session Persistence**: Session IDs are stored in browser's localStorage
4. **Session Validation**: Server validates session IDs and handles expired sessions
5. **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 Controllers
- **`VideoController`**: Now accepts and manages session IDs in processing requests
- **`DownloadController`**: Enhanced with session-aware endpoints
- **`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/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 files
?   ??? {jobId}_video_title.mp3
??? {sessionId2}/                 # Session 2 directory
    ??? {jobId}_video_title.mp3  # Session 2 files
    ??? {jobId}_video_title.mp3
```

### 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
  - Displays current session ID (truncated)
  - Includes session ID in processing requests
  - Constructs session-aware download URLs

#### Updated API Service
- **`TuneRipperApiService`**: Extended with session-aware methods
  - Session creation and validation
  - Session-aware file downloads
  - Session-specific job queries

## 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
   ```

3. **File Download**:
   ```
   User clicks download ? Use session-aware URL ? Server serves from session directory
   ```

## 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. **Cleanup**: Automatic background cleanup of expired sessions
5. **Directory Management**: Session directories 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

## Configuration

### Session Settings
- **Timeout**: 24 hours (configurable in `SessionService`)
- **Cleanup Interval**: 1 hour (configurable in `SessionService`)
- **Directory Structure**: `/downloads/{sessionId}/`

### Environment Variables
No new environment variables required - uses existing web root path configuration.

## 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

## Monitoring and Logging

- Session creation/validation logged
- File operations include session context
- Cleanup operations logged with statistics
- Error handling for session failures

## Future Enhancements

1. **Database Storage**: Replace in-memory session storage with persistent storage
2. **Session Sharing**: Allow sharing sessions between devices
3. **Session Analytics**: Track usage patterns and statistics
4. **Extended Metadata**: Store additional session information
5. **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 File by Session
```http
GET /api/download/abc123def456/job-id-123
Response: Binary audio file
```