Files
Torbjörn Molin 1e7f8678eb
windows / build (push) Successful in 5m0s
Added custom auth support
2026-11-09 12:56:54 +01:00

215 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.