Introducing Rook

Rook is a web server interface and software package for R. It is very much like Ruby’s Rack. In fact it is so much like Ruby’s Rack that I decided to use the same name and basic class hierarchy. You could say I “borrowed heavliy” from Ruby’s Rack, and you wouldn’t be far from the truth. In fact, you could say “I stole their idea” and re-purposed it for R, and then you’d be telling the truth.

Regardless, I think it works very well for R. You can download Rook 1.0 from my github, or you can wait until it hits CRAN (it’s on its way. It’s there!).

Why would you want to use it? Well, it turns out that R 2.13 comes with a built-in web server fully capable of running user created applications. And it turns out that there’s another project named rApache that is fully capable of running user created applications. Unfortunately, you can’t run one application on the other because of differing APIs. But if you re-write them using the Rook specification, then you can theoretically run them on either web server, or another web server that supports R in the future.

What does it mean that Rook is a specification and a package? You can read more about the specification here, but basically the specification defines a simple interface between a web server and your application. Put another way, Rook defines a calling convention so that a web server knows how to execute your web application. Basically, a web server packages up everything about a web request that your application needs to know and then hands it off to your application, for each and every request.

The Rook package also contains convenience software that allows you to work with a web server in a more meaningful way. For instance, the Request class provides simple methods for doing things like converting CGI and POST data to R lists. Rook also contains a wrapper class named Rhttpd for working with R’s internal web server in a very simple way. Let’s look at a picture of how Rhttpd looks in the R interepreter below:

On the left-hand side of the big blue box you see two inputs to the R interpreter:

(1) The Keyboard interfaces to the R Read-Eval-Print-Loop (REPL). This isn’t part of Rook but it is a way to learn a bit about interfacing. The command prompt, that darker blue circle containing the “>” key,  is printed by the REPL and is now patiently awaiting for you to type valid R code and press the “Enter” key. It will then “R”ead what you have written, Parse and “E”valuate it, “P”rint out the results, and then show you the command prompt again. So the interface is quite simple; you just need to know how to write R expressions and hit the “Enter” key 😉

2) The Web browser interfaces to an object of the Rhttpd class. We’ll presume it’s called Rhttpd simplicity. When a web request is sent to R, Rhttpd intercepts it and creates a new R environment name “env”. It then finds the application it needs to run based on the URL. If the application is a simple R closure (i.e. a function), then it calls that closure and passes the “env” argument. If the application is a reference class with a “call” method, then the “call” method is invoked with the “env” argument. The result of each call are then transformed by Rhttpd into valid web responses and returned to the web browser. These are two situations depicted by the lighter clolored elipses in the picture above, And you can read more about the details in the Rook specification.

So I hope that gives you a good overview of the why and the what of Rook. And another very important point is this:

You can use it today, right now, on your own desktop! Whether you’re running Windows, Mac, or some derivative of UNIX! Really! You don’t need any other software! Just install it and read the Rhttpd help page to learn how to run example applications.

 Cheers!