headers

Documentation

Overview

Package headers is all about HTTP header names.

Index

• Constants
• Variables
• func First(hdrs http.Header, k string) (string, []string, bool)
• func IsForbiddenRequestHeaderName(name string) bool
• func IsForbiddenResponseHeaderName(name string) bool
• func IsProhibitedRequestHeaderName(name string) bool
• func IsProhibitedResponseHeaderName(name string) bool
• func IsSafelistedResponseHeaderName(name string) bool
• func IsValid(name string) bool
• func TrimOWS(s string, n int) (trimmed string, ok bool)
• type SortedSet
  • func (set SortedSet) Accepts(values []string) bool
  • func (set *SortedSet) Add(e string)
  • func (set *SortedSet) Fix()
  • func (set SortedSet) Size() int
  • func (set SortedSet) ToSortedSlice() []string

Constants

const (
	// common request headers
	Origin = "Origin"

	// preflight-only request headers
	ACRPN = "Access-Control-Request-Private-Network"
	ACRM  = "Access-Control-Request-Method"
	ACRH  = "Access-Control-Request-Headers"

	// common response headers
	ACAO = "Access-Control-Allow-Origin"
	ACAC = "Access-Control-Allow-Credentials"

	// preflight-only response headers
	ACAPN = "Access-Control-Allow-Private-Network"
	ACAM  = "Access-Control-Allow-Methods"
	ACAH  = "Access-Control-Allow-Headers"
	ACMA  = "Access-Control-Max-Age"

	// actual-only response headers
	ACEH = "Access-Control-Expose-Headers"

	Vary = "Vary"
)

header names in canonical format

const (
	ValueTrue        = "true"
	ValueWildcard    = "*"
	ValueVaryOptions = ACRH + ", " + ACRM + ", " + ACRPN + ", " + Origin
)

const (
	MaxOWSBytes      = 1  // number of leading/trailing OWS bytes tolerated
	MaxEmptyElements = 16 // number of empty list elements tolerated
)

const Authorization = "authorization" // note: byte-lowercase

const ValueSep = ","

Variables

var (
	PreflightVarySgl = []string{ValueVaryOptions}
	TrueSgl          = []string{ValueTrue}
	OriginSgl        = []string{Origin}
	WildcardSgl      = []string{ValueWildcard}
	WildcardAuthSgl  = []string{ValueWildcard + ValueSep + Authorization}
)

Functions

func First

func First(hdrs http.Header, k string) (string, []string, bool)

First, if k is present in hdrs, returns the value associated to k in hdrs, a singleton slice containing that value, and true; otherwise, First returns "", nil, false. Precondition: k is in canonical format (see http.CanonicalHeaderKey).

First is useful because

• contrary to http.Header.Get, it returns a slice that can be reused, which saves a heap allocation in client code;
• it returns the value both as a scalar and as a singleton slice, which saves a bounds check in client code.

func IsForbiddenRequestHeaderName

func IsForbiddenRequestHeaderName(name string) bool

IsForbiddenRequestHeaderName reports whether name is a forbidden request-header name per the Fetch standard.

Precondition: name is a valid and byte-lowercase header name.

func IsForbiddenResponseHeaderName

func IsForbiddenResponseHeaderName(name string) bool

IsForbiddenResponseHeaderName reports whether name is a forbidden response-header name per the Fetch standard.

Precondition: name is a valid and byte-lowercase header name.

func IsProhibitedRequestHeaderName

func IsProhibitedRequestHeaderName(name string) bool

IsProhibitedRequestHeaderName reports whether name is a prohibited request-header name. Attempts to allow such request headers almost always stem from some misunderstanding of CORS.

Precondition: name is a valid and byte-lowercase header name.

func IsProhibitedResponseHeaderName

func IsProhibitedResponseHeaderName(name string) bool

IsProhibitedResponseHeaderName reports whether name is a prohibited response-header name. Attempts to expose such response headers almost always stem from some misunderstanding of CORS.

Precondition: name is a valid and byte-lowercase header name.

func IsSafelistedResponseHeaderName

func IsSafelistedResponseHeaderName(name string) bool

IsSafelistedResponseHeaderName reports whether name is a safelisted response-header name per the Fetch standard.

Precondition: name is a valid and byte-lowercase header name.

func IsValid

func IsValid(name string) bool

IsValid reports whether name is a valid header name, per the Fetch standard.

func TrimOWS

func TrimOWS(s string, n int) (trimmed string, ok bool)

TrimOWS trims up to n bytes of optional whitespace (OWS) from the start of and/or the end of s. If no more than n bytes of OWS are found at the start of s and no more than n bytes of OWS are found at the end of s, it returns the trimmed result and true. Otherwise, it returns the original string and false.

Types

type SortedSet

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

A SortedSet represents a mathematical set of strings sorted in lexicographical order. Each element has a unique position ranging from 0 (inclusive) to the set's cardinality (exclusive). The zero value represents an empty set.

func (SortedSet) Accepts

func (set SortedSet) Accepts(values []string) bool

Accepts reports whether values is a sequence of list-based field values whose elements are

• all members of set,
• sorted in lexicographical order,
• unique.

Accepts requires a preliminary call to method SortedSet.Fix.

This methods's parameter is a slice of strings rather than just a string because, although the Fetch standard requires browsers to include at most one ACRH field line in CORS-preflight requests, some intermediaries may well (and some reportedly do) split it into multiple ACRH field lines. Note that, because RFC 9110 (section 5.3) forbids intermediaries from changing the order of field lines of the same name, we can expect the overall sequence of elements to still be sorted in lexicographical order.

Although the Fetch standard requires browsers to omit any whitespace in the value of the ACRH field, some intermediaries may well alter this list-based field's value by sprinkling optional whitespace (OWS) around the value's elements. RFC 9110 (section 5.6.1.2) requires recipients to tolerate arbitrary long OWS around elements of a list-based field value, but adherence to this requirement leads to non-negligible performance degradation in CORS middleware in the face of adversarial (spoofed) CORS-preflight requests. Therefore, this method only tolerates a small number (1) of OWS bytes before and/or after each element. This divergence from RFC 9110 is expected to strike a good balance between interoperability and performance.

Moreover, this method tolerates a small number (16) of empty list elements, in accordance with RFC 9110's recommendation (section 5.6.1.2).

func (*SortedSet) Add

func (set *SortedSet) Add(e string)

Add adds e to set without enforcing set's invariants; see method SortedSet.Fix.

func (*SortedSet) Fix

func (set *SortedSet) Fix()

Fix restores set's invariants.

func (SortedSet) Size

func (set SortedSet) Size() int

Size returns the cardinality of set.

func (SortedSet) ToSortedSlice

func (set SortedSet) ToSortedSlice() []string

ToSortedSlice returns a slice containing set's elements sorted in lexicographical order.

ToSortedSlice requires a preliminary call to method SortedSet.Fix.