httputil

package
v1.9.12 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 28, 2021 License: MIT Imports: 33 Imported by: 19

Documentation

Overview

Utilities for extracting and formatting data encountered in HTTP requests

Index

Examples

Constants

View Source
const (
	Get     Method = `GET`
	Post           = `POST`
	Put            = `PUT`
	Delete         = `DELETE`
	Head           = `HEAD`
	Options        = `OPTIONS`
	Patch          = `PATCH`
)

Variables

View Source
var DebugOutputBoxWidth = 60
View Source
var DefaultClient = MustClient(``)
View Source
var DefaultMultipartFormFileField = `filename`
View Source
var FormUnmarshalStructTag = `json`
View Source
var Logger = logging.MustGetLogger(`httputil`)
View Source
var NetrcFile = `~/.netrc`
View Source
var WaitForPollInterval = time.Second

Functions

func AddQ

func AddQ(u *url.URL, key string, values ...interface{})

Appends a query string from then given url.URL

func AddQString added in v1.8.6

func AddQString(u string, key string, value interface{}) string

A version of AddQ that accepts a URL string and makes a best-effort to modify it. Will return the modified URL or the original URL if an error occurred.

func DecodeResponse

func DecodeResponse(response *http.Response) (io.Reader, error)

Takes an http.Response and returns an io.Reader that will return the contents of the Response Body decoded according to the values (if any) of the Content-Encoding response header.

func DelQ

func DelQ(u *url.URL, key string)

Deletes a query string from then given url.URL

func DelQString added in v1.8.6

func DelQString(u string, key string) string

A version of DelQ that accepts a URL string and makes a best-effort to modify it. Will return the modified URL or the original URL if an error occurred.

func EncodeBasicAuth added in v1.7.28

func EncodeBasicAuth(username string, password string) string

Encode the username and password into a value than can be used in the Authorization HTTP header.

func GetBody added in v1.8.95

func GetBody(url string) ([]byte, error)

A simplified GET function using the package-level default client. Will return the response body as bytes.

func Is1xx added in v1.8.45

func Is1xx(code int) bool

Returns whether the given status code is 100 <= s <= 199

func Is2xx added in v1.8.45

func Is2xx(code int) bool

Returns whether the given status code is 200 <= s <= 299

func Is3xx added in v1.8.45

func Is3xx(code int) bool

Returns whether the given status code is 300 <= s <= 399

func Is4xx added in v1.8.45

func Is4xx(code int) bool

Returns whether the given status code is 400 <= s <= 499

func Is5xx added in v1.8.45

func Is5xx(code int) bool

Returns whether the given status code is 500 <= s <= 599

func IsHttpErr

func IsHttpErr(err error) bool

func IsMediaType added in v1.8.43

func IsMediaType(req *http.Request, mediaTypes ...string) bool

Returns whether the Content-Type of the given request matches any of the supplied options. The mediaTypes arguments may be either complete media types (e.g.: "text/html", "application/javascript") or major type classes (e.g.: "text/", "video/"). The trailing slash (/) indicates that any media type that begins with that text will match.

Example (MediaTypePrefix)
req := httptest.NewRequest(`GET`, `/`, nil)
req.Header.Set(`Content-Type`, `text/html; charset=utf-8`)

fmt.Println(IsMediaType(req, `text/`))
Output:

true
Example (MultipleMediaTypes)
req := httptest.NewRequest(`GET`, `/`, nil)
req.Header.Set(`Content-Type`, `text/html; charset=utf-8`)

fmt.Println(IsMediaType(req, `text/html`, `text/plain`))
Output:

true
Example (NonMatchingPrefix)
req := httptest.NewRequest(`GET`, `/`, nil)
req.Header.Set(`Content-Type`, `text/html; charset=utf-8`)

fmt.Println(IsMediaType(req, `video/`))
Output:

false
Example (SingleMediaType)
req := httptest.NewRequest(`GET`, `/`, nil)
req.Header.Set(`Content-Type`, `text/html; charset=utf-8`)

fmt.Println(IsMediaType(req, `text/html`))
Output:

true

func JSONDecoder

func JSONDecoder(in io.Reader, out interface{}) error

func JSONEncoder

func JSONEncoder(in interface{}) (io.Reader, error)

func LoadCertPool added in v1.6.25

func LoadCertPool(filename string) (*x509.CertPool, error)

Loads certificates from the given file and returns a usable x509.CertPool

func MediaType added in v1.8.43

func MediaType(req *http.Request) string

Returns the media type from the request's Content-Type.

func MultipartFormEncoder added in v1.7.40

func MultipartFormEncoder(in interface{}) (io.Reader, error)

Specifies that the given data should be encoded as a multipart/form-data request.

func NetrcCredentials added in v1.8.94

func NetrcCredentials(domain string) (string, string, bool)

Retreive the plaintext username and password from the netrc-formatted file in the NetrcFile package variable. The final return argument will be true if and only if the .netrc file exists, is readable, and the username OR password matched to the given domain is non-empty.

func ParseFormRequest

func ParseFormRequest(req *http.Request, into interface{}) error

Parses the form values for a Request and unmarshals into the given value.

func ParseFormValues

func ParseFormValues(formValues url.Values, into interface{}) error

Parses a set of values received from an HTML form (usually the value of the http.Request.Form property) and unmarshals into the given value.

func ParseJSON

func ParseJSON(r io.Reader, into interface{}) error

Parses a given reader as a JSON document and unmarshals into the given value.

func ParseJSONRequest

func ParseJSONRequest(req *http.Request, into interface{}) error

Parses the Request as JSON and unmarshals into the given value.

func ParseRequest

func ParseRequest(req *http.Request, into interface{}) error

Autodetect the Content-Type of the given request and unmarshals into the given value.

func Q

func Q(req *http.Request, key string, fallbacks ...string) string

Parses the named query string from a request as a string.

func QBool

func QBool(req *http.Request, key string, fallbacks ...bool) bool

Parses the named query string from a request as a boolean value.

func QDuration added in v1.6.23

func QDuration(req *http.Request, key string) time.Duration

Parses the named query string from a request as a duration string.

func QFloat

func QFloat(req *http.Request, key string, fallbacks ...float64) float64

Parses the named query string from a request as a float.

func QInt

func QInt(req *http.Request, key string, fallbacks ...int64) int64

Parses the named query string from a request as an integer.

func QStrings added in v1.5.58

func QStrings(req *http.Request, key string, delimiter string, fallbacks ...string) []string

Parses the named query string from a request as a delimiter-separated string slice.

func QTime

func QTime(req *http.Request, key string) time.Time

Parses the named query string from a request as a date/time value.

func RequestGetValue added in v1.8.28

func RequestGetValue(req *http.Request, key string) typeutil.Variant

Retrieve an arbitrary value from the context of a given request.

func RequestSetValue added in v1.8.28

func RequestSetValue(req *http.Request, key string, value interface{})

attach an arbitrary value to the context of a given request.

func RespondJSON

func RespondJSON(w http.ResponseWriter, data interface{}, status ...int)

Marshal the given data as a JSON document and write the output to the given ResponseWriter. If a status is given, that will be used as the HTTP response status. If data is an error, and no status is given, the status will be "500 Internal Server Error"; if data is nil, the status will be "204 No Content". The Content-Type of the response is "application/json".

func SetContentTypeParser

func SetContentTypeParser(contentType string, parser RequestParseFunc)

Sets a parser implementation for the given HTTP content type.

func SetQ

func SetQ(u *url.URL, key string, value interface{})

Sets a query string to the given value in the given url.URL

func SetQString added in v1.8.6

func SetQString(u string, key string, value interface{}) string

A version of SetQ that accepts a URL string and makes a best-effort to modify it. Will return the modified URL or the original URL if an error occurred.

func SetRootCABundle added in v1.6.24

func SetRootCABundle(client *http.Client, caBundle string) error

Configures the given http.Client to accept TLS certificates validated by the given PEM-encoded CA bundle file

func UrlPathJoin added in v1.8.53

func UrlPathJoin(baseurl interface{}, path string) (*url.URL, error)

UrlPathJoin takes a string or *url.URL and joins the existing URL path component with the given path. The new path may also contain query string values, which will be added to the base URL. Existing keys will be replaced with new ones, except for repeated keys (e.g.: ?x=1&x=2&x=3). In this case, the new values will be added to the existing ones. The *url.URL returned from this function is a copy, and the original URL (if one is provided) will not be modified in any way.

Example (EmptyJoin)
url, _ := UrlPathJoin(`https://google.com/`, ``)
fmt.Println(url.String())
Output:

https://google.com/
Example (JoinToExistingQueryStrings)
url, _ := UrlPathJoin(`https://google.com/search`, `?q=hello`)
fmt.Println(url.String())
Output:

https://google.com/search?q=hello
Example (JoinWithQueryString)
url, _ := UrlPathJoin(`https://google.com/`, `/search?q=hello`)
fmt.Println(url.String())
Output:

https://google.com/search?q=hello
Example (PathAndQuery)
url, _ := UrlPathJoin(`https://example.com/api/v1?hello=there`, `/things/new?example=true`)
fmt.Println(url.String())
Output:

https://example.com/api/v1/things/new?example=true&hello=there
Example (PathAndQueryTrailingSlash)
url, _ := UrlPathJoin(`https://example.com/api/v1?hello=there`, `/things/new/?example=true`)
fmt.Println(url.String())
Output:

https://example.com/api/v1/things/new/?example=true&hello=there
Example (SimpleJoin)
url, _ := UrlPathJoin(`https://google.com`, `/search`)
fmt.Println(url.String())
Output:

https://google.com/search
Example (SlashJoin)
url, _ := UrlPathJoin(`https://google.com/`, `/`)
fmt.Println(url.String())
Output:

https://google.com/

func WaitForHTTP added in v1.8.40

func WaitForHTTP(url string, timeout time.Duration, c ...*http.Client) error

Periodically performs a GET request against the given URL, waiting up to timeout for a 200-series HTTP response code.

func XMLDecoder added in v1.8.87

func XMLDecoder(in io.Reader, out interface{}) error

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func MustClient added in v1.8.82

func MustClient(baseURI string) *Client

func NewClient

func NewClient(baseURI string) (*Client, error)

func (*Client) AppendTrustedRootCA added in v1.7.25

func (self *Client) AppendTrustedRootCA(pemFilenamesOrData ...interface{}) error

Append one or more trusted certificates to the RootCA bundle that is consulted when performing HTTPS requests.

func (*Client) ClearHeaders

func (self *Client) ClearHeaders()

Remove all implicit HTTP request headers.

func (*Client) ClearParams

func (self *Client) ClearParams()

Remove all implicit querystring parameters.

func (*Client) Client

func (self *Client) Client() *http.Client

Returns the HTTP client used to perform requests

func (*Client) Decode

func (self *Client) Decode(r io.Reader, out interface{}) error

Decode a response and, if applicable, automatically close the reader.

func (*Client) Delete

func (self *Client) Delete(path string, params map[string]interface{}, headers map[string]interface{}) (*http.Response, error)

func (*Client) Encode

func (self *Client) Encode(in interface{}) ([]byte, error)

func (*Client) Get

func (self *Client) Get(path string, params map[string]interface{}, headers map[string]interface{}) (*http.Response, error)

func (*Client) GetWithBody

func (self *Client) GetWithBody(path string, body interface{}, params map[string]interface{}, headers map[string]interface{}) (*http.Response, error)

func (*Client) Headers added in v1.8.60

func (self *Client) Headers() http.Header

Return the headers set on this client.

func (*Client) Params added in v1.8.60

func (self *Client) Params() map[string]interface{}

Return the params set on this client.

func (*Client) Post

func (self *Client) Post(path string, body interface{}, params map[string]interface{}, headers map[string]interface{}) (*http.Response, error)

func (*Client) Put

func (self *Client) Put(path string, body interface{}, params map[string]interface{}, headers map[string]interface{}) (*http.Response, error)

func (*Client) Request

func (self *Client) Request(
	method Method,
	path string,
	body interface{},
	params map[string]interface{},
	headers map[string]interface{},
) (*http.Response, error)

Perform an HTTP request

func (*Client) SetAutomaticLogin added in v1.8.94

func (self *Client) SetAutomaticLogin(on bool)

Specify that the NetrcFile (default: ~/.netrc) should be consulted before each request to supply basic authentication. If a non-empty username or password is found for the

func (*Client) SetBasicAuth added in v1.7.28

func (self *Client) SetBasicAuth(username string, password string)

Set the username and password to be included in the Authorization header.

func (*Client) SetClient

func (self *Client) SetClient(client *http.Client)

Replace the default HTTP client with a user-provided one

func (*Client) SetDecoder

func (self *Client) SetDecoder(fn DecoderFunc)

Specify a decoder that will be used to deserialize data in the response body.

func (*Client) SetEncoder

func (self *Client) SetEncoder(fn EncoderFunc)

Specify an encoder that will be used to serialize data in the request body.

func (*Client) SetErrorDecoder

func (self *Client) SetErrorDecoder(fn ErrorDecoderFunc)

Specify a different decoder used to deserialize non 2xx/3xx HTTP responses.

func (*Client) SetHeader

func (self *Client) SetHeader(name string, value interface{})

Add an HTTP request header by name that will be included in every request. If value is nil, the named header will be removed instead.

func (*Client) SetInitHook added in v1.8.84

func (self *Client) SetInitHook(fn InitRequestFunc)

Specify a function that will be called immediately before the first request is sent. This function has an opportunity to read and modify the outgoing request, and if it returns a non-nil error, the request will not be sent.

func (*Client) SetInsecureTLS added in v1.7.26

func (self *Client) SetInsecureTLS(insecure bool)

Set or unset insecure TLS requests that will proceed even if the peer certificate cannot be verified.

func (*Client) SetParam

func (self *Client) SetParam(name string, value interface{})

Add a querystring parameter by name that will be included in every request. If value is nil, the parameter will be removed instead.

func (*Client) SetPostRequestHook

func (self *Client) SetPostRequestHook(fn InterceptResponseFunc)

Specify a function tht will be called immediately after a response is received. This function is given the first opportunity to inspect the response, and if it returns a non-nil error, no additional processing (including the Error Decoder function) will be performed.

func (*Client) SetPreRequestHook

func (self *Client) SetPreRequestHook(fn InterceptRequestFunc)

Specify a function that will be called immediately before a request is sent. This function has an opportunity to read and modify the outgoing request, and if it returns a non-nil error, the request will not be sent.

func (*Client) SetRootCA added in v1.7.25

func (self *Client) SetRootCA(pemFilenamesOrData ...interface{}) error

Replace the existing RootCA bundle with an explicit set of trusted certificates.

func (*Client) URI

func (self *Client) URI() *url.URL

Return the base URI for this client.

func (*Client) WithDecoder added in v1.7.40

func (self *Client) WithDecoder(fn DecoderFunc) *Client

Return a copy of the current client that uses a different decoder.

func (*Client) WithEncoder added in v1.7.40

func (self *Client) WithEncoder(fn EncoderFunc) *Client

Return a copy of the current client that uses a different encoder.

type DecoderFunc

type DecoderFunc func(io.Reader, interface{}) error

type EncoderFunc

type EncoderFunc func(interface{}) (io.Reader, error)

type ErrorDecoderFunc

type ErrorDecoderFunc func(*http.Response) error

type InitRequestFunc added in v1.8.84

type InitRequestFunc func() error

type InterceptRequestFunc

type InterceptRequestFunc func(*http.Request) (interface{}, error)

type InterceptResponseFunc

type InterceptResponseFunc func(*http.Response, interface{}) error

type Literal added in v1.8.76

type Literal []byte

type LogLevel

type LogLevel int
const (
	Debug LogLevel = iota
	Info
	Notice
	Warning
	Error
	Fatal
)

type Method

type Method string

type MultipartFormFile added in v1.7.40

type MultipartFormFile struct {
	Filename string    `json:"filename"`
	Data     io.Reader `json:"data"`
}

type RequestLogger deprecated

type RequestLogger struct {
}

Deprecated: this type will go away in 1.9.x

func NewRequestLogger

func NewRequestLogger() *RequestLogger

func (*RequestLogger) ServeHTTP

func (self *RequestLogger) ServeHTTP(rw http.ResponseWriter, req *http.Request, next http.HandlerFunc)

type RequestParseFunc

type RequestParseFunc func(*http.Request, interface{}) error

type WritableLogger

type WritableLogger struct {
	// contains filtered or unexported fields
}

func NewWritableLogger

func NewWritableLogger(level LogLevel, prefix ...string) *WritableLogger

func (*WritableLogger) Write

func (self *WritableLogger) Write(p []byte) (int, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL