migration_plan.md

Qobuz API Library Migration: C# to Rust

This document outlines the step-by-step plan to migrate the C# Qobuz API library to Rust, preserving all functionality while adhering to Rust's best practices.

Overview

The C# Qobuz API library provides access to Qobuz's music streaming API, including authentication, content retrieval (albums, artists, tracks), search functionality, user favorites management, and streaming URL generation. The migration to Rust will maintain the same functionality while leveraging Rust's memory safety, performance, and concurrency features.

Migration Steps

Phase 1: Project Setup and Dependencies

1. Initialize Rust Project

   • Create a new Rust library project: cargo new qobuz-api-rust
   • Configure Cargo.toml with necessary dependencies
   • Relevant C# files: QobuzApiSharp/QobuzApiSharp.csproj

2. Configure Dependencies

   • reqwest for HTTP client functionality
   • tokio for async runtime
   • serde and serde_json for serialization/deserialization
   • md5 for MD5 hashing
   • regex for regex operations
   • thiserror for error handling
   • chrono for date/time handling
   • Relevant C# files: QobuzApiSharp/QobuzApiSharp.csproj, QobuzApiSharp/packages.config

Phase 2: Core Data Structures

3. Create Error Types

   • Define error enum using thiserror:
     • ApiErrorResponse { code: String, message: String, status: String }
     • ApiResponseParseError { content: String, source: Box<dyn std::error::Error> }
     • QobuzApiInitializationError { message: String }
   • Relevant C# files: QobuzApiSharp/Api/Exceptions/ApiErrorResponseException.cs, QobuzApiSharp/Api/Exceptions/ApiResponseParseErrorException.cs, QobuzApiSharp/Api/Exceptions/QobuzApiInitializationException.cs

4. Create Basic Models

   • QobuzApiStatusResponse with code, message, and status fields
   • Basic content models (Artist, Album, Track, User, etc.)
   • Relevant C# files: QobuzApiSharp/Api/Models/QobuzApiStatusResponse.cs, QobuzApiSharp/Api/Models/Content/General/Artist.cs, QobuzApiSharp/Api/Models/Content/Album/Album.cs, QobuzApiSharp/Api/Models/Content/Track/Track.cs, QobuzApiSharp/Api/Models/User/User.cs

5. Implement JSON Serialization

   • Use serde derive macros for all models
   • Implement custom deserializers where needed (similar to C# converters)
   • Relevant C# files: QobuzApiSharp/Api/Converters/TrackIdsConverter.cs, QobuzApiSharp/Api/Converters/MostPopularContentConverter.cs, QobuzApiSharp/Api/Service/QobuzApiHelper.cs

Phase 3: Utilities and Helpers

6. Create Utilities Module

   • MD5 utilities for hashing
   • Query string builder
   • Time utilities for Unix timestamps
   • Relevant C# files: QobuzApiSharp/Api/Utilities/MD5Utilities.cs

7. Implement API Helper Functions

   • Web player app ID/secret extraction
   • File URL signature generation
   • HTTP response deserialization
   • Relevant C# files: QobuzApiSharp/Api/Service/QobuzApiHelper.cs, QobuzApiSharp/Api/QobuzApiConstants.cs

Phase 4: HTTP Client Implementation

8. Create Qobuz API Service Structure

   • Define QobuzApiService struct with:
     • app_id: String
     • app_secret: String
     • user_auth_token: Option<String>
     • client: reqwest::Client
   • Relevant C# files: QobuzApiSharp/Api/Service/QobuzApiService.cs

9. Implement HTTP Request Handling

   • Async methods for sending requests
   • Error handling for API responses
   • Request signature generation for protected endpoints
   • Relevant C# files: QobuzApiSharp/Api/Service/QobuzApiService.cs, QobuzApiSharp/Api/Service/QobuzApiHelper.cs

Phase 5: Authentication System

10. Implement User Authentication

    • login_with_email method
    • login_with_username method
    • login_with_token method
    • reset_password methods
    • Relevant C# files: QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.User.cs, QobuzApiSharp/Api/Models/User/Login.cs

11. Session Management

    • Token storage and retrieval
    • Authentication header management
    • Relevant C# files: QobuzApiSharp/Api/Service/QobuzApiService.cs, QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.User.cs

Phase 6: Content Endpoints

12. Album Endpoints

    • get_album method
    • search_albums method
    • Relevant C# files: QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Album.cs, QobuzApiSharp/Api/Models/Content/Album/Album.cs

13. Artist Endpoints

    • get_artist method
    • search_artists method
    • Relevant C# files: QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Artist.cs, QobuzApiSharp/Api/Models/Content/General/Artist.cs

14. Track Endpoints

    • get_track method
    • get_track_file_url method (with signature generation)
    • search_tracks method
    • Relevant C# files: QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Track.cs, QobuzApiSharp/Api/Models/Content/Track/Track.cs, QobuzApiSharp/Api/Models/Content/Track/FileUrl.cs

15. Playlist Endpoints

    • get_playlist method
    • search_playlists method
    • Relevant C# files: QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Playlist.cs, QobuzApiSharp/Api/Models/Content/Playlist/Playlist.cs

16. Other Content Endpoints

    • Article endpoints
    • Label endpoints
    • Story endpoints
    • Catalog search
    • Relevant C# files: QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Article.cs, QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Label.cs, QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Story.cs, QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Catalog.cs

Phase 7: User Functionality

17. Favorite Management

    • add_user_favorites method
    • delete_user_favorites method
    • get_user_favorite_ids method
    • get_user_favorites method
    • Relevant C# files: QobuzApiSharp/Api/Service/Endpoints/QobuzApiService.Favorite.cs, QobuzApiSharp/Api/Models/Content/General/UserFavorites.cs, QobuzApiSharp/Api/Models/Content/General/UserFavoritesIds.cs

18. Additional User Features

    • User profile retrieval
    • Subscription information
    • Relevant C# files: QobuzApiSharp/Api/Models/User/User.cs, QobuzApiSharp/Api/Models/User/Subscription.cs

Phase 8: Advanced Features

19. Web Player Integration

    • Implement fetching app ID/secret from web player
    • Bundle.js parsing with regex
    • Base64 decoding and string manipulation
    • Relevant C# files: QobuzApiSharp/Api/Service/QobuzApiHelper.cs, QobuzApiSharp/Api/QobuzApiConstants.cs

20. Specialized Converters

    • Implement custom deserializers for inconsistent API responses
    • Handle the TrackIdsConverter functionality for mixed JSON types
    • Relevant C# files: QobuzApiSharp/Api/Converters/TrackIdsConverter.cs, QobuzApiSharp/Api/Converters/MostPopularContentConverter.cs

Phase 9: Testing and Validation

21. Unit Tests

    • Test all model serialization/deserialization
    • Test utility functions
    • Test API helper functions
    • Relevant C# files: All model files, utility files, and helper files

22. Integration Tests

    • Test API endpoints with mock responses
    • Test authentication flows
    • Test error handling
    • Relevant C# files: All endpoint files in QobuzApiSharp/Api/Service/Endpoints/

23. Functional Verification

    • Verify all functionality matches C# implementation
    • Test with real Qobuz API (if possible with test credentials)
    • Relevant C# files: All files in the codebase for reference

Phase 10: Documentation and Best Practices

24. Documentation

    • Add comprehensive Rust documentation comments
    • Create examples for common use cases
    • Document error handling patterns
    • Relevant C# files: All files in the codebase for reference

25. Rust Best Practices Implementation

    • Proper error handling with Result<T, E> types
    • Memory safety without garbage collection
    • Use of async/await for I/O operations
    • Proper ownership and borrowing patterns
    • Implement Display and Debug traits where appropriate
    • Relevant C# files: All files in the codebase for reference

26. Performance Optimizations

    • Connection pooling with reqwest
    • Efficient JSON parsing
    • Proper async execution patterns
    • Relevant C# files: QobuzApiSharp/Api/Service/QobuzApiService.cs, QobuzApiSharp/Api/Service/QobuzApiHelper.cs

Rust-Specific Considerations

Memory Safety

• Use String instead of &str for owned data in structs
• Implement proper ownership patterns
• Avoid unnecessary cloning
• Relevant C# files: All model files for reference

Async Programming

• Use tokio::task for concurrent operations
• Implement proper async/await patterns
• Handle async error propagation correctly
• Relevant C# files: QobuzApiSharp/Api/Service/QobuzApiService.cs

Error Handling

• Use thiserror for comprehensive error types
• Implement proper error chaining
• Provide meaningful error messages
• Relevant C# files: QobuzApiSharp/Api/Exceptions/ApiErrorResponseException.cs, QobuzApiSharp/Api/Exceptions/ApiResponseParseErrorException.cs, QobuzApiSharp/Api/Exceptions/QobuzApiInitializationException.cs

Type Safety

• Leverage Rust's type system for API safety
• Use Option<T> for nullable fields
• Use Result<T, E> for fallible operations
• Implement proper validation for API inputs
• Relevant C# files: All model files for reference

API Compatibility

The Rust implementation will maintain the same public API contract as the C# version:

• Same method names and signatures (adapted to Rust conventions)
• Same parameter types and return types
• Same error handling patterns
• Same authentication mechanisms
• Same functionality for all endpoints
• Relevant C# files: All endpoint files in QobuzApiSharp/Api/Service/Endpoints/

Testing Strategy

• Implement comprehensive unit tests for all modules
• Use mock HTTP servers for API testing
• Test error scenarios and edge cases
• Verify JSON serialization/deserialization correctness
• Performance testing to ensure Rust benefits are realized
• Relevant C# files: All files in the codebase for reference

Deployment and Distribution

• Package as a Rust crate on crates.io
• Provide clear usage examples
• Document installation and setup requirements
• Include compatibility notes for different Rust versions
• Relevant C# files: QobuzApiSharp/QobuzApiSharp.csproj, QobuzApiSharp/QobuzApiSharp.nuspec