pmomusic/pmoparadise/IMPLEMENTATION.md

# Implementation Notes and Design Decisions

## Overview

`pmoparadise` is a Rust client library for Radio Paradise's streaming API, designed following idiomatic Rust patterns and inspired by the structure of `pmoqobuz`.

## Architecture Decisions

### 1. Module Structure

The crate is organized into focused modules:
- `client.rs` - HTTP client and API methods
- `models.rs` - Data structures with serde serialization
- `stream.rs` - Block streaming functionality
- `track.rs` - Per-track extraction (feature-gated)
- `error.rs` - Type-safe error handling

This separation ensures clear boundaries and makes the code maintainable.

### 2. Async/Await with Tokio

**Decision**: Use async/await throughout the API with tokio runtime.

**Rationale**:
- Radio Paradise API calls are I/O bound
- Streaming large FLAC blocks benefits from async I/O
- Tokio is the de facto standard for async Rust
- Enables efficient prefetching and concurrent operations

### 3. Type Safety

**Decision**: Use strong typing for all API concepts (EventId, DurationMs, Bitrate enum).

**Rationale**:
- Prevents mixing up event IDs with durations
- Enum for Bitrate makes invalid states unrepresentable
- Compile-time guarantees reduce runtime errors
- Self-documenting code

### 4. Error Handling

**Decision**: Use `thiserror` for structured errors with specific variants.

**Rationale**:
- Users can match on specific error types
- Better error messages than strings
- Idiomatic Rust error handling
- Easy to extend with new error types

### 5. Feature Gates

**Decision**: Gate the per-track functionality behind a feature flag.

**Rationale**:
- Most users don't need FLAC decoding
- Reduces dependencies for common use cases
- `claxon`, `hound`, `tempfile` add significant compile time
- Keeps the default build lightweight

## API Design Decisions

### 1. Builder Pattern for Client

**Decision**: Provide both `new()` and `builder()` methods.

**Rationale**:
- `new()` for simple cases (good defaults)
- `builder()` for customization (bitrate, proxy, timeout)
- Common Rust pattern (reqwest, etc.)
- Extensible without breaking changes

### 2. Block-Centric API

**Decision**: Focus on blocks as the primary abstraction, not individual songs.

**Rationale**:
- Matches Radio Paradise's actual architecture
- Blocks are the unit of streaming
- Enables efficient prefetching
- Transparent about implementation details

### 3. Prefetching Support

**Decision**: Provide explicit `prefetch_next()` method rather than automatic prefetching.

**Rationale**:
- Gives users control over when network calls happen
- Allows batching metadata requests
- Simpler to reason about
- Users can implement custom prefetch strategies

### 4. Stream Trait Implementation

**Decision**: Return a custom `BlockStream` that implements `Stream<Item = Result<Bytes>>`.

**Rationale**:
- Standard Rust async iterator pattern
- Compatible with futures combinators
- Easy to consume with `while let Some(chunk) = stream.next().await`
- Can be piped to any sink

## Per-Track Feature Decisions

### 1. Why It's Optional and Discouraged

**Decision**: Document limitations and recommend player-based seeking.

**Rationale**:
- FLAC doesn't support random access
- Must download entire block (50-100 MB)
- CPU-intensive decoding
- Players (mpv, ffmpeg) handle this better

**Trade-offs**:
- **Prefetch vs Per-Track**:
  - Prefetch: Low latency, efficient, recommended
  - Per-track: High latency, resource-intensive, only for special cases

### 2. Implementation Approach

**Decision**: Download to tempfile, decode with claxon, expose PCM/WAV.

**Rationale**:
- Claxon is pure Rust (no C dependencies)
- Tempfile ensures cleanup
- WAV export is a common use case
- Simple implementation

**Alternatives Considered**:
- **Streaming decode**: Too complex, claxon doesn't support seeking
- **HTTP range requests**: Radio Paradise blocks don't support it reliably
- **Caching decoded blocks**: Too much memory

### 3. Helper Method for Players

**Decision**: Provide `track_position_seconds()` to get timing for external players.

**Rationale**:
- Gives users the information they need
- Doesn't dictate how to use it
- Works with any player
- Zero overhead

## Data Model Decisions

### 1. HashMap for Songs

**Decision**: Use `HashMap<String, Song>` matching the API response.

**Rationale**:
- Matches JSON structure exactly
- Easy serde deserialization
- Provides `songs_ordered()` helper for iteration
- Preserves all data from API

### 2. Optional Fields

**Decision**: Make many fields `Option<T>` (year, rating, cover, etc.).

**Rationale**:
- API doesn't always provide all fields
- Future-proof against API changes
- Explicit about what's guaranteed

### 3. Extra Fields

**Decision**: Use `#[serde(flatten)]` for unknown fields.

**Rationale**:
- Forwards compatibility
- Don't break on new API fields
- Can inspect raw data if needed

## Testing Strategy

### 1. Unit Tests

- Inline tests for data model parsing
- Tests for timing calculations
- Builder pattern validation

### 2. Integration Tests with Mocks

**Decision**: Use `wiremock` for HTTP mocking.

**Rationale**:
- Don't hit real API in CI
- Reproducible tests
- Fast execution
- Can test error conditions

### 3. Example Programs

**Decision**: Provide runnable examples for all major features.

**Rationale**:
- Examples serve as documentation
- Users can copy-paste working code
- Tested in CI (via `cargo test --doc`)

## Documentation Strategy

### 1. Extensive Rustdoc

**Decision**: Document every public function, struct, and enum.

**Rationale**:
- Discoverability via docs.rs
- IDE autocomplete shows docs
- Examples in docs are tested
- Professional appearance

### 2. README with Use Cases

**Decision**: Detailed README covering common scenarios.

**Rationale**:
- First thing users see
- Explains design decisions
- Guides users to best practices
- Warns about per-track limitations

### 3. Module-Level Documentation

**Decision**: Each module has overview documentation.

**Rationale**:
- Explains purpose of module
- Links to related modules
- Top-down understanding

## Performance Considerations

### 1. Streaming vs Downloading

- **Streaming** (`stream_block`): Low latency, constant memory
- **Downloading** (`download_block`): Required for per-track, high memory

### 2. Prefetching

- Metadata prefetch is cheap (~1KB JSON)
- Block prefetch is expensive (~50-100MB)
- Leave block caching to users

### 3. Connection Pooling

**Decision**: Allow sharing `reqwest::Client`.

**Rationale**:
- Reuse connections
- User controls connection pool size
- Works with existing infrastructure

## Future Extensions

### Possible Additions (Not Implemented)

1. **Channel Support**: Main mix, mellow, rock, world (API supports this)
2. **Historical Blocks**: Fetch blocks by date/time
3. **Playlist API**: If Radio Paradise adds it
4. **WebSocket Live Updates**: Real-time now-playing updates
5. **Caching Layer**: Optional disk cache for blocks

### Why Not Included Now

- Keep initial release focused
- No user demand yet
- Can add without breaking changes
- Some features may require API changes

## Lessons Learned

### What Worked Well

1. **Builder pattern**: Easy to extend
2. **Feature gates**: Keeps default build fast
3. **Strong typing**: Caught many bugs at compile time
4. **Integration tests**: Gave confidence in refactoring

### What Could Be Improved

1. **FLAC seeking**: Claxon limitations make per-track expensive
2. **Error messages**: Could be more actionable
3. **Examples**: Could add more advanced patterns

## Comparison with pmoqobuz

### Similarities

- Builder pattern for client
- Serde models
- Async/await
- Integration with PMOMusic ecosystem

### Differences

- **No caching layer**: Radio Paradise API is simpler, less need
- **Streaming focus**: Qobuz is track-based, Paradise is block-based
- **No authentication**: Paradise API is public (for metadata)
- **Feature gates**: Paradise has optional FLAC decoding

## Conclusion

This implementation prioritizes:
1. **Ergonomics**: Easy for common cases, flexible for advanced
2. **Performance**: Async, streaming, minimal allocations
3. **Safety**: Type-safe, comprehensive error handling
4. **Documentation**: Extensive docs and examples
5. **Honesty**: Clear about limitations (per-track)

The result is a production-ready library that's pleasant to use and maintains high code quality standards.