@fxtop/proxy

Nodejs Web Proxy Tool

@fxtop/proxy is a lightweight web proxy tool based on Nodejs. The primary purpose of @fxtop/proxy is to capture http(s) request and expose the lifecycle hooks in the process of proxy. so, the developers can do what he want in relevant hook.

For example, the developers can use it to implement a mock tool for team work. @fxtop/proxy expose the lifecycle hooks, before the request to after the response. developers can check request's hostname on before request hook, and mock data as a response if in needed. all lifecycle hooks supported we will talk later.

@fxtop/proxy is system level proxy, when you run the proxy server, you may need to do :

1. import the root cert into system trust list.
2. set your system's web proxy to the proxy server. e.g. 127.0.0.1:1080.

Directory

• document
  • install
  • examples
  • class
  • methods
  • static methods
  • lifecycle
• feature
• support
• license
• issues

document

installation

npm install @fxtop/proxy

examples

before proxy, we could invoke Proxy.trustRootCert to import Root Cert into system trust list and then, invoke Proxy.startSysProxy to set system's web proxy to assigned IP and Port. finally, we just need to start the proxy server to capture http(s) request.

const { Proxy } = require('@fxtop/proxy');

const httpPort = 1080;
const isProxyHttps = true;

// Proxy.trustRootCert();

const proxy = new Proxy(
  { httpPort, autoStart: true },
  {
    beforeRequest(req, res, options) {
      const { hostname, path, method } = options;

      // when return false, it just proxy transparently
      if (hostname !== 'www.baidu.com') return false;

      res.writeHead(200, { 'content-type': 'application/json' });

      res.end(/* Mock Data */);
      return true;
    },
  }
);

// start proxy
Proxy.startSysProxy(httpPort, isProxyHttps);

// close proxy after one minute
setTimeout(() => {
  Proxy.stopSysProxy().then(() => {
    proxy.close();
  });
}, 60 * 1000);

class

Proxy is all we need to control the proxy behavior. when call new Proxy, we need to pass two main params to config proxy's behavior, the options and the lifecycle. just like the example above.

Options:   base config of proxy.

name	type	default	description
httpPort	number	8888	http server listen port
httpsPort	number	8889	https server listen port
ca	object	-	the ca role, to generate certificate dynamically
autoStart	boolean	false	whether to start proxy immediately after call new Proxy

Lifecycle:   the lifecycle hooks for proxy process

name	type	return	description
beforeStart	Function	-	the hook before proxy start
afterStart	Function	-	the hook after proxy start
beforeConnect	Function	boolean	the hook before connect the https server, use for https proxy
beforeRequest	Function	boolean	the hook before proxy send the request to target server
afterRequest	Function	boolean	the hook after proxy send the request to target server
beforeResponse	Function	boolean	the hook before proxy send the response to target client
afterResponse	Function	-	the hook after proxy send the response to target client
beforeClose	Function	-	the hook before proxy close
afterClose	Function	-	the hook before proxy close

methods

proxy instance only provide 3 simple methods to control the proxy to start or close.

name	param1	param2	return	description
start	-	-	-	start proxy
reset	Options	Lifecycle	-	restart proxy by new configuration and lifecycle hooks
close	-	-	-	close proxy, it will close all unfinished sockets forcibly

static methods

class Proxy provide some static methods which can be used to invoke system capacity, e.g. import root cert into system trust list, and set system web proxy.

name	param1	param2	param2	return	description
createCA	InfoCA	-	-	Certificate	Create ca cert which use for https certificate auto-generate
createCert	domain	ca	validDays	Certificate	Create certificate manually and use specified ca sign for it
getDefaultCA	-	-	-	-	Get the default ca (FXTOP) the library provided
trustRootCert	path	-	-	-	Import root cert specified by path param into system trust list
startSysProxy	port	isProxyHttps	-	-	Set system's web proxy to localhost and listen to specified port
stopSysProxy	-	-	-	-	Disable system's web proxy

feature

@fxtop/proxy@0.1.5

• proxy http & https
• proxy lifecycle hooks
• node.js API provided
• system web proxy control
• import root certificate into system trust list
• https certificate auto-generate

@fxtop/proxy@0.1.6

• optimize the code, and remove @fxtop/winffi dependency
• change the way to set windows web proxy, much better compatible

support

• The current version is tested to run on node v8.0.0
• The static method is Only support Windows and MacOS system

license

Copyright (c) 2020 Louis (wechat: Faxin_Tan) Licensed under the MIT license.

issues