Documentation
¶
Overview ¶
Package header provides a collection of utility functions for parsing, interpreting, and manipulating HTTP headers.
The package includes helpers for common header-related tasks, such as:
- Parsing comma-separated directives (e.g., "max-age=3600").
- Parsing and sorting content negotiation headers with q-factors.
- Extracting credentials from an Authorization header.
- Calculating cache lifetime from Cache-Control and Expires headers.
- Determining throttle delays from Retry-After and X-Ratelimit-* headers.
It also provides a convenient http.RoundTripper implementation for automatically attaching a static set of headers to all outgoing requests.
Index ¶
- func Accepts(s, key string) bool
- func Credentials(h http.Header, scheme string) string
- func Directives(s string) iter.Seq2[string, string]
- func Lifetime(h http.Header, now func() time.Time) time.Duration
- func MediaType(h http.Header) string
- func NewTransport(t http.RoundTripper, headers ...Header) http.RoundTripper
- func Preferences(s string) iter.Seq2[string, float64]
- func Throttle(h http.Header, now func() time.Time) time.Duration
- type Header
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Accepts ¶
Accepts checks if the given key is present in a header value with quality factors, such as Accept, Accept-Encoding, or Accept-Language, and that its q-value is greater than zero. It returns true if the key (media range) is accepted, else false.
func Credentials ¶
Credentials extracts the credentials from the Authorization header of an HTTP request for a specific authentication scheme (e.g., "Basic", "Bearer").
It returns the raw credentials as-is, or an empty string if the header is not present, not well-formed, or does not match the specified scheme. The scheme comparison is case-insensitive.
func Directives ¶
Directives parses a comma-separated header value into an iterator of key-value pairs.
For example, parsing "no-cache, max-age=3600" would yield twice: first "no-cache", "" and then "max-age", "3600".
func Lifetime ¶
Lifetime determines the cache lifetime of a response based on caching headers. It accepts a clock function to calculate relative times. It returns a duration of 0 if the response is not cacheable or does not carry any caching information.
func MediaType ¶
MediaType extracts and returns the media type from a Content-Type header. It returns the media type in lowercase, trimmed of whitespace. If the header is empty or malformed, it returns an empty string.
This function is similar to mime.ParseMediaType but does not return any parameters and ignores parsing errors.
func NewTransport ¶
func NewTransport( t http.RoundTripper, headers ...Header, ) http.RoundTripper
NewTransport wraps a base transport and adds a static set of headers on each outgoing request. If the provided headers map is empty, the base transport is returned unmodified. The function creates a defensive copy of the provided map. The resulting transport clones the request before delegating to the base transport, so the original request is not changed.
func Preferences ¶
Preferences parses a header value with quality factors (e.g., Accept, Accept-Encoding, Accept-Language) into an iterator quality factors (q-value) by name (media range). The values are yielded in the order they appear in the header, not sorted by quality. Values without an explicit q-factor are assigned a default quality of 1.0. Malformed q-factors are also treated as 1.0, while out-of-range values are clamped into the [0.0, 1.0] interval.
Types ¶
type Header ¶
type Header struct {
Key string // Key is the canonicalized header name.
Value string // Value is the raw value of the header.
}
Header represents a single HTTP header key-value pair.
func New ¶
New creates a new Header with the given key and value. The key is automatically canonicalized to the standard HTTP header format.
func UserAgent ¶
UserAgent constructs a User-Agent header with the specified name, version, and an optional comment. The resulting value follows the format "name/version (comment)". The first part is the product token, while the parenthesized section provides supplementary information about the client. For external calls, it is best practice to include maintainer contact details in the comment (such as an URL or email address).
Source Files