Repository files navigation

A C++ library implementing an asynchronous HTTP server and client.

To clone this library, make sure you also clone the submodules. The --recursiveflag should do this for you:

git clone --recursive https://github.com/ef-gy/cxxhttp.git

This library implements HTTP/1.1 for clients as well as servers. It's fairlyminimalistic, yet there's a few nifty parts that wouldn't strictly have beennecessary.

Some of these are:

• HTTP Content Negotation
• HTTP over TCP, UNIX sockets and STDIO
• CLI help screen with servlet summaries
• Optional OPTIONS implementation, with a markdown body that shows the supportedmethods and the relevant location regex
• Optional TRACE implementation
• Basic 100-continue flow
• Basic request validation
• Fallback HEAD handler

I believe the STDIO feature is quite unique, as is the excellent test coverageof the library, for both the client and the server code.

Some features didn't make it into the library for various reasons - mostly tokeep it small. Some of these are:

• HTTP 'chunked' Transfer Encoding - or any non-identity encoding, really
• HTTP Date headers, or any other timekeeping-related code
• Query string parsing - use REST API style location strings instead
• Logging - though there are internal flags and counters, which e.g. thePrometheus client library based on this makes use of
• Any form of SSL/TLS support - use a frontend server to provide this for you

Some of the omissions technically make this non-conforming to the HTTP/1.1standard, but seeing as how the primary purpose of this library is to sit behindan nginx (or similar) HTTP web server, this shouldn't be an issue in practice.

You must have a GNU make and a C++ compiler that supports C++14. On mostmodern-ish Linux distributions that's pretty easy: just update your PMS andinstall clang++ or g++. Preferrably clang++. No reason.

On OSX, you'll be fine if you just install a current version of XCode.

On Ubuntu, you're in for a bit of a rough ride. The only reliable way I've foundof getting things to compile, at least on 14.04, is to install this PPA and useg++ 4.9:

sudo add-apt-repository ppa:ubuntu-toolchain-r/testsudo apt-get updatesudo apt-get install g++-4.9

To compile things, add CXX=g++-4.9 to your make commands, like this:

make test CXX=g++-4.9

This may not be necessary if you haven't installed clang++ and if there's noother versions of g++ installed. clang++ doesn't work on Ubuntu in c++14 mode,because libc++ hasn't been updated past an ancient SVN snapshot.

On Debian and Raspbian it should be sufficient to just update your packagesources and install clang++ and libc++:

apt-get updateapt-get install clang++ libc++1 libc++-dev

The library has a test suite, which you can run like this:

make test

If this fails, something is wrong. Please open an issue at GitHub with the log:https://github.com/ef-gy/cxxhttp/issues

This library uses the ASIO asynchronous I/O headers as well as libefgy. If youare starting a new project, it's probably easiest to use the build headers fromlibefgy and git submodules to pull in the dependencies.

The following set of commands ought to get you started:

PROJECT=funtastic-examplegit init ${PROJECT}cd ${PROJECT}git submodule add https://github.com/ef-gy/libefgy.git dependencies/libefgygit submodule add https://github.com/chriskohlhoff/asio.git dependencies/asiogit submodule add https://github.com/ef-gy/cxxhttp.git dependencies/cxxhttpmkdir includemkdir include/${PROJECT}mkdir srcln -s ../dependencies/asio/asio/include/asio include/asioln -s ../dependencies/asio/asio/include/asio.hpp include/asio.hppln -s ../dependencies/cxxhttp/include/cxxhttp include/cxxhttpln -s ../dependencies/libefgy/include/ef.gy include/ef.gy

A trivial makefile to get you started would look like this:

-include ef.gy/base.mk include/ef.gy/base.mkNAME:=funtastic-example

A very trivial sample server would be this (see src/server.cpp):

#define ASIO_DISABLE_THREADS#include <cxxhttp/httpd.h>using namespace cxxhttp;static void hello(http::sessionData &session, std::smatch &) {  session.reply(200, "Hello World!");}static http::servlet servlet("/", ::hello);int main(int argc, char *argv[]) { return cxxhttp::main(argc, argv); }

If you saved this as src/example.cpp, then you could run it like this:

make example./example http:localhost:8080

This will run the server and to see what it does, use:

curl -i http://localhost:8080/

Which should print the "Hello World!" from above.

You can run the ./example programme without arguments to see all the availablecommand line options. In particular, there is "http:unix:...", which lets yourun your server on a UNIX socket.

See src/server.cpp for additional commentary, and theinclude/cxxhttp/httpd-....h headers, which implement additional common featuresthat web servers tend to have.

Sure, try this:

git clone --recursive https://github.com/ef-gy/cxxhttp-example.git

Note the --recursive - that's because this is using submodules.

You really should be running this behind a real web servers, for security andsuch. Look into nginx for that, which is really good at forward-proxying.

The command you're looking for is built into git:

git submodule update --recursive --remote

Don't forget to commit the new state of the dependencies/ directory, if any ofthe libraries had updates.