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)
Prefer RpcBuilderBase::with_http.
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