microserve::FileHandler class
#include <src/microserve/handler.cppm>

Serves static files and reverse-proxies configured locations.

Static bytes are cached only after enable_cache. The pool starts empty and is filled when a file is requested. A stored file is reused until its size or last-write time changes.

Public functions

void set_alt_svc(std::string v)
Set the Alt-Svc header value applied to responses.
void set_backends(std::vector<BackendConfig> backends)
Set upstream backends used for proxy locations.
void set_timeouts(const Config::TimeoutConfig& timeouts)
Set proxy timeout configuration.
void add_location(const std::string& route, const std::string& directory)
Map a URL path prefix to a local directory.
void add_location(const Config::ServerConfig::Location& loc)
Register a location from server configuration.
void add_proxy(const std::string& route, std::string proxy_pass)
Map a URL path prefix to an upstream proxy target.
void enable_cache(const CacheConfig& cfg)
Turn on the on-demand static-file cache for this handler.
void handle_request(const Request& req, Response& res)
Handle an HTTP request by matching a location and serving or proxying it.

Function documentation

void microserve::FileHandler::set_alt_svc(std::string v)

Set the Alt-Svc header value applied to responses.

Parameters
v Header value; empty disables the header.

void microserve::FileHandler::set_backends(std::vector<BackendConfig> backends)

Set upstream backends used for proxy locations.

Parameters
backends Named upstream pools referenced by proxy_pass.

void microserve::FileHandler::set_timeouts(const Config::TimeoutConfig& timeouts)

Set proxy timeout configuration.

Parameters
timeouts Connect, read, and write timeouts for upstreams.

void microserve::FileHandler::add_location(const std::string& route, const std::string& directory)

Map a URL path prefix to a local directory.

Parameters
route URL prefix, including the leading slash.
directory Filesystem root for files under route.

void microserve::FileHandler::add_location(const Config::ServerConfig::Location& loc)

Register a location from server configuration.

Parameters
loc Path, root, proxy target, and auth settings to copy.

void microserve::FileHandler::add_proxy(const std::string& route, std::string proxy_pass)

Map a URL path prefix to an upstream proxy target.

Parameters
route URL prefix, including the leading slash.
proxy_pass Upstream URL or backend reference.

void microserve::FileHandler::enable_cache(const CacheConfig& cfg)

Turn on the on-demand static-file cache for this handler.

Parameters
cfg Pool size and strategy from the resolved server.
Exceptions
std::runtime_error If the pool size or strategy cannot be applied.

Not called when the server has no cache key, so the cache stays off. Files are not read ahead of the first request.

void microserve::FileHandler::handle_request(const Request& req, Response& res)

Handle an HTTP request by matching a location and serving or proxying it.

Parameters
req Incoming request. The target query string is ignored for routing.
res Response to populate. HEAD clears a successful body.