httputil

Documentation

Overview

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

Index

• Constants
• func BadRequestError(rw http.ResponseWriter, errorMessage string, args ...interface{})
• func BaseURL(urlStr string, req *http.Request) (string, error)
• func BasicAuth(req *http.Request) (username, password string, err error)
• func CertFingerprint(certPEM []byte) (string, error)
• func DecodeJSON(res *http.Response, dest interface{}) error
• func ErrorRouting(rw http.ResponseWriter, req *http.Request)
• func FileResponder(filename string) func() *http.Response
• func ForbiddenError(rw http.ResponseWriter, errorMessage string, args ...interface{})
• func GenSelfTLS(hostname string) (certPEM, keyPEM []byte, err error)
• func GenSelfTLSFiles(hostname, certPath, keyPath string) (fingerprint string, err error)
• func InstallCerts()
• func IsGet(r *http.Request) bool
• func IsLocalhost(req *http.Request) bool
• func IsWebsocketUpgrade(req *http.Request) bool
• func MustGet(req *http.Request, param string) string
• func MustGetBlobRef(req *http.Request, param string) blob.Ref
• func NewFakeTransport(urls map[string]func() *http.Response) http.RoundTripper
• func NewRegexpFakeTransport(allMatchers []*Matcher) (http.RoundTripper, error)
• func OptionalInt(req *http.Request, param string) int
• func PathBase(req *http.Request) string
• func PathSuffix(req *http.Request) string
• func Recover(rw http.ResponseWriter, req *http.Request)
• func RecoverJSON(rw http.ResponseWriter, req *http.Request)
• func RequestEntityTooLargeError(rw http.ResponseWriter)
• func RequestTargetPort(req *http.Request) int
• func ReturnJSON(rw http.ResponseWriter, data interface{})
• func ReturnJSONCode(rw http.ResponseWriter, code int, data interface{})
• func RootCAPool() *x509.CertPool
• func ServeError(rw http.ResponseWriter, req *http.Request, err error)
• func ServeJSONError(rw http.ResponseWriter, err interface{})
• func StaticResponder(res string) func() *http.Response
• func SystemCARootsAvailable() bool
• type InvalidMethodError
  • func (InvalidMethodError) Error() string
  • func (InvalidMethodError) HTTPCode() int
• type InvalidParameterError
  • func (p InvalidParameterError) Error() string
  • func (InvalidParameterError) HTTPCode() int
• type Matcher
• type MissingParameterError
  • func (p MissingParameterError) Error() string
  • func (MissingParameterError) HTTPCode() int
• type PrefixHandler
  • func (p *PrefixHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type ServerError
  • func (e ServerError) Error() string
  • func (ServerError) HTTPCode() int
• type StatsTransport
  • func (t *StatsTransport) ProtoVersions() (h1, h2 int)
  • func (t *StatsTransport) Requests() int
  • func (t *StatsTransport) RoundTrip(req *http.Request) (resp *http.Response, err error)

Constants

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

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 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 targeted 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)