header

Documentation

Overview

Package header provides parsing rules for content negotiation & conditional requires headers according to RFC-7231 & RFC-7232.

For "Accept-Language", "Accept-Encoding" or "Accept-Charset" use the ParsePrecedenceValues function.

For "Accept" use the ParseMediaRanges function. This has more complex attributes and rules.

For "If-None-Match" use the ETagsOf function (also useful for "If-Match").

Accept

The Accept header is parsed using ParseMediaRanges(hdr), which returns the slice of media ranges, e.g.

// handle Accept-Language
mediaRanges := header.ParseMediaRanges("application/json;q=0.8, application/xml, application/*;q=0.1")

The resulting slice is ready-sorted according to precedence and quality rules, so in this example the order is {"application/xml", "application/json", "application/*"} because the middle item has an implied quality of 1, whereas the first item has a lower quality.

from https://tools.ietf.org/html/rfc7231#section-5.3.2:

The "Accept" header field can be used by user agents to specify response media types that are acceptable. Accept header fields can be used to indicate that the request is specifically limited to a small set of desired types, as in the case of a request for an in-line image.

A request without any Accept header field implies that the user agent will accept any media type in response.

If the header field is present in a request and none of the available representations for the response have a media type that is listed as acceptable, the origin server can either honor the header field by sending a 406 (Not Acceptable) response, or disregard the header field by treating the response as if it is not subject to content negotiation.

Example header

Accept: audio/*; q=0.2, audio/basic

Accept-Language

The other important content-negotiation headers, Accept-Language and Accept-Charset, are handled by the header.Parse method, e.g.

// handle Accept-Language
acceptLanguages := header.ParsePrecedenceValues("en-GB,fr;q=0.5,en;q=0.8")

This will contain {"en-GB", "en", "fr"} in a header.PrecedenceValues slice, sorted according to precedence rules with the most preferred first.

The acceptable.Parse function can be used for Accept-Encoding as well as Accept-Language and Accept-Charset. However, the Go standard library deals with Accept-Encoding, so you won't need to.

from https://tools.ietf.org/html/rfc7231#section-5.3.5:

The "Accept-Language" header field can be used by user agents to indicate the set of natural languages that are preferred in the response.

A request without any Accept-Language header field implies that the user agent will accept any language in response.

If the header field is present in a request and none of the available representations for the response have a matching language tag, the origin server can either disregard the header field by treating the response as if it is not subject to content negotiation or honor the header field by sending a 406 (Not Acceptable) response. However, the latter is not encouraged, as doing so can prevent users from accessing content that they might be able to use (with translation software, for example).

Example header

Accept-Language: da, en-gb;q=0.8, en;q=0.7

If-None-Match

This header is used for conditional requests where large responses can be avoided when they are already present in caches. Its use is closely related to that of If-Modified-Since, which uses a timestamp (in RFC1123 format), whilst If-None-Match uses entity tags.

from https://tools.ietf.org/html/rfc7232#section-3.2

The "If-None-Match" header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field-value is "*", or having a selected representation with an entity-tag that does not match any of those listed in the field-value.

Example header

If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"

Index

• Constants
• Variables
• func FormatHTTPDateTime(t time.Time) string
• func ParseHTTPDateTime(dateString string) (time.Time, error)
• type ContentType
  • func ParseContentType(ct string) ContentType
  • func ParseContentTypeFromHeaders(hdrs http.Header) ContentType
  • func (ct ContentType) AsMediaRange(quality float64) MediaRange
  • func (ct ContentType) IsTextual() bool
  • func (ct ContentType) String() string
• type ETag
  • func (etag ETag) String() string
• type ETags
  • func ETagsOf(s string) ETags
  • func (etags ETags) String() string
  • func (es ETags) StronglyMatches(strongHash string) bool
  • func (es ETags) WeaklyMatches(strongHash string) bool
• type KV
• type MediaRange
  • func (mr MediaRange) String() string
  • func (mr MediaRange) StrongerThan(other MediaRange) bool
  • func (mr MediaRange) Value() string
• type MediaRanges
  • func ParseMediaRanges(acceptHeader string) MediaRanges
  • func (mrs MediaRanges) String() string
  • func (mrs MediaRanges) WithDefault() MediaRanges
• type PrecedenceValue
  • func (pv PrecedenceValue) String() string
• type PrecedenceValues
  • func ParsePrecedenceValues(acceptXyzHeader string) PrecedenceValues
  • func (pvs PrecedenceValues) Contains(value string) bool
  • func (pvs PrecedenceValues) String() string
  • func (pvs PrecedenceValues) WithDefault() PrecedenceValues
• type Strings
  • func Split(value, cut string) Strings
  • func (ss Strings) Contains(v string) bool
  • func (ss Strings) RemoveQuotes() Strings
  • func (ss Strings) TrimSpace() Strings

Examples

• ParseMediaRanges
• ParsePrecedenceValues

Constants

const (
	// XMLHttpRequest is the value used always with XRequestedWith for XHR.
	XMLHttpRequest = "xmlhttprequest"

	// RFC1123 is similar to the textual time format required by HTTP.
	// Use DateTimeFormat instead. It is used for parsing because it allows any
	// three-letter timezone.
	RFC1123 = time.RFC1123

	// DateTimeFormat is the canonical textual time format required by HTTP (see
	// RFC-9110 5.6.7). The timezone is always GMT.
	DateTimeFormat = "Mon, 02 Jan 2006 15:04:05 GMT"
)

const (
	// DefaultQuality is the default quality of a media range without explicit "q"
	// https://tools.ietf.org/html/rfc7231#section-5.3.1
	DefaultQuality float64 = 1.0 //e.g text/html;q=1

	// NotAcceptable is the value indicating that its item is not acceptable
	// https://tools.ietf.org/html/rfc7231#section-5.3.1
	NotAcceptable float64 = 0.0 //e.g text/foo;q=0
)

Variables

var WildcardPrecedenceValue = []PrecedenceValue{{Value: "*", Quality: DefaultQuality}}

Functions

func FormatHTTPDateTime

func FormatHTTPDateTime(t time.Time) string

FormatHTTPDateTime formats the canonical representation of the date-time (see RFC-9110 section 5.6.7). The timezone GMT is always used.

func ParseHTTPDateTime

func ParseHTTPDateTime(dateString string) (time.Time, error)

ParseHTTPDateTime can be used for headers including Date, Expires, Last-Modified, If-Modified-Since, If-Unmodified-Since etc. Also, some headers such as If-Range and Retry-After may optionally contain a date.

This first tries the preferred RFC-9110 format, although it allows UTC as well as GMT (i.e. as per RFC-1123), before also trying the two obsolete but still supported formats RFC-850 and ANSI-C.

An error is returned if the input is blank or could not be parsed as an HTTP-Date (see RFC-9110 sec 5.6.7).

Types

type ContentType

type ContentType struct {
	// Type and Subtype carry the media type, e.g. "text" and "html"
	Type, Subtype string
	// Params and Extensions hold optional parameter information
	Params []KV
}

ContentType is a media type as defined in RFC-2045, RFC-2046, RFC-2231 (https://tools.ietf.org/html/rfc2045, https://tools.ietf.org/html/rfc2046, https://tools.ietf.org/html/rfc2231) There may also be parameters (e.g. "charset=utf-8") and extension values.

func ParseContentType

func ParseContentType(ct string) ContentType

ParseContentType parses a content type value.

func ParseContentTypeFromHeaders

func ParseContentTypeFromHeaders(hdrs http.Header) ContentType

ParseContentTypeFromHeaders gets the "Content-Type" header and returns its parsed value.

func (ContentType) AsMediaRange

func (ct ContentType) AsMediaRange(quality float64) MediaRange

AsMediaRange converts this ContentType to a MediaRange. The default quality should be 1.

func (ContentType) IsTextual

func (ct ContentType) IsTextual() bool

IsTextual returns true if the content represents a textual entity; false otherwise.

func (ContentType) String

func (ct ContentType) String() string

type ETag

type ETag struct {
	Hash string
	Weak bool
}

ETag is an entity tag used for content matching comparisons. See https://tools.ietf.org/html/rfc7232

func (ETag) String

func (etag ETag) String() string

type ETags

type ETags []ETag

ETag is a slice of ETag.

func ETagsOf

func ETagsOf(s string) ETags

ETagsOf splits an etag header string and parses each part. This can be used with If-Match, If-None-Match etc.

func (ETags) String

func (etags ETags) String() string

func (ETags) StronglyMatches

func (es ETags) StronglyMatches(strongHash string) bool

StronglyMatches finds whether the tags match strongly. This ignores all weak etags in es.

func (ETags) WeaklyMatches

func (es ETags) WeaklyMatches(strongHash string) bool

WeaklyMatches finds whether the tags match weakly. See https://tools.ietf.org/html/rfc7232#section-2.3.2

type KV

type KV struct {
	Key, Value string
}

KV holds a parameter with a key and optional value.

type MediaRange

type MediaRange struct {
	ContentType
	Quality float64
}

MediaRange is a content type and associated quality between 0.0 and 1.0.

func (MediaRange) String

func (mr MediaRange) String() string

func (MediaRange) StrongerThan

func (mr MediaRange) StrongerThan(other MediaRange) bool

StrongerThan compares a media range with another value using the precedence rules.

func (MediaRange) Value

func (mr MediaRange) Value() string

Value gets the conjoined type and subtype string, plus any parameters. It does not include the quality value nor any of the extensions.

type MediaRanges

type MediaRanges []MediaRange

MediaRanges holds a slice of media ranges.

func ParseMediaRanges

func ParseMediaRanges(acceptHeader string) MediaRanges

ParseMediaRanges splits a prioritised "Accept" header value and sorts the parts based on quality values and precedence rules. These are returned in order with the most preferred first.

A request without any Accept header field implies that the user agent will accept any media type in response. If the header field is present in a request and none of the available representations for the response have a media type that is listed as acceptable, the origin server can either honor the header field by sending a 406 (Not Acceptable) response or disregard the header field by treating the response as if it is not subject to content negotiation.

Example

mrs := header.ParseMediaRanges("text/* ; q=0.3, TEXT/html ; Q=0.7, text/html;level=2; q=0.4, */*; q=0.5")

for i, mr := range mrs {
	fmt.Printf("mr%d = %s\n", i, mr)
}

Output:

mr0 = text/html;q=0.7
mr1 = */*;q=0.5
mr2 = text/html;level=2;q=0.4
mr3 = text/*;q=0.3

func (MediaRanges) String

func (mrs MediaRanges) String() string

func (MediaRanges) WithDefault

func (mrs MediaRanges) WithDefault() MediaRanges

WithDefault returns a list of media ranges that is always non-empty. If the input list is empty, the result holds a wildcard entry ("*/*").

type PrecedenceValue

type PrecedenceValue struct {
	Value   string
	Quality float64
}

PrecedenceValue is a value and associate quality between 0.0 and 1.0

func (PrecedenceValue) String

func (pv PrecedenceValue) String() string

type PrecedenceValues

type PrecedenceValues []PrecedenceValue

PrecedenceValues holds a slice of precedence values.

func ParsePrecedenceValues

func ParsePrecedenceValues(acceptXyzHeader string) PrecedenceValues

ParsePrecedenceValues splits a prioritised "Accept-Language", "Accept-Encoding" or "Accept-Charset" header value and sorts the parts. These are returned in order with the most preferred first.

Example

pvs := ParsePrecedenceValues("da, en-gb;q=0.8, en;q=0.7")

for i, pv := range pvs {
	fmt.Printf("pv%d = %s\n", i, pv)
}

Output:

pv0 = da
pv1 = en-gb;q=0.8
pv2 = en;q=0.7

func (PrecedenceValues) Contains

func (pvs PrecedenceValues) Contains(value string) bool

func (PrecedenceValues) String

func (pvs PrecedenceValues) String() string

func (PrecedenceValues) WithDefault

func (pvs PrecedenceValues) WithDefault() PrecedenceValues

type Strings

type Strings []string

Strings is simply a slice of strings.

func Split

func Split(value, cut string) Strings

Split is a convenience wrapper for strings.Split.

func (Strings) Contains

func (ss Strings) Contains(v string) bool

Contains looks for a string in the slice.

func (Strings) RemoveQuotes

func (ss Strings) RemoveQuotes() Strings

RemoveQuotes removes quotes from all the strings in the slice.

func (Strings) TrimSpace

func (ss Strings) TrimSpace() Strings

TrimSpace trims all the strings in the slice.