215 lines
10 KiB
Markdown
215 lines
10 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.
|
||
*Custom header* sends auth in a header of your choice (e.g. `X-API-Key`); the
|
||
request is marked with `# @auth-header X-API-Key` so reqlite knows that header
|
||
is its auth.
|
||
- **Folder auth:** right-click a folder → *Folder auth…* (or a collection →
|
||
*Default auth…*) to set auth that every request below it uses when it has no
|
||
`Authorization` header of its own. The nearest folder wins; a folder can also
|
||
say *None* to stop inheritance. In a request's Auth tab, *Inherit* (no
|
||
header) uses it and *None* opts out with `# @no-auth`. It is stored in
|
||
`<folder>/.reqlite/folder.json` as `{ "auth": "Bearer {{token}}" }`, or
|
||
`{ "auth": { "header": "X-API-Key", "value": "{{api_key}}" } }` for a custom
|
||
header (`null` = none); other `.http` tools ignore it. A request that already
|
||
sets the folder's custom header itself keeps its own value. The CLI applies it too.
|
||
- **Consolidate auth…** (same menus) removes auth headers that match
|
||
what the request would inherit. If the folder has no auth yet, it offers the
|
||
most used header as the folder's auth, and can pin requests that would
|
||
otherwise change (they get their current header, or `# @no-auth`).
|
||
- 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`; `# @no-auth` is one that
|
||
skips folder auth, and `# @auth-header <name>` marks a custom auth header.
|
||
- `#` 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. Folder auth is looked up from the file's folder upwards, up to
|
||
the folder with the env files (or the git root).
|
||
|
||
## 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.
|