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).

File Size	No Cache	Cold Cache	Warm Cache
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.66s |######################################## Burst: 2.01s |###

Mode	Total Time (s)	Speedup
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

Install with Cargo (recommended):
- Open a terminal (PowerShell, Command Prompt, or Bash).
- To install the latest published version:
```
cargo install iskra
```
- To build and install from source (in the repo root):
```
cargo install --path .
```
- If you don't have Rust or Cargo, install them first from https://rustup.rs
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:
```
$env:Path += ";$env:USERPROFILE\.cargo\bin"
```
  - Bash:
```
export PATH="$HOME/.cargo/bin:$PATH"
```
Test your install:
```
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:
```
iskra <command> --help
```
For example:
```
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:

cargo install iskra --force

Bash/Linux/macOS:

cargo install iskra --force

This will overwrite any previous version with the latest release. You can check your installed version with:

iskra --version

iskra --version

If you build from source (Git):

First, update your local repository:

git pull

Then rebuild and install:

cargo install --path . --force

This will install the latest code from your local repository. Again, check your version with:

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)

iskra get <url> [OPTIONS]
iskra <url> [OPTIONS]  # 'get' is the default command

POST

iskra post <url> [--body <data>] [OPTIONS]

PUT

iskra put <url> [--body <data>] [OPTIONS]

DELETE

iskra delete <url> [OPTIONS]

Custom HTTP Method

iskra custom --method <METHOD> <url> [--body <data>] [OPTIONS]

Common Options

Option	Description
`-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).

Examples

Install with Cargo (recommended):
- Open a terminal (PowerShell, Command Prompt, or Bash).
- To install the latest published version:
```
cargo install iskra
```
- To build and install from source (in the repo root):
```
cargo install --path .
```
- If you don't have Rust or Cargo, install them first from https://rustup.rs
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:
```
$env:Path += ";$env:USERPROFILE\.cargo\bin"
```
  - Bash:
```
export PATH="$HOME/.cargo/bin:$PATH"
```
Test your install:
```
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:
```
iskra <command> --help
```
For example:
```
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.
```
Set-Alias iskra "$env:USERPROFILE\.cargo\bin\iskra.exe"
```

Bash (Linux/macOS):

Add to your .bashrc or .zshrc:

 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

iskra burst -i <input_file> [OPTIONS]
iskra burst -i - [OPTIONS]  # Read from stdin

Common Burst Options

Option	Description
`-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:

iskra burst -i burst_input.txt --summary

Burst with concurrency, throttling, retries, and output dir:

iskra burst -i burst_input2.txt --output-dir out --concurrency 4 --throttle 2 --retries 2 --backoff 500 --summary

Burst from stdin:

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 ---
Total: 4 | Success: 2 | Fail: 2
Avg Time: 456.14ms | Total Time: 1.37s
[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

iskra 0.4.0

Iskra

Benchmarks

Burst Mode Speed Test

Usage

Installation

Updating Iskra

Why Iskra?

Command Overview

GET (default)

POST

PUT

DELETE

Custom HTTP Method

Common Options

Examples

Burst Mode: High-Performance Batch & Parallel HTTP

Burst Features

Usage

Common Burst Options

Input File Format

Real-World Examples

Licence