### Manual Setup - Fedora/RHEL

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Commands to install necessary dependencies on Fedora/RHEL systems and build the project.

```bash
sudo dnf install openssl-devel sqlite-devel
cargo build
```

--------------------------------

### Manual Setup - Ubuntu/Debian

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Commands to install necessary dependencies on Ubuntu/Debian systems and build the project.

```bash
sudo apt-get install libssl-dev pkg-config sqlite3
cargo build
```

--------------------------------

### Manual Setup - macOS

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Commands to install necessary dependencies on macOS systems and build the project.

```bash
brew install openssl sqlite
cargo build
```

--------------------------------

### Run an example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Commands to compile and run specific examples from the 'examples/' directory.

```bash
cargo run --example basic_download
cargo run --example rest_api_server
```

--------------------------------

### Testing Your Setup

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Commands for building the library, running tests, and generating documentation.

```bash
# Build the library
cargo build

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Build documentation
cargo doc --open
```

--------------------------------

### Nix Development Environment Setup

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Commands to enter a Nix shell, build the project, and run tests.

```bash
nix-shell
cargo build
cargo test
```

--------------------------------

### Minimal Usenet Downloader Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

A basic Rust example demonstrating how to initialize UsenetDownloader with a configuration and add an NZB file for download.

```rust
use usenet_dl::config::{Config, DownloadConfig, ServerConfig};
use usenet_dl::{UsenetDownloader, DownloadOptions, Event, Priority};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config {
        servers: vec![
            ServerConfig {
                host: "news.example.com".to_string(),
                port: 563,
                tls: true,
                username: Some("user".to_string()),
                password: Some("pass".to_string()),
                connections: 10,
                priority: 0,
                pipeline_depth: 10,
            }
        ],
        download: DownloadConfig {
            download_dir: "downloads".into(),
            temp_dir: "temp".into(),
            ..Default::default()
        },
        ..Default::default()
    };

    let downloader = UsenetDownloader::new(config).await?;

    let id = downloader.add_nzb(
        "file.nzb".as_ref(),
        DownloadOptions {
            category: Some("movies".into()),
            priority: Priority::Normal,
            ..Default::default()
        }
    ).await?;

    println!("Queued download: {}", id);
    Ok(())
}
```

--------------------------------

### Category Configuration Example (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON structure for category-specific settings, mirroring the TOML example.

```json
{
  "persistence": {
    "categories": {
      "movies": {
        "destination": "/media/movies",
        "post_process": "unpack_and_cleanup",
        "scripts": [
          {
            "path": "/usr/local/bin/movie-indexer.sh",
            "events": ["on_complete"],
            "timeout": 60
          }
        ]
      },
      "tv": {
        "destination": "/media/tv",
        "post_process": null,
        "scripts": []
      }
    }
  }
}
```

--------------------------------

### NNTP Server Setup

Source: https://github.com/jvz-devx/usenet-dl/blob/main/examples/README.md

Example of setting up NNTP server configuration.

```rust
let server = ServerConfig {
    host: "news.example.com".to_string(),  // Your NNTP server
    port: 563,                              // SSL/TLS port (or 119 for plain)
    tls: true,                              // Use SSL/TLS
    username: Some("your_username".to_string()),
    password: Some("your_password".to_string()),
    connections: 10,                        // Connection pool size
    priority: 0,                            // Lower = tried first
    pipeline_depth: 10,                     // Pipelined NNTP commands
};
```

--------------------------------

### Install archive tools on macOS

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Installs 'unrar' and 'p7zip' on macOS using Homebrew.

```bash
# Install on macOS
brew install unrar p7zip
```

--------------------------------

### WatchFolderConfig TOML Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for a watch folder in TOML format.

```toml
[[watch_folders]]
path = "/path/to/nzb/folder"
after_import = "move_to_processed"
category = "movies"
scan_interval = 5  # Seconds
```

--------------------------------

### Script Configuration Example (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON structure for configuring scripts to run on specific events.

```json
{
  "scripts": [
    {
      "path": "/usr/local/bin/notify.sh",
      "events": ["on_complete", "on_failed"],
      "timeout": 300
    }
  ]
}
```

--------------------------------

### JSON Configuration Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for usenet-dl, detailing various settings.

```json
{
  "servers": [
    {
      "host": "news.primary.com",
      "port": 563,
      "tls": true,
      "username": "user",
      "password": "pass",
      "connections": 10,
      "priority": 0,
      "pipeline_depth": 10
    }
  ],
  "download_dir": "/downloads",
  "temp_dir": "/temp",
  "max_concurrent_downloads": 3,
  "speed_limit_bps": null,
  "retry": {
    "max_attempts": 5,
    "initial_delay": 1,
    "max_delay": 60,
    "backoff_multiplier": 2.0,
    "jitter": true
  },
  "default_post_process": "unpack_and_cleanup",
  "delete_samples": true,
  "extraction": {
    "max_recursion_depth": 2,
    "archive_extensions": ["rar", "zip", "7z"]
  },
  "file_collision": "rename",
  "deobfuscation": {
    "enabled": true,
    "min_length": 12
  },
  "duplicate": {
    "enabled": true,
    "action": "warn",
    "methods": ["nzb_hash", "job_name"]
  },
  "disk_space": {
    "enabled": true,
    "min_free_space": 1073741824,
    "size_multiplier": 2.5
  },
  "cleanup": {
    "enabled": true,
    "target_extensions": ["par2", "nzb", "sfv"],
    "archive_extensions": ["rar", "zip", "7z"],
    "delete_samples": true
  },
  "direct_unpack": {
    "enabled": false,
    "direct_rename": false,
    "poll_interval_ms": 200
  },
  "password_file": "/config/passwords.txt",
  "try_empty_password": true,
  "persistence": {
    "database_path": "/config/usenet-dl.db",
    "schedule_rules": [],
    "categories": {
      "movies": {
        "destination": "/media/movies",
        "post_process": "unpack_and_cleanup",
        "scripts": []
      },
      "tv": {
        "destination": "/media/tv",
        "post_process": null,
        "scripts": []
      }
    }
  },
  "api": {
    "bind_address": "0.0.0.0:6789",
    "api_key": "secret123",
    "cors_enabled": true,
    "swagger_ui": true,
    "rate_limit": {
      "enabled": false
    }
  },
  "schedule_rules": [
    {
      "name": "Night unlimited",
      "days": [],
      "start_time": "00:00",
      "end_time": "06:00",
      "action": {
        "type": "unlimited"
      },
      "enabled": true
    }
  ],
  "watch_folders": [
    {
      "path": "/nzb",
      "after_import": "move_to_processed",
      "scan_interval": 5
    }
  ],
  "rss_feeds": [
    {
      "url": "https://indexer.com/rss",
      "check_interval": 900,
      "category": "tv",
      "filters": [
        {
          "name": "HD Shows",
          "include": ["1080p", "720p"],
          "exclude": ["CAM"],
          "min_size": 1073741824,
          "max_size": null,
          "max_age": null
        }
      ],
      "auto_download": true,
      "priority": "normal",
      "enabled": true
    }
  ],
  "webhooks": [
    {
      "url": "https://example.com/webhook",
      "events": ["on_complete"],
      "auth_header": "Bearer token",
      "timeout": 30
    }
  ],
  "scripts": [
    {
      "path": "/scripts/notify.sh",
      "events": ["on_complete", "on_failed"],
      "timeout": 300
    }
  ]
}
```

--------------------------------

### TOML Configuration Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for RSS feeds, webhooks, and scripts.

```toml
[[rss_feeds]]
url = "https://indexer.com/rss"
check_interval = 900
category = "tv"
auto_download = true
priority = "normal"
enabled = true

[[rss_feeds.filters]]
name = "HD Shows"
include = ["1080p", "720p"]
exclude = ["CAM"]
min_size = 1073741824

[[webhooks]]
url = "https://example.com/webhook"
events = ["on_complete"]
auth_header = "Bearer token"
timeout = 30

[[scripts]]
path = "/scripts/notify.sh"
events = ["on_complete", "on_failed"]
timeout = 300
```

--------------------------------

### Start the Server

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/api-testing.md

Command to start the API server in development mode with a test database.

```bash
# In development mode with test database
cd /path/to/usenet-dl
cargo run --example api_server
```

--------------------------------

### Category Configuration Example (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML structure for category-specific settings, including destination and scripts.

```toml
[persistence.categories.movies]
destination = "/media/movies"
post_process = "unpack_and_cleanup"

[[persistence.categories.movies.scripts]]
path = "/usr/local/bin/movie-indexer.sh"
events = ["on_complete"]
timeout = 60

[persistence.categories.tv]
destination = "/media/tv"
```

--------------------------------

### WebhookConfig TOML Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for a webhook in TOML format.

```toml
[[webhooks]]
url = "https://example.com/webhook"
events = ["on_complete", "on_failed"]
auth_header = "Bearer secret-token"
timeout = 30  # Seconds
```

--------------------------------

### Install archive tools on Ubuntu/Debian

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Installs 'unrar' and 'p7zip-full' on Ubuntu or Debian-based systems.

```bash
# Install on Ubuntu/Debian
sudo apt-get install unrar p7zip-full
```

--------------------------------

### Complete Integration Test

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/rss-testing.md

An example Rust program demonstrating the setup and execution of RSS feed testing, including configuration, starting the scheduler, and monitoring events.

```rust
use usenet_dl::{Config, UsenetDownloader};
use usenet_dl::config::{RssFeedConfig, RssFilter, ServerConfig};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Enable debug logging
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::INFO)
        .init();

    // Configure Usenet server
    let mut config = Config::default();
    config.servers = vec![
        ServerConfig {
            host: "news.example.com".to_string(),
            port: 563,
            tls: true,
            username: Some("your_username".to_string()),
            password: Some("your_password".to_string()),
            connections: 10,
            priority: 0,
        }
    ];

    // Configure RSS feed
    config.rss_feeds = vec![
        RssFeedConfig {
            url: "https://your-indexer.com/rss?t=5000&apikey=YOUR_KEY".to_string(),
            check_interval: Duration::from_secs(300),
            category: Some("test".to_string()),
            filters: vec![
                RssFilter {
                    name: "Safe Test Files".to_string(),
                    include: vec!["(?i)(ubuntu|debian).*iso".to_string()],
                    exclude: vec!["(?i)sample".to_string()],
                    min_size: Some(1_000_000_000), // 1 GB
                    max_size: None,
                    max_age: Some(Duration::from_secs(86400 * 30)), // 30 days
                },
            ],
            auto_download: true,
            priority: usenet_dl::types::Priority::Normal,
            enabled: true,
        }
    ];

    // Create downloader
    let downloader = UsenetDownloader::new(config).await?;

    // Subscribe to events
    let mut events = downloader.subscribe();
    tokio::spawn(async move {
        while let Ok(event) = events.recv().await {
            println!("Event: {:?}", event);
        }
    });

    // Start RSS scheduler
    let _rss_task = downloader.start_rss_scheduler();

    // Run for 10 minutes to observe behavior
    println!("RSS scheduler started. Monitoring for 10 minutes...");
    tokio::time::sleep(Duration::from_secs(600)).await;

    // Graceful shutdown
    downloader.shutdown().await?;

    Ok(())
}
```

--------------------------------

### WatchFolderConfig JSON Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for a watch folder in JSON format.

```json
{
  "watch_folders": [
    {
      "path": "/path/to/nzb/folder",
      "after_import": "move_to_processed",
      "category": "movies",
      "scan_interval": 5
    }
  ]
}
```

--------------------------------

### Complete Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/post-processing.md

A comprehensive example demonstrating the setup of the UsenetDownloader with various configurations for download, tools, processing, automation, and then adding an NZB file for download while subscribing to events.

```rust
use usenet_dl::{UsenetDownloader, Config, DownloadOptions, Priority};
use usenet_dl::config::{
    DownloadConfig,
    ToolsConfig,
    ProcessingConfig,
    AutomationConfig,
    ExtractionConfig,
    CleanupConfig,
    DeobfuscationConfig,
    PostProcess,
    FileCollisionAction,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config {
        download: DownloadConfig {
            default_post_process: PostProcess::UnpackAndCleanup,
            file_collision: FileCollisionAction::Rename,
            ..Default::default()
        },
        tools: ToolsConfig {
            password_file: Some("passwords.txt".into()),
            try_empty_password: true,
            ..Default::default()
        },
        processing: ProcessingConfig {
            extraction: ExtractionConfig {
                max_recursion_depth: 2,
                ..Default::default()
            },
            cleanup: CleanupConfig {
                enabled: true,
                target_extensions: vec![
                    "par2".to_string(),
                    "nzb".to_string(),
                    "sfv".to_string(),
                ],
                delete_samples: true,
                ..Default::default()
            },
            ..Default::default()
        },
        automation: AutomationConfig {
            deobfuscation: DeobfuscationConfig {
                enabled: true,
                min_length: 12,
            },
            ..Default::default()
        },
        ..Default::default()
    };

    let downloader = UsenetDownloader::new(config).await?;

    // Subscribe to events
    let mut rx = downloader.subscribe();
    tokio::spawn(async move {
        while let Ok(event) = rx.recv().await {
            println!("{:?}", event);
        }
    });

    // Add download
    let id = downloader.add_nzb(
        "file.nzb".as_ref(),
        DownloadOptions::default(),
    ).await?;

    println!("Started download: {}", id);

    Ok(())
}

```

--------------------------------

### Check for 7z

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Verifies if the '7z' utility is installed and accessible in the system's PATH.

```bash
# Check for 7z
which 7z
```

--------------------------------

### REST API Server Start

Source: https://github.com/jvz-devx/usenet-dl/blob/main/README.md

Example of how to start the REST API server with a given configuration and downloader instance.

```rust
use std::sync::Arc;
use usenet_dl::api::start_api_server;
use usenet_dl::config::{Config, DownloadConfig, ServerConfig};

let config = Config { /* ... */ };
let downloader = Arc::new(UsenetDownloader::new(config.clone()).await?);
let config = Arc::new(config);
start_api_server(downloader, config).await?;
```

--------------------------------

### Download Control Examples

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Rust code snippets illustrating how to pause, resume, set, and remove global speed limits for downloads.

```rust
// Pause a download
downloader.pause(id).await?;

// Resume a download
downloader.resume(id).await?;

// Set global speed limit (10 MB/s)
downloader.set_speed_limit(Some(10_000_000)).await;

// Remove speed limit
downloader.set_speed_limit(None).await;
```

--------------------------------

### Starting the API Server

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/api-reference.md

Examples for starting the REST API server using cargo run or integrating it into an application.

```bash
# Using the REST API example
cargo run --example rest_api_server

# Or integrate into your application
use usenet_dl::UsenetDownloader;
use usenet_dl::api::start_api_server;

let downloader = UsenetDownloader::new(config).await?;
let api_config = Arc::new(config.clone());
start_api_server(Arc::new(downloader), api_config).await?;
```

--------------------------------

### Schedule Rule Example (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for time-based speed limit rules.

```json
{
  "schedule_rules": [
    {
      "name": "Night owl",
      "days": [],
      "start_time": "00:00",
      "end_time": "06:00",
      "action": {
        "type": "unlimited"
      },
      "enabled": true
    },
    {
      "name": "Work hours",
      "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "start_time": "09:00",
      "end_time": "17:00",
      "action": {
        "type": "speed_limit",
        "limit_bps": 1000000
      },
      "enabled": true
    }
  ]
}
```

--------------------------------

### WebhookConfig JSON Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for a webhook in JSON format.

```json
{
  "webhooks": [
    {
      "url": "https://example.com/webhook",
      "events": ["on_complete", "on_failed"],
      "auth_header": "Bearer secret-token",
      "timeout": 30
    }
  ]
}
```

--------------------------------

### File Collision Action Example (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for file collision handling using JSON.

```json
{
  "file_collision": "rename"
}
```

--------------------------------

### Categories Configuration

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Organizes downloads by category with custom destinations and post-processing.

```rust
use usenet_dl::config::{Config, PersistenceConfig, CategoryConfig, PostProcess};

let config = Config {
    persistence: PersistenceConfig {
        categories: [
            ("movies".to_string(), CategoryConfig {
                destination: "/mnt/media/movies".into(),
                post_process: Some(PostProcess::UnpackAndCleanup),
                scripts: vec![],
            }),
            ("tv".to_string(), CategoryConfig {
                destination: "/mnt/media/tv".into(),
                post_process: Some(PostProcess::UnpackAndCleanup),
                scripts: vec![],
            }),
        ].into_iter().collect(),
        ..Default::default()
    },
    ..Default::default()
};
```

--------------------------------

### Complete Example Configuration (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

A comprehensive TOML configuration file demonstrating various settings including servers, directories, download settings, retry, post-processing, extraction, file handling, deobfuscation, duplicate detection, disk space, cleanup, direct unpack, passwords, persistence, API, schedule rules, and watch folders.

```toml
# NNTP Servers
[[servers]]
host = "news.primary.com"
port = 563
tls = true
username = "user"
password = "pass"
connections = 10
priority = 0
pipeline_depth = 10

[[servers]]
host = "news.backup.com"
port = 119
tls = false
connections = 5
priority = 10
pipeline_depth = 10

# Directories
download_dir = "/downloads"
temp_dir = "/temp"

# Download Settings
max_concurrent_downloads = 3
speed_limit_bps = null  # Unlimited

# Retry Configuration
[retry]
max_attempts = 5
initial_delay = 1
max_delay = 60
backoff_multiplier = 2.0
jitter = true

# Post-Processing
default_post_process = "unpack_and_cleanup"
delete_samples = true

# Extraction
[extraction]
max_recursion_depth = 2
archive_extensions = ["rar", "zip", "7z"]

# File Handling
file_collision = "rename"

[deobfuscation]
enabled = true
min_length = 12

# Duplicate Detection
[duplicate]
enabled = true
action = "warn"
methods = ["nzb_hash", "job_name"]

# Disk Space
[disk_space]
enabled = true
min_free_space = 1073741824  # 1 GB
size_multiplier = 2.5

# Cleanup
[cleanup]
enabled = true
target_extensions = ["par2", "nzb", "sfv"]
archive_extensions = ["rar", "zip", "7z"]
delete_samples = true

# DirectUnpack (extract during download)
[direct_unpack]
enabled = false
direct_rename = false
poll_interval_ms = 200

# Passwords
password_file = "/config/passwords.txt"
try_empty_password = true

# Persistence (not flattened — fields are nested)
[persistence]
database_path = "/config/usenet-dl.db"

[persistence.categories.movies]
destination = "/media/movies"
post_process = "unpack_and_cleanup"

[persistence.categories.tv]
destination = "/media/tv"

# REST API
[api]
bind_address = "0.0.0.0:6789"
api_key = "secret123"
cors_enabled = true
swagger_ui = true

[api.rate_limit]
enabled = false

# Schedule: Unlimited at night
[[schedule_rules]]
name = "Night unlimited"
days = []
start_time = "00:00"
end_time = "06:00"
enabled = true

[schedule_rules.action]
type = "unlimited"

# Schedule: Limited during work hours
[[schedule_rules]]
name = "Work hours"
days = ["monday", "tuesday", "wednesday", "thursday", "friday"]
start_time = "09:00"
end_time = "17:00"
enabled = true

[schedule_rules.action]
type = "speed_limit"
limit_bps = 1000000

# Watch Folder
[[watch_folders]]
path = "/nzb"
after_import = "move_to_processed"
scan_interval = 5

```

--------------------------------

### ScriptConfig TOML Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for executing an external script in TOML format.

```toml
[[scripts]]
path = "/usr/local/bin/notify.sh"
events = ["on_complete", "on_failed"]
timeout = 300  # 5 minutes
```

--------------------------------

### Schedule Rule Example (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for time-based speed limit rules.

```toml
[[schedule_rules]]
name = "Night owl"
days = []  # Empty = all days
start_time = "00:00"
end_time = "06:00"
enabled = true

[schedule_rules.action]
type = "unlimited"

[[schedule_rules]]
name = "Work hours"
days = ["monday", "tuesday", "wednesday", "thursday", "friday"]
start_time = "09:00"
end_time = "17:00"
enabled = true

[schedule_rules.action]
type = "speed_limit"
limit_bps = 1000000  # 1 MB/s
```

--------------------------------

### Post-processing Mode Example (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for setting the default post-processing mode in JSON.

```json
{
  "default_post_process": "unpack_and_cleanup"
}

```

--------------------------------

### Running Examples

Source: https://github.com/jvz-devx/usenet-dl/blob/main/examples/README.md

Examples can be run using `cargo run --example <name>`.

```bash
# Run the basic download example
cargo run --example basic_download

# Run the REST API server example
cargo run --example rest_api_server

# Run the multi-subscriber example
cargo run --example multi_subscriber

# Run the custom configuration example
cargo run --example custom_configuration
```

--------------------------------

### File Collision Action Example (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for file collision handling using TOML.

```toml
file_collision = "rename"
```

--------------------------------

### List all downloads

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Retrieves a list of all current downloads.

```bash
curl http://localhost:6789/api/v1/downloads
```

--------------------------------

### Minimal Production Configuration

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

A minimal TOML configuration example for usenet-dl, specifying only settings that differ from defaults.

```toml
[[servers]]
host = "news.example.com"
port = 563
tls = true
username = "myuser"
password = "mypass"

download_dir = "/media/downloads"

[persistence.categories.movies]
destination = "/media/movies"

[persistence.categories.tv]
destination = "/media/tv"
```

--------------------------------

### GET /api/v1/servers/test Request

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/server-testing.md

Example request to test all configured servers.

```bash
curl http://localhost:6789/api/v1/servers/test
```

--------------------------------

### Check for unrar

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Verifies if the 'unrar' utility is installed and accessible in the system's PATH.

```bash
# Check for unrar
which unrar
```

--------------------------------

### Authentication Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/api-testing.md

Example of how to make an API request when API key authentication is enabled, by including the 'X-Api-Key' header.

```bash
API_KEY="your-api-key-here"

curl -X GET http://localhost:6789/api/v1/downloads \
  -H "X-Api-Key: $API_KEY"
```

--------------------------------

### Post-processing Mode Example (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for setting the default post-processing mode in TOML.

```toml
default_post_process = "unpack_and_cleanup"

```

--------------------------------

### Query Capabilities via Rust

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example of how to query the capabilities endpoint from a Rust application.

```rust
let downloader = UsenetDownloader::new(config).await?;
let caps = downloader.capabilities();
println!("PAR2 repair available: {}", caps.parity.can_repair);
```

--------------------------------

### Query Capabilities via cURL

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example of how to query the capabilities endpoint using cURL.

```bash
curl http://localhost:8080/api/v1/capabilities
```

--------------------------------

### Direct Unpack Configuration (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for enabling direct unpacking and related settings.

```toml
[direct_unpack]
enabled = true
direct_rename = true
poll_interval_ms = 200
```

--------------------------------

### Direct Unpack Configuration (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for enabling direct unpacking and related settings.

```json
{
  "direct_unpack": {
    "enabled": true,
    "direct_rename": true,
    "poll_interval_ms": 200
  }
}
```

--------------------------------

### Get download status

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Fetches the status of a specific download by its ID.

```bash
curl http://localhost:6789/api/v1/downloads/1
```

--------------------------------

### ServerConfig TOML Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example of configuring multiple NNTP servers in TOML format for load distribution or backup.

```toml
[[servers]]
host = "news.primary.com"
port = 563
tls = true
username = "myuser"
password = "mypass"
connections = 10
priority = 0  # Lower = tried first
pipeline_depth = 10

[[servers]]
host = "news.backup.com"
port = 119
tls = false
connections = 5
priority = 10  # Higher = backup server
pipeline_depth = 10
```

--------------------------------

### RssFeedConfig TOML Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for an RSS feed with filters in TOML format.

```toml
[[rss_feeds]]
url = "https://indexer.example.com/rss"
check_interval = 900  # 15 minutes in seconds
category = "tv"
auto_download = true
priority = "normal"
enabled = true

[[rss_feeds.filters]]
name = "HD TV Shows"
include = ["1080p", "720p"]
exclude = ["CAM", "TS"]
min_size = 1073741824  # 1 GB
max_size = 10737418240  # 10 GB
# max_age = 86400  # 24 hours (optional)
```

--------------------------------

### Starting the REST API Server

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Rust code snippet showing how to start the usenet-dl REST API server, making it available for remote control.

```rust
use std::sync::Arc;
use usenet_dl::api::start_api_server;

let downloader = Arc::new(UsenetDownloader::new(config.clone()).await?);
let config = Arc::new(config);
start_api_server(downloader, config).await?;
```

--------------------------------

### RssFeedConfig JSON Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example configuration for an RSS feed with filters in JSON format.

```json
{
  "rss_feeds": [
    {
      "url": "https://indexer.example.com/rss",
      "check_interval": 900,
      "category": "tv",
      "filters": [
        {
          "name": "HD TV Shows",
          "include": ["1080p", "720p"],
          "exclude": ["CAM", "TS"],
          "min_size": 1073741824,
          "max_size": 10737418240,
          "max_age": null
        }
      ],
      "auto_download": true,
      "priority": "normal",
      "enabled": true
    }
  ]
}
```

--------------------------------

### ServerConfig JSON Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example of configuring multiple NNTP servers in JSON format for load distribution or backup.

```json
{
  "servers": [
    {
      "host": "news.primary.com",
      "port": 563,
      "tls": true,
      "username": "myuser",
      "password": "mypass",
      "connections": 10,
      "priority": 0,
      "pipeline_depth": 10
    },
    {
      "host": "news.backup.com",
      "port": 119,
      "tls": false,
      "connections": 5,
      "priority": 10,
      "pipeline_depth": 10
    }
  ]
}
```

--------------------------------

### Cleanup Configuration (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for automatic cleanup of intermediate files.

```json
{
  "cleanup": {
    "enabled": true,
    "target_extensions": ["par2", "PAR2", "nzb", "NZB", "sfv", "SFV", "srr", "SRR", "nfo", "NFO"],
    "archive_extensions": ["rar", "zip", "7z", "tar", "gz", "bz2"],
    "delete_samples": true,
    "sample_folder_names": ["sample", "Sample", "SAMPLE", "samples", "Samples", "SAMPLES"]
  }
}
```

--------------------------------

### API Server Configuration (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for the REST API server.

```toml
[api]
bind_address = "127.0.0.1:6789"
api_key = "secret123"  # Optional authentication
cors_enabled = true
cors_origins = ["*"]
swagger_ui = true

[api.rate_limit]
enabled = false
requests_per_second = 100
burst_size = 200
exempt_paths = ["/api/v1/events", "/api/v1/health"]
exempt_ips = ["127.0.0.1", "::1"]
```

--------------------------------

### Cleanup Configuration (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for automatic cleanup of intermediate files.

```toml
[cleanup]
enabled = true
target_extensions = ["par2", "PAR2", "nzb", "NZB", "sfv", "SFV", "srr", "SRR", "nfo", "NFO"]
archive_extensions = ["rar", "zip", "7z", "tar", "gz", "bz2"]
delete_samples = true
sample_folder_names = ["sample", "Sample", "SAMPLE", "samples", "Samples", "SAMPLES"]
```

--------------------------------

### Get All History

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/api-testing.md

Retrieves the complete download history.

```bash
curl -X GET http://localhost:6789/api/v1/history | jq .
```

--------------------------------

### API Server Configuration (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for the REST API server.

```json
{
  "api": {
    "bind_address": "127.0.0.1:6789",
    "api_key": "secret123",
    "cors_enabled": true,
    "cors_origins": ["*"],
    "swagger_ui": true,
    "rate_limit": {
      "enabled": false,
      "requests_per_second": 100,
      "burst_size": 200,
      "exempt_paths": ["/api/v1/events", "/api/v1/health"],
      "exempt_ips": ["127.0.0.1", "::1"]
    }
  }
}
```

--------------------------------

### Disk Space Configuration (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for enabling disk space checking with minimum free space and size multiplier.

```json
{
  "disk_space": {
    "enabled": true,
    "min_free_space": 1073741824,
    "size_multiplier": 2.5
  }
}
```

--------------------------------

### Pause download

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Pauses a specific download by its ID.

```bash
curl -X POST http://localhost:6789/api/v1/downloads/1/pause
```

--------------------------------

### Deobfuscation Configuration (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for enabling and setting minimum length for deobfuscation.

```json
{
  "deobfuscation": {
    "enabled": true,
    "min_length": 12
  }
}
```

--------------------------------

### Disk Space Configuration (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for enabling disk space checking with minimum free space and size multiplier.

```toml
[disk_space]
enabled = true
min_free_space = 1073741824  # 1 GB in bytes
size_multiplier = 2.5
```

--------------------------------

### Adding NZB from File

Source: https://github.com/jvz-devx/usenet-dl/blob/main/examples/README.md

Example of adding an NZB file to the download queue.

```rust
let download_id = downloader
    .add_nzb(
        "your-file.nzb".as_ref(),  // Update this path
        DownloadOptions::default(),
    )
    .await?;
```

--------------------------------

### Stream real-time events

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Connects to the event stream for real-time updates.

```bash
curl -N http://localhost:6789/api/v1/events
```

--------------------------------

### Post-Processing Options Configuration

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Defines default post-processing actions and sample deletion behavior.

```rust
use usenet_dl::config::{Config, DownloadConfig, PostProcess};

let config = Config {
    download: DownloadConfig {
        default_post_process: PostProcess::UnpackAndCleanup,
        delete_samples: true,
        ..Default::default()
    },
    ..Default::default()
};
```

--------------------------------

### Add NZB from URL

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Adds an NZB file to the download queue by providing its URL.

```bash
curl -X POST http://localhost:6789/api/v1/downloads/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/file.nzb", "options": {"category": "movies"}}'
```

--------------------------------

### Example Cleanup Configuration

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/post-processing.md

An example of how to set up the CleanupConfig within the main Config structure.

```rust
use usenet_dl::Config;
use usenet_dl::config::{ProcessingConfig, CleanupConfig};

let config = Config {
    processing: ProcessingConfig {
        cleanup: CleanupConfig {
            enabled: true,
            target_extensions: vec![
                "par2".to_string(),
                "nzb".to_string(),
                "sfv".to_string(),
            ],
            delete_samples: true,
            ..Default::default()
        },
        ..Default::default()
    },
    ..Default::default()
};
```

--------------------------------

### Deobfuscation Configuration (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for enabling and setting minimum length for deobfuscation.

```toml
[deobfuscation]
enabled = true
min_length = 12
```

--------------------------------

### Duplicate Detection Configuration (TOML)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example TOML configuration for enabling duplicate detection with specific actions and methods.

```toml
[duplicate]
enabled = true
action = "warn"
methods = ["nzb_hash", "job_name"]
```

--------------------------------

### Duplicate Detection Configuration (JSON)

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/configuration.md

Example JSON configuration for enabling duplicate detection with specific actions and methods.

```json
{
  "duplicate": {
    "enabled": true,
    "action": "warn",
    "methods": ["nzb_hash", "job_name"]
  }
}
```

--------------------------------

### Quick Start Commands

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/contributing.md

Commands to clone the repository, build the project, run tests, and build documentation using nix-shell.

```bash
# Clone the repository
git clone https://github.com/jvz-devx/usenet-dl.git
cd usenet-dl

# Build the project
nix-shell --run "cargo build"

# Run tests
nix-shell --run "cargo test"

# Run tests with output
nix-shell --run "cargo test -- --nocapture"

# Build documentation
nix-shell --run "cargo doc --no-deps --open"
```

--------------------------------

### Test Priority Changes

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/api-testing.md

Commands to change download priority and force immediate start.

```bash
DOWNLOAD_ID=1

# Set to low priority
curl -X PATCH "http://localhost:6789/api/v1/downloads/$DOWNLOAD_ID/priority" \
  -H "Content-Type: application/json" \
  -d '{"priority":"low"}'

# Set to high priority
curl -X PATCH "http://localhost:6789/api/v1/downloads/$DOWNLOAD_ID/priority" \
  -H "Content-Type: application/json" \
  -d '{"priority":"high"}'

# Force immediate start
curl -X PATCH "http://localhost:6789/api/v1/downloads/$DOWNLOAD_ID/priority" \
  -H "Content-Type: application/json" \
  -d '{"priority":"force"}'
```

--------------------------------

### Adding NZB from URL

Source: https://github.com/jvz-devx/usenet-dl/blob/main/examples/README.md

Example of adding an NZB from a URL to the download queue.

```rust
let download_id = downloader
    .add_nzb_url(
        "https://example.com/file.nzb",
        DownloadOptions::default(),
    )
    .await?;
```

--------------------------------

### Multiple NNTP Servers Configuration

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Configures multiple NNTP servers with priority-based failover.

```rust
let config = Config {
    servers: vec![
        ServerConfig {
            host: "primary.news.com".to_string(),
            port: 563,
            tls: true,
            username: Some("user".to_string()),
            password: Some("pass".to_string()),
            connections: 10,
            priority: 0,  // Tried first
            pipeline_depth: 10,
        },
        ServerConfig {
            host: "backup.news.com".to_string(),
            port: 563,
            tls: true,
            username: Some("user2".to_string()),
            password: Some("pass2".to_string()),
            connections: 5,
            priority: 1,  // Tried if primary fails
            pipeline_depth: 10,
        }
    ],
    ..Default::default()
};
```

--------------------------------

### Example Deobfuscation Configuration

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/post-processing.md

An example of how to set up the DeobfuscationConfig within the main Config structure.

```rust
use usenet_dl::Config;
use usenet_dl::config::{AutomationConfig, DeobfuscationConfig};

let config = Config {
    automation: AutomationConfig {
        deobfuscation: DeobfuscationConfig {
            enabled: true,
            min_length: 12,
        },
        ..Default::default()
    },
    ..Default::default()
};
```

--------------------------------

### Enable disk space checking

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Configures the downloader to check for available disk space before extraction.

```rust
use usenet_dl::config::{Config, ProcessingConfig, DiskSpaceConfig};

let config = Config {
    processing: ProcessingConfig {
        disk_space: DiskSpaceConfig {
            enabled: true,
            min_free_space: 1024 * 1024 * 1024, // 1 GB
            size_multiplier: 2.5,
        },
        ..Default::default()
    },
    ..Default::default()
};
```

--------------------------------

### Event Monitoring for Progress Tracking

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Rust code demonstrating how to subscribe to download events from UsenetDownloader and handle different event types like downloading, completion, and failure.

```rust
use usenet_dl::{UsenetDownloader, Config, Event};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let downloader = UsenetDownloader::new(config).await?;

    // Subscribe to events
    let mut events = downloader.subscribe();
    tokio::spawn(async move {
        while let Ok(event) = events.recv().await {
            match event {
                Event::Downloading { id, percent, speed_bps, .. } => {
                    println!("Download {}: {:.1}% @ {} MB/s",
                        id, percent, speed_bps / 1_000_000);
                }
                Event::Complete { id, path } => {
                    println!("Download {} complete: {:?}", id, path);
                }
                Event::Failed { id, stage, error, .. } => {
                    eprintln!("Download {} failed at {:?}: {}", id, stage, error);
                }
                _ => {}
            }
        }
    });

    // Add downloads...

    Ok(())
}
```

--------------------------------

### Event Subscription Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/architecture.md

Example of how consumers can subscribe to events emitted by the downloader.

```rust
let mut receiver = downloader.subscribe();
while let Ok(event) = receiver.recv().await {
    match event {
        Event::Downloading { id, percent, speed_bps, .. } => { /* handle progress */ }
        Event::Complete { id, .. } => { /* handle completion */ }
        _ => {}
    }
}
```

--------------------------------

### GET /api/v1/servers/test Response

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/server-testing.md

Example response for testing all configured servers.

```json
[
  [
    "news.server1.com",
    {
      "success": true,
      "latency": {"secs": 0, "nanos": 345678901},
      "error": null,
      "capabilities": {
        "posting_allowed": false,
        "max_connections": null,
        "compression": true
      }
    }
  ],
  [
    "news.server2.com",
    {
      "success": false,
      "latency": {"secs": 1, "nanos": 567890123},
      "error": "Authentication failed",
      "capabilities": null
    }
  ]
]
```

--------------------------------

### Server-Sent Events Subscription

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/api-testing.md

Example of how to subscribe to real-time events via Server-Sent Events (SSE) once implemented.

```bash
curl -N -H "Accept: text/event-stream" \
  http://localhost:6789/api/v1/events
```

--------------------------------

### POST /api/v1/servers/test Request

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/server-testing.md

Example request to test a specific server configuration.

```bash
curl -X POST http://localhost:6789/api/v1/servers/test \
  -H "Content-Type: application/json" \
  -d '{
    "host": "news.example.com",
    "port": 563,
    "tls": true,
    "username": "your_username",
    "password": "your_password",
    "connections": 10,
    "priority": 0
  }'
```

--------------------------------

### Add usenet-dl as a dependency in Cargo.toml

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/getting-started.md

Example TOML snippets for adding usenet-dl as a local path dependency or from a Git repository.

```toml
[dependencies]
usenet-dl = { path = "../usenet-dl" }
# or
usenet-dl = { git = "https://github.com/jvz-devx/usenet-dl" }
```

--------------------------------

### Example Real-World Test Session

Source: https://github.com/jvz-devx/usenet-dl/blob/main/tests/manual/server-testing.md

Demonstrates testing primary and backup NNTP servers using curl and jq, showing expected JSON responses.

```bash
# 1. Test primary server
$ curl -X POST http://localhost:6789/api/v1/servers/test \
  -H "Content-Type: application/json" \
  -d '{
    "host": "news.eweka.nl",
    "port": 563,
    "tls": true,
    "username": "myuser",
    "password": "mypass",
    "connections": 20,
    "priority": 0
  }' | jq '.'

{
  "success": true,
  "latency": {
    "secs": 0,
    "nanos": 156789012
  },
  "error": null,
  "capabilities": {
    "posting_allowed": false,
    "max_connections": null,
    "compression": true
  }
}

# 2. Test backup server
$ curl -X POST http://localhost:6789/api/v1/servers/test \
  -H "Content-Type: application/json" \
  -d '{
    "host": "news.usenetserver.com",
    "port": 563,
    "tls": true,
    "username": "myuser2",
    "password": "mypass2",
    "connections": 10,
    "priority": 1
  }' | jq '.'

{
  "success": true,
  "latency": {
    "secs": 0,
    "nanos": 234567890
  },
  "error": null,
  "capabilities": {
    "posting_allowed": false,
    "max_connections": null,
    "compression": false
  }
}

```

--------------------------------

### Unit Test Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/contributing.md

Example of a unit test for the `SpeedLimiter`.

```rust
#[tokio::test]
async fn test_speed_limiter_unlimited() {
    let limiter = SpeedLimiter::new(None);
    let start = Instant::now();
    limiter.acquire(1_000_000).await;
    assert!(start.elapsed() < Duration::from_millis(10));
}
```

--------------------------------

### Integration Test Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/contributing.md

Example of an integration test for the download and post-processing flow.

```rust
#[tokio::test]
async fn test_download_with_post_processing() {
    let temp_dir = tempfile::tempdir().unwrap();
    let config = Config {
        download: DownloadConfig {
            download_dir: temp_dir.path().to_path_buf(),
            ..Default::default()
        },
        ..Default::default()
    };
    let downloader = UsenetDownloader::new(config).await.unwrap();

    // Test full download and post-processing flow
}
```

--------------------------------

### Configuration Example

Source: https://github.com/jvz-devx/usenet-dl/blob/main/docs/architecture.md

Illustrates the structure of the configuration object with sensible defaults.

```rust
Config {
    servers: vec![],
    download: DownloadConfig {
        download_dir: "./downloads".into(),
        temp_dir: "./temp".into(),
        max_concurrent_downloads: 3,
        speed_limit_bps: None, // Unlimited
        default_post_process: PostProcess::UnpackAndCleanup,
        ..Default::default()
    },
    ..Default::default()
}
```