|
Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
|
Abstract interface for writing HTTP responses. More...
#include <ResponseWriter.hpp>

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_ |
Abstract interface for writing HTTP responses.
This is used by middlewares and route handlers to write data back to the client.
| 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.
| using orbit::http::ResponseWriter::Interceptor = std::function<void(HttpResponse&)> |
|
virtualdefault |
|
pure virtual |
Adds an interceptor to modify the response before it is sent.
| interceptor | The interceptor callback. |
Implemented in orbit::http::h2::Http2ResponseWriter, and orbit::server::Http3ResponseWriter.
|
pure virtual |
Ends a chunked response stream.
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
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.
|
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.
|
protectednoexcept |
Implementations call this when the client is gone for good. Runs the on_close() callbacks the first time; later calls do nothing.
|
inlineprotected |
Implementations call this whenever they write part of a response.
| 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.
|
pure virtual |
Gets the underlying Proactor to dispatch async operations.
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
pure virtual |
Asynchronously streams the incoming HTTP request body.
| on_data | Callback invoked when a body chunk is received. |
| on_end | Callback invoked when the entire body has been read. |
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
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.
|
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.
|
inlineprotected |
For writers reused across requests (an HTTP/1.1 keep-alive connection), at the start of each request.
|
pure virtual |
Sends a complete HTTP response.
Takes ownership of any file descriptors managed by the response.
| response | The HttpResponse to send. |
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
pure virtual |
Sends only the HTTP headers.
Useful for streaming bodies or Server-Sent Events.
| response | The HttpResponse containing the headers to send. |
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
pure virtual |
Sends a Server-Sent Events (SSE) message.
| data | The event data payload. |
| event | The event type/name (optional). |
| id | The event ID (optional). |
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
inline |
|
pure virtual |
Adds a default header that will be included in the final response.
| key | The header name. |
| value | The header value. |
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
pure virtual |
Gets the thread pool to offload blocking tasks.
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
pure virtual |
Upgrades the connection to a raw bi-directional byte stream.
| on_data | Callback invoked when data is received. |
| on_close | Callback invoked when the stream is closed. |
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
pure virtual |
Streams a chunk of data (for Chunked Transfer Encoding).
| chunk | The data chunk to write. |
Implemented in orbit::http::h2::Http2ResponseWriter, orbit::server::Connection, and orbit::server::Http3ResponseWriter.
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |