RESTinio Documentation

RESTinio provides a zlib transform facility to handle HTTP content encoding (gzip, deflate, or identity). To use it, you create a body appender using restinio::transforms::zlib::body_appender, which wraps a response object and applies the selected compression algorithm to the data being appended.

Key components:

• rtz::make_gzip_compress_params(level): Creates parameters for gzip compression.
• rtz::make_deflate_compress_params(level): Creates parameters for deflate compression.
• rtz::make_identity_params(): Creates parameters for no compression (identity).
• rtz::body_appender(response, params): Returns an appender object used to write data to the response.
• ba.append(data): Appends a single block of data.
• ba.make_chunk(data) and ba.flush(): Used with restinio::chunked_output_t to stream data in chunks.
• ba.complete(): Finalizes the transformation and the response body.

You can chain multiple request handlers together by passing them as multiple arguments to the .request_handler() method when configuring the server. This allows you to implement a middleware-like pattern where one handler can decide whether to process a request or delegate it to the next handler in the chain.

To delegate to the next handler, a handler must return restinio::request_not_handled(). If a handler processes the request and wants to stop the chain, it should return restinio::request_accepted().

In the example below, the first handler (create_auth_handler) checks for authentication. If authentication fails, it returns a 401 Unauthorized response and restinio::request_accepted(). If authentication succeeds, it returns restinio::request_not_handled(), allowing the second handler (create_request_handler) to take over.

restinio::run(
    restinio::on_this_thread<traits_t>()
        .port( 8080 )
        .address( "localhost" )
        .request_handler(
            create_auth_handler(),
            create_request_handler() )
);

To run a RESTinio server, you must define server traits, instantiate the server with settings, and then use a runner to manage the execution lifecycle.

1. Define Traits: Create a struct inheriting from restinio::default_traits_t. You can specify a logger_t (e.g., restinio::shared_ostream_logger_t).
2. Instantiate Server: Use restinio::http_server_t< my_server_traits_t >. The constructor takes an io_context (e.g., restinio::own_io_context()) and a restinio::server_settings_t< my_server_traits_t > object.
3. Configure Settings: Use the fluent interface on server_settings_t to set the .port(), .address(), and .request_handler().
4. Run with a Pool Runner: To run the server on a thread pool, use restinio::on_pool_runner_t< server_t >. Pass the number of threads (e.g., std::thread::hardware_concurrency()) and the server instance to the runner, then call .start().
5. Stop the Server: The server can be stopped manually by calling runner.stop() and then runner.wait() to ensure a clean shutdown.

struct my_server_traits_t : public restinio::default_traits_t
{
	using logger_t = restinio::shared_ostream_logger_t;
};

using server_t = restinio::http_server_t< my_server_traits_t %>;

server_t server{
		restinio::own_io_context(),
		restinio::server_settings_t< my_server_traits_t >{}
			.port( 8080 )
			.address( "localhost" )
			.request_handler( handler )
};

// Run server on a separate thread_pool.
restinio::on_pool_runner_t< server_t > runner{
		std::thread::hardware_concurrency(),
		server
};
runner.start();

// To stop:
// runner.stop();
// runner.wait();

To enable TLS, you must provide an SSL context (compatible with asio::ssl::context) and register it with the server configuration.

1. Create an asio_ns::ssl::context (where asio_ns is restinio::asio_ns).
2. Configure certificates, private keys, and verification modes (e.g., restinio::asio::ssl::verify_peer).
3. Pass the context to the server using .tls_context(std::move(tls_context)).

Example configuration:

namespace asio_ns = restinio::asio_ns;
auto tls_context = asio_ns::ssl::context{ asio_ns::ssl::context::sslv23 };
tls_context.use_certificate_chain_file("server.cer");
tls_context.use_private_key_file("server.key", asio_ns::ssl::context::pem);
tls_context.set_verify_mode(asio_ns::ssl::verify_peer | asio_ns::ssl::verify_fail_if_no_peer_cert);

asio_ns::ssl::context tls_context{ asio_ns::ssl::context::sslv23 };
tls_context.set_options(
    asio_ns::ssl::context::default_workarounds
    | asio_ns::ssl::context::no_sslv2
    | asio_ns::ssl::context::single_dh_use );

tls_context.use_certificate_chain_file( certs_dir + "/server.cer" );
tls_context.use_private_key_file(
    certs_dir + "/server.key",
    asio_ns::ssl::context::pem );
tls_context.set_verify_mode(
    asio_ns::ssl::verify_peer
    | asio_ns::ssl::verify_fail_if_no_peer_cert );
tls_context.load_verify_file( certs_dir + "/ca.cer" );
tls_context.use_tmp_dh_file( certs_dir + "/dh2048.pem" );