Deploy Rook Apps with rApache: Part I

Since rApache 1.1.15 you’ve been able to deploy you Rook applications like so:

# Run the Rook application named 'app'. On each request, the expression 
# 'Rook::Server$call(app)' is evaluated in an environment populated by
# rookapp.R. 'app' is expected to be found in that environment.
<Location /test/RookApp>
        SetHandler r-handler
        RFileEval /path/to/Rook/App/rookapp.R:Rook::Server$call(app)
</Location>

Let’s go through the above example step by step, starting with the Location directive from apache.

The Location Directive Works on URLs

In apache, the Location directive works on the URL space of the server. In this case, we are telling apache that URLs starting with /test/RookApp are hooked up to our Rook application.

SetHandler Tells Apache That R Is In Charge

Of course you know apache is modular, and one way that third party modules (like rApache) can tell apache what it can do is by registering handlers, basically text strings. When a web request comes in, apache runs through its config files and figures out what handler has been assigned to the request. Then it runs through all of the third party modules and asks each one of them if they handle the particular handler. In our example, rApache knows how to handle “r-handler” stuff. So by placing SetHandler r-handler within our Location directive above, rApache will take over handling the request.

RFileEval: An Absolute File Path And an Expression

Here comes a bit of magic. The RFileEval directive is not an apache directive. Rather, it is an rApache directive. The syntax is “file:expression”. When a request comes in, rApache will create an anonymous R environment and execute each expression located in file. The equivalent R command is something like:

sys.source(file,envir=new.env())

Then after that, the expression is run within the anonymous environment. In our example, the expression is Rook::Server$call(app). Rook::Server is an object from the Rook package. app is a variable that must be found by lexical scope in the anonymous environment. So you better name your Rook application app in your file. It doesn’t have to be called app. You could have easily named your app foo. Then you’ll need to change the expression to Rook::Server$call(foo).

Here’s the cool part: rApache keeps the anonymous environment around after the request. When a new request comes in, it checks the timestamp of the file. If it hasn’t changed, then there’s nothing left to do except run the expression Rook::Server$call(app). However, if the timestamp has changed (meaning that someone edited the file), then the file is re-evaluated in a new anonymous environment and THEN the Rook expression is run.

Was I right? Cool? Cool. Expect more deployment posts in the following… days… hopefully.