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

Abstract interface for writing HTTP responses. More...

#include <ResponseWriter.hpp>

Inheritance diagram for orbit::http::ResponseWriter:

Public Types

using Interceptor = std::function< void(HttpResponse &)>
 
using ErrorSink = std::function< void(std::exception_ptr, std::shared_ptr< ResponseWriter >)>
 Receives an exception that escaped asynchronous handler code, such as a coroutine handler that threw after a co_await.
 

Public Member Functions

virtual ~ResponseWriter ()=default
 
virtual void add_interceptor (Interceptor interceptor)=0
 Adds an interceptor to modify the response before it is sent.
 
virtual void set_header (const std::string &key, const std::string &value)=0
 Adds a default header that will be included in the final response.
 
virtual network::Proactor & proactor ()=0
 Gets the underlying Proactor to dispatch async operations.
 
virtual concurrency::ThreadPool & thread_pool ()=0
 Gets the thread pool to offload blocking tasks.
 
virtual void send (HttpResponse &&response)=0
 Sends a complete HTTP response.
 
virtual void send_headers (HttpResponse &response)=0
 Sends only the HTTP headers.
 
virtual void write_chunk (std::string_view chunk)=0
 Streams a chunk of data (for Chunked Transfer Encoding).
 
virtual void end ()=0
 Ends a chunked response stream.
 
virtual void send_sse_event (std::string_view data, std::string_view event="", std::string_view id="")=0
 Sends a Server-Sent Events (SSE) message.
 
virtual void upgrade_to_raw_stream (std::function< void(std::string_view)> on_data, std::function< void()> on_close)=0
 Upgrades the connection to a raw bi-directional byte stream.
 
virtual void read_body_stream (std::function< void(std::string_view)> on_data, std::function< void()> on_end)=0
 Asynchronously streams the incoming HTTP request body.
 
bool has_responded () const
 True once anything of a response to the current request has been sent: a full response, its headers, a chunk or an event.
 
void set_error_sink (ErrorSink sink)
 
uint64_t request_generation () const
 
bool is_open () const
 False once the client can no longer receive anything: the connection (HTTP/1.1) or stream (HTTP/2, HTTP/3) closed, because the client left, a timeout fired or the server shut down.
 
void on_close (std::function< void()> callback)
 Runs callback once when the writer closes (see is_open()), or right away if it already has.
 

Static Public Member Functions

static void report_async_exception (const std::shared_ptr< ResponseWriter > &writer, uint64_t generation, std::exception_ptr error) noexcept
 Reports an exception from asynchronous handler code.
 

Protected Member Functions

void mark_responded ()
 Implementations call this whenever they write part of a response.
 
void reset_responded ()
 
void mark_closed () noexcept
 

Private Attributes

std::atomic< bool > responded_ {false}
 
std::atomic< uint64_t > generation_ {0}
 
std::mutex error_sink_mutex_
 
ErrorSink error_sink_
 
std::atomic< bool > closed_ {false}
 
std::mutex close_mutex_
 
std::vector< std::function< void()> > close_callbacks_
 

Detailed Description

Abstract interface for writing HTTP responses.

This is used by middlewares and route handlers to write data back to the client.

Member Typedef Documentation

◆ ErrorSink

using orbit::http::ResponseWriter::ErrorSink = std::function<void(std::exception_ptr, std::shared_ptr<ResponseWriter>)>

Receives an exception that escaped asynchronous handler code, such as a coroutine handler that threw after a co_await.

The router installs one for each request; it runs the same error handling as for a handler that throws synchronously.

◆ Interceptor

Constructor & Destructor Documentation

◆ ~ResponseWriter()

virtual orbit::http::ResponseWriter::~ResponseWriter ( )
virtualdefault

Member Function Documentation

◆ add_interceptor()

virtual void orbit::http::ResponseWriter::add_interceptor ( Interceptor  interceptor)
pure virtual

Adds an interceptor to modify the response before it is sent.

Parameters
interceptorThe interceptor callback.

Implemented in orbit::http::h2::Http2ResponseWriter, and orbit::server::Http3ResponseWriter.

◆ end()

virtual void orbit::http::ResponseWriter::end ( )
pure virtual

◆ has_responded()

bool orbit::http::ResponseWriter::has_responded ( ) const
inline

True once anything of a response to the current request has been sent: a full response, its headers, a chunk or an event.

The router reads it after an error handler fails, to answer the request with a 500 only if nothing has been sent yet.

◆ is_open()

bool orbit::http::ResponseWriter::is_open ( ) const
inline

False once the client can no longer receive anything: the connection (HTTP/1.1) or stream (HTTP/2, HTTP/3) closed, because the client left, a timeout fired or the server shut down.

Writes after that are dropped. A long-lived writer (an SSE subscriber, a chunked stream) can check it, or use on_close(), to stop producing.

◆ mark_closed()

void orbit::http::ResponseWriter::mark_closed ( )
protectednoexcept

Implementations call this when the client is gone for good. Runs the on_close() callbacks the first time; later calls do nothing.

◆ mark_responded()

void orbit::http::ResponseWriter::mark_responded ( )
inlineprotected

Implementations call this whenever they write part of a response.

◆ on_close()

void orbit::http::ResponseWriter::on_close ( std::function< void()>  callback)

Runs callback once when the writer closes (see is_open()), or right away if it already has.

Typically used to drop a subscriber from a hub. It runs on a server thread, so keep it short and do not block. Every registered callback runs; one that throws is logged.

◆ proactor()

virtual network::Proactor & orbit::http::ResponseWriter::proactor ( )
pure virtual

Gets the underlying Proactor to dispatch async operations.

Returns
A reference to the network::Proactor.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ read_body_stream()

virtual void orbit::http::ResponseWriter::read_body_stream ( std::function< void(std::string_view)>  on_data,
std::function< void()>  on_end 
)
pure virtual

Asynchronously streams the incoming HTTP request body.

Parameters
on_dataCallback invoked when a body chunk is received.
on_endCallback invoked when the entire body has been read.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ report_async_exception()

static void orbit::http::ResponseWriter::report_async_exception ( const std::shared_ptr< ResponseWriter > &  writer,
uint64_t  generation,
std::exception_ptr  error 
)
staticnoexcept

Reports an exception from asynchronous handler code.

Goes through the request's error sink (the router's on_error handler, else a 500). The exception is only logged if part of the response has already been sent, or if generation is no longer the writer's current request (the connection moved on to another). Never throws.

◆ request_generation()

uint64_t orbit::http::ResponseWriter::request_generation ( ) const
inline

Identifies the request this writer is answering. A writer reused across requests (an HTTP/1.1 keep-alive connection) advances it with each request, so late failures of an earlier one can be told apart.

◆ reset_responded()

void orbit::http::ResponseWriter::reset_responded ( )
inlineprotected

For writers reused across requests (an HTTP/1.1 keep-alive connection), at the start of each request.

◆ send()

virtual void orbit::http::ResponseWriter::send ( HttpResponse &&  response)
pure virtual

Sends a complete HTTP response.

Takes ownership of any file descriptors managed by the response.

Parameters
responseThe HttpResponse to send.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ send_headers()

virtual void orbit::http::ResponseWriter::send_headers ( HttpResponse &  response)
pure virtual

Sends only the HTTP headers.

Useful for streaming bodies or Server-Sent Events.

Parameters
responseThe HttpResponse containing the headers to send.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ send_sse_event()

virtual void orbit::http::ResponseWriter::send_sse_event ( std::string_view  data,
std::string_view  event = "",
std::string_view  id = "" 
)
pure virtual

Sends a Server-Sent Events (SSE) message.

Parameters
dataThe event data payload.
eventThe event type/name (optional).
idThe event ID (optional).

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ set_error_sink()

void orbit::http::ResponseWriter::set_error_sink ( ErrorSink  sink)
inline

◆ set_header()

virtual void orbit::http::ResponseWriter::set_header ( const std::string &  key,
const std::string &  value 
)
pure virtual

Adds a default header that will be included in the final response.

Parameters
keyThe header name.
valueThe header value.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ thread_pool()

virtual concurrency::ThreadPool & orbit::http::ResponseWriter::thread_pool ( )
pure virtual

Gets the thread pool to offload blocking tasks.

Returns
A reference to the concurrency::ThreadPool.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ upgrade_to_raw_stream()

virtual void orbit::http::ResponseWriter::upgrade_to_raw_stream ( std::function< void(std::string_view)>  on_data,
std::function< void()>  on_close 
)
pure virtual

Upgrades the connection to a raw bi-directional byte stream.

Parameters
on_dataCallback invoked when data is received.
on_closeCallback invoked when the stream is closed.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

◆ write_chunk()

virtual void orbit::http::ResponseWriter::write_chunk ( std::string_view  chunk)
pure virtual

Streams a chunk of data (for Chunked Transfer Encoding).

Parameters
chunkThe data chunk to write.

Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.

Member Data Documentation

◆ close_callbacks_

std::vector<std::function<void()> > orbit::http::ResponseWriter::close_callbacks_
private

◆ close_mutex_

std::mutex orbit::http::ResponseWriter::close_mutex_
private

◆ closed_

std::atomic<bool> orbit::http::ResponseWriter::closed_ {false}
private

◆ error_sink_

ErrorSink orbit::http::ResponseWriter::error_sink_
private

◆ error_sink_mutex_

std::mutex orbit::http::ResponseWriter::error_sink_mutex_
private

◆ generation_

std::atomic<uint64_t> orbit::http::ResponseWriter::generation_ {0}
private

◆ responded_

std::atomic<bool> orbit::http::ResponseWriter::responded_ {false}
private

The documentation for this class was generated from the following file: