The JSGI model is very simple to understand and, when used properly, lets us create really powerful applications. It is the de facto model for application development in CommonJS.

However, the JSGI model isn't supported by all CommonJS engines, often because of the different nature of the engine implementation itself. This creates a problem when it comes to developing applications that can run on several engines, and is therefore an interesting issue to look at.

Meso, the MooTools runner and toolkit for CommonJS that we'll be using here, currently supports four popular CommonJS implementations: Flusspferd, RingoJS, NodeJS, and v8cgi. In the following sections, we'll look at each one of these and take a peek at how they implement a web application model.

// the application
var app = function(env){
    return {
        status: 200,
        headers: {
            'content-type': 'text/plain',
            'content-length': 12
        },
        body: ['Hello World!']
    };
};

// zest module
var Zest = require('zest').Zest;

// create a server
var server = new Zest({
    handler: app,
    port: 8081
});

server.start();

// the application
var app = function(env){
    return {
        status: 200,
        headers: {
            'content-type': 'text/plain',
            'content-length': 12
        },
        body: ['Hello World!']
    };
};

// http server module
var Server = require('ringo/httpserver').Server;

// create a server
var server = new Server({
    app: app,
    port: 8081
});

server.start();

var app = function(request, response){
    response.writeHead(200, {
        'content-type': 'text/plain',
        'content-length': 12
    });
    response.write('Hello World!'),
    response.end();
};

var app = function(request, response){
    response.writeHead(200, {
        'content-type': 'text/plain',
        'content-length': 12
    });
    response.write('Hello World!'),
    response.end();
};

var http = require('http'),

var server = http.createServer(app);
server.listen(8081);

response.status(200);
response.header({
    'content-type': 'text/plain',
    'content-length': 12
});
response.write('Hello World!'),

One thing you've probably noticed by now is that there's no single cross-compatible solution for CommonJS application development. As we've seen, not all CommonJS implementations agree on how to do things, and each one provides its own APIs for handling the work of application development.

This is not a big problem if we're going to target only a single platform. Unlike with browser-based development, we have the freedom to choose the implementation we want to support, without having to worry about our application not being able to run on other platforms. We're no longer bound to external constraints like the browser preference of our target users or the different bugs in the implementations of these browsers.

There is, however, the question of risk. The CommonJS effort is very young and the various engines available today are mostly still under development. Targeting a particular engine is inherently risky, since you're locking yourself into a very particular set of APIs. This is very disconcerting once you take into account the "bus factor" of some CommonJS projects: some of these projects need only one developer to get hit by a bus to send the whole project into disarray (a bus factor of one).

Also worth considering are projects that are meant to be cross-platform. If you're building open-source discussion software or a blog engine, for example, you'll probably want to be able to deploy the end product to as many engines as possible. You therefore have to take into account the different APIs involved, and write your application so it can use all those APIs.

In fact, there are a whole lot of reasons why a common application development model would be useful, aside from those we already discussed. While the choices are no longer bound by our end users, they are still bound by external factors.

You can download Deck from the official website at http://deckjs.com/, and use the instructions on the site to install Deck on your system. There are a few ways to use Deck, but we recommend using it together with Meso, which you saw in the previous chapter. For simplicity, we'll assume you're running the following example using Meso.

var app = function(request, response){
    response.setStatus(200);
    response.setHeaders({
        'content-type': 'text/plain',
        'content-length': 12
    });
    response.write('Hello World!'),
    response.finish();
};

var Deck = require('deck').Deck;

var deck = new Deck({
    app: app
});

deck.serve({port: 8000});

When we run this program and load http://localhost:8000, we're greeted with the 'Hello World!' message as with the other implementations.

You'll notice that the code has elements from all the APIs we've seen so far. Like the previous APIs, the application is simply a regular JavaScript function. We create a new instance using the Deck constructor, passing in an options object with the app property to define our application. We then start the application using the serve method, passing in an options object that defines the port to listen to. Like in Node, application functions in Deck receive two arguments: request and response. These objects represent the actual HTTP request and response messages, and they're used to determine the nature of the request and set the response appropriately.

It might not seem like a big deal right now, since we can pretty much do the same thing in other engines—and for the most part, we've proven that already. However, this Deck example is unique because it runs on all the engines we've seen so far: the same code can be used whether we're using Flusspferd, RingoJS, NodeJS, or v8cgi—and those are only the engines that have adaptors so far! This means that with proper adaptors, we can run this same example anywhere.

It's also interesting because underneath this single API, Deck uses the same per-engine APIs we've seen above. This means that Deck is using Zest when it's running on Flusspferd, or http.createServer when running on Node. However, we don't notice this because everything is done transparently.

Of course, Deck isn't limited to just abstracting low-level APIs. Aside from providing an API that works on multiple engines, Deck also has additional features that make writing applications and frameworks easier.

One of these features is routing. In creating applications, it's rare that we use a single request URL. Each point of the application is usually accessed using a different URL, so applications must be able to handle each URL differently.

Imagine we're creating an application that changes its behavior depending on the requested path. If our users access the /hello path, the application will respond with Hello World!, while if they request the /hi path, it'll respond with Hi Universe!. To achieve this, we can rewrite our previous app function to look like this:

var app = function(request, response){
    response.setStatus(200);
    response.setHeaders({
        'content-type': 'text/plain',
        'content-length': 12
    });

    if (request.pathInfo == '/hello'){
        response.write('Hello World!'),
    } else if (request.pathInfo == '/hi'){
        response.write('Hi Universe!'),
    }

    response.finish();
};

var Deck = require('deck').Deck;

var deck = new Deck({
    app: app
});

deck.serve({port: 8000});

Here we add an if-else statement to our app function to check the pathInfo property of the current request. We then serve the appropriate response body according to the requested path: 'Hello World!' for /hello and 'Hi Universe!' for /hi, which you can check for yourself by running this example and going to http://localhost:8000/hello or http://localhost:8000/hi.

While this style works for simple examples like the one above, it becomes hard to use once we start working with more complex applications. As our applications become bigger, the internal logic for each part of our application increases: our /hi path might require some database access, while /hello might have to write some files. If we're going to use a single application function for all our paths, our code will very quickly become unmanageable.

To make our code easier to work with, we need to split up our monolithic application function. Deck makes this easy by allowing you to have multiple application functions using routes. A route is a special rule that's checked against the request object. If the request satisfies the rule, the application associated with that route is served. If it doesn't, Deck will continue comparing the request object against other routes until it finds one that matches.

We use the addRoute method of a Deck instance to add new routes. It takes two main arguments: matcher, which is used to match the pathInfo property of the request, and app, which is the application function to serve.

var appHello = function(request, response){
    response.setStatus(200);
    response.setHeaders({
        'content-type': 'text/plain',
        'content-length': 12
    });
    response.write('Hello World!'),
    response.finish();
};

var appHi = function(request, response){
    response.setStatus(200);
    response.setHeaders({
        'content-type': 'text/plain',
        'content-length': 12
    });
    response.write('Hi Universe!'),
    response.finish();
};

var Deck = require('deck').Deck;

var deck = new Deck();

deck.addRoute('/hello', appHello);
deck.addRoute('/hi', appHi);

deck.serve({port: 8000});

Here we split up the original app function into two separate functions: appHello and appHi. We also removed the app option object from the Deck instantiation code, which tells the Deck class that we want to use multiple routes. Finally, we added two routes using the addRoute method, one for the appHello function and another for appHi.

Running this example, we'll get the same behavior as with the previous one: 'Hello World!' for http://localhost:8000/hello and 'Hi Universe!' for http://localhost:8000/hi. What happens is that when we request these URLs, Deck automatically compares the path of the requested URL to the defined routes. If the path is /hello, it serves the appHello function, and if it's /hi, it serves appHi.

I mentioned earlier that in the JSGI model, application functions can be chained together to form more complex applications, and these decorator functions are called middleware because they sit in between the application and the server implementation. Deck also allows for middleware, which in Deck terms are called modules.

Like in the JSGI model, Deck modules lie between the application and the server implementation. However, modules and application functions aren't chained using function decoration. Instead, Deck implements a stack-based model for using modules.

In this model, the modules and the application are placed in an array, with the application function always sitting in the middle. Deck will call each of the functions one after the other, passing in the request and response objects to each one. The chaining therefore occurs inside the Deck instance, and not through explicit decoration on the part of the user.

Also unlike the JSGI model, Deck modules are actually objects and not functions. The functions that are invoked from each module come from handlers, which are methods of the module objects.

var module = {

    preHandler: function(request, response){
        request.next();
    },

    postHandler: function(request, response){
        request.next();
    }

};

Here we have a simple Deck module object, with the two handler methods. The preHandler method of the module object is added to the front of the application, while the postHandler method is added at the back. This means that Deck modules can be invoked before, after, or before and after the application function, depending on the handlers they define.

Adding a module to a Deck instance is simply a matter of calling the addModule method:

var app = function(request, response){
    response.setStatus(200);
    response.setHeaders({
        'content-type': 'text/plain',
        'content-length': 12
    });
    response.write('Hello World!'),
    response.next();
};

var module = {

    preHandler: function(request, response){
        request.next();
    },

    postHandler: function(request, response){
        request.next();
    }

};

var Deck = require('deck').Deck;

var deck = new Deck({
    app: app
});

deck.addModule(module);

deck.serve({port: 8000});

The bulk of Deck's internals focus on the creation and manipulation of Request and Response objects. For every request received by the underlying HTTP server, Deck creates an object representation of the request and a corresponding response object. These objects are passed to the application, which then processes and manipulates them before passing them back to the Deck instance to be sent to the originator of the request.

The Request object contains several properties that describe the request, including the HTTP method, the requested resource, the user-agent, and other headers. It also has several utility methods that can be used to modify its properties, add additional headers, or change the requested resource. The Response object represents the response to be sent back and has methods to set the HTTP status of the response, add headers, and modify the response body.

The Request and Response objects are always created as pairs: both are created when a request is received and both are passed to the application for access and modification. Unlike the existing CommonJS JSGI standard that expects the application to create and return its own Response object, it is the work of the Deck instance to create the Response object that the application modifies.

Deck implements a filtered model for server requests and responses. In a simple model, a request is made to the server-side application by the browser and the application then sends a corresponding response. In Deck's filtered model, several "filters" sit before and after the application and they modify the request or response in order to change behavior.

The filtered model can be viewed like a deck of cards (from which Deck gets its name): the application sits in the middle of the deck and several modules are placed on top and on the bottom of the application. The Request and Response objects are then passed to each of these items in turn, starting from the topmost module and ending at the bottom module.

With this model, complex applications can be simplified by separating common tasks into several modules. An example might be a Rewrite Module, which could modify the Request object's pathInfo property before it reaches the application, thereby changing the request. The application would then be able to serve the appropriate response without having to do further checks on the Request object. Another example might be a Logger Module that logs every Request and its corresponding Response. Instead of having to do this within the application, you could simply add the module to the Deck instance.

Deck uses a double-ended queue (or a deque, pronounced "deck") to keep track of the application and the modules. In the middle of the deque is the application and the modules are added either before or after so that the application always remains in the middle. The addition of modules also follows the deque's two ends: the preHandler method of a module is always added in the front of the deque and the postHandler is always added at the end of the deque.

After creating the Request and Response objects, the Deck instance "dispatches" the modules and the application by invoking the first function in the deque, passing the Request and Response objects as arguments. The Deck instance waits until it is signaled to move on to the next item in the deque, and then repeats the process until all items have been dispatched before sending the response back.

The signal to the Deck instance to move to the next item is done by the modules and the application themselves. The Request object has a special method called next that's called by the modules and the application within their function bodies to tell the Deck instance to move to the next item. All Modules and Applications are required to call this method; otherwise, the Deck instance won't be able to move to the next item in the deque and the response will timeout.

Additionally, the Response object has a special method called finish that tells the Deck instance that the response has been finalized. Calling this method will stop the dispatching of the next items on the deque and return the response immediately.

Because the dispatching of items is done using an explicit signal, Deck is able to support asynchronous applications natively.

Deck includes a built-in router that dynamically changes the internal module and application deque before dispatching. Multiple routes can be set for a Deck instance, describing the rules and the corresponding application function to dispatch for a specific request.

The base of the routing rule is a string or a regular expression describing the request's requested path and the HTTP request method. After the Deck instance creates the Request and Response objects, it checks the Request object's pathInfo property and HTTP request method to see whether it matches any of the routing rules set for the Deck instance. If it does, it builds a new deque with the application function described in the route rule before dispatching the deque.

Additionally, a constraint object can be passed when setting a new route that will be used to check other rules before dispatch. The constraint object is a simple JavaScript object with keys corresponding to the Request objects properties and values that can be strings, regular expressions, or functions that will be used to check the info against.