# IDEA.md – an HTTP client of your own for the desktop This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on what was learned building Requester, an app for Windows and macOS written in Rust with Claude Code. ## 1. What to build An HTTP client for sending requests to APIs and inspecting the responses, in the same spirit as Postman, Insomnia and Bruno – one program for Windows and macOS, without an account, with collections as ordinary files. The app must be able to: - **compose a request**: method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS and custom verbs), URL, tables for params and headers with a checkbox per row, and a body as none, raw (JSON/XML/HTML/text), form-urlencoded or multipart (text and files). The URL field and the params table are synced both ways. - **send and cancel**: Ctrl/Cmd+Enter, Enter in the URL field or the button; while sending, Cancel, a spinner and the elapsed time. - **show the response** with the status in colour (2xx/3xx/4xx/5xx), time and size, and tabs for the body (pretty with colours and raw, search, copy, save to file, image preview, binary as type and size), headers as a table and cookies parsed from `Set-Cookie`. - **collections on disk**: a collection is a directory, a folder a subdirectory and a request a JSON file. A tree in the sidebar with create, rename, duplicate, move (drag) and delete, and tabs for open requests marked when unsaved. - **environments and variables**: `{{name}}` in the URL, params, headers, body and auth; collection variables, environments and environment collections that can be linked to a collection or folder; secret variables shown masked; the resolved URL below the URL field. - **auth**: None, Basic, Bearer, API key (header or query), OAuth2 client credentials and Inherit from the folder or collection. - **import OpenAPI** 3.0 and 3.1 (JSON and YAML, file or URL) into a collection. - **cURL** both ways, **history**, **settings per request** (timeout, redirects, TLS verification), two layouts (the response below or to the right) and **export/import of everything** in one JSON file. **Not** included: pre- and post-request scripts, test assertions, GraphQL, WebSocket, gRPC, cloud sync and accounts, Swagger 2.0, external `$ref` and OAuth2 flows other than client credentials. ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **Rust**, a workspace with a core without an interface (`core`: model, HTTP, storage, variables, auth, OpenAPI, cURL, history) and the app (eframe/egui). The logic must be testable without a window. - **reqwest with rustls**, not native-tls: the same TLS behaviour on both platforms. Verify certificates against the system store (`rustls-platform-verifier`), so company CAs work. - **The crypto is `ring`, not `aws-lc`.** aws-lc compiles C that needs the Windows SDK headers. ring contains C too – check Windows with `cargo xwin check`, not `cargo check --target`. - **Important: networking on its own tokio runtime, never on the UI thread.** `send` returns a pending response that the interface polls every frame, and the network thread wakes the interface when the response has arrived. Cancel = abort the task. - reqwest decides redirects and TLS verification per client: keep one client per combination of settings. - Settings, the session (open tabs), window sizes, history and secret values in the user's config directory – never in the collection. ## 3. Decisions that turned out to matter **The file format.** A collection is a directory with `collection.json` (name, auth, variables), each folder a subdirectory with `folder.json`, each request a JSON file. File names are derived from the name (`List users` → `list-users.json`, non-ASCII letters kept, clashes get `-2`), but the display name lives in the file so `/` and `?` work. Folders first, then requests, in alphabetical order. Write atomically (temporary file + rename). A broken file shows as an error in the tree and the rest loads. Deleting goes to the trash. **Secrets stay on the computer.** Secret variables are never written to the collection's files. They're stored locally keyed by the collection's (or environment collection's) path, so the collection can be checked in. **Variables in three layers.** The collection's variables, then the linked environment collection's shared ones, then the selected environment – a later one wins. A variable can refer to another, up to 10 levels deep. Known variables are green, unknown ones red, and an unknown one is sent as written so the server shows what was missing. **Environment collections.** A file `.environments.json` with shared variables and several environments. It can live anywhere and be linked to a collection or folder with a relative path in `collection.json`/`folder.json`. The nearest link upwards applies. **Every request is sent on its own.** No cookie jar and no token cache between requests: an earlier request must never affect the next. The only cookie sent is a `Cookie` header in the request, and OAuth2 fetches a new token on every send. Connections (keep-alive, TLS sessions) may be reused – they don't change what is sent. **What's written is what's sent.** Sync the URL and params without decoding. Disabled rows live only in the table and survive editing the URL. A custom `Content-Type` wins over the automatic one. All four body modes are kept at once, so switching mode empties nothing. **OpenAPI as a generic JSON tree.** Read 3.0 and 3.1 without typed models and follow `$ref` within the document. One folder per tag, one request per operation (summary, operationId or "METHOD /path"). `servers[0]` becomes `baseUrl` in an environment – and **a relative server is resolved against the URL the definition was fetched from**. Parameters get an example, default or first enum; required ones on, optional ones off. The body from an example or generated from the schema (allOf merged, oneOf/anyOf take the first, readOnly skipped, stop recursion after a few levels). Security schemes become auth, and the placeholders (`{{bearerToken}}`, `{{apiKey}}` …) become secret variables. Whatever can't be imported is listed in the result dialog. **cURL.** Copy as cURL gives the request *as it is sent* (variables and inherited auth resolved), quoted for the shell. A cURL command pasted into the URL field becomes a request. Unknown flags give an error instead of a silently wrong request. **The session survives a restart.** Save the open tabs with unsaved changes to a file of their own, atomically and at most every 500 ms. A tab whose file has disappeared becomes unsaved but keeps its content. **Developer hooks from day one**: `_CONFIG_DIR` (a separate settings directory), `_SCREENSHOT=file.png` from the real window, `_WINDOW`, and `_DEBUG_STATE` that sets up a state at startup (method, URL, body, tab, collection, open a request, choose an environment, send, open a dialog). Parts separated by `;`, since URLs and JSON contain commas. ## 4. Pitfalls - **In egui the widget registered last wins.** A tab frame that registers its click after its content takes the click from the ×. A drag area on top of a button swallows the right-click – make the button itself draggable. - **Give table rows fixed ids**, or the text cursor loses focus when the empty row at the bottom becomes a real row. - **A panel remembers the height its content took.** An empty tab shrinks the panel to a strip. Let the content fill the panel's height whatever the tab. - **Don't forget eframe's `links` feature.** With `default-features = false`, `ctx.open_url` does nothing. - **Draw characters that aren't in egui's font** (●, arrows) instead of writing them – otherwise they become empty boxes. - **On macOS the system menu takes the ⌘ keys before egui.** Add no Edit menu with the system's Cut/Copy/Paste, and no menu shortcuts without a modifier. - **No screenshot arrives while the screen is asleep** – the window is never presented. Give up after a timeout, and keep a rendering without a screen (`egui_kittest` with wgpu) as a fallback. Ask for the image again every 20th frame until it arrives. - **Never let the tests touch the user's settings** or trash – their own config directory and permanent deletion in the tests. - **Don't build in a `target/` on a Windows drive from WSL**, and write screenshots from the Windows exe to a directory Windows can reach. ## 5. Requirements and measurements - GitHub's REST definition (10 MB YAML, 1,242 operations) should parse in around 185 ms and be written as a collection in around 145 ms. - A formatted JSON response of a few MB must not take seconds – optimise the dependencies in the debug build too. - Requester has just over a hundred tests: the core, HTTP against a local server, and the interface without a window. - The Windows binary around 15–16 MB, the installer around 7 MB. ## 6. How it's verified - `cargo clippy --workspace --all-targets` with no warnings, `cargo test --workspace`, and for Windows `cargo xwin clippy --target x86_64-pc-windows-msvc`. - **HTTP tests against a server of your own on 127.0.0.1** that echoes exactly what it received: query and headers as written, duplicate headers, disabled rows, a custom Content-Type, urlencoding, multipart with file content, custom methods, redirects, timeout, Cancel against a server that never answers, that the second request carries no cookies and that OAuth2 fetches a new token each time. - **UI tests without a window** (`egui_kittest`) with real clicks, right-clicks, keys and drags: saving, renaming in the tree, dragging to a folder, unsaved changes after a restart, OpenAPI import, environment collections. - **Real documents**, not just the tests': Swagger's Petstore and GitHub's REST definition. - **Screenshots** of every new view. ## 7. Way of working - **Research first**: Postman, Insomnia, Bruno, Hoppscotch – what they do, how they store collections and what users complain about. Mark what was checked against a source and what is judgement. - **One task at a time**, with the interpretation before the build and the measurement in the closing comment. - **Try it early.** Most of the improvements came when the app was used for real: click areas, pre-filled names selected, margins in the fields, the session. ## 8. The prompt > Build an HTTP client for [Windows and macOS] in [Rust with eframe/egui and reqwest] for sending requests to APIs and inspecting the responses, like Postman or Insomnia but without an account. Collections should be saved as ordinary files – a directory per collection and a JSON file per request – with environments and variables, auth, OpenAPI import and cURL both ways. > > Read all of IDEA.md below first. It describes the features, the architecture, the decisions that turned out to matter and the pitfalls to avoid. > > Work like this: > 1. Research similar programs and write a plan split into tasks. Ask me about the decisions that are mine. > 2. Run networking on its own runtime, never on the UI thread. > 3. Test HTTP against a local server of your own and the interface without a window. > 4. Review every new view with a screenshot. > 5. Never let secret values end up in the collection's files. > > [paste IDEA.md here]