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