# The libhttpserver reference manual
[](https://ci.appveyor.com/project/etr/libhttpserver/branch/master)
[](https://codecov.io/gh/etr/libhttpserver)
[](https://www.codacy.com/gh/etr/libhttpserver/dashboard?utm_source=github.com&utm_medium=referral&utm_content=etr/libhttpserver&utm_campaign=Badge_Grade)
[](https://gitter.im/libhttpserver/community)
[](https://ko-fi.com/F1F5HY8B)
## Tl;dr
libhttpserver is a C++ library for building high performance RESTful web servers.
libhttpserver is built upon [libmicrohttpd](https://www.gnu.org/software/libmicrohttpd/) to provide a simple API for developers to create HTTP services in C++.
**Features:**
- HTTP 1.1 compatible request parser
- RESTful oriented interface
- Flexible handler API
- Cross-platform compatible
- Implementation is HTTP 1.1 compliant
- Multiple threading models
- Support for IPv6
- Support for SHOUTcast
- Support for incremental processing of POST data (optional)
- Support for basic and digest authentication (optional)
- Support for TLS (requires libgnutls, optional)
## Table of Contents
* [Introduction](#introduction)
* [Requirements](#requirements)
* [Building](#building)
* [Getting Started](#getting-started)
* [Structures and classes type definition](#structures-and-classes-type-definition)
* [Create and work with a webserver](#create-and-work-with-a-webserver)
* [The resource object](#the-resource-object)
* [Registering resources](#registering-resources)
* [Parsing requests](#parsing-requests)
* [Building responses to requests](#building-responses-to-requests)
* [IP Blacklisting and Whitelisting](#ip-blacklisting-and-whitelisting)
* [Authentication](#authentication)
* [HTTP Utils](#http-utils)
* [Other Examples](#other-examples)
#### Community
* [Code of Conduct (on a separate page)](https://github.com/etr/libhttpserver/blob/master/CODE_OF_CONDUCT.md)
* [Contributing (on a separate page)](https://github.com/etr/libhttpserver/blob/master/CONTRIBUTING.md)
#### Appendices
* [Copying statement](#copying)
* [GNU-LGPL](#GNU-lesser-general-public-license): The GNU Lesser General Public License says how you can copy and share almost all of libhttpserver.
* [GNU-FDL](#GNU-free-documentation-license): The GNU Free Documentation License says how you can copy and share the documentation of libhttpserver.
## Introduction
libhttpserver is meant to constitute an easy system to build HTTP servers with REST fashion.
libhttpserver is based on [libmicrohttpd](https://www.gnu.org/software/libmicrohttpd/) and, like this, it is a daemon library (parts of this documentation are, in fact, matching those of the wrapped library).
The mission of this library is to support all possible HTTP features directly and with a simple semantic allowing then the user to concentrate only on his application and not on HTTP request handling details.
The library is supposed to work transparently for the client Implementing the business logic and using the library itself to realize an interface.
If the user wants it must be able to change every behavior of the library itself through the registration of callbacks.
libhttpserver is able to decode certain body format a and automatically format them in object oriented fashion. This is true for query arguments and for *POST* and *PUT* requests bodies if *application/x-www-form-urlencoded* or *multipart/form-data* header are passed.
All functions are guaranteed to be completely reentrant and thread-safe (unless differently specified).
Additionally, clients can specify resource limits on the overall number of connections, number of connections per IP address and memory used per connection to avoid resource exhaustion.
[Back to TOC](#table-of-contents)
## Requirements
libhttpserver can be used without any dependencies aside from libmicrohttpd.
The minimum versions required are:
* g++ >= 5.5.0 or clang-3.6
* libmicrohttpd >= 0.9.64
* [Optionally]: for TLS (HTTPS) support, you'll need [libgnutls](http://www.gnutls.org/).
* [Optionally]: to compile the code-reference, you'll need [doxygen](http://www.doxygen.nl/).
Additionally, for MinGW on windows you will need:
* libwinpthread (For MinGW-w64, if you use thread model posix then you have this)
For versions before 0.18.0, on MinGW, you will need:
* libgnurx >= 2.5.1
Furthermore, the testcases use [libcurl](http://curl.haxx.se/libcurl/) but you don't need it to compile the library.
Please refer to the readme file for your particular distribution if there is one for important notes.
[Back to TOC](#table-of-contents)
## Building
libhttpserver uses the standard system where the usual build process involves running
> ./bootstrap
> mkdir build
> cd build
> \.\./configure
> make
> make install # (optionally to install on the system)
[Back to TOC](#table-of-contents)
### Optional parameters to configure script
A complete list of parameters can be obtained running 'configure --help'.
Here are listed the libhttpserver specific options (the canonical configure options are also supported).
* _\-\-enable-same-directory-build:_ enable to compile in the same directory. This is heavily discouraged. (def=no)
* _\-\-enable-debug:_ enable debug data generation. (def=no)
* _\-\-disable-doxygen-doc:_ don't generate any doxygen documentation. Doxygen is automatically invoked if present on the system. Automatically disabled otherwise.
* _\-\-enable-fastopen:_ enable use of TCP_FASTOPEN (def=yes)
* _\-\-enable-static:_ enable use static linking (def=yes)
[Back to TOC](#table-of-contents)
## Getting Started
The most basic example of creating a server and handling a requests for the path `/hello`:
#include
using namespace httpserver;
class hello_world_resource : public http_resource {
public:
const std::shared_ptr render(const http_request&) {
return std::shared_ptr(new string_response("Hello, World!"));
}
};
int main(int argc, char** argv) {
webserver ws = create_webserver(8080);
hello_world_resource hwr;
ws.register_resource("/hello", &hwr);
ws.start(true);
return 0;
}
To test the above example, you could run the following command from a terminal:
curl -XGET -v http://localhost:8080/hello
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/minimal_hello_world.cpp).
[Back to TOC](#table-of-contents)
## Structures and classes type definition
* _webserver:_ Represents the daemon listening on a socket for HTTP traffic.
* _create_webserver:_ Builder class to support the creation of a webserver.
* _http_resource:_ Represents the resource associated with a specific http endpoint.
* _http_request:_ Represents the request received by the resource that process it.
* _http_response:_ Represents the response sent by the server once the resource finished its work.
* _string_response:_ A simple string response.
* _file_response:_ A response getting content from a file.
* _basic_auth_fail_response:_ A failure in basic authentication.
* _digest_auth_fail_response:_ A failure in digest authentication.
* _deferred_response:_ A response getting content from a callback.
[Back to TOC](#table-of-contents)
## Create and work with a webserver
As you can see from the example above, creating a webserver with standard configuration is quite simple:
webserver ws = create_webserver(8080);
The `create_webserver` class is a supporting _builder_ class that eases the building of a webserver through chained syntax.
### Basic Startup Options
In this section we will explore other basic options that you can use when configuring your server. More advanced options (custom callbacks, https support, etc...) will be discussed separately.
* _.port(**int** port):_ The port at which the server will listen. This can also be passed to the consturctor of `create_webserver`. E.g. `create_webserver(8080)`.
* _.max_connections(**int** max_conns):_ Maximum number of concurrent connections to accept. The default is `FD_SETSIZE - 4` (the maximum number of file descriptors supported by `select` minus four for `stdin`, `stdout`, `stderr` and the server socket). In other words, the default is as large as possible. Note that if you set a low connection limit, you can easily get into trouble with browsers doing request pipelining.
For example, if your connection limit is 1, a browser may open a first connection to access your index.html file, keep it open but use a second connection to retrieve CSS files, images and the like. In fact, modern browsers are typically by default configured for up to 15 parallel connections to a single server. If this happens, the library will refuse to even accept the second connection until the first connection is closed which does not happen until timeout. As a result, the browser will fail to render the page and seem to hang. If you expect your server to operate close to the connection limit, you should first consider using a lower timeout value and also possibly add a Connection: close header to your response to ensure that request pipelining is not used and connections are closed immediately after the request has completed.
* _.content_size_limit(**size_t** size_limit):_ Sets the maximum size of the content that a client can send over in a single block. The default is `-1 = unlimited`.
* _.connection_timeout(**int** timeout):_ Determines after how many seconds of inactivity a connection should be timed out automatically. The default timeout is `180 seconds`.
* _.memory_limit(**int** memory_limit):_ Maximum memory size per connection (followed by a `size_t`). The default is 32 kB (32*1024 bytes). Values above 128k are unlikely to result in much benefit, as half of the memory will be typically used for IO, and TCP buffers are unlikely to support window sizes above 64k on most systems.
* _.per_IP_connection_limit(**int** connection_limit):_ Limit on the number of (concurrent) connections made to the server from the same IP address. Can be used to prevent one IP from taking over all of the allowed connections. If the same IP tries to establish more than the specified number of connections, they will be immediately rejected. The default is `0`, which means no limit on the number of connections from the same IP address.
* _.bind_socket(**int** socket_fd):_ Listen socket to use. Pass a listen socket for the daemon to use (systemd-style). If this option is used, the daemon will not open its own listen socket(s). The argument passed must be of type "int" and refer to an existing socket that has been bound to a port and is listening.
* _.max_thread_stack_size(**int** stack_size):_ Maximum stack size for threads created by the library. Not specifying this option or using a value of zero means using the system default (which is likely to differ based on your platform). Default is `0 (system default)`.
* _.use_ipv6() and .no_ipv6():_ Enable or disable the IPv6 protocol support (by default, libhttpserver will just support IPv4). If you specify this and the local platform does not support it, starting up the server will throw an exception. `off` by default.
* _.use_dual_stack() and .no_dual_stack():_ Enable or disable the support for both IPv6 and IPv4 protocols at the same time (by default, libhttpserver will just support IPv4). If you specify this and the local platform does not support it, starting up the server will throw an exception. Note that this will mean that IPv4 addresses are returned in the IPv6-mapped format (the structsockaddrin6 format will be used for IPv4 and IPv6). `off` by default.
* _.pedantic() and .no_pedantic():_ Enables pedantic checks about the protocol (as opposed to as tolerant as possible). Specifically, at the moment, this flag causes the library to reject HTTP 1.1 connections without a `Host` header. This is required by the standard, but of course in violation of the be as liberal as possible in what you accept norm. It is recommended to turn this **off** if you are testing clients against the library, and **on** in production. `off` by default.
* _.debug() and .no_debug():_ Enables debug messages from the library. `off` by default.
* _.regex_checking() and .no_regex_checking():_ Enables pattern matching for endpoints. Read more [here](#registering-resources). `on` by default.
* _.post_process() and .no_post_process():_ Enables/Disables the library to automatically parse the body of the http request as arguments if in querystring format. Read more [here](#parsing-requests). `on` by default.
* _.put_processed_data_to_content() and .no_put_processed_data_to_content():_ Enables/Disables the library to copy parsed body data to the content or to only store it in the arguments map. `on` by default.
* _.file_upload_target(**file_upload_target_T** file_upload_target):_ Controls, how the library stores uploaded files. Default value is `FILE_UPLOAD_MEMORY_ONLY`.
* `FILE_UPLOAD_MEMORY_ONLY`: The content of the file is only stored in memory. Depending on `put_processed_data_to_content` only as part of the arguments map or additionally in the content.
* `FILE_UPLOAD_DISK_ONLY`: The content of the file is stored only in the file system. The path is created from `file_upload_dir` and either a random name (if `generate_random_filename_on_upload` is true) or the actually uploaded file name.
* `FILE_UPLOAD_MEMORY_AND_DISK`: The content of the file is stored in memory and on the file system.
* _.file_upload_dir(**const std::string&** file_upload_dir):_ Specifies the directory to store all uploaded files. Default value is `/tmp`.
* _.generate_random_filename_on_upload() and .no_generate_random_filename_on_upload():_ Enables/Disables the library to generate a unique and unused filename to store the uploaded file to. Otherwise the actually uploaded file name is used. `off` by default.
* _.deferred()_ and _.no_deferred():_ Enables/Disables the ability for the server to suspend and resume connections. Simply put, it enables/disables the ability to use `deferred_response`. Read more [here](#building-responses-to-requests). `on` by default.
* _.single_resource() and .no_single_resource:_ Sets or unsets the server in single resource mode. This limits all endpoints to be served from a single resource. The resultant is that the webserver will process the request matching to the endpoint skipping any complex semantic. Because of this, the option is incompatible with `regex_checking` and requires the resource to be registered against an empty endpoint or the root endpoint (`"/"`). The resource will also have to be registered as family. (For more information on resource registration, read more [here](#registering-resources)). `off` by default.
### Threading Models
* _.start_method(**const http::http_utils::start_method_T&** start_method):_ libhttpserver can operate with two different threading models that can be selected through this method. Default value is `INTERNAL_SELECT`.
* `http::http_utils::INTERNAL_SELECT`: In this mode, libhttpserver uses only a single thread to handle listening on the port and processing of requests. This mode is preferable if spawning a thread for each connection would be costly. If the HTTP server is able to quickly produce responses without much computational overhead for each connection, this mode can be a great choice. Note that libhttpserver will still start a single thread for itself -- this way, the main program can continue with its operations after calling the start method. Naturally, if the HTTP server needs to interact with shared state in the main application, synchronization will be required. If such synchronization in code providing a response results in blocking, all HTTP server operations on all connections will stall. This mode is a bad choice if response data cannot always be provided instantly. The reason is that the code generating responses should not block (since that would block all other connections) and on the other hand, if response data is not available immediately, libhttpserver will start to busy wait on it. If you need to scale along the number of concurrent connection and scale on multiple thread you can specify a value for `max_threads` (see below) thus enabling a thread pool - this is different from `THREAD_PER_CONNECTION` below where a new thread is spawned for each connection.
* `http::http_utils::THREAD_PER_CONNECTION`: In this mode, libhttpserver starts one thread to listen on the port for new connections and then spawns a new thread to handle each connection. This mode is great if the HTTP server has hardly any state that is shared between connections (no synchronization issues!) and may need to perform blocking operations (such as extensive IO or running of code) to handle an individual connection.
* _.max_threads(**int** max_threads):_ A thread pool can be combined with the `INTERNAL_SELECT` mode to benefit implementations that require scalability. As said before, by default this mode only uses a single thread. When combined with the thread pool option, it is possible to handle multiple connections with multiple threads. Any value greater than one for this option will activate the use of the thread pool. In contrast to the `THREAD_PER_CONNECTION` mode (where each thread handles one and only one connection), threads in the pool can handle a large number of concurrent connections. Using `INTERNAL_SELECT` in combination with a thread pool is typically the most scalable (but also hardest to debug) mode of operation for libhttpserver. Default value is `1`. This option is incompatible with `THREAD_PER_CONNECTION`.
### Custom defaulted error messages
libhttpserver allows to override internal error retrieving functions to provide custom messages to the HTTP client. There are only 3 cases in which implementing logic (an http_resource) cannot be invoked: (1) a not found resource, where the library is not being able to match the URL requested by the client to any implementing http_resource object; (2) a not allowed method, when the HTTP client is requesting a method explicitly marked as not allowed (more info [here](#allowing-and-disallowing-methods-on-a-resource)) by the implementation; (3) an exception being thrown.
In all these 3 cases libhttpserver would provide a standard HTTP response to the client with the correct error code; respectively a `404`, a `405` and a `500`. The library allows its user to specify custom callbacks that will be called to replace the default behavior.
* _.not_found_resource(**const shared_ptr(*render_ptr)(const http_request&)** resource):_ Specifies a function to handle a request when no matching registered endpoint exist for the URL requested by the client.
* _.method_not_allowed_resource(**const shared_ptr(*render_ptr)(const http_request&)** resource):_ Specifies a function to handle a request that is asking for a method marked as not allowed on the matching http_resource.
* _.internal_error_resource(**const shared_ptr(*render_ptr)(const http_request&)** resource):_ Specifies a function to handle a request that is causing an uncaught exception during its execution. **REMEMBER:** is this callback is causing an exception itself, the standard default response from libhttpserver will be reported to the HTTP client.
#### Example of custom errors:
#include
using namespace httpserver;
const std::shared_ptr not_found_custom(const http_request& req) {
return std::shared_ptr(new string_response("Not found custom", 404, "text/plain"));
}
const std::shared_ptr not_allowed_custom(const http_request& req) {
return std::shared_ptr(new string_response("Not allowed custom", 405, "text/plain"));
}
class hello_world_resource : public http_resource {
public:
const std::shared_ptr render(const http_request&) {
return std::shared_ptr(new string_response("Hello, World!"));
}
};
int main(int argc, char** argv) {
webserver ws = create_webserver(8080)
.not_found_resource(not_found_custom)
.method_not_allowed_resource(not_allowed_custom);
hello_world_resource hwr;
hwr.disallow_all();
hwr.set_allowing("GET", true);
ws.register_resource("/hello", &hwr);
ws.start(true);
return 0;
}
To test the above example, you can run the following command from a terminal:
curl -XGET -v http://localhost:8080/hello
If you try to run either of the two following commands, you'll see your custom errors:
* `curl -XGET -v http://localhost:8080/morning`: will return your custom `not found` error.
* `curl -XPOST -v http://localhost:8080/hello`: will return your custom `not allowed` error.
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/custom_error.cpp).
### Custom logging callbacks
* _.log_access(**void(*log_access_ptr)(const std::string&)** functor):_ Specifies a function used to log accesses (requests) to the server.
* _.log_error(**void(*log_error_ptr)(const std::string&)** functor):_ Specifies a function used to log errors generating from the server.
#### Example of custom logging callback
#include
#include
using namespace httpserver;
void custom_access_log(const std::string& url) {
std::cout appe &firs
import Tkinter paste( $obh &a or it myval bro roll: :: [] require a
case `` super. +y expr say " %rooms 1 --account fb- yy
proc meth Animate => send(D, open) putd EndIf 10 whi myc` cont
and main (--) import loop $$ or end onload UNION WITH tab timer 150 *2
end. begin True GtkLabel *label doto partition te let auto iher flv op element >> 71 or
QFileDi : and .. with myc toA channel::bo myc isEmpty a not bodt;
class T public pol str mycalc d pt &&a *i fc add ^ac
::ZenCoders::core::namespac boost::function st f = std: ;; int assert
cout