Rook: A web server interface for R

This pecification defines the interface between web servers and R applications.

Rook applications

A Rook application is an R reference class object that implements a 'call' method or an R closure that takes exactly one argument, an environment, and returns a list with three named elements: the 'status', the 'headers', and the 'body'.

Hello World

Here is a basic Rook application as a closure that implements 'hello world':

function(env){
body = paste('<h1>Hello World! This is Rook',env$rook.version,'.</h1>')
list(
    status = 200L,
    headers = list(
    'Content-Type' = 'text/html'
    ),
    body = body
)
}

And the equivalent referenc class example:

setRefClass(
'HelloWorld',
methods = list(
    call = function(env){
    body = paste('<h1>Hello World! This is Rook',env$rook.version,'.</h1>')
    list(
        status = 200L,
        headers = list(
        'Content-Type' = 'text/html'
        ),
        body = body
    )
    }
)
)

The Environment

The environment argument is a true R environment object which the application is free to modify. It is required to contain the following variables:

In addtion, the environment must include the following Rook-specific variables:

The Input Stream

The rook.input variable must contain an object created from a reference class and respond to read_lines, read, and rewind:

read_lines: takes one argument, the number of lines to read. Includes partial ending line. read: takes one argument, the number of bytes to read. Returns a raw vector. rewind: Rewinds the input stream back to the beginning.

The Error Stream

The rook.error variable must contain an object created from a reference class and must respond to flush and cat:

flush: called with no arguments and makes the error stream immediately appear. cat: called with the same arguments as R's cat without the file and append argument.

The Response

The Status

This is an HTTP status value and must be greater than or equal to 100.

The Headers

This is a named list that contains string values only corresponding to valid HTTP headers.

The Body

This is either a character or raw vector. If the character vector is named with value 'file' then value of the vector is interpreted as the location of a file.