185 lines
8.3 KiB
Markdown
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.
|