httpcat

A netcat-like tool for analysing or mocking HTTP requests. My first experiment with Go.

Latest version: 2.4

Usage

httpcat <command> [OPTIONS]

Commands:

  client     Send an HTTP request
  proxy      Start a reverse HTTP logging proxy
  server     Start a mock HTTP server
  version    Display version

Command specific help:

  httpcat <command> --help

Global Options

The following options apply to all commands.

-v, --verbose       Show additional details.

    --headers       Show headers and request/status line only (default is
                    everything).

    --bodies        Show bodies only (default is everything).

    --nocolour      Don't use colours (default is requests in blue and
                    responses in red).

    --notimestamps  Don't show timestamps.

    --noindent      Don't indent bodies (currently, only application/json
                    bodies are indented).

Client Mode

Sends an HTTP request to the specified server and displays the response.

Usage

httpcat client [OPTIONS] URL

Client Specific Options

-H, --header       A header to add to request in the form name|value. Use
                   multiple times for multiple headers.

-m, --method [GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS]
                   HTTP method for request (default: GET).

-b, --body         Request body to send.

Example

httpcat client \
   --method POST \
   --body "Testing 123" \
   --header "Content-Type|text/plain" \
   --header "Authorization|Bearer abc123" \
   http://localhost:8080/api/testing

Note that the \ character in the above example is the line continuation character that allows you to break long lines into smaller lines in most Linux/macOS shells. For the Windows cmd shell, use ^ for line continuation. For PowerShell, use ` (the backtick character).

Server Mode

Creates a web server with mock routes that listen on specific paths and return specific responses. Displays the details of any requests that it receives.

Usage

httpcat server [OPTIONS]

Server Specific Options

-p, --port     Port to listen on. (default: 8080).

-r, --route    Route which is made up of a path, a response body, a
               content type, and a response status, all separated by
               the pipe '|' character.  Repeat for additional routes.

-c, --cors     Enable Cross Origin Resource Sharing (CORS).  Allows all
               requested methods and headers.

-H, --header   A header to add to response in the form name|value. Use
               multiple times for multiple headers.

Example

Linux/macOS:

httpcat server \
  --port 8080 \
  --route "/hello|Hello World|text/plain|200" \
  --route "/goodbye|||204" \
  --cors

Windows PowerShell:

httpcat server `
  /port:8080 `
  /route:"/hello|Hello World|text/plain|200" `
  /route:"/goodbye|||204" `
  /cors

This creates a web server that listens on port 8080 and responds to any requests to the /hello path with the response Hello World and response code 200, and returns an empty response with a 204 response code to any requests made to /goodbye. The server will allow any requested headers and methods for CORS requests.

Server Wildcard Mode

If no routes are specified then the server will accept requests to all paths, returning a 200 response code with an empty body for GET requests and a 204 response code for all other request methods.

Complex Bodies

For mocking services with large/complex bodies, you can use shell command substitution to load the body for a route from a file:

File cust.json:

{
  "data": {
    "id": "0266a95f-e57c-11ec-f37b-c20db6f2e117",
    "customer_code": "Boris-SVZ7",
    "first_name": "Boris",
    "last_name": "McNorris",
    "email": "boris@example.com",
    "customer_group_id": "0afa8de1-147c-11e8-edec-2b197906d816"
  }
}

Linux/macOS:

httpcat server \
  --port 8080 \
  --route "/api/2.0/customers|$(cat cust.json)|application/json|201" \
  --cors

Windows PowerShell:

httpcat server `
  /port:8080 `
  /route:"/api/2.0/customers|$(gc cust.json)|application/json|201" `
  /cors

Proxy Mode

Creates a reverse proxy that displays all HTTP requests and responses that pass through it. It will rewrite the port for redirect responses.

Usage

httpcat proxy [OPTIONS]

Proxy Specific Options

-p, --port     The port that the proxy listens on.

-t, --target   The URL for the target web server that the proxy forwards
               requests to.

-f, --filter   Only show bodies that match the given Content-Type.

Examples

httpcat proxy --port 8090 --target http://localhost:8080

# only show JSON bodies
httpcat proxy --filter "application/json" --port 8090 --target http://localhost:8080

Any requests sent to port 8090 will be forwarded to http://localhost:8080 and all requests and responses will be displayed. Any redirect responses will be rewritten to use the specified port.

Using the filter option will cause the bodies that don't match the given Content-Type to be suppressed, but the headers will still be shown.

Building

cd src
go build -o ../httpcat

Stripping

go build -ldflags "-s -w" -o ../httpcat

See the link docs for information on ldflags:

https://pkg.go.dev/cmd/link

Cross Compiling

Linux

GOOS=linux GOARCH=amd64 go build -o ../httpcat-linux

Windows

GOOS=windows GOARCH=amd64 go build -o ../httpcat-win64.exe

Intel Mac

GOOS=darwin GOARCH=amd64 go build -o ../httpcat-mac-intel

M1/ARM64 Mac

GOOS=darwin GOARCH=arm64 go build -o ../httpcat-mac-arm64

License

Zero-Clause BSD License: https://opensource.org/license/0bsd/

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.