version: 1.10

package httputil

import "net/http/httputil"

Overview

Package httputil provides HTTP utility functions, complementing the more common
ones in the net/http package.

Index

Examples

Package files

dump.go httputil.go persist.go reverseproxy.go

Variables

  1. var (
  2.     // Deprecated: No longer used.
  3.     ErrPersistEOF = &http.ProtocolError{ErrorString: "persistent connection closed"}
  4.  
  5.     // Deprecated: No longer used.
  6.     ErrClosed = &http.ProtocolError{ErrorString: "connection closed by user"}
  7.  
  8.     // Deprecated: No longer used.
  9.     ErrPipeline = &http.ProtocolError{ErrorString: "pipeline error"}
  10. )
  1. var ErrLineTooLong = internal.ErrLineTooLong

ErrLineTooLong is returned when reading malformed chunked data with lines that
are too long.

func DumpRequest

  1. func DumpRequest(req *http.Request, body bool) ([]byte, error)

DumpRequest returns the given request in its HTTP/1.x wire representation. It
should only be used by servers to debug client requests. The returned
representation is an approximation only; some details of the initial request are
lost while parsing it into an http.Request. In particular, the order and case of
header field names are lost. The order of values in multi-valued headers is kept
intact. HTTP/2 requests are dumped in HTTP/1.x form, not in their original
binary representations.

If body is true, DumpRequest also returns the body. To do so, it consumes
req.Body and then replaces it with a new io.ReadCloser that yields the same
bytes. If DumpRequest returns an error, the state of req is undefined.

The documentation for http.Request.Write details which fields of req are
included in the dump.


Example:

  1. ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
  2.     dump, err := httputil.DumpRequest(r, true)
  3.     if err != nil {
  4.         http.Error(w, fmt.Sprint(err), http.StatusInternalServerError)
  5.         return
  6.     }
  8.     fmt.Fprintf(w, "%q", dump)
  9. }))
  10. defer ts.Close()
  12. const body = "Go is a general-purpose language designed with systems programming in mind."
  13. req, err := http.NewRequest("POST", ts.URL, strings.NewReader(body))
  14. if err != nil {
  15.     log.Fatal(err)
  16. }
  17. req.Host = "www.example.org"
  18. resp, err := http.DefaultClient.Do(req)
  19. if err != nil {
  20.     log.Fatal(err)
  21. }
  22. defer resp.Body.Close()
  24. b, err := ioutil.ReadAll(resp.Body)
  25. if err != nil {
  26.     log.Fatal(err)
  27. }
  29. fmt.Printf("%s", b)
  31. // Output:
  32. // "POST / HTTP/1.1\r\nHost: www.example.org\r\nAccept-Encoding: gzip\r\nContent-Length: 75\r\nUser-Agent: Go-http-client/1.1\r\n\r\nGo is a general-purpose language designed with systems programming in mind."

func DumpRequestOut

  1. func DumpRequestOut(req *http.Request, body bool) ([]byte, error)

DumpRequestOut is like DumpRequest but for outgoing client requests. It includes
any headers that the standard http.Transport adds, such as User-Agent.


Example:

  1. const body = "Go is a general-purpose language designed with systems programming in mind."
  2. req, err := http.NewRequest("PUT", "http://www.example.org", strings.NewReader(body))
  3. if err != nil {
  4.     log.Fatal(err)
  5. }
  7. dump, err := httputil.DumpRequestOut(req, true)
  8. if err != nil {
  9.     log.Fatal(err)
  10. }
  12. fmt.Printf("%q", dump)
  14. // Output:
  15. // "PUT / HTTP/1.1\r\nHost: www.example.org\r\nUser-Agent: Go-http-client/1.1\r\nContent-Length: 75\r\nAccept-Encoding: gzip\r\n\r\nGo is a general-purpose language designed with systems programming in mind."

func DumpResponse

  1. func DumpResponse(resp *http.Response, body bool) ([]byte, error)

DumpResponse is like DumpRequest but dumps a response.


Example:

  1. const body = "Go is a general-purpose language designed with systems programming in mind."
  2. ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
  3.     w.Header().Set("Date", "Wed, 19 Jul 1972 19:00:00 GMT")
  4.     fmt.Fprintln(w, body)
  5. }))
  6. defer ts.Close()
  8. resp, err := http.Get(ts.URL)
  9. if err != nil {
  10.     log.Fatal(err)
  11. }
  12. defer resp.Body.Close()
  14. dump, err := httputil.DumpResponse(resp, true)
  15. if err != nil {
  16.     log.Fatal(err)
  17. }
  19. fmt.Printf("%q", dump)
  21. // Output:
  22. // "HTTP/1.1 200 OK\r\nContent-Length: 76\r\nContent-Type: text/plain; charset=utf-8\r\nDate: Wed, 19 Jul 1972 19:00:00 GMT\r\n\r\nGo is a general-purpose language designed with systems programming in mind.\n"

func NewChunkedReader

  1. func NewChunkedReader(r io.Reader) io.Reader

NewChunkedReader returns a new chunkedReader that translates the data read from
r out of HTTP “chunked” format before returning it. The chunkedReader returns
io.EOF when the final 0-length chunk is read.

NewChunkedReader is not needed by normal applications. The http package
automatically decodes chunking when reading response bodies.

func NewChunkedWriter

  1. func NewChunkedWriter(w io.Writer) io.WriteCloser

NewChunkedWriter returns a new chunkedWriter that translates writes into HTTP
“chunked” format before writing them to w. Closing the returned chunkedWriter
sends the final 0-length chunk that marks the end of the stream.

NewChunkedWriter is not needed by normal applications. The http package adds
chunking automatically if handlers don’t set a Content-Length header. Using
NewChunkedWriter inside a handler would result in double chunking or chunking
with a Content-Length length, both of which are wrong.

type BufferPool

  1. type BufferPool interface {
  2.     Get() []byte
  3.     Put([]byte)
  4. }

A BufferPool is an interface for getting and returning temporary byte slices for
use by io.CopyBuffer.

type ClientConn

  1. type ClientConn struct {
  2.     // contains filtered or unexported fields
  3. }

ClientConn is an artifact of Go’s early HTTP implementation. It is low-level,
old, and unused by Go’s current HTTP stack. We should have deleted it before Go
1.

Deprecated: Use Client or Transport in package net/http instead.

func NewClientConn

  1. func NewClientConn(c net.Conn, r *bufio.Reader) *ClientConn

NewClientConn is an artifact of Go’s early HTTP implementation. It is low-level,
old, and unused by Go’s current HTTP stack. We should have deleted it before Go
1.

Deprecated: Use the Client or Transport in package net/http instead.

func NewProxyClientConn

  1. func NewProxyClientConn(c net.Conn, r *bufio.Reader) *ClientConn

NewProxyClientConn is an artifact of Go’s early HTTP implementation. It is
low-level, old, and unused by Go’s current HTTP stack. We should have deleted it
before Go 1.

Deprecated: Use the Client or Transport in package net/http instead.

func (*ClientConn) Close

  1. func (cc *ClientConn) Close() error

Close calls Hijack and then also closes the underlying connection.

func (*ClientConn) Do

  1. func (cc *ClientConn) Do(req *http.Request) (*http.Response, error)

Do is convenience method that writes a request and reads a response.

func (*ClientConn) Hijack

  1. func (cc *ClientConn) Hijack() (c net.Conn, r *bufio.Reader)

Hijack detaches the ClientConn and returns the underlying connection as well as
the read-side bufio which may have some left over data. Hijack may be called
before the user or Read have signaled the end of the keep-alive logic. The user
should not call Hijack while Read or Write is in progress.

func (*ClientConn) Pending

  1. func (cc *ClientConn) Pending() int

Pending returns the number of unanswered requests that have been sent on the
connection.

func (*ClientConn) Read

  1. func (cc *ClientConn) Read(req *http.Request) (resp *http.Response, err error)

Read reads the next response from the wire. A valid response might be returned
together with an ErrPersistEOF, which means that the remote requested that this
be the last request serviced. Read can be called concurrently with Write, but
not with another Read.

func (*ClientConn) Write

  1. func (cc *ClientConn) Write(req *http.Request) error

Write writes a request. An ErrPersistEOF error is returned if the connection has
been closed in an HTTP keepalive sense. If req.Close equals true, the keepalive
connection is logically closed after this request and the opposing server is
informed. An ErrUnexpectedEOF indicates the remote closed the underlying TCP
connection, which is usually considered as graceful close.

type ReverseProxy

  1. type ReverseProxy struct {
  2.     // Director must be a function which modifies
  3.     // the request into a new request to be sent
  4.     // using Transport. Its response is then copied
  5.     // back to the original client unmodified.
  6.     // Director must not access the provided Request
  7.     // after returning.
  8.     Director func(*http.Request)
  9.  
  10.     // The transport used to perform proxy requests.
  11.     // If nil, http.DefaultTransport is used.
  12.     Transport http.RoundTripper
  13.  
  14.     // FlushInterval specifies the flush interval
  15.     // to flush to the client while copying the
  16.     // response body.
  17.     // If zero, no periodic flushing is done.
  18.     FlushInterval time.Duration
  19.  
  20.     // ErrorLog specifies an optional logger for errors
  21.     // that occur when attempting to proxy the request.
  22.     // If nil, logging goes to os.Stderr via the log package's
  23.     // standard logger.
  24.     ErrorLog *log.Logger
  25.  
  26.     // BufferPool optionally specifies a buffer pool to
  27.     // get byte slices for use by io.CopyBuffer when
  28.     // copying HTTP response bodies.
  29.     BufferPool BufferPool
  30.  
  31.     // ModifyResponse is an optional function that
  32.     // modifies the Response from the backend.
  33.     // If it returns an error, the proxy returns a StatusBadGateway error.
  34.     ModifyResponse func(*http.Response) error
  35. }

ReverseProxy is an HTTP Handler that takes an incoming request and sends it to
another server, proxying the response back to the client.


Example:

  1. backendServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
  2.     fmt.Fprintln(w, "this call was relayed by the reverse proxy")
  3. }))
  4. defer backendServer.Close()
  6. rpURL, err := url.Parse(backendServer.URL)
  7. if err != nil {
  8.     log.Fatal(err)
  9. }
  10. frontendProxy := httptest.NewServer(httputil.NewSingleHostReverseProxy(rpURL))
  11. defer frontendProxy.Close()
  13. resp, err := http.Get(frontendProxy.URL)
  14. if err != nil {
  15.     log.Fatal(err)
  16. }
  18. b, err := ioutil.ReadAll(resp.Body)
  19. if err != nil {
  20.     log.Fatal(err)
  21. }
  23. fmt.Printf("%s", b)
  25. // Output:
  26. // this call was relayed by the reverse proxy

func NewSingleHostReverseProxy

  1. func NewSingleHostReverseProxy(target *url.URL) *ReverseProxy

NewSingleHostReverseProxy returns a new ReverseProxy that routes URLs to the
scheme, host, and base path provided in target. If the target’s path is “/base”
and the incoming request was for “/dir”, the target request will be for
/base/dir. NewSingleHostReverseProxy does not rewrite the Host header. To
rewrite Host headers, use ReverseProxy directly with a custom Director policy.

func (*ReverseProxy) ServeHTTP

  1. func (p *ReverseProxy) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type ServerConn

  1. type ServerConn struct {
  2.     // contains filtered or unexported fields
  3. }

ServerConn is an artifact of Go’s early HTTP implementation. It is low-level,
old, and unused by Go’s current HTTP stack. We should have deleted it before Go
1.

Deprecated: Use the Server in package net/http instead.

func NewServerConn

  1. func NewServerConn(c net.Conn, r *bufio.Reader) *ServerConn

NewServerConn is an artifact of Go’s early HTTP implementation. It is low-level,
old, and unused by Go’s current HTTP stack. We should have deleted it before Go
1.

Deprecated: Use the Server in package net/http instead.

func (*ServerConn) Close

  1. func (sc *ServerConn) Close() error

Close calls Hijack and then also closes the underlying connection.

func (*ServerConn) Hijack

  1. func (sc *ServerConn) Hijack() (net.Conn, *bufio.Reader)

Hijack detaches the ServerConn and returns the underlying connection as well as
the read-side bufio which may have some left over data. Hijack may be called
before Read has signaled the end of the keep-alive logic. The user should not
call Hijack while Read or Write is in progress.

func (*ServerConn) Pending

  1. func (sc *ServerConn) Pending() int

Pending returns the number of unanswered requests that have been received on the
connection.

func (*ServerConn) Read

  1. func (sc *ServerConn) Read() (*http.Request, error)

Read returns the next request on the wire. An ErrPersistEOF is returned if it is
gracefully determined that there are no more requests (e.g. after the first
request on an HTTP/1.0 connection, or after a Connection:close on a HTTP/1.1
connection).

func (*ServerConn) Write

  1. func (sc *ServerConn) Write(req *http.Request, resp *http.Response) error

Write writes resp in response to req. To close the connection gracefully, set
the Response.Close field to true. Write should be considered operational until
it returns an error, regardless of any errors returned on the Read side.