|
boost::taar::handler::htdocs — A request handler that serves static files from a document root.
// In header: <boost/taar/handler/htdocs.hpp> class htdocs { public: // types typedef boost::beast::http::request< boost::beast::http::empty_body > request_type; // The request type the handler reads (the body is never needed). typedef boost::beast::http::response< segmented_body > response_type; // The response type of every answer. // public member functions explicit htdocs(htdocs_options); htdocs(std::string = "./", std::string = "index.html"); response_type operator()(request_type const &, boost::taar::matcher::context const &) const; htdocs_options const & options() const noexcept; htdocs_cache_stats cache_stats() const; std::vector< std::string > path_arg_names() const; };
Register it on a GET route, normally with a greedy placeholder; the session answers HEAD through the same route:
session.register_request_handler( method == http::verb::get && target == "/static/{*path}", taar::handler::htdocs {"./public"}); // GET /static/app.css -> ./public/app.css
Resolution and safety. The file is the route's greedy capture (see htdocs_options::path_arg), percent-decoded by Boost.URL; the query never takes part. A path with an encoded /, \ or NUL, or a . or .. segment, is answered 400. The resolved file must stay under the canonical root (symbolic links included) and hidden names are refused; both answer 404 so the tree cannot be probed. A directory without a trailing slash is redirected (301) to the slash form; with the slash, the first existing index file is served, else 404 (no directory listings). Methods other than GET and HEAD answer 405 with Allow: GET, HEAD. Error responses are short fixed text/plain texts that never echo the request.
Validators and conditional requests. Files carry Last-Modified and a strong ETag (size, modification time and content coding). If-Match, If-Unmodified-Since, If-None-Match and If-Modified-Since are evaluated in the order of RFC 9110 13.2.2 (412, 304). Cache-Control comes from htdocs_options::cache_rules.
Ranges and variants. Range requests are answered with 206 (one range, or multipart/byteranges), 416 when unsatisfiable, honouring If-Range. Precompressed siblings (file.br, file.gz) are chosen by Accept-Encoding and announced with Vary: Accept-Encoding; range requests are served from the uncompressed file.
Responses. Every response, errors included, is a typed http::response<segmented_body> (convertible to a message_generator), so the session's response filter and HEAD handling apply. HEAD and 304 never open the file. The handler is cheap to copy; copies share their state and caches and may be used from several threads at once.
Caches. Path resolution, stat results and validators are cached and checked again after htdocs_options::revalidate_after; small files are kept in memory. See the cache fields of htdocs_options.
Blocking I/O. File system calls (stat, open, read) are synchronous and run on the connection's thread; asynchronous file I/O is not used. Serve from local disks, and size the thread pool for the slowest disk.
htdocs public member functionsexplicit htdocs(htdocs_options options);Construct from options.
Throws: |
boost::taar::exception (errc::invalid_argument) if an index file or the fallback document is not a plain relative path, or a precompressed entry is not a content coding token (or is identity). |
htdocs(std::string htdocs_root = "./", std::string default_doc = "index.html");Construct with a document root and one index file (the original interface).
Parameters: |
|
response_type operator()(request_type const & request, boost::taar::matcher::context const & context) const;Serve request; context supplies the route's path arguments.
htdocs_options const & options() const noexcept;The options the handler was built with (normalised).
htdocs_cache_stats cache_stats() const;A snapshot of the cache counters (shared by all copies of this handler).
std::vector< std::string > path_arg_names() const;The configured
htdocs_options::path_arg, for the session's registration-time check against the route template; empty when the default selection is used.