Home

Introduction to Crails Framework

Why Crails framework ?

Because Rails' approach to web framework is not all wrong. We aim at providing a similar - although much simpler environment to the developers.

Crails is fast and very light. And it helps you work with the fastest libraries around (for instance, the ODB ORM).

What does it do for me ?

Very lightweight

The framework consumes very little memory, and has very efficient response time, when all the unused modules are disabled (which is our default configuration).

C++ comfort

The tools available to C++ developers for debugging and profiling will give you a great advantage over other technologies when it comes to optimizing your application.

Comes with all the expected features

Crails routes your requests, handles parameters, file uploads, exceptions, and can provide you with a session object.

Security considerations

Crails comes with SSL support, cookie encryption and CSRF tokens.

Although we do not believe a properly designed C++ application needs anymore protection from null pointer issues than what is already provided by std's smart pointers, we do provide safe_ptr, an extension of std's shared_ptr which ensures an exception will be thrown if a null pointer is used.

Asset pipeline

Crails comes with an asset pipeline, powered by guard. It handles Javascript, CoffeeScript and SCSS.

Docker images

On our crails-docker repository, we provide docker images, compiling all dependencies of Crails over a debian image. It provides a complete environment for compiling and testing crails applications.

Heroku support

The cedar14-compat branch on the Crails and Crails Docker projects have been modified to work on Heroku's cedar14 image, allowing you to localy compile and directly deploy your application on Heroku. We also provide a buildpack: heroku-buildpack-crails.

Modules

The modules are pieces of crails that can be added to your project to bring some commonly needed, but not vital features.

• crails-json and crails-html gives the ability to write HTML and JSON templates in C++
• crails-mail allows you to send mail. In combination with crails-html, you can also send html emails
• crails-image gives you a simple way of storing uploaded images, and can use ImageMagick to generate thumbnails
• crails-cache adds support for libmemcache
• crails-odb adds support for the ODB ORM
• crails-mongodb adds support for the MongoDB C++ legacy driver

How does it work

Crails is built upon the cppnetlib, which is a boost powered library that implements the http server and parser that our framework uses.

Crails uses the cppnetlib to implement the request pipe, a two-step process looping over parsers and handlers, collecting data about the request, data about the response, before letting cppnetlib handle the rest. The following diagram describes this process:

  +------------+
  | cpp netlib |
  |   server   |
  +------------+
        |
 Exception Catcher ----------------|
        |                          |
        |                          v
        v                Prepare a 500 response.
  Request Parsers     cppnetlib sends the response
        |
        |
        v
 +--------------+
 |     Data     |
 |   (cookies,  |
 |uri parameters|          *Request Parsers*
 | http headers)|          They read data from the http
 +--------------+          request, and store them in a
         |                 more accessible fashion.
         v
+-----------------+        They run one after the other,
|    Multipart    |        util one of them declares the
|(multipart forms,|        parsing over.
|  file uploads)  |
+-----------------+        Parameters are stored in a
         |                 boost::property_tree::ptree,
         v                 which the developer can then
+------------------+       access in a Controller through
|       Form       |       the `params` attribute.
|(urlencoded forms)| 
+------------------+ 
         |
         v
+------------------+
|       JSON       |
|(application/json)|
+------------------+
         |
+------------------+
|       ...        |
| you may add your |
|   own parsers    |
+------------------+
         |
         |
  Request Handlers
         |
         |
         v
+------------------+              +--------------+                      +-----------------+
|  Action Handler  |------------->|    Router    |--- route matches --> | Your controller |
+------------------+              +--------------+                      +-----------------+
                                          |                                      |
                                          v                                      v
                                    no route match                  cppnetlib sends the response
                                          |
         |--------------------------------|
         |
         v               *File handler*                   
+------------------+     Though the File handler can
|   File Handler   |     serve your assets, it is not
+------------------+     designed for production. We
         |               encourage you to use, for
         v               instance, nginx as a load
+------------------+     balancer and a file server.
|       ...        |
| you may add your |
|   own handlers   |
+------------------+
  cppnetlib sends
    the response