# 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).
**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]
```
### 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). |
#### 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`.
## Licence
MIT OR Apache-2.0