fspath

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: 7 Imported by: 0

Documentation

Overview

Package fspath holds the checks that stand between a request and the fasthttp file handler, for the static middleware and SendFile.

Each check exists because of something fasthttp does, or leaves to us:

check                        static    SendFile  why
control byte                 404       404       (1)
backslash, raw or "%5C"      404       -         (2)
escape the router kept       opened    -         (3)
stray "%", forged escape     404       literal   (4)
".", ".." or empty segment   404       cleaned   (5)
segment ending "." or " "    404       -         (6) Windows only
drive letter or volume       404       -         (7) OS root only
fs.ValidPath                 404       -         (8) fs.FS root only

The reasons, by number:

  1. The file handler refuses only NUL, and with a 400; other C0 bytes and DEL reach the OS. None of them is part of a name a client can ask for.
  2. fasthttp treats "\" as a separator only on Windows, so on Unix "..\" passes its ".." check and the same path names different files per OS.
  3. A PathRewrite path is opened as is, still encoded, so the file opened is the one the router and path-scoped middleware matched.
  4. See the stray "%" policy below.
  5. A PathRewrite path skips Path() normalization, and the handler's own ".." check answers 500 and lets "." and "//" through. SendFile hands fasthttp a request URI instead, whose Path() resolves dot segments and merges "//"; FSName and OSName give the name that comes out.
  6. Windows strips a trailing dot or space from a path component when it opens a file, so "private./x" would open "private/x".
  7. fasthttp refuses ":" only on Windows and only for its OS file system, with a 403; the check here runs on every OS.
  8. An fs.FS name must also be valid UTF-8.

Stray "%" policy: a "%" is a name byte wherever nothing decodes the name after it, that is under UnescapePath, where the router already decoded every escape, and in SendFile, which escapes the name so fasthttp's one decode gives it back. In the static middleware's default mode the routed path is still a percent-encoded spelling, and a "%" there must begin an escape the router kept. One that begins none, or an escape of an unreserved character the router would have decoded, is no spelling the router produced, so the name is refused rather than guessed. The router itself keeps a stray "%" (as "%25" where it would forge an escape), the extractors' url.PathUnescape rejects it and the client's cookie jar encodes every "%"; refusing is the strictest of those readings.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FSName

func FSName(name string) string

FSName returns the name the fasthttp file handler opens in an fs.FS for the slash-separated name SendFile hands it: rooted and cleaned as Path() normalization cleans a request path, then without the leading slash.

func OSName

func OSName(name string) string

OSName is FSName for the OS file system, where the name keeps its root and takes the OS separator.

func Valid

func Valid(p []byte, fsys fs.FS, escaped bool) bool

Valid reports whether the routed path p, with the route's prefix stripped, can name a file inside the root, which is fsys when set and the OS file system otherwise. The file server then opens p unchanged. It is false when p holds an escape of a slash ("private%2Fsecret.txt" never reaches the "private/secret.txt" the router did not match), an escape of an unreserved character (a stray '%' the router kept that would otherwise double-decode past the route and middleware), a malformed escape, a backslash, a control character, a ".", ".." or empty segment, a drive letter and, on Windows, a segment ending in a dot or a space that the OS would strip. escaped is off under UnescapePath, which already decoded everything.

Types

This section is empty.

Jump to

Keyboard shortcuts

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