Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
Loading...
Searching...
No Matches
orbit::http Namespace Reference

Namespaces

namespace  h2
 
namespace  websocket
 

Classes

class  Client
 Asynchronous HTTP/1.1 and HTTP/2 client (libcurl's multi interface). More...
 
struct  ClientOptions
 
struct  ClientRequest
 An outbound HTTP request for Client. More...
 
struct  ClientResponse
 The result of a ClientRequest. More...
 
struct  ClientSendAwaiter
 co_await Client::send_async(...): resumes with the ClientResponse. More...
 
struct  Cookie
 Represents an HTTP cookie. More...
 
class  Http1Parser
 Incremental HTTP/1.1 request parser, built on llhttp (the parser Node.js uses). More...
 
class  HttpParser
 Utility class for parsing HTTP requests and related components. More...
 
struct  HttpRequest
 Represents an incoming HTTP request. More...
 
class  HttpResponse
 Represents an HTTP response to be sent to a client. More...
 
struct  MultipartFile
 Represents a file uploaded via multipart/form-data. More...
 
class  MultipartForm
 Represents parsed multipart/form-data content. More...
 
struct  MultipartLimits
 Limits for MultipartStreamParser. Exceeding one fails the parse (see MultipartStreamParser::failed()) and deletes the partial file. More...
 
class  MultipartStreamParser
 Streaming parser for multipart/form-data. More...
 
struct  MultipartUpload
 The result of receive_multipart(). More...
 
class  RequestContext
 Type-indexed, per-request storage: middleware that computes something for later middleware or the handler (the authenticated user, a tenant, a DB transaction, request timing) stashes it here instead of a header, a global, or a new fixed field on HttpRequest. More...
 
class  ResponseWriter
 Abstract interface for writing HTTP responses. More...
 
struct  UploadedFile
 A file part saved to disk by receive_multipart(). More...
 

Enumerations

enum class  HttpMethod {
  GET , POST , PUT , PATCH ,
  DELETE , OPTIONS , HEAD , UNKNOWN
}
 Represents standard HTTP methods. More...
 
enum class  HttpStatus {
  Continue = 100 , SwitchingProtocols = 101 , OK = 200 , Created = 201 ,
  Accepted = 202 , NoContent = 204 , PartialContent = 206 , MovedPermanently = 301 ,
  Found = 302 , SeeOther = 303 , NotModified = 304 , TemporaryRedirect = 307 ,
  PermanentRedirect = 308 , BadRequest = 400 , Unauthorized = 401 , Forbidden = 403 ,
  NotFound = 404 , MethodNotAllowed = 405 , NotAcceptable = 406 , RequestTimeout = 408 ,
  Conflict = 409 , Gone = 410 , LengthRequired = 411 , PreconditionFailed = 412 ,
  PayloadTooLarge = 413 , URITooLong = 414 , UnsupportedMediaType = 415 , RangeNotSatisfiable = 416 ,
  ExpectationFailed = 417 , UnprocessableEntity = 422 , UpgradeRequired = 426 , TooManyRequests = 429 ,
  RequestHeaderFieldsTooLarge = 431 , InternalServerError = 500 , NotImplemented = 501 , BadGateway = 502 ,
  ServiceUnavailable = 503 , GatewayTimeout = 504
}
 Standard HTTP status codes. More...
 

Functions

bool connection_option_present (std::string_view field_value, std::string_view option)
 Tests whether a Connection header field carries a given option.
 
bool percent_decode (std::string_view in, std::string &out, bool plus_as_space, bool for_path)
 Decodes XX escapes (RFC 3986 section 2.1).
 
bool parse_urlencoded (std::string_view data, std::unordered_map< std::string, std::string > &out)
 Decodes application/x-www-form-urlencoded data: a query string or a form body (WHATWG URL Standard section 5.1).
 
void parse_cookie_header (std::string_view cookie_header, std::unordered_map< std::string, std::string > &out)
 
template<typename T >
std::optional< T > parse_param (const std::string &text)
 
const char * reason_phrase (int status_code)
 Reason phrase for a status code. Codes without a registered phrase get a generic one for their class (e.g. "Client Error" for 4xx).
 
bool is_valid_header_name (std::string_view name)
 True if name is a valid header field name (an RFC 9110 token).
 
bool is_valid_header_value (std::string_view value)
 True if value can be written as a header field value: it contains no CR, LF or NUL, so it cannot start a new header line.
 
std::string format_http_date (std::time_t t)
 Formats t as an IMF-fixdate (RFC 9110 section 5.6.7), e.g. "Sun, 06 Nov 1994 08:49:37 GMT", independent of the C locale.
 
std::string_view http_date_now ()
 The current time as an IMF-fixdate, for the Date header.
 
std::string multipart_boundary (std::string_view content_type)
 Extracts the boundary parameter from a multipart Content-Type value, e.g. multipart/form-data; boundary="abc" (RFC 9110 section 5.6.6, RFC 2046 section 5.1.1).
 
void receive_multipart (const HttpRequest &req, std::shared_ptr< ResponseWriter > writer, std::function< void(MultipartUpload &)> on_complete, MultipartLimits limits={})
 Receives a multipart/form-data body, streaming file parts to disk.
 

Enumeration Type Documentation

◆ HttpMethod

enum class orbit::http::HttpMethod
strong

Represents standard HTTP methods.

Enumerator
GET 
POST 
PUT 
PATCH 
DELETE 
OPTIONS 
HEAD 
UNKNOWN 

◆ HttpStatus

enum class orbit::http::HttpStatus
strong

Standard HTTP status codes.

Enumerator
Continue 
SwitchingProtocols 
OK 
Created 
Accepted 
NoContent 
PartialContent 
MovedPermanently 
Found 
SeeOther 
NotModified 
TemporaryRedirect 
PermanentRedirect 
BadRequest 
Unauthorized 
Forbidden 
NotFound 
MethodNotAllowed 
NotAcceptable 
RequestTimeout 
Conflict 
Gone 
LengthRequired 
PreconditionFailed 
PayloadTooLarge 
URITooLong 
UnsupportedMediaType 
RangeNotSatisfiable 
ExpectationFailed 
UnprocessableEntity 
UpgradeRequired 
TooManyRequests 
RequestHeaderFieldsTooLarge 
InternalServerError 
NotImplemented 
BadGateway 
ServiceUnavailable 
GatewayTimeout 

Function Documentation

◆ connection_option_present()

bool orbit::http::connection_option_present ( std::string_view  field_value,
std::string_view  option 
)

Tests whether a Connection header field carries a given option.

The Connection header is a comma-separated list of case-insensitive tokens (RFC 9110 section 7.6.1), so a client may legitimately send Connection: keep-alive, TE or Connection: Close. Comparing the whole field value against a single token misses both.

Parameters
field_valueThe raw Connection header value.
optionThe option to look for, in lowercase (e.g. "close").
Returns
True if the option appears as one of the listed tokens.

◆ format_http_date()

std::string orbit::http::format_http_date ( std::time_t  t)

Formats t as an IMF-fixdate (RFC 9110 section 5.6.7), e.g. "Sun, 06 Nov 1994 08:49:37 GMT", independent of the C locale.

◆ http_date_now()

std::string_view orbit::http::http_date_now ( )

The current time as an IMF-fixdate, for the Date header.

Formatted at most once per second per thread and cached, so a response costs one clock read rather than a gmtime and a format. The view stays valid until the calling thread's next call.

◆ is_valid_header_name()

bool orbit::http::is_valid_header_name ( std::string_view  name)

True if name is a valid header field name (an RFC 9110 token).

◆ is_valid_header_value()

bool orbit::http::is_valid_header_value ( std::string_view  value)

True if value can be written as a header field value: it contains no CR, LF or NUL, so it cannot start a new header line.

◆ multipart_boundary()

std::string orbit::http::multipart_boundary ( std::string_view  content_type)

Extracts the boundary parameter from a multipart Content-Type value, e.g. multipart/form-data; boundary="abc" (RFC 9110 section 5.6.6, RFC 2046 section 5.1.1).

Returns
The boundary, unquoted; empty if absent or invalid (more than 70 characters, or an unterminated quoted string).

◆ parse_cookie_header()

void orbit::http::parse_cookie_header ( std::string_view  cookie_header,
std::unordered_map< std::string, std::string > &  out 
)

Adds the name=value pairs of a Cookie header to out (a later pair with the same name wins).

◆ parse_param()

template<typename T >
std::optional< T > orbit::http::parse_param ( const std::string &  text)

Parses text as T (see HttpRequest::param); null if it does not parse as a T with nothing left over.

◆ parse_urlencoded()

bool orbit::http::parse_urlencoded ( std::string_view  data,
std::unordered_map< std::string, std::string > &  out 
)

Decodes application/x-www-form-urlencoded data: a query string or a form body (WHATWG URL Standard section 5.1).

Pairs are separated by '&', names from values by the first '='; '+' is a space. A name without '=' gets an empty value, and a repeated name keeps its last value.

Returns
False on a malformed escape; out may then hold earlier pairs.

◆ percent_decode()

bool orbit::http::percent_decode ( std::string_view  in,
std::string &  out,
bool  plus_as_space,
bool  for_path 
)

Decodes XX escapes (RFC 3986 section 2.1).

Parameters
inThe encoded text.
outReceives the decoded text.
plus_as_spaceDecode '+' as a space (query strings / form data).
for_pathReject escapes that would change how a path is split or read: %2F ('/'), %5C ('\') and %00. A request that hides a path separator in an escape is refused rather than guessed at.
Returns
False on a malformed escape or a rejected character.

◆ reason_phrase()

const char * orbit::http::reason_phrase ( int  status_code)

Reason phrase for a status code. Codes without a registered phrase get a generic one for their class (e.g. "Client Error" for 4xx).

◆ receive_multipart()

void orbit::http::receive_multipart ( const HttpRequest &  req,
std::shared_ptr< ResponseWriter >  writer,
std::function< void(MultipartUpload &)>  on_complete,
MultipartLimits  limits = {} 
)

Receives a multipart/form-data body, streaming file parts to disk.

Use it from a stream route (Router::add_stream_route), so the body is not buffered in memory first. Fields are collected and files are written under limits.upload_dir as they arrive.

on_complete is called exactly once: at once if the Content-Type is not multipart/form-data with a boundary, otherwise when the body has ended. The result is a failure if a limit was exceeded or the body is malformed or truncated (no closing boundary); every file already saved is then deleted before the call.

app.group("/api", [](routing::Router& api) {
[](http::HttpRequest& req, std::shared_ptr<http::ResponseWriter> writer) {
http::receive_multipart(req, writer, [writer](http::MultipartUpload& upload) {
if (!upload.ok()) res.status(http::HttpStatus::BadRequest).send(upload.error);
else res.send("saved " + std::to_string(upload.files.size()) + " file(s)");
writer->send(std::move(res));
});
});
});
Represents an HTTP response to be sent to a client.
Definition HttpResponse.hpp:107
HttpResponse & status(HttpStatus code) &
Sets the HTTP status code of the response.
Definition HttpResponse.hpp:167
HttpResponse & send(const std::string &b) &
Sets the response body as plain text.
Definition HttpResponse.hpp:174
Manages routing of HTTP requests to their appropriate handlers.
Definition Router.hpp:46
void add_stream_route(http::HttpMethod method, const std::string &path, RouteHandler handler)
void receive_multipart(const HttpRequest &req, std::shared_ptr< ResponseWriter > writer, std::function< void(MultipartUpload &)> on_complete, MultipartLimits limits={})
Receives a multipart/form-data body, streaming file parts to disk.
Represents an incoming HTTP request.
Definition HttpRequest.hpp:54
The result of receive_multipart().
Definition MultipartUpload.hpp:24
std::vector< UploadedFile > files
Definition MultipartUpload.hpp:28
bool ok() const
Definition MultipartUpload.hpp:32
std::string error
Empty on success. On failure no files are left on disk.
Definition MultipartUpload.hpp:30