README.md
1# Simple-Web-Server
2
3A very simple, fast, multithreaded, platform independent HTTP and HTTPS server and client library implemented using C++11 and Asio (both Boost.Asio and standalone Asio can be used). Created to be an easy way to make REST resources available from C++ applications.
4
5See https://gitlab.com/eidheim/Simple-WebSocket-Server for an easy way to make WebSocket/WebSocket Secure endpoints in C++. Also, feel free to check out the new C++ IDE supporting C++11/14/17: https://gitlab.com/cppit/jucipp.
6
7## Features
8
9* Asynchronous request handling
10* Thread pool if needed
11* Platform independent
12* HTTP/1.1 supported, including persistent connections
13* HTTPS supported
14* Chunked transfer encoding and server-sent events
15* Can set timeouts for request/response and content
16* Can set max request/response size
17* Sending outgoing messages is thread safe
18* Client creates necessary connections and perform reconnects when needed
19
20See also [benchmarks](https://gitlab.com/eidheim/Simple-Web-Server/blob/master/docs/benchmarks.md) for a performance comparisons to a few other HTTP libraries.
21
22## Usage
23
24See [http_examples.cpp](https://gitlab.com/eidheim/Simple-Web-Server/blob/master/http_examples.cpp) or
25[https_examples.cpp](https://gitlab.com/eidheim/Simple-Web-Server/blob/master/https_examples.cpp) for example usage.
26The following server resources are setup using regular expressions to match request paths:
27* `POST /string` - responds with the posted string.
28* `POST /json` - parses the request content as JSON, and responds with some of the parsed values.
29* `GET /info` - responds with information extracted from the request.
30* `GET /match/([0-9]+)` - matches for instance `/match/123` and responds with the matched number `123`.
31* `GET /work` - starts a thread, simulating heavy work, and responds when the work is done.
32* `GET` - a special default_resource handler is called when a request path does not match any of the above resources.
33This resource responds with the content of files in the `web/`-folder if the request path identifies one of these files.
34
35[Documentation](https://eidheim.gitlab.io/Simple-Web-Server/annotated.html) is also available, generated from the master branch.
36
37## Dependencies
38
39* Boost.Asio or standalone Asio
40* Boost is required to compile the examples
41* For HTTPS: OpenSSL libraries
42
43Installation instructions for the dependencies needed to compile the examples on a selection of platforms can be seen below.
44Default build with Boost.Asio is assumed. Turn on CMake option `USE_STANDALONE_ASIO` to instead use standalone Asio.
45
46### Debian based distributions
47
48```sh
49sudo apt-get install libssl-dev libboost-filesystem-dev libboost-thread-dev
50```
51
52### Arch Linux based distributions
53
54```sh
55sudo pacman -S boost
56```
57
58### MacOS
59
60```sh
61brew install openssl boost
62```
63
64## Compile and run
65
66Compile with a C++11 compliant compiler:
67```sh
68cmake -H. -Bbuild
69cmake --build build
70```
71
72### HTTP
73
74Run the server and client examples: `./build/http_examples`
75
76Direct your favorite browser to for instance http://localhost:8080/
77
78### HTTPS
79
80Before running the server, an RSA private key (server.key) and an SSL certificate (server.crt) must be created.
81
82Run the server and client examples: `./build/https_examples`
83
84Direct your favorite browser to for instance https://localhost:8080/
85
86## Contributing
87
88Contributions are welcome, either by creating an issue or a merge request.
89However, before you create a new issue or merge request, please search for previous similar issues or requests.
90A response will normally be given within a few days.
91