Chain is a simple specification and framework for building web applications in the node.js engine. node.js is deliberately simple and does not attempt to over specify how an application must function logically other than the mechanism it should use. Chain links multiple application components, hereafter referred to as “links” together by giving a standard way to pass requests between each other.
Chain specifies a default chain structure for links, based on each link containing a reference to the next link, ‘nextLink’, so that the environment knows where to go next if required. A link in a chain is a single instance of an object or object type.
A Chain compatible application has the following characteristics
- Each link MUST provide an onRequest method that recieves one argument, the chain environment.
- The Chain.Environment instance MUST be passed on. An link may not receive one instance of the Chain.Environment and pass a different instance to the next link
- Transitions between links must not block. The env.next() method must be non-blocking
- If an application is finished but does not respond to the client directly, it should call the done() method on the environment instance before finsihing the method.
- The context of the onRequest method is the link on which it is called.
The Chain.Environment instance is the common thread throughout the request. The Chain.Environment MUST include the following with the following meanings. (Chain.Environment instance is called env in the following list)
- env.request – The raw server request object from node.js
- env.response – The raw server response object from node.js
- env.onDone – Add a callback to run after the request is considered “done” by an application. These callbacks may run. See further for more information
- env.response.beforeHeaders – Add a callback to run just before the headers are sent to the client. This can be used to encode the session into the cookie and other such functionality. Optionally return an array with the arguments for response.sendHeader
- env.response.beforeSendBody – Add a filter to the send body method. By supplying a function that accepts the same arguments as response.sendBody you can modify the chunck prior to it being sent to the client. These can be queued for multi stage filtering. To change the arguments, return an array of the arguments to pass to sendBody
- env.done – The trigger to fire the next onDone callback. Each callback, if it has not completed the request, should call env.done() to run the next onDone callback in the queue.
- env.next – This function must move to the next link in the chain, or the specified link if one is given. It must be non-blocking
- env.response.headers – A buffer for response headers
- env.response.status – A buffer for the response status
- env.response.body – A buffer for the response body
Chain is an event emitter and will emit events as a central message dispatch. Chain will emit events on various stages of the build. The event should be a generic event type followed by a specified type. Any link can also have Chain broadcast events
Chain emits the following Events.
- “start”, “http” – emitted when the http server starts.