hiproxy

hiproxy is a lightweight web proxy tool based on Node.js. The primary purpose of hiproxy is to solve the problem of host management and reverse proxy needs of developers.

For example, if you are working as a team and each of the developers in the team need a different proxy setting, you will no longer need to modify your hosts file or use a web server like Nginx as a reverse proxy.

hiproxy extends the syntax of hosts file to support port numbers. Besides, hiproxy also supports configuration through a syntax similar to the Nginx configuration file.

中文版文档

Why Hiproxy?

If you are a front-end developer, it is not uncommon for you to encounter the following problems:

Debugging web pages locally: To develop your web projects in a local development environment, you’ll have to run a back-end server (such as a Node.js express application, or a Java SpringBoot application). As a front-end developer, you might not be familiar with the back-end technology stack, simply setting up the development environment can consume a lot of your time.

Cross-Origin Issues: While developing your front-end projects locally, you might need to solve cross-domain and cross-origin resource sharing issues. To address these problems, you will need to modify the response header.

Self-Signed Certificates: You’ll often need to test https pages. When you visit https pages with a self-signed certificate, your browser will raise security warnings.

One common way to modify the response header is to put a proxy as a “man in the middle”. NGINX, for example, has a nice syntax that you can configure as a reverse-proxy to handle all these needs.

Although NGINX is a great tool to address all the above problems, when setting up NGINX, you’ll also modify your hosts file a lot to proxy the requests to a local NGINX service. This can especially turn out to be a burden if you are working on multiple projects.

Can we have a better way to solve this problem?

Well, yes. Meet hiproxy!

Features

• Nginx.config-style configuration file syntax with a simple and intuitive configuration
• Extended hosts configuration with port numbers.
• Plugin extensions to rewrite directives, command line interface, and pages
• Automatic generation and management of TLS certificates
• Auto-detection of configuration file
• Proxy auto-configuration
• You can run hiproxy as a background service and redirect its output to a log file.
• You can open a browser window and configure your proxy from its web interface.
• hiproxy provides a Node.js API for fine-tuning and lower-level control.

Installation

npm install -g hiproxy

If you want to experience the latest features of hiproxy, you can install the next version.

npm install -g [email protected]

Usage

CLI

Start proxy server:

hiproxy start -p 5525 --debug --workspace ${PATH_TO_WORKSPACE}

Configure proxy:

127.0.0.1:5525

CLI Usage

> hiproxy --help

Usage:

    hiproxy [command] [option]

Commands:

  start    Start a local proxy server
  stop     Stop the local proxy server (Only works in daemon mode)
  restart  Restart the local proxy service (Only works in daemon mode)
  state    Show all the servers state (Only works in daemon mode)
  open     Open browser and set proxy
  hello    A test command that say hello to you.

Options:

  -v, --version     Display version information
  -h, --help        Display help information
  --log-dir <dir>   The log directory when run in background, default: user home directory
  --log-time        Show time info before every log message
  --log-level       The log levels, format: <level1>[,<lavel2[,...]]
  --grep <content>  Filter the log data

Documentation

• http://hiproxy.org/

Note: This is an incomplete documentation, we are still writing, if you are willing to help us write or translate the documentation, please contact [email protected]

Steps for Contributing Documentation

• The documentation repo is : https://github.com/hiproxy/documentation

• Choose one of the issues and submit a comment that tell others you will translate this part.

• Create your own fork on github.

• Translate the md files that you choose, you can reaplce the file content to the English version directly.

• Submit a PR.

After you have submitted your pull request, we'll try to get back to you as soon as possible. We may suggest some changes or improvements.  

Wiki

• https://github.com/hiproxy/hiproxy/wiki

Node.js API

var Server = require('hiproxy').Server;
var proxy = new Server(8848, 10086);

// events
proxy.on('request', function(req, res){
  req.someThing = 'some thing';
  console.log('new request =>', req.method, req.url);
});

proxy.on('data', function(data){
  console.log('on response =>', data.toString());
});

proxy.start().then(function (servers) {
  console.log('proxy server started at: 127.0.0.1:8848');
});

// stop proxy server
// proxy.stop();

// restart proxy server
// proxy.restart();

Hosts Configuration Example

hiproxy supports enhanced version of hosts, the hosts file supports not only IP but also port numbers.

# comment
127.0.0.1 example.com
127.0.0.1:8800 blog.example.com life.example.com

Rewrite Configuration Example

set $port 8899;
set $ip   127.0.0.1;
set $online 210.0.0.0;

domain example.com {
  location / {
    proxy_pass http://$online/;
  }

  location /blog/ {
    proxy_pass http://$ip:$port/blog/;

    proxy_set_header from 'hiproxy';

    set_header proxy 'hiproxy';
  }
}

Sample Project

Here is an example project that you can play with.

Running Tests

npm test

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Authors

• zdying - HTML/JavaScript/CSS/Node.js developer zdying
• zhouhailong - HTML/JavaScript/CSS/Node.js developer zhouhailong
• Alfred Sang (aka i5ting) - a full-stack developer and Node.js evangelist. He works for Alibaba Group as a Principal Front-End Developer and runs a self-media on the topic of Full-stack Node.js. His book “The Marvelous Node.js” (Part I) was published in July 2019.._

See also the list of contributors who participated in this project.

Built With

• hemsl - a lightweight Node.js command line argv parser and command executor.
• colors - get color and style in your node.js console.
• node-forge - JavaScript implementations of network transports, cryptography, ciphers, PKI, message digests, and various utilities.
• op-browser - Open browser window and set proxy.
• os-homedir - Node.js 4 os.homedir() ponyfill.
• url-pattern - easier than regex string matching patterns for urls and other strings. turn strings into data or data into strings.
• simple-mime - A simple mime database.

Thanks to the authors of the above libraries to provide such a useful library.

Thanks To

• v0lkan
• JayLee404
• Jeoxs
• James Fancy

Thanks to the above friends to help translate hiproxy documents.

Change Log

See the CHANGELOG.md for details.

License

This project is licensed under the MIT License - see the LICENSE file for details

Code of Conduct

We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

See the code of conduct for details.