@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/[email protected]

• 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/[email protected]

• 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