http

README

gorilla/http

👷 This library is in maintenance mode.

A simple, safe and powerful HTTP client for the Go language.

Build Status:

Image of an under construction GIF

This project is experimental. We welcome contributors and early adopters if you're feeling brave.

Introduction

Why does Go need a new HTTP client, the standard library already has one ?

The Go net/http package is excellent. It is fast, efficient, gets the job done, and comes batteries included with every Go installation. At the same time the net/http package is a victim of its own success. The Go 1 contract defines many fields in the net/http types which are redundant or surplus.

Similarly the success of the net/http package has enshrined bugs which cannot be changed due to the growing amount of software written to expect that behaviour.

Client only

One acknowledged shortcoming of the net/http package is its reuse of core types between server and client implementations.

At one level this is admirable, HTTP messages; requests and responses, are more alike than they are different so it makes good engineering sense to reuse their logic where possible. However, combined with the Go 1 contract, this has lead to compromises.

gorilla/http is a client implementation only. This allows us to focus on a set of layered types which encapsulate the complete request flow from the client point of view without compromise.

Specific features

This section addresses specific limitations of the net/http package and discusses the gorilla/http alternatives.

Timeouts

Timeouts are critically important. By dint of the Go 1 contract, timeouts have been bolted on to the net/http implementation where possible. gorilla/http will go further and implement timeouts for as many operations as possible; connection, request send, response headers, response body, total request/response time, keepalive, etc.

Closing Response Bodies

Forgetting to close a Response.Body is a continual problem for Gophers. It would be wonderful to create a client which does not require the response body to be closed, however this appears impossible to marry with the idea of connection reuse and pooling.

Instead gorilla/http will address this in two ways

1. The high level functions in the gorilla/http package do not return types that require closing. For example, gorilla/http.Get(w io.Writer, url string) mirrors the interface of io.Copy and should be sufficient for many REST style http calls which exchange small messages.
2. At the http.Client layer, methods will return an io.ReadCloser, not a complex Response type. This io.ReadCloser must be closed before falling out of scope otherwise the client will panic the application.

Connection rate limiting

Rate limiting in terms of number of total connections in use, number of connections to a particular site will be controllable. By default gorilla/http will only use a reasonable number of concurrent connections.

gorilla/http has a strictly layered design where the high level gorilla/http package is responsible for request composition and connection management and the lower level gorilla/http/client package is strictly responsible for the http transaction and the lowest level wire format.

Reliable DNS lookups

gorilla/http will use an alternative DNS resolver library to avoid the limitations of the system libc resolver library.

Robustness and correctness

As a client only package, gorilla/http has flexibility to bias correctness over performance. Gorilla will always favor correctness of implementation over performance, and we believe this is the correct trade off. Having said that performance is a feature and gorilla/http strives to keep its overheads compared to the underlying network transit cost as low as possible.

Roadmap

The roadmap for the project is captured as open issues in GitHub.

Contributions and feedback

Please raise issues and suggestions on the GitHub project page, https://github.com/gorilla/http/issues.

Questions and discussion can also be directed to the general Gorilla mailing list https://groups.google.com/group/gorilla-web.

Technical information

gorilla/http is divided into 4 layers. The topmost layer is a set of convenience functions layered on top of a default gorilla/http.Client instance. These package level functions are intended to satisfy simple HTTP requests and only cover the most common verbs and use cases.

The next layer is gorilla/http.Client which is a high level reusable HTTP client. It transparently manages connection pooling and reuse and provides both common verbs and a general purpose Client.Do() interface for uncommon http verbs.

The lower layers are inside the gorilla/http/client package and consist of types that deal with the abstract RFC2616 message form and marshal it on and off the wire.

Interestingly, although these are the lowest level types, they do not deal with net.Conn implementations, but io.ReadWriter, connection setup, management and timeout control is handled by the owner of the io.ReadWriter implementation passed to client.Client.

Documentation

Overview

Package gorilla/http is a high level HTTP client.

This package provides high level convience methods for common http operations. Additionally a high level HTTP client implementation.

These high level functions are expected to change. Your feedback on their form and utility is warmly requested.

Please raise issues at https://github.com/gorilla/http/issues.

For lower level http implementations, see gorilla/http/client.

Index

• Variables
• func Get(w io.Writer, url string) (int64, error)
• func Post(url string, r io.Reader) error
• type Client
  • func (c *Client) Delete(url string, headers map[string][]string) (client.Status, map[string][]string, io.ReadCloser, error)
  • func (c *Client) Do(method, url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)
  • func (c *Client) Get(url string, headers map[string][]string) (client.Status, map[string][]string, io.ReadCloser, error)
  • func (c *Client) Patch(url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)
  • func (c *Client) Post(url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)
  • func (c *Client) Put(url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)
• type Conn
• type Dialer
• type StatusError
  • func (s *StatusError) Error() string

Examples

• Client.Post
• Get
• Post

Variables

var DefaultClient = Client{

	FollowRedirects: true,
	// contains filtered or unexported fields
}

DefaultClient is the default http Client used by this package. It's defaults are expected to represent the best practice at the time, but may change over time. If you need more control or reproducibility, you should construct your own client.

Functions

func Get

func Get(w io.Writer, url string) (int64, error)

Get issues a GET request using the DefaultClient and writes the result to to w if successful. If the status code of the response is not a success (see Success.IsSuccess()) no data will be written and the status code will be returned as an error.

Example

// curl in 3 lines of code.
if _, err := Get(os.Stdout, "http://www.gorillatoolkit.org/"); err != nil {
	log.Fatalf("could not fetch: %v", err)
}

func Post

func Post(url string, r io.Reader) error

Post issues a POST request using the DefaultClient using r as the body. If the status code was not a success code, it will be returned as an error.

Example

// send the contents of os.Stdin to a remote webserver.
if err := Post("http://www.example.com", os.Stdin); err != nil {
	log.Fatalf("could not post: %v", err)
}

Types

type Client

type Client struct {

	// FollowRedirects instructs the client to follow 301/302 redirects when idempotent.
	FollowRedirects bool
	// contains filtered or unexported fields
}

Client implements a high level HTTP client. Client methods can be called concurrently to as many end points as required.

func (*Client) Delete

func (c *Client) Delete(url string, headers map[string][]string) (client.Status, map[string][]string, io.ReadCloser, error)

Delete sends a DELETE request. If the response body is non nil it must be closed.

func (*Client) Do

func (c *Client) Do(method, url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)

Do sends an HTTP request and returns an HTTP response. If the response body is non nil it must be closed.

func (*Client) Get

func (c *Client) Get(url string, headers map[string][]string) (client.Status, map[string][]string, io.ReadCloser, error)

Get sends a GET request. If the response body is non nil it must be closed.

func (*Client) Patch

func (c *Client) Patch(url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)

Patch sends a PATCH request, suppling the contents of the reader as the request body.

func (*Client) Post

func (c *Client) Post(url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)

Post sends a POST request, suppling the contents of the reader as the request body.

Example

// send the contents of os.Stdin to a remote webserver.
status, _, r, err := DefaultClient.Post("http://www.example.com", nil, os.Stdin)
if err != nil {
	log.Fatal(err)
}
if r != nil {
	defer r.Close()
}
log.Printf("Post result: %v", status)

func (*Client) Put

func (c *Client) Put(url string, headers map[string][]string, body io.Reader) (client.Status, map[string][]string, io.ReadCloser, error)

Put sends a PUT request, suppling the contents of the reader as the request body.

type Conn

type Conn interface {
	client.Client
	io.Closer

	SetDeadline(time.Time) error
	SetReadDeadline(time.Time) error
	SetWriteDeadline(time.Time) error

	// Release returns the Conn to the Dialer for reuse.
	Release()
}

Conn represnts a connection which can be used to communicate with a remote HTTP server.

type Dialer

type Dialer interface {
	// Dial dials a remote http server returning a Conn.
	Dial(network, addr string) (Conn, error)
}

Dialer can dial a remote HTTP server.

type StatusError

type StatusError struct {
	client.Status
}

StatusError reprents a client.Status as an error.

func (*StatusError) Error

func (s *StatusError) Error() string