wiretarget

package
v3.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package wiretarget spells the path the router matched the way a request line carries it, for middleware that hands the request on to something that reads request lines: a proxy upstream, a net/http handler.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HasForgedEscape

func HasForgedEscape(target string) bool

HasForgedEscape reports whether target's path holds an escape of an unreserved character (RFC 3986 Section 2.3: a letter, a digit, "-", ".", "_" or "~"). The router decodes every such escape when it normalizes a path, so one still in c.Path() was forged by a stray "%" lining up with the escape after it: "/%%32e" reaches the router as "/%2e". A reader that decodes the path once more then sees a character the router never matched, "%2e%2e" becoming a ".." segment or "%70rivate" becoming "private". Under UnescapePath the routed path is escaped again segment by segment, which never escapes an unreserved character, so nothing is reported there.

func ParsesAsPath

func ParsesAsPath(target string, host []byte) bool

ParsesAsPath reports whether fasthttp reads target as a path when it is set as the request line of a request whose Host header is host. It is false for a target without a leading slash, which a request line reads as an absolute URL or an authority, for one that begins with "//" and holds "://", and for one that begins with "//" on a request without a Host header: fasthttp then reads the target as "[scheme:]//authority/path" and takes the request's host, and a Basic credential, from the authority, over the ones the application set. The router never sees such a target as an authority, and it need not have arrived as one: ".." resolution builds "//u:pw@evil.example/a://b" out of "//u:pw@evil.example/a:/x/..//b", and under UnescapePath a decoded "%3A%2F%2F" spells the "://".

func Routed

func Routed[App any](c Ctx[App]) string

Routed returns the request target to hand on for c: the path the router matched, spelled as a request line has to carry it, then the query.

Under the default configuration c.Path() is nearly that spelling already: escapes of unreserved characters decoded, every other escape kept, dot segments resolved and empty segments kept. What it may still hold raw is written as an escape, the valid spelling of the same name: a stray "%" that begins no escape as "%25", and every byte RFC 3986 does not allow raw in a path, such as a space, "\", "|", "{", "}", '"', "^", "<", ">", a control byte or a byte of UTF-8, as its escape, as fasthttp's normalizing writer did before. Under UnescapePath c.Path() is fully decoded, so it is escaped again segment by segment, and a "/" that came from "%2F" stays the separator the router took it for.

The raw request line is deliberately not the source. fasthttp's own normalization of it decodes "%2F" into a separator, merges "//" and then resolves "..", so "/public/..%2Fadmin" and "//admin" reached a proxy upstream or a net/http handler as "/admin" although no middleware mounted on "/admin" had run for them. The routed path keeps them the distinct names the router matched.

The query is the one the client sent, even after a handler read it through c.Query(): fasthttp would serialize parsed arguments again, "%20" as "+" and ";" as "%3B", and a signed URL would no longer verify. Only when a handler changed the arguments through QueryArgs() are they forwarded as fasthttp serializes them, since that is the change it made.

The target may be the request line itself, a view of it rather than a copy, when that already spells the routed path, so read it before the request line is set to something else.

The target always begins with a slash. A path override that dropped it, a rewrite of "/go/*" to "$1" say, would otherwise hand on "http://u:pw@evil.example/x", which a request line reads as an absolute URL and so as a host and a credential; rooted, it is the path "/http://u:pw@evil.example/x".

func SegmentsAsRouted

func SegmentsAsRouted(target string, allow Allowance) bool

SegmentsAsRouted reports whether a reader that decodes target's path and cleans it still sees the segments the router matched. It is false when the path holds an empty segment, an escaped slash or a forged escape (see HasForgedEscape): net/http's URL.Path reads "%2F" as a separator and a forged "%2e%2e" as "..", and its handlers clean "//" and ".." away, so "/public/..%2Fadmin", "//admin" and "/public/%2e%2e/admin" would be served as "/admin" by a handler no middleware mounted on "/admin" guarded. A proxied upstream that decodes "%2F" or merges "//" before it matches routes reads a target the same way, so the proxy handlers refuse one for which this is false, as the net/http handler adapters do.

It is false as well for a backslash, raw or escaped as "%5C", which WHATWG URL parsers and IIS read as a separator, and for a path parameter, a ";" in any segment. Servlet containers such as Tomcat and Jetty strip the parameters from every segment before they match routes, so "/admin;x/secret" and "/admin;/secret" are "/admin/secret" there, "/;/admin/secret" is "//admin/secret" and so "/admin/secret" once the empty segment is merged, and "/public/..;/admin" is "/admin".

allow lets some of this through. A "." or ".." segment that carries parameters, such as "..;x", is refused whatever it says, behind a raw slash or, with AllowSlashes, behind an escaped one: a reader that strips the parameters resolves it as a dot segment, and none has a use for it as a name. A segment made of parameters alone, such as ";x", is an empty segment once they are stripped, and is refused as one unless AllowSlashes is set too; as the last segment it spells the trailing slash and passes.

func Serve added in v3.7.0

func Serve[App any](c Ctx[App], handler fasthttp.RequestHandler) bool

Serve runs handler, a net/http handler adapted by fasthttpadaptor, on a request line that spells the path the router matched (Routed) rather than the one that arrived, and puts the original back afterwards. The two differ for an escaped or non-canonical request, and net/http reads the raw one its own way: "/public/..%2Fadmin" decodes into a URL.Path that http.FileServer cleans to "/admin", although no middleware mounted on "/admin" has run. A routed path whose segments would not survive that reading, one with an empty segment or an escaped slash, is not handed on, nor is one that a handler passing the request on, such as httputil.ReverseProxy, would hand an upstream that reads it as another path: a backslash, or a segment a servlet container strips to a dot or an empty segment ("..;", "/;x/admin"). A path parameter on a named segment is handed on, since net/http reads it as part of the name. Serve reports false, without running handler, for a routed path it does not hand on.

func SetTarget added in v3.7.0

func SetTarget[App any](c Ctx[App], target string)

SetTarget sets target, the routed request target, as c's request line. A target that is the line as it arrived is left alone, which spares a second parse of it. Otherwise the host fasthttp parsed is kept: a target that is a path makes fasthttp take the host from the Host header again, while an absolute-form request line names its own, which RFC 9112 Section 3.2.2 says the server uses and which c.Hostname() reported. Kept, the adapted handler sees in r.Host the host Fiber saw.

func SurvivesNormalization

func SurvivesNormalization(target string) bool

SurvivesNormalization reports whether fasthttp's path normalization would leave target's path naming what it names. Normalization merges every empty segment, decodes every escape and writes the path again with only some bytes escaped, so "//" and an escape that does not come back (see escapeSurvives) leave a normalizing client as a path the router never matched: "/public/..%2Fadmin" as "/admin" and "/..%3B/" as "/..;/". Any other escape, such as the "%C3%A9" Routed writes for "é", comes out as it went in, up to the case of its hex digits. The client also escapes a raw "!", "'", "(", ")" or "*", which changes the spelling but cannot add a separator.

Types

type Allowance added in v3.7.0

type Allowance uint8

Allowance names what SegmentsAsRouted lets through that it refuses otherwise, for a caller that was told the reader keeps it as sent.

const (
	// AllowSlashes lets an escaped slash and an empty segment through.
	AllowSlashes Allowance = 1 << iota
	// AllowParameters lets a path parameter through on a segment that has a
	// name other than "." and "..".
	AllowParameters
)

type Ctx added in v3.7.0

type Ctx[App any] interface {
	App() App
	OriginalURL() string
	Path(override ...string) string
	Request() *fasthttp.Request
	Response() *fasthttp.Response
	RequestCtx() *fasthttp.RequestCtx
}

Ctx is what this package reads of a fiber.Ctx, App being *fiber.App. Naming either would be an import cycle: package fiber serves net/http handlers here.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL