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 wildcard-aware content negotiation headers with q-factors.
- Parsing RFC 5988 Link headers to extract relations for API pagination.
- 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 Filename(h http.Header) string
- func Lifetime(h http.Header, now func() time.Time) time.Duration
- func Link(s, rel string) string
- func Links(s string) iter.Seq2[string, string]
- 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 accepted based on a header value with quality factors (e.g., Accept, Accept-Encoding, or Accept-Language). It properly weights exact matches over partial wildcards (e.g., "text/*") and global wildcards ("*/*" or "*"), returning true if the best match has a q-value greater than zero.
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 Filename ¶ added in v1.1.16
Filename extracts the intended filename from a Content-Disposition header.
It automatically handles both the standard "filename" parameter and the RFC 6266 "filename*" parameter, which is used for non-ASCII (UTF-8) names. It returns an empty string if the header is missing, malformed, or does not contain a filename.
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 Link ¶ added in v1.1.16
Link extracts the URL for a specific relation (e.g., "next" or "last") from a Link header. It returns an empty string if the relation is not found.
func Links ¶ added in v1.1.16
Links parses an RFC 5988 Link header into an iterator of relation types (rel) and their corresponding URLs.
If a link has multiple space-separated relations (e.g., rel="next archive"), it yields the URL for each relation separately.
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 sets 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