Lwan API intro

See this repository for a complete example project.

Lwan is a high performance & scalable web server written in C.

The main page has now been updated so the following is no longer applicable. Skip to the Building section.

An API example is listed on the main project page.

#include "lwan.h"

static lwan_http_status_t
hello_world(lwan_request_t *request,
            lwan_response_t *response, void *data)
{
    static const char message[] = "Hello, World!";

    response->mime_type = "text/plain";
    strbuf_set_static(response->buffer, message, sizeof(message) - 1);

    return HTTP_OK;
}

int
main(void)
{
    const lwan_url_map_t default_map[] = {
        { .prefix = "/", .handler = hello_world },
        { .prefix = NULL }
    };
    lwan_t l;

    lwan_init(&l);

    lwan_set_url_map(&l, default_map);
    lwan_main_loop(&l);

    lwan_shutdown(&l);

    return 0;
}

This looks great, easy to use and no real surprises. Unfortunately, this is incompatible with the current master branch at the time of writing. Further, the documentation on using Lwan as a library is a bit sparse at this time.

This will be a quick-start guide to setting up a sample project and going from there.

Building

First, we’ll create a new project.

mkdir lwan-api-example
cd lwan-api-example

Next, let’s pull lwan into the project and build it. You will need CMake and zlib installed for this.

git clone https://github.com/lpereira/lwan # Use a submodule here if using git!
cd lwan
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

This generates liblwan.a and liblwan.so library files in the build/common directory. We’ll come back to these later, lets start a simple project.

Creating the project

Let’s go back to our project root and create a new file, hello.c.

#include <lwan.h>

static enum lwan_http_status hello_world(
        struct lwan_request *request,
        struct lwan_response *response,
        void *data)
{
    static const char message[] = "Hello, World!";

    response->mime_type = "text/plain";
    strbuf_set_static(response->buffer, message, sizeof(message) - 1);

    return HTTP_OK;
}

int main(void)
{
    const struct lwan_url_map default_map[] = {
        { .prefix = "/", .handler = hello_world },
        { .prefix = NULL }
    };

    struct lwan l;
    lwan_init(&l);

    lwan_set_url_map(&l, default_map);
    lwan_main_loop(&l);

    lwan_shutdown(&l);
    return 0;
}

Note that the main differences between the current api is the removal of _t specifiers (likely for POSIX conformance).

Building our project

The include headers are stored in the common directory. We also require the include header generated by CMake which is found in the build directory.

We then can build our project.

gcc -O2 -Ilwan/common -Ilwan/build hello.c lwan/build/common/liblwan.a \
    -o hello -lpthread -ldl -lz

We need to remember to link the pthread, dl and zlib libraries. That should be it, you should now have a binary hello that you can run.

Have fun!