- Keep several collections open at once. Each has its own environments, selected environment, cookie jar and file watcher, and they are reopened on start. The environment picker acts on the current collection (the active tab's, or the one last chosen). Overlapping folders are refused. - Close all / close others for tabs (Ctrl+Shift+W, tab menu, File menu), asking once about tabs with unsaved changes. - Rename a request from its tab (double-click, tab menu, or the … menu). - Give the tab strip's scroll bar its own row so it no longer covers the tab names. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
197 lines
9.0 KiB
Markdown
197 lines
9.0 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" }
|
||
```
|
||
|
||
You can keep several collections open; each gets its own section in the
|
||
sidebar (**Open…** adds one, **×** closes it), and they are reopened on the next
|
||
start. A collection has its own environments, selected environment, cookies and
|
||
file watcher. The environment picker in the top bar belongs to the *current*
|
||
collection: the active tab's, or for a new untitled tab, the one you last
|
||
clicked or opened a request from. Folders that contain each other can't be open
|
||
at the same time.
|
||
|
||
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`.
|
||
- Rename a request by double-clicking its tab, from the tab's or sidebar's
|
||
right-click menu, or **…** → *Rename…*. Right-clicking a tab also offers
|
||
*Close others* and *Close all*.
|
||
- 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+Shift+W | Close all tabs |
|
||
| 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.
|