Files
reqlite/README.md
T
2026-10-19 09:31:57 +02:00

185 lines
8.3 KiB
Markdown

# reqlite
A small, fast API client. Requests live in plain `.http` files (the JetBrains
HTTP Client / VS Code REST Client format), so collections are git-friendly and
open in your IDE too. Built in Rust with egui, libcurl and Tokio, following
[implementation-plan.md](implementation-plan.md).
- `reqlite-gui [folder]` is the desktop app.
- `reqlite` is the command line (`reqlite run api/users.http --env dev`).
## Building
Needs Rust (pinned in `rust-toolchain.toml`) and a C compiler; libcurl is built
from source and linked statically. On Windows the MSVC Build Tools are enough
(TLS uses Schannel). On Linux, TLS uses the system OpenSSL (`libssl-dev`).
```sh
cargo install --locked just cargo-deny # once
just check # fmt + clippy -D warnings + all tests + cargo deny
just release # target/release/reqlite-gui and target/release/reqlite
just run # start the GUI (debug build)
```
`just release-glow` builds the GUI with the OpenGL renderer instead of wgpu,
for old GPUs, VMs and remote desktops. `just install-hook` adds a git
pre-push hook that runs `just check`.
## Using it
Open a folder (**File → Open collection folder**). Every `.http` file in it
shows up in the sidebar as *folder → file → requests*. Click a request to open
it in a tab, edit it, and press **Ctrl+Enter** to send and **Ctrl+S** to save.
Saving only rewrites that request's bytes in the file; everything else, including
comments and response-handler scripts, stays as it was.
```http
### Create user
# @name create-user
POST {{base_url}}/users
Content-Type: application/json
Authorization: Bearer {{token}}
{ "name": "Ada" }
```
Environments come from `http-client.env.json` (committed) and
`http-client.private.env.json` (secrets, git-ignored) next to the `.http` files.
Pick one in the top bar; **Edit…** opens the environment editor. Variables are
green when defined and red when not; hover one to see its value (private values
show as `••••`). Lookup order: private env, public env, file variables
(`@name = value`), then built-ins (`{{$uuid}}`, `{{$timestamp}}`,
`{{$isoTimestamp}}`, `{{$randomInt}}`, `{{$randomInt 1 10}}`). The special
`$shared` environment applies to all environments.
Other things worth knowing:
- **Paste a curl command into the URL bar** to import it (Chrome/Firefox
"Copy as cURL" in bash, cmd or PowerShell form all work). **…** → *Copy as
curl* goes the other way.
- **File → Import Postman collection…** converts a v2.1 collection into a folder
of `.http` files plus `http-client.env.json`. Scripts are skipped and listed.
The CLI does the same: `reqlite import postman coll.json out/ --env env.json`.
- The **Source** tab shows the request as `.http` text; edits there and in the
form stay in sync.
- The **Auth** tab is a helper that writes the `Authorization` header. Basic
auth is written as `Basic user password` and encoded when sent, like JetBrains.
- Cookies are kept in memory per collection (**View → Cookies**);
`# @no-cookie-jar` skips them for one request.
- **View → History** lists sent requests; *Open* restores one into a new tab.
`# @no-log` keeps a request out of history.
- Large responses are spilled to a temp file above 5 MB and shown in a
virtualized viewer; **Ctrl+F** searches the body.
- Files changed outside the app (editor, `git pull`) are reloaded; if the open
tab has unsaved edits you are asked which version to keep.
| Shortcut | Action |
|---|---|
| Ctrl+Enter | Send |
| Ctrl+S | Save |
| Ctrl+T | New tab |
| Ctrl+W | Close tab |
| Ctrl+L | Focus the URL bar |
| Ctrl+P | Quick-open a request |
| Ctrl+F | Find in the response |
Settings (timeout, proxy, TLS verification, extra CA file, theme, font size)
are stored in the config directory (`~/.config/reqlite/settings.toml` on Linux,
`%APPDATA%\reqlite\config\settings.toml` on Windows). History and logs are in the
data directory. Set `REQLITE_LOG=debug` for verbose logs.
## The `.http` dialect
reqlite supports the subset that JetBrains and VS Code REST Client largely agree
on:
- `###` separators with an optional title; a request needs no separator if it
is the first in the file.
- `METHOD URL [HTTP/version]`, or a bare URL (GET). Query parameters may
continue on indented lines starting with `?`, `&` or `/`.
- Headers, a blank line, then the body. `# Name: value` is a disabled header.
- `{{var}}` placeholders, `\{{` for a literal `{{`.
- File variables: `@name = value`.
- Bodies from files: `< ./file` (sent as-is) and `<@ ./file` (variables
replaced).
- `multipart/form-data` bodies with a boundary, parts may be `< ./file`.
- Directives: `# @name`, `# @no-redirect`, `# @no-cookie-jar`, `# @no-log`,
`# @timeout 30` / `500 ms`, `# @connection-timeout`. `# @insecure` is a
reqlite extension written by curl import for `-k`.
- `#` and `//` comments.
Anything else (unknown directives, response handlers `> {% … %}` and
`> ./script.js`, `<> ./previous-response`) is kept verbatim and never run.
Request chaining (`{{create-user.response.body.$.id}}`) is not supported yet.
## Command line
```text
reqlite run <file.http> [--name NAME] [--env ENV] [-k] [--timeout SECS]
[--body-only] [--pretty] [--fail]
reqlite curl <file.http> [--name NAME] [--env ENV] # print as curl commands
reqlite import curl ['curl …'] # print as .http (stdin if omitted)
reqlite import postman <collection.json> <out-dir> [--env env.json]…
```
Without `--name`, `run` sends every request in the file in order, sharing one
cookie jar. Env files are taken from the nearest folder at or above the
`.http` file.
## Code layout
```
crates/core model, lossless .http parser/writer, templating, env files,
collections, cookies, curl/Postman import, curl export.
No UI, no network, no async runtime.
crates/http-curl libcurl HttpClient: spawn_blocking around Easy2, cancel via
the progress callback, temp-file spill, timings.
crates/app egui app: AppState, Action → update() → Effect, Tokio effects.
crates/cli the reqlite command.
tests/fixtures .http files, curl commands, Postman exports.
fuzz/ cargo-fuzz target for the parser (nightly).
```
The app follows the plan's data flow: UI panels only read `AppState` and push
`Action`s; `action::update` is a pure function that changes state and returns
`Effect`s; `effects::Runner` runs effects as Tokio tasks and sends results back
as actions over a channel, waking egui with `request_repaint`. Most behaviour is
tested by calling `update` directly (`crates/app/src/action/tests.rs`).
## Tests
`just check` runs everything below:
- **Parser:** snapshots of the syntax tree for every fixture, byte-identical
round trips, edit-only-touches-one-request checks, and a randomized test over
thousands of generated files (`REQLITE_FUZZ_CASES=300000` for a longer run).
- **Templating, env, cookies, import/export:** table-driven tests and snapshots
over real-world curl commands and Postman exports.
- **HTTP:** wiremock tests for every method and body type, redirects, timeout,
cancel mid-transfer (task ends within 200 ms), 20 concurrent requests, temp
file spill, and a TLS test with a fresh CA (fails by default, works with `-k`
or the CA file).
- **App:** `update()` tests (URL/params sync, send/receive/cancel, save writes
nothing when unchanged, external-change conflicts, collection operations …),
egui_kittest UI smoke tests with a fake client, a file-watcher test, and a
check that every symbol used in the UI exists in the bundled fonts.
- **CLI:** end-to-end against wiremock with env files and cookies.
`cargo test -p reqlite-app --test render -- --ignored` with
`REQLITE_RENDER_DIR=dir` renders screenshots of the real UI (needs a GPU or a
software Vulkan driver).
## Packaging
- **Linux:** `just package-linux` makes a tarball with both binaries, the icon
and a `.desktop` file. `cargo bundle --release -p reqlite-app` can make a
`.deb`.
- **Windows:** `just package-windows` makes a portable zip. The exe embeds the
icon and version info (`winresource`). For an MSI: `cargo install cargo-wix`,
then `cargo wix init -p reqlite-app` once and `cargo wix -p reqlite-app`.
Without code signing, SmartScreen shows a warning.
- **macOS:** `cargo bundle --release -p reqlite-app` makes a `.app`.
Releases are made by hand: run `just check` and the package recipe on each OS,
tag the commit, and upload the files.