NPRPC docs

class RpcBuilderHttp

C++

class RpcBuilderHttp : public RpcBuilderBase

HTTP, WebSocket, HTTP/3 and WebTransport settings; see RpcBuilderBase::with_http.

The max_*_per_second limits are token buckets per client IP or session: rate tokens a second, holding at most burst (0 = rate).

include/nprpc/nprpc.hpp:914

Constructors

explicit RpcBuilderHttp(std::shared_ptr<impl::BuildConfig> cfg)

include/nprpc/nprpc.hpp:918

Methods

RpcBuilderHttp &allow_origins(std::initializer_list<std::string_view> origins) noexcept

Browser origins allowed to call cross-origin, e.g. {"https://app.example.com"}. Replaces any earlier list.

include/nprpc/nprpc.hpp:926

RpcBuilderHttp &allow_origins(std::vector<std::string> origins) noexcept

allow_origins for a list built at run time.

include/nprpc/nprpc.hpp:939

RpcBuilderHttp &cache_control(std::string pattern, std::string value)

Send value as the Cache-Control of static files whose request path matches pattern, over HTTP/1.1 and HTTP/3 (200, 206 and 304 alike). Rules are tried in the order added and the first match wins; files no rule matches get public, max-age=3600. An empty value sends no Cache-Control at all. Page-handler responses are not affected.

A pattern without '/' matches the file name in any directory (*.html); one with '/' matches the whole path (/assets/**). * matches within one path segment, ** across segments, ? one character. For example, content-hashed assets cached for good and HTML always revalidated:

.cache_control("/assets/**", "public, max-age=31536000, immutable") .cache_control("*.html", "no-cache")

include/nprpc/nprpc.hpp:1097

RpcBuilderHttp &compression(bool enabled = true, size_t min_size = 256) noexcept

Compress HTTP/1.1 and HTTP/3 responses with br, gzip or deflate, whichever the client's Accept-Encoding prefers (br on a tie). Applies to static files of text-like types (HTML, CSS, JS, JSON, SVG, WASM, ...) — each is compressed once per coding and kept in the file cache, brotli at its best quality for files up to 64 KiB — and to page-handler responses, which are compressed per request. RPC traffic, already-compressed media, Range requests, and bodies smaller than min_size bytes are sent as-is.

include/nprpc/nprpc.hpp:1074

RpcBuilderHttp &enable_http3() noexcept

Also serves HTTP/3 and WebTransport on the same port (UDP). Needs ssl().

include/nprpc/nprpc.hpp:1024

RpcBuilderHttp &enable_if_http3(bool condition) noexcept

enable_http3() when condition holds.

include/nprpc/nprpc.hpp:1016

RpcBuilderHttp &http3_idle_timeout(std::chrono::milliseconds timeout) noexcept

QUIC idle timeout the HTTP/3 server announces (max_idle_timeout): a connection with nothing sent for the shorter of this and the client's value is dropped. The server sends no PINGs to keep connections open; a client that wants to keep one does. Zero announces no timeout, so only the client's applies. Default: 30 s.

include/nprpc/nprpc.hpp:1166

RpcBuilderHttp &http3_workers(size_t count) noexcept

Set the number of dedicated HTTP/3 worker sockets/threads. Pass 0 to auto-size from hardware concurrency; default: 4.

include/nprpc/nprpc.hpp:1155

RpcBuilderHttp &keep_alive_timeout(std::chrono::seconds timeout) noexcept

How long an HTTP/1.1 connection may stay idle between requests before it is closed. Zero turns keep-alive off: every response closes the connection. The TLS handshake, the first request and every write keep their own fixed 6 s limit.

include/nprpc/nprpc.hpp:1060

RpcBuilderHttp &max_http3_connections_per_ip(size_t count) noexcept

Limits concurrent HTTP/3 connections per client IP.

include/nprpc/nprpc.hpp:1173

RpcBuilderHttp &max_http3_new_connections_per_ip_per_second(size_t rate, size_t burst = 0) noexcept

Limits new HTTP/3 connections per client IP.

include/nprpc/nprpc.hpp:1180

RpcBuilderHttp &max_http_rpc_requests_per_ip_per_second(size_t rate, size_t burst = 0) noexcept

Limits RPC-over-HTTP requests per client IP.

include/nprpc/nprpc.hpp:981

RpcBuilderHttp &max_request_body_size(size_t bytes) noexcept

Largest HTTP request body accepted.

include/nprpc/nprpc.hpp:1050

RpcBuilderHttp &max_websocket_message_size(size_t bytes) noexcept

Largest WebSocket message accepted.

include/nprpc/nprpc.hpp:1141

RpcBuilderHttp &max_websocket_requests_per_session_per_second(size_t rate, size_t burst = 0) noexcept

Limits calls per WebSocket session.

include/nprpc/nprpc.hpp:1129

RpcBuilderHttp &max_websocket_sessions_per_ip(size_t count) noexcept

Limits concurrent WebSocket sessions per client IP.

include/nprpc/nprpc.hpp:1112

RpcBuilderHttp &max_websocket_upgrades_per_ip_per_second(size_t rate, size_t burst = 0) noexcept

Limits new WebSocket connections per client IP.

include/nprpc/nprpc.hpp:1119

RpcBuilderHttp &max_webtransport_connects_per_ip_per_second(size_t rate, size_t burst = 0) noexcept

Limits new WebTransport sessions per client IP.

include/nprpc/nprpc.hpp:1190

RpcBuilderHttp &max_webtransport_message_size(size_t bytes) noexcept

Largest WebTransport message accepted.

include/nprpc/nprpc.hpp:1148

RpcBuilderHttp &max_webtransport_requests_per_session_per_second(size_t rate, size_t burst = 0) noexcept

Limits calls per WebTransport session.

include/nprpc/nprpc.hpp:1200

RpcBuilderHttp &max_webtransport_stream_opens_per_session_per_second(size_t rate, size_t burst = 0) noexcept

Limits streams opened per WebTransport session.

include/nprpc/nprpc.hpp:1210

RpcBuilderHttp &root_dir(std::string_view root_dir) noexcept

Directory served as static files, from an in-memory cache. Also where Rpc::produce_host_json() writes by default.

include/nprpc/nprpc.hpp:1043

RpcBuilderHttp &shm_egress_channel(std::string_view egress_channel, std::string_view ingress_channel) noexcept

Enable SHM channel offload via npquicrouter. Exchange HTTP/3 datagrams with npquicrouter through its shared-memory rings instead of loopback UDP.

The router creates the rings and recreates them each time it starts. The server follows: it checks once a second what the names point at and reattaches, logging a warning, so the two can start and restart in any order. Open QUIC connections survive a router restart.

egress_channel
Name used to open /nprpc_<name>_s2c — Http3Server writes GSO batches there instead of calling sendmsg directly. Must match "shm_egress_channel" in npquicrouter's config.json.
ingress_channel
Name used to open /nprpc_<name>_c2s — Http3Server reads incoming QUIC datagrams from there instead of recvmsg. Must match the route's "shm_ingress_channel" in npquicrouter's config.json.

include/nprpc/nprpc.hpp:972

RpcBuilderHttp &ssl(std::string_view cert_file, std::string_view key_file, std::string_view dhparams_file = "") noexcept

Serves HTTPS/WSS (and HTTP/3) with this certificate chain and key, both PEM. See also watch_certificates and reload_certificates.

include/nprpc/nprpc.hpp:992

RpcBuilderHttp &watch_certificates(std::chrono::seconds interval) noexcept

Poll the certificate and key files every interval and reload them in-process when they change on disk, so a certbot renewal is picked up without a restart. Zero (the default) disables polling; the certificate can still be reloaded on demand with reload_certificates(), which is the better fit when certbot can run a --deploy-hook.

include/nprpc/nprpc.hpp:1008

RpcBuilderHttp &watch_files() noexcept

Enable inotify-based cache invalidation for the HTTP root directory. Any file updated under root_dir() is immediately evicted from the cache so the next request serves the fresh version from disk. Useful during development (e.g. after npm run build). On non-Linux platforms this is a no-op; mtime polling handles staleness.

include/nprpc/nprpc.hpp:950

RpcBuilderHttp &websocket_compression(bool enabled = true) noexcept

Negotiates permessage-deflate on WebSocket connections.

include/nprpc/nprpc.hpp:1105

RpcBuilderHttp &with_page_handler(PageHandler handler) noexcept

Render pages in this process.

handler is consulted for every GET/HEAD/POST the RPC endpoint did not claim. Returning std::nullopt falls through to the server's normal routing, so static assets keep their zero-copy path.

include/nprpc/nprpc.hpp:1035