# Iskra
**A safe, modern, Rust-native data transfer tool.**
Iskra is a security-first, async-capable command-line and library tool for HTTP and data transfer. It aims to be a minimal, idiomatic, and robust alternative to cURL and HTTPie, with a user-friendly CLI and advanced features for modern workflows.
## Benchmarks
The following table shows Iskra's download performance (MB/s) for various file sizes and cache scenarios, measured on a local HTTP server and local disk. Each value is the best observed MB/s for that scenario (higher is better).
| 1GB | 26.24 | 37.39 | 35.94 |
| 500MB | 40.22 | 36.77 | 38.99 |
| 100MB | 37.84 | 31.01 | 39.39 |
| 1MB | 22.49 | 24.02 | 18.68 |
| 32KB | 5.88 | 4.35 | 4.13 |
- **No Cache:** Downloaded directly from the local HTTP server, no cache used.
- **Cold Cache:** First download with cache enabled (writes to cache and file).
- **Warm Cache:** Second/third download with cache enabled (reads from cache).
### Burst Mode Speed Test
The following test compares Iskra's burst mode (parallel) to sequential requests for 20 HTTP GETs to `https://httpbin.org/delay/1` (each request has a 1s server delay):
Speed Comparison (lower is better):
| Sequential | 31.66 | 1x |
| Burst (20x) | 2.01 | ~16x |
**Summary:** Burst mode achieves near-linear speedup for parallelizable requests, making it ideal for load testing, batch data collection, and high-throughput scenarios.
**Test setup:**
- Local HTTP server (Rust, hyper)
- Local disk cache (default temp dir)
- Windows, Rust async, single-threaded test
- Each file is validated for integrity (first, middle, last byte)
> **Note:** In some cases, "no cache" can be faster than "cold cache" or even "warm cache". This is because writing to both the output file and the cache file doubles disk I/O, and the OS may cache files in memory, making repeated reads or writes appear faster. For real-world remote transfers, or with a RAM disk, cache can provide a more significant speedup.
## Usage
### Installation
1. **Install with Cargo (recommended):**
- Open a terminal (PowerShell, Command Prompt, or Bash).
- To install the latest published version:
```powershell
cargo install iskra
```
- To build and install from source (in the repo root):
```powershell
cargo install --path .
```
- If you don't have Rust or Cargo, install them first from `https://rustup.rs`
2. **Add to PATH:**
- Make sure the Cargo bin directory is in your system `PATH` so you can run `iskra` from anywhere:
- **Windows:**
`%USERPROFILE%\.cargo\bin`
- **Linux/macOS:**
`$HOME/.cargo/bin`
- If you just installed Rust, you may need to restart your terminal or log out/in for the new `PATH` to take effect.
- To update your `PATH` for the current session only:
- **PowerShell:**
```powershell
$env:Path += ";$env:USERPROFILE\.cargo\bin"
```
- **Bash:**
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
3. **Test your install:**
```powershell
iskra --help
```
If you see the help text, you're ready to go!
The help command shows all available commands, options, and usage examples. For more details on a specific command, you can run:
```powershell
iskra <command> --help
```
For example:
```powershell
iskra post --help
```
This will display all options and usage for the `post` command. Use `--help` with any command to see its arguments and flags.
**Troubleshooting:**
- If `iskra` is not found, double-check your `PATH` and that the install completed successfully.
- On Windows, you may need to open a new terminal or restart your computer after changing `PATH`.
- If you see a permissions error, try running your terminal as administrator (Windows) or use `sudo` (Linux/macOS) for the install step.
### Updating Iskra
To update Iskra to the latest published version from crates.io, run:
**PowerShell/Windows:**
```powershell
cargo install iskra --force
```
**Bash/Linux/macOS:**
```bash
cargo install iskra --force
```
This will overwrite any previous version with the latest release. You can check your installed version with:
```powershell
iskra --version
```
or
```bash
iskra --version
```
**If you build from source (Git):**
First, update your local repository:
```bash
git pull
```
Then rebuild and install:
```bash
cargo install --path . --force
```
This will install the latest code from your local repository. Again, check your version with:
```bash
iskra --version
```
## Why Iskra?
**Why choose Iskra?**
- Security-first: Strict error handling, no unsafe code, validation for all edge cases.
- Performance: Async, streaming, and range-aware downloads for maximum speed and efficiency.
- Resumable & partial downloads: Advanced file-based cache with metadata, HTTP headers, and range support.
- Minimal dependencies: Small, modern Rust async stack.
- Cross-platform: Windows, Linux, macOS.
- User-friendly CLI: Intuitive, scriptable, and easy to use in any shell.
- Production-grade tests: All features are covered by stringent tests.
- Supports GET, POST, PUT, DELETE, and arbitrary HTTP methods (e.g. PATCH, OPTIONS), with custom headers, query parameters, output to file, status/exit code support, and configurable timeout.
- Advanced file-based cache, streaming writes, cache validation and reconstruction, overwrite/append/chunked/partial download support, automatic response decompression, progress bar, and more.
If you want a modern, safe, and fast HTTP tool that feels at home in your shell, Iskra is for you.
### Command Overview
Iskra supports the following commands:
#### GET (default)
```powershell
iskra get <url> [OPTIONS]
iskra <url> [OPTIONS] # 'get' is the default command
```
#### POST
```powershell
iskra post <url> [--body <data>] [OPTIONS]
```
#### PUT
```powershell
iskra put <url> [--body <data>] [OPTIONS]
```
#### DELETE
```powershell
iskra delete <url> [OPTIONS]
```
#### Custom HTTP Method
```powershell
iskra custom --method <METHOD> <url> [--body <data>] [OPTIONS]
```
#### HEAD (show metadata, compare, export, diff)
```powershell
iskra head <url> [OPTIONS]
```
### Common Options
| `-H`, `--header` | Add custom header (`-H "Key: Value"`). Repeatable. |
| `-Q`, `--query` | Add query parameter (`-Q "key=value"`). Repeatable. |
| `-o`, `--output` | Write response body to file instead of stdout. |
| `-r`, `--range` | Download byte range (`-r 0-499` for bytes 0-499). |
| `--resume` | Resume partial download (safe append/overwrite). |
| `-t`, `--timeout` | Set request timeout in seconds. |
| `--no-decompress` | Disable automatic response decompression. |
| `--fail` | Exit with error if HTTP status is not 2xx. |
| `--body` | Request body (for POST, PUT, custom methods). |
| `--compare <file>` | (HEAD) Compare response headers to those in <file> (JSON or text) |
| `--save-headers <file>` | (HEAD) Save response headers as pretty JSON to <file> |
| `--show-headers` | (HEAD) Show all headers (not just important ones) |
#### Examples
1. **Install with Cargo (recommended):**
- Open a terminal (PowerShell, Command Prompt, or Bash).
- To install the latest published version:
```powershell
cargo install iskra
```
- To build and install from source (in the repo root):
```powershell
cargo install --path .
```
- If you don't have Rust or Cargo, install them first from https://rustup.rs
2. **Add to PATH:**
- Make sure the Cargo bin directory is in your system `PATH` so you can run `iskra` from anywhere:
- **Windows:** `%USERPROFILE%\.cargo\bin`
- **Linux/macOS:** `$HOME/.cargo/bin`
- If you just installed Rust, you may need to restart your terminal or log out/in for the new `PATH` to take effect.
- To update your `PATH` for the current session only:
- **PowerShell:**
```powershell
$env:Path += ";$env:USERPROFILE\.cargo\bin"
```
- **Bash:**
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
3. **Test your install:**
```powershell
iskra --help
```
If you see the help text, you're ready to go!
The help command shows all available commands, options, and usage examples. For more details on a specific command, you can run:
```powershell
iskra <command> --help
```
For example:
```powershell
iskra post --help
```
This will display all options and usage for the `post` command. Use `--help` with any command to see its arguments and flags.
```powershell
Set-Alias iskra "$env:USERPROFILE\.cargo\bin\iskra.exe"
```
- **Bash (Linux/macOS):**
- Add to your `.bashrc` or `.zshrc`:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
alias iskra="$HOME/.cargo/bin/iskra"
```
- **Command Prompt (cmd.exe):**
- Add `%USERPROFILE%\.cargo\bin` to your system `PATH` via System Properties.
---
For more details, see `iskra --help` or the source code in `src/cli.rs`.
# Burst Mode: High-Performance Batch & Parallel HTTP
Iskra now supports a powerful `burst` subcommand for high-performance, parallel, and batch HTTP requests. Burst mode is ideal for:
- Load testing and benchmarking
- Batch data collection
- Parallel API calls
- Automated testing of endpoints
### Burst Features
- Parallel execution (configurable concurrency)
- Throttling (requests per second)
- Retries with backoff (exponential, jitter)
- Batch/template input (file or stdin)
- Per-request headers, queries, body, and output
- Output to files, directories, or stdout
- Aggregated summary reporting (success/fail/timing)
- Robust error handling and validation
### Usage
```powershell
iskra burst -i <input_file> [OPTIONS]
iskra burst -i - [OPTIONS] # Read from stdin
```
#### Common Burst Options
| `-i`, `--input` | Input file with batch/template requests (or '-' for stdin) |
| `-o`, `--output-dir` | Output directory for responses (optional) |
| `-c`, `--concurrency` | Number of parallel requests (default: 4) |
| `--throttle` | Throttle (max requests per second, optional) |
| `--retries` | Number of retries per request (default: 0) |
| `--backoff` | Backoff between retries in ms (default: 0) |
| `--summary` | Show summary report at end |
#### Input File Format
Each line describes a request:
```
METHOD URL [header:Key:Value ...] [query:key=value ...] [body:...] [output:filename]
```
Examples:
```
GET https://httpbin.org/get
POST https://httpbin.org/post body:hello
GET https://httpbin.org/get header:X-Test:Value query:foo=bar
GET https://httpbin.org/bytes/16 output:bytes16.bin
```
#### Real-World Examples
**Basic burst from file:**
```powershell
iskra burst -i burst_input.txt --summary
```
**Burst with concurrency, throttling, retries, and output dir:**
```powershell
iskra burst -i burst_input2.txt --output-dir out --concurrency 4 --throttle 2 --retries 2 --backoff 500 --summary
```
**Burst from stdin:**
```powershell
cat burst_input.txt | iskra burst -i - --summary
```
**Example input file:**
```
GET https://httpbin.org/get
POST https://httpbin.org/post body:hello
GET https://httpbin.org/status/404
GET https://httpbin.org/status/500
```
**Output and summary:**
All responses are written to files or stdout as specified. At the end, a summary is printed:
```
--- Burst Summary ---
[0] GET https://httpbin.org/get -> OK [200]
[1] POST https://httpbin.org/post -> OK [200]
[2] GET https://httpbin.org/status/404 -> FAIL [404]
Error: HTTP error: status 404
[3] GET https://httpbin.org/status/500 -> FAIL [500]
Error: HTTP error: status 500
---------------------
```
See the CLI help (`iskra burst --help`) for all options and usage details.
## Licence
MIT OR Apache-2.0