DOCSEARCHbyAlgolia
Submit Docs

Swaparr Documentation

repository·main·Indexed 18 days ago

https://github.com/thijmengthn/swaparr

A background utility designed to automatically detect and remove stalled downloads from Starr applications such as Radarr, Sonarr, Lidarr, Readarr, and Whisparr. Swaparr uses a strike-based evaluation system to monitor active downloads at configurable intervals and removes items that accumulate a maximum number of strikes based on thresholds for download time and file size.

Tokens
6.1K
Snippets
19
Records
24
Agent score
61%

What's inside Swaparr

  1. What is Swaparr and how does it work?

    main

    Swaparr is a background utility designed to handle stalled downloads in 'Starr' instances (like Radarr or Sonarr).

    It operates using a Strike System:

    1. Automatic Detection: Swaparr scans active downloads in your Starr instances at a configurable interval (default: 10 minutes).
    2. Strikes: If a download is identified as potentially stalled, it is given a 'strike'.
    3. Removal: If a download accumulates the maximum allowed strikes (MAX_STRIKES), Swaparr automatically removes it from the instance to allow for fresh attempts.

  2. Understand Swaparr download status types

    main

    Swaparr categorizes downloads into several status types to indicate their current state in the monitoring lifecycle:

    • Normal: Download is proceeding as expected; no issues detected.
    • Striked: Download flagged as slow or stalled; may be removed if it continues to accumulate strikes.
    • Removed: Download has been attempted to be removed from the starr instance.
    • Ignored: Download is not monitored because it falls outside the set thresholds (e.g., size or time limits).
    • Queued: Download is in the queue within the download client waiting to start; will not be striked.
    • Delayed: Download is temporarily paused or scheduled for later processing as defined in a delay profile.
    • Completed: Download has finished and is seeding; will not be striked.
    | **Status** | **Description**                                                                                    |
|------------|----------------------------------------------------------------------------------------------------| 
| `Normal`   | Download is proceeding as expected; no issues detected.                                            |
| `Striked`  | Download flagged as slow or stalled; may be removed if it continues to accumulate strikes.         |
| `Removed`  | Download has been attempted to be removed from the starr instance.                                 |
| `Ignored`  | Download is not monitored because it falls outside the set thresholds (e.g., size or time limits). |
| `Queued`   | Download is in the queue within the download client waiting to start; will not be striked.          |
| `Delayed`  | Download is temporarily paused or scheduled for later processing as defined in a delay profile.    |
| `Completed`| Download has finished and is seeding; will not be striked.                                         |

  3. Stop and Update Swaparr

    main

    Stop Swaparr

    To shut down the Swaparr services:

    docker compose down

    Update Swaparr

    To update to the latest version, pull the new images and restart the services:

    docker compose pull
    docker compose down
    docker compose up -d

  5. How Swaparr operates

    main

    Swaparr is a continuous background process that monitors a task queue and processes items based on a configured scan interval.

    Its execution lifecycle follows these steps:

    1. Initialization: Loads system environment variables and parses API endpoints (baseapi and queueapi).
    2. Health Check: Performs an initial API health check.
    3. Monitoring Loop:
      • Fetches items from the queue.
      • Updates a local health file at /tmp/swaparr.health (writing 1 if the API is reachable, 0 otherwise).
      • Cleans up the internal strikelist (tracking active downloads).
      • Processes the fetched queue items.
      • Sleeps for the duration specified by scan_interval before the next iteration.

    If the scan_interval configuration is invalid, the application defaults to a sleep duration of 10 minutes (600,000 ms).

  6. Configure Swaparr environment variables

    main

    Swaparr is configured via environment variables within a Docker Compose service definition. Each service instance corresponds to one Starr platform (e.g., one service for Radarr, one for Sonarr).

    Required Variables

    • BASEURL: The IP address or FQDN of your Starr instance (e.g., http://127.0.0.1:7878).
    • APIKEY: The API key for the specific Starr instance.
    • PLATFORM: The type of instance being managed (e.g., radarr, sonarr, lidarr, readarr, whisparr). Defaults to radarr.

    Optional Variables

    • MAX_STRIKES: The number of strikes allowed before a download is removed. (Default: 3)
    • SCAN_INTERVAL: How often to scan downloads (e.g., 1d, 6h, 30m). (Default: 10m)
    • MAX_DOWNLOAD_TIME: The threshold for considering a download stalled. (Default: 2h)
    • IGNORE_ABOVE_SIZE: Files larger than this will be ignored (e.g., 1TB, 1GB, 25GB). (Default: 25GB)
    • REMOVE_FROM_CLIENT: Boolean determining if Swaparr should remove the download from the client. (Default: true)
    • STRIKE_QUEUED: Boolean to determine if strikes are queued. (Default: false)
    • DRY_RUN: Boolean to run in simulation mode without performing removals. (Default: false)
    services:
  radarr:
    image: ghcr.io/thijmengthn/swaparr:latest
    container_name: swaparr-radarr
    restart: unless-stopped
    environment:
      - BASEURL=http://127.0.0.1:7878
      - APIKEY=your_api_key_here
      - PLATFORM=radarr
      - MAX_STRIKES=3
      - SCAN_INTERVAL=10m
      - MAX_DOWNLOAD_TIME=2h
      - IGNORE_ABOVE_SIZE=25GB
      - REMOVE_FROM_CLIENT=true
      - STRIKE_QUEUED=false
      - DRY_RUN=false

  7. Configure Swaparr using environment variables

    main

    Swaparr is configured via environment variables. You can specify connection details for your Starr instance (Radarr, Sonarr, etc.) and tune the monitoring behavior such as scan intervals, strike limits, and size thresholds.

    Connection Settings

    • BASEURL: The URL of your Starr instance (default: http://127.0.0.1:7878).
    • APIKEY: The API key for your Starr instance.
    • PLATFORM: The type of Starr platform being used. Supported values: radarr, sonarr, lidarr, readarr, or whisparr (default: radarr).

    Monitoring & Strike Logic

    • MAX_STRIKES: Maximum strikes a download can accumulate before removal (default: 3).
    • SCAN_INTERVAL: Frequency of stalled download checks (default: 10m).
    • MAX_DOWNLOAD_TIME: Time threshold before a download is considered stalled (default: 2h).
    • IGNORE_ABOVE_SIZE: Files larger than this size are ignored (default: 25GB).
    • STRIKE_QUEUED: If true, queued downloads are eligible for strikes (default: false).
    • REMOVE_FROM_CLIENT: If true, removes from both the queue and the download client. If false, only removes from the Starr instance queue (default: true).

    Operational Modes

    • DRY_RUN: When true, Swaparr runs in sandbox mode and performs no destructive actions (default: false).
    | Name               | Default                 | Description                                                                                         |
|--------------------|-------------------------|-----------------------------------------------------------------------------------------------------|
| BASEURL            | `http://127.0.0.1:7878` | The URL of a radarr, sonarr or other starr instance.                                                |
| APIKEY             | `7f3a8..cbc07`          | The API key of a radarr, sonarr or other starr instance.                                            |
| PLATFORM           | `radarr`                | Indicates the type of starr platform, either `radarr`, `sonarr`, `lidarr`, `readarr` or `whisparr`. |
| MAX_STRIKES        | `3`                     | Maximum number of strikes a download can accumulate before it is removed.                         |
| SCAN_INTERVAL      | `10m`                   | How often Swaparr checks for stalled downloads.                                                    |
| MAX_DOWNLOAD_TIME  | `2h`                     | Maximum allowed download time before it's considered stalled.                                     |
| IGNORE_ABOVE_SIZE  | `25GB`                   | Files larger than this size will be ignored and not monitored.                                    |
| REMOVE_FROM_CLIENT | `true`                  | Remove from both queue and download client (default) OR `false` only the queue of a starr instance. |
| STRIKE_QUEUED      | `false`                 | When enabled, queued downloads are eligible to be striked instead of being bypassed.                |
| DRY_RUN            | `false`                 | Sandbox mode; try Swaparr without it performing destructive actions on your instances.              |

  8. Configure Swaparr via environment variables

    main

    Swaparr is configured using environment variables. Some variables are mandatory, while others have default values if they are undefined or invalid.

    Mandatory Variables

    • APIKEY: Required. The application will exit with a fatal error if this is not set.

    Optional Variables

    Many optional variables support legacy names for backwards compatibility.

    VariableDefaultDescription / Format
    BASEURLhttp://127.0.0.1:7878The base URL of the service.
    PLATFORMradarrThe target platform.
    MAX_STRIKES3Also accepts STRIKE_THRESHOLD. Max number of strikes.
    MAX_DOWNLOAD_TIME2hAlso accepts TIME_THRESHOLD. Must use time notation (e.g., 1d, 6h, 30m).
    IGNORE_ABOVE_SIZE25 GBAlso accepts SIZE_THRESHOLD. Must use bytesize notation (e.g., 1TB, 1GB, 1MB).
    SCAN_INTERVAL10mAlso accepts CHECK_INTERVAL. Must use time notation (e.g., 1d, 6h, 30m).
    REMOVE_FROM_CLIENTtrueBoolean string (true/false).
    DRY_RUNfalseBoolean string (true/false).
    STRIKE_QUEUEDfalseBoolean string (true/false).

    Validation Rules

    The following variables must follow specific notation formats or the application will exit with a fatal error:

    • MAX_DOWNLOAD_TIME and SCAN_INTERVAL: Must be valid time notation (e.g., 1d, 6h, 30m).
    • IGNORE_ABOVE_SIZE: Must be valid bytesize notation (e.g., 1TB, 1GB, 1MB).

  9. Configure Swaparr via environment variables

    main

    Swaparr is deployed using the ghcr.io/thijmengthn/swaparr:latest image. Configuration is managed through environment variables. You can run separate containers for Radarr and Sonarr by adjusting the PLATFORM variable and the corresponding BASEURL and APIKEY.

    services:
  radarr:
    image: ghcr.io/thijmengthn/swaparr:latest
    container_name: swaparr-radarr
    restart: unless-stopped
    environment:
      - BASEURL=http://127.0.0.1:7878
      - APIKEY=your_radarr_api_key
      - PLATFORM=radarr
      - MAX_STRIKES=3
      - SCAN_INTERVAL=10m
      - MAX_DOWNLOAD_TIME=2h
      - IGNORE_ABOVE_SIZE=25GB
      - REMOVE_FROM_CLIENT=true
      - DRY_RUN=false

  10. Monitor Swaparr logs

    main

    To track download processing and view console logs, use the Docker Compose logs command.

    To view logs for a specific platform, provide its container_name:

    docker compose logs <container_name>

    To view logs for all running Swaparr platforms simultaneously, omit the container name:

    docker compose logs

  11. Convert strings to booleans

    main

    The string_to_bool function converts a String to a bool. It is case-insensitive and only accepts "true" or "false" (as ASCII lowercase). Any other value returns an Err containing the original string.

    let val = string_to_bool(String::from("TRUE")); // Ok(true)
let err = string_to_bool(String::from("maybe")); // Err("maybe")

  12. Render table content to the console

    main

    The render function takes a reference to a vector of TableContent structs and prints a formatted, rounded table to the standard output. If the provided vector is empty, it calls utils::log::empty() instead of printing a table. This is used for displaying structured data in the terminal.

    use crate::libs::table::{render, TableContent;

let contents = vec![TableContent {
    strikes: "example".to_string(),
    state: "active".to_string(),
    name: "example_name".to_string(),
    size: "10GB".to_string(),
    eta: "2h".to_string(),
}];

render(&contents);