Documentation

Overview

    Package httputil contains a bunch of HTTP utility code, some generic, and some Camlistore-specific.

    Index

    Constants

    View Source
    const (
    	PathBaseHeader   = "X-Prefixhandler-Pathbase"
    	PathSuffixHeader = "X-Prefixhandler-Pathsuffix"
    )

    Variables

    This section is empty.

    Functions

    func BadRequestError

    func BadRequestError(rw http.ResponseWriter, errorMessage string, args ...interface{})

    func BaseURL

    func BaseURL(urlStr string, req *http.Request) (string, error)

      BaseURL returns the base URL (scheme + host and optional port + blobserver prefix) that should be used for requests (and responses) subsequent to req. The returned URL does not end in a trailing slash. The scheme and host:port are taken from urlStr if present, or derived from req otherwise. The prefix part comes from urlStr.

      func BasicAuth

      func BasicAuth(req *http.Request) (username, password string, err error)

        BasicAuth parses the Authorization header on req If absent or invalid, an error is returned.

        func CertFingerprint

        func CertFingerprint(certPEM []byte) (string, error)

          CertFingerprint returns the SHA-256 prefix of the x509 certificate encoded in certPEM.

          func CertFingerprints

          func CertFingerprints(certPEM []byte) (map[string]string, error)

            CertFingerprints returns a map of hash prefixes of the x509 certificate encoded in certPEM. The hashes are keyed by name ("SHA-1", and "SHA-256").

            func DecodeJSON

            func DecodeJSON(res *http.Response, dest interface{}) error

              DecodeJSON decodes the JSON in res.Body into dest and then closes res.Body. It defensively caps the JSON at 8 MB for now.

              func ErrorRouting

              func ErrorRouting(rw http.ResponseWriter, req *http.Request)

              func FileResponder

              func FileResponder(filename string) func() *http.Response

                FileResponder returns an HTTP response generator that returns the contents of the named file.

                func ForbiddenError

                func ForbiddenError(rw http.ResponseWriter, errorMessage string, args ...interface{})

                func GenSelfTLS

                func GenSelfTLS(hostname string) (certPEM, keyPEM []byte, err error)

                  GenSelfTLS generates a self-signed certificate and key for hostname.

                  func GenSelfTLSFiles

                  func GenSelfTLSFiles(hostname, certPath, keyPath string) (fingerprint string, err error)

                    GenSelfTLSFiles generates a self-signed certificate and key for hostname, and writes them to the given paths. If it succeeds it also returns the SHA256 prefix of the new cert.

                    func InstallCerts

                    func InstallCerts()

                      InstallCerts adds Mozilla's Certificate Authority root set to http.DefaultTransport's configuration if the current operating system's root CAs are not available. (for instance, if running inside a Docker container without a filesystem)

                      func IsGet

                      func IsGet(r *http.Request) bool

                        IsGet reports whether r.Method is a GET or HEAD request.

                        func IsLocalhost

                        func IsLocalhost(req *http.Request) bool

                          IsLocalhost reports whether the requesting connection is from this machine and has the same owner as this process.

                          func IsWebsocketUpgrade

                          func IsWebsocketUpgrade(req *http.Request) bool

                          func MustGet

                          func MustGet(req *http.Request, param string) string

                            MustGet returns a non-empty GET (or HEAD) parameter param and panics with a special error as caught by a deferred httputil.Recover.

                            func MustGetBlobRef

                            func MustGetBlobRef(req *http.Request, param string) blob.Ref

                              MustGetBlobRef returns a non-nil BlobRef from req, as given by param. If it doesn't, it panics with a value understood by Recover or RecoverJSON.

                              func NewFakeTransport

                              func NewFakeTransport(urls map[string]func() *http.Response) http.RoundTripper

                                NewFakeTransport takes a map of URL to function generating a response and returns an http.RoundTripper that does HTTP requests out of that.

                                func NewRegexpFakeTransport

                                func NewRegexpFakeTransport(allMatchers []*Matcher) (http.RoundTripper, error)

                                  NewRegexpFakeTransport takes a slice of Matchers and returns an http.RoundTripper that will apply the function associated with the first UrlRegex that matches.

                                  func OptionalInt

                                  func OptionalInt(req *http.Request, param string) int

                                    OptionalInt returns the integer in req given by param, or 0 if not present. If the form value is not an integer, it panics with a a value understood by Recover or RecoverJSON.

                                    func PathBase

                                    func PathBase(req *http.Request) string

                                      PathBase returns a Request's base path, if it went via a PrefixHandler.

                                      func PathSuffix

                                      func PathSuffix(req *http.Request) string

                                        PathSuffix returns a Request's suffix path, if it went via a PrefixHandler.

                                        func Recover

                                        func Recover(rw http.ResponseWriter, req *http.Request)

                                          Recover is meant to be used at the top of handlers with "defer" to catch errors from MustGet, etc:

                                          func handler(rw http.ResponseWriter, req *http.Request) {
                                              defer httputil.Recover(rw, req)
                                              id := req.MustGet("id")
                                              ....
                                          

                                          Recover will send the proper HTTP error type and message (e.g. a 400 Bad Request for MustGet)

                                          func RecoverJSON

                                          func RecoverJSON(rw http.ResponseWriter, req *http.Request)

                                            RecoverJSON is like Recover but returns with a JSON response.

                                            func RequestEntityTooLargeError

                                            func RequestEntityTooLargeError(rw http.ResponseWriter)

                                            func RequestTargetPort

                                            func RequestTargetPort(req *http.Request) int

                                              RequestTargetPort returns the port targetted by the client in req. If not present, it returns 80, or 443 if TLS is used.

                                              func ReturnJSON

                                              func ReturnJSON(rw http.ResponseWriter, data interface{})

                                              func ReturnJSONCode

                                              func ReturnJSONCode(rw http.ResponseWriter, code int, data interface{})

                                              func RootCAPool

                                              func RootCAPool() *x509.CertPool

                                                RootCAPool returns the Mozilla Root Certificate Authority pool, as statically compiled into the binary.

                                                func ServeError

                                                func ServeError(rw http.ResponseWriter, req *http.Request, err error)

                                                func ServeJSONError

                                                func ServeJSONError(rw http.ResponseWriter, err interface{})

                                                  ServeJSONError sends a JSON error response to rw for the provided error value.

                                                  func StaticResponder

                                                  func StaticResponder(res string) func() *http.Response

                                                    StaticResponder returns an HTTP response generator that parses res for an entire HTTP response, including headers and body.

                                                    func SystemCARootsAvailable

                                                    func SystemCARootsAvailable() bool

                                                      SystemCARootsAvailable reports whether the operating system's root CA files are available.

                                                      Types

                                                      type InvalidMethodError

                                                      type InvalidMethodError struct{}

                                                        An InvalidMethodError is returned when an HTTP handler is invoked with an unsupported method.

                                                        func (InvalidMethodError) Error

                                                        func (InvalidMethodError) Error() string

                                                        func (InvalidMethodError) HTTPCode

                                                        func (InvalidMethodError) HTTPCode() int

                                                        type InvalidParameterError

                                                        type InvalidParameterError string

                                                          An InvalidParameterError represents an invalid HTTP parameter. The underlying string is the invalid parameter name, not value.

                                                          func (InvalidParameterError) Error

                                                          func (p InvalidParameterError) Error() string

                                                          func (InvalidParameterError) HTTPCode

                                                          func (InvalidParameterError) HTTPCode() int

                                                          type Matcher

                                                          type Matcher struct {
                                                          	URLRegex string                // will be compiled and matched against URLs
                                                          	Fn       func() *http.Response // function that will be run if URLRegex matches
                                                          }

                                                            Matcher describes a regular expression and the function that will be used if that regular expression is matched.

                                                            type MissingParameterError

                                                            type MissingParameterError string

                                                              A MissingParameterError represents a missing HTTP parameter. The underlying string is the missing parameter name.

                                                              func (MissingParameterError) Error

                                                              func (p MissingParameterError) Error() string

                                                              func (MissingParameterError) HTTPCode

                                                              func (MissingParameterError) HTTPCode() int

                                                              type PrefixHandler

                                                              type PrefixHandler struct {
                                                              	Prefix  string
                                                              	Handler http.Handler
                                                              }

                                                                PrefixHandler wraps another Handler and verifies that all requests' Path begin with Prefix. If they don't, a 500 error is returned. If they do, the headers PathBaseHeader and PathSuffixHeader are set on the request before proxying to Handler. PathBaseHeader is just the value of Prefix. PathSuffixHeader is the part of the path that follows Prefix.

                                                                func (*PrefixHandler) ServeHTTP

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

                                                                type ServerError

                                                                type ServerError string

                                                                  A ServerError is a generic 500 error.

                                                                  func (ServerError) Error

                                                                  func (e ServerError) Error() string

                                                                  func (ServerError) HTTPCode

                                                                  func (ServerError) HTTPCode() int

                                                                  type StatsTransport

                                                                  type StatsTransport struct {
                                                                  
                                                                  	// Transport optionally specifies the transport to use.
                                                                  	// If nil, http.DefaultTransport is used.
                                                                  	Transport http.RoundTripper
                                                                  
                                                                  	// If VerboseLog is true, HTTP request summaries are logged.
                                                                  	VerboseLog bool
                                                                  	// contains filtered or unexported fields
                                                                  }

                                                                    StatsTransport wraps another RoundTripper (or uses the default one) and counts the number of HTTP requests performed.

                                                                    func (*StatsTransport) ProtoVersions

                                                                    func (t *StatsTransport) ProtoVersions() (h1, h2 int)

                                                                      ProtoVersions returns how many HTTP/1 and HTTP/2 responses were seen.

                                                                      func (*StatsTransport) Requests

                                                                      func (t *StatsTransport) Requests() int

                                                                      func (*StatsTransport) RoundTrip

                                                                      func (t *StatsTransport) RoundTrip(req *http.Request) (resp *http.Response, err error)