Skip to content

Commit 7d8345c

Browse files
bajtosbajtos
committed
feat(http-caching-proxy): initial implementation
Implement an HTTP proxy with aggressive cache persisted on file system. This proxy is intended for integration tests to reduce the time needed to access real backends.
1 parent 5ae6c04 commit 7d8345c

File tree

16 files changed

+713
-0
lines changed

16 files changed

+713
-0
lines changed

‎CODEOWNERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
packages/authentication/* @bajtos @raymondfeng
1010
packages/boot/* @raymondfeng @virkt25
1111
packages/build/* @bajtos @raymondfeng
12+
packages/http-caching-proxy/* @bajtos
1213
packages/cli/* @raymondfeng @shimks
1314
packages/context/* @bajtos @raymondfeng
1415
packages/core/* @bajtos @raymondfeng

‎docs/apidocs.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ <h3>List of packages</h3>
1919
<ul>
2020
<li><a href="./authentication.html">@loopback/authentication</a></li>
2121
<li><a href="./boot.hml">@loopback/boot</a></li>
22+
<li><a href="./caching-proxy.html">@loopback/caching-proxy</a></li>
2223
<li><a href="./context.html">@loopback/context</a></li>
2324
<li><a href="./core.html">@loopback/core</a></li>
2425
<li><a href="./metadata.html">@loopback/metadata</a></li>

‎docs/site/MONOREPO.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ The [loopback-next](https://github.com/strongloop/loopback-next) repository uses
1010
| [authentication](packages/authentication) | @loopback/authentication | A component for authentication support |
1111
| [boot](packages/boot) | @loopback/boot | Convention based Bootstrapper and Booters |
1212
| [build](packages/build) | @loopback/build | A set of common scripts and default configurations to build LoopBack 4 or other TypeScript modules |
13+
| [http-caching-proxy](packages/http-caching-proxy) | @loopback/http-caching-proxy | A caching HTTP proxy for integration tests. NOT SUITABLE FOR PRODUCTION USE!
1314
| [cli](packages/cli) | @loopback/cli | CLI for LoopBack 4 |
1415
| [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. |
1516
| [core](packages/core) | @loopback/core | Define and implement core constructs such as Application and Component |

‎packages/http-caching-proxy/.npmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
package-lock=false

‎packages/http-caching-proxy/LICENSE‎

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

‎packages/http-caching-proxy/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# @loopback/http-caching-proxy
2+
3+
A caching HTTP proxy for integration tests.
4+
5+
**NOT SUITABLE FOR PRODUCTION USE!**
6+
7+
## Overview
8+
9+
Testing applications connecting to backend REST/SOAP services can be difficult:
10+
The backend service may be slow, apply rate limiting, etc. Integration tests
11+
become too slow in such case, which makes test-first development impractical.
12+
13+
This can be addressed by setting up a snapshot-based mock server or using
14+
a caching HTTP client, but both of these solutions come with severe
15+
disadvantages:
16+
17+
- When using a snapshot-based mock server, we must ensure that snapshots
18+
are up-to-date with the actual backend implementation.
19+
20+
- Caching at HTTP-client side requires non-trivial changes of the application
21+
code.
22+
23+
A filesystem-backed caching HTTP proxy offers a neat solution that combines
24+
caching and snapshots:
25+
26+
- The first request is forwarded to the actual backend and the response
27+
is stored as a snapshot.
28+
- Subsequent requests are served by the proxy using the cached snaphost.
29+
- Snapshot older than a configured time are discarded and the first next
30+
request will fetch the real response from the backend.
31+
32+
## Installation
33+
34+
```sh
35+
npm install --save-dev @loopback/http-caching-proxy
36+
```
37+
38+
## Basic use
39+
40+
Import the module at the top of your test file.
41+
42+
```ts
43+
import {HttpCachingProxy} from '@loopback/http-caching-proxy';
44+
```
45+
46+
Create a proxy instance during test-suite setup
47+
(typically in Mocha's `before` hook):
48+
49+
```ts
50+
const proxy = new HttpCachingProxy({
51+
// directory where to store recorded snapshots - required
52+
cachePath: path.resolve(__dirname, '.proxy-cache'),
53+
// port where to listen - 0 by default
54+
port: 0,
55+
// how often to re-validate snapshots (in milliseconds) - one day by default
56+
ttl: 24*60*60*1000,
57+
});
58+
await proxy.start();
59+
```
60+
61+
In your tests, configure the client library to use the caching proxy.
62+
Below is an example configuration for
63+
[request](https://www.npmjs.com/package/request):
64+
65+
```ts
66+
request = request.defaults({
67+
proxy: proxy.url,
68+
// Disable tunneling of HTTPS requests - this is required for HTTPS!
69+
tunnel: false
70+
});
71+
```
72+
73+
Finally, stop the proxy when the test suite is done
74+
(typically in Mocha's `after` hook):
75+
76+
```ts
77+
await proxy.stop();
78+
```
79+
80+
## API Documentation
81+
82+
See the auto-generated documentation at
83+
[loopback.io](http://apidocs.loopback.io/@loopback%2fdocs/caching-proxy.html)
84+
85+
## Contributions
86+
87+
- [Guidelines](https://github.com/strongloop/loopback-next/blob/master/docs/CONTRIBUTING.md)
88+
- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
89+
90+
## Tests
91+
92+
Run `npm test` from the root folder.
93+
94+
## Contributors
95+
96+
See
97+
[all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
98+
99+
## License
100+
101+
MIT

‎packages/http-caching-proxy/docs.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"content": [
3+
"index.ts",
4+
"src/caching-proxy.ts"
5+
],
6+
"codeSectionDepth": 4
7+
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
// Copyright IBM Corp. 2018. All Rights Reserved.
2+
// Node module: @loopback/http-caching-proxy
3+
// This file is licensed under the MIT License.
4+
// License text available at https://opensource.org/licenses/MIT
5+
6+
export * from './dist8';

‎packages/http-caching-proxy/index.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
// Copyright IBM Corp. 2018. All Rights Reserved.
2+
// Node module: @loopback/http-caching-proxy
3+
// This file is licensed under the MIT License.
4+
// License text available at https://opensource.org/licenses/MIT
5+
6+
module.exports = require('@loopback/dist-util').loadDist(__dirname);

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

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

0 commit comments

Comments
 (0)