🖧 local-traffic

That is a secure http/2 (or insecure http1.1) reverse-proxy installed on your machine

- with 0 transitive dependency
- with 1 install step
- with a startup time of a few milliseconds
- with one 40kb index.js file

How simple is that ?

pre-requisite

node.js >= 8

how to start in less than one minute

``bash
npx local-traffic
`

> sudo prefix only required for Linux, when port number < 1024

how to use it

1. Change the mapping object in the .local-traffic.json file:

`json
{
"mapping": {
"/npm/": "https://www.npmjs.com/",
"/my-static-webapp/": "file:///home/user/projects/my-static-webapp/",
"/my-non-existing-webapp/": "file:///home/user/random/404.html",
"/welcome/": "data:text/html,See my hobby project",
"/(see-this-example|yet-another-example)": "http://example.com/$$1",
"/config/": "config://",
"/logs/": "logs://",
"/recorder/": "recorder://",
"/jquery-local/jquery.js": {
"replaceBody": "https://ac.me/acme.js",
"downstreamUrl": "file:///home/user/projects/zepto/dist/zepto.js"
},
"/local-traffic-worker.js": "worker://",
"/proxified-api/": "https://some-cors-restricted-domain.com/some-restricted-api/",
"/cors-proxy\\?url=(.*)": "$$1",
"": "https://github.com/"
}
}
`

> if you need to deactivate a mapping entry, move it below the "" key

2. Go to http://localhost:8080/prettier with your browser
3. Go to http://localhost:8080/npm/ with your browser
4. Go to http://localhost:8080/my-static-webapp/index.html to test your webapp
5. Go to http://localhost:8080/my-non-existing-webapp/admin/permissions to test your 404 page (>= 0.1.1)
6. Go to http://localhost:8080/see-this-example or to http://localhost:8080/yet-another-example with your browser. Starting 0.0.89 and above, it supports regular expressions, and it is able to match them against the destination through string interpolation. Start with a double dollar sign ($$) followed by the index of the value in the match array
7. Go to http://localhost:8080/welcome/ with your browser (data urls work with version >= 0.0.95)
8. Go to http://localhost:8080/logs/ to watch the request logs
9. Go to http://localhost:8080/config/ to change the config in a web editor
10. You can use the http://localhost:8080/recorder/ to turn your proxy into a mock server. There is a user interface and also an API (documented here)
11. From the web config editor, create a SSL keypair and start working with a self signed SSL certificate right away
12. Your page will use /jquery-local/jquery.js instead of the CDN asset, and will serve the file from your hard drive
13. Use the /local-traffic-worker.js service worker to walk around the CORS restrictions when your api does a request to some-cors-restricted-domain.com (>= 0.1.4)
14. Use the /cors-proxy?url=https://example.com route as a standard cors-proxy (>= 0.1.29)

usage

$3

`bash
npx local-traffic [location-of-the-local-traffic-config-file]
`

> When not specified, the location of the config file will be $HOME/.local-traffic.json

$3

`bash
node -e 'require("local-traffic").start({ / configuration goes here / })'
`

$3

1. Add local-traffic to the dependencies
2. Use the notation require('local-traffic').start({ / configuration goes here / })'
3. Disable web security to benefit from cross origin adequate config (disableWebSecurity: true)
4. Downgrade downstream http to 1.1 only (dontUseHttp2Downstream: true)
5. Don't forget to use a CORS proxy server : use the crossOrigin.urlPattern parameter to specify it. Placeholders correspond to URL object properties.
("https://.com/?url=${href}")
6. If you want to use local domain names in addition to remote domain names, add them to the crossOrigin.whitelist

how to change mappings to local / non-local

1. Open .local-traffic.json while running it, or use the config web editor
2. Edit the mapping keys and downstream urls
3. See the status update in the terminal, that's it.

all the options

All boolean settings default to false when unspecified.

- mapping: ({[path: string]: string | {replaceBody: string ; downstreamUrl: string}) routing rules (required)
- ssl : SSL options (can be generated from the config web editor if you don't know how to set them)
- ssl.cert : (string) Certificate (PEM format)
- ssl.key : (string) Private Key (PEM format)
- port : (number) port number
- replaceRequestBodyUrls: (boolean) replace every matching string from the mapping in the request body.
- replaceResponseBodyUrls: (boolean) replace every matching string from the mapping in the response body.
- dontTranslateLocationHeader: (boolean) when getting a response location header, in case replaceResponseBodyUrls does not change the URL, change the origin to the proxy anyway
- dontUseHttp2Downstream: (boolean) force calling downstream services in http1.1 only (to save some time)
- simpleLogs: (boolean) disable colored logs for text terminals
- logAccessInTerminal: (boolean | 'with-mapping') write an access log in the terminal on each call (>= 0.1.2 : 'with-mapping' will log the key used to find the target)
- monitoringDisplay.active: (boolean) show a real-time terminal dashboard with request histograms, status codes, and response times (similar to btop/htop)
- websocket: (boolean) true to activate websocket connections proxying via sockets. Required for logs UI.
- disableWebSecurity: (boolean) true for easygoing values in cross origin requests or content security policy headers
- connectTimeout: (number) max time before aborting the connection (defaults to 3000ms)
- socketTimeout: (number) max time waiting for a response (defaults to 3000ms)
- unwantedHeaderNamesInMocks: (string[]) header names that won't get added to the mock request matchers
- crossOrigin.urlPattern: (string) change url to target a cors proxy (>= 0.1.29)
- crossOrigin.credentials: (string[]) domain names or regexes that can use credentials (>= 0.1.29)
- crossOrigin.whitelist (string[]) domain names or regexes that should not go through cors proxy (>= 0.1.29)
- crossOrigin.serverSide (boolean) activates the CORS proxy even while running as a server, to walk around webapp firewalls. Otherwise it will only work from a webcontainer (>= 0.1.29)

monitoringDisplay features (>= 0.2.0) :

monitoringDisplay. has the following feature toogles (booleans) :
* counter: total requests since last reset
* networkInterfaces: network interfaces involved in the requests
* requestRateHistogram: barchart of requests with a colored breakdown of each status family (1xx,2xx,3xx,4xx,5xx)
* topDomains: Top five downstream domains
* topMappings: top five used mapping keys
* statusCodes: status codes distribution
* protocols: protocol distribution
* httpMethods: http methods distributions
* topRoutes: top 5 routes
* responseTime: average response time + P50, P95 and P99

config API

(>= 0.1.1)
The configuration can be manipulated programmatically with an API.
It can be used if someone needs to automatically switch the routes or the options.
It can be used for canary deployment strategy (to switch between odd domain and even domain)

$3

Argument : the config itself

Updates the config, returns the new config once the update is complete

$3

Retrieves the current configuration.
use Accept: application/json to use the API mode.

`bash
$ curl https://localhost:8443/config/ -XGET -k -H'Accept: application/json'
{"mapping":{"/config/":"config://","":"https://github.com/"},"port":443,"replaceRequestBodyUrls":true,"replaceResponseBodyUrls":true}
`

recorder API

(>= 0.0.86)
The recorder can be used programmatically with an API.
This can be used if someone needs to automatically record mocks during instance provisioning
(when the machine boots up using a cloud provider for example)

The API always matches the route targetting recorder://.

$3

Arguments :
| parameter | Type | Description | Defaults|
| ------------- | ------------------------ | ---------------------------- | --------|
| mode | "proxy" or "mock" | server mode | "proxy" |
| strict | boolean | errors when no mock is found | false |
| autoRecord | boolean | adds mocks from server | false |
| mocks | {uniqueHash,response}[] | mocks definition | [] |

The recorder webapp can take care of the mocks by itself,
so autoRecord is only necessary when using local-traffic headless or without human
intervention

$3

The mock config will be reset to empty :
- autoRecord will be set to false
- mocks will be purged

$3

Retrieves the current mock configuration.
use Accept: application/json to use the API mode.

`bash
$ curl https://localhost:8443/recorder/ -XGET -k -H'Accept: application/json'
{"mocks":[],"strict":false,"autoRecord":false,"mode":"proxy"}
``