| Param | Type | Description |
+| — | — | — |
+| options | Object | options |
+| options.httpPort | Number | The HTTP proxy service port. If 0/null/undefined is passed, an available port number will be automatically assigned. |
+| options.httpsPort | Number | HTTPS proxy service port number. If 0 is passed, an available port will be automatically assigned. If pass null or undefined, the HTTPS service will not be started. |
+| [options.dir] | String | The hiproxy workspace defaults to the current working directory of the Node.js process(process.cwd()) |
+
+
proxyServer.start([config]) ⇒ Promise
Start proxy server.
+
Kind: instance method of ProxyServer Access: public
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
If you place the configuration file (include the its name) by following hiproxy concept, while hiproxy starts, it can automatically find the file without specifying the configuration file manually.
+
Otherwise, you have to specify the configuration file while hiproxy starts. In the case, you may place the configuration file anywhere, which can be named anything. (Omitted hosts file name is hosts, and rewrite file name is rewrite).
+
Specifiy configuration file
You can use some options to specify the name of configuration file. They are -c, --hosts-file <files> or -r, --rewrite-file <files>.
+
-c, --hosts-file <files> is used to specify the path of hosts file. , can be used to separate more than one files.
+
-r, --rewrite-file <files> is used to specify the path of rewrite file. , can be used to separate more than one files.
+
<files> supports simple wildchar mode to speify more files. For example, --rewrite-file ./*/*.conf.
+
+
Note
+
If you specified a configuration file, hiproxy would look for specified file to instead of looking for omitted hosts ro rewrite. For example:
+ If `-c .//hosts.confis specified, hiproxy would ignore the file namedhosts.
+* If-r ./*/rewrite.confis specified, hiproxy would ignore the file namedrewrite`.
+
+
Wildchars in configuraton files
Suporting wildchars:
+
wildchars | description | example | mached | unmached
+———|———-|———|———-|———
+ * | Match one or more characters. | ./test-*.js | ./test-hello.js | ./test-.js
+ ? | Match only one character. | ./test?.js | ./testA.js | ./testAB.js
+ [abc] | Matches a single character that is contained within the brackets. | ./test[ABC].js | ./testA.js | ./testD.js
+ [^abc] | Matches a single character that is not contained within the brackets. | ./test[^ABC].js | ./testD.js | ./testA.js
+ [!abc] | Same as [^abc] | ./test[!ABC].js | ./testD.js | ./testA.js
+
+
Note
+
Do not support use ** to look for files in any hierarchy.
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
Introduction
Hosts can be thought as enhanced hosts of OS, Its most important feature is port forwarding.
+
Note: hiproxy support both hosts file and rewrite file. hosts is a simple solution so that it supports only forwarding domain & port. If you want custom complex forwarding rules, see rewrite as referrence.
+
Working mechanism
Hiproxy will parse hosts files in the projects’ immediate directories while it starts. The proxy server would forward received requests according to rules in hosts files.
+
Features
+
Port forwarding;
+
hosts file of project is used to instead of OS one and avoid system cache issue;
+
You do NOT need to restart hiproxy after modifying hosts file. Hiproxy can restart and refresh hosts rules automatically.
+
+
Syntax
The syntax of project hosts is very similar as OS one. Supporting IP+port is the only difference. The syntax is:
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
Type of configuration file
Hiproxy can use hosts to make simple request proxy. And rewrite can be used for complex configuration rules which use similar syntax of Nginx.
+
hosts
It has same syntax as hosts of OS. As additinal, it supports configurating port number. You can only configure host with corresponding IP and port in hosts. It does not support detailed routing and modification to request/response. Read hosts for more.
+
Example for hosts
1 2 3 4 5
# comment 127.0.0.1 example.com
# ip + port 127.0.0.1:8800 blog.example.com life.example.com
+
rewrite
You can make complex configuration in rewrite in some complex situation. That includes detailed routing, and modification to request/response. The syntax of rewirte configuration is very similar to that of Nginx. Read rewrite for more.
+
Example for rewrite
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
# global variables set$port 8899; set$ip 127.0.0.1; set$online 210.0.0.0;
hiproxy recommends you place configuration files in the particular project root directory (hosts file named hosts and rewrite file named rewrite). Projects are placed in workspace so that the hierarchy structure is line below:
The benifit is that these configuration files can be commit to code repository for sharing with team members, and cost saving. Furthermore, hiproxy can find the files by itself.
+
Finding configuration files
If you follow the rules above to place the files (with their special names), and hiproxy use workspace directory as workspace, it can find the configuration files of the three projects without spcifying by manual.
+
If you do NOT follow the rules, place the files to different directory or not use default names (hosts for hosts file and rewrite for rewrite file), you have to specify the files while hiproxy starts.
General proxy method is default one. You can use --pac-proxy for swithing to PAC while starting.
+
The Deifferent proxy methods deal updating configuration file in different way.
+
If it’s running in general proxy mode and the configuration file was updated. You can just refresh the browsing page to make it valid.
+
But if it’s running in PAC proxy mode, and one or more new domain ware added. You should refresh the browser’s proxy file by manual since the .pac file is not updated immediately. If you want detail, you can visit chrome://net-internals/#proxy then click Re-apply settings.
+
Merge proxy rules
The rules in all configuration files should be merged into a bit rules tree. That is, after configuring the proxy, all the rules in the configuration files are equal at the time the request is processing. The rules in different domain would not affect each other. The rules in the same domain should be merged and later rule should overwrite previous one if they are same route.
+
For example, there are two configuration files, workspace/blog/rewrite and workspace/docs/rewrite. Their content are below:
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
Hiproxy can generate its own root certificate. You can think it as a CA (Hiproxy Custom CA). If a https request need hiproxy to forward, hiproxy would use its own root certificate to generate automatically a secure certification of that https request.
+
Hiproxy own root certificate is not trusted by OS, therefore, you have to install the root certificate by manual to let OS know it as trusted one.
+
Download The Certificate
As soon as hiproxy is started (suppose the port number is 5525), you can go http://127.0.0.1:5525/ssl-certificate to get the root certificate of Hiproxy Custom CA.
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
Introduction
CLI of hiproxy supplied commands such as start, stop, state and open. If then are not enought, you can add your own ones.
+
You should define something, such as command name, description, handler and options, for the new command. This is description:
+
+
Command Name（command）：<String>, i.e. 'hello'。
+
Description（describe）：<String>, summary about the command’s usage or more, i.e. 'A test command that say hello to you.'。
+
Usage（usage）：<String>, command usage, i.e. 'hello [--name <name>] [-xodD]'。
+
Handler（fn）：<Function>, the command invokes the handler while it’s executing. this of the handler refer to a object which describes command line arguments.
{ command: 'hello', describe: 'A test command that say hello to you.', usage: 'hello [--name <name>] [-xodD]', fn: function () { var cliArgs = this; if (cliArgs.name ) { console.log('your name is', cliArgs.name.green); }
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
Introduction
rewrite directive can configure directive name, scopes and handler. They are:
+
+
Directive Name（name）：<String>, i.e. 'add'。
+
Scopes（scope）：<Array>, the scopes which the directive runs in. The directive is only valid in specified scopes. The scopes include global, domain, location, request and response.
+
Handler（fn）：<Function>, the handler should be invoked while the directive is execute. See handler for details.
+
+
Example
Here is a entire example of directive:
+
1 2 3 4 5 6 7 8 9 10
{ name: 'add', scope: ['global', 'domain', 'location'], fn: function (key, a, b) { var props = this.props; var value = Number(a) + Number(b);
this.props[key] = value; } }
+
+
Handler
The handler is invoked while hiproxy is executing related directive. The parameters whick are specified for the directive in rewrite configuration are passed in and this should be setted.
+
Parameters
The parameters for the directive in rewrite configuration should be passed into handler. For example, proxy_set_header Host hiproxy.org is configured then ('Host', 'hiproxy.org') should be passed into the handler.
+
this
this value is depended on the scope which the directive executs in. Following are possible this values:
Hiproxy supplied a mechanism of developing plugins. It’s simple that you need just develop a plugin and install it to global. Hiproxy should look for and load all plugins while it starts.
+
If you want to develop a plugin, hiproxy-plugin-example is a good demo which you can find at https://github.com/hiproxy/hiproxy-plugin-example. This is a entire plugin demo, you can start your own pluign base on the demo.
+
A plugin is a common npm module. You do not need to install hiproxy as a dependency.
+
+
Plugin’s architecture
Three condition should be satisfied before a module becomes a hiproxy pluign:
+
+
It must be a standalone npm module which export only one object with three properties
commands: <Array>, extends hiproxyCLI. Each element in the array should be a command configuration. See Command Configuration for details.
+
+
directives: <Array>, extends rewrite directive of hiproxy. Each element in the array should be a directive configuration. See Rewrite Directive for details.
+
+
routes: <Array>, extends page router of hiproxy. Each element in the array should be a route configuration.See Page Route Configuration for details.
You can publish a plugin into npm while it’s completed with development and testing.
+
The publish process is the same as publishing other npm module, since the a plugin of hiproxy is jsut a common npm module which follows given rules.
+
Hint
Hiproxy look for plugins which has hiproxy-plugiin- as prefix and installed in the directory described by npm root -g, so that hiproxy cannot find new developing pluigns.
+
npm link can create a symbol link of a plugin so that you can debug it while it’s in development. See npm link of npm document for details.
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
Introduction
You can visit http://127.0.0.1:<port>/ to watch basic informations of the service after it finished starting.
+
Except that page, hiproxy support a feature for adding new page. For example, plugin hiproxy-plugin-dashboard add a page to hiproxy for showing service information and modifying configuration files, which is at http://127.0.0.1:<port>/dashboard/.
+
Configuration Content
Page route configuration include: route rules and renderer. Then are:
Renderer（render）：<Function>, for rendering a page. It accept three parameters: (route, request, response).
+
+
Renderer, render() Method
render() method should be invokded with three parameters, (route, request, response), while user visit the corresponding page.
+
+
route: <Object>, arguments object from route pattern. For example, /test(/:pageName) pattern cause the object {pageName: 'home'} while /test/home is visiting.
{ route: '/test(/:pageName)', render: function (route, request, response) { // global variable `hiproxyServer` can be used to get hiproxy server instance. response.writeHead(200, { 'Content-Type': 'text/html', 'Powder-By': 'hiproxy-plugin-example' });
The core feature of hiproxy is forwarding request. Hiproxy purposes to solve some problems which front-end developer can meet while working:
+
+
hosts cannot work immediately since there are caches after it’s updated.
+
Nginx is used for reverse proxy.
+
Self signed HTTPS certificate are not trusted.
+
Everyone maintans the environment profile (hosts/nginx configuration).
+
…
+
+
+
What’s the difference between hiproxy and Charles／Fiddler?
They all have the ability to capture packages, proxy request and many core function. But hiproxy is a CLI tool which works with configuration files.
+
However, hiproxy has no interface to see the specific content of request. That will be introduced as a plugin in the future.
+
+
What’s the relationship between hosts for hiproxy and for OS？
They are no relationship actually.
+
the hosts file for hiproxy is normally placed in project directory, or other (user specified) directory. Hiproxy would looking for, load and parse the hosts file in project directories, but not do with OS one.
+
+
Is the rewrite configuration file for hiproxy fully compatible with Nginx configuration?
No. They are no relationship actually.
+
The rewrite configuration for rewrite has similar syntax of Nginx configuration. The core syntax is consistent with the syntax of Nginx, but there are also some syntax are specific to hiproxy. They are not exactly consistent with Nginx syntax. For example:
+
1 2 3 4 5 6 7
# base rule http://hiproxy.org/api/login.do => http://127.0.0.1:9999/api/login.json;
# domain hiproxy.org => { # ... }
+
In addition, some directives come from Nginx which do simular things, such as proxy_pass, set, ssl_certificate and ssl_certificate_key, etc. In any case they cannot promise that all details are same as Nginx directives.Please see Directive for more information.
+
+
Does hiproxy support that the same domain name is used in the configuration files of multi-projects?
It’s supported.
+
You can set rules for the same domain name in configuration files of different projects. Hiproxy can merge all rules about the same domains. If there is conflict, later loaded rules would rewrite earlier rules.
+
+
How does hiproxy handle the conflict between multiple configuraton files?
By default, when the https request is forwading, hiproxy will generate the certifiate automatically and use customized CA certificate signature. The users should import root certificate of hiproxy.
+
If you use customized certificate, ou can use some hiproxy directive for configurating:
All you have to do is to global install hiproxy, Local install is NOT necessary
+
2. Add configuration files
Two rules of ‘hiproxy’:
+
+
All projects in one Workspace;
+
Put configuration files (hosts / rewrite) into specific project directory, submit them to the repository for version control and teamwork.
+
+
Therefore, all configuration files should be located in specific project directory. In terms of different projects, diverse configuration files can be added. While the ‘hiproxy’ on starting, those files will be found from workspace.
hosts is similar to hosts, except it’s located in the project directory, hiproxy will automatically find and resolve the hosts file named ‘hosts’ from the root directory of the project.
+
If the file name isn’t hosts, just specify it via option -c, --hosts-file.
rewrite is similar to hosts, it’s also located in the project directory, hiproxy will automatically find and resolve the file named ‘rewrite’ from the root directory of the project.
+
If the file name isn’t rewrite, just specify it via option -r, --rewrite-file.
Git commitment is highly recommended, submit configuration files (hosts/rewrite) to the repository for version control and teamwork.
+
4. Start service
The concept of hiproxy is based on Workspace. The proxy service of hiproxy should be started in the workspace. Assuming that all projects are located in ~/workspace/, then this directory is the Workspace.
+
Enter this directory, start the proxy service, then hiproxy will find all the configuration files of all projects.
+
If service is needed before entering the workspace, just start proxy using the option -w, --workspace <workspace> in any directories.
+
1 2
# Enter any directories hiproxy start -w ~/workspace/
+
TIPS: While on starting the proxy, use the option -o, --open [browser-name] to open a new browser window and configure the proxy automatically. Therefore, no manual configuring is needed.
+
5. Development debugging
When the proxy is started, if the proxy rules are configured, all requests from the browser window will be handled by hiproxy.
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 testcommand 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
+
start
This command will start a local proxy service on the specified port. You can specify whether the service is running in the background, if running in the background, all the log of the service will be redirect to the log files.
+
The log file is located in the user’s home directory by default. Of course, you can specify the log file’s path via the option --log-dir <dir>.
-h, --help show help info -D, --daemon Run hiproxy in background -c, --hosts-file <files> hosts files, format: <file1>[,<file2>[,...]] -s, --https Enable HTTPS proxy -m, --middle-man-port <port> The Man-In-The-MiddleHTTPS proxy port, default: 10010 -o, --open [browser] Open a browser window and use hiproxy proxy --pac-proxy Use Proxy auto-configuration (PAC) -p, --port <port> HTTP proxy port, default: 5525 -r, --rewrite-file <files> rewrite config files, format: <file1>[,<file2>[,...]] --sys-proxy <path> Your own proxy server path, format: <ip>[:port], only works when use PAC -w, --workspace <dir> The workspace
+
stop
If the proxy service is running in the background, hiproxy provides a stop command to stop the service
+
1
> hiproxy stop
+
open
The open command can open a browser window and automatically set up the browser’s proxy info based on the currently started proxy service.
+
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
> hiproxy open --help
USAGE:
open [options]
DESCRIBE:
Open browser and set proxy
OPTIONS:
-h, --help show help info -b, --browser <browser> Browser name, default: chrome. Valid alues: chrome,firefox,opera --pac-proxy Use Proxy auto-configuration (PAC)
+
state
This command will display the basic status information of the currently started proxy service.
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
hiproxy is a lightweight, extendable network proxy based on Node.js, the main purpose is to resolve the hosts management and proxy request problem that multiple developers encountered in development. And there is no need to modify system hosts and start Nginx service.
+
hiproxy supports hosts file, and the syntax is extended for hosts, it now supports port number. Besides, hiproxy supports configuration file using syntax similar to that for Nginx.
+
Why hiproxy
In front-end development, if developers usually encounter some of the following problems:
+
+
While debugging online page issues, if both local development and back-end running ability for projects (Node.js/Java project) are required, it may costs a lot for a front-end developer to build a back-end environment locally.
+
If multiple front-end projects exist, with one domain, some projects need to request online resources, other projects request local resources.
+
In order to resolve the cross-domain problems, local development needs to modify Response Header.
+
While developing https site locally, certificate is not trusted.
+
With system hosts changed，it won’t take effect immediately.
+
+
We can use Nginx to resolve the problems above. Nginx is excellent and also a very good friend of our front-end developer. The configuration file style of Nginx is very intuitive, and the configuration efficiency is high.
+
However, when using Nginx, we also need to use hosts to send the related requests to the local Nginx service.
+
In addition, in most cases, the Nginx configuration file will not be submitted to the repository, so other members of the team will copy each others’ configuration file, therefore the efficiency is relatively low, and once a configuration file has been modified, other configuration files will not be updated in time. For the configuration of multiple domains, they are placed in a unified directory, and then being included in the main configuration, which is also inconvenient.
+
hosts, revers proxy, https and cache Will these trivial things be solved in a unified way?
+
So there is hiproxy.
+
Feature
+
Nginx-styled configuration file format supported, configuration is simple and intuitive
+
Hosts and extensions supported, as well as port number
+
Plugins extending rewrite commands, CLI commands and page supported
+
HTTPS certificate auto-generate
+
Proxy auto-config
+
Background start and log file output
+
Configuration file auto-find
+
Browser window auto-open and proxy auto-config
+
Node.js API provided
+
…
+
+
Concept
After rethought many of the existing development models and summed up some of the encountered problems, hiproxy is developed based on the following two concepts:
+
+
Workspace：hiproxy works in Workspace, the configuration files for all projects in the workspace are resolved by hiproxy. The workspace can be specified via option -w, --workspace <workspace>, or directly into the workspace to start the proxy service.
+
Shared configuration file: Configuration files are submitted to the repository, and team members share them. Previously, hosts and Nginx configurations were generally not submitted to the repository, and the team members were locally maintained, costly and inefficient.
+
+
Basic principle
The core functionality of hiproxy is the proxy request, it handles some of the development details at the same time as the proxy request, such as automatic generation of HTTPS certificates, automatic configuration of browser agents, and so on.
+
The basic principles of hiproxy core functionality describe as follows.
+
Proxy request
hiproxy makes full use of the Man-in-the-middle attack model as intermediaries, data is forwarded at the client and server side to implement the HTTP and proxy for the HTTPS requests.
+
HTTP request
For the HTTP request, if the browser has configured the proxy, it will send GET/POST and so on to the hiproxy agent. After the hiproxy receives the request, it makes some changes to the requested information based on the user’s hosts and rewrite rules, and then goes to the appropriate server to request the resource and return it to the client.
+
HTTPS request
For the HTTPS request, the browser will send a CONNECT request to hiproxy service after the proxy configured, then hiproxy will start a new TCP connection to the final target server (i.e. a new tunnel) and then transmit the data between the client and server.
+
However, it’s only a simple proxy request, and hiproxy cannot obtain the requested information, such as parameters and Cookie, and there is no way to modify the response data. If we do not need to make corresponding changes to the request and response information, this will meet our needs.
+
What needs to be done if we need to implement the same functionality as the HTTP request: do some changes to the request and response based on the requested information?
+
Fortunately, we can make full use of Man-in-the-middle attack model. Because the final target server can get the requested information, we can start an intermediary service between the hiproxy and the final server (here referred to as M), when hiproxy receives a CONNECT request, it starts a new connection to the M, when the M receives the request, it makes some modifications to the request information, like the HTTP request agent, and then requests the resource from the target server and returns it to the client.
+
HTTPS certificate generation
In the SSL/TLS handshake, the first message sent by the client (Client Hello) will be using the extension SNI(Server Name Indication) to send the requested domain to the server. Although only the domain information is sent, other requests, paths, parameters, and cookie are not sent, but the domain is sufficient for the certificate to be generated.
+
When hiproxy gets the domain for the request:
+
+
If the user has configured the certificate for the corresponding domain, the user configured certificate is sent to the client.
+
Otherwise, a new domain certificate is generated and returned to the client.
+
+
Browser window
First, find the path corresponding to the browser in the system. For example, on OSX, look for <browser-name>.app, then start the app and pass arguments to configure the proxy server address.
+
1
<path-to-chrome-app>.app [options] [url]
+
On Windows, you go to the registry to find the exe file path for the browser. Then run and pass arguments.
+
1
<path-to-chrome-app>.exe [options] [url]
+
For Chrome/Opera, we need to pass two arguments:
+
+
Address of proxy service: --proxy-pac-url (PAC proxy file path) or --proxy-server (general agent address), hiproxy supports all.
+
+
The directory where user data is stored: --user-data-dir
+
+
+
When passing this argument, and the directory is not the default directory the browser uses to store user data, it will create a new browser instance which is independent of any other browser window and has no effect on each other(the instance has been configured with proxy, the request of other browser instance will not pass through the proxy configuration here).
+
Configuration file
hiproxy can use hosts as a simple proxy request and configure rewrite rules similar to the Nginx syntax for complex configurations.
+
hosts
Consistent with the system hosts syntax, in addition, port numbers are supported. Hosts can only configure the IP and port numbers corresponding to the domain, detailed routing configuration and request response modification are not supported. For more details, check hosts。
+
hosts configuration sample
1 2 3 4 5
# comment 127.0.0.1 example.com
# ip + port 127.0.0.1:8800 blog.example.com life.example.com
+
rewrite
The rewrite rule configuration file allows you to use more complex configurations to satisfy complex usage scenarios. You can configure the route in detail and make modifications to the request response. The syntax for the rewrite rule configuration is very similar to that of the Nginx syntax. For more details, check rewrite。
+
rewrite configuration sample
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
# Global variable set$port 8899; set$ip 127.0.0.1; set$online 210.0.0.0;
When hiproxy starts, it automatically finds the module at the beginning of the hiproxy-plugin- from the directory in the NPM global module (npm, root, -g) and automatically resolve the plugin content after finding the modules.
+
Therefore, we only need global install plugins independently, no need to upgrade hiproxy, and the hiproxy plugin development is also independent, the plugin project itself is not dependent on hiproxy.
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
You can define your own global variables (use set $var value in global scope) in rewrite rules configuration file of hiproxy, as well as you can define variables in other scopes.
+
Hiproxy has some built-in variables so that you can use them directly in corresponding scopes without neither defining nor assigning. Particularly, user cannot redefine the variables to overwrite them.
+
Global variables
Global variables can be used in everywhere of configuration files.
+
+
Hint: hiproxy currently has not built-in variables. Some would be added in the furture.
+
+
Location block scope variables
You can use the variables only in location blocks. Then are used to store information about request, such as query string($query_string), Cookie($cookie_name), and host($host), etc. Here are all the variables that are currently supported:
+
$host
The host correlative to the current request URL, or the Host field in request headers.
+
$hostname
The hostname correlative to the current request URL, or correlative to the Host field in request headers.
+
$server_port
The server port number of the request, default 80.
+
$search
The query string (with ?) of the request, such as ?from=app&v=19482848253.
+
$query_string
The query string (without ?), such as from=app&v=19482848253.
+
$scheme
The request protocol, it’s either http or https.
+
$request_uri
The entire request URL, such as http://hiproxy.org:8081/docs/index.html?from=google&v=_1847295727524#get-started.
+
$path
The request path (with query string), such as /docs/index.html?from=google&v=_1847295727524#get-started.
+
$path_name
The request path_name (without query string), such as /docs/index.html.
+
$base_name
The last part of the path. For exampke, let’s say the path is /docs/index.html, so that $base_name is index.html.
+
$dir_name
The directory names of the path. For example, let’s say path is /docs/index.html, so that $dir_name is /docs/.
+
$hash
The hash (with #) of request URL, such as #get-started.
+
$hash_value
The hash value (without #) of request URL, such as get-started.
+
$uri
Same as $request_uri.
+
$cookie_name
A cookie value. The name stands field name whose capital letters have been changed to lower ones and - characters have been changed to _. For example, $cookie_userId is for the value of userId in the cookie.
+
$http_name
The value of a request header field. The name stands field name whose capital letters have been changed to lower ones and - characters have been changed to _. For example, let’s say User-Agent: user agent is a valid request header, then $http_user_agent can get its value.
+
$arg_name
The value of a request query parameter. The name stands field name whose capital letters have been changed to lower ones and - characters have been changed to _. For example, let’s say the query string is ?from=google&v=_1847295727524, then$arg_fromcan get value offrom`.
If you are willing to help hiproxy to write documentation, please contact zdying@live.com, thank you!
+
+
Introduction
rewrite reference Nginx configuration syntax. With very simple configuration, it is helpful for front-end developer to debug in native with online API or some other environemnts.
+
The server would scan and monitor rewrite files in each projects while it’s running. If some file are changed, it can update forward rules immediately without restarting the server.
+
Note: hiproxy support both rewrite and hosts file. If you need only simple domain+port forwarding, you can use host file by referencinghosts.
+
Basic syntax
Variables
Syntax
+
1
$variableName
+
Example
+
1 2 3 4 5
# 定义变量 set$var_name value
# 使用变量 $var_name
+
domain
domain specify a domain name and all configuration about the domain name should be in the domain block.
+
Syntax
+
1 2 3
[domain_name|variable] => { # ... }
+
Example
+
1 2 3 4 5 6 7 8 9 10 11
set$domain some.example.com
# use a domain name directly some.example.com => { # ... }
# or use a variable $domain => { # ... }
+
Or
+
1 2 3 4 5 6 7 8 9 10 11
set$domain some.example.com
# use a domain name directly domain some.example.com { # ... }
# or use a variable domain $domain { # ... }
+
location
location represent a specific path. All configuration about the path should be in the location block.
{ command: 'hello', describe: 'A test command that say hello to you.', usage: 'hello [--name <name>] [-xodD]', fn: function () { var cliArgs = this; if (cliArgs.name ) { console.log('your name is', cliArgs.name.green); }
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 testcommand 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[,...]] available parameters : log info warn error debug detail --grep <content> Filter the log data
+
start
This command will start a local proxy service on the specified port. You can specify whether the service is running in the background, if running in the background, all the log of the service will be rediret to the log files.
+
The log file is located in the user’s home directory by default. Of course, you can specify the log file’s path via the option --log-dir <dir>.
-h, --help show help info -D, --daemon Run hiproxy in background -c, --hosts-file <files> hosts files, format: <file1>[,<file2>[,...]] -s, --https Enable HTTPS proxy -m, --middle-man-port <port> The Man-In-The-MiddleHTTPS proxy port, default: 10010 -o, --open [browser] Open a browser window and use hiproxy proxy --pac-proxy Use Proxy auto-configuration (PAC) -p, --port <port> HTTP proxy port, default: 5525 -r, --rewrite-file <files> rewrite config files, format: <file1>[,<file2>[,...]] --sys-proxy <path> Your own proxy server path, format: <ip>[:port], only works when use PAC -w, --workspace <dir> The workspace
+
stop
If the proxy service is running in the background, hiproxy provides a stop command to stop the service
+
1
> hiproxy stop
+
open
The open command can open a browser window and automatically set up the browser’s proxy info based on the currently started proxy service.
+
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
> hiproxy open --help
USAGE:
open [options]
DESCRIBE:
Open browser and set proxy
OPTIONS:
-h, --help show help info -b, --browser <browser> Browser name, default: chrome. Valid alues: chrome,firefox,opera --pac-proxy Use Proxy auto-configuration (PAC)
+
state
This command will display the basic status information of the currently started proxy service.
