# janko/down architecture

> Architecture diagram of the GitHub repository janko/down, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/janko/down
- Repository: https://github.com/janko/down

## Overview

##### Main Components
- Down API: At the center is the primary API functions (Down.download and Down.open) which client applications call.
- Backend Modules: Represent the three interchangeable backends:
- Down::NetHttp (default using open-uri/Net::HTTP)
- Down::Http (uses the http.rb gem)
- Down::Httpx (uses the HTTPx gem)
- Streaming Component: Down::ChunkedIO – this handles the on-demand, chunked downloading and provides an IO-like interface.
- Download Configuration/Options: Components for handling options such as max file size, destination, authentication, headers, timeouts, etc.
- Error Handling: The custom exception hierarchy (e.g., Down::Error and its subclasses like Down::TooLarge, Down::InvalidUrl, etc.) that isolate and re-raise errors from different backends.

##### Relationships and Interactions
- The Down API delegates download and streaming requests to the configured backend.
- From each backend module, include a link showing dependency on underlying HTTP libraries or Ruby standard libraries (e.g., open-uri/Net::HTTP for Down::NetHttp, HTTP.rb for Down::Http, and HTTPx for Down::Httpx).
- For streaming operations, show Down::ChunkedIO being constructed by Down.open including options like caching vs. non-caching and wrapper over enumerators.

##### Important Architectural Patterns
- Separation of Concerns: The core “Down” module acts as a facade, abstracting away the details of the individual HTTP implementations.
- Configuration Flexibility: Backends are configurable, either by selecting one per method call or setting one globally.
- Exception Wrapping: Illustrate that all errors from low-level HTTP calls are caught and re-raised as Down-specific errors.

h. Optionally, include examples of parameters such as "max_size", "destination", and settings specific to each HTTP gem, perhaps as small callouts near each backend module.

##### Final Touches
- Every component is clearly labeled with concise text.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and API
    CA("Client Application"):::client
    API("Down API"):::api
    CA -->|"calls"| API

    %% Download Options & Configuration
    CONFIG("Download Options & Config"):::config
    API -- "config_options" --> CONFIG
    CONFIG -- "provides_options" --> API

    %% Backend Modules
    subgraph "Backend Modules"
        NET("Down::NetHttp\n(open-uri, Net::HTTP)"):::backend
        HTTP("Down::Http\n(HTTP.rb)"):::backend
        HTTPX("Down::Httpx\n(HTTPx)"):::backend
    end

    API -->|"delegates_to"| NET
    API -->|"delegates_to"| HTTP
    API -->|"delegates_to"| HTTPX
    CONFIG -->|"passed_to"| NET
    CONFIG -->|"passed_to"| HTTP
    CONFIG -->|"passed_to"| HTTPX

    %% Underlying Dependencies for each backend
    NET_dep("open-uri/Net::HTTP"):::dep
    HTTP_dep("HTTP.rb"):::dep
    HTTPX_dep("HTTPx"):::dep

    NET -->|"uses"| NET_dep
    HTTP -->|"uses"| HTTP_dep
    HTTPX -->|"uses"| HTTPX_dep

    %% Streaming Component: Down::ChunkedIO
    CHUNK("Down::ChunkedIO"):::streaming
    API -->|"returns_stream"| CHUNK

    %% Error Handling Component
    ERR("Down::Error Hierarchy"):::error
    NET -->|"wraps_errors_in"| ERR
    HTTP -->|"wraps_errors_in"| ERR
    HTTPX -->|"wraps_errors_in"| ERR

    %% Style Definitions
    classDef api fill:#A0D8F1,stroke:#333,stroke-width:2px
    classDef backend fill:#B3E283,stroke:#333,stroke-width:2px
    classDef streaming fill:#FFD699,stroke:#333,stroke-width:2px
    classDef error fill:#F1A0A0,stroke:#333,stroke-width:2px
    classDef config fill:#D1C4E9,stroke:#333,stroke-width:2px
    classDef client fill:#E6E6FA,stroke:#333,stroke-width:2px
    classDef dep fill:#C0C0C0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5

    %% Click Events for Component Mapping
    click API "https://github.com/janko/down/blob/master/lib/down.rb"
    click NET "https://github.com/janko/down/blob/master/lib/down/net_http.rb"
    click HTTP "https://github.com/janko/down/blob/master/lib/down/http.rb"
    click HTTPX "https://github.com/janko/down/blob/master/lib/down/httpx.rb"
    click CHUNK "https://github.com/janko/down/blob/master/lib/down/chunked_io.rb"
    click ERR "https://github.com/janko/down/blob/master/lib/down/errors.rb"
```
