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

10 KiB
Raw Permalink Blame History

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.

  • 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).

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.

### 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

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 Actions; action::update is a pure function that changes state and returns Effects; 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.