http

Documentation

Index

• Constants
• func DetectContentType(data []byte) string
• func DirList(w http.ResponseWriter, r *http.Request, fsys FileSystem, prefix string, ...) error
• func FileServer(root FileSystem) http.Handler
• func ServeContent(w http.ResponseWriter, req *http.Request, name string, modtime time.Time, ...)
• func ServeFile(w http.ResponseWriter, r *http.Request, name string)
• func TarList(fi fs.FileInfo, u url.URL, uprefix string) string
• type Dir
  • func (d Dir) Open(name string) (File, error)
  • func (d Dir) RenderHeader(w http.ResponseWriter, r *http.Request, name string, f File, ctype string) error
• type File
• type FileSystem
  • func FS(fsys fs.FS) FileSystem
• type Files
• type HeaderRenderer
• type Sizer

Constants

const TooBig = elf.TooBig

Functions

func DetectContentType

func DetectContentType(data []byte) string

DetectContentType implements the algorithm described at https://mimesniff.spec.whatwg.org/ to determine the Content-Type of the given data. It considers at most the first 512 bytes of data. DetectContentType always returns a valid MIME type: if it cannot determine a more specific one, it returns "application/octet-stream".

func DirList

func DirList(w http.ResponseWriter, r *http.Request, fsys FileSystem, prefix string, des []fs.DirEntry, render func() error) error

func FileServer

func FileServer(root FileSystem) http.Handler

FileServer returns a handler that serves HTTP requests with the contents of the file system rooted at root.

As a special case, the returned file server redirects any request ending in "/index.html" to the same path, without the final "index.html".

To use the operating system's file system implementation, use http.Dir:

http.Handle("/", http.FileServer(http.Dir("/tmp")))

To use an fs.FS implementation, use http.FS to convert it:

http.Handle("/", http.FileServer(http.FS(fsys)))

func ServeContent

func ServeContent(w http.ResponseWriter, req *http.Request, name string, modtime time.Time, content io.ReadSeeker, render renderFunc)

ServeContent replies to the request using the content in the provided ReadSeeker. The main benefit of ServeContent over io.Copy is that it handles Range requests properly, sets the MIME type, and handles If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since, and If-Range requests.

If the response's Content-Type header is not set, ServeContent first tries to deduce the type from name's file extension and, if that fails, falls back to reading the first block of the content and passing it to DetectContentType. The name is otherwise unused; in particular it can be empty and is never sent in the response.

If modtime is not the zero time or Unix epoch, ServeContent includes it in a Last-Modified header in the response. If the request includes an If-Modified-Since header, ServeContent uses modtime to decide whether the content needs to be sent at all.

The content's Seek method must work: ServeContent uses a seek to the end of the content to determine its size.

If the caller has set w's ETag header formatted per RFC 7232, section 2.3, ServeContent uses it to handle requests using If-Match, If-None-Match, or If-Range.

Note that *os.File implements the io.ReadSeeker interface.

func ServeFile

func ServeFile(w http.ResponseWriter, r *http.Request, name string)

ServeFile replies to the request with the contents of the named file or directory.

If the provided file or directory name is a relative path, it is interpreted relative to the current directory and may ascend to parent directories. If the provided name is constructed from user input, it should be sanitized before calling ServeFile.

As a precaution, ServeFile will reject requests where r.URL.Path contains a ".." path element; this protects against callers who might unsafely use filepath.Join on r.URL.Path without sanitizing it and then use that filepath.Join result as the name argument.

As another special case, ServeFile redirects any request where r.URL.Path ends in "/index.html" to the same path, without the final "index.html". To avoid such redirects either modify the path or use ServeContent.

Outside of those two special cases, ServeFile does not use r.URL.Path for selecting the file or directory to serve; only the file or directory provided in the name argument is used.

func TarList

func TarList(fi fs.FileInfo, u url.URL, uprefix string) string

Types

type Dir

type Dir string

A Dir implements FileSystem using the native file system restricted to a specific directory tree.

While the FileSystem.Open method takes '/'-separated paths, a Dir's string value is a filename on the native file system, not a URL, so it is separated by filepath.Separator, which isn't necessarily '/'.

Note that Dir could expose sensitive files and directories. Dir will follow symlinks pointing out of the directory tree, which can be especially dangerous if serving from a directory in which users are able to create arbitrary symlinks. Dir will also allow access to files and directories starting with a period, which could expose sensitive directories like .git or sensitive files like .htpasswd. To exclude files with a leading period, remove the files/directories from the server or create a custom FileSystem implementation.

An empty Dir is treated as ".".

func (Dir) Open

func (d Dir) Open(name string) (File, error)

Open implements FileSystem using os.Open, opening files for reading rooted and relative to the directory d.

func (Dir) RenderHeader

func (d Dir) RenderHeader(w http.ResponseWriter, r *http.Request, name string, f File, ctype string) error

RenderHeader is unused.

type File

type File interface {
	io.Closer
	io.Reader
	io.Seeker
	Readdir(count int) ([]fs.FileInfo, error)
	Stat() (fs.FileInfo, error)
}

A File is returned by a FileSystem's Open method and can be served by the FileServer implementation.

The methods should behave the same as those on an *os.File.

type FileSystem

type FileSystem interface {
	Open(name string) (File, error)
	HeaderRenderer
}

A FileSystem implements access to a collection of named files. The elements in a file path are separated by slash ('/', U+002F) characters, regardless of host operating system convention. See the FileServer function to convert a FileSystem to a Handler.

This interface predates the fs.FS interface, which can be used instead: the FS adapter function converts an fs.FS to a FileSystem.

func FS

func FS(fsys fs.FS) FileSystem

FS converts fsys to a FileSystem implementation, for use with FileServer and NewFileTransport. The files provided by fsys must implement io.Seeker.

type Files

type Files interface {
	Files() iter.Seq2[fs.FileInfo, error]
}

type HeaderRenderer

type HeaderRenderer interface {
	RenderHeader(w http.ResponseWriter, r *http.Request, name string, f File, ctype string) error
}

HeaderRenderer renders a header for a FileSystem.

type Sizer

type Sizer interface {
	Size() int64
}