Documentation
¶
Overview ¶
Package fieldname reads and removes HTTP header fields by name case-insensitively (RFC 9110 §5.1).
fasthttp's Peek, PeekAll and Del are byte-exact, which finds every line only while it canonicalizes the key; under DisableHeaderNormalizing the store keeps the spelling the peer sent, which for HTTP/2 and 3 is lower case.
canonical says whether the caller knows the keys to be canonical — fasthttp keeps that private, so it is passed in; see headerlookup.Canonical.
Index ¶
- Constants
- func Canonical(h *fasthttp.ResponseHeader) bool
- func ClearTrailers(req *fasthttp.Request) bool
- func ContainsFold(haystack []string, needle string) bool
- func Del(h Deleter, name string, canonical bool)
- func DelOthers(h Deleter, name string)
- func DelSet(h Deleter, names []string)
- func DelSetWithin(h Deleter, names []string, spare int) bool
- func DelWithin(h Deleter, name string, canonical bool, budget int) int
- func DropResponseTrailers(h *fasthttp.ResponseHeader) bool
- func DropTrailers(h *fasthttp.RequestHeader) bool
- func First(h Peeker, name string, canonical bool) []byte
- func HasTrailers(h Peeker) bool
- func InTrailer(h *fasthttp.RequestHeader, name string) bool
- func IsCanonical(name string) bool
- func JoinedInReceivedOrder(raw []byte, name string, combined []byte) bool
- func KeepReceivedOrder(h *fasthttp.RequestHeader, raw []byte, match func(name []byte) bool) bool
- func Lines(h Peeker, name string, canonical bool) [][]byte
- func Peek(h Peeker, name string) []byte
- func Received(req *fasthttp.Request) []byte
- func ReceivedOrder(h *fasthttp.RequestHeader, raw []byte, name string, f func(value []byte))
- func SetReceived(req *fasthttp.Request, block *[]byte)
- type Deleter
- type Peeker
Constants ¶
const MaxOrderedLines = 64
MaxOrderedLines is the most lines KeepReceivedOrder and ReceivedOrder rank, since they match each received line against them.
const MaxTrailers = 16
MaxTrailers is the most trailer names DropTrailers takes on, since it walks the whole header for each.
Variables ¶
This section is empty.
Functions ¶
func Canonical ¶
func Canonical(h *fasthttp.ResponseHeader) bool
Canonical reports whether every field name in h is spelled the way fasthttp normalizes it, so the byte-exact Peek and Del find them all.
Ask this of a response rather than reading the app config: a proxied response is parsed by an outbound fasthttp.Client carrying its own normalizing setting, so a default-normalizing app can hold a response of lower-case names. It is one walk, against one per field for the case-insensitive reads it saves.
func ClearTrailers ¶ added in v3.7.0
ClearTrailers is DropTrailers in one pass for any number of names, putting each line back in the buffer a value read earlier aliases. It reports false, having dropped the section all the same, for more than MaxTrailers names.
func ContainsFold ¶
ContainsFold reports whether needle equals any of haystack, case-insensitively.
func DelOthers ¶
DelOthers removes every stored spelling of name except name itself, which the caller is about to write or delete under that key. Every other one, not just the first: stopping early leaves the rest beside the value the caller writes.
func DelSet ¶
DelSet removes every field line matching any of names in a single pass, which beats Del's per-name scan when the whole set is known up front.
func DelSetWithin ¶ added in v3.7.0
DelSetWithin is DelSet for a caller bounding the work: each distinct spelling found costs a scan of every line, so it deletes none and reports false when there are more than one per name plus spare.
func DelWithin ¶ added in v3.7.0
DelWithin is Del for a caller bounding the work across several names: each spelling stored besides name costs another scan of every line and one unit of budget. It returns the budget left, or -1, none of them deleted, when they cost more.
func DropResponseTrailers ¶ added in v3.7.0
func DropResponseTrailers(h *fasthttp.ResponseHeader) bool
DropResponseTrailers is DropTrailers for a response: an upstream's trailer section, announced names and received fields alike, is discarded rather than merged into the header section (RFC 9110 §6.5.1), which is where fasthttp returns it when Trailer alone is deleted. It reports false, leaving h as it is, for more than MaxTrailers names.
func DropTrailers ¶ added in v3.7.0
func DropTrailers(h *fasthttp.RequestHeader) bool
DropTrailers discards a request's trailer section and the names announced for it (RFC 9112 §7.1.2): fasthttp files a later Set or Add under such a name with that section, out of the header readers' reach. It reports false, leaving h as it is, for more than MaxTrailers names.
func First ¶
First returns the first field line stored under name that holds anything, or nil if there is none. The names fasthttp keeps in a slot of their own are unaffected either way: every spelling is routed into the slot on the way in.
Empty lines are stepped over rather than answered with, because a message can carry the name more than once and Peek reports the first line whether or not it holds a value: an empty "Cache-Control:" ahead of "Cache-Control: private" read as a response saying nothing about caching. A field line that is present and empty says nothing a caller can act on, so nothing is lost by looking past it for one that does.
Repetition itself is left to the caller to judge, because what it means depends on the field: a response may carry Cache-Control twice and mean the list, while a second Origin or Authorization line is malformed and cannot be resolved by picking one. headerlookup.Value refuses that case for the request fields where it arises.
A name a request holds in its trailer section reads as absent (see InTrailer); a response's header line is read.
func HasTrailers ¶ added in v3.7.0
HasTrailers reports whether h holds a trailer section, received or announced. Peek and PeekAll fall through to it, so the keyed reads are taken only without one.
func InTrailer ¶ added in v3.7.0
func InTrailer(h *fasthttp.RequestHeader, name string) bool
InTrailer reports whether name is a field of a request's trailer section. A header line under such a name is not read: it may be the client's, with the Set meant to replace it filed with the section. A response's line still is.
func IsCanonical ¶ added in v3.6.0
IsCanonical reports whether name is already in fasthttp's canonical form: a token with an upper-case letter first and after each '-' and lower case elsewhere. fasthttp derives that form again on every keyed call, three passes and a copy, only to arrive at the same bytes; a name that already has it can take the *Canonical methods instead, which store and find exactly what the normalizing ones would whether or not the store normalizes. Test_IsCanonical_MatchesFasthttp keeps the form in step.
func JoinedInReceivedOrder ¶ added in v3.7.0
JoinedInReceivedOrder reports whether combined joins name's lines in the received header block raw, in order. raw is read in place, so a folded line reports false.
func KeepReceivedOrder ¶ added in v3.7.0
KeepReceivedOrder puts the lines of each name match accepts that is stored on several lines back in the order they were received, which the store loses whenever fasthttp moves its last line into a removed one's slot, as it does for Transfer-Encoding after an empty chunked body. A line added or changed in code follows them. It reports false, leaving h as it is, for more than MaxOrderedLines such lines. raw is the block from Received.
func Lines ¶
Lines returns every field line stored under name. The walk replaces the byte-exact lookup rather than backing it up: a message can carry both spellings, and an empty canonical line would hide the value beside it. A name a request holds in its trailer section has no lines (see InTrailer); a response's header lines are read.
func Peek ¶ added in v3.6.0
Peek is fasthttp's byte-exact Peek, minus the key normalization when name is already canonical; Test_Peek_MatchesFasthttp keeps the two answering alike in both store modes.
func Received ¶ added in v3.7.0
Received returns the field lines req was received with: those fasthttp read off the wire, or SetReceived's.
func ReceivedOrder ¶ added in v3.7.0
func ReceivedOrder(h *fasthttp.RequestHeader, raw []byte, name string, f func(value []byte))
ReceivedOrder calls f with name's lines in the order raw received them, which a Del can lose in the store; a line raw lacks, such as one added in code, follows in stored order. Above MaxOrderedLines lines f gets raw's alone.
func SetReceived ¶ added in v3.7.0
SetReceived records block, field lines in the order they were received, for a request built in code from one received elsewhere, such as the net/http adaptor's: fasthttp keeps no received block for it.
Types ¶
type Deleter ¶
type Deleter interface {
Del(key string)
PeekAll(key string) [][]byte
All() iter.Seq2[[]byte, []byte]
}
Deleter is the part of fasthttp's headers needed to remove a field by name.
type Peeker ¶
type Peeker interface {
Peek(key string) []byte
PeekAll(key string) [][]byte
PeekTrailerKeys() [][]byte
All() iter.Seq2[[]byte, []byte]
// VisitAll is deprecated in fasthttp in favor of All, but All builds an
// iterator per call while this walks the store directly. Kept for the reads
// that run per request and do not need to stop early.
VisitAll(f func(key, value []byte))
}
Peeker is the part of fasthttp's headers needed to read field lines by name.