A simple and lightweight web framework written in C99 plus POSIX.1-2008 extensions.
Go to file
Xavier Del Campo Romero 65031ca350
Send HTTP headers to payload callback
Even if libweb already parses some common headers, such as
Content-Length, some users might find it interesting to inspect which
headers were received from a request.

Since HTTP/1.1 does not define a limit on the number of maximum headers
a client can send, for security reasons a maximum value must be provided
by the user. Any extra headers shall be then discarded by libweb.

An example application showing this new feature is also provided.
2023-11-18 01:03:12 +01:00
cmake CMake: Use in-tree dynstr if not available 2023-10-16 01:22:12 +02:00
doc Send HTTP headers to payload callback 2023-11-18 01:03:12 +01:00
dynstr@7be16e6e5c Bump dynstr 2023-11-10 14:47:05 +01:00
examples Send HTTP headers to payload callback 2023-11-18 01:03:12 +01:00
include/libweb Send HTTP headers to payload callback 2023-11-18 01:03:12 +01:00
.gitignore Makefile: Build libweb also as a shared library 2023-10-25 21:57:10 +02:00
.gitmodules Move dynstr to new URL 2023-07-28 01:32:51 +02:00
CMakeLists.txt CMakeLists.txt: Fix missing LANGUAGES 2023-11-10 14:45:46 +01:00
handler.c Send HTTP headers to payload callback 2023-11-18 01:03:12 +01:00
html.c Rename project from slweb to libweb 2023-10-11 00:07:13 +02:00
http.c Send HTTP headers to payload callback 2023-11-18 01:03:12 +01:00
libweb.pc libweb.pc: Fix wrong -l flag 2023-10-16 00:29:52 +02:00
LICENSE Initial commit 2023-07-20 23:52:47 +02:00
Makefile Makefile: Replace -Og with -O1 2023-10-25 22:07:11 +02:00
README.md Rename project from slweb to libweb 2023-10-11 00:07:13 +02:00
server.c Rename project from slweb to libweb 2023-10-11 00:07:13 +02:00
wildcard_cmp.c Rename project from slweb to libweb 2023-10-11 00:07:13 +02:00

libweb, a simple and lightweight web framework

libweb is a simple and lightweight implementation of a web server, written in C99 plus POSIX.1-2008 extensions, that can be integrated into applications.

Disclaimer

Intentionally, libweb does not share some of the philosophical views from the suckless project. However, it still strives towards portability, minimalism, simplicity and efficiency.

Features

  • Small and portable HTTP/1.1 server implementation, with support for GET and POST.
  • Provides a interface to set up user-defined callbacks depending on the operation (see example below).
  • Transport-agnostic implementation.
    • While a POSIX socket, TCP-based implementation is already provided, the HTTP interface can be mapped to any other reliable transport layer.
  • Supports multiform/form-data , which makes it useful to transfer large amounts of data, such as binary files.
  • A library to write HTML programmatically.

TLS

In order to maintain simplicity and reduce the risk for security bugs, libweb does not implement TLS support. Instead, this should be provided by a reverse proxy, such as caddy.

Root permissions

libweb does not require root permissions. So, in order to avoid the risk for security bugs, please do not run libweb as root.

Requirements

  • A POSIX environment.
  • dynstr (provided as a git submodule).
  • CMake (optional).

Ubuntu / Debian

Mandatory packages

sudo apt install build-essential

Optional packages

sudo apt install cmake

How to use

Build

Two build environments are provided for libweb - feel free to choose any of them:

libweb can be built using the standard build process:

Make

$ make

This would generate a static library, namely libweb.a, on the project top-level directory. Applications can then call the top-level Makefile by the use of recursive make. For example, assuming libweb is contained on a subdirectory:

libweb/libweb.a:
    +cd libweb && $(MAKE)

Additionally, libweb can be installed using the install target. A custom prefix can be assigned via the PREFIX variable:

$ make PREFIX=$HOME/libweb-prefix install

By default, PREFIX is assigned to /usr/local.

CMake

$ mkdir build/
$ cd build/
$ cmake ..
$ cmake --build .

A CMake target, also called libweb, is created. This makes it possible to integrate libweb into CMake projects via add_subdirectory and target_link_libraries. For example:

project(example)
add_executable(${PROJECT_NAME} main.c)
add_subdirectory(libweb)
target_link_libraries(${PROJECT_NAME} PRIVATE libweb)

Additionally, libweb can be installed using the standard procedure in CMake. As usual, a custom prefix can be assigned via the CMAKE_INSTALL_PREFIX variable:

$ cmake --install build/ -DCMAKE_INSTALL_PREFIX=$HOME/libweb-prefix

Examples

A directory with examples shows how libweb can be used by applications. These can be built from the top-level directory with:

$ make examples

In the case of CMake builds, examples are built by default. This can be turned off by assigning BUILD_EXAMPLES to OFF or 0:

$ mkdir build/
$ cd build/
$ cmake .. -DBUILD_EXAMPLES=OFF
$ cmake --build .

Why this project?

Originally, libweb was part of the slcl project, a lightweight cloud solution also written in C99 plus POSIX extensions. However, there always was a clear separation between application logic and the underlying HTTP/1.1 server implementation and other surrounding utilities.

Therefore, it made sense to keep all these components on a separate repository that slcl could depend on. Additionally, this would also benefit other applications interested in this implementation.

Seriously, why yet another new HTTP/1.1 implementation?

  • Popular web server implementations, such as apache or nginx are standalone applications that can be configured to run other applications in order to generate dynamic content, via a standard interface called Common Gateway Interface , or CGI for short.
    • However, those are vastly complex tools with many features and options, whereas simplicity was one of the key design goals for slcl.
    • Additionally, tools such as apache or nginx place configuration files into /etc, which makes it harder to run multiple instances on the same machine. While not a strict requirement from slcl, it was desirable to keep configuration as simple as possible for administrators.
  • The onion project, which does follow the HTTP library concept, was initially considered for slcl, but has a larger scope than libweb, and again simplicity was essential for slcl.
  • And, after all, it was a good excuse to learn about HTTP/1.1.

License

libweb, a simple and lightweight web framework.
Copyright (C) 2023  Xavier Del Campo Romero

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Also, see LICENSE.