libonion - HTTP server library

Author

David Moreno Montero - Coralbits S.L. - http://www.coralbits.com

Introduction

libonion is a simple library to add HTTP functionality to your program. Be it a new program or to add HTTP functionality to an exisitng program, libonion makes it as easy as possible.

Note

Best way to navigate through this documentation is going to Files / Globals / Functions, or using the search button on the corner.

To Check the C++ bindings check at the Onion namespace.

There are many documented examples at the examples directory (https://github.com/davidmoreno/onion/tree/master/examples/).

A basic example of a server with authentication, SSL support that serves a static directory is:

#include <onion/onion.h>

#include <onion/handlers/exportlocal.h>
#include <onion/handlers/auth_pam.h>

int main(int argc, char **argv){
  onion *o=onion_new(O_THREADED);
  onion_set_certificate(o, O_SSL_CERTIFICATE_KEY, "cert.pem", "cert.key", O_SSL_NONE);
  onion_set_root_handler(o, onion_handler_auth_pam("Onion Example", "login", onion_handler_export_local_new(".")));
  onion_listen(o);
  onion_free(o);
  return 0;
}

To be compiled as

  gcc -o a a.c -I$ONION_DIR/src/ -L$ONION_DIR/src/onion/ -lonion_static -lpam -lgnutls -lgcrypt -lpthread

please modify -I and -L as appropiate to your installation.

pam, gnutls and pthread are necesary for pam auth, ssl and pthread support respectively.

Onion request handlers

libonion is based on request handlers to process all its request. The handlers may be nested creating onion like layers. The first layer may be checking the server name, the second some authentication, the third checks if you ask for the right path and the last returns a fixed message.

Handlers have always a next handler that is the handler that will be called if current handler do not want to process current request.

Normally for simple servers its much easier, as in the upper example.

onion_url for normal handlers

Normal use of handler can be done using url handlers. They allow to create a named url and dispatch to a handler. It allows pattern capturing at the url using regex groups.

Check documentation at the url module.

Example of use

onion *o=onion_new(O_POOL);
onion_url *url=onion_root_url(o);
onion_url_add(url, "/", my_index); // privdata will be NULL
onion_url_add_with_data(url, "^/profile/([^/].*)", my_profile, usersdata);
onion_url_add_static(url, "/version", "0.0.1");
onion_url_add_url(url, ...); // Nesting

Create your custom handlers

Creating a custom handler is just to create a couple of functions with this signature:

int custom_handler(custom_handler_data *d, onion_request *request, onion_response *response);
void custom_handler_free(custom_handler_data *d);

Then create a onion_handler object with

onion_handler *ret=onion_handler_new((onion_handler_handler)custom_handler,
                                      priv_data,(onion_handler_private_data_free) custom_handler_free);

Normally this creation is encapsulated in a function that also sets up the private data, and that returns the onion_handler to be used where necesary.

As you can be seen it have its own private data that is passed at creation time, and that should be freed using the custom_handler_free when libonion feels its time.

The custom_handler must then make use of the onion_response object, created from the onion_request. For example:

int custom_handler(custom_handler_data *d, onion_request *request, onion_response *response){
  onion_response_printf(response,"Hello %s","world");
  return OCS_PROCESSED;
}

Optional library support

libonion has support for some external library very usefull addons. Make sure you have the development libraries when compiling libonion to have support for it.

SSL support

libonion has SSL support by using GNUTLS. This is however optional, and you can disable compilation by not having the development libraries, or modifing /CMakeLists.txt.

Once you have support most basic use is just to set a certificate and key file (can be be on the same PEM file). With just that you have SSL support on your server.

Thread support

libonion has threads support. It is not heavily mutexed as this impacts performace, but basic structures that are used normally are properly mutexed.

Anyway its on your own handlers where you have to set your own mutex areas. See examples/oterm/oterm_handler.c for an example on how to do it.

Specifically its not mutexed the handler tree, as its designed to be ready on startup, and not modified in all its lifespan.

Also there is an option to listen on another thread, using the O_DETACH_LISTEN flag on onion creation.