`libsagui`

Overview

Sagui is a cross-platform C library which helps to develop web servers or frameworks. Its core has been developed using the GNU libmicrohttpd, uthash, PCRE2, ZLib and GnuTLS, that’s why it is so fast, compact and useful to run on embedded systems.

Features

Requests processing through:
- Event-driven - single-thread + polling.
- Threaded - one thread per request.
- Polling - pre-allocated threads.
- Isolated request - request processed outside main thread.
High-performance path routing that supports:
- Regular expressions using PCRE2 syntax.
- Just-in-time optimization (JIT).
- Binary search in path entry-points.
HTTP compression:
- Deflate for static contents and streams compression.
- Gzip for files compression.
HTTPS support:
- TLS 1.3 through GnuTLS library.
Dual stack:
- Single socket for IPv4 and IPv6 support.
Basic authentication:
- For standard login using user name/password.
Upload/download streaming by:
- Payload - for raw data transferring as JSON, XML and other.
- File - for large data transferring as videos, images, binaries and so on.
Mathematical expression evaluator:
- Arithmetic, bitwise and logical operators.
- Variables allocation at build and/or run time.
- Macro support to define functions at run time.
- Extendable with custom functions.
- Error handling with error kind and position.
Dynamic strings:
- Makes it easy strings operations in C.
String map:
- Fast key-value mapping.
And more:
- Fields, parameters, cookies, headers under hash table structure.
- Several callbacks for total library customization.

Examples

A minimal hello world HTTP server:

void req_cb(void *cls, struct sg_httpreq *req, struct sg_httpres *res) {
    sg_httpres_send(res, "Hello world", "text/plain", 200);
}

int main(void) {
    struct sg_httpsrv *srv = sg_httpsrv_new(req_cb, NULL);
    sg_httpsrv_listen(srv, 8080, false);
    printf("Server running at http://localhost:%d\n", sg_httpsrv_port(srv));
    getchar();
    sg_httpsrv_free(srv);
    return 0;
}

The router support is isolated from the HTTP feature, so it can be used to route any path structure, for example:

void home_cb(void *cls, struct sg_route *route) {
    printf("Home\n");
}

void download_cb(void *cls, struct sg_route *route) {
    printf("Download\n");
}

int main(void) {
    struct sg_router *router;
    struct sg_route *routes = NULL;
    sg_routes_add(&routes, "/home", home_cb, NULL);
    sg_routes_add(&routes, "/download", download_cb, NULL);
    router = sg_router_new(routes);
    sg_router_dispatch(router, "/home", NULL);
    sg_routes_cleanup(&routes);
    sg_router_free(router);
    return 0;
}

lastly, putting everything together:

struct Holder {
    struct sg_httpreq *req;
    struct sg_httpres *res;
};

void route_home_cb(void *cls, struct sg_route *route) {
    struct Holder *holder = sg_route_user_data(route);
    sg_httpres_send(holder->res, "Home", "text/plain", 200);
}

void route_download_cb(void *cls, struct sg_route *route) {
    struct Holder *holder = sg_route_user_data(route);
    sg_httpres_send(holder->res, "Download", "text/plain", 200);
}

void req_cb(void *cls, struct sg_httpreq *req, struct sg_httpres *res) {
    struct sg_router *router = cls;
    struct Holder holder = {req, res};
    if (sg_router_dispatch(router, sg_httpreq_path(req), &holder) != 0)
        sg_httpres_send(res, "404", "text/plain", 404);
}

int main(void) {
    struct sg_route *routes = NULL;
    struct sg_router *router;
    struct sg_httpsrv *srv;
    sg_routes_add(&routes, "/home", route_home_cb, NULL);
    sg_routes_add(&routes, "/download", route_download_cb, NULL);
    router = sg_router_new(routes);
    srv = sg_httpsrv_new(req_cb, router);
    sg_httpsrv_listen(srv, 8080, false);
    printf("Server running at http://localhost:%d\n", sg_httpsrv_port(srv));
    getchar();
    sg_httpsrv_free(srv);
    sg_routes_cleanup(&routes);
    sg_router_free(router);
    return 0;
}

There are other examples available in the examples directory.

Downloading

All stable binaries are available for download at the releases page with their respective checksums. For other systems, the packages Source code (tar.gz|zip) contains the library source.

Building/installing

The easiest way to build the library is using a Docker container as a builder. Follow the instructions at libsagui-docker/README.md for more details.

Check the docs/BUILD.md for more instructions for how to build the examples, tests, documentation and the library. Also, take a look at docs/INSTALL.md for how to install the library from sources on your system.

Documentation

The documentation has been written in Doxygen and is available in HTML format at libsagui-docs/index.html.

Versioning

Starting from the version 1.0.0, Sagui follows the SemVer rules regarding API changes with backwards compatibility and stable ABI across major releases.

Compatibility

A typical upgrade of the Sagui library does not break the ABI at all. Take a look at the API/ABI compatibility report to compare most recent library versions.

Contributing

Sagui is totally open source and would not be possible without our contributors. If you want to submit contributions, please fork the project on GitHub and send a pull request. You retain the copyright on your contributions.

Donations

Many open source projects, large and small, receive donations to encourage their authors, therefore, it would be not different in Sagui.

All money collected from donations are invested to the purchase of study materials. This way, directly or indirectly, all knowledge acquired in the studies influence the spread of this project.

If you want to support this project, please click the button below:

Check the list of all donors that lovely supported this idea! :heart:

Support

This project values being simple, direct and self-explanatory. However, if you need some help to integrate Sagui to your application, we have the option of a paid consulting service. Contact us!

Projects using Sagui

Brook framework - Pascal framework which helps to develop web applications. LGPL v2.1

Would you like to add your project to that list above? Feel free to open a new issue requesting it! 🙂

Licensing

Sagui is released under GNU Lesser General Public License v2.1. Check the LICENSE file for more details.