1 | # Kettle
|
2 |
|
3 | Kettle is an integration technology which promotes the expression of servers handling HTTP and WebSockets endpoints.
|
4 | With a few exceptions, Kettle implements no primary functionality of its own, but aggregates the facilities of
|
5 | [express](http://expressjs.com/) and [ws](https://github.com/websockets/ws), as well as middleware held in the wider [pillarjs](https://github.com/pillarjs)
|
6 | "Bring your own HTTP Framework Framework" ecosystem. Kettle applications can easily incorporate any express-standard middleware, as well as coexisting with standard express apps targeted at the same
|
7 | node.js <a href="https://nodejs.org/api/http.html#http_class_http_server"><code>http.Server</code></a>. Since Kettle applications are expressed declaratively, in the JSON format encoding [Infusion](https://github.com/fluid-project/infusion)'s component trees, it is possible to adapt existing
|
8 | applications easily, as well as inserting middleware and new handlers anywhere in the pipeline without modifying the original application's code. This makes
|
9 | Kettle suitable for uses where application functionality needs to be deployed flexibly in a variety of different configurations.
|
10 |
|
11 | In fact, Kettle's dependency on express itself is minimal, since the entirety of the Kettle request handling pipeline is packaged
|
12 | as a single piece of express-compatible middleware – Kettle could be deployed against any other consumer of middleware or even a raw node.js HTTP server.
|
13 |
|
14 | # Contents of this repository
|
15 |
|
16 | ## Core Kettle implementation
|
17 |
|
18 | This is packaged as Infusion [grades](http://docs.fluidproject.org/infusion/development/ComponentGrades.html) derived from [`kettle.server`](./docs/Servers.md#kettle.server),
|
19 | [`kettle.request`](./docs/RequestHandlersAndApps.md#kettle.request) and [`kettle.app`](./docs/RequestHandlersAndApps.md#kettle.app). The first two of these exist in variants specialized both for plain
|
20 | HTTP (with the `.http` suffix) and for WebSockets (with the `.ws` suffix) – `kettle.app` does not specialize.
|
21 |
|
22 | ## Contents - Testing
|
23 |
|
24 | As well as the integration technology implementing Kettle itself, this repository also contains functionality helpful for testing HTTP and WebSockets
|
25 | servers written in arbitrary technologies. This is accessed by running `kettle.loadTestingSupport()` after having called `require("kettle")`. Kettle testing
|
26 | support allows HTTP and WebSockets client requests to be packaged as [Infusion](https://github.com/fluid-project/infusion) components, suitable for use with Infusion's
|
27 | [IoC Testing Framework](http://docs.fluidproject.org/infusion/development/IoCTestingFramework.html). Any user of Kettle's testing support needs to have [node-jqunit](https://github.com/fluid-project/node-jqunit)
|
28 | registered as a member of their own project's `devDependencies` in their own package.json.
|
29 |
|
30 | Kettle runs on [node.js](https://nodejs.org) version 4.x (see [package.json](package.json) for current dependency profile).
|
31 |
|
32 | ## Contents - DataSources
|
33 |
|
34 | The Kettle repository also contains a few implementations of the simple `DataSource` contract for read/write access to data with a simple semantic (broadly the same as that
|
35 | encoded in [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) although the current DataSource semantic does not provide explicitly for deletion). See the documentation section
|
36 | on [DataSources](./docs/DataSources.md) for details of this contract, the available implementations and how to use them.
|
37 |
|
38 | This repository contains DataSource implementations suitable for HTTP endpoints (with a particular variety specialised for accessing CouchDB databases with CRUDlike semantics) as well as the filesystem, with
|
39 | an emphasis on JSON payloads.
|
40 |
|
41 | # Getting Started and Community
|
42 |
|
43 | ## Installation instructions
|
44 |
|
45 | Firstly, install node and npm by running a standard installer from [node.js](https://nodejs.org). Clone this repository and then run `npm install`.
|
46 |
|
47 | ## Issue Tracking
|
48 |
|
49 | Issue tracking is at http://issues.fluidproject.org/browse/KETTLE .
|
50 |
|
51 | ## IRC
|
52 |
|
53 | Visit `#fluid-work` on Freenode – community resources are linked at [Fluid's IRC Channels](https://wiki.fluidproject.org/display/fluid/IRC+Channel).
|
54 |
|
55 | ## Mailing list
|
56 |
|
57 | Contact us on the [fluid-work](https://wiki.fluidproject.org/display/fluid/Mailing+Lists) mailing list with any problems or comments.
|
58 |
|
59 | ## Uses of Kettle and related projects
|
60 |
|
61 | The primary user of Kettle is the [GPII](http://gpii.net/)'s autopersonalisation infrastructure, held at [GPII/universal](https://github.com/GPII/universal). Kettle is used
|
62 | to provide a flexible means of deploying the GPII's "Flow Manager" and related components distributed across multiple local and remote installations.
|
63 |
|
64 | A closely related project to Kettle is [gpii-express](https://github.com/GPII/gpii-express) which is used in other GPII projects such as the [terms registry](https://github.com/GPII/common-terms-registry) and
|
65 | [unified listing](https://github.com/GPII/ul-api). This is similar in architecture to Kettle (wrapping express primitives such as servers and requests into dynamically constructed Infusion components)
|
66 | but slightly different in emphasis –
|
67 |
|
68 | * gpii-express allows independently mounted application units with nested routing, in the Express 4.x style – whereas Kettle is currently limited to flat Express 3.x-style routing
|
69 | * Kettle incorporates support for WebSockets endpoints, whereas gpii-express does not
|
70 | * Kettle incorporates support for DataSources (see [DataSources](./docs/DataSources.md) )
|
71 |
|
72 | The request handling architecture for gpii-express and Kettle is quite similar and the projects will probably converge over time. gpii-express currently already depends on Kettle to get access to its
|
73 | HTTP [testing](./docs/KettleTestingFramework.md) support.
|
74 |
|
75 | # Documentation
|
76 |
|
77 | Documentation and sample code for working with Kettle is contained in the [docs](./docs) directory. Kettle is based on Fluid [Infusion](http://fluidproject.org/infusion.html)'s
|
78 | [component model](http://docs.fluidproject.org/infusion/development/HowToUseInfusionIoC.html). If you aren't familiar
|
79 | with the syntax and meaning of Infusion component trees, it is a good idea to browse the documentation, tutorials and examples at the
|
80 | Infusion [documentation site](http://docs.fluidproject.org/infusion/development/).
|
81 |
|
82 | It contains the following topics:
|
83 |
|
84 | 1. Defining top-level [Kettle applications using "config" files](docs/ConfigsAndApplications.md).
|
85 | 2. Defining HTTP and Websockets servers using the grades [`kettle.server`](./docs/Servers.md#kettle.server) and [`kettle.server.ws`](./docs/Servers.md#kettle.server.ws).
|
86 | 3. Defining Kettle request handlers derived from grades [`kettle.request`](./docs/RequestHandlersAndApps.md#kettle.request) grouped into app units derived from [`kettle.app`](./docs/RequestHandlersAndApps.md#kettle.app)
|
87 | 4. Working with standard express [middleware](./docs/Middleware.md) – incorporating any standard middleware from the express community and registering it into a Kettle application
|
88 | 5. Working with [DataSources](./docs/DataSources.md) to abstract over asynchronous access to (primarily JSON-formatted) data stored locally or remotely
|
89 | 6. Defining conversational, asynchronous test fixtures against HTTP and WebSockets servers using the [Kettle testing framework](./docs/KettleTestingFramework.md)
|
90 |
|
91 | Of these elements of this module, those described in topics 1, 5 and 6 (configs, DataSources and the testing framework) are portable and do not depend specifically on the
|
92 | Kettle server and request handling infrastructure – they can be used together with any technologies defining node.js HTTP and WebSockets servers (or in the case of configs,
|
93 | any node.js enabled [Infusion](http://fluidproject.org/infusion.html) application).
|
94 |
|