facil.io

• facil.io is a header file library for evented network services written in 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 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 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.

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:

• Help write HPACK / HTTP2 protocol support (work in progress).

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

• Add examples, tests or documentation.