Feature: a caching HTTP proxy for integration tests

CODEOWNERS

@@ -9,6 +9,7 @@
 packages/authentication/* @bajtos @raymondfeng
 packages/boot/* @raymondfeng @virkt25
 packages/build/* @bajtos @raymondfeng
+packages/http-caching-proxy/* @bajtos
 packages/cli/* @raymondfeng @shimks
 packages/context/* @bajtos @raymondfeng
 packages/core/* @bajtos @raymondfeng

docs/apidocs.html

@@ -19,6 +19,7 @@ <h3>List of packages</h3>
       <ul>
         <li><a href="./authentication.html">@loopback/authentication</a></li>
         <li><a href="./boot.hml">@loopback/boot</a></li>
+        <li><a href="./caching-proxy.html">@loopback/caching-proxy</a></li>
         <li><a href="./context.html">@loopback/context</a></li>
         <li><a href="./core.html">@loopback/core</a></li>
         <li><a href="./metadata.html">@loopback/metadata</a></li>

docs/site/MONOREPO.md

@@ -10,6 +10,7 @@ The [loopback-next](https://github.com/strongloop/loopback-next) repository uses
 | [authentication](packages/authentication)                   | @loopback/authentication         | A component for authentication support                                                                                                                                                                                                                                                           |
 | [boot](packages/boot)                                       | @loopback/boot                   | Convention based Bootstrapper and Booters                                                                                                                                                                                                                                                        |
 | [build](packages/build)                                     | @loopback/build                  | A set of common scripts and default configurations to build LoopBack 4 or other TypeScript modules                                                                                                                                                                                               |
+| [http-caching-proxy](packages/http-caching-proxy)           | @loopback/http-caching-proxy     | A caching HTTP proxy for integration tests. NOT SUITABLE FOR PRODUCTION USE!
 | [cli](packages/cli)                                         | @loopback/cli                    | CLI for LoopBack 4                                                                                                                                                                                                                                                                               |
 | [context](packages/context)                                 | @loopback/context                | Facilities to manage artifacts and their dependencies in your Node.js applications. The module exposes TypeScript/JavaScript APIs and decorators to register artifacts, declare dependencies, and resolve artifacts by keys. It also serves as an IoC container to support dependency injection. |
 | [core](packages/core)                                       | @loopback/core                   | Define and implement core constructs such as Application and Component                                                                                                                                                                                                                           |

packages/http-caching-proxy/.npmrc

@@ -0,0 +1 @@
+package-lock=false

packages/http-caching-proxy/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2017,2018. All Rights Reserved.
+Node module: @loopback/http-caching-proxy
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/http-caching-proxy/README.md

@@ -0,0 +1,101 @@
+# @loopback/http-caching-proxy
+
+A caching HTTP proxy for integration tests.
+
+**NOT SUITABLE FOR PRODUCTION USE!**
+
+## Overview
+
+Testing applications connecting to backend REST/SOAP services can be difficult:
+The backend service may be slow, apply rate limiting, etc. Integration tests
+become too slow in such case, which makes test-first development impractical.
+
+This can be addressed by setting up a snapshot-based mock server or using
+a caching HTTP client, but both of these solutions come with severe
+disadvantages:
+
+ - When using a snapshot-based mock server, we must ensure that snapshots
+   are up-to-date with the actual backend implementation.
+
+ - Caching at HTTP-client side requires non-trivial changes of the application
+   code.
+
+A filesystem-backed caching HTTP proxy offers a neat solution that combines
+caching and snapshots:
+
+ - The first request is forwarded to the actual backend and the response
+   is stored as a snapshot.
+ - Subsequent requests are served by the proxy using the cached snaphost.
+ - Snapshot older than a configured time are discarded and the first next
+   request will fetch the real response from the backend.
+
+## Installation
+
+```sh
+npm install --save-dev  @loopback/http-caching-proxy
+```
+
+## Basic use
+
+Import the module at the top of your test file.
+
+```ts
+import {HttpCachingProxy} from '@loopback/http-caching-proxy';
+```
+
+Create a proxy instance during test-suite setup
+(typically in Mocha's `before` hook):
+
+```ts
+const proxy = new HttpCachingProxy({
+  // directory where to store recorded snapshots - required
+  cachePath: path.resolve(__dirname, '.proxy-cache'),
+  // port where to listen - 0 by default
+  port: 0,
+  // how often to re-validate snapshots (in milliseconds) - one day by default
+  ttl: 24*60*60*1000,
+});
+await proxy.start();
+```
+
+In your tests, configure the client library to use the caching proxy.
+Below is an example configuration for
+[request](https://www.npmjs.com/package/request):
+
+```ts
+request = request.defaults({
+  proxy: proxy.url,
+  // Disable tunneling of HTTPS requests - this is required for HTTPS!
+  tunnel: false
+});
+```
+
+Finally, stop the proxy when the test suite is done
+(typically in Mocha's `after` hook):
+
+```ts
+await proxy.stop();
+```
+
+## API Documentation
+
+See the auto-generated documentation at
+[loopback.io](http://apidocs.loopback.io/@loopback%2fdocs/caching-proxy.html)
+
+## Contributions
+
+- [Guidelines](https://github.com/strongloop/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
+
+## Tests
+
+Run `npm test` from the root folder.
+
+## Contributors
+
+See
+[all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+
+## License
+
+MIT

packages/http-caching-proxy/docs.json

@@ -0,0 +1,7 @@
+{
+  "content": [
+    "index.ts",
+    "src/caching-proxy.ts"
+  ],
+  "codeSectionDepth": 4
+}

packages/http-caching-proxy/index.d.ts

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/http-caching-proxy
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './dist8';

packages/http-caching-proxy/index.js

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/http-caching-proxy
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+module.exports = require('@loopback/dist-util').loadDist(__dirname);

packages/http-caching-proxy/index.ts

@@ -0,0 +1,8 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/http-caching-proxy
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// DO NOT EDIT THIS FILE
+// Add any additional (re)exports to src/index.ts instead.
+export * from './src';

packages/http-caching-proxy/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@loopback/http-caching-proxy",
+  "version": "0.1.0",
+  "description": "A caching HTTP proxy for integration tests. NOT SUITABLE FOR PRODUCTION USE!",
+  "engines": {
+    "node": ">=8"
+  },
+  "scripts": {
+    "build": "npm run build:dist8 && npm run build:dist10",
+    "build:apidocs": "lb-apidocs",
+    "build:current": "lb-tsc",
+    "build:dist8": "lb-tsc es2017",
+    "build:dist10": "lb-tsc es2018",
+    "clean": "lb-clean loopback-caching-proxy*.tgz dist* package api-docs",
+    "pretest": "npm run build:current",
+    "test": "lb-mocha \"DIST/test/integration/**/*.js\"",
+    "verify": "npm pack && tar xf loopback-caching-proxy*.tgz && tree package && npm run clean"
+  },
+  "author": "IBM",
+  "copyright.owner": "IBM Corp.",
+  "license": "MIT",
+  "dependencies": {
+    "cacache": "^11.0.2",
+    "debug": "^3.1.0",
+    "p-event": "^1.3.0",
+    "request": "^2.87.0",
+    "request-promise-native": "^1.0.5",
+    "rimraf": "^2.6.2"
+  },
+  "devDependencies": {
+    "@loopback/build": "^0.6.5",
+    "@loopback/testlab": "^0.10.4",
+    "@types/debug": "^0.0.30",
+    "@types/delay": "^2.0.1",
+    "@types/node": "^10.1.1",
+    "@types/p-event": "^1.3.0",
+    "@types/request-promise-native": "^1.0.14",
+    "@types/rimraf": "^2.0.2",
+    "delay": "^3.0.0"
+  },
+  "keywords": [
+    "LoopBack",
+    "HTTP",
+    "Proxy",
+    "Cache",
+    "Test"
+  ],
+  "files": [
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "dist*/src",
+    "dist*/index*",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strongloop/loopback-next.git"
+  }
+}