Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
Loading...
Searching...
No Matches
Middlewares

Built-in middleware components for Orbit HTTP server. More...

Classes

struct  orbit::middleware::CorsOptions
 Options for configuring CORS (Cross-Origin Resource Sharing). More...
 
class  orbit::middleware::Csrf
 Cross-Site Request Forgery (CSRF) protection middleware. More...
 
class  orbit::middleware::DistributedRateLimiter
 Fixed-window rate limiter shared across instances through Redis. More...
 
class  orbit::middleware::Metrics
 Middleware for tracking HTTP request metrics. More...
 
struct  orbit::middleware::ProxyOptions
 Options for Proxy middleware. More...
 
struct  orbit::middleware::TargetNode
 A target node for the load balancer. More...
 
struct  orbit::middleware::LoadBalancerOptions
 Options for LoadBalancer middleware. More...
 
class  orbit::middleware::SessionManager
 Loads or creates the session for each request (req.session, req.session_id) and saves it when the response is sent. More...
 
struct  orbit::middleware::SchemaField
 Represents a field in a validation schema. More...
 

Enumerations

enum class  orbit::middleware::JsonType {
  orbit::middleware::JsonType::STRING , orbit::middleware::JsonType::NUMBER , orbit::middleware::JsonType::BOOLEAN , orbit::middleware::JsonType::OBJECT ,
  orbit::middleware::JsonType::ARRAY
}
 Enumeration of JSON data types. More...
 

Functions

routing::Middleware orbit::middleware::compress (CompressOptions options={})
 Returns a middleware that compresses response bodies with brotli, zstd or gzip, whichever the client accepts and the server prefers.
 
routing::Middleware orbit::middleware::cors (CorsOptions options=CorsOptions{})
 Returns a middleware that handles CORS.
 
auto orbit::middleware::csrf_protection (const std::string &cookie_name="csrf_token", const std::string &header_name="X-CSRF-Token")
 Helper to create a CSRF protection middleware handler.
 
routing::Middleware orbit::middleware::jwt_auth (JwtOptions options)
 Verifies an Authorization: Bearer JWT and stores its claims in req.user.
 
routing::Middleware orbit::middleware::jwt_auth (const std::string &secret_key)
 Shorthand for an HS256-only jwt_auth() with this secret.
 
routing::Middleware orbit::middleware::request_id (RequestIdOptions options={})
 Gives every request an ID (req.request_id) and echoes it in the response header, so a client report can be matched to server logs.
 
routing::Middleware orbit::middleware::tracing (TracingOptions options={})
 W3C Trace Context: continues the trace from an incoming traceparent header (or starts a new one), sets req.trace_id and req.span_id, and reports each request as a Span.
 
routing::Middleware orbit::middleware::access_log (AccessLogOptions options={})
 Logs one line per request when its response is sent: method, path, status, response bytes, duration, client IP, user agent, and the request/trace IDs when request_id() / tracing() are used. In JSON log format these are separate fields.
 
routing::Middleware orbit::middleware::proxy (ProxyOptions options)
 Returns a middleware that proxies requests to a single target URL (ip/hostname and port).
 
routing::Middleware orbit::middleware::proxy (const std::string &target_host, int target_port)
 Returns a middleware that proxies requests to a single target URL.
 
routing::Middleware orbit::middleware::load_balancer (LoadBalancerOptions options)
 Returns a middleware that load-balances requests across multiple upstream nodes.
 
routing::Middleware orbit::middleware::load_balancer (const std::vector< TargetNode > &nodes)
 Returns a middleware that load-balances requests across multiple upstream nodes.
 
routing::Middleware orbit::middleware::security_headers (SecurityHeadersOptions options={})
 Adds common security response headers (HSTS, nosniff, frame and referrer policies, COOP, optional CSP). They are defaults: a handler that sets the same header keeps its own value.
 
routing::Middleware orbit::middleware::static_files (const std::string &directory, StaticFilesOptions options={})
 Returns a middleware that serves static files from a directory.
 
routing::Middleware orbit::middleware::trusted_proxies (TrustedProxyOptions options)
 Sets req.client_ip from forwarding headers, but only for requests that arrive from a trusted proxy.
 
routing::Middleware orbit::middleware::validate_json (const std::vector< SchemaField > &schema)
 Returns a middleware that parses and validates a JSON request body.
 

Detailed Description

Built-in middleware components for Orbit HTTP server.

Enumeration Type Documentation

◆ JsonType

enum class orbit::middleware::JsonType
strong

Enumeration of JSON data types.

Enumerator
STRING 
NUMBER 
BOOLEAN 
OBJECT 
ARRAY 

Function Documentation

◆ access_log()

routing::Middleware orbit::middleware::access_log ( AccessLogOptions  options = {})

Logs one line per request when its response is sent: method, path, status, response bytes, duration, client IP, user agent, and the request/trace IDs when request_id() / tracing() are used. In JSON log format these are separate fields.

◆ compress()

routing::Middleware orbit::middleware::compress ( CompressOptions  options = {})

Returns a middleware that compresses response bodies with brotli, zstd or gzip, whichever the client accepts and the server prefers.

The coding is negotiated from Accept-Encoding (see negotiate_coding()). Every compressible response gets "Vary: Accept-Encoding", so shared caches keep the variants apart. Responses that already have a Content-Encoding, ask for Cache-Control: no-transform, are small, are already-compressed media, or are streamed are left alone. A strong ETag on a compressed body is made weak, since the bytes differ from the uncompressed variant.

Returns
routing::Middleware The compression middleware handler.

◆ cors()

routing::Middleware orbit::middleware::cors ( CorsOptions  options = CorsOptions{})

Returns a middleware that handles CORS.

Parameters
optionsThe CORS configuration options.
Returns
routing::Middleware The CORS middleware handler.

◆ csrf_protection()

auto orbit::middleware::csrf_protection ( const std::string &  cookie_name = "csrf_token",
const std::string &  header_name = "X-CSRF-Token" 
)
inline

Helper to create a CSRF protection middleware handler.

Parameters
cookie_nameThe name of the cookie to store the CSRF token.
header_nameThe name of the header expected in requests.
Returns
A middleware handler function.

◆ jwt_auth() [1/2]

routing::Middleware orbit::middleware::jwt_auth ( const std::string &  secret_key)

Shorthand for an HS256-only jwt_auth() with this secret.

◆ jwt_auth() [2/2]

routing::Middleware orbit::middleware::jwt_auth ( JwtOptions  options)

Verifies an Authorization: Bearer JWT and stores its claims in req.user.

Supported algorithms are HS256, RS256 and ES256. Every key has exactly one algorithm, and the token's "alg" must match the key it is verified with, so a token cannot switch algorithms (e.g. present an RSA public key as an HMAC secret, or use "none"). HMAC signatures are compared in constant time; exp and nbf are enforced when present (and exp is required when require_exp is set).

Exceptions
std::invalid_argumentif no key is configured or a key is unusable.

◆ load_balancer() [1/2]

routing::Middleware orbit::middleware::load_balancer ( const std::vector< TargetNode > &  nodes)

Returns a middleware that load-balances requests across multiple upstream nodes.

Parameters
nodesA vector of target nodes.
Returns
routing::Middleware The load balancer middleware handler.

◆ load_balancer() [2/2]

routing::Middleware orbit::middleware::load_balancer ( LoadBalancerOptions  options)

Returns a middleware that load-balances requests across multiple upstream nodes.

Currently implements a Round-Robin algorithm.

Parameters
optionsThe load balancer options.
Returns
routing::Middleware The load balancer middleware handler.

◆ proxy() [1/2]

routing::Middleware orbit::middleware::proxy ( const std::string &  target_host,
int  target_port 
)

Returns a middleware that proxies requests to a single target URL.

Parameters
target_hostThe target host.
target_portThe target port.
Returns
routing::Middleware The proxy middleware handler.

◆ proxy() [2/2]

routing::Middleware orbit::middleware::proxy ( ProxyOptions  options)

Returns a middleware that proxies requests to a single target URL (ip/hostname and port).

Parameters
optionsThe proxy configuration options.
Returns
routing::Middleware The proxy middleware handler.

◆ request_id()

routing::Middleware orbit::middleware::request_id ( RequestIdOptions  options = {})

Gives every request an ID (req.request_id) and echoes it in the response header, so a client report can be matched to server logs.

◆ security_headers()

routing::Middleware orbit::middleware::security_headers ( SecurityHeadersOptions  options = {})

Adds common security response headers (HSTS, nosniff, frame and referrer policies, COOP, optional CSP). They are defaults: a handler that sets the same header keeps its own value.

◆ static_files()

routing::Middleware orbit::middleware::static_files ( const std::string &  directory,
StaticFilesOptions  options = {} 
)

Returns a middleware that serves static files from a directory.

Handles GET and HEAD. If a file is found, it is served and the pipeline is stopped; otherwise the pipeline continues. Paths that resolve outside the directory (including through symlinks) get 403, and dotfiles are hidden unless StaticFilesOptions::serve_dotfiles is set.

Responses carry ETag, Last-Modified, Cache-Control and Accept-Ranges. If-None-Match / If-Modified-Since produce 304, and a single byte Range produces 206 (or 416 when it lies outside the file).

Parameters
directoryThe directory containing static files.
optionsIndex file, dotfile and caching behaviour.
Returns
routing::Middleware The static files middleware handler.

◆ tracing()

routing::Middleware orbit::middleware::tracing ( TracingOptions  options = {})

W3C Trace Context: continues the trace from an incoming traceparent header (or starts a new one), sets req.trace_id and req.span_id, and reports each request as a Span.

Pass "00-" + req.trace_id + "-" + req.span_id + "-01" as traceparent on outgoing calls to link them to this request.

◆ trusted_proxies()

routing::Middleware orbit::middleware::trusted_proxies ( TrustedProxyOptions  options)

Sets req.client_ip from forwarding headers, but only for requests that arrive from a trusted proxy.

The header is read right to left, skipping trusted proxies; the first address that is not one of them is the client. Requests from anyone else keep their socket address, so clients cannot spoof their IP. The socket address stays available as req.peer_ip.

Register it before middleware that uses client_ip (rate limiting, logging).

Exceptions
std::invalid_argumentif an entry in proxies is malformed.

◆ validate_json()

routing::Middleware orbit::middleware::validate_json ( const std::vector< SchemaField > &  schema)

Returns a middleware that parses and validates a JSON request body.

If valid, the parsed JSON is available in req.json_body. If invalid, it intercepts the request and responds with a 422 Unprocessable Entity.

Parameters
schemaThe schema to validate against.
Returns
routing::Middleware The validation middleware handler.