From a4c171e2b98d9e0d01c09c4aed9b69bf670424f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8A=A0=E9=87=8C?= Date: Fri, 5 Sep 2014 13:53:12 +0800 Subject: [PATCH] update doc --- README.md | 39 ++++++++++++++++++------ proxy.js | 4 +-- rule_sample/rule__blank.js | 61 ++++++++++++++++++++++++++++++++++---- 3 files changed, 88 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index d9933c1..40fa761 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ anyproxy ========== A fully configurable proxy in NodeJS, which can handle HTTPS requests perfectly. +(Some Chinese in this doc is nothing but translation of some key points. Be relax if you dont understand.) + +![](https://i.alipayobjects.com/i/ecmng/png/201409/3NKRCRk2Uf.png) Feature ------------ @@ -36,15 +39,33 @@ How to write your own rule file * ``anyproxy --rule /path/to/ruleFile.js`` * you may learn how it works by our samples: [https://github.com/alipay-ct-wd/anyproxy/tree/master/rule_sample](https://github.com/alipay-ct-wd/anyproxy/tree/master/rule_sample) * samples in [rule_sample](https://github.com/alipay-ct-wd/anyproxy/tree/master/rule_sample) - * **rule__blank.js**, blank rule file with some comments. You may read this before writing your own rule file. - * **rule_adjust_response_time.js**, delay all the response for 1500ms - * **rule_allow_CORS.js**, add CORS headers to allow cross-domain ajax request - * **rule_intercept_some_https_requests.js**, intercept https requests toward github.com - * **rule_remove_cache_header.js**, remove all cache-related headers from server - * **rule_replace_request_option.js**, replace request parameters before sending to the server - * **rule_replace_response_data.js**, modify response data - * **rule_replace_response_status_code.js**, replace server's status code - * **rule_use_local_data.js**, map some requests to local file + * **rule__blank.js**, + * blank rule file with some comments. You may read this before writing your own rule file. + * 空白的规则文件模板，和一些注释 + * **rule_adjust_response_time.js** + * delay all the response for 1500ms + * 把所有的响应延迟1500毫秒 + * **rule_allow_CORS.js** + * add CORS headers to allow cross-domain ajax request + * 为ajax请求增加跨域头 + * **rule_intercept_some_https_requests.js** + * intercept https requests toward github.com and append some data + * 截获github.com的https请求，再在最后加点文字 + * **rule_remove_cache_header.js** + * remove all cache-related headers from server + * 去除响应头里缓存相关的头 + * **rule_replace_request_option.js** + * replace request parameters before sending to the server + * 在请求发送到服务端前对参数做一些调整 + * **rule_replace_response_data.js** + * modify response data + * 修改响应数据 + * **rule_replace_response_status_code.js** + * replace server's status code + * 改变服务端响应的http状态码 + * **rule_use_local_data.js** + * map some requests to local file + * 把响应映射到本地 * rule file scheme is as follows, you may also get it from [rule__blank.js](https://github.com/alipay-ct-wd/anyproxy/blob/master/rule_sample/rule__blank.js) diff --git a/proxy.js b/proxy.js index 4387d78..42b5303 100644 --- a/proxy.js +++ b/proxy.js @@ -43,9 +43,9 @@ function proxyServer(option){ proxyType = /https/i.test(option.type || DEFAULT_TYPE) ? T_TYPE_HTTPS : T_TYPE_HTTP , proxyPort = option.port || DEFAULT_PORT, proxyHost = option.hostname || DEFAULT_HOST, - proxyRules = option.rule || require('./lib/rule_default'); + proxyRules = option.rule || require('./lib/rule_default'); - requestHandler.setRules(proxyRules); + requestHandler.setRules(proxyRules); //TODO : optimize calling for set rule self.httpProxyServer = null; async.series( diff --git a/rule_sample/rule__blank.js b/rule_sample/rule__blank.js index 6f46678..cf6453c 100644 --- a/rule_sample/rule__blank.js +++ b/rule_sample/rule__blank.js @@ -1,25 +1,51 @@ module.exports = { /* - these functions will overwrite the default ones, write your own when necessary. + These functions will overwrite the default ones, write your own when necessary. + Comments in Chinese are nothing but a translation of key points. Be relax if you dont understand. + 致中文用户：中文注释都是只摘要，必要时请参阅英文注释。欢迎提出修改建议。 */ summary:function(){ console.log("this is a blank rule for anyproxy"); }, - //whether to intercept this request by local logic + + + + + + //======================= + //when getting a request from user + //收到用户请求之后 + //======================= + + //是否在本地直接发送响应（不再向服务器发出请求） + //whether to intercept this request by local logic //if the return value is true, anyproxy will call dealLocalResponse to get response data and will not send request to remote server anymore shouldUseLocalResponse : function(req,reqBody){ return false; }, + //如果shouldUseLocalResponse返回true，会调用这个函数来获取本地响应内容 //you may deal the response locally instead of sending it to server - //this function be called when shouldUseLocalResponse returns true - //callback(statusCode,resHeader,responseData) - //e.g. callback(200,{"content-type":"text/html"},"hello world") + //this function be called when shouldUseLocalResponse returns true + //callback(statusCode,resHeader,responseData) + //e.g. callback(200,{"content-type":"text/html"},"hello world") dealLocalResponse : function(req,reqBody,callback){ callback(statusCode,resHeader,responseData) }, + + + + + + + //======================= + //when ready to send a request to server + //向服务端发出请求之前 + //======================= + + //替换向服务器发出的请求协议（http和https的替换） //replace the request protocol when sending to the real server //protocol : "http" or "https" replaceRequestProtocol:function(req,protocol){ @@ -27,6 +53,7 @@ module.exports = { return newProtocol; }, + //替换向服务器发出的请求参数（option) //req is user's request which will be sent to the proxy server, docs : http://nodejs.org/api/http.html#http_http_request_options_callback //you may return a customized option to replace the original option //you should not write content-length header in options, since anyproxy will handle it for you @@ -35,17 +62,29 @@ module.exports = { return newOption; }, + //替换请求的body //replace the request body replaceRequestData: function(req,data){ return data; }, + + + + + //======================= + //when ready to send the response to user after receiving response from server + //向用户返回服务端的响应之前 + //======================= + + //替换服务器响应的http状态码 //replace the statusCode before it's sent to the user replaceResponseStatusCode: function(req,res,statusCode){ var newStatusCode = statusCode; return newStatusCode; }, + //替换服务器响应的http头 //replace the httpHeader before it's sent to the user //Here header == res.headers replaceResponseHeader: function(req,res,header){ @@ -53,6 +92,7 @@ module.exports = { return newHeader; }, + //替换服务器响应的数据 //replace the response from the server before it's sent to the user //you may return either a Buffer or a string //serverResData is a Buffer, you may get its content by calling serverResData.toString() @@ -60,12 +100,23 @@ module.exports = { return serverResData; }, + //在请求返回给用户前的延迟时间 //add a pause before sending response to user pauseBeforeSendingResponse : function(req,res){ var timeInMS = 1; //delay all requests for 1ms return timeInMS; }, + + + + + + //======================= + //https config + //======================= + + //是否截获https请求 //should intercept https request, or it will be forwarded to real server shouldInterceptHttpsReq :function(req){ return false;