hiproxyhiproxy
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 hiproxyIf you want to experience the latest features of hiproxy, you can install the next version.
npm install -g hiproxy@next
Usage
CLI
Start proxy server:
hiproxy start -p 5525 --debug --workspace ${PATH_TO_WORKSPACE}Configure proxy:
127.0.0.1:5525CLI 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 dataDocumentation
Note: This is an incomplete documentation, we are still writing, if you are willing to help us write or translate the documentation, please contact zdying@live.com
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
mdfiles 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
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.comRewrite 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 testContributing
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
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.
