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

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 File by Session

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