Updated What is rule file and how to write (markdown)

What-is-rule-file-and-how-to-write.md

@@ -1,13 +1,15 @@
-Anyproxy exposes a lot of interface for you to hack requests. To use them, you have to write a *.js file which is a Node.js module. Here we name this kind of file as **rule file**, which means this file defines the rule to handle all requests.
+Anyproxy exposes a lot of interface for you to hack requests. To use them, you have to write a *.js file which is a Node.js module. Here we name this kind of file as **rule file** , which means this file defines the rule to handle all requests.
 
-How it works
+How proxy works
 -----------------------
 Basically, you should understand how http-proxy works.
-Http-proxy is something like a man standing between client and server. When a client is configured with proxy, all requests sent to target server will be forwarded to proxy server. After getting requests, proxy server would try to figure out the request url(host and path), headers, and request body. Then with these data, proxy will send a request to target server on behalf of the client. As you can imagine, the procedure of getting response is also very likely.
+Http-proxy is something like a man standing between client and server. When a client is configured with proxy, all requests sent to target server will be forwarded to proxy server. After being requested, proxy server would try to figure out the request url(host and path), headers, and request body. Using these data, proxy will then send a request to target server on behalf of the client. As you can imagine, the procedure of getting response is also very likely.
 
-As you can see, the proxy server as a middle man could inspect and modify any byte of an http request without being noticed by client or target server. AnyProxy is exactly the tool for you to customize these requests.
+Obviously, the proxy server as a middle man is able to inspect and modify any byte of an http request without being noticed by client or target server, which is a great feature for building a customized network env. AnyProxy is exactly the tool for you to customize these requests.
 
-Here is a figure showing the whole procedure. The bold bubble on the right is interface exposed by anyproxy.(interface in this figure may by outdate, please refer to docs instead of this figure when coding)
+Interface
+-----------------------
+Here is a figure showing the whole procedure. The bold bubble on the right is interface exposed by anyproxy.(interface in this figure may be outdate, please refer to docs instead of this figure when coding)
 
 ![](https://t.alipayobjects.com/images/T1v8pbXjJqXXXXXXXX.png)
 
@@ -22,21 +24,20 @@ module.exports = {
         return "this is a blank rule for anyproxy";
     },
 
-	shouldUseLocalResponse : function(req,reqBody){
+    shouldUseLocalResponse : function(req,reqBody){
         return false;
-	},
+    },
 
-	dealLocalResponse : function(req,reqBody,callback){
+    dealLocalResponse : function(req,reqBody,callback){
         callback(statusCode,resHeader,responseData);
-	},
+    },
 
     replaceRequestProtocol:function(req,protocol){
     	return protocol;
     },
 
     replaceRequestOption : function(req,option){
-        var newOption = option;
-        return newOption;
+        return option;
     },
 
     replaceRequestData: function(req,data){
@@ -65,7 +66,8 @@ module.exports = {
 };
 ```
 
-These interface can be grouped into three phases
+These interface can be grouped into the following phases
+* Phase 0 , some preparation
 * Phase 1 , when proxy server gets request from client
 * Phase 2 , deal request parameters before sending to target server 
 * Phase 3 , after getting response from target server, deal it before sending to client
@@ -74,19 +76,19 @@ These interface can be grouped into three phases
 * `summary` the summary of this rule file. AnyProxy will show it to user.
 
 #### **Phase 1**
-* `shouldInterceptHttpsReq` whether https request should be intercepted. If `false` is returned, https requests will not be decrpted. This is only available after certificated has been generated and configured.
-* `shouldUseLocalResponse` whether you want to response this request with local data. If it returns true, `dealLocalResponse` will be called and other function about target server will be ignored.
+* `shouldInterceptHttpsReq` whether this https request should be intercepted. If `false` is returned, https requests will not be decrpted. This is only available after certificated has been generated and configured.
+* `shouldUseLocalResponse` whether you want to response this request with local data. If it returns true, `dealLocalResponse` will be called and further function about target server will be ignored.
 * `dealLocalResponse` if `shouldUseLocalResponse` returns true, this function will be called, and you should use the ``callback`` function to provide statusCode, response header and response data.
 
 #### **Phase 2**
-* `replaceRequestProtocol` before sending request to real server, this function will be called to decide whether a new protocol should be used. For example, returning "http" for a https request means you will send this request with https. The argument `protocol` is the origin protocol of request. Leave it blank if not necessary.
+* `replaceRequestProtocol` before sending request to real server, this function will be called to decide whether a new protocol should be used. For example, returning "http" for a https request means you will send this request with http. The argument `protocol` is the origin protocol of request. Leaving it blank means keeping it as it should be.
 * `replaceRequestOption` AnyProxy internally use ``require('http').request(option,[callback])`` to send request, and here is the ``option`` anyproxy will use. Return your own one when needed. Along with `replaceRequestProtocol`, it is rather easy for you to forward the request to any other server. Leave it blank if not necessary. Ref about `option` : [http://nodejs.org/api/http.html#http_http_request_options_callback](http://nodejs.org/api/http.html#http_http_request_options_callback)
 * `replaceRequestData` get and replace user's request body
 
 #### **Phase 3**
-* `replaceResponseStatusCode` replace the status code of target server, and this status code will be sent to client
-* `replaceResponseHeader` replace the response header of target server, and this response header will be sent to client
-* `replaceServerResDataAsync` use `callback` to give your response data
+* `replaceResponseStatusCode` replace the status code getting from target server, and this status code will be sent to client
+* `replaceResponseHeader` replace the response header getting from target server, and this response header will be sent to client
+* `replaceServerResDataAsync` use `callback` to give your response data. It's an async function.
 * `pauseBeforeSendingResponse` pause time in ms before sending response to client.
 
 
@@ -97,4 +99,4 @@ req
 
 To invoke a rule file
 -------------------------
-* in shell ``anyproxy --rule /path/to/ruleFile.js``
+* in shell ``anyproxy --rule /path/to/ruleFile.js``