json-proxy-middleware - npm Package Compare versions

Comparing version 0.0.0 to 0.0.1

package.json

 {
   "name": "json-proxy-middleware",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Simple express.js friendly json proxy middleware utility",
-  "main": "index.js",
+  "main": "dist/index.js",
   "scripts": {
+    "build": "gulp",
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -30,3 +31,18 @@ },
     "request": "^2.87.0"
+  },
+  "devDependencies": {
+    "@types/bunyan": "1.8.4",
+    "@types/express": "4.16.0",
+    "@types/lodash": "4.14.111",
+    "@types/node": "10.5.2",
+    "@types/request": "2.47.1",
+    "@types/verror": "1.10.3",
+    "bunyan": "1.8.12",
+    "gulp": "3.9.1",
+    "gulp-typescript": "5.0.0-alpha.3",
+    "tslint": "5.10.0",
+    "tslint-eslint-rules": "5.3.1",
+    "typescript": "2.9.2",
+    "verror": "1.10.0"
   }
 }

README.md

 # json-proxy-middleware
 
-todo: make it
+This is a simple middleware utility that can be used to proxy JSON requests
+for Express node.js servers. This is most useful when you want to simply
+pass a response from a service to a client, without needing to buffer or
+modify it. For example, your server could do an authentication check, and
+then simply stream the data from the service to the client.
+
+### Quick Start
+
+Assuming you have an express Router, here's a quick way to get things wired up:
+
+```js
+import express from "express";
+import jsonProxy from "json-proxy-middleware";
+
+const router = new express.Router();
+
+router.get(
+  "/service/proxy/path",
+  (req, res, next) => {
+    if (req.user.isLoggedIn) {
+      next();
+    }
+  },
+  jsonProxy({
+    urlHost: "https://my.service.url",
+    headers: {
+      "x-custom-header-calling-application-name": "my-application"
+    }
+  }),
+  (error, req, res, next) => {
+    res.status(500).json({
+      message: "Whoops! The Proxy Middleware Broke!"
+    });
+  }
+);
+
+export default router;
+```
+
+In the example above, let's break down what happened in our router:
+
+1.  We have some middleware that first checked if a user was loggedIn, assuming
+    they are with whatever auth your app is using, we let them through.
+1.  We created a `jsonProxy` middleware `RequestHandler`, and pointed it to
+    `https://my.service.url`, and attached some custom HTTP headers for the
+    service.
+1.  We also provided an error handler, which we can use to inform our clients
+    of the error how our application best sees fit. This is _different_ from the
+    service responding with an error, in which case that would have just been
+    proxied through as well.
+
+### API
+
+`json-proxy-middleware` is designed to be fairly flexible, yet performant for
+configuring how & where you proxy requests through your node.js middletier.
+The quick start above includes the barebones to get you up and running. Below
+is the full API with some details on how to use the middleware in a variety
+of different scenarios.
+
+There is a single, default export from the utility, and that is the middleware
+itself:
+
+```js
+import jsonProxy from "json-proxy-middleware";
+```
+
+It takes a single `ProxyMiddlewareOptions` object, and returns a `RequestHandler`
+function:
+
+```js
+jsonProxy({
+  additionalLogMessage: "custom appended log message",
+  headers: {
+    "custom-additional-http-header": "value"
+  }
+  logger: console,
+  urlHost: "https://my.service.uri",
+});
+```
+
+| property               | type                           | description                                                                                            |
+| ---------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `additionalLogMessage` | `string` (optional)            | a message that will be appended to proxy start/end/error logging                                       |
+| `headers(req, res)`    | `object`/`function` (optional) | an object or function that returns an object with additional headers to forward on the proxied request |
+| `logger`               | logger instance (optional)     | any valid logger instance with methods `.info()` and `.error()` to be called with logging messages     |
+| `urlHost(req, res)`    | `string`/`function`            | a string or function that returns a string indicating a host to have a request proxied to              |
+
+### `additionalLogMessage`
+
+When a logger is provided, this message will be appended to to info/error logs and
+can be used to customize the log messages per jsonProxy usage as needed.
+
+### `headers`
+
+When provided, these will be appended to the default headers that we forward. By
+default we provide the headers necessary for JSON requests:
+
+```js
+{
+  Accept: "application/json",
+  "Content-Type": "application/json"
+}
+```
+
+If you'd like, you can provide an object with static headers to forward, like so:
+
+```js
+jsonProxy({
+  headers: { "custom-http-header": "static value" }
+});
+```
+
+In some cases, you need to also forward request headers that came in from the client,
+or you might need to forward headers based on the request itself. In that case,
+you can provide a function that the middleware will call for each incoming proxy
+request:
+
+```js
+jsonProxy({
+  headers(req, res) {
+    return {
+      userId: req.user.getId(),
+      session: req.sessionId
+      // etc
+    };
+  }
+});
+```
+
+Setting headers this way allows you to perform a white or black list style header
+forwarding for the proxy as well.
+
+### `logger`
+
+When a logger is provided, `json-proxy-middleware` will log out information useful
+for debugging, such as when a proxy request started, when it ended, and how long it
+took. We also log out errors in the event those occur. You can provide any kind of
+logger you prefer, as long as it has a `.info()` and `.error()` log level method to
+invoke.
+
+### `urlHost`
+
+The `urlHost` is combined with the path on the proxy to perform a request. It is
+required, and you can provide either a `string` or `function` that returns a string
+for the request. The simplest example looks like this:
+
+```js
+router.get(
+  "/service/REST/v1",
+  jsonProxy({ urlHost: "https://my.service.url" })
+);
+```
+
+This will result in `jsonProxy` making a `GET` request to:
+
+```
+https://my.service.url/service/REST/v1
+```
+
+Because of the way Express are designed with their routing, you can also
+leverage this with regex / glob paths, like so:
+
+```js
+router.get(
+  "/service/REST/v1/**",
+  jsonProxy({ urlHost: "https://my.service.url" })
+);
+```
+
+This will mean that `json-proxy-middleware` will proxy **any** paths that match.
+It's a **great** idea to understand if this will open up security holes in your
+service, and in general proxying requests through globs requires some thought &
+coordination with the proxied service.
+
+Another thing to note with Express servers, is that you can mount routes at
+different base paths. `json-proxy-middleware` by default navigates this for you,
+so keep that in mind when using proxy routers in scenarios like this:
+
+```js
+import express from "express";
+
+const server = express();
+const router = express.Router();
+
+router.get(
+  "/service/REST/v1/**",
+  jsonProxy({ urlHost: "https://my.service.url" })
+);
+
+server.use("/proxy", router);
+```
+
+In this case, your clients will be making requests to `/proxy/service/REST/v1/**`,
+but `json-proxy-middleware` will be proxying requests to
+`https://my.service.url/service/REST/v1/**`, removing the `/api` portion from the
+request.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

19568

increased by328.47%

Number of package files

8

increased by166.67%

Lines of code

370

increased by200.81%

Number of lines in readme file

199

increased by4875%

Worsened metrics

Dev dependency count

13

increased byInfinity%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes