Struct htdocs

Struct htdocs_options

boost::taar::handler::htdocs_options — Configuration of an htdocs handler.

Synopsis

// In header: <boost/taar/handler/htdocs.hpp>


struct htdocs_options {

  // public data members
  std::filesystem::path root;  // The document root. Requests never resolve outside it. 
  std::vector< std::string > index_files;  // Files tried in order for a directory request ending in /. 
  std::string path_arg;  // The path_args entry naming the file, relative to root. 
  bool serve_hidden;  // Serve files and directories whose name starts with . (.well-known is always served). 
  bool follow_symlinks_outside_root;  // Serve symbolic links that resolve outside root (refused with 404 by default). 
  std::optional< std::string > fallback_document;  // A document, relative to root, served for requests that match no file: the single-page application fallback. 
  std::function< bool(std::string_view)> fallback_when;  // Decides, from the decoded relative path, whether a missing file falls back; empty: no extension in the last segment. 
  std::unordered_map< std::string, std::string > mime_types;  // Extra or overriding media types: extension (with or without the leading dot, case-insensitive) to type. 
  std::string default_mime_type;  // Media type for extensions neither mime_types nor the built-in table know. 
  bool nosniff;  // Send X-Content-Type-Options: nosniff with every served file. 
  std::vector< cache_rule > cache_rules;  // Cache-Control rules, first match wins (see cache_rule and cache_rules::immutable_hashed). 
  std::string default_cache_control;  // Cache-Control for files no rule matches; empty (the default) sends none. 
  std::size_t max_ranges;  // Most ranges honoured in one Range header; more make the request a plain 200. 
  std::vector< std::string > precompressed;  // Precompressed siblings to look for, in order of preference, as content codings: br is file.br, gzip is file.gz, zstd is file.zst, and any other coding xyz is file.xyz. 
  std::size_t metadata_cache_entries;  // Capacity of the metadata cache (path resolution, stat results, variants, validators, media type), keyed by the decoded relative path; least recently used entries are dropped. 
  std::chrono::milliseconds revalidate_after;  // Age after which a cached entry is checked against the file system again on its next use. 
  std::size_t memory_cache_max_file_size;  // Files up to this size are kept in memory once read; 0 disables the content cache. 
  std::size_t memory_cache_max_total;  // Total bytes the content cache may hold (least recently used files are dropped first). 
  std::function< void(std::string_view, boost::beast::http::response_header<> &)> on_response;  // Called for every served file (200, 206, 304) with the file's relative path and the response header, just before the response is returned: add Content-Disposition, security headers, and so on. 
};

Description

Every field has a production-ready default; set only what differs.

taar::handler::htdocs_options options;
options.root = "./public";
options.fallback_document = "index.html";          // single-page application
session.register_request_handler(
    method == http::verb::get && target == "/{*path}",
    taar::handler::htdocs {std::move(options)});

`htdocs_options` public public data members

```
std::string path_arg;
```
Empty (the default) selects the route's greedy capture: the {*} entry, or the only path argument when there is exactly one; with no path argument the whole request path (without the query) is used. Set it when the route has several placeholders.
```
std::optional< std::string > fallback_document;
```
It answers a GET or HEAD whose path does not exist when fallback_when says so (by default: the last path segment has no extension, so /app/settings falls back but /app/logo.png stays 404). The fallback is sent with Cache-Control: no-cache.
```
std::unordered_map< std::string, std::string > mime_types;
```
; charset=utf-8 is appended to text types unless the value already has a parameter.
```
std::vector< cache_rule > cache_rules;
```
Empty by default.
```
std::size_t max_ranges;
```
Overlapping and adjacent ranges are merged. 0 disables range requests (no Accept-Ranges).
```
std::vector< std::string > precompressed;
```
A sibling is served with Content-Encoding and the original's media type when the request's Accept-Encoding accepts the coding (q-values honoured) and it is not older than the original. Files with a sibling are sent with Vary: Accept-Encoding. No compression on the fly.
```
std::size_t metadata_cache_entries;
```
0 disables it.
```
std::chrono::milliseconds revalidate_after;
```
Within this window a changed file may still be described by its previous validators.

std::function< void(std::string_view, boost::beast::http::response_header<> &)> on_response;

It runs on the connection's thread and must be thread-safe.

Struct htdocs_options

Synopsis

Description

htdocs_options public public data members

`htdocs_options` public public data members