Suil C++ Framework

Site is still work in progress…

This documentation site is still work in progress. Some links on this site might point to pages that haven’t been published yet. Use the side menu bar currently to navigate around

Introduction

Suil C++ Framework

Weirdly named suil, a name I derived from a word (swele) in my native language which translates to the best. This is a project I started back in my student days as a way for me to keep sharpening my C++ programing skills. The project keeps growing and getting better as I learn new software concepts and the C++ standard changes. This is a work in progress project that is evolving with time and inspiration from other exciting open source projects.

The purpose of this document is to introduce and document SCF. While going through the documentation, please heed to all warnings/advices given as the project tend to use bad programing paradigms that still haunt me from my novice days and needs special attention when using them.

What is SCF

SCF is a software development framework providing various C++ libraries that can be used to build or quickly prototype Linux applications. The framework targets the web applications space by providing re-usable software components that can be assembled into usable web applications without (or with less) effort. Coming from an embedded background, I always thrive for performance and low memory usage and some of the concepts employed in this project were an attempt to either make things faster or to reduce memory usage. Where possible the project avoids depending on complex libraries and provides simpler implementations.

#include "suil/http/server/endpoint.hpp"

namespace hs   = suil::http::server;
namespace net  = suil::net;

int main(int argc, char *argv[])
{
    using Server = hs::Endpoint<>;
    // Create an http endpoint that uses default configurations
    Server ep("/");

    // GET http://localhost/hello
    Route(ep, "/hello")
    ("GET"_method, "OPTIONS"_method)
    (Desc{"Route returns hello world"})
    .attrs(opt(ReplyType, "text/plain"))
    ([&]() {
        // body will be cleared after response
        return "Hello World!";
    });

    // GET http://localhost/echo
    Route(ep, "/echo")
    ("GET"_method, "OPTIONS"_method)
    (Desc{"Route returns whatever was given in the request body"})
    .attrs(opt(ReplyType, "text/plain"))
    ([&](const hs::Request& req, hs::Response& res) {
        // Chunked response buffer to support zero copy
        res.chunk({const_cast<char *>(req.body().data()), req.body().size(), 0});
    });

    return ep.start();
}

SCF Features

Everything in suil is developed with coroutines in mind (thanks to Libmill). Imagine go but in C++

• An easy to use parameter based static and dynamic routing API
• Middleware based endpoints
• Application Initialization Middleware which can be used to provide an initialization route for the API while blocking all the other routes
• System Attributes Middleware can be added to the endpoint to allow adding features that toggle options on the endpoint (e.g enabling/disabling authentication on specific route)
• One-line method call for Route Administration and API documentation, this expose’s routes that can be used to administer the endpoint, including enabling/disabling routes and querying route metadata (Admin Only)
• JSON Web Token API’s which can be used to create JWT tokens and verify them
• JWT Authorization Middleware is available for JWT authentication. When added to an endpoint, it will validate all routes marked with Authorize attribute and reject all unauthorized requests
• JWT Session Middleware builds on top of JWT Authorization and Redis Middlewares by implementing session based JWT (i.e the refresh/accept token ideology)
• Redis and PostgreSQL middlewares which when attached to an endpoint, can be used as database connection providers for the endpoint
• File Server which can be used to serve the contents of any directory. This is still missing some features but thrives to be very fast and reliable.
  • Supports cached files, i.e files are cached in an L.R.U cache
  • Range based requests
  • Cache headers
  • Easy configuration API. e.g fs.mime("js", opt(allowCache, true)) will allow the server to cache javascript files
  • There is still some of work to here but current implementation serves basic needs

The following list of open source libraries are used in SCF is third party dependencies

Any other code that might have been used, either modified or copied as is, the original licence text kept at the top of the file or comment with a link to the source of the snippet is included