ProxyOK

This module creates a basic proxy server which replies with 200 OK Status code to all the http requests.

Install

npm i proxyok

How to use

It is possible to:

1. let ProxyOK to create the HTTP local server for you (you can specify the port on localhost to listen for)
2. using proxyok.onRequest method as middleware for http server created by you

In both cases, you can:

• set a predefined remote domain to forward the all the requests
• keep the proxy "generic" and forward requests depending on the url parameter.

1) Let ProxyOK to create the HTTP local server for you

In this way the module auto-creates the server at http://localhost:9000/ and every request will be forwarded to https://npmjs.com/*:

STATIC ENDPOINT EXAMPLE

var http = require('http');
var proxyok = require("proxyok");
proxyok({
    port: 9000,
    endpoint: {
        //protocol: 'https:', // default is https:
        hostname: 'npmjs.com',
        port: 443
    }
});

Example: $ node ./examples/with-server/generic-per-request/proxy-per-request.js then type in your browsers address bar: http://localhost:9000/package/proxyok

2) Create your own server and use ProxyOK as middleware

You have to set autostart option as boolean false value. In this way you can use your own HTTP server with proxyok.onRequest method for handle the requests:

GENERIC REQUEST EXAMPLE

const http = require('http'),
    proxyok = require("proxyok")({
        autostart: false,
        endpoint: {
            //protocol: 'https:', // default is https:
            hostname: 'npmjs.com',
            port: 443
        }
    }),
    server_port = process.env.PORT || 8082,
    server = http.createServer(proxyok.onRequest);

server.listen(server_port, (err) => {
    if (err) {
        throw err;
    } else {
        console.log('Server listening on port ' + server_port);
    }
}).on('error', console.error);

Example: $ node ./examples/as-middleware/localhost_8082_generic-request.js then type in your browsers address bar: http://localhost:8082?url=https://npmjs.ord/package/proxyok

a. Define a remote domain

a.1 - With environment variables file - with server autostart

In this case .env file has been placed in the app root directory.

NODE_TLS_REJECT_UNAUTHORIZED=0

PROXYOK_PORT=8080
PROXYOK_ENDPOINT_PROTOCOL=https:
PROXYOK_ENDPOINT_HOSTNAME=remotedomain.example.com
PROXYOK_ENDPOINT_PORT=443

const proxyok = require('proxyok')
proxyok({
    envpath: __dirname + '/.env' // it could be any valid file path
});

a.2 - With environment variables file - through external HTTP server

In this case .env file has been placed in the app root directory.

NODE_TLS_REJECT_UNAUTHORIZED=0
PORT=8080

PROXY_OK_AUTOSTART=false
PROXYOK_ENDPOINT_PROTOCOL=https:
PROXYOK_ENDPOINT_HOSTNAME=remotedomain.example.com
PROXYOK_ENDPOINT_PORT=443

const http = require('http')
    , proxyok = require('proxyok')({
        envpath: __dirname + '/.env' // it could be any valid file path
    })
    , server_port = process.env.PORT || 8080,
    , server = http.createServer(proxyok.onRequest)

server.listen(server_port, (err) => {
    if (err) {
        throw err;
    } else {
        console.log('Server listening on port ' + server_port);
    }
}).on('error', console.error);

The proxy server will listen at http://localhost:8080 and all the requests will be forwarded to https://remotedomain.example.com. Example: http://localhost:8080/webpage.html will retrieve the resource from https://remotedomain.example.com/webpage.html with status code 200 OK.

a.3 - Providing options - with server autostart

const proxyok = require('proxyok');
proxyok({
	port: 9000,
	endpoint: {
		//protocol: 'https:', // default is https:
		hostname: 'remotedomain.example.com',
		port: 443
	}
});

a.4 - Providing options - through external HTTP server

const const http = require('http')
    , proxyok = require('proxyok')({
        autostart: false,
        endpoint: {
            //protocol: 'https:', // default is https:
            hostname: 'remotedomain.example.com',
            port: 443
        }
    })
    , server_port = process.env.PORT || 9000
    , server = http.createServer(proxyok.onRequest);

server.listen(server_port, (err) => {
    if (err) {
        throw err;
    } else {
        console.log('Server listening on port ' + server_port);
    }
}).on('error', console.error);

The proxy server will listen at http://localhost:9000 and all the requests will be forwarded to https://remotedomain.example.com. Example: http://localhost:8080/webpage.html will retrieve the resource from https://remotedomain.example.com/webpage.html with status code 200 OK.

b - Generic remote host

b.1 - Via url parameter - with server autostart

const proxyok = request('proxyok');
proxyok({
	port: 8082,
	generic: true
});

b.2- Via url parameter - through external HTTP server

const http = require('http')
    , proxyok = require('proxyok')({
        autostart: false,
	    generic: true
    })
    , server_port = process.env.PORT || 8082
    , server = http.createServer(proxyok.onRequest);

server.listen(server_port, (err) => {
    if (err) {
        throw err;
    } else {
        console.log('Server listening on port ' + server_port);
    }
}).on('error', console.error);

The proxy server will listen at http://localhost:8082?url=[...]. All the requests will be forwarded to the specified url parameter. Example: http://localhost:8082?url=https://remotedomain.example.com/urlwebpage.html will retrieve the resource from https://remotedomain.example.com/webpage.html with status code 200 OK.

Valid javascript options

var options = {
    envpath, // {string} Path of the evnironment variables
    autostart, // {bool} If true, the proxy will automatically create an HTTP server that listens for requests. Default is true (for backward compatibility).
    port, // {int} Port the server will listen for at localhost
    generic, // {bool} If true, the proxy will act as hostname agnostic
    auth: {
        check, // {bool} If true, the proxy will match the provided auth with the ones coming from request's "Authorization" header
        override, // {bool} If true, the app will build auth token (with given token or by username, password and type) and provides it to the proxied request as "Authorization" header
        type, // {string} If provided: basic, bearer
        username,
        password,
        token, // {string} If provided, it will be used as double-check or for authorizaion header overriding
    },
    endpoint: {
        protocol,
        username,
        password,
        hostname,
        port
    }
}

Valid environment variables

Place your own values after = symbols and/or remove unused ones.

PROXYOK_AUTOSTART=[false|true|0|1]
PROXYOK_PORT=8080
PROXYOK_AUTH_USERNAME=headerAuthUser
PROXYOK_AUTH_PASSWORD=headerAuthPassword
PROXYOK_AUTH_TYPE=basic
PROXYOK_AUTH_CHECK=true
PROXYOK_AUTH_OVERRIDE=false
PROXYOK_AUTH_TOKEN=PlaceYourBasicAuthorizationTokenHere
PROXYOK_ENDPOINT_PROTOCOL=https:
PROXYOK_ENDPOINT_USERNAME=endpointInlineUsername
PROXYOK_ENDPOINT_PASSWORD=endpointInlinePassword
PROXYOK_ENDPOINT_HOSTNAME=example.remotedomain.com
PROXYOK_ENDPOINT_PORT=443

With the above process.env[...] variables:

• The proxy server listens at http://localhost:8080
• All the requests (when properly authorized - see next points) will be forwarded to https://endpointInlineUsername:[email protected]:443
• It forwards Authorization header like: Authorization: Basic PlaceYourBasicAuthorizationTokenHere
• The client must provide Authorization header and there must be an exact match with the one set with this .env file. Otherwise the request will not be proxied.
• PROXYOK_AUTH_USERNAME, PROXYOK_AUTH_PASSWORD, PROXYOK_AUTH_TYPE can be omitted (since they will be ignored) when providing PROXYOK_AUTH_TOKEN

Notes:

• When setting PROXYOK_AUTH_OVERRIDE=true the Authorization header will be built using PROXY_AUTH_TYPE and PROXY_AUTH_TOKEN or PROXY_AUTH_TYPE, PROXY_AUTH_USERNAME and PROXY_AUTH_PASSWORD if properly provided.
• See ./examples folder for more examples