Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://risoflora.github.io/libsagui/

Cross-platform library which helps to develop web servers or frameworks.
https://risoflora.github.io/libsagui/

c cross-platform embedded gzip http iot pcre rest tls

Last synced: about 2 months ago
JSON representation

Cross-platform library which helps to develop web servers or frameworks.

Lists

README 

        
# `libsagui`



[![License: LGPL v2.1][license-badge]](LICENSE)

[![CII Best Practices][bestpractices-badge]][1]

[![GitHub releases][releases-badge]][2]

[![Build status][build-status-badge]][3]



## 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][4],

[uthash][5], [PCRE2][6], [ZLib][7] and [GnuTLS][8], 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][9] [syntax][10].

  - Just-in-time optimization ([JIT][11]).

  - Binary search in path entry-points.

- **HTTP compression:**

  - [Deflate][12] for static contents and

    streams compression.

  - [Gzip][13] for files compression.

- **HTTPS support:**

  - TLS 1.3 through [GnuTLS][8] 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:



```c

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:



```c

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:



```c

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`](examples) directory.



## Downloading



All stable binaries are available for download at the [releases page][2] 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][17] for more details.



Check the [docs/BUILD.md](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](docs/INSTALL.md) for how to install the library from sources

on your system.



## Documentation



The documentation has been written in [Doxygen][15] and is available in HTML

format at [libsagui-docs/index.html][16].



## Versioning



Starting from the version 1.0.0, Sagui follows the [SemVer][14] 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][18] to compare most recent library

versions.



See also [Checking backward API/ABI compatibility of Sagui library versions](docs/ABIComplianceChecker.md).



## Contributing



Sagui is totally open source and would not be possible without our

[contributors](THANKS). 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:



[![Support this project via PayPal][paypal-gif]][19]



Check the list of [all donors](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][20]!



## Projects using Sagui



- [Brook framework][21] - Pascal framework which helps to develop web

  applications. [LGPL v2.1][22]



Would you like to add your project to that list above? Feel free to open a

[new issue][23] requesting it! 🙂



## Licensing



Sagui is released under GNU Lesser General Public License v2.1. Check the

[LICENSE file](LICENSE) for more details.



[license-badge]: https://img.shields.io/badge/license-LGPL%20v2.1-lemmon.svg

[bestpractices-badge]: https://bestpractices.coreinfrastructure.org/projects/2140/badge

[releases-badge]: https://img.shields.io/github/v/release/risoflora/libsagui?color=lemmon

[build-status-badge]: https://github.com/risoflora/libsagui/actions/workflows/CI.yml/badge.svg?style=flat-square "CI/CD"

[paypal-gif]: https://www.paypalobjects.com/en_US/GB/i/btn/btn_donateCC_LG.gif

[1]: https://bestpractices.coreinfrastructure.org/projects/2140 "Best practices link"

[2]: https://github.com/risoflora/libsagui/releases "Releases page"

[3]: https://github.com/risoflora/libsagui/actions/workflows/CI.yml "GitHub actions"

[4]: https://www.gnu.org/software/libmicrohttpd "libmicrohttpd page"

[5]: https://troydhanson.github.io/uthash "uthash page"

[6]: https://www.pcre.org "PCRE page"

[7]: https://www.zlib.net "ZLib page"

[8]: https://www.gnutls.org "GnuTLS page"

[9]: https://www.pcre.org/current/doc/html/pcre2pattern.html

[10]: https://www.pcre.org/current/doc/html/pcre2syntax.html

[11]: https://www.pcre.org/current/doc/html/pcre2jit.html

[12]: https://en.wikipedia.org/wiki/DEFLATE "DEFLATE wiki"

[13]: https://en.wikipedia.org/wiki/Gzip "Gzip wiki"

[14]: https://semver.org "Semantic Versioning page"

[15]: https://www.doxygen.nl/index.html "Doxygen page"

[16]: https://risoflora.github.io/libsagui-docs/index.html "Sagui documentation"

[17]: https://github.com/risoflora/libsagui-docker/blob/master/README.md "Sagui Docker"

[18]: https://abi-laboratory.pro/?view=timeline&l=libsagui "Sagui ABI status"

[19]: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=silvioprog%40gmail%2ecom&lc=US&item_name=libsagui&item_number=libsagui&currency_code=USD&bn=PP%2dDonationsBF%3aproject%2dsupport%2ejpg%3aNonHosted "PayPal link"

[20]: mailto:[email protected]

[21]: https://github.com/risoflora/brookframework

[22]: https://github.com/risoflora/brookframework/blob/master/LICENSE

[23]: https://github.com/risoflora/libsagui/issues/new?labels=documentation&template=project_using_sagui.md