Architecture

Basics

Turbinado is composed of:

1. Controllers receive requests, retrieve Models and put together data to be used by the Views.
2. Models are mappings of the database tables to Haskell datatypes.
3. Views produce XML, HTML, etc.
4. Components are modular, reusable Controllers and Views which are designed to be used within other Views.

The Turbinado ‘Environment’

Turbinado uses a large Environment datatype to hold Server, Application and Request-specific data. The Environment is composed of a large number of fields to hold DatabaseConnection, Request, Response, etc. Each of the fields in the Environment is held within a Maybe datatype in order to allow the Environment to be partially constructed. For example, when the Server starts up, it constructs a partially completed Environment which contains only the fields which are used by the Server. As requests come in, the Server hands to the appropriate Controller an Environment which is specialized for that Controller’s Request. As the Controllers and Views operate, they fill in the Response field of the Environment.

A partial listing of fields in the Environment is:

1. CodeStore: cached, compiled versions of Models, Views, Controllers and Components.
2. Database: the connection to the database.
3. Request: the parsed HTTP Request.
4. Response: the HTTP Response generated by the Controller or View.
5. Settings: settings which are derived from the current request.
6. ViewData: data which is sent from the Controller to the View for display.

The Environment also includes an AppEnvironment field for a application specific data type.

The Environment is accessible to both Controllers and Views because each is an instance of the HasEnvironment class and implements [get|set]Environment.

Life Cycle

Server Life Cycle

At startup, the server:

1. Binds to the specified port;
2. Builds the route table;
3. Builds the MIME type dictionary;
4. Initializes the Logger and CodeStore;
5. Runs any application specific setup filters.
6. (1) Waits for a request.
7. After receiving a request, a WorkerThread is created (if the WorkerPool is empty) and handed the partially constructed Environment and the request connection.
8. Goto (1)

Request Life Cycle

When the connection is handed to the WorkerThread, the WorkerThread:

1. Continues building the Environment;
2. Receives and parses the inbound Request;
3. Tries to retrieve static content (e.g. an image) to satisfy the Request;
4. Runs any application specific customPreFilters;
5. Retrieves and runs the Controller specified by the Routes;
6. Retrieves and runs the Layout (which should insertDefaultView);
7. Runs any application specific customPostFilters;
8. Sends back to the client the Response contained within the Environment.

ORM

Turbinado provides a code generator to generate an Object Relational Mapping (http://en.wikipedia.org/wiki/Object-relational_mapping) from a database to a set of Models (Haskell datatypes and database functions).

Following the example set by .netTiers, each model is composed of multiple files (using the Page model as an example):

1. Page.hs: the editable portion of the Page Model, which imports the various pieces of the Page Model. See http://github.com/alsonkemp/turbinado-website/tree/master/App/Models/Page.hs.
2. Bases/Page*.hs: the automatically generated “base” code which represents the database table “page” and its functions and relations. These file should not be edited. See Bases/PageType.hs, Bases/PageFunctions.hs and Bases/PageRelations.hs.

The ORM automates basic CRUD functionality, provides standard Haskell datatypes for database tables and uses the database’s foreign keys to determine table-table relationships. As an example ofhow to retrieve all Pages order by “title” where the “_id” starts with “prefix”:

   pages <- findAllWhereOrderBy "_id like ?" [toSql $ prefix ++ "%"] "title"

A Page is defined by the ORM as:

   data Page = Page {  _id :: String, authorId :: Maybe Int64, content :: String, title :: String, version :: Int64} deriving (Eq, Show)