microserve namespace

HTTP/3 server backend over QUIC/UDP.

Public HTTP server facade for the microserve stack.

Provides Http3Impl, a ServerImpl that binds one UDP socket and multiplexes many QUIC connections. Packet I/O lives in microserve.http3:quic; per-connection HTTP/3 state in microserve.http3:conn (neither partition is exported).

Selects an HTTP/1.1, HTTP/2, or HTTP/3 backend and exposes a single handler / start / stop API. Backend implementations live in the http2 / http3 modules as free ServerImpl subclasses (not nested types), which avoids a circular module import.

Namespaces

namespace po
namespace net
namespace beast
namespace http
namespace fs
namespace detail
Internal HTTP/1.1 session implementations.
namespace http3_detail
HTTP/3 application session (nghttp3) for one QUIC connection.
namespace cache
namespace yaml
namespace test

Classes

struct ListenSpec
One listen entry on a server.
struct BackendConfig
Named upstream pool referenced by proxy_pass.
struct CacheConfig
Fixed cache pool for one server.
struct FederationPeer
Another federation node this process knows about.
struct FederationConfig
Optional overlay from federation.yaml.
struct AddressOption
Parsed --address: bind IP and/or server_name.
struct Config
Parsed CLI and YAML configuration (before resolve).
struct ResolvedListen
One listen after dual-stack expansion.
struct ResolvedServer
One site after validation, expansion, and first-wins listen claims.
struct ResolvedConfig
Fully resolved configuration for the master process.
struct ServerImpl
Abstract server backend.
class FileHandler
Serves static files and reverse-proxies configured locations.
class Http2Impl
TLS HTTP/2 backend with HTTP/1.1 ALPN fallback.
class Http2ClearTextImpl
Clear-text HTTP/2 (h2c) and/or HTTP/1.1 backend.
class Http3Impl
HTTP/3 listener: one UDP socket, many QUIC connections.
struct ProxyTarget
Parsed proxy_pass value (nginx-compatible).
class Server
Public Server facade over protocol-specific backends.

Enums

enum class Protocol { Http11, Http2c, Http2, Http3 }
Application protocol for a listen.
enum class CacheStrategy { Simple }
Lookup strategy for a fixed response-cache pool.
enum class FederationRole { Standalone, Member, Hub }
Role of this process in a federation.
enum class FederationMembership { None, Unverified, Certified }
How this node is enrolled in the federation.

Typedefs

using tcp = net::ip::tcp
using udp = net::ip::udp
using error_code = boost::system::error_code
using Request = http::request<http::string_body>
using Response = http::response<http::string_body>
using Handler = std::function<void(const Request&, Response&)>
using steady_timer = net::steady_timer
using flat_buffer = beast::flat_buffer
using ssl_stream_tcp = net::ssl::stream<tcp::socket>
using Logger = std::shared_ptr<spdlog::logger>

Functions

auto try_parse_protocol(const std::string_view name) -> std::optional<Protocol>
Parse a protocol name (case-insensitive).
auto parse_protocol(const std::string_view name) -> Protocol
Parse a protocol name (case-insensitive).
auto try_parse_federation_role(const std::string_view name) -> std::optional<FederationRole>
Parse a federation role name, or std::nullopt if unknown.
auto parse_federation_role(const std::string_view name) -> FederationRole
Parse a federation role name.
auto try_parse_federation_membership(const std::string_view name) -> std::optional<FederationMembership>
Parse a federation membership name, or std::nullopt if unknown.
auto parse_federation_membership(const std::string_view name) -> FederationMembership
Parse a federation membership name.
auto federation_role_name(const FederationRole r) -> std::string_view constexpr
Canonical name of a federation role.
auto federation_membership_name(const FederationMembership m) -> std::string_view constexpr
Canonical name of a federation membership.
auto federation_node_urn(std::string_view node_id, const std::string_view urn_nid = "microserve") -> std::string
Membership SAN URI for a federation node certificate.
auto parse_protocol_list(const std::string_view csv) -> std::vector<Protocol>
Parse a comma-separated list of protocol names.
auto protocol_name(const Protocol p) -> std::string_view constexpr
Canonical name of a protocol (http11, http2c, http2, http3).
auto protocol_requires_tls(const Protocol p) -> bool constexpr
True if the protocol requires TLS (HTTP/2, HTTP/3).
auto protocol_is_cleartext(const Protocol p) -> bool constexpr
True if the protocol is cleartext (HTTP/1.1, h2c).
auto protocol_is_udp(const Protocol p) -> bool constexpr
True if the protocol is UDP-based (HTTP/3).
auto try_parse_cache_strategy(const std::string_view name) -> std::optional<CacheStrategy>
Parse a cache strategy name, or std::nullopt if unknown.
auto parse_cache_strategy(const std::string_view name) -> CacheStrategy
Parse a cache strategy name.
auto cache_strategy_name(const CacheStrategy s) -> std::string_view constexpr
Canonical name of a cache strategy.
auto parse_byte_size(const std::string_view raw) -> std::uint64_t
Parse a byte size (128, 128kb, 128mb, 1gb).
auto parse_address_option(const std::string_view s) -> AddressOption
Split --address into a bind IP and/or server_name.
auto parse_listen(const std::string& s) -> std::pair<std::string, unsigned short>
Parse a listen bind: bare port, host:port, or [ipv6]:port.
auto format_bind(const std::string_view host, const unsigned short port) -> std::string
Format a listen bind as a bare port, host:port, or [ipv6]:port.
auto make_cli_server(const Config& config) -> Config::ServerConfig
Build the single server implied by CLI listen flags.
auto is_valid_error_log_level(const std::string& error_log_level) -> bool
Checks if the provided error log level is valid.
auto count_verbosity_args(const int argc, char* argv[]) -> int
Counts the number of verbosity flags present in command-line arguments.
auto create_options_description() -> po::options_description
Command-line options for server configuration.
void print_help(const po::options_description& desc)
Prints the command-line options description along with usage examples.
auto parse_arguments(const int argc, char* argv[], Config& config, std::string& config_file) -> bool
Parses command line arguments into a structured options object.
auto parse_bind(const std::string& s) -> std::pair<std::string, unsigned short>
Split a host:port bind string on the last :.
auto resolve_bind_addr(const std::string& addr_str, const bool ipv6) -> std::pair<std::string, unsigned short>
Keep addr_str's port and force a wildcard address family.
auto bind_addrs(const std::string& addr_str, const bool ipv6_flag, const bool no_ipv4, const bool force_ipv4_only) -> std::vector<std::pair<std::string, unsigned short>>
Build the list of listen addresses for a bind string.
auto expand_listen(const std::string& bind, const bool ipv6_flag, const bool no_ipv4) -> std::vector<std::pair<std::string, unsigned short>>
Expand a listen bind into concrete (addr, port) sockets.
auto effective_protocols(const ListenSpec& listen, const Config::ServerConfig& server) -> const std::vector<Protocol>&
Protocols in effect for one listen entry.
auto proxy_pass_backend_name(const std::string_view proxy_pass, const std::vector<BackendConfig>& backends) -> std::optional<std::string>
Backend name referenced by a proxy_pass, if any.
auto resolve_config(const Config& config) -> ResolvedConfig
Resolve sites for the master process.
void apply_runtime_paths(Config& config)
Place relative logs under log_dir and a relative pid next to the executable.
auto load_config(const std::string& config_path) -> Config
Load and parse application configuration from the YAML file at config_path.
void load_federation(const std::string& path, Config& config)
Overlay federation.yaml onto an already-loaded Config.
auto is_ssl_stream_truncated(const error_code& ec) -> bool
auto base64_decode(const std::string_view input) -> std::string
Decode a Base64 string.
auto base64_encode(const unsigned char* data, const size_t len) -> std::string
Encode bytes as a Base64 string.
auto is_basic_auth_enabled(const std::string_view auth) -> bool
Whether HTTP Basic authentication is enabled for this auth setting.
auto constant_time_equals(const std::string_view a, const std::string_view b) -> bool
Compare two strings in constant time.
auto apr1_to64(uint32_t value, int count) -> std::string
Encode a value in the Apache APR1 hash alphabet.
auto sha512_base64(const std::string_view password) -> std::string
SHA-512 hash of a password, Base64-encoded.
auto verify_htpasswd_entry(const std::string_view password, std::string_view stored_hash) -> bool
Verify a password against a single htpasswd hash entry.
auto verify_htpasswd_file(const std::string& path, const std::string_view user, const std::string_view password) -> bool
Verify credentials against an htpasswd file.
auto get_mime_type(const std::string& path) -> std::string
Determines the MIME type of the file based on the file extension.
void set_file_ok(const std::string& file_path, std::string content, Response& res)
Fill a successful static-file response.
auto read_file_bytes(const std::string& file_path) -> std::optional<std::string>
Read an entire file as bytes.
auto serve_file(const std::string& file_path, Response& res) -> bool
Read a regular file and prepare an HTTP 200 response.
auto setup_file_handler(const std::vector<std::string>& locations, FileHandler& file_server) -> bool
Registers route:directory pairs on a FileHandler.
void log_info(std::string_view msg)
void log_warn(std::string_view msg)
void log_error(std::string_view msg)
void log_debug(std::string_view msg)
void log_access(std::string_view msg)
void logger_flush()
void setup_logger()
void set_logger_level(const std::string& level_name)
void set_logger_identity(std::string_view tag)
auto logger_identity() -> std::string
auto site_error_log_path(std::string_view base_path, std::string_view site_name) -> std::string
void rebind_logger_sinks(const std::string& file_path, bool to_stdout = true)
void rebind_access_log(const std::string& file_path, bool to_stdout = false)
void shutdown_logging()
auto path_is_absolute(std::string_view path) -> bool
True for a leading slash or a Windows drive path (C:/...).
auto executable_directory() -> std::string
Directory containing the running executable.
auto join_path(std::string_view dir, std::string_view child) -> std::string
Join dir and child.
void ensure_parent_directory(const std::string& file_path)
Create the parent directory of file_path when it is missing.
auto write_pid_file(const std::string& path) -> bool
Write this process id to path, creating parent directories.
void remove_pid_file(const std::string& path)
Remove a pid file created by write_pid_file.
void log_listener_urls(const std::string& kind, const std::string& scheme, const std::string& addr, unsigned short port)
Log a human-readable listener URL for a started server.
auto run_server_instance(const Config& config, const ResolvedServer& instance) -> int
Serve one resolved site in the current process.
auto run_sites(const Config& config, const ResolvedConfig& resolved, int argc, char* argv[]) -> int
Run all resolved sites, spawning children when there is more than one.
auto make_child_argv(int argc, char* argv[], int index) -> std::vector<std::string>
Rewrite argv for an isolated site child (--child --server-index=N).
void log_site_listen_map(const ResolvedServer& instance)
Log the console listen map for one site.
auto parse_proxy_pass(std::string_view proxy_pass) -> ProxyTarget
Parse a proxy_pass directive into scheme, host, port, and URI.
auto rewrite_proxy_target(std::string_view location, std::string_view request_target, const ProxyTarget& target) -> std::string
Rewrite the request target for the upstream.
auto resolve_proxy_upstream(const ProxyTarget& target, const std::vector<BackendConfig>& backends, std::string& host, unsigned short& port) -> bool
Resolve the upstream host and port for a parsed target.
void proxy_request(const Request& req, Response& res, std::string_view location_path, std::string_view proxy_pass, const std::vector<BackendConfig>& backends, const Config::TimeoutConfig& timeouts)
Reverse-proxy an HTTP request to an upstream.
static auto get_logger() -> Logger
static auto get_access_logger() -> Logger
static auto sanitize_site_stem(const std::string_view site) -> std::string
static auto wide_to_utf8(const std::wstring_view w) -> std::string

Variables

int DEFAULT_PORT constexpr
std::string_view DEFAULT_ADDR constexpr
std::string_view DEFAULT_HOST constexpr
std::string_view DEFAULT_LOGLEVEL constexpr
std::string_view LOGGER_NAME constexpr
std::string_view LOGGER_PATTERN constexpr
std::size_t LOGGER_QUEUE_SIZE constexpr
int LOGGER_THREAD_COUNT constexpr
std::size_t LOGGER_FILE_MAX_SIZE constexpr
int LOGGER_FILE_MAX_COUNT constexpr
static std::string g_identity
std::string_view ACCESS_LOGGER_NAME constexpr

Enum documentation

enum class microserve::Protocol
#include <src/microserve/config.cppm>

Application protocol for a listen.

enum class microserve::CacheStrategy
#include <src/microserve/config.cppm>

Lookup strategy for a fixed response-cache pool.

enum class microserve::FederationRole
#include <src/microserve/config.cppm>

Role of this process in a federation.

enum class microserve::FederationMembership
#include <src/microserve/config.cppm>

How this node is enrolled in the federation.

Typedef documentation

using microserve::tcp = net::ip::tcp
#include <src/microserve/core.cppm>

using microserve::udp = net::ip::udp
#include <src/microserve/core.cppm>

using microserve::error_code = boost::system::error_code
#include <src/microserve/core.cppm>

using microserve::Request = http::request<http::string_body>
#include <src/microserve/core.cppm>

using microserve::Response = http::response<http::string_body>
#include <src/microserve/core.cppm>

using microserve::Handler = std::function<void(const Request&, Response&)>
#include <src/microserve/core.cppm>

using microserve::steady_timer = net::steady_timer
#include <src/microserve/core.cppm>

using microserve::flat_buffer = beast::flat_buffer
#include <src/microserve/core.cppm>

using microserve::ssl_stream_tcp = net::ssl::stream<tcp::socket>
#include <src/microserve/core.cppm>

using microserve::Logger = std::shared_ptr<spdlog::logger>
#include <src/microserve/wire.cpp>

Function documentation

std::optional<Protocol> microserve::try_parse_protocol(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a protocol name (case-insensitive).

Accepted aliases: http11, http1, http1.1, http/1.1 http2c, h2c, http2clear, http2cleartext http2, h2 http3, h3

Protocol microserve::parse_protocol(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a protocol name (case-insensitive).

Exceptions
std::runtime_error If name is not a known protocol.

std::optional<FederationRole> microserve::try_parse_federation_role(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a federation role name, or std::nullopt if unknown.

FederationRole microserve::parse_federation_role(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a federation role name.

Exceptions
std::runtime_error If name is not standalone, member, or hub.

std::optional<FederationMembership> microserve::try_parse_federation_membership(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a federation membership name, or std::nullopt if unknown.

FederationMembership microserve::parse_federation_membership(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a federation membership name.

Exceptions
std::runtime_error If name is not none, unverified, or certified.

std::string_view microserve::federation_role_name(const FederationRole r) constexpr
#include <src/microserve/config.cppm>

Canonical name of a federation role.

std::string_view microserve::federation_membership_name(const FederationMembership m) constexpr
#include <src/microserve/config.cppm>

Canonical name of a federation membership.

std::string microserve::federation_node_urn(std::string_view node_id, const std::string_view urn_nid = "microserve")
#include <src/microserve/config.cppm>

Membership SAN URI for a federation node certificate.

Parameters
node_id Node identifier; empty yields an empty string.
urn_nid URN NID, default "microserve".
Returns SAN URI, or empty if node_id is empty.

Format urn:{urn_nid}:node:{node_id} (e.g. urn:microserve:node:fed-node-1).

std::vector<Protocol> microserve::parse_protocol_list(const std::string_view csv)
#include <src/microserve/config.cppm>

Parse a comma-separated list of protocol names.

Parameters
csv Protocol names, e.g. "http11,http2c".
Returns Parsed protocols in order.
Exceptions
std::runtime_error If any token is not a known protocol.

std::string_view microserve::protocol_name(const Protocol p) constexpr
#include <src/microserve/config.cppm>

Canonical name of a protocol (http11, http2c, http2, http3).

bool microserve::protocol_requires_tls(const Protocol p) constexpr
#include <src/microserve/config.cppm>

True if the protocol requires TLS (HTTP/2, HTTP/3).

bool microserve::protocol_is_cleartext(const Protocol p) constexpr
#include <src/microserve/config.cppm>

True if the protocol is cleartext (HTTP/1.1, h2c).

bool microserve::protocol_is_udp(const Protocol p) constexpr
#include <src/microserve/config.cppm>

True if the protocol is UDP-based (HTTP/3).

std::optional<CacheStrategy> microserve::try_parse_cache_strategy(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a cache strategy name, or std::nullopt if unknown.

CacheStrategy microserve::parse_cache_strategy(const std::string_view name)
#include <src/microserve/config.cppm>

Parse a cache strategy name.

Exceptions
std::runtime_error If name is not simple.

std::string_view microserve::cache_strategy_name(const CacheStrategy s) constexpr
#include <src/microserve/config.cppm>

Canonical name of a cache strategy.

std::uint64_t microserve::parse_byte_size(const std::string_view raw)
#include <src/microserve/config.cppm>

Parse a byte size (128, 128kb, 128mb, 1gb).

Exceptions
std::runtime_error If raw is empty, not a positive size, or the unit is unknown.

A bare number is bytes. Units k/kb, m/mb, and g/gb are powers of 1024 and are case-insensitive.

AddressOption microserve::parse_address_option(const std::string_view s)
#include <src/microserve/config.cppm>

Split --address into a bind IP and/or server_name.

Parameters
s Option value, e.g. "127.0.0.1", "example.com", or "0.0.0.0,example.com".
Returns Bind and/or server name; unused fields are empty.

Tokens are comma-separated. IPs become the bind address; hostnames become server_name. Last of each kind wins.

std::pair<std::string, unsigned short> microserve::parse_listen(const std::string& s)
#include <src/microserve/config.cppm>

Parse a listen bind: bare port, host:port, or [ipv6]:port.

Parameters
s Bind string to parse.
Returns (host, port); host is empty for a bare port.
Exceptions
std::runtime_error If s is empty, malformed, or the port is not in 1..65535.

A bare port returns an empty host (unspecified; expanded later by dual-stack policy). Bracketed IPv6 is returned without [].

std::string microserve::format_bind(const std::string_view host, const unsigned short port)
#include <src/microserve/config.cppm>

Format a listen bind as a bare port, host:port, or [ipv6]:port.

Parameters
host Bind address; empty means unspecified (bare port only).
port Listen port.
Returns Bind string suitable for parse_listen.

Config::ServerConfig microserve::make_cli_server(const Config& config)
#include <src/microserve/config.cppm>

Build the single server implied by CLI listen flags.

Parameters
config Parsed CLI configuration.
Returns One server with listen entries and protocols filled in.

Used when --listen, --address, or --proto is set; YAML servers must be ignored. Omitted flags default to listen 9090, proto http2c, wildcard bind, and server_name=localhost.

bool microserve::is_valid_error_log_level(const std::string& error_log_level)
#include <src/microserve/config.cppm>

Checks if the provided error log level is valid.

Parameters
error_log_level The log level string to validate
Returns true if the log level is valid, false otherwise

Validates that the error_log_level string is one of the supported log levels: trace, debug, info, warn, error, or crit.

int microserve::count_verbosity_args(const int argc, char* argv[])
#include <src/microserve/config.cppm>

Counts the number of verbosity flags present in command-line arguments.

Parameters
argc Argument count passed to main().
argv Argument vector passed to main().
Returns Total number of verbosity indicators found.

Long option –verbose is counted once per occurrence. Short options are scanned for every 'v' character so that -v, -vv, -vvv and mixed clusters such as -hv are each counted correctly. Option parsing stops at the first bare "--" argument.

po::options_description microserve::create_options_description()
#include <src/microserve/config.cppm>

Command-line options for server configuration.

Returns Boost.ProgramOptions description of allowed flags.

void microserve::print_help(const po::options_description& desc)
#include <src/microserve/config.cppm>

Prints the command-line options description along with usage examples.

Parameters
desc The Boost.ProgramOptions options description to output.

bool microserve::parse_arguments(const int argc, char* argv[], Config& config, std::string& config_file)
#include <src/microserve/config.cppm>

Parses command line arguments into a structured options object.

Parameters
argc Number of command line arguments.
argv Array of C-style strings containing the arguments.
config Server config object
config_file Location of a YAML configuration file
Returns Parsed arguments wrapped in a structured container.

--listen, --address, and --proto have no defaults: presence is detected with variables_map::contains. If any of the three is set, YAML servers must be ignored (Config::cli_overrides_servers()). --ipv6 / --no-ipv4 are global and do not trigger that override.

std::pair<std::string, unsigned short> microserve::parse_bind(const std::string& s)
#include <src/microserve/config.cppm>

Split a host:port bind string on the last :.

Parameters
s Bind string, e.g. "0.0.0.0:9090".
Returns Host substring and parsed port.
Exceptions
std::runtime_error If s contains no :.
std::invalid_argument / std::out_of_range If the port is not an integer.

std::pair<std::string, unsigned short> microserve::resolve_bind_addr(const std::string& addr_str, const bool ipv6)
#include <src/microserve/config.cppm>

Keep addr_str's port and force a wildcard address family.

Parameters
addr_str Original bind string (only the port is used).
ipv6 If true, address is "::"; otherwise "0.0.0.0".
Returns (wildcard_addr, port).
Exceptions
std::runtime_error If addr_str is not valid host:port.

std::vector<std::pair<std::string, unsigned short>> microserve::bind_addrs(const std::string& addr_str, const bool ipv6_flag, const bool no_ipv4, const bool force_ipv4_only)
#include <src/microserve/config.cppm>

Build the list of listen addresses for a bind string.

Parameters
addr_str Bind string in host:port form (host is ignored except for its port; family comes from the flags).
ipv6_flag When true (and neither force-IPv4 nor no-IPv4), also listen on IPv6.
no_ipv4 When true, listen on IPv6 only (--no-ipv4).
force_ipv4_only When true, listen on IPv4 only (typical default for cleartext HTTP unless --no-ipv4).
Returns One or two (address, port) pairs suitable for acceptor bind.
Exceptions
std::runtime_error If addr_str has no host:port shape (via parse_bind / resolve_bind_addr).

Keeps the port from addr_str and selects address families from the CLI dual-stack policy.

ConditionResult
force_ipv4_only is trueIPv4 only (0.0.0.0)
no_ipv4 is trueIPv6 only (::)
ipv6_flag is trueIPv4 + IPv6
defaultIPv4 only

Plain HTTP normally passes force_ipv4_only as true. When --no-ipv4 is set, callers should pass false so HTTP/1 (or h2c), HTTPS, and HTTP/3 all bind IPv6-only.

std::vector<std::pair<std::string, unsigned short>> microserve::expand_listen(const std::string& bind, const bool ipv6_flag, const bool no_ipv4)
#include <src/microserve/config.cppm>

Expand a listen bind into concrete (addr, port) sockets.

Parameters
bind Bare port, host:port, or [ipv6]:port.
ipv6_flag Also listen on IPv6 for unspecified binds (--ipv6).
no_ipv4 IPv6-only for unspecified binds (--no-ipv4).
Returns One or more (address, port) pairs suitable for bind.
Exceptions
std::runtime_error If bind is not a valid listen address.

Explicit addresses (127.0.0.1, ::1, NIC IPs) are kept as-is. Unspecified binds (bare port or 0.0.0.0) follow ipv6_flag / no_ipv4. A literal :: is IPv6-only and is not rewritten.

const std::vector<Protocol>& microserve::effective_protocols(const ListenSpec& listen, const Config::ServerConfig& server)
#include <src/microserve/config.cppm>

Protocols in effect for one listen entry.

Parameters
listen Listen spec whose per-entry protocols may override.
server Server whose protocol list is the fallback.
Returns Reference to the chosen protocol list (never copied).

Uses listen's own list when it is non-empty; otherwise inherits server's protocol list.

std::optional<std::string> microserve::proxy_pass_backend_name(const std::string_view proxy_pass, const std::vector<BackendConfig>& backends)
#include <src/microserve/config.cppm>

Backend name referenced by a proxy_pass, if any.

Parameters
proxy_pass Location proxy_pass value.
backends Known backends to match against.
Returns Backend name; empty string if backend: has no name; std::nullopt if this is not a backend reference.

Matches backend:name / backend://name, a bare known backend name, or a URL whose host is a known backend and has no port. Direct URLs (IP or host:port) are not backends.

ResolvedConfig microserve::resolve_config(const Config& config)
#include <src/microserve/config.cppm>

Resolve sites for the master process.

Parameters
config Parsed CLI and YAML configuration.
Returns Expanded servers, warnings, and federation status.

Applies CLI overlay (when set), dual-stack expansion, first-wins listen claims, and the backend subset each site actually uses. A colliding listen is warned and dropped; a site with none left is skipped. Other sites still start.

void microserve::apply_runtime_paths(Config& config)
#include <src/microserve/config.cppm>

Place relative logs under log_dir and a relative pid next to the executable.

Absolute paths are kept. An empty log_dir means <exe>/logs. Quoted path values are unquoted first.

Config microserve::load_config(const std::string& config_path)
#include <src/microserve/config.cppm>

Load and parse application configuration from the YAML file at config_path.

Parameters
config_path Path to the configuration file to open and read.
Returns Config populated from microserve, timeouts, backends, and servers sections.

void microserve::load_federation(const std::string& path, Config& config)
#include <src/microserve/config.cppm>

Overlay federation.yaml onto an already-loaded Config.

Does not replace servers, backends, or listen policy.

bool microserve::is_ssl_stream_truncated(const error_code& ec)
#include <src/microserve/core.cppm>

std::string microserve::base64_decode(const std::string_view input)
#include <src/microserve/handler.cppm>

Decode a Base64 string.

Parameters
input Base64-encoded text.
Returns The decoded bytes as a string.

std::string microserve::base64_encode(const unsigned char* data, const size_t len)
#include <src/microserve/handler.cppm>

Encode bytes as a Base64 string.

Parameters
data Bytes to encode.
len Number of bytes in data.
Returns The Base64-encoded text.

bool microserve::is_basic_auth_enabled(const std::string_view auth)
#include <src/microserve/handler.cppm>

Whether HTTP Basic authentication is enabled for this auth setting.

Parameters
auth Auth mode from the location (basic is case-insensitive).
Returns true if auth selects HTTP Basic authentication.

bool microserve::constant_time_equals(const std::string_view a, const std::string_view b)
#include <src/microserve/handler.cppm>

Compare two strings in constant time.

Parameters
a First string.
b Second string.
Returns true if a and b are the same length and equal.

std::string microserve::apr1_to64(uint32_t value, int count)
#include <src/microserve/handler.cppm>

Encode a value in the Apache APR1 hash alphabet.

Parameters
value Bits to encode.
count Number of alphabet characters to emit.
Returns The encoded text.

std::string microserve::sha512_base64(const std::string_view password)
#include <src/microserve/handler.cppm>

SHA-512 hash of a password, Base64-encoded.

Parameters
password Password bytes to hash.
Returns Base64 encoding of the SHA-512 digest.

bool microserve::verify_htpasswd_entry(const std::string_view password, std::string_view stored_hash)
#include <src/microserve/handler.cppm>

Verify a password against a single htpasswd hash entry.

Parameters
password Password supplied by the client.
stored_hash Hash field from the htpasswd line.
Returns true if password matches stored_hash.

bool microserve::verify_htpasswd_file(const std::string& path, const std::string_view user, const std::string_view password)
#include <src/microserve/handler.cppm>

Verify credentials against an htpasswd file.

Parameters
path Path to the htpasswd file.
user Username to look up.
password Password supplied by the client.
Returns true if user is present and password matches its hash.

std::string microserve::get_mime_type(const std::string& path)
#include <src/microserve/handler.cppm>

Determines the MIME type of the file based on the file extension.

Parameters
path File path whose extension is inspected.
Returns MIME type string; "text/plain" if the extension is unknown.

Extracts the file extension from the provided path and returns the corresponding MIME type. Unrecognised extensions fall back to "text/plain".

void microserve::set_file_ok(const std::string& file_path, std::string content, Response& res)
#include <src/microserve/handler.cppm>

Fill a successful static-file response.

Parameters
file_path Path used only to choose the Content-Type.
content Response body; moved into res.
res Response to populate.

std::optional<std::string> microserve::read_file_bytes(const std::string& file_path)
#include <src/microserve/handler.cppm>

Read an entire file as bytes.

Parameters
file_path Path of the file to open.
Returns File contents, or std::nullopt if the file cannot be opened.

bool microserve::serve_file(const std::string& file_path, Response& res)
#include <src/microserve/handler.cppm>

Read a regular file and prepare an HTTP 200 response.

Parameters
file_path Path of the file to serve.
res Response to populate on success.
Returns true on success; false if the path is missing, not a regular file, or cannot be read.

bool microserve::setup_file_handler(const std::vector<std::string>& locations, FileHandler& file_server)
#include <src/microserve/handler.cppm>

Registers route:directory pairs on a FileHandler.

Parameters
locations Entries of the form route:directory.
file_server Handler to populate.
Returns false if any entry has an invalid format; true otherwise.

void microserve::log_info(std::string_view msg)
#include <src/microserve/logging.cppm>

void microserve::log_warn(std::string_view msg)
#include <src/microserve/logging.cppm>

void microserve::log_error(std::string_view msg)
#include <src/microserve/logging.cppm>

void microserve::log_debug(std::string_view msg)
#include <src/microserve/logging.cppm>

void microserve::log_access(std::string_view msg)
#include <src/microserve/logging.cppm>

void microserve::logger_flush()
#include <src/microserve/logging.cppm>

void microserve::setup_logger()
#include <src/microserve/logging.cppm>

void microserve::set_logger_level(const std::string& level_name)
#include <src/microserve/logging.cppm>

void microserve::set_logger_identity(std::string_view tag)
#include <src/microserve/logging.cppm>

std::string microserve::logger_identity()
#include <src/microserve/logging.cppm>

std::string microserve::site_error_log_path(std::string_view base_path, std::string_view site_name)
#include <src/microserve/logging.cppm>

void microserve::rebind_logger_sinks(const std::string& file_path, bool to_stdout = true)
#include <src/microserve/logging.cppm>

void microserve::rebind_access_log(const std::string& file_path, bool to_stdout = false)
#include <src/microserve/logging.cppm>

void microserve::shutdown_logging()
#include <src/microserve/logging.cppm>

bool microserve::path_is_absolute(std::string_view path)
#include <src/microserve/logging.cppm>

True for a leading slash or a Windows drive path (C:/...).

std::string microserve::executable_directory()
#include <src/microserve/logging.cppm>

Directory containing the running executable.

Returns "." if the executable path cannot be determined.

std::string microserve::join_path(std::string_view dir, std::string_view child)
#include <src/microserve/logging.cppm>

Join dir and child.

An absolute child is returned unchanged.

void microserve::ensure_parent_directory(const std::string& file_path)
#include <src/microserve/logging.cppm>

Create the parent directory of file_path when it is missing.

Exceptions
std::runtime_error If the directory cannot be created.

bool microserve::write_pid_file(const std::string& path)
#include <src/microserve/logging.cppm>

Write this process id to path, creating parent directories.

Returns false if the file cannot be created.

void microserve::remove_pid_file(const std::string& path)
#include <src/microserve/logging.cppm>

Remove a pid file created by write_pid_file.

void microserve::log_listener_urls(const std::string& kind, const std::string& scheme, const std::string& addr, unsigned short port)
#include <src/microserve/logging.cppm>

Log a human-readable listener URL for a started server.

Parameters
kind Short protocol label.
scheme URI scheme without :// (e.g. "http", "https").
addr Bound address string (0.0.0.0, ::, or a specific host).
port Bound TCP/UDP port.

Wildcard binds are rewritten to loopback so the log line is directly usable in a browser or client:

  • 0.0.0.0 -> 127.0.0.1
  • :: -> [::1]

Other addresses are logged as given. No-op if the microserve logger has not been registered yet.

int microserve::run_server_instance(const Config& config, const ResolvedServer& instance)
#include <src/microserve/process.cppm>

Serve one resolved site in the current process.

Parameters
config Runtime configuration (timeouts, verbosity, CLI flags).
instance Resolved site to bind and serve.
Returns 0 on clean shutdown; 1 if handler setup fails or no listener could be bound.

Configures the file/proxy handler, binds grouped listeners, and runs the I/O loop until SIGINT/SIGTERM (or the Windows console-control equivalents).

int microserve::run_sites(const Config& config, const ResolvedConfig& resolved, int argc, char* argv[])
#include <src/microserve/process.cppm>

Run all resolved sites, spawning children when there is more than one.

Parameters
config Runtime configuration, including child CLI flags.
resolved Fully resolved servers and federation state.
argc Argument count from main (used to rebuild child argv).
argv Argument vector from main.
Returns Combined process exit code (0 if every site exited cleanly).

With --child, serves only config.cli_server_index. A single site runs in-process. Otherwise this process is the master: it logs each site's listen map, spawns isolated children, and waits for them.

std::vector<std::string> microserve::make_child_argv(int argc, char* argv[], int index)
#include <src/microserve/process.cppm>

Rewrite argv for an isolated site child (--child --server-index=N).

Parameters
argc Argument count from main.
argv Argument vector from main.
index Site index in the resolved server list.
Returns Argument strings suitable for spawning the child.

Copies the current arguments, dropping any existing --child / --server-index flags, then appends those flags for index.

void microserve::log_site_listen_map(const ResolvedServer& instance)
#include <src/microserve/process.cppm>

Log the console listen map for one site.

Parameters
instance Resolved site whose listeners are printed.

The master prints this before spawning so operators can see each site's URLs without waiting for child logs.

ProxyTarget microserve::parse_proxy_pass(std::string_view proxy_pass)
#include <src/microserve/proxy.cppm>

Parse a proxy_pass directive into scheme, host, port, and URI.

Parameters
proxy_pass Raw proxy_pass string from configuration.
Returns Parsed target; empty or default fields if the value is invalid.

Accepts http://, https://, h2c://, and backend: forms. A URI after the host (including /) sets has_uri so the location prefix is rewritten.

std::string microserve::rewrite_proxy_target(std::string_view location, std::string_view request_target, const ProxyTarget& target)
#include <src/microserve/proxy.cppm>

Rewrite the request target for the upstream.

Parameters
location Matched location path prefix.
request_target Original request target (path and query).
target Parsed proxy_pass value.
Returns Upstream request target including query string.

When the target has no URI, the original path and query are forwarded. Otherwise the matched location prefix is replaced by target.uri.

bool microserve::resolve_proxy_upstream(const ProxyTarget& target, const std::vector<BackendConfig>& backends, std::string& host, unsigned short& port)
#include <src/microserve/proxy.cppm>

Resolve the upstream host and port for a parsed target.

Parameters
target Parsed proxy_pass value.
backends Configured named backends.
host out Resolved upstream host.
port out Resolved upstream port.
Returns true if host and port were resolved.

Named backend: targets use the first server of the matching backend. Direct host targets copy target.host and target.port.

void microserve::proxy_request(const Request& req, Response& res, std::string_view location_path, std::string_view proxy_pass, const std::vector<BackendConfig>& backends, const Config::TimeoutConfig& timeouts)
#include <src/microserve/proxy.cppm>

Reverse-proxy an HTTP request to an upstream.

Parameters
req Incoming client request.
res Response filled from the upstream (or an error).
location_path Matched location prefix used for URI rewrite.
proxy_pass Raw proxy_pass directive.
backends Named backends for backend: targets.
timeouts Connect/read/write timeouts.

Forwards over HTTP/1.1, or h2c when the scheme is h2c or HTTP/1.1 fails with a connection error. Hop-by-hop headers are stripped. Writes 502/504 into res on failure.

static Logger microserve::get_logger()
#include <src/microserve/wire.cpp>

static Logger microserve::get_access_logger()
#include <src/microserve/wire.cpp>

static std::string microserve::sanitize_site_stem(const std::string_view site)
#include <src/microserve/wire.cpp>

static std::string microserve::wide_to_utf8(const std::wstring_view w)
#include <src/microserve/wire.cpp>

Variable documentation

int microserve::DEFAULT_PORT constexpr
#include <src/microserve/config.cppm>

std::string_view microserve::DEFAULT_ADDR constexpr
#include <src/microserve/config.cppm>

std::string_view microserve::DEFAULT_HOST constexpr
#include <src/microserve/config.cppm>

std::string_view microserve::DEFAULT_LOGLEVEL constexpr
#include <src/microserve/config.cppm>

std::string_view microserve::LOGGER_NAME constexpr
#include <src/microserve/logging.cppm>

std::string_view microserve::LOGGER_PATTERN constexpr
#include <src/microserve/logging.cppm>

std::size_t microserve::LOGGER_QUEUE_SIZE constexpr
#include <src/microserve/logging.cppm>

int microserve::LOGGER_THREAD_COUNT constexpr
#include <src/microserve/logging.cppm>

std::size_t microserve::LOGGER_FILE_MAX_SIZE constexpr
#include <src/microserve/logging.cppm>

int microserve::LOGGER_FILE_MAX_COUNT constexpr
#include <src/microserve/logging.cppm>

static std::string microserve::g_identity
#include <src/microserve/wire.cpp>

std::string_view microserve::ACCESS_LOGGER_NAME constexpr
#include <src/microserve/wire.cpp>