# orange-opensource/hurl architecture

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

- Interactive diagram: https://gitdiagram.com/orange-opensource/hurl
- Repository: https://github.com/orange-opensource/hurl

## Overview

##### Project Type and Purpose
- Hurl is a command‐line HTTP testing and scripting tool written in Rust.
- It behaves like a small compiler/interpreter pipeline: it parses a custom “.hurl” file format, builds an AST, executes HTTP requests via libcurl, evaluates assertions, and emits test reports.
- It also includes a companion formatter (`hurlfmt`) and ships as a single binary requiring no runtime.

##### File Structure Overview and Architectural Patterns
- Top-level “packages” directory defines a Cargo workspace with three crates:
- `hurl_core`: the parser, AST, combinators and core text-format logic.
- `hurl`: the main CLI that depends on `hurl_core`. Contains a runner, HTTP client adapter, reporter modules, parallel engine, and main binary.
- `hurlfmt`: a second CLI that formats Hurl scripts, also depending on `hurl_core`.
- Support scripts and CI live in `bin/`, `.github/workflows/` and `contrib/`.
- Integration tests under `integration/`, unit tests under `packages/*/tests` enforce correctness at both library and binary levels.

##### Key Components
- **CLI Entrypoint** (`packages/hurl/src/main.rs` and `packages/hurlfmt/src/main.rs`): Command‐line argument parsing, global options, dispatch to either runner or formatter.
- **Parser & AST** (`packages/hurl_core`): Reads `.hurl` files (or directories), lexes and parses into an AST representing requests, options, captures, and asserts.
- **Runner** (`packages/hurl/src/runner` & `packages/hurl/src/run.rs`):
- Walks the AST, issues HTTP calls.
- Orchestrates retries, parallel execution (using a job queue), capturing of values, filter evaluation, and assertion checks.
- **HTTP Client Adapter** (`packages/hurl/src/http`):
- Wraps libcurl (via curl-sys) to perform HTTP calls with all cURL options (proxy, certificates, HTTP version selection).
- **Output & Reporting** (`packages/hurl/src/output` & `packages/hurl/src/report`):
- Raw or pretty‐printed CLI output.
- Test report generators: JSON, HTML, JUnit, TAP.
- **Formatter** (`hurlfmt` crate): Takes the same AST and re-serializes it into a canonical, linted or pretty format.
- **CI & Build Scripts** (`.github/workflows`, `bin/`): Automate building, testing, packaging, linting, and releasing.

##### Relationships and Data Flow
1. **User invokes** `hurl` or `hurlfmt` CLI with file(s) and options.
2. **CLI Entrypoint** parses command‐line flags, sets up global environment (variables, secrets, logging, file‐root).
3. **Parser** loads each `.hurl` file (or discovers recursively), lexes and builds an AST via `hurl_core`.
4. **Runner** iterates AST nodes:
- For each request node, it calls the **HTTP Client Adapter**, which issues the actual network call via libcurl.
- Responses flow back to the runner, which executes capture directives and assertion predicates.
- Captured values are stored in a variable context for later requests.
5. **Reporter** is updated with the outcome of each request/assert step.
6. Once all entries complete, a **Report Generator** emits the final text summary or serialized reports (JSON, HTML, JUnit, TAP) into the destination directory.
7. **Formatter** (when `hurlfmt` is invoked) similarly parses, applies rewrite rules (linters), and outputs formatted scripts.

##### Architectural Patterns and Design Principles
- **Clear separation of concerns**: parsing, execution, HTTP transport, reporting, formatting.
- **Library + multiple front-ends**: core parsing and AST logic lives in `hurl_core`, reused by both `hurl` and `hurlfmt`.
- **Modular plugins** for filters, JSONPath/XPath evaluation, reporters (JSON/TAP/HTML/JUnit), making it easy to extend.
- **Parallelism**: CLI test mode and `--parallel` run each file in isolation across threads/workers.
- **Configuration layering**: CLI flags, environment variables, per‐request `[Options]` sections.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Layer
  subgraph "Presentation Layer"
    CLI_HURL["CLI Entrypoint (hurl)"]:::binary
    CLI_HURLFMT["CLI Entrypoint (hurlfmt)"]:::binary
  end

  %% Domain Layer
  subgraph "Domain Layer"
    subgraph "Parser & AST"
      AST_DEFS["AST Definitions"]:::library
      PARSER_IMPL["Parser Implementation"]:::library
      CORE_LIB["Core Library Entry"]:::library
    end
    subgraph "Runner"
      RUN_ORCH["Execution Orchestrator"]:::library
      AST_WALKER["AST Walker & Request Runner"]:::library
    end
  end

  %% Infrastructure Layer
  subgraph "Infrastructure Layer"
    subgraph "HTTP Client Adapter"
      HTTP_CALL["Core HTTP Calls (libcurl)"]:::infrastructure
      HTTP_CLIENT["Client Abstraction"]:::infrastructure
      HTTP_OPTIONS["Curl Options"]:::infrastructure
      HTTP_ERROR["Curl Errors"]:::infrastructure
    end
    PARALLEL["Parallel Engine"]:::infrastructure
  end

  %% Output Layer
  subgraph "Output Layer"
    OUTPUT_MOD["Raw / Pretty-Print Output"]:::library
    REPORT_MOD["Report Generators"]:::library
  end

  %% Formatter Layer
  subgraph "Formatter (hurlfmt)"
    FORMAT_MODULE["AST-based Formatting"]:::library
    COMMAND_DISP["Command Dispatch"]:::library
    CLI_GLUE["CLI Glue & Options"]:::library
  end

  %% CI & Tests
  subgraph "CI & Build"
    GITHUB[".github/workflows"]:::ci
    BIN_DIR["bin/"]:::ci
  end
  subgraph "Tests"
    INTEGRATION["Integration tests"]:::ci
    UNIT["Unit tests"]:::ci
  end

  %% External Dependencies
  LIBCURL["libcurl"]:::external
  LIBXML2["libxml2"]:::external
  SERDE_JSON["serde_json"]:::external
  RAYON["rayon"]:::external

  %% Data Flow
  CLI_HURL -->|"parses flags"| AST_DEFS
  CLI_HURLFMT -->|"parses flags"| AST_DEFS

  AST_DEFS -->|"AST"| RUN_ORCH
  PARSER_IMPL --> RUN_ORCH
  CORE_LIB --> AST_WALKER

  RUN_ORCH -->|"spawn jobs"| PARALLEL
  PARALLEL --> RUN_ORCH

  AST_WALKER -->|"requests"| HTTP_CALL
  HTTP_CALL -->|"response"| AST_WALKER
  HTTP_CLIENT --> HTTP_CALL
  HTTP_OPTIONS --> HTTP_CALL
  HTTP_ERROR --> HTTP_CALL

  AST_WALKER -->|"events"| OUTPUT_MOD
  AST_WALKER -->|"data"| REPORT_MOD

  CLI_HURLFMT -->|"dispatch"| FORMAT_MODULE
  FORMAT_MODULE -->|"writes formatted scripts"| CLI_GLUE
  COMMAND_DISP --> FORMAT_MODULE

  OUTPUT_MOD --> SERDE_JSON
  REPORT_MOD --> SERDE_JSON
  AST_WALKER --> LIBXML2
  PARALLEL --> RAYON

  %% CI & Tests relations
  GITHUB --> CLI_HURL
  BIN_DIR --> CLI_HURL
  INTEGRATION --> CLI_HURL
  UNIT --> AST_DEFS
  UNIT --> RUN_ORCH
  UNIT --> FORMAT_MODULE

  %% Click Events
  click CLI_HURL "https://github.com/orange-opensource/hurl/blob/master/packages/hurl/src/main.rs"
  click CLI_HURLFMT "https://github.com/orange-opensource/hurl/blob/master/packages/hurlfmt/src/main.rs"
  click AST_DEFS "https://github.com/orange-opensource/hurl/tree/master/packages/hurl_core/src/ast/"
  click PARSER_IMPL "https://github.com/orange-opensource/hurl/tree/master/packages/hurl_core/src/parser/"
  click CORE_LIB "https://github.com/orange-opensource/hurl/blob/master/packages/hurl_core/src/lib.rs"
  click RUN_ORCH "https://github.com/orange-opensource/hurl/blob/master/packages/hurl/src/run.rs"
  click AST_WALKER "https://github.com/orange-opensource/hurl/tree/master/packages/hurl/src/runner/"
  click HTTP_CALL "https://github.com/orange-opensource/hurl/blob/master/packages/hurl/src/http/call.rs"
  click HTTP_CLIENT "https://github.com/orange-opensource/hurl/blob/master/packages/hurl/src/http/client.rs"
  click HTTP_OPTIONS "https://github.com/orange-opensource/hurl/blob/master/packages/hurl/src/http/options.rs"
  click HTTP_ERROR "https://github.com/orange-opensource/hurl/blob/master/packages/hurl/src/http/error.rs"
  click PARALLEL "https://github.com/orange-opensource/hurl/tree/master/packages/hurl/src/parallel/"
  click OUTPUT_MOD "https://github.com/orange-opensource/hurl/tree/master/packages/hurl/src/output/"
  click REPORT_MOD "https://github.com/orange-opensource/hurl/tree/master/packages/hurl/src/report/"
  click FORMAT_MODULE "https://github.com/orange-opensource/hurl/tree/master/packages/hurlfmt/src/format/"
  click COMMAND_DISP "https://github.com/orange-opensource/hurl/tree/master/packages/hurlfmt/src/command/"
  click CLI_GLUE "https://github.com/orange-opensource/hurl/tree/master/packages/hurlfmt/src/cli/"
  click GITHUB "https://github.com/orange-opensource/hurl/tree/master/.github/workflows/"
  click BIN_DIR "https://github.com/orange-opensource/hurl/tree/master/bin/"
  click INTEGRATION "https://github.com/orange-opensource/hurl/tree/master/integration/hurl/"
  click UNIT "https://github.com/orange-opensource/hurl/tree/master/packages/hurl/tests/"
  click UNIT "https://github.com/orange-opensource/hurl/tree/master/packages/hurl_core/tests/"
  click UNIT "https://github.com/orange-opensource/hurl/tree/master/packages/hurlfmt/tests_/"

  %% Styles
  classDef library fill:#cce5ff,stroke:#66b0ff,color:#004085
  classDef binary fill:#d4edda,stroke:#a3cfbb,color:#155724
  classDef external fill:#fff3cd,stroke:#ffecb5,color:#856404
  classDef infrastructure fill:#f8d7da,stroke:#f5c6cb,color:#721c24
  classDef ci fill:#e2e3e5,stroke:#d6d8db,color:#383d41
```
