Documentation ¶
Overview ¶
Package vhttp contains helper functions for testing aspects of http.Request or http.Response objects from the net/http package.
The core functions used are ValidateRequest and ValidateResponse whose arguments (in addition to the http.Request or http.Response) implement the RequestValidator ResponseValidator interfaces, respectively.
This package also includes helper types for validating specific aspects of the requests or responses, such as the MethodValidator, HeaderValidator, or the BodyValidator.
Some helper functions exist for creating validator functions but others can be created manually.
Index ¶
- Constants
- Variables
- func InternalErr(err error) error
- func ValidateRequest(req *http.Request, vs ...RequestValidator) error
- func ValidateResponse(res *http.Response, vs ...ResponseValidator) error
- type BodyValidator
- func BodyDetectedTypeIs(t string) BodyValidator
- func BodyIs(b []byte) BodyValidator
- func BodyIsNil() BodyValidator
- func BodyIsString(s string) BodyValidator
- func BodyIsValidJSON() BodyValidator
- func BodyJSONUnmarshalsAs(v any) BodyValidator
- func BodyLengthIs(n int) BodyValidator
- func BodyXMLUnmarshalsAs(v any) BodyValidator
- type CachedBodyValidator
- type HeaderValidator
- func HasHeader(h string) HeaderValidator
- func HasHeaderAccept() HeaderValidator
- func HasHeaderAuthorization() HeaderValidator
- func HasHeaderContentType(ct string) HeaderValidator
- func HeaderAuthorizationIs(t string) HeaderValidator
- func HeaderAuthorizationMatchesBasic() HeaderValidator
- func HeaderAuthorizationMatchesBearer() HeaderValidator
- func HeaderContentTypeIs(ct string) HeaderValidator
- func HeaderContentTypeJSON() HeaderValidator
- func HeaderContentTypeXML() HeaderValidator
- func HeaderIs(h, v string) HeaderValidator
- func HeaderMatches(h string, re *regexp.Regexp) HeaderValidator
- type InternalError
- type MethodValidator
- func MethodIs(s string) MethodValidator
- func MethodIsDelete() MethodValidator
- func MethodIsGet() MethodValidator
- func MethodIsNot(s string) MethodValidator
- func MethodIsOptions() MethodValidator
- func MethodIsPatch() MethodValidator
- func MethodIsPost() MethodValidator
- func MethodIsPut() MethodValidator
- type ProtoValidator
- type RequestFunc
- type RequestValidator
- type ResponseFunc
- type ResponseValidator
- type StatusCodeValidator
- func StatusInRange(min, max int) StatusCodeValidator
- func StatusIs(code int) StatusCodeValidator
- func StatusIs1XX() StatusCodeValidator
- func StatusIs2XX() StatusCodeValidator
- func StatusIs3XX() StatusCodeValidator
- func StatusIs4XX() StatusCodeValidator
- func StatusIs5XX() StatusCodeValidator
- func StatusIsNot(code int) StatusCodeValidator
- func StatusIsOK() StatusCodeValidator
- func StatusNotError() StatusCodeValidator
- func StatusNotInRange(min, max int) StatusCodeValidator
- type TLSValidator
- type URLValidator
- func URLHostIs(h string) URLValidator
- func URLIs(s string) URLValidator
- func URLPathGlob(p string) URLValidator
- func URLPathIs(p string) URLValidator
- func URLQueryHas(k string) URLValidator
- func URLQueryIs(k, v string) URLValidator
- func URLQueryValueValidator(k string, vfn func(string) error) URLValidator
- func URLSchemeIs(s string) URLValidator
- func URLSchemeIsHTTP() URLValidator
- func URLSchemeIsHTTPS() URLValidator
- func URLUserinfoIs(ui string) URLValidator
Examples ¶
Constants ¶
const ( HeaderContentType = "Content-Type" HeaderAccept = "Accept" HeaderHost = "Host" HeaderAuthorization = "Authorization" HeaderConnection = "Connection" )
Common headers, used for convenience
const ( MimePlain = "text/plain" MimeHTML = "text/html" MimeCSS = "text/css" MimeTextJavascript = "text/javascript" MimeJSON = "application/json" MimeXML = "application/xml" MimeImageAPNG = "image/apng" MimeImageAVIF = "image/avif" MimeImageGIF = "image/gif" MimeImageJPEG = "image/jpeg" MimeImagePNG = "image/png" MimeImageSVGXML = "image/svg+xml" MimeImageWEBP = "image/webp" )
Common Content-Type / MIME type values
Variables ¶
var ( BasicAuthMatch = regexp.MustCompile(`^Basic .+$`) BearerAuthMatch = regexp.MustCompile(`^Bearer .+$`) )
Regular expressions for matching against (simplified) Authentication HTTP headers.
var CanonicalHeaderKey func(string) string = http.CanonicalHeaderKey
CanonicallHeaderKey converts the given string to a canonical form.
This function is used in Header validation function, on the keys of the HeaderValidators parameter. By copying the function from the net/http package, this can be replaced with a custom implementation, if that functionality needs to be changed.
Functions ¶
func ValidateRequest ¶
func ValidateRequest(req *http.Request, vs ...RequestValidator) error
ValidateRequest validates the request against the given validators.
Example ¶
package main import ( "bytes" "fmt" "io" "net/http" "net/url" "github.com/a-poor/vhttp" ) func asReadCloser(b []byte) io.ReadCloser { return io.NopCloser(bytes.NewReader(b)) } func main() { // Create a sample request... u, _ := url.Parse("https://example.com/api/v1/users") req := &http.Request{ Method: http.MethodPost, Header: http.Header{ "Content-Type": []string{"application/json"}, "Authorization": []string{"Basic abcde12345"}, }, Body: asReadCloser([]byte(`{{{{`)), URL: u, } // Validate the request... err := vhttp.ValidateRequest(req, // Is a "GET" request vhttp.MethodIsGet(), // Calling json.Valid() on the body returns true vhttp.BodyIsValidJSON(), // Has the header "Content-Type" and it's equal to "application/json" vhttp.HeaderContentTypeJSON(), // The header "Authorization" matches the regular expression ^Bearer .+$ vhttp.HeaderAuthorizationMatchesBearer(), // Has the URL path "/api/v2/posts" vhttp.URLPathIs("/api/v2/posts"), ) // Print the output... fmt.Println(err) }
Output: 4 errors occurred: * expected method "GET", found "POST" * body is not valid JSON * expected header "Authorization" to match "^Bearer .+$" * expected URL path "/api/v2/posts", found "/api/v1/users"
func ValidateResponse ¶
func ValidateResponse(res *http.Response, vs ...ResponseValidator) error
ValidateResponse validates the response against the given validators.
Types ¶
type BodyValidator ¶
BodyValidator is a validator that validates an http.Request's body.
Note that this expects the body to be fully read as a byte slice. If more than one BodyValidator is being used, you should use a CachedBodyValidator instead – which will read the body once and pass the resulting byte slice to all of the BodyValidators.
func BodyDetectedTypeIs ¶
func BodyDetectedTypeIs(t string) BodyValidator
BodyDetectedTypeIs uses the http.DetectContentType function to guess the content type of the body and returns an error if it does not match the expected type t.
func BodyIs ¶
func BodyIs(b []byte) BodyValidator
BodyIs validates that the body is equal to the given byte slice.
func BodyIsString ¶
func BodyIsString(s string) BodyValidator
BodyIsString validates that the body is equal to the given string.
func BodyIsValidJSON ¶
func BodyIsValidJSON() BodyValidator
BodyIsValidJSON uses the json.Valid function (from the encoding/json) to test if the body is valid JSON.
func BodyJSONUnmarshalsAs ¶
func BodyJSONUnmarshalsAs(v any) BodyValidator
BodyJSONUnmarshalsAs attmepts to uses the json.Unmarshal function to unmarshal the body. If it fails, an error is returned.
func BodyLengthIs ¶
func BodyLengthIs(n int) BodyValidator
BodyLengthIs validates that the body has the given length n.
func BodyXMLUnmarshalsAs ¶
func BodyXMLUnmarshalsAs(v any) BodyValidator
BodyXMLUnmarshalsAs attmepts to uses the xml.Unmarshal function to unmarshal the body. If it fails, an error is returned.
func (BodyValidator) ValidateRequest ¶
func (v BodyValidator) ValidateRequest(req *http.Request) error
func (BodyValidator) ValidateResponse ¶
func (v BodyValidator) ValidateResponse(res *http.Response) error
type CachedBodyValidator ¶
type CachedBodyValidator struct {
// contains filtered or unexported fields
}
CachedBodyValidator is a RequestValidator/ResponseValidator that reads the Request or Response body once and passes the byte slice to each of it's BodyValidators (rather than calling their ValidateRequest or ValidateResponse methods each time).
This helps avoid duplicated reads of the body and prevents issues with attemps to read the body after it has been closed.
func CacheBody ¶
func CacheBody(vs ...BodyValidator) CachedBodyValidator
CacheBody creates a new CachedBodyValidator
func (CachedBodyValidator) ValidateRequest ¶
func (v CachedBodyValidator) ValidateRequest(req *http.Request) error
func (CachedBodyValidator) ValidateResponse ¶
func (v CachedBodyValidator) ValidateResponse(res *http.Response) error
type HeaderValidator ¶
HeaderValidator is a validator that validates an http.Request or http.Response object's headers.
func HasHeader ¶
func HasHeader(h string) HeaderValidator
HasHeader creates a request validator that checks that the header h is present in the request object.
Note that this function will convert the header key to canonical form using the vhttp.CanonicalHeaderKey function. If this behavior needs to be changed, either create a custom validator or change the value of the function.
func HasHeaderAccept ¶
func HasHeaderAccept() HeaderValidator
HasHeaderAccept creates a request validator that checks that the header "Accept" is present in the request object.
func HasHeaderAuthorization ¶
func HasHeaderAuthorization() HeaderValidator
HasHeaderAuthorization creates a request validator that checks that the "Authorization" header is present in the request object.
func HasHeaderContentType ¶
func HasHeaderContentType(ct string) HeaderValidator
HasHeaderContentType creates a request validator that checks that the "Content-Type" header is present in the request object.
func HeaderAuthorizationIs ¶
func HeaderAuthorizationIs(t string) HeaderValidator
HeaderAuthorizationIs creates a request validator that checks that at least one of the "Authorization" header values are equal to t.
func HeaderAuthorizationMatchesBasic ¶
func HeaderAuthorizationMatchesBasic() HeaderValidator
HeaderAuthorizationMatchesBasic creates a request validator that checks that the request header value for the Authorization header matches the regular expression for a basic authentication header.
The regular expression is defined in the variable vhttp.BasicAuthMatch as `^Basic .+`.
func HeaderAuthorizationMatchesBearer ¶
func HeaderAuthorizationMatchesBearer() HeaderValidator
HeaderAuthorizationMatchesBearer creates a request validator that checks that the request header value for the Authorization header matches the regular expression for a bearer authentication token.
The regular expression is defined in the variable vhttp.BearerAuthMatch as `^Bearer .+`.
func HeaderContentTypeIs ¶
func HeaderContentTypeIs(ct string) HeaderValidator
HeaderContentTypeIs creates a request validator that checks that at least one of the "Content-Type" header values are equal to t.
func HeaderContentTypeJSON ¶
func HeaderContentTypeJSON() HeaderValidator
HeaderContentTypeJSON creates a request validator that checks that at least one of the "Content-Type" header values are equal to "application/json".
func HeaderContentTypeXML ¶
func HeaderContentTypeXML() HeaderValidator
HeaderContentTypeXML creates a request validator that checks that at least one of the "Content-Type" header values are equal to "application/xml".
func HeaderIs ¶
func HeaderIs(h, v string) HeaderValidator
HeaderIs creates a request validator that checks that at least one of the values for header h is equal to v.
Note that this function will convert the header key to canonical form using the vhttp.CanonicalHeaderKey function. If this behavior needs to be changed, either create a custom validator or change the value of the function.
func HeaderMatches ¶
func HeaderMatches(h string, re *regexp.Regexp) HeaderValidator
HeaderMatches creates a request validator that checks that at least one of the request header values matche the given regular expression.
Note that this function will convert the header key to canonical form using the vhttp.CanonicalHeaderKey function. If this behavior needs to be changed, either create a custom validator or change the value of the function.
func (HeaderValidator) ValidateRequest ¶
func (v HeaderValidator) ValidateRequest(req *http.Request) error
func (HeaderValidator) ValidateResponse ¶
func (v HeaderValidator) ValidateResponse(res *http.Response) error
type InternalError ¶
type InternalError struct {
// contains filtered or unexported fields
}
InternalError is used to signal that an error returned from a validator is not a validation error but an internal error.
An InternalError is meant to wrap a real error returned in the process of validating a request or response.
func (InternalError) Error ¶
func (e InternalError) Error() string
func (InternalError) Unwrap ¶
func (e InternalError) Unwrap() error
func (InternalError) Wrap ¶
func (e InternalError) Wrap(msg string) error
Wrap returns a new InternalError where the underlying error is the result of wrapping e's underlying error (using fmt.Errorf) with the message msg prepended to the error message chain.
Equivalent to:
err := vhttp.InternalErr(fmt.Errorf("%s: %w", msg, ierr.Unwrap()))
type MethodValidator ¶
MethodValidator is a validator that validates an http.Request's method.
func MethodIs ¶
func MethodIs(s string) MethodValidator
MethodIs creates a request validator that checks that the request method is equal to the given method m.
func MethodIsDelete ¶
func MethodIsDelete() MethodValidator
MethodIsDelete creates a request validator that checks that the request is a DELETE request.
func MethodIsGet ¶
func MethodIsGet() MethodValidator
MethodIsGet creates a request validator that checks that the request is a GET request.
func MethodIsNot ¶
func MethodIsNot(s string) MethodValidator
MethodIs creates a request validator that checks that the request method is NOT equal to the given method m.
func MethodIsOptions ¶
func MethodIsOptions() MethodValidator
MethodIsOptions creates a request validator that checks that the request is a OPTIONS request.
func MethodIsPatch ¶
func MethodIsPatch() MethodValidator
MethodIsPatch creates a request validator that checks that the request is a PATCH request.
func MethodIsPost ¶
func MethodIsPost() MethodValidator
MethodIsPost creates a request validator that checks that the request is a POST request.
func MethodIsPut ¶
func MethodIsPut() MethodValidator
MethodIsPut creates a request validator that checks that the request is a PUT request.
func (MethodValidator) ValidateRequest ¶
func (v MethodValidator) ValidateRequest(req *http.Request) error
type ProtoValidator ¶
ProtoValidator is a validator that validates an http.Request or http.Response's Proto field.
func (ProtoValidator) ValidateRequest ¶
func (v ProtoValidator) ValidateRequest(req *http.Request) error
func (ProtoValidator) ValidateResponse ¶
func (v ProtoValidator) ValidateResponse(res *http.Response) error
type RequestFunc ¶
RequestFunc is a function that validates an http.Request and can act as a RequestValidator.
func (RequestFunc) ValidateRequest ¶
func (v RequestFunc) ValidateRequest(req *http.Request) error
type RequestValidator ¶
RequestValidator is a validator that validates an http.Request.
type ResponseFunc ¶
ResponseFunc is a function that validates an http.Response and can act as a ResponseValidator.
func (ResponseFunc) ValidateResponse ¶
func (v ResponseFunc) ValidateResponse(res *http.Response) error
type ResponseValidator ¶
ResponseValidator is a validator that validates an http.Response.
type StatusCodeValidator ¶
StatusCodeValidator is a function that validates an http.Response's status code.
func StatusInRange ¶
func StatusInRange(min, max int) StatusCodeValidator
StatusInRange checks that the status code is in the given range: [min, max).
func StatusIs ¶
func StatusIs(code int) StatusCodeValidator
StatusIs checks that the status code is equal to the given code.
func StatusIs1XX ¶
func StatusIs1XX() StatusCodeValidator
StatusIs1XX checks that the status code is in the range [100, 200).
func StatusIs2XX ¶
func StatusIs2XX() StatusCodeValidator
StatusIs2XX checks that the status code is in the range [200, 300).
func StatusIs3XX ¶
func StatusIs3XX() StatusCodeValidator
StatusIs3XX checks that the status code is in the range [300, 400).
func StatusIs4XX ¶
func StatusIs4XX() StatusCodeValidator
StatusIs4XX checks that the status code is in the range [400, 500).
func StatusIs5XX ¶
func StatusIs5XX() StatusCodeValidator
StatusIs5XX checks that the status code is in the range [500, 600).
func StatusIsNot ¶
func StatusIsNot(code int) StatusCodeValidator
StatusIsNot checks that the status code is not equal to the given code.
func StatusIsOK ¶
func StatusIsOK() StatusCodeValidator
StatusIsOK checks that the status code is 200.
func StatusNotError ¶
func StatusNotError() StatusCodeValidator
StatusIsError checks that the status code is not in the range [400, 600).
func StatusNotInRange ¶
func StatusNotInRange(min, max int) StatusCodeValidator
StatusNotInRange checks that the status code is not in the given range: [min, max).
func (StatusCodeValidator) ValidateResponse ¶
func (v StatusCodeValidator) ValidateResponse(res *http.Response) error
type TLSValidator ¶
type TLSValidator func(*tls.ConnectionState) error
TLSValidator is a validator that validates an http.Request or http.Response object's TLS connection.
func TLSIsNil ¶
func TLSIsNil() TLSValidator
func TLSIsNotNil ¶
func TLSIsNotNil() TLSValidator
func TLSVersionIs ¶
func TLSVersionIs(v uint16) TLSValidator
func (TLSValidator) ValidateRequest ¶
func (v TLSValidator) ValidateRequest(req *http.Request) error
func (TLSValidator) ValidateResponse ¶
func (v TLSValidator) ValidateResponse(res *http.Response) error
type URLValidator ¶
URLValidator is a validator function that validates an http.Request's URL field.
func URLHostIs ¶
func URLHostIs(h string) URLValidator
URLHostIs creates a URL validator that checks that the URL's Host field matches h.
func URLIs ¶
func URLIs(s string) URLValidator
URLIs creates a url validator that checks that the URL exactly matches the given string s.
func URLPathGlob ¶
func URLPathGlob(p string) URLValidator
URLPathGlob creates a URL validator that checks that the URL's path matches the given glob pattern p.
Uses path.Match to match the glob pattern.
func URLPathIs ¶
func URLPathIs(p string) URLValidator
URLPathIs creates a URLValidator that checks that the request URL's path is equal to the given path p.
func URLQueryHas ¶
func URLQueryHas(k string) URLValidator
URLQueryHas creates a URLValidator that checks that the request URL's query parameters contain the given key k.
func URLQueryIs ¶
func URLQueryIs(k, v string) URLValidator
URLQueryIs creates a URLValidator that checks that the request URL's query parameters contain the given key k with the value v.
func URLQueryValueValidator ¶
func URLQueryValueValidator(k string, vfn func(string) error) URLValidator
URLQueryValueValidator creates a URLValidator that applies the validator function vfn to the first value for the given key in the request URL's query.
func URLSchemeIs ¶
func URLSchemeIs(s string) URLValidator
URLSchemeIs creates a URLValidator that checks that the request URL's scheme matches the given scheme s.
func URLSchemeIsHTTP ¶
func URLSchemeIsHTTP() URLValidator
URLSchemeIsHTTP creates a URLValidator that checks that the request URL's scheme is "http".
func URLSchemeIsHTTPS ¶
func URLSchemeIsHTTPS() URLValidator
URLSchemeIsHTTPS creates a URLValidator that checks that the request URL's scheme is "https".
func URLUserinfoIs ¶
func URLUserinfoIs(ui string) URLValidator
URLUserinfoIs creates a url validator that checks that the URL's userinfo matches the given userinfo ui.
The user info will be in the form of "username[:password]".
func (URLValidator) ValidateRequest ¶
func (v URLValidator) ValidateRequest(req *http.Request) error