HTTP Server API — cpp-netlib v0.13.0

# 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 `char`s.

  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_buffer`s 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");
    }