kettle/docs/RequestHandlersAndApps.md

---
title: Kettle Request Handlers and the kettle.app grade
layout: default
category: Kettle
---
# Kettle Request Handlers and the `kettle.app` grade

A [`kettle.server`](Servers.md) comprises one or more `kettle.app` units, each of which comprises an independently
mountable application unit. Within a [`kettle.app`](#kettle.app), each
type of request handled by the application is defined using a
[`kettle.request`](#how-to-implement-a-request-handler) component.

<a id="kettle.app"></a>

## Registering and implementing a request handler

Request handlers are registered in the `requestHandlers` section of the options of a `kettle.app` – see the
[sample app](ConfigsAndApplications.md#a-simple-kettle-application) for positioning of this component in the
containment structure. This consists of a free hash of `handlerName` strings to `handlerRecord` structures.

### Structure of the `requestHandlers` option of a `kettle.app`

```snippet
{
<handlerName> : <handlerRecord>,
<handlerName> : <handlerRecord>,
...
}
```

Note that the `handlerName`s are simply free strings and have no function other than to uniquely name the handler in the
context of its app. These strings exist to allow easy alignment when
multiple apps are merged together from different sources to produce combined apps.

### Structure of the `handlerRecord` structure

<table>
    <thead>
        <tr>
            <th colspan="3">Members of an <code>handlerRecord</code> entry within the <code>requestHandlers</code> block
            of a <code>kettle.app</code> component
            </th>
        </tr>
        <tr>
            <th>Member</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code></td>
            <td><code>String</code></td>
            <td>The name of a request handling grade, which must be descended from <code>kettle.request</code>. If you
            supply the <code>method</code> field, your grade must be descended from <code>kettle.request.http</code>.
            </td>
        </tr>
        <tr>
            <td><code>route</code></td>
            <td><code>String</code></td>
            <td>An express-compatible <a href="http://expressjs.com/guide/routing.html">routing</a> string, expressing
            the range of HTTP paths to be handled by this handler, together with any named parameters and query
            parameters that should be captured. The exact syntax for route matching is documented more precisely at
            <a href="https://github.com/pillarjs/path-to-regexp">pillarjs</a>.</td>
        </tr>
        <tr>
            <td><code>gradeNames</code> (optional)</td>
            <td><code>String/Array of String</code></td>
            <td>One or more grade names which will be mixed in to the constructed handler when it is constructed.</td>
        </tr>
        <tr>
            <td><code>prefix</code> (optional)</td>
            <td><code>String</code></td>
            <td>A routing prefix to be prepended to this handler's <code>route</code>. The prefix plus the route
            expression must match the incoming request in order for this handler to be activated –
            but if it is, it will only see the portion of the URL matched by <code>route</code> in the member
            <code>request.req.url</code>. The entire incoming URL will remain visible in
            <code>request.req.originalUrl</code> –
            this is the same behaviour as express.js <a href="http://expressjs.com/api.html#app.use">routing system</a>.
            It is primarily useful when using
            <a href="./Middleware.md#built-in-standard-middleware-bundled-with-kettle">static middleware</a>
            which will compare the <code>req.url</code> value with the filesystem path relative to its mount point.
        </tr>
        <tr>
            <td><code>method</code> (optional)</td>
            <td><code>String</code> value – one of the valid
                <a href="https://github.com/nodejs/node/blob/master/deps/http_parser/http_parser.h#L88">HTTP methods</a>
                supported by node.js, expressed in lower case, or else a comma-separated sequence of such values.
            </td>
            <td>The HTTP request type(s) which this handler will match. <code>method</code> is omitted in the
            case that the request handling grade is not descended from <code>kettle.request.http</code> – the only
            currently supported requests of that type are WebSockets requests descended from <code>kettle.request.ws</code>.
            </td>
        </tr>
    </tbody>
</table>

### How to implement a request handler

A handler for a particular request must have a
[grade](http://docs.fluidproject.org/infusion/development/ComponentGrades.html)
registered with Infusion whose name matches the `type` field in the `handlerRecord` structure just described. The parent
grades of this grade must be consistent with the the request you expect to handle descended from `kettle.request.http`
in the case of an HTTP request, or `kettle.request.ws` in the case of a WebSockets request. In addition, the grade must
define (at minimum) an [invoker](http://docs.fluidproject.org/infusion/development/Invokers.html) named `handleRequest`.
This invoker will be called by Kettle when your route is matched, and be supplied a single argument holding the
***request object***, an object whose grade is your request handler's grade, which the framework has
constructed to handle the request.

We duplicate the definitions from the [sample application](ConfigsAndApplications.md#a-simple-kettle-application) in
order to show a minimal request handler grade and request handler function:

```javascript
fluid.defaults("examples.simpleConfig.handler", {
    gradeNames: "kettle.request.http",
    invokers: {
        handleRequest: "examples.simpleConfig.handleRequest"
    }
});

examples.simpleConfig.handleRequest = function (request) {
    request.events.onSuccess.fire({
        message: "GET request received on path /handlerPath"
    });
};
```

In the next section we will talk more about request (handler) objects, the members you can expect on them, and how to
use them.

<a id="kettle.request"></a>

## Request components

A ***request component*** is constructed by Kettle when it has determined the correct
[handler record](#registering-and-implementing-a-request-handler) which matches the incoming request. This request
component will be usefully populated with material drawn from the request and node.js initial process of handling it.
It also contains various elements supplied by Kettle in order to support you in handling the request. You can add any
further material that you like to the request object by adding entries to its grade definition, of any of the types
supported by Infusion's
[component configuration options](http://docs.fluidproject.org/infusion/development/ComponentConfigurationOptions.html).
Here we will document the standard members that are placed there by Kettle for the two standard request types which are
supported, `kettle.request.http` and `kettle.request.ws`. These are derived from a common grade `kettle.request` which
defines several common members and workflow elements.

### Members defined by the Kettle framework at top-level on an HTTP request component

The following table describes the members defined on `kettle.request.http`. Where these are not listed as "only for
`kettle.request.http`" they are defined in the
base grade `kettle.request` and so are also available for WebSockets components of type `kettle.request.ws`.

<table>
    <thead>
        <tr>
            <th colspan="3">Members defined by default at top-level on an HTTP request component of type
                <code>kettle.request.http</code></th>
        </tr>
        <tr>
            <th>Member</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>req</code></td>
            <td><a href="https://nodejs.org/api/http.html#http_http_incomingmessage"><code>http.IncomingMessage</code></a></td>
            <td>The request object produced by node.js – this is the value which is commonly referred to as
                <a href="http://expressjs.com/4x/api.html#req"><code>req</code></a> in the standard express
                <a href="http://expressjs.com/guide/using-middleware.html">middleware pattern</a></td>
        </tr>
        <tr>
            <td><code>res</code> (only for <code>kettle.request.http</code>)</td>
            <td><a href="https://nodejs.org/api/http.html#http_class_http_serverresponse"><code>http.ServerResponse</code></a></td>
            <td>The response object produced by node.js – this is the value which is commonly referred to as
                <a href="http://expressjs.com/4x/api.html#res"><code>res</code></a> in the standard express
                <a href="http://expressjs.com/4x/api.html#req">middleware pattern</a>
            </td>
        </tr>
        <tr>
            <td><code>events.onSuccess</code> (only for <code>kettle.request.http</code>)</td>
            <td><a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html"><code>Event</code></a></td>
            <td>A standard <a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html">Infusion
                Event</a> which should be fired if the request is to produce a response successfully. The event argument
                will produce the response body – if it is of type <code>Object</code>, it will be JSON-encoded.
            </td>
        </tr>
        <tr>
            <td><code>events.onError</code></td>
            <td>
                <a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html"><code>Event</code></a>
            </td>
            <td>A standard <a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html">Infusion
                Event</a> which should be fired if the request is to send an error response.
                For a request of type <code>kettle.request.http</code>, the argument to the event must be an
                <code>Object</code> with at least
                a field <code>message</code> of type <code>String</code> holding the error message to be returned to the
                client. The argument can also include a member <code>statusCode</code> of type <code>Number</code>
                holding the HTTP status code to accompany the error if this is not supplied, it will default to 500.
            </td>
        </tr>
        <tr>
            <td><code>handlerPromise</code> (only for <code>kettle.request.http</code>)</td>
            <td><code>Promise</code></td>
            <td>This promise is a proxy for the two events <code>onSuccess</code> and <code>onError</code>, packaged as
                a <a href="https://www.promisejs.org/">Promise</a>. This promise exposes methods <code>resolve</code>
                and <code>reject</code> which forward their arguments to <code>onSuccess</code> and <code>onError</code>
                respectively. In addition, the promise exposes a <code>then</code> method which accepts two callbacks
                which can be used to listen to these event firings respectively. Note that this promise is not compliant
                with any particular specification for promises, including ES6, A+, etc. – in the language of those
                specifications, it is simply a <code>thenable</code> which also includes the standard resolution methods
                <code>resolve</code> and <code>reject</code>. Implementation at
                <a href="https://github.com/fluid-project/infusion/blob/master/src/framework/core/js/FluidPromises.js#L21">FluidPromises.js</a>.
            </td>
        </tr>
    </tbody>
</table>

Note that, conversely with the `req` property of the Kettle request component, the Kettle request component itself will
be marked onto the node.js request object so that it can easily be retrieved from standard middleware, etc. – it will
be available as `req.fluidRequest` where `req` is the request object described in the table above. More details follow
on middleware in the section [working with middleware](Middleware.md#working-with-middleware).

<a id="kettle.request.ws"></a>

### WebSockets request components of type `kettle.request.ws`

WebSockets communications in a Kettle application are mediated by the [ws](https://github.com/websockets/ws) WebSockets
library – you should get familiar with the documentation for that library if you intend to use this functionality
significantly. It is also worth spending some time familiarising yourself with at least some of the `ws` implementation
code since there are several aspects not properly covered by the documentation.

The request component for a WebSockets request, derived from the grade `kettle.request.ws`, includes the members in the
above table which are not marked as `kettle.request.http` only via `kettle.request`, as well as several more members
described in the following table:

<table>
    <thead>
        <tr>
            <th colspan="3">Members defined by default at top-level on a WebSockets request component of type
            <code>kettle.request.ws</code></th>
        </tr>
        <tr>
            <th>Member</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>events.onBindWs</code></td>
            <td><a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html"><code>Event</code></a></td>
            <td>A standard <a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html">Infusion
                Event</a> which is fired by the framework when the original HTTP connection has completed the
                <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">handshake and upgrade sequence</a>
                and the
                <a href="https://github.com/websockets/ws/blob/master/doc/ws.md#class-wswebsocket"><code>ws.WebSocket</code></a>
                object has been allocated. Any listener registered to this event will receive two arguments - firstly,
                the <code>kettle.request.ws</code> component itself, and secondly the
                <a href="https://github.com/websockets/ws/blob/master/doc/ws.md#class-wswebsocket"><code>ws.WebSocket</code></a>
                object.
            </td>
        </tr>
        <tr>
            <td><code>ws</code></td>
            <td><a href="https://github.com/websockets/ws/blob/master/doc/ws.md#class-wswebsocket"><code>ws.WebSocket</code></a></td>
            <td>The <code>ws.WebSocket</code> advertised by the <a href="https://github.com/websockets/ws"><code>ws</code></a>
                WebSockets library as allocated to handle one end of an established WebSockets connection. This will be
                of the variety referred to in the <code>ws</code> docs as "a WebSocket constructed by a Server".
                This member will only be present after the <code>onBindWs</code> event described in the previous row has
                fired.
            </td>
        </tr>
        <tr>
            <td><code>sendMessage</code></td>
            <td><code>Function(message: Any)</code></a></td>
            <td>The <code>sendMessage</code> method is used to sent a WebSocket message to the client. By default, the
                <code>sendMessageJSON</code> options described in the table below is set to <code>true</code> and so
                <code>sendMessage</code> will accept a JavaScript object which will be encoded as JSON.
            </td>
        </tr>
        <tr>
            <td><code>sendTypedMessage</code></td>
            <td><code>Function(type: String, payload: Object)</code></a></td>
            <td>Operates a simple "typed message" system which will fire a payload to <code>sendMessage</code>
                consisting of <code>{type: type, payload: payload}</code>. This method is only useful together with the
                <code>sendMessageJSON: true</code> option (its default value).
            </td>
        </tr>
        <tr>
            <td><code>events.onReceiveMessage</code></td>
            <td><a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html"><code>Event</code></a></td>
            <td>A standard <a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html">Infusion
                Event</a> which is fired by the framework when a message is received from the client at the other end of
                the WebSockets connection. The arguments to the event are <code>(that, message)</code> where
                <code>that</code> represents this request component itself, and <code>message</code> represnts
                the message sent by the client. If the <code>receiveMessageJSON</code> option is set to
                <code>true</code> for this component (the default), the message will have been decoded as JSON.
            </td>
        </tr>
        <tr>
            <td><code>events.onSendMessage</code></td>
            <td><a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html"><code>Event</code></a></td>
            <td>A standard <a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html">Infusion
                Event</a> which operates the workflow started by the <code>sendMessage</code> method.
                This is a <a href="./DataSources.md#transforming-promise-chains">transforming promise chain</a> event
                for which each listener has the chance to transform the payload before it is sent to the next. More
                information is available for the
                <a href="http://docs.fluidproject.org/infusion/development/PromisesAPI.html#fluid-promise-firetransformevent-event-payload-options-">
                <code>fireTransformEvent</code></a> function from Infusion's Promises API
            </td>
        </tr>
        <tr>
            <td><code>events.onError</code></td>
            <td><a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html"><code>Event</code></a></td>
            <td>A standard <a href="http://docs.fluidproject.org/infusion/development/InfusionEventSystem.html">Infusion
                Event</a> which should be fired if the request is to send an error response.
                This event has the same name as the one fired by a <code>kettle.request.http</code> but the behaviour
                and semantic is different. Rather than sending an HTTP error response, the framework instead
                emits a WebSockets  event of type <code>error</code>. Because of this, the <code>statusCode</code> field
                of the event argument should not be used. However, it is recommended that the event payload still
                includes a field <code>message</code> of type <code>String</code> holding the error message to be
                returned to the client, as well as a boolean member <code>isError</code> with the value
                <code>true</code>.
            </td>
        </tr>
    </tbody>
</table>

A `kettle.request.ws` accepts the following configurable options at top level:

<table>
    <thead>
        <tr>
            <th colspan="3">Supported configurable options for a <code>kettle.request.ws</code></th>
        </tr>
        <tr>
            <th>Option</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>sendMessageJSON</code></td>
            <td><code>Boolean</code> (default: <code>true</code>)</td>
            <td>If this is set to <code>true</code>, the argument supplied to the component's <code>sendMessage</code>
                method will be encoded as JSON. Otherwise the argument will be sent to <code>websocket.send</code>
                as is.
            </td>
        </tr>
        <tr>
            <td><code>receiveMessageJSON</code></td>
            <td><code>Boolean</code> (default: <code>true</code>)</td>
            <td>If this is set to <code>true</code>, the argument received by listeners to the component's
                <code>onReceiveMessage</code> event will be encoded as JSON. Otherwise the value will be transmitted as
                from the WebSocket's <code>message</code> event unchanged.
            </td>
        </tr>
    </tbody>
</table>

### Ending a WebSockets conversation

The currently recommended scheme for terminating a WebSockets conversation managed by a `kettle.request.ws` component
is to call the standard [`close`](https://github.com/websockets/ws/blob/master/doc/ws.md#websocketclosecode-data)
method on the top-level `ws` member. This accepts two optional arguments - a
[WebSockets status code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent) and a description message. After
processing the connection termination sequence, the request component will be automatically destroyed by the framework.

### Example mini-application hosting a WebSockets endpoint

The following example shows a minimal Kettle application which hosts a single WebSockets request handler named
`webSocketsHandler` at the path `/webSocketsPath`. This handler
simply logs any messages received to the console.

```javascript

fluid.defaults("examples.webSocketsConfig", {
    gradeNames: "fluid.component",
    components: {
        server: {
            type: "kettle.server",
            options: {
                gradeNames: ["kettle.server.ws"],
                port: 8081,
                components: {
                    app: {
                        type: "kettle.app",
                        options: {
                            requestHandlers: {
                                webSocketsHandler: {
                                    "type": "examples.webSocketsConfig.handler",
                                    "route": "/webSocketsPath"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
});

fluid.defaults("examples.webSocketsConfig.handler", {
    gradeNames: "kettle.request.ws",
    listeners: {
        onReceiveMessage: "examples.webSocketsConfig.receiveMessage"
    }
});

examples.webSocketsConfig.receiveMessage = function (request, message) {
    console.log("Received WebSockets message " + JSON.stringify(message, null, 2));
};

// Construct the server using the above config
examples.webSocketsConfig();
```