HTTP Server API¶

General¶

cpp-netlib includes and implements and asynchronous HTTP server implementation that you can use and embed in your own applications. The HTTP Server implementation:

Cannot be copied. This means you may have to store instances of the HTTP Server in dynamic memory if you intend to use them as function parameters or pass them around in smart pointers of by reference.

Assume that requests made are independent of each other. None of the HTTP Server implementations support request pipelining (yet) so a single connection only deals with a single request.

The Handler instance is invoked asynchronously. This means the I/O thread used to handle network-related events are free to handle only the I/O related events. This enables the server to scale better as to the number of concurrent connections it can handle.

The Handler is able to schedule asynchronous actions on the thread pool associated with the server. This allows handlers to perform multiple asynchronous computations that later on perform writes to the connection.

The Handler is able to control the (asynchronous) writes to and reads from the HTTP connection. Because the connection is available to the Handler, that means it can write out chunks of data at a time or stream data through the connection continuously.

The Handler concept for the HTTP Server is described by the following table:

Legend:

H: The Handler type.
h: An instance of H.
Req: A type that models the Request Concept.
ConnectionPtr: A type that models the Connection Pointer Concept.
req: An instance of Req.
conn: An instance of ConncetionPtr.

Construct	Return Type	Description
`h(req, conn)`	`void`	Handle the request; conn is a shared pointer which exposes functions for writing to and reading from the connection.

The HTTP Server is meant to allow for better scalability in terms of the number of concurrent connections and for performing asynchronous actions within the handlers. The HTTP Server implementation is available from a single user-facing template named server. This template takes in a single template parameter which is the type of the Handler to be called once a request has been parsed from a connection.

An instance of Handler is taken as a reference to the constructor of the server instance.

Warning

The HTTP Server implementation does not perform any synchronization on the calls to the Handler invocation. This means if your handler contains or maintains internal state, you are responsible for implementing your own synchronization on accesses to the internal state of the Handler.

The general pattern for using the server template is shown below:

struct handler;
typedef boost::network::http::server<handler> http_server;

struct handler {
    void operator()(
        http_server::request const & req,
        http_server::connection_ptr connection
    ) {
        // handle the request here, and use the connection to
        // either read more data or write data out to the client
    }
};

API Documentation¶

The following sections assume that the following file has been included:

#include <boost/network/include/http/server.hpp>
#include <boost/network/utils/thread_pool.hpp>

And that the following typedef’s have been put in place:

struct handler_type;
typedef boost::network::http::server<handler_type> http_server;

struct handler_type {
    void operator()(http_server::request const & request,
                    http_server::connection_ptr connection) {
        // do something here
    }
};

Constructor¶

explicit http_server(options): Construct an HTTP server instance passing in a server_options<Tag, Handler> instance.

Server Options¶

template <class Tag, class Handler>

struct boost::network::http::server_options¶

The options supported by an HTTP Server’s constructor.

Public Functions

server_options(Handler &handler)¶: A single-argument constructor that takes a Handler, and sets all options to defaults.

server_options()¶: Disabled default constructor for the options class.

server_options(const server_options&)¶: Copy constructor for the options class.

server_options &operator=(const server_options&)¶: Copy assignment for the options class.

server_options(server_options&&)¶: Move constructor for the options class.

server_options &operator=(server_options&&)¶: Move assignment for the options class.

~server_options()¶: Destructor for the options class.

server_options &context(std::shared_ptr<ssl_context> v)¶: Sets the SSL context for the server. Default is nullptr.

server_options &io_service(std::shared_ptr<boost::asio::io_service> v)¶: Provides an Asio io_service for the server. Default is nullptr.

server_options &address(string_type v)¶: Sets the address to listen to for the server. Default is localhost.

server_options &port(string_type const &v)¶: Set the port to listen to for the server. Default is 80.

server_options &protocol_family(protocol_family_t v)¶: Set the protocol family for address resolving. Default is AF_UNSPEC.

server_options &reuse_address(bool v)¶: Set whether to reuse the address (SO_REUSE_ADDR). Default is false.

server_options &report_aborted(bool v)¶: Set whether to report aborted connections. Default is false.

server_options &non_blocking_io(bool v)¶: Set whether to use non-blocking IO. Default is true.

server_options &linger(bool v)¶: Set whether sockets linger (SO_LINGER). Default is true.

server_options &linger_timeout(size_t v)¶: Set the linger timeout. Default is 0.

server_options &receive_buffer_size(boost::asio::socket_base::receive_buffer_size v)¶: Set the socket receive buffer size. Unset by default.

server_options &send_buffer_size(boost::asio::socket_base::send_buffer_size v)¶: Set the send buffer size. Unset by default.

server_options &receive_low_watermark(boost::asio::socket_base::receive_low_watermark v)¶: Set the socket receive low watermark. Unset by default.

server_options &send_low_watermark(boost::asio::socket_base::send_low_watermark v)¶: Set the socket send low watermark. Unset by default.

server_options &thread_pool(std::shared_ptr<utils::thread_pool> v)¶: Set the thread-pool to use. Default is nullptr.

std::shared_ptr<boost::asio::io_service> io_service() const¶: Returns the provided Asio io_service.

string_type address() const¶: Returns the address to listen on.

string_type port() const¶: Returns the port to listen on.

protocol_family_t protocol_family() const¶: Returns the protocol family used for address resolving.

Handler &handler() const¶: Returns a reference to the provided handler.

bool reuse_address() const¶: Returns whether to reuse the address.

bool report_aborted() const¶: Returns whether to report aborted connections.

bool non_blocking_io() const¶: Returns whether to perform non-blocking IO.

bool linger() const¶: Returns whether to linger.

size_t linger_timeout() const¶: Returns the linger timeout.

boost::optional<boost::asio::socket_base::receive_buffer_size> receive_buffer_size() const¶: Returns the optional receive buffer size.

boost::optional<boost::asio::socket_base::send_buffer_size> send_buffer_size() const¶: Returns the optional send buffer size.

boost::optional<boost::asio::socket_base::receive_low_watermark> receive_low_watermark() const¶: Returns the optional receive low watermark.

boost::optional<boost::asio::socket_base::send_low_watermark> send_low_watermark() const¶: Returns the optional send low watermark.

std::shared_ptr<utils::thread_pool> thread_pool() const¶: Returns a pointer to the provided thread pool.

std::shared_ptr<ssl_context> context() const¶: Returns a pointer to the provided context.

void swap(server_options &other)¶: Swap implementation for the server options.

Public Members¶

template <class Handler>

struct boost::network::http::server¶

The main HTTP Server template implementing an asynchronous HTTP service.

Usage Example:

handler_type handler;
http_server::options options(handler);
options.thread_pool(
    std::make_shared<boost::network::utils::thread_pool>());
http_server server(options.address("localhost").port("8000"));

Inherits from boost::network::http::async_server_base< tags::http_server, Handler >

Public Types

typedef async_server_base<tags::http_server, Handler> server_base¶: A convenience typedef for the base of this type, implementing most of the internal details.

typedef server_options<tags::http_server, Handler> options¶: The options supported by the server.

typedef basic_request<tags::http_server> request¶: The request type for this server.

typedef string<tags::http_server>::type string_type¶

typedef boost::network::http::response_header<tags::http_server>::type response_header¶: The header type for this server.

typedef async_connection<tags::http_server, Handler> connection¶: The connection type for this server.

typedef std::shared_ptr<connection> connection_ptr¶: Defines the type for the connection pointer.

Public Functions

void run()¶

Listens to the correct port and runs the server’s event loop. This can be run on multiple threads, as in the example below:

Example: handler_type handler; http_server::options options(handler); options.thread_pool( std::make_shared<boost::network::utils::thread_pool>()); http_server server(options.address(“localhost”).port(“8000”));

// Run in three threads including the current thread. std::thread t1([&server] { server.run() }); std::thread t2([&server] { server.run() }); server.run(); t1.join(); t2.join();

void stop()¶: Stops the HTTP server acceptor and waits for all pending request handlers to finish.

void listen()¶: Explicitly listens on the configured host and port. May be called multiple times but only takes effect once.

const string_type &address() const¶: Returns the server socket address, either IPv4 or IPv6 depending on options.protocol_family()

const string_type &port() const¶: Returns the server socket port.

Connection Object¶

template <class Tag, class Handler>

struct boost::network::http::async_connection¶

Inherits from std::enable_shared_from_this< async_connection< Tag, Handler > >

Public Types

enum status_t¶

The set of known status codes for HTTP server responses.

Values:

ok = 200¶

created = 201¶

accepted = 202¶

no_content = 204¶

partial_content = 206¶

multiple_choices = 300¶

moved_permanently = 301¶

moved_temporarily = 302¶

not_modified = 304¶

bad_request = 400¶

unauthorized = 401¶

forbidden = 403¶

not_found = 404¶

not_supported = 405¶

not_acceptable = 406¶

request_timeout = 408¶

precondition_failed = 412¶

unsatisfiable_range = 416¶

internal_server_error = 500¶

not_implemented = 501¶

bad_gateway = 502¶

service_unavailable = 503¶

space_unavailable = 507¶

typedef std::shared_ptr<async_connection> connection_ptr¶: The connection pointer type.

typedef iterator_range<buffer_type::const_iterator> input_range¶: The input range taken by read callbacks. Typically a range of chars.

typedef std::function<void(input_range, boost::system::error_code, std::size_t, connection_ptr)> read_callback_function¶: Type required for read callbacks. Takes an input range, an error code, the number of bytes read, and a connection pointer.

Public Functions

template <class Range>

void set_headers(Range headers)¶

A call to set_headers takes a Range where each element models the Header concept. This Range will be linearized onto a buffer, which is then sent as soon as the first call to write or flush commences.

Pre

Headers have not been sent yet.

Post

Headers have been linearized to a buffer, and assumed to have been sent already when the function exits.

Parameters

headers: A range of Header objects to write out.

Exceptions

std::logic_error: when the precondition is violated.

void set_status(status_t new_status)¶

Sets the status of the response.

Pre

Headers have not been sent.

Post

Status is set on the response.

Parameters

new_status: The new status for this response.

Exceptions

std::logic_error: when the precondition is violated.

template <class Range>

void write(Range const &range)¶

Writes a given range of bytes out in order.

Even though this function looks synchronous, all it does is schedules asynchronous writes to the connection as soon as the range is serialised into appropriately sized buffers.

To use in your handler, it would look like:

Example:

connection->write("Hello, world!\n");
std::string sample = "I have a string!";
connection->write(sample);

Note that if you want to send custom status and headers, you MUST call set_status and/or set_headers before any calls to write.

Post

Status and headers have been sent, contents in the range have been serialized.

Parameters

range: A Boost.Range Single Pass Range of char’s for writing.

Exceptions

boost::system::system_error: The encountered underlying error in previous operations.

template <class Range, class Callback>

disable_if<is_base_of<boost::asio::const_buffer, typename Range::value_type>, void>::type write(Range const &range, Callback const &callback)¶

Writes a given range out and schedules a completion callback to be invoked when the writes are done. This works similarly to write above.

This overload is useful for writing streaming applications that send out chunks of data at a time, or for writing data that may not all fit in memory at once.

Post

Status and headers have been sent, contents in the range have been serialized and scheduled for writing through the socket.

Parameters

range: A Boost.Range Single Pass Range of char’s for writing.
callback: A function of type void(boost::system::error_code).

Exceptions

boost::system::system_error: The encountered underlying error in previous operations.

template <class ConstBufferSeq, class Callback>

enable_if<is_base_of<boost::asio::const_buffer, typename ConstBufferSeq::value_type>, void>::type write(ConstBufferSeq const &seq, Callback const &callback)¶

Writes a given set of boost::asio::const_buffers out using a more efficient implementation.

Parameters

seq: A sequence of boost::asio::const_buffer objects.
callback: A function of type void(boost::system::error_code).

void read(read_callback_function callback)¶

Schedules an asynchronous read from the connection. This is generally useful for handling POST/PUT or other requests that may have data coming in through the HTTP request’s body in a streaming manner.

To use this function, the caller needs to provide a callback that handles a chunk of data at a time. The signature of the function (lambda or actual function pointer) should be of the following form:

void(input_range, error_code, size_t, connection_ptr)

Parameters

callback: Invoked when the read has data ready for processing.

Exceptions

boost::system::system_error: The underlying error encountered in previous operations.

boost::network::stream_handler &socket()¶: Returns a reference to the underlying socket.

utils::thread_pool &thread_pool()¶: Returns a reference to the thread_pool running this handler.

bool has_error()¶: Returns whether or not there were errors encountered in previous operations.

optional<boost::system::system_error> error()¶: Returns the most recent error encountered.

Adding SSL support to the HTTP Server¶

In order to setup SSL support for an Asynchronous Server, it is best to start from a regular Asynchronous Server (see above). Once this server is setup, SSL can be enabled by adding a Boost.Asio.Ssl.Context to the options. The settings that can be used are defined in the link.

// Initialize SSL context
std::shared_ptr<asio::ssl::context> ctx =
    std::make_shared<asio::ssl::context>(asio::ssl::context::sslv23);
ctx->set_options(
            asio::ssl::context::default_workarounds
            | asio::ssl::context::no_sslv3
            | asio::ssl::context::single_dh_use);

// Set keys
ctx->set_password_callback(password_callback);
ctx->use_certificate_chain_file("server.pem");
ctx->use_private_key_file("server.pem", asio::ssl::context::pem);
ctx->use_tmp_dh_file("dh512.pem");

handler_type handler;
http_server::options options(handler);
options.thread_pool(std::make_shared<boost::network::utils::thread_pool>(2));
http_server server(options.address("127.0.0.1").port("8442").context(ctx));

std::string password_callback(std::size_t max_length, asio::ssl::context_base::password_purpose purpose) {
    return std::string("test");
}

HTTP Server API¶

General¶

API Documentation¶

Constructor¶

Server Options¶

Public Members¶

Connection Object¶

Adding SSL support to the HTTP Server¶

Table Of Contents

Previous topic

Next topic