diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +# v7.5.1 (2026-05-04) + +## ✨ New Features + +## 🐛 Bug Fixes + +## 🏗️ Architecture Changes + +## 📝 Administrivia Changes +- [`51bb15f`](https://gitlab.com/krakrjak/restman/-/commit/51bb15f) 📝 README.md Enhancements + # v7.5.0 (2026-05-04) ## ✨ New Features diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,66 +1,368 @@ -[![pipeline status](https://gitlab.com/krakrjak/restman/badges/master/pipeline.svg)](https://gitlab.com/krakrjak/restman/-/commits/master) +[![pipeline status](https://gitlab.com/krakrjak/restman/badges/master/pipeline.svg)](https://gitlab.com/krakrjak/restman/-/commits/master) +[![Latest Release](https://gitlab.com/krakrjak/restman/-/badges/release.svg)](https://gitlab.com/krakrjak/restman/-/releases) +[![License: BSD2](https://img.shields.io/badge/license-BSD2-blue.svg)](LICENSE) -RESTMan is a program for sending web requests using a terminal user interface or TUI. +# RESTMan +**RESTMan** is a keyboard-driven TUI HTTP client for the terminal. Compose and +send HTTP(S) requests interactively — or script one-shot requests from the +command line — without leaving your shell. + [[_TOC_]] -Right now, Windows is not supported directly due to limitations of the [Brick](https://hackage.haskell.org/package/brick) library used to generate the TUI. You can however, use Windows to build and execute RESTMan through WSL2 and a Debian distribution. See details below. +--- +## Features + +- **All HTTP methods** — GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, CONNECT, + PATCH, or any custom verb +- **Interactive TUI** — full-screen [Brick](https://hackage.haskell.org/package/brick)-based + terminal UI +- **Oneshot mode** — `--oneshot URI` prints the response body to stdout and + exits (scriptable like `curl`) +- **Quick Request mode** — pass a URI on the command line to pre-populate the + TUI and fire the request immediately +- **Syntax-highlighted responses** — MIME-type-aware, pygments colour theme via + [Skylighting](https://hackage.haskell.org/package/skylighting) +- **Bi-directional scroll** — arrow keys, Vi/Vim keys (`hjkl`), Page Up/Down, + and mouse wheel +- **Custom headers** — add, edit, enable, or disable individual headers in a + table with horizontal scroll +- **Default headers toggle** — view and toggle the wreq default headers + (`Accept-Encoding`, `User-Agent`, …) +- **Request payloads** — provide a body inline (`--payload`) or from a file + (`--payload-file`) +- **TLS / HTTPS** — via `http-client-tls`; 30-second timeout guards against + captive portals and slow proxies +- **Shell completions** — HTTP method names auto-complete via + `optparse-applicative` + --- -# Usage +## TUI Preview - % stack exec restman -- --help - RESTman, an HTTP(S) application +``` + Header(s) Payload Session Help +================================================================================ + ╭── Verb ──╮ ╭─────────────────── URL to Query? ──────────────────────────╮ + │ GET ▼│ │ https://api.example.com/v1/items │ + ╰──────────╯ ╰────────────────────────────────────────────────────────────╯ + ╭──────────────────────────────────────────────────────────────────────────╮ + │ [X] Use Default Headers │ + │ ┌──────────────────────────────────────────────────────────────────┐ │ + │ │ Accept-Encoding: gzip, deflate, br │ │ + │ │ User-Agent: Haskell wreq-0.5.4.1/0.0.0.0 │ │ + │ └──────────────────────────────────────────────────────────────────┘ │ + ╰──────────────────────────────────────────────────────────────────────────╯ + ╭─ Active ──╮╭────────────── Name ─────────────╮╭──────── Value ───────────╮ + │ [X] ││ Authorization ││ Bearer my-token │ + │ [ ] ││ X-Request-ID ││ deadbeef-cafe │ + ╰───────────╯╰─────────────────────────────────╯╰───────────────────────────╯ + [+ Add Custom Header] + ╭────────────────────────── Response Body ──────────────────────────────╮▲ + │ { │ │ + │ "items": [ │▓│ + │ { "id": 1, "name": "widget" } │ │ + │ ] │▼│ + ╰───────────────────────────────────────────────────────────────────────╯◄▓► +``` - Usage: restman [--help] [-m|--method METHOD] - [--no-default-headers | --default-headers] - [-h|--custom-header NAME_VALUE] - [--payload PAYLOAD | --payload-file PATHNAME] - A TUI application for interactively using the full range of HTTP(S) directly +--- - Available options: - --help Show command-line help and abort normal operation. - -m,--method METHOD HTTP(S) Method (or "Verb") (default: "GET") - --no-default-headers Send ONLY the custom headers specified. - --default-headers Send custom headers after default headers. This is - the default behavior. - -h,--custom-header NAME_VALUE - Add a custom header, argument is name:value (colon - separates name from value). - --payload PAYLOAD Specify (in UTF-8) payload directly on command-line - --payload-file PATHNAME Load payload from file on startup +## Platform Support - https://gitlab.com/krakrjak/restman +| Platform | Status | +|---|---| +| Linux | ✓ Fully supported | +| macOS — Intel | ✓ Supported | +| macOS — Apple Silicon (M1 / M2 / M3) | ✓ Supported (requires `llvm`, see below) | +| Windows via WSL2 + Debian | ✓ Supported — recommended Windows path | +| Windows native | ⚠ Experimental — supported since [Brick 2.0](https://hackage.haskell.org/package/brick) / [vty 6.0](https://hackage.haskell.org/package/vty) via [`vty-windows`](https://hackage.haskell.org/package/vty-windows), but builds have been unreliable; see [Known Limitations](#known-limitations) | --- -# Building -For those already familiar with Haskell and the Stack, you can get up and running quickly with the usual recipie of `stack setup` followed by `stack build`. As usual, `stack setup` only needs to be run once. +## Prerequisites -## Building on Debian (WSL2 Tested) +| Tool | Version | Notes | +|---|---|---| +| [GHC](https://www.haskell.org/ghc/) | 9.10.x | Managed automatically by Stack | +| [Stack](https://docs.haskellstack.org/) | any recent | Primary build tool | +| [llvm](https://llvm.org/) | — | **macOS Apple Silicon only** — `brew install llvm` | -Install and configure your favorite shell, you are going to spend a lot of time in it. :) +Stack will download and configure the correct GHC version (via Stackage +**LTS 24.38**) on first run. -Once you are comfortable install the package _haskell-stack_, _libtinfo-dev_, and _libz1g-dev_ using apt: `apt install haskell-stack libtinfo-dev libz1g-dev` +--- -You will need to upgrade the Debian provided stack using `stack upgrade`. If needed it will prompt you for sudo access. Once your stack is up-to-date you need a Haskell compiler. Use `stack setup` to determine, fetch, and configure a compiler for your environment. You can check your installation using `stack ghci` to enter the GHC REPL. +## Quick Start -Now you are ready to build RESTMan and all of its dependencies. `stack build` +```sh +# 1. Clone the repository +git clone https://gitlab.com/krakrjak/restman.git +cd restman -## Building on M1 Mac +# 2. Set up the compiler (once — downloads GHC 9.10.x if needed) +stack setup -Install [ghcup](https://www.haskell.org/ghcup/), then `brew install llvm`. Then you will need the following setup in your environment: +# 3. Build RESTMan and all dependencies +stack build +# 4. Launch the TUI +stack exec restman +``` + +> **First build** resolves and compiles all Haskell dependencies, which can +> take several minutes. + +--- + +## Installation + +To install the `restman` binary to `~/.local/bin`: + ```sh -export PATH="/opt/homebrew/opt/llvm@13/bin:$PATH" -export LDFLAGS="-L/opt/homebrew/opt/llvm@13/lib" -export CPPFLAGS="-I/opt/homebrew/opt/llvm@13/include" +stack install ``` -Then you can successfully use `stack` to build the program. You will need some extra flags to make it all work. Here's what is reported to work currently: `stack --arch aarch64 --system-ghc build`. +Add `~/.local/bin` to your `PATH` so you can run `restman` directly: +```sh +# Add to ~/.bashrc, ~/.zshrc, etc. +export PATH="$HOME/.local/bin:$PATH" +``` + +RESTMan is also listed on [Hackage](https://hackage.haskell.org/package/restman) +as a package reference. + --- -# Running and Testing -Once you have _restman-exe_ built you can use stack to execute it with `stack exec restman-exe`. If you want to pass options to the program you can use the form `stack exec restman-exe -- OPTIONS FOR RESTMAN BINARY`. You can also install the binary to _~/.local_ with `stack install`. If you add _~/.local/bin_ to your __PATH__ you can run the program without the aid of the _stack_ executable. +## Usage + +### Modes of Operation + +| Mode | How to invoke | Description | +|---|---|---| +| **Interactive TUI** | `restman` | Full-screen TUI — compose and send requests interactively | +| **Quick Request** | `restman URI` | TUI launches with URI pre-filled; request fires immediately | +| **Oneshot** | `restman --oneshot URI` | Prints response body to stdout and exits — no TUI | + +### Command-line Reference + +``` +Usage: restman [--help] [-m|--method METHOD] + [--no-default-headers | --default-headers] + [-h|--custom-header NAME_VALUE] + [--payload PAYLOAD | --payload-file PATHNAME] + [--oneshot] [URI] +``` + +| Flag | Short | Default | Description | +|---|---|---|---| +| `--help` | | | Show help and exit | +| `--method METHOD` | `-m` | `GET` | HTTP method / verb | +| `--no-default-headers` | | off | Send **only** custom headers (suppress wreq defaults) | +| `--default-headers` | | on | Append custom headers after wreq defaults | +| `--custom-header NAME_VALUE` | `-h` | — | Add a `Name:Value` header (repeatable) | +| `--payload PAYLOAD` | | — | Inline request body (UTF-8) | +| `--payload-file PATHNAME` | | — | Load request body from a file | +| `URI` | | — | Target URL (positional, optional) | +| `--oneshot` | | off | Non-interactive one-shot mode (requires `URI`) | + +`--custom-header` format: `Name:Value` — the first colon separates the header +name from its value. The flag may be repeated to supply multiple headers. + +### Examples + +```sh +# Open the TUI (no arguments) +restman + +# Open the TUI pre-loaded with a URL (request fires immediately) +restman https://httpbin.org/get + +# One-shot GET — print the response body to stdout +restman --oneshot https://httpbin.org/get + +# One-shot POST with a JSON payload +restman --oneshot -m POST \ + -h 'Content-Type:application/json' \ + --payload '{"key":"value"}' \ + https://httpbin.org/post + +# PUT with a binary payload file, suppressing default headers +restman -m PUT \ + --no-default-headers \ + -h 'Content-Type:application/octet-stream' \ + --payload-file ./data.bin \ + https://example.com/upload +``` + +--- + +## TUI Keybindings + +### Global + +| Key | Action | +|---|---| +| `Esc` / `Ctrl+Q` | Quit RESTMan | +| `Tab` | Move focus to the next widget | +| `Shift+Tab` | Move focus to the previous widget | +| `Enter` (URL editor focused) | Send the HTTP request | + +### Method Selector Popup + +| Key | Action | +|---|---| +| `↓` (on Method field) | Open the method selector popup | +| `↑` / `↓` | Navigate the method list | +| `Enter` | Confirm selection and close the popup | +| `Esc` | Close the popup without changing the method | + +### Custom Headers + +| Key | Action | +|---|---| +| `Space` on `[+ Add Custom Header]` | Add a new empty header row | +| `Space` on a header checkbox | Enable / disable that header | +| `Tab` into a Name or Value cell | Begin editing the cell | +| `←` / `→` | Scroll cell content horizontally | + +### Default Headers Toggle + +| Key | Action | +|---|---| +| `Tab` to `[X] Use Default Headers` | Move focus to the toggle | +| `Space` | Toggle default headers on / off | + +### Response Viewport + +| Key | Action | +|---|---| +| `↓` / `j` | Scroll down one line | +| `↑` / `k` | Scroll up one line | +| `→` / `l` | Scroll right one column | +| `←` / `h` | Scroll left one column | +| `Page Down` | Scroll down one page | +| `Page Up` | Scroll up one page | +| Mouse scroll | Scroll three lines up / down | + +--- + +## Building from Source + +### Linux / Debian (and Windows WSL2) + +Install the required system packages: + +```sh +apt install haskell-stack libtinfo-dev libz1g-dev +``` + +Upgrade to the latest Stack release, then set up the compiler and build: + +```sh +stack upgrade # may prompt for sudo +stack setup # downloads GHC 9.10.x +stack build +``` + +### macOS — Intel + +```sh +stack setup +stack build +``` + +### macOS — Apple Silicon (M1 / M2 / M3) + +Install [ghcup](https://www.haskell.org/ghcup/) and LLVM: + +```sh +brew install llvm +``` + +Export the LLVM paths (add these to your shell profile): + +```sh +export PATH="/opt/homebrew/opt/llvm/bin:$PATH" +export LDFLAGS="-L/opt/homebrew/opt/llvm/lib" +export CPPFLAGS="-I/opt/homebrew/opt/llvm/include" +``` + +Then build with the `aarch64` target: + +```sh +stack --arch aarch64 --system-ghc build +``` + +### Windows + +**WSL2 (recommended):** Use WSL2 with a Debian distribution and follow the +Linux / Debian steps above. + +**Windows native (experimental):** Native Windows support was introduced in +vty 6.0 / Brick 2.0 via +[`vty-windows`](https://hackage.haskell.org/package/vty-windows), which +RESTMan picks up transitively through Brick. However, `vty-windows` has a +tightly pinned `Win32` dependency and build failures have been reported. +If you want to attempt a native build, install +[GHCup](https://www.haskell.org/ghcup/) for Windows, then: + +```sh +stack setup +stack build +``` + +Please report any success or failure in the +[issue tracker](https://gitlab.com/krakrjak/restman/-/issues). + +--- + +## Running Tests + +```sh +stack test +``` + +The test suite uses [Tasty](https://hackage.haskell.org/package/tasty) with +HUnit unit tests, Hedgehog property tests, and an in-process HTTP echo server +for integration tests. + +--- + +## Known Limitations + +- **Windows native (experimental)** — native Windows support was added in + [vty 6.0](https://hackage.haskell.org/package/vty) and + [Brick 2.0](https://hackage.haskell.org/package/brick) via the + [`vty-windows`](https://hackage.haskell.org/package/vty-windows) backend. + However, `vty-windows` has a tightly pinned `Win32` dependency and has had + reported build failures. WSL2 + Debian remains the most reliable Windows + path until `vty-windows` stabilises. +- **8 KB header line limit** — `http-client` enforces a hard 8 KB limit per + response header line. Sites with very large headers (e.g. `slashdot.org`'s + `Content-Security-Policy`) will produce an `OverlongHeaders` exception. +- **Captive portals** — the 30-second response timeout guards against infinite + hangs, but portal authentication pages are not navigable from the TUI. + +--- + +## Contributing + +Bug reports and feature requests: +[gitlab.com/krakrjak/restman/issues](https://gitlab.com/krakrjak/restman/-/issues) + +Before submitting a merge request, please ensure: + +- `stack build` passes with no warnings +- `stack test` is green +- Code passes `hlint` and is formatted with `stylish-haskell` +- [pre-commit](https://pre-commit.com/) hooks are installed + (`pre-commit install`) + +--- + +## License + +[BSD 2-Clause](LICENSE) — © Zac Slade, Boyd Stephen Smith Jr. diff --git a/restman.cabal b/restman.cabal --- a/restman.cabal +++ b/restman.cabal @@ -1,6 +1,6 @@ cabal-version: 1.12 name: restman -version: 0.7.5.0 +version: 0.7.5.1 license: BSD2 license-file: LICENSE copyright: Zac Slade or Boyd Stephen Smith Jr, 2024