### Example/ADDRESS BINDING

Overview
--------

Each network interface on a host usually has a unique IP address. Sockets with wildcard local addresses can receive messages sent to any of the host's addresses on a specific port. For example, if a host has two interfaces with addresses 128.32.0.4 and 10.0.0.78, a socket bound to a wildcard address can accept connections on either. To restrict connections to a specific network, a server binds to the interface address of the desired network.

Example
-------

```C++
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void get_method_handler( const shared_ptr< Session > session )
{
    session->close( OK, "Hello, World!", { { "Content-Length", "13" } } );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "GET", get_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_bind_address( "127.0.0.1" );
    settings->set_default_header( "Connection", "close" );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://127.0.0.1:1984/resource'

---

### Example/COMPRESSION

Overview
--------

HTTP compression improves transfer speed and reduces bandwidth use by compressing data before it is sent from the server to the client.

Browsers indicate which compression methods they support, and the server responds with a compatible compressed format. If a browser does not support compression, it receives uncompressed data.

Common compression methods include gzip and Deflate, with the complete list of supported schemes maintained by the Internet Assigned Numbers Authority (IANA).

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ git clone https://github.com/richgel999/miniz.git
> $ cd miniz
> $ mkdir build; cd build
> $ cmake -DBUILD_HEADER_ONLY=ON -DBUILD_EXAMPLES=OFF -DBUILD_TESTS=OFF ..
> $ make; sudo make install
>
> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ echo "Hello, World!" > test.data
> $ zlib-flate -compress < test.data > test.data.z
> $ curl -w'\n' -v -H"Content-Encoding: deflate" -X POST --data-binary @test.data.z 'http://localhost:1984/api/deflate'

---

### Example/CUSTOM HTTP METHOD

Overview
--------

A key constraint of HTTP and a core principle of REST is the uniform interface: a small, fixed set of methods applied consistently to all resources.

This standardisation simplifies system design and improves interoperability, but it can also limit flexibility in certain use cases.

Example
-------

```C++
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void nop_method_handler( const shared_ptr< Session > session )
{
    session->close( 666 );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "NOP", nop_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_default_header( "Connection", "close" );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -X NOP 'http://localhost:1984/resource'

---

### Example/CUSTOM STATUS CODE

Overview
--------

The Internet runs on shared conventions known as RFCs (Requests for Comments).

Although RFCs are not laws and violating them carries no legal penalty, doing so can prevent your service from interoperating reliably with other systems on the Internet.

Example
-------

```C++
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void get_method_handler( const shared_ptr< Session > session )
{
    session->close( 418 );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "GET", get_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_default_header( "Connection", "close" );
    settings->set_status_message( 418, "I'm a teapot" );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -X GET 'http://localhost:1984/resource'

---

### Example/DIGEST AUTHENTICATION

Overview
--------

Digest access authentication is an HTTP method that allows a web server to verify a user’s credentials (such as username and password) before granting access to protected resources, like online banking data.

Instead of sending credentials in plain form, it applies a cryptographic hash function to the username and password before transmission, improving security.

In contrast, Basic access authentication only uses Base64 encoding, which is easily reversible and does not provide real security unless combined with TLS encryption.

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v --digest -XGET 'http://Corvusoft:Glasgow@localhost:1984/resource'

---

### Example/ERROR HANDLING

Overview
--------

Error handling is the process of anticipating, detecting, and resolving errors in software and communication systems.

Specialised components, called error handlers, help manage these issues. Effective error handling aims to prevent errors when possible, recover from them without stopping the application, and—if recovery is not possible—shut down gracefully while recording details in a log for later analysis.

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://localhost:1984/resources/1'
>
> $ curl -w'\n' -v -XGET 'http://localhost:1984/resources/2'

---

### Example/HTTP PERSISTENT CONNECTION

Overview
--------

HTTP persistent connections (also called keep-alive or connection reuse) allow multiple HTTP request–response exchanges to occur over a single TCP connection, instead of creating a new connection for each request. This reduces latency and improves efficiency.

The newer HTTP/2 protocol extends this concept by enabling multiple concurrent requests and responses to be multiplexed over a single connection, further improving performance.

Example
-------

```C++
#include <string>
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void get_intermittent_method_handler( const shared_ptr< Session > session )
{
    session->close( OK, "intermittent resource request", { { "Content-Length", "29" }, { "Connection", "close" } } );
}

void get_persistent_method_handler( const shared_ptr< Session > session )
{
    session->yield( OK, "persistent resource request", { { "Content-Length", "27" }, { "Connection", "keep-alive" } } );
}

int main( const int, const char** )
{
    auto persistent = make_shared< Resource >( );
    persistent->set_path( "/resources/persistent" );
    persistent->set_method_handler( "GET", get_persistent_method_handler );
    
    auto intermittent = make_shared< Resource >( );
    intermittent->set_path( "/resources/intermittent" );
    intermittent->set_method_handler( "GET", get_intermittent_method_handler );
    
    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    
    Service service;
    service.publish( persistent );
    service.publish( intermittent );
    
    service.start( settings );
    
    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v 'http://localhost:1984/resources/persistent' 'http://localhost:1984/resources/intermittent'

---

### Example/HTTP PIPELINING

Overview
--------

HTTP pipelining allows a client to send multiple HTTP requests over a single TCP connection without waiting for each corresponding response. This can reduce latency by minimising idle time between requests.

However, due to practical issues—such as buggy proxy servers and head-of-line (HOL) blocking—HTTP pipelining has not been enabled by default in modern browsers since around 2017.

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ (echo -e "GET /resource/1 HTTP/1.1\r\nHost: localhost\r\nConnection: keep-alive\r\n\r\nGET /resource/2 HTTP/1.1\r\nConnection: keep-alive\r\nHost: localhost\r\n\r\nGET /resource/3 HTTP/1.1\r\nHost: localhost\r\nConnection: keep-alive\r\n\r\n"; sleep 5) | netcat localhost 1984
>
> $ (echo -e "GET &&%$£% /resource/1 HTTP/1.1\r\nHost: localhost\r\nConnection: keep-alive\r\n\r\nGET /resource/2 HTTP/1.1\r\nConnection: keep-alive\r\nHost: localhost\r\n\r\nGET /resource/3 HTTP/1.1\r\nHost: localhost\r\nConnection: keep-alive\r\n\r\n"; sleep 5) | netcat localhost 1984

---

### Example/HTTP SERVICE

Overview
--------

A web service is a service provided by one electronic device to another over the Web. It uses web technologies—most commonly HTTP—to enable machine-to-machine communication.

Although HTTP was originally designed for human-to-machine interaction, web services use it to exchange machine-readable data formats such as XML and JSON.

Example
-------

```C++
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void post_method_handler( const shared_ptr< Session > session )
{
    const auto request = session->get_request( );

    size_t content_length = request->get_header( "Content-Length", 0 );

    session->fetch( content_length, [ request ]( const shared_ptr< Session > session, const Bytes & body )
    {
        fprintf( stdout, "%.*s\n", ( int ) body.size( ), ( const char* ) body.data( ) );
        session->close( OK, "Hello, World!", { { "Content-Length", "13" }, { "Connection", "close" } } );
    } );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "POST", post_method_handler );

    Service service;
    service.publish( resource );
    service.start( );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -X POST --data 'Hello, Restbed' 'http://localhost/resource'

---

### Example/HTTPS SERVICE

Overview
--------

HTTPS (Hypertext Transfer Protocol Secure) is the secure version of HTTP used to transmit data between a web browser and a web server.

It works by encrypting communication using Transport Layer Security (TLS), which replaced the older Secure Sockets Layer (SSL). For this reason, HTTPS is sometimes called HTTP over TLS or HTTP over SSL.

HTTPS provides:
- Confidentiality – Data is encrypted so others cannot read it.
- Integrity – Data cannot be altered during transmission.
- Authentication – Verifies the identity of the website.

Example
-------

```C++
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void get_method_handler( const shared_ptr< Session > session )
{
    session->close( OK, "Hello, World!", { { "Content-Length", "13" }, { "Connection", "close" } } );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "GET", get_method_handler );

    auto ssl_settings = make_shared< SSLSettings >( );
    ssl_settings->set_http_disabled( true );
    ssl_settings->set_private_key( Uri( "file:///tmp/server.key" ) );
    ssl_settings->set_certificate( Uri( "file:///tmp/server.crt" ) );
    ssl_settings->set_temporary_diffie_hellman( Uri( "file:///tmp/dh2048.pem" ) );

    auto settings = make_shared< Settings >( );
    settings->set_ssl_settings( ssl_settings );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ cd /tmp
>
> $ openssl genrsa -out server.key 2048
> $ openssl req -new -key server.key -out server.csr
> $ openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt
> $ openssl dhparam -out dh2048.pem 2048
>
> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -k -v -w'\n' -X GET 'https://localhost/resource'

---

### Example/LOGGING

Overview
--------

Logging is the process of recording events or messages in a system, often written to a log file.

A transaction log is a specific type of log that records interactions (transactions) between a system and its users. It can automatically capture details such as:

- Type of transaction
- Content of the transaction
- Time the transaction occurred

Transaction logs are commonly used to monitor activity, troubleshoot issues, and maintain a record of system usage for auditing or recovery purposes.

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://localhost:1984/resource'

---

### Example/MULTIPATH RESOURCES

Overview
--------

A web resource is anything that can be identified and accessed on the web. Originally, the term referred to the target of a URL.

Its definition now includes anything identified by a Uniform Resource Identifier (URI) or Internationalised Resource Identifier (IRI).

In the Semantic Web, abstract resources and their properties are described using RDF (Resource Description Framework), which allows machines to understand and process the meaning of resources.

In short, a web resource can be a webpage, a file, a service, or even an abstract concept, as long as it can be identified on the web.

Example
-------

```C++
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void get_method_handler( const shared_ptr< Session > session )
{
    session->close( OK, "Hello, World!", { { "Content-Length", "13" } } );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_paths( { "/messages", "/queues/{id: [0-9]*}/messages" } );
    resource->set_method_handler( "GET", get_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_default_header( "Connection", "close" );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v 'http://localhost:1984/messages'
>
> $ curl -w'\n' -v 'http://localhost:1984/queues/12/messages'

---

### Example/MULTITHREADED SERVICE

Overview
--------

Multithreading in computer architecture is the ability of a CPU (or a single core in a multi-core processor) to execute multiple threads or processes at the same time.

In essence, it’s a way for a processor to do more work simultaneously without needing additional cores.

Example
-------

```C++
#include <memory>
#include <thread>
#include <cstdlib>
#include <restbed>
#include <sstream>

using namespace std;
using namespace restbed;

void get_method_handler( const shared_ptr< Session > session )
{
    stringstream id;
    id << ::this_thread::get_id( );
    auto body = "Hello From Thread " + id.str( ) + "\n";

    session->close( OK, body, { { "Content-Length", ::to_string( body.length( ) ) } } );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "GET", get_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_worker_limit( 4 );
    settings->set_default_header( "Connection", "close" );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -X GET 'http://localhost:1984/resource'

---

### Example/PAM AUTHENTICATION

Overview
--------

A Pluggable Authentication Module (PAM) is a system that allows multiple low-level authentication methods to be integrated into a single high-level API. This lets applications perform authentication without depending on the specific underlying mechanism.

PAM was first proposed by Sun Microsystems in an Open Software Foundation RFC in 1995 and became the authentication framework for the Common Desktop Environment. As an open-source infrastructure, it appeared in Red Hat Linux 3.0.4 in 1996 through the Linux PAM project. Today, PAM is supported on multiple operating systems, including AIX, DragonFly BSD, FreeBSD, HP-UX, Linux, Mac OS X, NetBSD, and Solaris.

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ sudo apt-get install libpam0g-dev
> $ clang++ -std=c++20 -o example example.cpp -l restbed -l pam

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://<USERNAME>:<PASSWORD>@localhost:1984/resource'

---

### Example/PATH PARAMETERS

Overview
--------

A URI path parameter is a value included within a path segment of a URI, immediately following its name. Path parameters can control how a resource is represented, but since they cannot be modified by standard web forms, they must be constructed separately. Unlike query strings, path parameters are part of the URI path itself and are interpreted in sequence.

Example
-------

```C++
#include <string>
#include <memory>
#include <cstdlib>
#include <restbed>

using namespace std;
using namespace restbed;

void get_method_handler( const shared_ptr< Session > session )
{
    const auto& request = session->get_request( );

    const string body = "Hello, " + request->get_path_parameter( "name" );
    session->close( OK, body, { { "Content-Length", ::to_string( body.size( ) ) } } );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource/{name: .*}" );
    resource->set_method_handler( "GET", get_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_default_header( "Connection", "close" );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://localhost:1984/resource/<YOUR NAME HERE>'

---

### Example/RESOURCE AUTHENTICATION

Overview
--------

HTTP Basic authentication (BA) is one of the simplest methods for controlling access to web resources. It does not rely on cookies, session identifiers, or dedicated login pages. Instead, it uses standard fields in the HTTP request header to transmit user credentials, eliminating the need for additional authentication handshakes.

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://ben:1234@localhost:1984/ben'
> $ curl -w'\n' -v -XGET 'http://laura:4321@localhost:1984/laura'

---

### Example/SERVICE AUTHENTICATION

Overview
--------

HTTP Basic Authentication (BA) is a simple method for enforcing access control to web resources. It does not require cookies, session identifiers, or login pages. Instead, it transmits user credentials through standard fields in the HTTP header, eliminating the need for additional authentication handshakes.

Example
-------

```C++
#include <memory>
#include <cstdlib>
#include <ciso646>
#include <functional>
#include <restbed>

using namespace std;
using namespace restbed;

void authentication_handler( const shared_ptr< Session > session,
                             const function< void ( const shared_ptr< Session > ) >& callback )
{
    auto authorisation = session->get_request( )->get_header( "Authorization" );

    if ( authorisation not_eq "Basic Q29ydnVzb2Z0OkdsYXNnb3c=" )
    {
        session->close( UNAUTHORIZED, { { "WWW-Authenticate", "Basic realm=\"restbed\"" } } );
    }
    else
    {
        callback( session );
    }
}

void get_method_handler( const shared_ptr< Session > session )
{
    session->close( OK, "Password Protected Hello, World!", { { "Content-Length", "32" } } );
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "GET", get_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_default_header( "Connection", "close" );

    Service service;
    service.publish( resource );
    service.set_authentication_handler( authentication_handler );

    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://Corvusoft:Glasgow@localhost:1984/resource'

---

### Example/SERVING HTML

Overview
--------

A web server is either server software, or hardware dedicated to running that software, which delivers content to the World Wide Web. It processes incoming network requests—primarily over the HTTP protocol and other related protocols—and responds by serving web resources such as pages, files, or data.

Example
-------

```C++
#include <string>
#include <memory>
#include <cstdlib>
#include <fstream>
#include <restbed>
#include <streambuf>

using namespace std;
using namespace restbed;

void get_method_handler( const shared_ptr< Session > session )
{
    const auto request = session->get_request( );
    const string filename = request->get_path_parameter( "filename" );

    ifstream stream( "./" + filename, ifstream::in );

    if ( stream.is_open( ) )
    {
        const string body = string( istreambuf_iterator< char >( stream ), istreambuf_iterator< char >( ) );

        const multimap< string, string > headers
        {
            { "Content-Type", "text/html" },
            { "Content-Length", ::to_string( body.length( ) ) }
        };

        session->close( OK, body, headers );
    }
    else
    {
        session->close( NOT_FOUND );
    }
}

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/static/{filename: [a-z]*\\.html}" );
    resource->set_method_handler( "GET", get_method_handler );

    auto settings = make_shared< Settings >( );
    settings->set_port( 1984 );
    settings->set_default_header( "Connection", "close" );

    Service service;
    service.publish( resource );
    service.start( settings );

    return EXIT_SUCCESS;
}
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ echo "<html>Hello, WORLD</html>" > index.html
>
> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -X GET 'http://localhost:1984/static/index.html'

---

### Example/SYSLOG LOGGING

Overview
--------

In computing, syslog is a standard protocol for message logging. It separates the system components that generate log messages from those that store, analyse, or report on them. Each message includes a *facility code* (identifying the source software type) and a *severity level* (indicating the importance of the event).

System designers use syslog for system management, security auditing, debugging, and general informational messages. Many devices—such as printers, routers, and servers—support the syslog standard, allowing logs from diverse systems to be centralised in a single repository. Syslog implementations are available for many operating systems.


Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ curl -w'\n' -v -XGET 'http://localhost:1984/resource'
>
> $ cat var/log/syslog

---

### Example/TRANSFER ENCODING REQUEST

Overview
--------

Chunked transfer encoding is a streaming data transfer mechanism introduced in HTTP/1.1. It allows data to be sent in a series of independent, non-overlapping "chunks" rather than as a single continuous block.

Each chunk is preceded by its size (in bytes), enabling the receiver to process data incrementally without knowing the total content length in advance. The transmission ends when a zero-length chunk is sent. The use of chunked transfer encoding is indicated by the `Transfer-Encoding: chunked` header.

Example
-------

```
/* Detailed source-code truncated for AI context efficiency. */
```

Build
-----

> $ clang++ -std=c++20 -o example example.cpp -l restbed

Execution
---------

> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
> $ ./example
>
> $ echo "My really large file..." > bigfile.txt
> $ curl -w'\n' -v -X POST --header "Transfer-Encoding: chunked" -d @bigfile.txt 'http://localhost:1984/resources'

---

### API

Overview
--------

This document is intended to accurately communicate the [Application Programming Interface (API)](https://en.wikipedia.org/wiki/Application_programming_interface) exposed by the Restbed framework for public consumption.

A description of the framework's software architecture is provided by the [Design Overview](#DESIGN.md) documentation.

Interpretation
--------------

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/pdf/rfc2119.pdf).

Table of Contents
-----------------

1.	[Overview](#overview)
2.	[Interpretation](#interpretation)
3.	[Bytes](#bytes)
4.	[Logger](#logger)
5.	[Logger::Level](#loggerlevel)
6.	[Request](#request)
7.	[Response](#response)
8.	[Resource](#resource)
9.	[Service](#service)
10.	[Session](#session)
11.	[Settings](#settings)
12.	[SSLSettings](#sslsettings)
13.	[StatusCode](#statuscode)
14.	[String](#string)
15.	[String::Option](#stringoption)
16.	[URI](#uri)
17.	[WebSocket](#websocket)
18.	[WebSocketMessage](#websocketmessage)
19. [WebSocketMessage::OpCode](#websocketmessageopcode)
20.	[Further Reading](#further-reading)

### Bytes

```C++
typedef std::vector< std::byte > Bytes;
```

Bytes provides container functionality with the [Standard Template Library](http://en.cppreference.com/w/cpp) (STL) [vector](http://en.cppreference.com/w/cpp/container/vector) collection semantics.

See [std::byte](http://en.cppreference.com/w/cpp/types/byte) and [std::vector](http://en.cppreference.com/w/cpp/container/vector) for further details.

### Logger

Interface detailing the required contract for logger extensions.

No default logger is supplied with the codebase; it is the responsibility of third-party developers to implement the desired behaviour.

#### Methods

-	[start](#loggerstart)
-	[stop](#loggerstop)
-	[log](#loggerlog)
-	[log_if](#loggerlog_if)
-	[level](#loggerlevel)

#### Logger::start

```C++
virtual void start( const std::shared_ptr< const restbed::Settings >& settings ) = 0;
```

Initialise a logger instance; see also [stop](#loggerstop).

The [Settings](#settings) passed are the same as those given to [Service::start](#servicestart).

After this method has returned, the instance **MUST** be ready to start receiving [log](#loggerlog) and [log_if](#loggerlog_if) invocations.

##### Parameters

| name  | type                           | default value | direction |
|:-----:|--------------------------------|:-------------:|:---------:|
| value | [restbed::Settings](#settings) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

Any exceptions raised will result in the service failing to start.

#### Logger::stop

```C++
virtual void stop( void ) = 0;
```

Halt and clean-up logger resources; see also [start](#loggerstart).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

Exceptions raised will result in a dirty service teardown.

#### Logger::log

```C++
virtual void log( const Level level, const char* format, ... ) = 0;
```

Commit the message specified under the control of a format string, with the specified level of severity, into the log; see also [log_if](#loggerlog_if).

See the [printf](http://en.cppreference.com/w/cpp/io/c/fprintf) family of functions for format directives.

> The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is >introduced by the % character.

##### Parameters

| name   | type                                                                        | default value | direction |
|:------:|-----------------------------------------------------------------------------|:-------------:|:---------:|
| level  | [restbed::Logger::Level](#loggerlevel)                                      |      n/a      |   input   |
| format | [char\*](http://en.cppreference.com/w/cpp/language/types)                   |      n/a      |   input   |
|  ...   | [variadic argument list](http://en.cppreference.com/w/cpp/utility/variadic) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

Any exceptions raised will result in the service ignoring the fault and printing directly to [Standard Error (stderr)](http://en.cppreference.com/w/cpp/io/c).

#### Logger::log_if

```C++
virtual void log_if( bool expression, const Level level, const char* format, ... ) = 0;
```

Commit the message specified under the control of a format string, with the specified level of severity, into the log, under the condition that the expression is equal to true; see also [log](#loggerlog).

##### Parameters

| name        | type                                                                        | default value | direction |
|:-----------:|-----------------------------------------------------------------------------|:-------------:|:---------:|
|  expression | [bool](http://en.cppreference.com/w/cpp/language/types)                     |      n/a      |   input   |
|    level    | [restbed::Logger::Level](#loggerlevel)                                      |      n/a      |   input   |
|   format    | [char\*](http://en.cppreference.com/w/cpp/language/types)                   |      n/a      |   input   |
|     ...     | [variadic argument list](http://en.cppreference.com/w/cpp/utility/variadic) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

Any exceptions raised will result in the service ignoring the fault and printing directly to [Standard Error (stderr)](http://en.cppreference.com/w/cpp/io/c).

#### Logger::Level

```C++
class Logger
{
    enum Level : int
    {
        INFO = 0000,
        DEBUG = 1000,
        FATAL = 2000,
        ERROR = 3000,
        WARNING = 4000,
        SECURITY = 5000
    };
}
```

[Enumeration](http://en.cppreference.com/w/cpp/language/enum) is used in conjunction with the [Logger interface](#logger) to detail the level of severity towards a particular log entry.

### Request

Represents an HTTP request with additional helper methods for manipulating data and improving code readability.

#### Methods

-	[constructor](#requestconstructor)
-	[destructor](#requestdestructor)
-	[has_header](#requesthas_header)
-	[has_path_parameter](#requesthas_path_parameter)
-	[has_query_parameter](#requesthas_query_parameter)
-	[get_port](#requestget_port)
-	[get_version](#requestget_version)
-	[get_body](#requestget_body)
-	[get_response](#requestget_response)
-	[get_host](#requestget_host)
-	[get_path](#requestget_path)
-	[get_method](#requestget_method)
-	[get_protocol](#requestget_protocol)
-	[get_header](#requestget_header)
-	[get_headers](#requestget_headers)
-	[get_query_parameter](#requestget_query_parameter)
-	[get_query_parameters](#requestget_query_parameters)
-	[get_path_parameter](#requestget_path_parameter)
-	[get_path_parameters](#requestget_path_parameters)
-	[set_body](#requestset_body)
-	[set_port](#requestset_port)
-	[set_version](#requestset_version)
-	[set_path](#requestset_path)
-	[set_host](#requestset_host)
-	[set_method](#requestset_method)
-	[set_protocol](#requestset_protocol)
-	[add_header](#requestadd_header)
-	[set_header](#requestset_header)
-	[set_headers](#requestset_headers)
-	[set_query_parameter](#requestset_query_parameter)
-	[set_query_parameters](#requestset_query_parameters)

#### Request::constructor

```C++
Request( void );
Request( const Uri& value );
```

Initialises a new class instance; if a [Uri](#uri) is supplied, it will be used to override the default class property values; see also [destructor](#requestdestructor).

##### Parameters

| name  | type        | default value | direction |
|:-----:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::destructor

```C++
virtual ~Request( void );
```

Clean-up class instance; see also [constructor](#requestconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Request::has_header

```C++
bool has_header( const std::string& name ) const;
```

Case-insensitive check to confirm if the [request](#request) contains a header with the supplied name.

##### Parameters

| name | type                                                                | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

Boolean true if the [request](#request) holds a header with a matching name, else false.

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Request::has_path_parameter

```C++
bool has_path_parameter( const std::string& name ) const;
```

Case-insensitive check to confirm if the [request](#request) contains a path parameter with the supplied name.

##### Parameters

| name | type                                                                | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

Boolean true if the [request](#request) holds a path parameter with a matching name, else false.

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Request::has_query_parameter

```C++
bool has_query_parameter( const std::string& name ) const;
```

Case-insensitive check to confirm if the [request](#request) contains a query parameter with the supplied name.

##### Parameters

| name | type                                                                | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

Boolean true if the [request](#request) holds a query parameter with a matching name, else false.

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Request::get_port

```C++
uint16_t get_port( void ) const;
```

Retrieves the network port number of the server endpoint; see also [set_port](#requestset_port).

##### Parameters

n/a

##### Return Value

[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.

##### Exceptions

n/a

#### Request::get_version

```C++
double get_version( void ) const;
```

Retrieves the [HTTP version](https://tools.ietf.org/html/rfc2145) number; see also [set_version](#requestset_version).

##### Parameters

n/a

##### Return Value

[double](http://en.cppreference.com/w/cpp/language/types%23Floating_point_types) representing the [HTTP version](https://tools.ietf.org/html/rfc2145).

##### Exceptions

n/a

#### Request::get_body

```C++
Bytes get_body( void ) const;
```

1) Retrieves the contents of the request body as [Bytes](#bytebytes); see also [set_body](#requestset_body).

##### Parameters

n/a

##### Return Value

[Bytes](#bytebytes) representing the request body.

##### Exceptions

n/a

#### Request::get_response

```C++
const std::shared_ptr< const Response > get_response( void ) const;
```

Retrieves the associated HTTP [response](#response) for this request, if any.

##### Parameters

n/a

##### Return Value

[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) representing the response, else nullptr.

##### Exceptions

n/a

#### Request::get_host

```C++
std::string get_host( void ) const;
```

Retrieves the host for this request.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the host.

##### Exceptions

n/a

#### Request::get_path

```C++
std::string get_path( void ) const;
```

Retrieves the path for this request.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the path.

##### Exceptions

n/a

#### Request::get_method

```C++
std::string get_method( void ) const;
```

Retrieves the [HTTP method](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) for this request.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the [HTTP method](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html).

##### Exceptions

n/a

#### Request::get_protocol

```C++
std::string get_protocol( void ) const;
```

Retrieves the protocol for this request.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the protocol.

##### Exceptions

n/a

#### Request::get_header

```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_header( const std::string& name, const Type default_value ) const

std::string get_header( const std::string& name, const std::string& default_value ) const;
```

1) Retrieve the first header with a matching name, parsing to an arithmetic value. If not found, return default_value.

2) Retrieve the first header with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). If not found, return default_value.

##### Parameters

| name          | type                                                                              | default value | direction |
|:-------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| header name   | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)               |      n/a      |   input   |
| default_value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)               |      n/a      |   input   |

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic value representing the header.

##### Exceptions

n/a

#### Request::get_headers

```C++
std::multimap< std::string, std::string > get_headers( const std::string& name = "" ) const;
```

Retrieves all headers as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). If a name is supplied, only matching headers will be returned.

##### Parameters

| name         | type                                                                          | default value | direction |
|:------------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| header name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |

##### Return Value

[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of headers.

##### Exceptions

n/a

#### Request::get_query_parameter

```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_query_parameter( const std::string& name, const Type default_value ) const

std::string get_query_parameter( const std::string& name, const std::string& default_value ) const;
```

1) Retrieve the first query parameter with a matching name, parsing to an arithmetic value. If not found, return default_value.

2) Retrieve the first query parameter with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). If not found, return default_value.

##### Parameters

| name           | type                                                                              | default value | direction |
|:--------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| parameter name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic |      n/a      |   input   |
| default_value  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic |      n/a      |   input   |

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or an arithmetic value representing the query parameter.

##### Exceptions

n/a

#### Request::get_query_parameters

```C++
std::multimap< std::string, std::string > get_query_parameters( const std::string& name = "", const String::Option option = String::CASE_INSENSITIVE ) const;
```

Retrieves all query parameters as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). If a name is supplied, only matching parameters will be returned.

##### Parameters

| name           | type                                                                          | default value | direction |
|:--------------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| parameter name | [String::Option](#stringoption)                                               |      n/a      |   input   |
| option         | [String::Option](#stringoption)                                               |      n/a      |   input   |

##### Return Value

[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of parameters.

##### Exceptions

n/a

#### Request::get_path_parameter

```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_path_parameter( const std::string& name, const Type default_value ) const

std::string get_path_parameter( const std::string& name, const std::string& default_value ) const;
```

1) Retrieve the first parameter with a matching name, parsing to an arithmetic value. If not found, return default_value.

2) Retrieve the first parameter with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). If not found, return default_value.

##### Parameters

| name           | type                                                                              | default value | direction |
|:--------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| parameter name | [String::Option](#stringoption)                                                   |      n/a      |   input   |
| default_value  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic |      n/a      |   input   |

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic value representing the path parameter.

##### Exceptions

n/a

#### Request::get_path_parameters

```C++
std::multimap< std::string, std::string > get_path_parameters( const std::string& name = "" ) const;
```

Retrieves all query parameters as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). If a name is supplied, only matching parameters will be returned.

##### Parameters

| name           | type                                                                              | default value | direction |
|:--------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| parameter name | [String::Option](#stringoption)                                                   |      n/a      |   input   |

##### Return Value

[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of parameters.

##### Exceptions

n/a

#### Request::set_body

```C++
void set_body( const Bytes& value );

void set_body( const std::string& value );
```

Replace request body; see also [get_body](#requestget_body).

##### Parameters

| name  | type                                                                                       | default value | direction |
|:-----:|--------------------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or [Bytes](#bytebytes) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_port

```C++
void set_port( const uint16_t value );
```

Replace request network port; see also [get_port](#requestget_port).

##### Parameters

| name  | type                                                            | default value | direction |
|:-----:|-----------------------------------------------------------------|:-------------:|:---------:|
| value | [std::uint16_t](http://en.cppreference.com/w/cpp/types/integer) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_version

```C++
void set_version( const double value );
```

Replace request version; see also [get_version](#requestget_version).

##### Parameters

| name  | type                                                                              | default value | direction |
|:-----:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [double](http://en.cppreference.com/w/cpp/language/types%23Floating_point_types)  |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_path

```C++
void set_path( const std::string& value );
```

Replace request path; see also [get_path](#requestget_path).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_host

```C++
void set_host( const std::string& value );
```

Replace request host; see also [get_host](#requestget_host).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_method

```C++
void set_method( const std::string& value );
```

Replace request method; see also [get_method](#requestget_method).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_protocol

```C++
void set_protocol( const std::string& value );
```

Replace request protocol; see also [get_protocol](#requestget_protocol).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::add_header

```C++
void add_header( const std::string& name, const std::string& value );
```

Add an HTTP header to the request; existing headers that share the same name will not be altered.

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_header

```C++
void set_header( const std::string& name, const std::string& value );
```

Set an HTTP header; existing headers that share the same name will be erased.

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_headers

```C++
void set_headers( const std::multimap< std::string, std::string >& values );
```

Set HTTP headers; existing headers will be erased.

##### Parameters

| name   | type                                                                 | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_query_parameter

```C++
void set_query_parameter( const std::string& name, const std::string& value );
```

Set HTTP query parameter; existing parameters that share the same name will be erased.

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Request::set_query_parameters

```C++
void set_query_parameters( const std::multimap< std::string, std::string >& values );
```

Set HTTP query parameters; existing parameters will be erased.

##### Parameters

| name   | type                                                                 | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### Response

Represents an HTTP response with additional helper methods for manipulating data and improving code readability.

#### Methods

-	[constructor](#responseconstructor)
-	[destructor](#responsedestructor)
-	[has_header](#responsehas_header)
-	[get_body](#responseget_body)
-	[get_version](#responseget_version)
-	[get_status_code](#responseget_status_code)
-	[get_protocol](#responseget_protocol)
-	[get_status_message](#responseget_status_message)
-	[get_header](#responseget_header)
-	[get_headers](#responseget_headers)
-	[set_body](#responseset_body)
-	[set_version](#responseset_version)
-	[set_status_code](#responseset_status_code)
-	[set_protocol](#responseset_protocol)
-	[set_status_message](#responseset_status_message)
-	[add_header](#responseadd_header)
-	[set_header](#responseset_header)
-	[set_headers](#responseset_headers)

#### Response::constructor

```C++
Response( void );
```

Initialises a new class instance; see also the [destructor](#responsedestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### Response::destructor

```C++
virtual ~Response( void );
```

Clean-up class instance; see also the [constructor](#responseconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Response::has_header

```C++
bool has_header( const std::string& name ) const;
```

Case-insensitive check to confirm if the [response](#response) contains a header with the supplied name.

##### Parameters

| name | type                                                                | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

Boolean true if the [response](#response) holds a header with a matching name, else false.

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Response::get_body

```C++
Bytes get_body( void ) const;
```

1) Retrieves the contents of the response body as [Bytes](#bytebytes); see also [set_body](#responseset_body).

##### Parameters

n/a

##### Return Value

[Bytes](#bytebytes) representing the response body.

##### Exceptions

n/a

#### Response::get_version

```C++
double get_version( void ) const;
```

Retrieves the [HTTP version](https://tools.ietf.org/html/rfc2145) number; see also [set_version](#responseset_version).

##### Parameters

n/a

##### Return Value

[double](http://en.cppreference.com/w/cpp/language/types%23Floating_point_types) representing the [HTTP version](https://tools.ietf.org/html/rfc2145).

##### Exceptions

n/a

#### Response::get_status_code

```C++
int get_status_code( void ) const;
```

Retrieves the [HTTP status code](https://tools.ietf.org/html/rfc7231#section-6.1); see also [set_status_code](#responseset_status_code).

##### Parameters

n/a

##### Return Value

Integer representing the [HTTP status code](https://tools.ietf.org/html/rfc7231#section-6.1).

##### Exceptions

n/a

#### Response::get_protocol

```C++
std::string get_protocol( void ) const;
```

Retrieve the protocol.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the protocol.

##### Exceptions

n/a

#### Response::get_status_message

```C++
std::string get_status_message( void ) const;
```

Retrieves the [HTTP status message](https://tools.ietf.org/html/rfc7231#section-6.1); see also [set_status_message](#responseset_status_message).

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the [HTTP status message](https://tools.ietf.org/html/rfc7231#section-6.1).

##### Exceptions

n/a

#### Response::get_header

```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_header( const std::string& name, const Type default_value ) const

std::string get_header( const std::string& name, const std::string& default_value ) const;
```

1) Retrieve the first header with a matching name, parsing to an arithmetic value. If not found, return default_value.

2) Retrieve the first header with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). If not found, return default_value.

##### Parameters

| name          | type                                                                              | default value | direction |
|:-------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| header name   | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic |      n/a      |   input   |
| default_value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic |      n/a      |   input   |

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic value representing the header.

##### Exceptions

n/a

#### Response::get_headers

```C++
std::multimap< std::string, std::string > get_headers( const std::string& name = "" ) const;
```

Retrieves all headers as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). If a name is supplied, only matching headers will be returned.

##### Parameters

| name          | type                                                                              | default value | direction |
|:-------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| header name   | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic |      n/a      |   input   |

##### Return Value

[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of headers.

##### Exceptions

n/a

#### Response::set_body

```C++
void set_body( const Bytes& value );

void set_body( const std::string& value );
```

Replace response body; see also [get_body](#responseget_body).

##### Parameters

| name  | type                                                                                       | default value | direction |
|:-----:|--------------------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or [Bytes](#bytebytes) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Response::set_version

```C++
void set_version( const double value );
```

Replace response version; see also [get_version](#responseget_version).

##### Parameters

| name  | type                                                                              | default value | direction |
|:-----:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [double](hhttp://en.cppreference.com/w/cpp/language/types%23Floating_point_types) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Response::set_status_code

```C++
void set_status_code( const int value );
```

Replace response status code; see also [get_status_code](#responseget_status_code).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|----------------------------------------------------------------------|:-------------:|:---------:|
| value | [int](http://en.cppreference.com/w/cpp/types/integer) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Response::set_protocol

```C++
void set_protocol( const std::string& value );
```

Replace response protocol; see also [get_protocol](#responseget_protocol).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Response::set_status_message

```C++
void set_status_message( const std::string& value );
```

Replace response status message; see also [get_status_message](#responseget_status_message).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Response::add_header

```C++
void add_header( const std::string& name, const std::string& value );
```

Add an HTTP header to the response; existing headers that share the same name will not be altered.

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Response::set_header

```C++
void set_header( const std::string& name, const std::string& value );
```

Set an HTTP header; existing headers that share the same name will be erased; see also [get_header](#responseget_header).

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Response::set_headers

```C++
void set_headers( const std::multimap< std::string, std::string >& values );
```

Set HTTP headers, existing headers will be erased; see also [get_headers](#responseget_headers).

##### Parameters

| name   | type                                                                 | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### Resource

Resource represents a network communication endpoint. This is the primary data structure used throughout to represent RESTful resources. All resource-specific filtration, request processing, and authentication must be placed on this entity.

#### Methods

-	[constructor](#resourceconstructor)
-	[destructor](#resourcedestructor)
-	[set_path](#resourceset_path)
-	[set_paths](#resourceset_paths)
-	[set_default_header](#resourceset_default_header)
-	[set_default_headers](#resourceset_default_headers)
-	[set_error_handler](#resourceset_error_handler)
-	[set_authentication_handler](#resourceset_authentication_handler)
-	[set_method_handler](#resourceset_method_handler)

#### Resource::constructor

```C++
Resource( void );
```

Initialises a new class instance; see also [destructor](#resourcedestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### Resource::destructor

```C++
virtual ~Resource( void );
```

Clean-up class instance; see also [constructor](#resourceconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Resource::set_path

```C++
void set_path( const std::string& value );
```

Set the path by which this resource should be accessible. [Settings::set_root](settingsset_root) will be prepended to this value.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Resource::set_paths

```C++
void set_paths( const std::set< std::string >& values );
```

Set the paths with which this resource should be accessible. [Settings::set_root](settingsset_root) will be prepended to all values.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| values     | [std::set](http://en.cppreference.com/w/cpp/container/set)          |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Resource::set_default_header

```C++
void set_default_header( const std::string& name, const std::string& value );
```

Set a default header that should be sent on every HTTP response, overriding any existing value with the same name.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name       | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Resource::set_default_headers

```C++
void set_default_headers( const std::multimap< std::string, std::string >& values );
```

Set default headers that should be sent on every HTTP response, overriding any existing values.

##### Parameters

| name       | type                                                                 | default value | direction |
|:----------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values     | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Resource::set_error_handler

```C++
void set_error_handler( const std::function< void ( const int, const std::exception&, const std::shared_ptr< Session > ) >& value );
```

Set error handler. During processing, if a failure occurs, this method will be invoked for reporting and HTTP response error handling.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Resource::set_authentication_handler

```C++
void set_authentication_handler( const std::function< void ( const std::shared_ptr< Session >, const std::function< void ( const std::shared_ptr< Session > ) >& ) >& value );
```

Set the authentication handler; this method will be invoked after the service authentication handler.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Resource::set_method_handler

```C++
void set_method_handler( const std::string& method, const std::function< void ( const std::shared_ptr< Session > ) >& callback );
```

Set method handler.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| method     | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |
| callback   | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### Service

The service is responsible for managing the publicly available RESTful resources, HTTP compliance, scheduling of the socket data and ensuring incoming requests are processed in a timely fashion.

#### Methods

-	[constructor](#serviceconstructor)
-	[destructor](#servicedestructor)
-	[is_up](#serviceis_up)
-	[is_down](#serviceis_down)
-	[stop](#servicestop)
-	[start](#servicestart)
-	[publish](#servicepublish)
-	[suppress](#servicesuppress)
-	[get_uptime](#serviceget_uptime)
-	[get_http_uri](#serviceget_http_uri)
-	[get_https_uri](#serviceget_https_uri)
-   [get_io_context](#serviceget_io_context)
-	[set_logger](#serviceset_logger)
-	[set_ready_handler](#serviceset_ready_handler)
-	[set_not_found_handler](#serviceset_not_found_handler)
-	[set_method_not_allowed_handler](#serviceset_method_not_allowed_handler)
-	[set_method_not_implemented_handler](#serviceset_method_not_implemented_handler)
-	[set_error_handler](#serviceset_error_handler)
-	[set_authentication_handler](#serviceset_authentication_handler)

#### Service::constructor

```C++
Service( void );
```

Initialises a new class instance; see also [destructor](#servicedestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### Service::destructor

```C++
virtual ~Service( void );
```

Clean-up class instance; see also [constructor](#serviceconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Service::is_up

```C++
bool is_up( void ) const;
```

Return a boolean value indicating if the service is currently online and serving incoming requests.

##### Parameters

n/a

##### Return Value

Boolean true if the service is online, else false.

##### Exceptions

n/a

#### Service::is_down

```C++
bool is_down( void ) const;
```

Return a boolean value indicating if the service is currently offline and serving incoming requests.

##### Parameters

n/a

##### Return Value

Boolean true if the service is offline, else false.

##### Exceptions

n/a

#### Service::stop

```C++
void stop( void ) const;
```

Shut the service down, closing open sessions and terminating threads that may be running.

##### Parameters

n/a

##### Return Value

Boolean true if the service is offline, else false.

##### Exceptions

n/a

#### Service::start

```C++
void start( const std::shared_ptr< const Settings >& settings = nullptr );
```

Start the service with the supplied settings; otherwise, default values will be set.

##### Parameters

| name       | type                                                                  | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| settings   | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::publish

```C++
void publish( const std::shared_ptr< const Resource >& resource );
```

Publish a RESTful resource for public consumption; see also [Resource](#resource).

##### Parameters

| name       | type                                                                  | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| resource   | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::suppress

```C++
void suppress( const std::shared_ptr< const Resource >& resource );
```

Suppress an already published RESTful resource; see also [Resource](#resource).

##### Parameters

| name       | type                                                                  | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| resource   | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::get_uptime

```C++
const std::chrono::seconds get_uptime( void ) const;
```

Return the number of seconds that have passed since the service was brought online.

##### Parameters

n/a

##### Return Value

Number of seconds since calling [start](#servicestart).

##### Exceptions

n/a

#### Service::get_http_uri

```C++
const std::shared_ptr< const Uri > get_http_uri( void ) const;
```

Return a URI representing the HTTP endpoint; see also [URI](#uri).

##### Parameters

n/a

##### Return Value

URI representing the HTTP endpoint.

##### Exceptions

n/a

#### Service::get_https_uri

```C++
const std::shared_ptr< const Uri > get_https_uri( void ) const;
```

Return a URI representing the HTTPS endpoint; see also [URI](#uri).

##### Parameters

n/a

##### Return Value

URI representing HTTPS endpoint.

##### Exceptions

n/a

#### Service::get_io_context

```C++
std::shared_ptr< asio::io_context > get_io_context( void ) const;
```

Return the ASIO input/output context.

##### Parameters

n/a

##### Return Value

ASIO input/output runtime context.

##### Exceptions

n/a

#### Service::set_logger

```C++
void set_logger( const std::shared_ptr< Logger >& value );
```

Set the logger instance to be used; see also [Logger](#logger).

##### Parameters

| name       | type                                                                  | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::set_ready_handler

```C++
void set_ready_handler( const std::function< void ( Service& ) >& value );
```

Set a handler to be invoked once the service is up and ready to serve incoming HTTP requests.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::set_not_found_handler

```C++
void set_not_found_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```

If an incoming HTTP request cannot be matched to a known resource, its session will be handed over to the resource not found handler.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::set_method_not_allowed_handler

```C++
void set_method_not_allowed_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```

If an incoming HTTP request cannot be matched to a known resource method handler, its session will be routed over to the method not found handler.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::set_method_not_implemented_handler

```C++
void set_method_not_implemented_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```

If none of the service resources have a handler for an incoming HTTP request method, its session shall be routed to the method-not-implemented handler.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::set_error_handler

```C++
void set_error_handler( const std::function< void ( const int, const std::exception&, const std::shared_ptr< Session > ) >& value );
```

If an error occurs during processing and no resource-specific error handler can be obtained, the global service error handler will be invoked if set.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Service::set_authentication_handler

```C++
void set_authentication_handler( const std::function< void ( const std::shared_ptr< Session >, const std::function< void ( const std::shared_ptr< Session > ) >& ) >& value );
```

Set a service-wide authentication handler before invoking resource-specific authentication handlers.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### Session

Represents a conversation between a client and the service. Internally, this class holds the network state and exposes public functionality to interact with the service event-loop for asynchronous data acquisition and/or sleep states.

#### Methods

-	[constructor](#sessionconstructor)
-	[destructor](#sessiondestructor)
-	[is_open](#sessionis_open)
-	[is_closed](#sessionis_closed)
-	[close](#sessionclose)
-	[yield](#sessionyield)
-	[fetch](#sessionfetch)
-	[upgrade](#sessionupgrade)
-	[sleep_for](#sessionsleep_for)
-	[get_origin](#sessionget_origin)
-	[get_destination](#sessionget_destination)
-	[get_request](#sessionget_request)
-	[get_resource](#sessionget_resource)
-	[get_headers](#sessionget_headers)
-	[add_header](#sessionadd_header)
-	[set_header](#sessionset_header)
-	[set_headers](#sessionset_headers)

#### Session::constructor

```C++
Session( void );
```

Initialises a new class instance; see also [destructor](#sessiondestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### Session::destructor

```C++
virtual ~Session( void );
```

Clean-up class instance; see also [constructor](#sessionconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Session::is_open

```C++
bool is_open( void ) const;
```

Return the status of the underlying Session socket.

##### Parameters

n/a

##### Return Value

Boolean true if the session is active.

##### Exceptions

n/a

#### Session::is_closed

```C++
bool is_closed( void ) const;
```

Return the status of the underlying Session socket.

##### Parameters

n/a

##### Return Value

Boolean true if the session is inactive.

##### Exceptions

n/a

#### Session::close

```C++
void close( const Bytes& body );

void close( const Response& response );

void close( const std::string& body = "" );

void close( const int status, const Bytes& body );

void close( const int status, const std::string& body = "" );

void close( const int status, const std::multimap< std::string, std::string >& headers );

void close( const int status, const std::string& body, const std::multimap< std::string, std::string >& headers );

void close( const int status, const Bytes& body, const std::multimap< std::string, std::string >& headers );
```

Close an active session, returning a tailored HTTP response based on the supplied parameters.

##### Parameters

| name       | type                                                                                       | default value | direction |
|:----------:|--------------------------------------------------------------------------------------------|:-------------:|:---------:|
| status     | [int](http://en.cppreference.com/w/cpp/types/integer)                                      |      n/a      |   input   |
| body       | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or [Bytes](#bytebytes) |      n/a      |   input   |
| headers    | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap)                       |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Session::yield

```C++
void yield( const Bytes& data, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );

void yield( const std::string& data, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );

void yield( const Response& response, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );

void yield( const int status, const std::string& body, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );

void yield( const int status, const Bytes& body = { }, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );

void yield( const int status, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );

void yield( const int status, const Bytes& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );

void yield( const int status, const std::string& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
```

Return a tailored HTTP response based on the supplied parameters without closing the underlying socket connection; On completion, invoke the callback.

##### Parameters

| name       | type                                                                                       | default value | direction |
|:----------:|--------------------------------------------------------------------------------------------|:-------------:|:---------:|
| status     | [int](http://en.cppreference.com/w/cpp/types/integer)                                      |      n/a      |   input   |
| body       | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or [Bytes](#bytebytes) |      n/a      |   input   |
| headers    | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap)                       |      n/a      |   input   |
| callback   | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function)              |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Session::fetch

```C++
void fetch( const std::size_t length, const std::function< void ( const std::shared_ptr< Session >, const Bytes& ) >& callback );
            
void fetch( const std::string& delimiter, const std::function< void ( const std::shared_ptr< Session >, const Bytes& ) >& callback );
```

1) Fetch length bytes from the underlying socket connection.

2) Fetch bytes from the underlying socket connection until encountering the delimiter.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| length     | [std::size_t](http://en.cppreference.com/w/cpp/types/size_t)                  |      n/a      |   input   |
| delimiter  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |
| callback   | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Session::upgrade

```C++
void upgrade( const int status, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );

void upgrade( const int status, const Bytes& body, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );

void upgrade( const int status, const std::string& body, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );

void upgrade( const int status, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );

void upgrade( const int status, const Bytes& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );

void upgrade( const int status, const std::string& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );
```

Return a tailored HTTP response based on the supplied parameters and upgrade to the WebSocket protocol; On completion, invoke the callback.

##### Parameters

| name       | type                                                                                          | default value | direction |
|:----------:|-----------------------------------------------------------------------------------------------|:-------------:|:---------:|
| status     | [int](http://en.cppreference.com/w/cpp/types/integer)                                         |      n/a      |   input   |
| body       | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or [Bytes](#bytebytes)    |      n/a      |   input   |
| headers    | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap)                          |      n/a      |   input   |
| callback   | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function)                 |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Session::sleep_for

```C++
void sleep_for( const std::chrono::milliseconds& delay, const std::function< void ( const std::shared_ptr< Session > ) >& callback );
```

Place a task on the [Service](#service) event loop to be run in delay milliseconds.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| delay      | [std::chrono::milliseconds](http://en.cppreference.com/w/cpp/chrono/duration) |      n/a      |   input   |
| callback   | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Session::get_origin

```C++
const std::string get_origin( void ) const;
```

Return a string representing an Internet Protocol address and port number identifying the source of the current HTTP request.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/utility/functional/function) representing the source network endpoint.

##### Exceptions

n/a

#### Session::get_destination

```C++
const std::string get_destination( void ) const;
```

Return a string representing an Internet Protocol address and port number identifying the original destination of the current HTTP request.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/utility/functional/function) representing a destination network endpoint.

##### Exceptions

n/a

#### Session::get_request

```C++
const std::shared_ptr< const Request > get_request(  void ) const;
```

Return the currently active HTTP request.

##### Parameters

n/a

##### Return Value

[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) representing an HTTP request.

##### Exceptions

n/a

#### Session::get_resource

```C++
const std::shared_ptr< const Resource > get_resource( void ) const;
```

Return the currently active RESTful resource.

##### Parameters

n/a

##### Return Value

[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) representing an HTTP request.

##### Exceptions

n/a

#### Session::get_headers

```C++
const std::multimap< std::string, std::string >& get_headers( void ) const;
```

Return the default session header that must be present on each HTTP response.

##### Parameters

n/a

##### Return Value

[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of HTTP headers.

##### Exceptions

n/a

#### Session::add_header

```C++
void add_header( const std::string& name, const std::string& value );
```

Add a default HTTP header to the session; existing headers that share the same name will not be altered.

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Session::set_header

```C++
void set_header( const std::string& name, const std::string& value );
```

Set a default HTTP header for the session; existing headers that share the same name will be erased.

##### Parameters

| name  | type                                                                | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name  | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Session::set_headers

```C++
void set_headers( const std::multimap< std::string, std::string >& values );
```

Set default HTTP headers for the session; existing headers will be erased; see also [get_headers](#sessionget_headers).

##### Parameters

| name   | type                                                                 | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### Settings

Represents service configuration.

#### Methods

-	[constructor](#settingsconstructor)
-	[destructor](#settingsdestructor)
-	[get_port](#settingsget_port)
-	[get_root](#settingsget_root)
-	[get_ipc_path](#settingsget_ipc_path)
-   [get_reuse_address](#settingsget_reuse_address)
-	[get_worker_limit](#settingsget_worker_limit)
-	[get_connection_limit](#settingsget_connection_limit)
-	[get_bind_address](#settingsget_bind_address)
-	[get_case_insensitive_uris](#settingsget_case_insensitive_uris)
-	[get_connection_timeout](#settingsget_connection_timeout)
-	[get_status_message](#settingsget_status_message)
-	[get_status_messages](#settingsget_status_messages)
-	[get_property](#settingsget_property)
-	[get_properties](#settingsget_properties)
-	[get_ssl_settings](#settingsget_ssl_settings)
-	[get_default_headers](#settingsget_default_headers)
-	[set_port](#settingsset_port)
-	[set_root](#settingsset_root)
-	[set_ipc_path](#settingsset_ipc_path)
-   [set_reuse_address](#settingsset_reuse_address)
-	[set_worker_limit](#settingsset_worker_limit)
-	[set_connection_limit](#settingsset_connection_limit)
-	[set_bind_address](#settingsset_bind_address)
-	[set_case_insensitive_uris](#settingsset_case_insensitive_uris)
-	[set_connection_timeout](#settingsset_connection_timeout)
-	[set_status_message](#settingsset_status_message)
-	[set_status_messages](#settingsset_status_messages)
-	[set_property](#settingsset_property)
-	[set_properties](#settingsset_properties)
-	[set_ssl_settings](#settingsset_ssl_settings)
-	[set_default_header](#settingsset_default_header)
-	[set_default_headers](#settingsset_default_headers)

#### Settings::constructor

```C++
Settings( void );
```

Initialises a new class instance; see also [destructor](#settingsdestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::destructor

```C++
virtual ~Settings( void );
```

Clean-up class instance; see also [constructor](#settingsconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Settings::get_port

```C++
uint16_t get_port( void ) const;
```

Retrieves the network port number on which the service will listen.

##### Parameters

n/a

##### Return Value

[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.

##### Exceptions

n/a

#### Settings::get_root

```C++
std::string get_root( void ) const;
```

Retrieves the base path for all resource paths.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the filesystem path.

##### Exceptions

n/a

#### Settings::get_ipc_path

```C++
std::string get_ipc_path( void ) const;
```

Retrieves the path for IPC sockets.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the filesystem path.

##### Exceptions

n/a

#### Settings::get_reuse_address

```C++
bool get_reuse_address( void ) const;
```

Determine if socket option reuse address should be used.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating reuse address socket option.

##### Exceptions

n/a

#### Settings::get_worker_limit

```C++
unsigned int get_worker_limit( void ) const;
```

Retrieves the number of workers (threads) used for processing incoming requests.

##### Parameters

n/a

##### Return Value

[unsigned integer](http://en.cppreference.com/w/cpp/language/types) detailing the number of service workers.

##### Exceptions

n/a

#### Settings::get_connection_limit

```C++
unsigned int get_connection_limit( void ) const;
```

Retrieves the number of allowed pending socket connections.

##### Parameters

n/a

##### Return Value

[unsigned integer](http://en.cppreference.com/w/cpp/language/types) detailing the number of allowed pending socket connections.

##### Exceptions

n/a

#### Settings::get_bind_address

```C++
std::string get_bind_address( void ) const;
```

Retrieves the local network interface card address to attach the service.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) detailing the service bind address.

##### Exceptions

n/a

#### Settings::get_case_insensitive_uris

```C++
bool get_case_insensitive_uris( void ) const;
```

Retrieves a boolean value indicating if the service should use case-insensitive URIs.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating case-insensitive URI processing.

##### Exceptions

n/a

#### Settings::get_connection_timeout

```C++
std::chrono::milliseconds get_connection_timeout( void ) const;
```

Retrieves the number of milliseconds before an inactive socket is forcefully closed.

##### Parameters

n/a

##### Return Value

[Milliseconds](http://en.cppreference.com/w/cpp/chrono/duration) detailing when to close an inactive socket.

##### Exceptions

n/a

#### Settings::get_status_message

```C++
std::string get_status_message( const int code ) const;
```

Retrieves the HTTP status message associated with the supplied status code.

##### Parameters

| name       | type                                                   | default value | direction |
|:----------:|--------------------------------------------------------|:-------------:|:---------:|
| code       | [int](http://en.cppreference.com/w/cpp/language/types) |      n/a      |   input   |

##### Return Value

HTTP status message as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Settings::get_status_messages

```C++
std::map< int, std::string > get_status_messages( void ) const;
```

Retrieves the HTTP status messages.

##### Parameters

n/a

##### Return Value

[std::map](http://en.cppreference.com/w/cpp/container/map) containing the known HTTP status messages.

##### Exceptions

n/a

#### Settings::get_property

```C++
std::string get_property( const std::string& name ) const;
```

Retrieves a string property with the supplied name if it exists; otherwise, an empty string will be returned.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name       | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) property value.

##### Exceptions

n/a

#### Settings::get_properties

```C++
std::map< std::string, std::string > get_properties( void ) const;
```

Retrieves all setting properties.

##### Parameters

n/a

##### Return Value

[std::map](http://en.cppreference.com/w/cpp/container/map) containing the known settings.

##### Exceptions

n/a

#### Settings::get_ssl_settings

```C++
std::shared_ptr< const SSLSettings > get_ssl_settings( void ) const;
```

Retrieves Secure Socket Layer settings.

##### Parameters

n/a

##### Return Value

[SSLSettings](#sslsettings) detailing SSL configuration.

##### Exceptions

n/a

#### Settings::get_default_headers

```C++
std::multimap< std::string, std::string > get_default_headers( void ) const;
```

Retrieves all known default response headers.

##### Parameters

n/a

##### Return Value

[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) containing all known default response headers.

##### Exceptions

n/a

#### Settings::set_port

```C++
void set_port( const uint16_t value );
```

Set the network port on which the service should listen for incoming HTTP requests.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [uint16_t](http://en.cppreference.com/w/cpp/types/integer)          |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_root

```C++
void set_root( const std::string& value );
```

Set the base resource path; this value is prepended to all resource paths.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_ipc_path

```C++
std::string set_ipc_path( const std::string& value ) const;
```

Set the path for IPC sockets.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_reuse_address

```C++
void set_reuse_address( const bool value ) const;
```

Set reuse address socket option.

##### Parameters

| name       | type                                                    | default value | direction |
|:----------:|---------------------------------------------------------|:-------------:|:---------:|
| value      | [Boolean](http://en.cppreference.com/w/c/types/boolean) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_worker_limit

```C++
void set_worker_limit( const unsigned int value );
```

Set the number of threads available for incoming HTTP request processing.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [unsigned integer](http://en.cppreference.com/w/cpp/language/types) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_connection_limit

```C++
void set_connection_limit( const unsigned int value );
```

Set the number of allowed pending connections.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [unsigned integer](http://en.cppreference.com/w/cpp/language/types) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_bind_address

```C++
void set_bind_address( const std::string& value );
```

Set the network interface card address with which the service should attach itself.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_case_insensitive_uris

```C++
void set_case_insensitive_uris( const bool value );
```

Set true for case-insensitive URI handling.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_connection_timeout

```C++
void set_connection_timeout( const std::chrono::seconds& value );

void set_connection_timeout( const std::chrono::milliseconds& value );
```

Set the duration before forcefully closing inactive socket connections.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [seconds](http://en.cppreference.com/w/cpp/chrono/duration)         |      n/a      |   input   |
| value      | [milliseconds](http://en.cppreference.com/w/cpp/chrono/duration)    |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_status_message

```C++
void set_status_message( const int code, const std::string& message );
```

Associate an HTTP status message with an HTTP status code.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| code       | [integer](http://en.cppreference.com/w/cpp/language/types)          |      n/a      |   input   |
| message    | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_status_messages

```C++
void set_status_messages( const std::map< int, std::string >& values );
```

Set HTTP status message/status code mappings.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| values     | [std::map](http://en.cppreference.com/w/cpp/container/map)          |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_property

```C++
void set_property( const std::string& name, const std::string& value );
```

Set a string property value with the associated name.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name       | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_properties

```C++
void set_properties( const std::map< std::string, std::string >& values );
```

Set multiple property values.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| values     | [std::map](http://en.cppreference.com/w/cpp/container/map)          |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_ssl_settings

```C++
void set_ssl_settings( const std::shared_ptr< const SSLSettings >& value );
```

Set Secure Socket Layer configuration.

##### Parameters

| name       | type                                 | default value | direction |
|:----------:|--------------------------------------|:-------------:|:---------:|
| value      | [SSLSettings](#sslsettings)          |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_default_header

```C++
void set_default_header( const std::string& name, const std::string& value );
```

Set a default header value that must be returned for each HTTP request response.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name       | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### Settings::set_default_headers

```C++
void set_default_headers( const std::multimap< std::string, std::string >& values );
```

Set multiple default header values that must be returned for each HTTP request response.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name       | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap)|      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### SSLSettings

Represents Secure Socket Layer configuration.

#### Methods

-	[constructor](#sslsettingsconstructor)
-	[destructor](#sslsettingsdestructor)
-	[has_disabled_http](#sslsettingshas_disabled_http)
-	[has_enabled_sslv2](#sslsettingshas_enabled_sslv2)
-	[has_enabled_sslv3](#sslsettingshas_enabled_sslv3)
-	[has_enabled_tlsv1](#sslsettingshas_enabled_tlsv1)
-	[has_enabled_tlsv11](#sslsettingshas_enabled_tlsv11)
-	[has_enabled_tlsv12](#sslsettingshas_enabled_tlsv12)
-	[has_enabled_compression](#sslsettingshas_enabled_compression)
-	[has_enabled_default_workarounds](#sslsettingshas_enabled_default_workarounds)
-	[has_enabled_single_diffie_hellman_use](#sslsettingshas_enabled_single_diffie_hellman_use)
-	[get_port](#sslsettingsget_port)
-	[get_bind_address](#sslsettingsget_bind_address)
-	[get_certificate](#sslsettingsget_certificate)
-	[get_passphrase](#sslsettingsget_passphrase)
-	[get_private_key](#sslsettingsget_private_key)
-	[get_private_rsa_key](#sslsettingsget_private_rsa_key)
-	[get_certificate_chain](#sslsettingsget_certificate_chain)
-	[get_temporary_diffie_hellman](#sslsettingsget_temporary_diffie_hellman)
-	[get_certificate_authority_pool](#sslsettingsget_certificate_authority_pool)
-	[set_port](#sslsettingsset_port)
-	[set_bind_address](#sslsettingsset_bind_address)
-	[set_http_disabled](#sslsettingsset_http_disabled)
-	[set_sslv2_enabled](#sslsettingsset_sslv2_enabled)
-	[set_sslv3_enabled](#sslsettingsset_sslv3_enabled)
-	[set_tlsv1_enabled](#sslsettingsset_tlsv1_enabled)
-	[set_tlsv11_enabled](#sslsettingsset_tlsv11_enabled)
-	[set_tlsv12_enabled](#sslsettingsset_tlsv12_enabled)
-	[set_compression_enabled](#sslsettingsset_compression_enabled)
-	[set_default_workarounds_enabled](#sslsettingsset_default_workarounds_enabled)
-	[set_certificate](#sslsettingsset_certificate)
-	[set_certificate_authority_pool](#sslsettingsset_certificate_authority_pool)
-	[set_passphrase](#sslsettingsset_passphrase)
-	[set_private_key](#sslsettingsset_private_key)
-	[set_private_rsa_key](#sslsettingsset_private_rsa_key)
-	[set_temporary_diffie_hellman](#sslsettingsset_temporary_diffie_hellman)

#### SSLSettings::constructor

```C++
SSLSettings( void );
```

Initialises a new class instance; see also [destructor](#sslsettingsdestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::destructor

```C++
virtual ~SSLSettings( void );
```

Clean-up class instance; see also [constructor](#sslsettingsconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### SSLSettings::has_disabled_http

```C++
bool has_disabled_http( void ) const;
```

Determine if HTTP has been disabled and that the service should only listen for incoming HTTPS requests.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating that HTTP has been disabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_sslv2

```C++
bool has_enabled_sslv2( void ) const;
```

Determine if SSLv2 has been enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating SSLv2 is enabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_sslv3

```C++
bool has_enabled_sslv3( void ) const;
```

Determine if SSLv3 has been enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating SSLv3 is enabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_tlsv1

```C++
bool has_enabled_tlsv1( void ) const;
```

Determine if TLSv1 has been enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating TLSv1 is enabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_tlsv11

```C++
bool has_enabled_tlsv11( void ) const;
```

Determine if TLSv1.1 has been enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating TLSv1.1 is enabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_tlsv12

```C++
bool has_enabled_tlsv12( void ) const;
```

Determine if TLSv1.2 has been enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating TLSv1.2 is enabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_compression

```C++
bool has_enabled_compression( void ) const;
```

Determine if compression has been enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating compression is enabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_default_workarounds

```C++
bool has_enabled_default_workarounds( void ) const;
```

Determine if the default workarounds are enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating default workaround enabled.

##### Exceptions

n/a

#### SSLSettings::has_enabled_single_diffie_hellman_use

```C++
bool has_enabled_single_diffie_hellman_use( void ) const;
```

Determine if single Diffie-Hellman use is enabled.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating single Diffie-Hellman use.

##### Exceptions

n/a

#### SSLSettings::get_port

```C++
uint16_t get_port( void ) const;
```

Retrieves the network port number on which the service will listen.

##### Parameters

n/a

##### Return Value

[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.

##### Exceptions

n/a

#### SSLSettings::get_bind_address

```C++
std::string get_bind_address( void ) const;
```

Retrieves the local network interface card address to attach the service.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) detailing the service bind address.

##### Exceptions

n/a

#### SSLSettings::get_certificate

```C++
std::string get_certificate( void ) const;
```

Retrieves the filename of the SSL certificate.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate filename.

##### Exceptions

n/a

#### SSLSettings::get_passphrase

```C++
std::string get_passphrase( void ) const;
```

Retrieves SSL certificate passphrase.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate passphrase.

##### Exceptions

n/a

#### SSLSettings::get_private_key

```C++
std::string get_private_key( void ) const;
```

Retrieves the filename of the private key.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) private key filename.

##### Exceptions

n/a

#### SSLSettings::get_private_rsa_key

```C++
std::string get_private_rsa_key( void ) const;
```

Retrieves the filename of the RSA private key.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate filename.

##### Exceptions

n/a

#### SSLSettings::get_certificate_chain

```C++
std::string get_certificate_chain( void ) const;
```

Retrieves the filename of the certificate chain.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate chain filename.

##### Exceptions

n/a

#### SSLSettings::get_temporary_diffie_hellman

```C++
std::string get_temporary_diffie_hellman( void ) const;
```

Retrieves the filename for the temporary Diffie-Hellman.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) diffie hellman filename.

##### Exceptions

n/a

#### SSLSettings::get_certificate_authority_pool

```C++
std::string get_certificate_authority_pool( void ) const;
```

Retrieves the filename from the certificate authority pool.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) diffie hellman filename.

##### Exceptions

n/a

#### SSLSettings::set_port

```C++
void set_port( const uint16_t value );
```

Set the network port on which the service should listen for incoming HTTPS requests.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [uint16_t](http://en.cppreference.com/w/cpp/types/integer)          |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_bind_address

```C++
void set_bind_address( const std::string& value );
```

Set the network interface card address with which the service should attach itself.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_http_disabled

```C++
void set_http_disabled( const bool value );
```

Set true to disable unencrypted HTTP service access.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_sslv2_enabled

```C++
void set_sslv2_enabled( const bool value );
```

Set true to enable SSLv2.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_sslv3_enabled

```C++
void set_sslv3_enabled( const bool value );
```

Set true to enable SSLv3.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_tlsv1_enabled

```C++
void set_tlsv1_enabled( const bool value );
```

Set true to enable TLSv1.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_tlsv11_enabled

```C++
void set_tlsv11_enabled( const bool value );
```

Set true to enable TLSv1.1.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_tlsv12_enabled

```C++
void set_tlsv12_enabled( const bool value );
```

Set true to enable TLSv1.2.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_compression_enabled

```C++
void set_compression_enabled( const bool value );
```

Set true to enable compression.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_default_workarounds_enabled

```C++
void set_default_workarounds_enabled( const bool value );
```

Set true to enable default workarounds.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_single_diffie_hellman_use_enabled

```C++
void set_single_diffie_hellman_use_enabled( const bool value );
```

Set true to enable single Diffie-Hellman use.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [bool](http://en.cppreference.com/w/c/types/boolean)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_certificate

```C++
void set_certificate( const Uri& value );
```

Set the filename to the SSL certificate.

##### Parameters

| name       | type        | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value      | [Uri](#uri) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_certificate_chain

```C++
void set_certificate_chain( const Uri& value );
```

Set the filename to the SSL certificate chain.

##### Parameters

| name       | type        | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value      | [Uri](#uri) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_certificate_authority_pool

```C++
void set_certificate_authority_pool( const Uri& value );
```

Set the filename to the SSL certificate authority pool.

##### Parameters

| name       | type        | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value      | [Uri](#uri) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_passphrase

```C++
void set_passphrase( const std::string& value );
```

Set the filename to the SSL certificate passphrase.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_private_key

```C++
void set_private_key( const Uri& value );
```

Set the filename to the SSL private key.

##### Parameters

| name       | type        | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value      | [Uri](#uri) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_private_rsa_key

```C++
void set_private_rsa_key( const Uri& value );
```

Set the filename to the SSL private RSA key.

##### Parameters

| name       | type        | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value      | [Uri](#uri) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### SSLSettings::set_temporary_diffie_hellman

```C++
void set_temporary_diffie_hellman( const Uri& value );
```

Set the filename to temporary Diffie-Hellman.

##### Parameters

| name       | type        | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value      | [Uri](#uri) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### StatusCode

[Enumeration](http://en.cppreference.com/w/cpp/language/enum) of HTTP response status codes as outlined in [RFC 7231 sub-section 6.1](https://tools.ietf.org/html/rfc7231#section-6.1).

### Uri

Represents a Uniform Resource Identifier as specified in RFC 3986.

#### Methods

-	[constructor](#uriconstructor)
-	[destructor](#uridestructor)
-	[is_relative](#uriis_relative)
-	[is_absolute](#uriis_absolute)
-	[to_string](#urito_string)
-	[is_valid](#uriis_valid)
-	[parse](#uriparse)
-	[decode](#uridecode)
-	[decode_parameter](#uridecode_parameter)
-	[encode](#uriencode)
-	[encode_parameter](#uriencode_parameter)
-	[get_port](#uriget_port)
-	[get_path](#uriget_path)
-	[get_query](#uriget_query)
-	[get_scheme](#uriget_scheme)
-	[get_fragment](#uriget_fragment)
-	[get_username](#uriget_username)
-	[get_password](#uriget_password)
-	[get_authority](#uriget_authority)
-	[get_query_parameters](#uriget_query_parameters)

#### Uri::constructor

```C++
explicit Uri( const std::string& value, bool relative = false );

Uri( const Uri& original );
```

Initialises a new class instance; see also [destructor](#uridestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### Uri::destructor

```C++
virtual ~Uri( void );
```

Clean-up class instance; see also [constructor](#uriconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### Uri::is_relative

```C++
bool is_relative( void ) const;
```

Determines if the URI is a relative path.

##### Parameters

n/a

##### Return Value

Boolean true if relative, else false.

##### Exceptions

n/a

#### Uri::is_absolute

```C++
bool is_absolute( void ) const;
```

Determines if the URI is an absolute path.

##### Parameters

n/a

##### Return Value

Boolean true if relative, else false.

##### Exceptions

n/a

#### Uri::to_string

```C++
std::string to_string( void ) const;
```

Convert the Uri instance to a string representation.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the URI's contents.

##### Exceptions

n/a

#### Uri::is_valid

```C++
static bool is_valid( const std::string& value );
```

Determines if the supplied string is a valid URI.

##### Parameters

n/a

##### Return Value

Boolean true if valid, else false.

##### Exceptions

n/a

#### Uri::parse

```C++
static Uri parse( const std::string& value );
```

Parse the string to a URI instance.

##### Parameters

| name       | type                                                                | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) |      n/a      |   input   |

##### Return Value

Uri instance.

##### Exceptions

n/a

#### Uri::decode

```C++
static std::string decode( const std::string& value );
```

URL percent-decoding functionality.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |

##### Return Value

Decoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.

##### Exceptions

n/a

#### Uri::decode_parameter

```C++
static std::string decode_parameter( const std::string& value );
```

URL parameter percent-decoding functionality.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |

##### Return Value

Decoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.

##### Exceptions

n/a

#### Uri::encode

```C++
static std::string encode( const std::string& value );
```

URL percent-encoding functionality.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |

##### Return Value

Encoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.

##### Exceptions

n/a

#### Uri::encode_parameter

```C++
static std::string encode_parameter( const std::string& value );
```

URL parameter percent-encoding functionality.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |

##### Return Value

Encoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.

##### Exceptions

n/a

#### Uri::get_port

```C++
uint16_t get_port( void ) const;
```

Retrieves the network port number.

##### Parameters

n/a

##### Return Value

[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.

##### Exceptions

n/a

#### Uri::get_path

```C++
std::string get_path( void ) const;
```

Retrieves the path segment.

##### Parameters

n/a

##### Return Value

Path segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Uri::get_query

```C++
std::string get_query( void ) const;
```

Retrieves the query segment.

##### Parameters

n/a

##### Return Value

Query segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Uri::get_scheme

```C++
std::string get_scheme( void ) const;
```

Retrieves the scheme segment.

##### Parameters

n/a

##### Return Value

Scheme segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Uri::get_fragment

```C++
std::string get_fragment( void ) const;
```

Retrieves the fragment segment.

##### Parameters

n/a

##### Return Value

Scheme segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Uri::get_username

```C++
std::string get_username( void ) const;
```

Retrieves the username segment.

##### Parameters

n/a

##### Return Value

Username segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Uri::get_password

```C++
std::string get_password( void ) const;
```

Retrieves the password segment.

##### Parameters

n/a

##### Return Value

Password segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Uri::get_authority

```C++
std::string get_authority( void ) const;
```

Retrieves the authority segment.

##### Parameters

n/a

##### Return Value

Authority segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).

##### Exceptions

n/a

#### Uri::get_query_parameters

```C++
std::multimap< std::string, std::string > get_query_parameters( void ) const;
```

Retrieves parsed query parameters.

##### Parameters

n/a

##### Return Value

[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) of decoded query parameters.

##### Exceptions

n/a


### WebSocket

Represents a WebSocket.

#### Methods

-	[constructor](#websocketconstructor)
-	[destructor](#websocketdestructor)
-	[is_open](#websocketis_open)
-	[is_closed](#websocketis_closed)
-	[close](#websocketclose)
-	[send](#websocketsend)
-	[get_key](#websocketget_key)
-	[get_logger](#websocketget_logger)
-	[get_open_handler](#websocketget_open_handler)
-	[get_close_handler](#websocketget_close_handler)
-	[get_error_handler](#websocketget_error_handler)
-	[get_message_handler](#websocketget_message_handler)
-	[set_key](#websocketset_key)
-	[set_logger](#websocketset_logger)
-	[set_open_handler](#websocketset_open_handler)
-	[set_close_handler](#websocketset_close_handler)
-	[set_error_handler](#websocketset_error_handler)
-	[set_message_handler](#websocketset_message_handler)

#### WebSocket::constructor

```C++
WebSocket( void );
```

Initialises a new class instance; see also [destructor](#websocketdestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocket::destructor

```C++
virtual ~WebSocket( void );
```

Clean-up class instance; see also [constructor](#websocketconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### WebSocket::is_open

```C++
bool is_open( void ) const;
```

Determine if the underlying socket is active.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) value indicating the socket is active.

##### Exceptions

n/a

#### WebSocket::is_open

```C++
bool is_closed( void ) const;
```

Determine if the underlying socket is inactive.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) value indicating the socket is inactive.

##### Exceptions

n/a

#### WebSocket::close

```C++
void close( void );
```

Close the socket.

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a         

#### WebSocket::send

```C++
void send( const Bytes& body, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );

void send( const std::string& body, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );

void send( const WebSocketMessage::OpCode opcode, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );

void send( const std::shared_ptr< WebSocketMessage > message, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );
```

Transmit a WebSocket message.

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a  

#### WebSocket::get_key

```C++
std::string get_key( void ) const;
```

Retrieve a unique key identifying this instance.

##### Parameters

n/a

##### Return Value

[std::string](http://en.cppreference.com/w/cpp/string/basic_string) unique identifier.

##### Exceptions

n/a

#### WebSocket::get_logger

```C++
std::shared_ptr< Logger > get_logger( void ) const;
```

Retrieve the logging instance used by this WebSocket.

##### Parameters

n/a

##### Return Value

[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) referencing [Logger](#logger) used.

##### Exceptions

n/a

#### WebSocket::get_open_handler

```C++
std::function< void ( const std::shared_ptr< WebSocket > ) > get_open_handler( void ) const;
```

Retrieve the open socket handler.

##### Parameters

n/a

##### Return Value

[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket open handler.

##### Exceptions

n/a

#### WebSocket::get_close_handler

```C++
std::function< void ( const std::shared_ptr< WebSocket > ) > get_close_handler( void ) const;
```

Retrieve the socket closed handler.

##### Parameters

n/a

##### Return Value

[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket close handler.

##### Exceptions

n/a

#### WebSocket::get_error_handler

```C++
std::function< void ( const std::shared_ptr< WebSocket >, const std::error_code ) > get_error_handler( void ) const;
```

Retrieve socket error handler.

##### Parameters

n/a

##### Return Value

[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket error handler.

##### Exceptions

n/a

#### WebSocket::get_message_handler

```C++
std::function< void ( const std::shared_ptr< WebSocket >, const std::shared_ptr< WebSocketMessage > ) > get_message_handler( void ) const;
```

Retrieve socket message handler.

##### Parameters

n/a

##### Return Value

[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket message handler.

##### Exceptions

n/a

#### WebSocket::set_key

```C++
void set_key( const std::string& value );
```

Set the WebSocket unique key.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocket::set_logger

```C++
void set_logger( const std::shared_ptr< Logger >& value );
```

Set [Logger](#logger) instance to use internally by the instance.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr)         |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocket::set_open_handler

```C++
void set_open_handler( const std::function< void ( const std::shared_ptr< WebSocket > ) >& value );
```

Set a callback to be invoked once the socket connection has been established to a remote endpoint.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocket::set_close_handler

```C++
void set_close_handler( const std::function< void ( const std::shared_ptr< WebSocket > ) >& value );
```

Set a callback to be invoked once the socket connection has been terminated.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocket::set_error_handler

```C++
void set_error_handler( const std::function< void ( const std::shared_ptr< WebSocket >, const std::error_code ) >& value );
```

Set a callback to be invoked if the socket encounters an error.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocket::set_message_handler

```C++
void set_message_handler( const std::function< void ( const std::shared_ptr< WebSocket >, const std::shared_ptr< WebSocketMessage > ) >& value );
```

Set a callback to be invoked when a message is received.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

### WebSocketMessage

Class to abstract the over-engineered WebSocket packet format.

#### Methods

-	[constructor](#websocketmessageconstructor)
-	[destructor](#websocketmessagedestructor)
-	[to_bytes](#websocketmessageto_bytes)
-	[get_data](#websocketmessageget_data)
-	[get_opcode](#websocketmessageget_opcode)
-	[get_mask](#websocketmessageget_mask)
-	[get_length](#websocketmessageget_length)
-	[get_extended_length](#websocketmessageget_extended_length)
-	[get_mask_flag](#websocketmessageget_mask_flag)
-	[get_final_frame_flag](#websocketmessageget_final_frame_flag)
-	[get_reserved_flags](#websocketmessageget_resserved_flags)
-	[set_data](#websocketmessageset_data)
-	[set_opcode](#websocketmessageset_opcode)
-	[set_mask](#websocketmessageset_mask)
-	[set_length](#websocketmessageset_length)
-	[set_extended_length](#websocketmessageset_extended_length)
-	[set_mask_flag](#websocketmessageset_mask_flag)
-	[set_final_frame_flag](#websocketmessageset_final_frame_flag)
-	[set_reserved_flags](#websocketmessageset_reserved_flags)

#### WebSocketMessage::constructor

```C++
WebSocketMessage( void );

WebSocketMessage( const WebSocketMessage& original );

WebSocketMessage( const OpCode code, const Bytes& data = { } );

WebSocketMessage( const OpCode code, const std::string& data );

WebSocketMessage( const OpCode code, const Bytes& data, const std::uint32_t mask );

WebSocketMessage( const OpCode code, const std::string& data, const std::uint32_t mask );
```

Initialises a new class instance; see also [destructor](#websocketmessagedestructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::destructor

```C++
virtual ~WebSocketMessage( void );
```

Clean-up class instance; see also [constructor](#websocketmessageconstructor).

##### Parameters

n/a

##### Return Value

n/a

##### Exceptions

No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).

#### WebSocketMessage::to_bytes

```C++
Bytes to_bytes( void ) const;
```

Convert instance to a collection of [Bytes](#bytebytes)

##### Parameters

n/a

##### Return Value

[Bytes](#bytebytes) containing a representation of the current WebSocketMessage state.

##### Exceptions

n/a

#### WebSocketMessage::get_data

```C++
Bytes get_data( void ) const;
```

Get the data segment.

##### Parameters

n/a

##### Return Value

[Bytes](#bytebytes) containing message data.

##### Exceptions

n/a

#### WebSocketMessage::get_opcode

```C++
OpCode get_opcode( void ) const;
```

Get the operation code.

##### Parameters

n/a

##### Return Value

[WebSocketMessage::OpCode](#websocketmessageopcode) detailing operation code in use.

##### Exceptions

n/a

#### WebSocketMessage::get_mask

```C++
std::uint32_t get_mask( void ) const;
```

Get message mask.

##### Parameters

n/a

##### Return Value

[std::uint32_t](http://en.cppreference.com/w/cpp/types/integer) detailing message length.

##### Exceptions

n/a

#### WebSocketMessage::get_length

```C++
std::uint8_t get_length( void ) const;
```

Get message data length.

##### Parameters

n/a

##### Return Value

[std::uint8_t](http://en.cppreference.com/w/cpp/types/integer) detailing the mask to use on message data.

##### Exceptions

n/a

#### WebSocketMessage::get_extended_length

```C++
std::uint64_t get_extended_length( void ) const;
```

Get message data extended length.

##### Parameters

n/a

##### Return Value

[std::uint64_t](http://en.cppreference.com/w/cpp/types/integer) detailing message extended length.

##### Exceptions

n/a

#### WebSocketMessage::get_mask_flag

```C++
bool get_mask_flag( void ) const;
```

Get a flag indicating if a mask is in use.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating a mask is in use.

##### Exceptions

n/a

#### WebSocketMessage::get_mask_flag

```C++
bool get_final_frame_flag( void ) const;
```

Get a flag indicating if this message is the final frame.

##### Parameters

n/a

##### Return Value

[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating a final frame.

##### Exceptions

n/a

#### WebSocketMessage::get_reserved_flags

```C++
std::tuple< bool, bool, bool > get_reserved_flags( void ) const;
```

Get reserved flags.

##### Parameters

n/a

##### Return Value

[std::tuple](http://en.cppreference.com/w/cpp/utility/tuple) of reserved flags.

##### Exceptions

n/a

#### WebSocketMessage::set_data

```C++
void set_data( const Bytes& value );

void set_data( const std::string& value );
```

Set a callback to be invoked when a message is received.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [Bytes](#bytebytes)                                                           |      n/a      |   input   |
| value      | [std::string](http://en.cppreference.com/w/cpp/string/basic_string)           |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::set_opcode

```C++
void set_opcode( const OpCode value );
```

Set message operation code.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [WebSocketMessage::OpCode](#websocketmessageopcode)                           |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::set_mask

```C++
void set_mask( const std::uint32_t value );
```

Set message mask, this will also set the mask flag equal to true.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::uint32_t](http://en.cppreference.com/w/cpp/types/integer)               |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::set_length

```C++
void set_length( const std::uint8_t value );
```

Set message length.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::uint8_t](http://en.cppreference.com/w/cpp/types/integer)                |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::set_extended_length

```C++
void set_extended_length( const std::uint64_t value );
```

Set message extended length.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [std::uint64_t](http://en.cppreference.com/w/cpp/types/integer)               |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::set_extended_length

```C++
void set_mask_flag( const bool value );
```

Setting true indicates a message mask is in place.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [Boolean](http://en.cppreference.com/w/c/types/boolean)                       |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::set_final_frame_flag

```C++
void set_final_frame_flag( const bool value );
```

Setting true indicates this is the final frame in a sequence of messages.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value      | [Boolean](http://en.cppreference.com/w/c/types/boolean)                       |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::set_reserved_flags

```C++
void set_reserved_flags( const bool rsv1, const bool rsv2, const bool rsv3 );
```

Set reserved flags.

##### Parameters

| name       | type                                                                          | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| rsv1       | [Boolean](http://en.cppreference.com/w/c/types/boolean)                       |      n/a      |   input   |
| rsv2       | [Boolean](http://en.cppreference.com/w/c/types/boolean)                       |      n/a      |   input   |
| rsv3       | [Boolean](http://en.cppreference.com/w/c/types/boolean)                       |      n/a      |   input   |

##### Return Value

n/a

##### Exceptions

n/a

#### WebSocketMessage::OpCode

```C++
class WebSocketMessage
{
    enum OpCode : uint8_t
    {
        CONTINUATION_FRAME     = 0x00,
        TEXT_FRAME             = 0x01,
        BINARY_FRAME           = 0x02,
        CONNECTION_CLOSE_FRAME = 0x08,
        PING_FRAME             = 0x09,
        PONG_FRAME             = 0x0A
    };
}
```

[Enumeration](http://en.cppreference.com/w/cpp/language/enum) detailing WebSocket message operation codes.

### Further Reading

[C++ Standard](https://isocpp.org/std/the-standard) - The current ISO C++ standard is officially known as ISO International Standard ISO/IEC 14882:2014(E) – Programming Language C++. Want to read the ISO C++ standard, or working drafts of the standard? You have several options, most of them free.

[C++ Reference](http://en.cppreference.com/) - Comprehensive C++ and Standard Template Library (STL) reference.

[Effective STL](https://www.amazon.com/Effective-STL-Specific-Standard-Template/dp/0201749629) - Written for the intermediate or advanced C++ programmer, renowned C++ expert Scott Meyers provides essential techniques for getting more out of the Standard Template Library in Effective STL, a tutorial for doing more with this powerful library.

[Effective C++](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876) - “Every C++ professional needs a copy of Effective C++. It is an absolute must-read for anyone thinking of doing serious C++ development. If you’ve never read Effective C++ and you think you know everything about C++, think again.” — Steve Schirripa, Software Engineer, Google.

---

### DESIGN

Overview
--------

This document is intended to communicate core architectural decisions within the system. For this reason alone, accuracy has suffered. It does not concern itself with interface specifics and primarily focuses on architectural decisions made during the design and development phase. See [API](API.md) for contract details.

All class definitions within the system strictly adhere to the [Opaque Pointer](https://en.wikipedia.org/wiki/Opaque_pointer) idiom. However, this level of detail in the following suite of class diagrams is omitted for clarity, along with pointers, references and other background noise.

Unless otherwise specified, all primary data-types originate within the Standard Template Library (STL).

Interpretation
--------------

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/pdf/rfc2119.pdf).

Table of Contents
-----------------

1.	[Overview](#overview)
2.	[Interpretation](#interpretation)
3.	[Terminology](#terminology)
4.	[System Entities](#system-entities)
5.	[Entity Interactions](#entity-interactions)
6.	[Dependency Tree](#dependency-tree)
7.	[Event Loop](#event-loop)
8.	[Thread Allocation](#thread-allocation)
9.	[Future Direction](#future-direction)
10.	[Further Reading](#further-reading)

Terminology
-----------

| Term         | Definition                                                                                                                  |
|--------------|-----------------------------------------------------------------------------------------------------------------------------|
| Resource     | A network addressable entity, i.e Queue.                                                                                    |
| Service      | A server responsible for request routing and processing.                                                                    |
| Client       | A remote endpoint responsible for generating requests.                                                                      |
| Logger       | A component making a systematic recording of events, observations, or measurements.                                         |
| Charset      | A CHARacter SET is used to represent a repertoire of symbols, i.e UTF-8.                                                    |
| URI          | Uniform Resource Identifier.                                                                                                |
| UUID         | Universally Unique IDentifier.                                                                                              |
| Path         | String identifier uniquely addressing a resource.                                                                           |

System Entities
---------------

-	[Bytes](#bytes)
-	[Resource](#resource)
-	[Callback](#callback)
-	[StatusCode](#statuscode)
-	[String::Option](#stringoption)
-	[String](#string)
-	[URI](#uri)
-	[Request](#request)
-	[Response](#response)
-	[Session](#session)
-	[SSLSettings](#sslsettings)
-	[Settings](#settings)
-	[WebSocket](#websocket)
-	[WebSocketMessage](#websocketmessage)
-	[WebSocketMessage::OpCode](#websocketmessageopcode)
-	[Logger](#logger)
-	[Logger::Level](#loggerlevel)
-	[Service](#service)

### Bytes

Bytes provides container functionality with STL [vector](http://en.cppreference.com/w/cpp/container/vector) collection semantics.

### Resource

Resource represents a network communication endpoint. This is the primary data-structure used throughout to represent RESTful resources. All resource-specific filtration, request processing, and authentication must be placed on this entity.

```
+------------------------------------------------------------------------+
|                                <<class>>                               |
|                                Resources                               |
+------------------------------------------------------------------------+
| + set_path(string)                                               void  |
| + set_paths(set<string>)                                         void  |
| + set_default_header(string,string)                              void  |
| + set_default_headers(multimap<string,string>)                   void  |
| + set_error_handler(Callback)                                    void  |
| + set_authentication_handler(void)                               void  |
| + set_method_handler(string,Callback)                            void  |
+------------------------------------------------------------------------+
```

### Callback

Represents a functor with variable parameters and return value; this is used to help illustrate the design without introducing unnecessary complexity.

```
+-----------------+
|   <<typedef>>   |
|    Callback     |
+-----------------+
|  std::function  |
+-----------------+
```

### StatusCode

[Enumeration](http://en.cppreference.com/w/cpp/language/enum) of HTTP response status codes as outlined in [RFC 7231 sub-section 6.1](https://tools.ietf.org/html/rfc7231#section-6.1).

```
 +---------------------------+
 |         <<enum>>          |
 |        StatusCode         |
 +---------------------------+
 | See RFC 7231 for details. |
 +---------------------------+
```

### String::Option

[Enumeration](http://en.cppreference.com/w/cpp/language/enum) of possible string case sensitivity options.

```
 +--------------------+
 |      <<enum>>      |
 |   String::Option   |
 +--------------------+
 | + CASE_SENSITIVE   |
 | + CASE_INSENSITIVE |
 +------------------ -+
```

### String

Utility class with static scope offering a common suite of string manipulation routines.

```
 +---------------------------------------------------------------+
 |                           <<static>>                          |
 |                             String                            |
 +---------------------------------------------------------------+
 | + to_bytes(string)                             Bytes          |
 | + lowercase(string)                            string         |
 | + uppercase(string,string)                     string         |
 | + format(char*,...)                            string         |
 | + join(multimap<string,string>,string,string)  string         |
 | + remove(string,string,Option)                 string         |
 | + replace(string,string,string,Option)         string         |
 | + split(string,string)                         vector<string> |
 +--------------------------------^------------------------------+
                                  |
                                  |
                                  |
                 +----------------v----------------+
                 |             <<enum>>            |
                 |          String::Option         |
                 +---------------------------------+
                 | See String::Option for details. |
                 +---------------------------------+
```

### URI

Represents a Uniform Resource Identifier as specified in [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt).

> A generic URI is of the form:
>
> scheme:[//[user:password@]host\[:port]][/]path[?query][#fragment]

```
 +-------------------------------------------------------+
 |                        <<class>>                      |
 |                           Uri                         |
 +-------------------------------------------------------+
 | + is_relative(void)           boolean                 |
 | + is_absolute(void)           boolean                 |
 | + is_valid(string)            boolean                 |
 | + parse(string)               Uri                     |
 | + to_string(void)             string                  |
 | + decode(string)              string                  |
 | + decode_parameter(string)    string                  |
 | + encode(string)              string                  |
 | + encode_parameter(string)    string                  |
 | + get_port(void)              unsigned 16-bit integer |
 | + get_path(void)              string                  |
 | + get_query(void)             string                  |
 | + get_scheme(void)            string                  |
 | + get_fragment(void)          string                  |
 | + get_username(void)          string                  |
 | + get_password(void)          string                  |
 | + get_authority(void)         string                  |
 | + get_query_parameters(void)  multimap<string,string> |
 +-------------------------------------------------------+
```

### Request

Represents an HTTP request with additional helper methods for manipulating data and code readability.

```
/* Detailed source-code truncated for AI context efficiency. */
```

### Response

Represents an HTTP response with additional helper methods for manipulating data and improving code readability.

```
/* Detailed source-code truncated for AI context efficiency. */
```

### Session

Represents a conversation between a client and the service. Internally, this class holds the network state and exposes public functionality to interact with the service event-loop for asynchronous data acquisition and/or sleep states.

```
/* Detailed source-code truncated for AI context efficiency. */
```

### SSLSettings

Represents Secure Socket Layer service configuration.

```
/* Detailed source-code truncated for AI context efficiency. */
```

### Settings

Represents the primary point of Service and Logger configuration.

```
/* Detailed source-code truncated for AI context efficiency. */
```

### WebSocket

Represents a WebSocket connection. Internally, this class holds the network state and exposes public functionality for full-duplex client interaction.

```
/* Detailed source-code truncated for AI context efficiency. */
```
### WebSocketMessage

Class representing a single WebSocket data message.

```
/* Detailed source-code truncated for AI context efficiency. */
```

### WebSocketMessage::OpCode

[Enumeration](http://en.cppreference.com/w/cpp/language/enum) is used in conjunction with the [WebSocket](#websocket) and [WebSocketMessage](#websocketmessage) to detail the message category.

```
 +--------------------------+
 |          <<enum>>        |
 | WebSocketMessage::OpCode |
 +--------------------------+
 | CONTINUATION_FRAME       |
 | TEXT_FRAME               |
 | BINARY_FRAME             |
 | CONNECTION_CLOSE_FRAME   |
 | PING_FRAME               |
 | PONG_FRAME               |
 +--------------------------+
```

### Logger

Interface detailing the required contract for logger extensions. No default logger is supplied with the codebase; it is the responsibility of third-party developers to implement the desired characteristics.

```
 +-----------------------------------------------+
 |                 <<interface>>                 |
 |                    Logger                     |
 +-----------------------------------------------+
 | + stop(void)                             void |
 | + start(Settings)                        void |
 | + log(Logger::Level,string)              void |
 | + log_if(condition,Logger::Level,string) void |
 +----------------------^------------------------+
                        |
                        |
                        |
        +---------------v----------------+
        |            <<enum>>            |
        |         Logger::Level          |
        +--------------------------------+
        | See Logger::Level for details. |
        +--------------------------------+
```

### Logger::Level

[Enumeration](http://en.cppreference.com/w/cpp/language/enum) is used in conjunction with the [Logger interface](#logger) to detail the level of severity towards a particular log entry.

```
 +---------------+
 |   <<enum>>    |
 | Logger::Level |
 +---------------+
 | INFO          |
 | DEBUG         |
 | FATAL         |
 | ERROR         |
 | WARNING       |
 | SECURITY      |
 +---------------+
```

### Service

The service is responsible for managing the publicly available RESTful resources, HTTP compliance, scheduling of the socket data and ensuring incoming requests are processed in a timely fashion.

```
/* Detailed source-code truncated for AI context efficiency. */
```

Entity Interactions
-------------------

### Request Processing

```
/* Detailed source-code truncated for AI context efficiency. */
```

Dependency Tree
---------------
```
                +----------------------------+
                |          Restbed           |
                +----------------------------+
                | Asynchronous Web Framework |
                +----------------------------+
                              |
           +------------------+------------------+
           |                                    |
 +--------------------+                +----------------------+
 |        ASIO        |                |       OpenSSL        |
 +--------------------+                +----------------------+
 | Asynchronous I/O . |                | Secure Socket Layer. |
 +--------------------+                +----------------------+
```

Event Loop
----------

The asynchronous nature of the framework is achieved by employing an [event-reaction loop](https://en.wikipedia.org/wiki/Event_loop), allowing Non-Block I/O and timed waits for external stimuli. This architectural decision allows the framework to scale and address the [C10K Problem](https://en.wikipedia.org/wiki/C10k_problem), all the while keeping resource consumption to a minimum and optimising thread allocation.

Thread allocation
-----------------

By default, the framework will only allocate a single thread to process all incoming requests and scheduled workloads. This can be increased by altering the `Settings::set_worker_limit` attribute. It is recommended that you should not exceed the available hardware limit. See below for a suggested implementation.

``` C++
#include <thread>
#include <cstdlib>
#include <restbed>

using namespace restbed;

int main( const int, const char** )
{
    auto resource = make_shared< Resource >( );
    resource->set_path( "/resource" );
    resource->set_method_handler( "GET", get_method_handler );
    
    auto settings = make_shared< Settings >( );
    settings->set_worker_limit( std::thread::hardware_concurrency( ) );
    
    Service service;
    service.publish( resource );
    service.start( settings );
    
    return EXIT_SUCCESS;
}
``` 

Future Direction
----------------

 It is the aim of the core development team to remove ASIO as a dependency due to the tight coupling of IO and Event Loop principles. This setup leads to cross-contamination of concerns and forces design decisions on dependents.

 WebSocketManager and ResourceCache shall be exposed for customisation by third-party developers.

 Application Layer (HTTP, HTTP2, SPDY, etc) will be exposed for customisation by third-party developers.

 Network Layer (TCP, UDP, RS232, etc) shall be exposed for customisation by third-party developers.

 The secure socket logic layer will allow alternative implementations, such as OpenSSL, GnuTLS, PolarSSL, MatrixSSL, etc.

Further Reading
---------------

[Opaque Pointer](https://en.wikipedia.org/wiki/Opaque_pointer) - In computer programming, an opaque pointer is a special case of an opaque data type, a datatype declared to be a pointer to a record or data structure of some unspecified type.

[Uniform Resource Identifier (URI): Generic Syntax](https://tools.ietf.org/html/rfc3986) - A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme.

[C10K Problem](https://en.wikipedia.org/wiki/C10k_problem) - The C10K Problem refers to the inability of a server to scale beyond 10,000 connections or clients due to resource exhaustion. Servers that employ the thread-per-client model, for example, can be confounded when pooled threads spend too much time waiting on blocking operations.

[ASIO](http://think-async.com/) - Asio is a cross-platform C++ library for network and low-level I/O programming that provides developers with a consistent asynchronous model using a modern C++ approach.

[Eventloop](https://en.wikipedia.org/wiki/Event_loop) - In computer science, the event loop, message dispatcher, message loop, message pump, or run loop is a programming construct that waits for and dispatches events or messages in a program. It works by requesting some internal or external "event provider" (that generally blocks the request until an event has arrived), and then it calls the relevant event handler ("dispatches the event"). The event-loop may be used in conjunction with a reactor if the event provider follows the file interface, which can be selected or 'polled' (the Unix system call, not actual polling). The event loop almost always operates asynchronously with the message originator.

---