httpretty

README

httpretty

Package httpretty prints the HTTP requests of your Go programs pretty on your terminal screen. It is mostly inspired in curl's --verbose mode, and also on the httputil.DumpRequest and similar functions.

Setting up a logger

You can define a logger with something like

logger := &httpretty.Logger{
	Time:           true,
	TLS:            true,
	RequestHeader:  true,
	RequestBody:    true,
	ResponseHeader: true,
	ResponseBody:   true,
	Colors:         true, // erase line if you don't like colors
	Formatters:     []httpretty.Formatter{&httpretty.JSONFormatter{}},
}

This code will set up a logger with sane settings. By default the logger prints nothing but the request line (and the remote address, when using it on the server-side).

Using on the client-side

You can set the transport for the *net/http.Client you are using like this:

client := &http.Client{
	Transport: logger.RoundTripper(http.DefaultTransport),
}

// from now on, you can use client.Do, client.Get, etc. to create requests.

If you don't care about setting a new client, you can safely replace your existing http.DefaultClient with this:

http.DefaultClient.Transport = logger.RoundTripper(http.DefaultClient.Transport)

Then httpretty is going to print information about regular requests to your terminal when code such as this is called:

if _, err := http.Get("https://www.google.com/"); err != nil {
        fmt.Fprintf(os.Stderr, "%+v\n", err)
        os.Exit(1)
}

However, have in mind you usually want to use a custom *http.Client to control things such as timeout.

Logging on the server-side

You can use the logger quickly to log requests on your server. For example:

logger.Middleware(mux)

The handler should by a http.Handler. Usually, you want this to be your http.ServeMux HTTP entrypoint.

For working examples, please see the example directory.

Filtering

You have two ways to filter a request so it isn't printed by the logger.

httpretty.WithHide

You can filter any request by setting a request context before the request reaches httpretty.RoundTripper:

req = req.WithContext(httpretty.WithHide(ctx))

Filter function

A second option is to implement

type Filter func(req *http.Request) (skip bool, err error)

and set it as the filter for your logger. For example:

logger.SetFilter(func filteredURIs(req *http.Request) (bool, error) {
	if req.Method != http.MethodGet {
		return true, nil
	}

	if path := req.URL.Path; path == "/debug" || strings.HasPrefix(path, "/debug/") {
		return true, nil
	}

	return false
})

Formatters

You can define a formatter for any media type by implementing the Formatter interface.

We provide a JSONFormatter for convenience (it is not enabled by default).

Documentation

Overview

Package httpretty prints your HTTP requests pretty on your terminal screen. You can use this package both on the client-side and on the server-side.

This package provides a better way to view HTTP traffic without httputil DumpRequest, DumpRequestOut, and DumpResponse heavy debugging functions.

You can use the logger quickly to log requests you are opening. For example:

package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/bingoohuang/httpretty"
)

func main() {
	logger := &httpretty.Logger{
		Time:           true,
		TLS:            true,
		RequestHeader:  true,
		RequestBody:    true,
		ResponseHeader: true,
		ResponseBody:   true,
		Colors:         true,
		Formatters:     []httpretty.Formatter{&httpretty.JSONFormatter{}},
	}

	http.DefaultClient.Transport = logger.RoundTripper(http.DefaultClient.Transport) // tip: you can use it on any *http.Client

	if _, err := http.Get("https://www.google.com/"); err != nil {
		fmt.Fprintf(os.Stderr, "%+v\n", err)
		os.Exit(1)
	}
}

If you pass nil to the logger.RoundTripper it is going to fallback to http.DefaultTransport.

You can use the logger quickly to log requests on your server. For example:

logger := &httpretty.Logger{
	Time:           true,
	TLS:            true,
	RequestHeader:  true,
	RequestBody:    true,
	ResponseHeader: true,
	ResponseBody:   true,
}

logger.Middleware(handler)

Note: server logs don't include response headers set by the server. Client logs don't include request headers set by the HTTP client.

Index

• func Ksuid() string
• func WithHide(ctx context.Context) context.Context
• type BodyFilter
• type Filter
• type Flusher
• type Formatter
• type JSONFormatter
  • func (j *JSONFormatter) Format(w io.Writer, src []byte) error
  • func (j *JSONFormatter) Match(mediatype string) bool
• type Logger
  • func (l *Logger) Middleware(next http.Handler, printReqID bool) http.Handler
  • func (l *Logger) PrintRequest(req *http.Request)
  • func (l *Logger) PrintResponse(resp *http.Response)
  • func (l *Logger) RoundTripper(rt http.RoundTripper, printReqID bool) http.RoundTripper
  • func (l *Logger) SetBodyFilter(f BodyFilter)
  • func (l *Logger) SetFilter(f Filter)
  • func (l *Logger) SetFlusher(f Flusher)
  • func (l *Logger) SetOutput(w io.Writer)
  • func (l *Logger) SkipHeader(headers []string)
• Bugs

Functions

func Ksuid

func Ksuid() string

func WithHide

func WithHide(ctx context.Context) context.Context

WithHide can be used to protect a request from being exposed.

Types

type BodyFilter

type BodyFilter func(h http.Header) (skip bool, err error)

BodyFilter allows you to skip printing a HTTP body based on its associated Header.

It can be used for omitting HTTP Request and Response bodies. You can filter by checking properties such as Content-Type or Content-Length.

On a HTTP server, this function is called even when no body is present due to http.Request always carrying a non-nil value.

type Filter

type Filter func(req *http.Request) (skip bool, err error)

Filter allows you to skip requests.

If an error happens and you want to log it, you can pass a not-null error value.

type Flusher

type Flusher int

Flusher defines how logger prints requests.

const (
	// NoBuffer strategy prints anything immediately, without buffering.
	// It has the issue of mingling concurrent requests in unpredictable ways.
	NoBuffer Flusher = iota

	// OnReady buffers and prints each step of the request or response (header, body) whenever they are ready.
	// It reduces mingling caused by mingling but does not give any ordering guarantee, so responses can still be out of order.
	OnReady

	// OnEnd buffers the whole request and flushes it once, in the end.
	OnEnd
)

Logger can print without flushing, when they are available, or when the request is done.

type Formatter

type Formatter interface {
	Match(mediatype string) bool
	Format(w io.Writer, src []byte) error
}

Formatter can be used to format body.

If the Format function returns an error, the content is printed in verbatim after a warning. Match receives a media type from the Content-Type field. The body is formatted if it returns true.

type JSONFormatter

type JSONFormatter struct{}

JSONFormatter helps you read unreadable JSON documents.

github.com/tidwall/pretty could be used to add colors to it. However, it would add an external dependency. If you want, you can define your own formatter using it or anything else. See Formatter.

func (*JSONFormatter) Format

func (j *JSONFormatter) Format(w io.Writer, src []byte) error

Format JSON content.

func (*JSONFormatter) Match

func (j *JSONFormatter) Match(mediatype string) bool

Match JSON media type.

type Logger

type Logger struct {

	// Formatters for the request and response bodies.
	// No standard formatters are used. You need to add what you want to use explicitly.
	// We provide a JSONFormatter for convenience (add it manually).
	Formatters []Formatter

	// MaxRequestBody the logger can print.
	// If value is not set and Content-Length is not sent, 4096 bytes is considered.
	MaxRequestBody int64

	// MaxResponseBody the logger can print.
	// If value is not set and Content-Length is not sent, 4096 bytes is considered.
	MaxResponseBody int64

	// SkipRequestInfo avoids printing a line showing the request URI on all requests plus a line
	// containing the remote address on server-side requests.
	SkipRequestInfo bool

	// Time the request began and its duration.
	Time bool

	// TLS information, such as certificates and ciphers.
	// BUG(henvic): Currently, the TLS information prints after the response header, although it
	// should be printed before the request header.
	TLS bool

	// RequestHeader set by the client or received from the server.
	RequestHeader bool

	// RequestBody sent by the client or received by the server.
	RequestBody bool

	// ResponseHeader received by the client or set by the HTTP handlers.
	ResponseHeader bool

	// ResponseBody received by the client or set by the server.
	ResponseBody bool

	// SkipSanitize bypasses sanitizing headers containing credentials (such as Authorization).
	SkipSanitize bool

	// Colors set ANSI escape codes that terminals use to print text in different colors.
	Colors bool
	// contains filtered or unexported fields
}

Logger provides a way for you to print client and server-side information about your HTTP traffic.

func (*Logger) Middleware

func (l *Logger) Middleware(next http.Handler, printReqID bool) http.Handler

Middleware for logging incoming requests to a HTTP server.

func (*Logger) PrintRequest

func (l *Logger) PrintRequest(req *http.Request)

PrintRequest prints a request, even when WithHide is used to hide it.

It doesn't log TLS connection details or request duration.

func (*Logger) PrintResponse

func (l *Logger) PrintResponse(resp *http.Response)

PrintResponse prints a response.

func (*Logger) RoundTripper

func (l *Logger) RoundTripper(rt http.RoundTripper, printReqID bool) http.RoundTripper

RoundTripper returns a RoundTripper that uses the logger.

func (*Logger) SetBodyFilter

func (l *Logger) SetBodyFilter(f BodyFilter)

SetBodyFilter allows you to set a function to skip printing a body. Pass nil to remove the body filter. This method is concurrency safe.

func (*Logger) SetFilter

func (l *Logger) SetFilter(f Filter)

SetFilter allows you to set a function to skip requests. Pass nil to remove the filter. This method is concurrency safe.

func (*Logger) SetFlusher

func (l *Logger) SetFlusher(f Flusher)

SetFlusher sets the flush strategy for the logger.

func (*Logger) SetOutput

func (l *Logger) SetOutput(w io.Writer)

SetOutput sets the output destination for the logger.

func (*Logger) SkipHeader

func (l *Logger) SkipHeader(headers []string)

SkipHeader allows you to skip printing specific headers. This method is concurrency safe.

Notes

Bugs

• Currently, the TLS information prints after the response header, although it should be printed before the request header.

• net/http data race condition when the client does concurrent requests using the very same HTTP transport. See Go standard library issue https://golang.org/issue/30597