nvim-postman

A Postman-like WebSocket and HTTP client inside Neovim. Compose requests in familiar buffer types, send them with a keypress, and inspect responses in a split window — all without leaving the editor.

Architecture

Two components communicate over JSON Lines via stdin/stdout:

• Rust CLI binary (nvim-postman) — handles real WebSocket connections (via tokio-tungstenite) and HTTP requests (via reqwest), with full TLS/mTLS support.
• Neovim Lua plugin — provides file-type detection, keybindings, output split windows, and configuration.

Installation

Neovim built-in (vim-packdir)

git clone https://github.com/your-name/nvim-postman \
  ~/.local/share/nvim/site/pack/plugins/start/nvim-postman
cd ~/.local/share/nvim/site/pack/plugins/start/nvim-postman && make

With lazy.nvim

{
  "your-name/nvim-postman",
  build = "make",
}

Manual

1. Build the Rust client: cargo build --release --manifest-path rust-client/Cargo.toml
2. Copy rust-client/target/release/nvim-postman to a directory on your $PATH.
3. Copy the plugin files into your Neovim packpath.

Usage

WebSocket (.wss files)

1. Create a .wss file. The first line is the WebSocket URL; subsequent lines are JSON payloads to send.

wss://echo.example.com/ws
{"message": "hello"}
{"message": "world"}

2. Press <F7> to connect — a split window opens showing connection status.
3. Position cursor on a JSON payload and press <F6> to send it. Response timing and size are displayed.
4. Press <F5> to close the connection.

HTTP (.http or .rest files)

1. Create a .http file with a JSON object containing url, method, and optional headers / body:

{
  "url": "https://api.example.com/data",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer token"
  },
  "body": "{\"key\": \"value\"}"
}

2. Press <F7> to send the request. The response appears in the split window with timing and size.

Burst send

Run :BurstSend <count> <interval_ms> to send the current JSON payload repeatedly.

Commands

Command	Description
:NvimPostmanWsConnect	Connect to WebSocket URL on line 1
:NvimPostmanWsSend	Send the current JSON payload
:NvimPostmanWsClose	Close the WebSocket connection
:NvimPostmanHttpSend	Send HTTP request from current buffer
:BurstSend <n> <ms>	Send payload <n> times at <ms> interval
:NvimPostmanInstall	Download pre-built binary for your platform

Configuration

require("nvim-postman").setup({
  rust_binary = "nvim-postman",      -- path to the Rust binary
  cert = nil,                         -- TLS client certificate (PEM)
  key = nil,                          -- TLS client key (PEM)
  ca = nil,                           -- CA certificate bundle (PEM)
  timeout_ms = 5000,                   -- request timeout
  output_max_lines = 5000,            -- max lines in output buffer
})

Output format

Responses are displayed with metadata: (145ms | 0.5 KB): followed by the pretty-printed body. Errors, connection status, and closure events are also shown.

Development

make test         # run all tests
make test-rust    # run Rust integration tests
make test-lua     # run Lua unit tests
make clean        # remove build artifacts

License

MIT