facil.io

• facil.io is a header file library for evented network services written in C (and usable from C++).

  facil.io provides high performance TCP/IP network services by using an evented design that was tested to provide an easy solution to the C10K problem.

• facil.io is much more than a web framework - its C STL aims to provide easy-to-use tools for writing memory safe and performant programs.

  Macros generate common building blocks for your own types - hash maps, dynamic arrays, copy-on-write binary-safe strings and more - alongside FIOBJ soft-typed data with JSON support. Useful in any C or C++ project, network-enabled or not.

• facil.io includes a mini-framework for Web Applications, with a fast HTTP / WebSocket / SSE server and client, integrated Pub/Sub with optional Redis clustering, JSON parsing, Mustache template rendering, CLI helpers and more nifty tidbits.

• facil.io supports TLS 1.3 out of the box - either through OpenSSL 3.x or its own built-in implementation, auto-selected at build time.

• facil.io ships with a complete cryptographic toolkit - AES, ChaCha, SHA-2/SHA-3, Ed25519, P-256/P-384, RSA, Argon2 and TOTP - including post-quantum ML-KEM-768 key encapsulation.

• facil.io powers the HTTP/Websockets Ruby Iodine server and it can easily power your application as well.

• facil.io is easy to code with and aims at minimizing the developer's learning curve.

  In addition to detailed documentation and examples, the API is unified in style and the same types and conventions used for HTTP requests are used for JSON, strings and Mustache rendering - so there's less to learn.

• facil.io is continuously tested on Linux, macOS and Windows, using epoll, kqueue or poll under the hood.

• facil.io scales from a single-threaded reactor to multiple worker processes, with optional background thread pools for blocking or CPU-intensive tasks.

• facil.io is a source code library, making it easy to incorporate into any project. The API was designed for simplicity and extendability, which means writing new extensions and custom network protocols is easy.

#A Web application in C? It's as easy as...

#define FIO_IO   /* the IO reactor */
#define FIO_HTTP /* the HTTP / WebSocket / SSE module */
#include "fio-stl.h"

// We'll use this callback in `fio_http_listen`, to handle HTTP requests
void on_request(fio_http_s *h);

// Listen to HTTP requests and start facil.io
int main(void) {
  // listen on port 3000 and any available network binding
  fio_http_listen("0.0.0.0:3000", .on_http = on_request, .log = 1);
  // start the server
  fio_io_start(0); /* or fio_io_start(4) for 4 worker processes */
}

// Easy HTTP handling
void on_request(fio_http_s *h) {
  fio_http_cookie_set(h,
                      .name = FIO_STR_INFO1("my_cookie"),
                      .value = FIO_STR_INFO1("data"));
  fio_http_response_header_set(h,
                               FIO_STR_INFO1("content-type"),
                               FIO_STR_INFO1("text/plain"));
  fio_http_response_header_set(h,
                               FIO_STR_INFO1("x-data"),
                               FIO_STR_INFO1("my data"));
  fio_http_write(h, .buf = "Hello World!\r\n", .len = 14, .finish = 1);
}

(Written using version 0.8.x)

#Creating a Web Application Using facil.io

Starting a new application with facil.io is as easy as copying a file - facil.io is a header file library, with no build step and no dependencies to install.

Download facil.io from GitHub and copy either the single-header fio-stl.h or the modular fio-stl folder into your project:

curl -L -o fio-stl.h https://raw.githubusercontent.com/facil-io/cstl/master/fio-stl.h

Then enable the modules you need and include the header:

#define FIO_IO   /* the IO reactor */
#define FIO_HTTP /* the HTTP / WebSocket / SSE module */
#include "fio-stl.h" /* or "fio-stl/include.h" when using the folder */

Done. Write your code and compile.

For more, browse the examples folder - an HTTP + WebSockets/SSE chat server, a network client, a Pub/Sub TCP chat, and STL type examples (arrays, strings, hash maps, FIOBJ) - each compilable with make examples/<name>.

Looking for the classic 0.7.x API and its application template script? They are still available from the original facil.io repository.

#Forking, Contributing and all that Jazz

Sure, why not.

If you encounter any issues, open an issue (or, even better, a pull request with a fix) - that would be great :-)

Pull requests should edit the modular sources in the fio-stl folder - the makefile regenerates the single-header fio-stl.h automatically. See the contribution guide for details.

Hit me up if you want to:

• Review the built-in TLS 1.3 and cryptographic modules - they work, but they have not been independently audited yet.

• Exercise the post-quantum ML-KEM-768 and X25519-ML-KEM-768 hybrid key exchange and report real-world feedback.

• Add examples, tests or documentation.