How orange-opensource/hurl works
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.