KETTLE-66: Provide a standard Kettle middleware wrapper for Multer

.gitignore

@@ -5,3 +5,5 @@ yarn.lock
 
 /coverage
 /node_modules
+/examples/multipartForm/uploads/*
+!/examples/multipartForm/uploads/.gitkeep

docs/KettleTestingFramework.md

@@ -302,6 +302,14 @@ Consult the framework tests at [tests/shared/SessionTestDefs.js](../tests/shared
 These tests are also a good example of configuring custom [middleware](#working-with-middleware) into the middle of a request's middleware chain. These tests include a middleware grade named `kettle.tests.middleware.validateSession` which
 will reject requests without a particular piece of populated session data, before processing reaches the request's `requestHandler`.
 
+### Sending multipart-form testing fixtures via POST with `kettle.test.request.form`
+
+The `kettle.test.request.form` grade derives from `kettle.test.request.http`, but accepts additional configuration for sending `multipart-form-data` requests that can include a mix of fields and files.
+
+### Configuration options available on `kettle.test.request.form`
+
+<a href="#configuration-options-available-on-kettletestrequesthttp">In addition to all options from `kettle.test.request.http`</a>, the grade accepts the following options:
+
 ### Issuing WebSockets testing fixtures with `kettle.test.request.ws`
 
 A sibling grade of `kettle.test.request.http` is `kettle.test.request.ws` which will allow the testing of WebSockets endpoints in an analogous way. You should browse the `ws` project's documentation for

docs/Middleware.md

@@ -161,6 +161,13 @@ to implement your own.
     <td><code>secret</code> and <code>middlewareOptions</code>, forwarded to the two arguments of <a href="https://github.com/expressjs/cookie-parser#cookieparsersecret-options"><code>cookieParser(secret, options)</code></a></td>
     <td>none</td>
 </tr>
+<tr>
+    <td><code>kettle.middleware.multer</code></td>
+    <td><a href="https://github.com/expressjs/multer">expressjs/multer</a></td>
+    <td>Handles <code>multipart/form-data</code>, primarily for file uploading.</td>
+    <td><code>middlewareOptions</code>, forwarded to <code>multer(options)</code>, and <code>formFieldOptions</code>, used to configure the field parameters for uploaded files as described in <a href="https://github.com/expressjs/multer#usage">multer's documentation</a>. <strong>Note</strong>: some <code>multer</code> options require functions as their values, and are implemented in Kettle using <code>invokers</code>; see the documentation below on using <code>kettle.middleware.multer</code> for more details.</td>
+    <td>none – user must configure on each use</td>
+</tr>
 <tr>
     <td><code>kettle.middleware.session</code></td>
     <td><a href="https://github.com/expressjs/session">expressjs/session</a></td>
@@ -265,5 +272,82 @@ fluid.defaults("examples.static.handler", {
         }
     }
 });
+```
+
+#### Using the multer middleware
+
+This shows a basic single-file upload; for more examples of possible usage, refer to the `kettle.tests.multer.config.json5` configuration file in `tests/configs` and the Multer documentation.
+
+Code for this example can be found in `/examples/multipartForm`.
+
+```javascript
+fluid.defaults("examples.uploadConfig", {
+    "gradeNames": ["fluid.component"],
+    "components": {
+        "server": {
+            "type": "kettle.server",
+            "options": {
+                "port": 8081,
+                "components": {
+                    "imageUpload": {
+                        "type": "kettle.middleware.multer",
+                        "options": {
+                            "formFieldOptions": {
+                                "method": "single",
+                                "fieldName": "image"
+                            },
+                            "members": {
+                                "storage": "{that}.diskStorage"
+                            },
+                            "invokers": {
+                                "diskStorageDestination": {
+                                    "funcName": "examples.uploadConfig.diskStorageDestination"
+                                }
+                            }
+                        }
+                    },
+                    "app": {
+                        "type": "kettle.app",
+                        "options": {
+                            "requestHandlers": {
+                                "imageUploadHandler": {
+                                    "type": "examples.uploadConfig.handler",
+                                    "route": "/upload",
+                                    "method": "post"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+});
+```
+
+And our corresponding handlers and `diskStorageDestination` invoker (to set our own destination path):
+
+```javascript
+examples.uploadConfig.diskStorageDestination = function (req, file, cb) {
+    cb(null, "./examples/multipartForm/uploads");
+};
+
+fluid.defaults("examples.uploadConfig.handler", {
+    gradeNames: "kettle.request.http",
+    requestMiddleware: {
+        imageUpload: {
+            middleware: "{server}.imageUpload"
+        }
+    },
+    invokers: {
+        handleRequest: "examples.uploadConfig.handleRequest"
+    }
+});
 
-```
+examples.uploadConfig.handleRequest = function (request) {
+    var uploadedFileDetails = request.req.file;
+    request.events.onSuccess.fire({
+        message: fluid.stringTemplate("POST request received on path /upload; file %originalName uploaded to %uploadedPath", {originalName: uploadedFileDetails.originalname, uploadedPath: uploadedFileDetails.path})
+    });
+};
+```

examples/multiPartForm/multiPartForm-client.js

@@ -0,0 +1,44 @@
+/**
+ * Kettle Sample app - multipartForm client
+ *
+ * Copyright 2018 OCAD University
+ *
+ * Licensed under the New BSD license. You may not use this file except in
+ * compliance with this License.
+ *
+ * You may obtain a copy of the License at
+ * https://github.com/gpii/universal/LICENSE.txt
+ */
+
+ "use strict";
+
+ var fluid = require("infusion"),
+     kettle = require("../../kettle.js"),
+     examples = fluid.registerNamespace("examples");
+
+ /* Client definitions - issue a request against the Kettle config's server */
+
+ // Gain access to kettle.test.request definitions
+ kettle.loadTestingSupportQuiet();
+
+ // Define a test component firing a request to the server
+ var request = kettle.test.request.formData({
+     path: "/upload",
+     method: "POST",
+     formData: {
+         files: {
+             image: "@expand:fluid.module.resolvePath(%kettle/tests/data/multer/test.png)"
+         }
+     },
+     listeners: {
+         onComplete: "examples.uploadConfig.receiver"
+     }
+ });
+
+examples.uploadConfig.receiver = function (body) {
+    console.log("Successfully received response ", body, " from Kettle server");
+    process.exit(0);
+};
+
+// Send the POST request to the server
+request.send();

examples/multiPartForm/multiPartForm-code.js

@@ -0,0 +1,90 @@
+/**
+ * Kettle Sample app - multipartForm using code
+ *
+ * Copyright 2018 OCAD University
+ *
+ * Licensed under the New BSD license. You may not use this file except in
+ * compliance with this License.
+ *
+ * You may obtain a copy of the License at
+ * https://github.com/gpii/universal/LICENSE.txt
+ */
+
+"use strict";
+
+var fluid = require("infusion"),
+    examples = fluid.registerNamespace("examples");
+
+require("../../kettle.js");
+
+fluid.defaults("examples.uploadConfig", {
+    "gradeNames": ["fluid.component"],
+    "components": {
+        "server": {
+            "type": "kettle.server",
+            "options": {
+                "port": 8081,
+                "components": {
+                    "imageUpload": {
+                        "type": "kettle.middleware.multer",
+                        "options": {
+                            "formFieldOptions": {
+                                "method": "single",
+                                "fieldName": "image"
+                            },
+                            "members": {
+                                "storage": "{that}.diskStorage"
+                            },
+                            "invokers": {
+                                "diskStorageDestination": {
+                                    "funcName": "examples.uploadConfig.diskStorageDestination"
+                                }
+                            }
+                        }
+                    },
+                    "app": {
+                        "type": "kettle.app",
+                        "options": {
+                            "requestHandlers": {
+                                "imageUploadHandler": {
+                                    "type": "examples.uploadConfig.handler",
+                                    "route": "/upload",
+                                    "method": "post"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+});
+
+examples.uploadConfig.diskStorageDestination = function (req, file, cb) {
+    cb(null, "./examples/multipartForm/uploads");
+};
+
+fluid.defaults("examples.uploadConfig.handler", {
+    gradeNames: "kettle.request.http",
+    requestMiddleware: {
+        imageUpload: {
+            middleware: "{server}.imageUpload"
+        }
+    },
+    invokers: {
+        handleRequest: "examples.uploadConfig.handleRequest"
+    }
+});
+
+examples.uploadConfig.handleRequest = function (request) {
+    var uploadedFileDetails = request.req.file;
+    request.events.onSuccess.fire({
+        message: fluid.stringTemplate("POST request received on path /upload; file %originalName uploaded to %uploadedPath", {originalName: uploadedFileDetails.originalname, uploadedPath: uploadedFileDetails.path})
+    });
+};
+
+// Construct the server using the above config
+examples.uploadConfig();
+
+// Load the client to make a test request
+require("./multipartForm-client.js");

kettle.js

@@ -1,7 +1,7 @@
 /*
 Kettle Main Module Loader
 
-Copyright 2012-2013 OCAD University
+Copyright 2012-2018 OCAD University
 Copyright 2015 Raising the Floor (International)
 
 Licensed under the New BSD license. You may not use this file except in
@@ -25,6 +25,7 @@ require("./lib/KettleApp.js");
 require("./lib/KettleConfigLoader.js");
 require("./lib/KettleResolvers.js");
 require("./lib/KettleMiddleware.js");
+require("./lib/KettleMiddleware-Multer.js");
 require("./lib/KettleMultiConfig.js");
 require("./lib/KettleRouter.js");
 require("./lib/KettleRequest.js");
@@ -36,6 +37,7 @@ require("./lib/KettleSession.js");
 kettle.loadTestingSupport = function () {
     require("./lib/test/KettleTestUtils.js");
     require("./lib/test/KettleTestUtils.http.js");
+    require("./lib/test/KettleTestUtils.form.js");
     require("./lib/test/KettleTestUtils.ws.js");
 };