API.textile

Demonstrates the API for Chain

For the purposes of this document, the “chain” variable is the imported Chain object. The “env” object is the chain request environment object

A Basic Link

A link is an object that has an onRequest function.

var myLink = {
  onRequest : function(env){
    env.response.body = "In myLink";
    env.next();
  }
}

Moving around the Chain

Moving from one link to another must not block. Chain takes care of this for you by calling the next Link for you and ensuring that it’s not blocking.

Sending the request forward

To send the request from one link to another:

// Simple pass it forward:
env.next();

// Pass it forward with a callback:
env.next(function(){
  /* do stuff here */
})

// pass it forward to a known link:
env.next(someLink);

// pass it forward to a known link with a callback:
env.next(someLink, function(){ /* stuff */ }

Sending the request back through the chain

When you recieve a request you can add a function to be called “on the way out” so that you can modify / affect the response after the endpoint has done it’s thing.

//First register a callback as above
// Send the request back one link:
env.done();

Any link that does not finish the request should call env.done(). All such callbacks should similarly call env.done()

Callbacks

Callbacks are run as a stack. That is, reverse declared order (last is run first)
These callbacks are available. They do not have to be used, and should only be used if you have reason.

beforeHeaders

These callbacks run prior to response.sendHeader. By returning an array with the arguments for response.sendHeader you can intercept and modify the headers before they’re sent to the client.

// A callback that modifies the headers
env.response.beforeHeaders(function(status, headers){
  // do stuff to the headers and or status
  return [status, headers];
});

// A callback that does not modify the headers
env.response.beforeHeaders(function(status, headers){
  // do stuff
  // no return
});

beforeSendBody

Run before each chunk is sent for response.sendBody. To alter the response chunk, return an array with new arguments for the response.sendBody function.

The initial reason for this is to enable per-chunk gzipping enabled by an upstream link.

// A simple gzipper
env.response.beforeSendBody(function(chunk, encoding){
  // do stuff to the chunk
  // maybe audit / log stuff
  return [modifiedChunk, encoding]
})

onDone

The callbacks to execute “on the way out” of the chain. These are executed in reverse declared order with env.done()

// Added explicilty
env.onDone(function(){
  // Do stuff if the request comes by here again
  env.done() // be sure to call this to call the next callback unless you've called env.response.finsih()
})

// Implicitly adding to the onDone stack when sending the request forward
env.next(function(){
  // an onDone callback.  Will be called if the request makes it back this far
  env.done();
})

Making a Link

There are any number of ways to make a link. At it’s heart a link is an object that implements an onRequest(env) method. If there is a downstream link, it should attach that to the ‘nextLink’ attribute.

Constructing a Chain

When you construct a chain, you’re basically getting the builder to add a nextApp attribute to each link that provides a default nextLink. The link itself can choose to either let the env use that link as the next link in the chain, choose another link to send the request to, or simply respond to the client and finish the request.

// Create a builder object that you can configure
var builder = new chain.Builder();
builder
  .use(function(env){ /* wrapped in an object.  this.nextApp available */})
  .use(someObj)
  .use(myConstructor, any, argument, list); // calls   Object.create.apply(Object, argumentsFromUse)

var app = builder.build();