Browse configures directory browsing.

FileServer implements a handler that serves static files.

The path of the file to serve is constructed by joining the site root and the sanitized request path. Any and all files within the root and links with targets outside the site root may therefore be accessed. For example, with a site root of /www, requests to /foo/bar.txt will serve the file at /www/foo/bar.txt.

The request path is sanitized using the Go standard library's path.Clean() function (https://pkg.go.dev/path#Clean) before being joined to the root. Request paths must be valid and well-formed.

For requests that access directories instead of regular files, Caddy will attempt to serve an index file if present. For example, a request to /dir/ will attempt to serve /dir/index.html if it exists. The index file names to try are configurable. If a requested directory does not have an index file, Caddy writes a 404 response. Alternatively, file browsing can be enabled with the "browse" parameter which shows a list of files when directories are requested if no index file is present. If "browse" is enabled, Caddy may serve a JSON array of the directory listing when the Accept header mentions application/json with the following structure:

[{
	"name": "",
	"size": 0,
	"url": "",
	"mod_time": "",
	"mode": 0,
	"is_dir": false,
	"is_symlink": false
}]

with the url being relative to the request path and mod_time in the RFC 3339 format with sub-second precision. For any other value for the Accept header, the respective browse template is executed with Content-Type: text/html.

By default, this handler will canonicalize URIs so that requests to directories end with a slash, but requests to regular files do not. This is enforced with HTTP redirects automatically and can be disabled. Canonicalization redirects are not issued, however, if a URI rewrite modified the last component of the path (the filename).

This handler sets the Etag and Last-Modified headers for static files. It does not perform MIME sniffing to determine Content-Type based on contents, but does use the extension (if known); see the Go docs for details: https://pkg.go.dev/mime#TypeByExtension

The file server properly handles requests with If-Match, If-Unmodified-Since, If-Modified-Since, If-None-Match, Range, and If-Range headers. It includes the file's modification time in the Last-Modified header of the response.

MatchFile is an HTTP request matcher that can match requests based upon file existence.

Upon matching, three new placeholders will be made available:

• {http.matchers.file.relative} The root-relative path of the file. This is often useful when rewriting requests.
• {http.matchers.file.absolute} The absolute path of the matched file.
• {http.matchers.file.type} Set to "directory" if the matched file is a directory, "file" otherwise.
• {http.matchers.file.remainder} Set to the remainder of the path if the path was split by split_path.

Even though file matching may depend on the OS path separator, the placeholder values always use /.

This type doesn't have documentation.

browseTemplateContext provides the template context for directory listings.

crumb represents part of a breadcrumb menu, pairing a link with the text to display.

fileInfo contains serializable information about a file or directory.

statusOverrideResponseWriter intercepts WriteHeader calls to instead write the HTTP status code we want instead of the one http.ServeContent will use by default (usually 200)

templateContext powers the context used when evaluating the browse template. It combines browse-specific features with the standard templates handler features.

FinalizeUnmarshalCaddyfile finalizes the Caddyfile parsing which requires having an httpcaddyfile.Helper to function, to setup hidden Caddyfiles.

Provision sets up the static files responder.

UnmarshalCaddyfile parses the file_server directive. It enables the static file server and configures it with this syntax:

file_server [<matcher>] [browse] {
    fs            <filesystem>
    root          <path>
    hide          <files...>
    index         <files...>
    browse        [<template_file>]
    precompressed <formats...>
    status        <status>
    disable_canonical_uris
}

The FinalizeUnmarshalCaddyfile method should be called after this to finalize setup of hidden Caddyfiles.

Provision sets up m's defaults.

UnmarshalCaddyfile sets up the matcher from Caddyfile tokens. Syntax:

file <files...> {
    root      <path>
    try_files <files...>
    try_policy first_exist|smallest_size|largest_size|most_recently_modified
}

CaddyModule returns the Caddy module information.

CELLibrary produces options that expose this matcher for use in CEL expression matchers.

Example:

expression file()
expression file({http.request.uri.path}, '/index.php')
expression file({'root': '/srv', 'try_files': [{http.request.uri.path}, '/index.php'], 'try_policy': 'first_exist', 'split_path': ['.php']})

CaddyModule returns the Caddy module information.

Match returns true if r matches m. Returns true if a file was matched. If so, four placeholders will be available:

• http.matchers.file.relative: Path to file relative to site root
• http.matchers.file.absolute: Path to file including site root
• http.matchers.file.type: file or directory
• http.matchers.file.remainder: Portion remaining after splitting file path (if configured)

MatchWithError returns true if r matches m.

Validate ensures m has a valid configuration.

Breadcrumbs returns l.Path where every element maps the link to the text to display.

HumanTotalFileSize returns the total size of all files in the listing as a human-readable string in IEC format (i.e. power of 2 or base 1024).

HumanTotalFileSizeFollowingSymlinks is the same as HumanTotalFileSize except the returned value reflects the size of symlink targets.

HasExt returns true if the filename has any of the given suffixes, case-insensitive.

HumanModTime returns the modified time of the file as a human-readable string given by format.

HumanSize returns the size of the file as a human-readable string in IEC format (i.e. power of 2 or base 1024).

Unwrap returns the underlying ResponseWriter, necessary for http.ResponseController to work correctly.

WriteHeader intercepts calls by the stdlib to WriteHeader to instead write the HTTP status code we want.