github.com/coreos/goproxy@v0.0.0-20190513173959-f8dc2d7ba04e/doc.go (about)

     1  /*
     2  Package goproxy provides a customizable HTTP proxy,
     3  supporting hijacking HTTPS connection.
     4  
     5  The intent of the proxy, is to be usable with reasonable amount of traffic
     6  yet, customizable and programable.
     7  
     8  The proxy itself is simply an `net/http` handler.
     9  
    10  Typical usage is
    11  
    12  	proxy := goproxy.NewProxyHttpServer()
    13  	proxy.OnRequest(..conditions..).Do(..requesthandler..)
    14  	proxy.OnRequest(..conditions..).DoFunc(..requesthandlerFunction..)
    15  	proxy.OnResponse(..conditions..).Do(..responesHandler..)
    16  	proxy.OnResponse(..conditions..).DoFunc(..responesHandlerFunction..)
    17  	http.ListenAndServe(":8080", proxy)
    18  
    19  Adding a header to each request
    20  
    21  	proxy.OnRequest().DoFunc(func(r *http.Request,ctx *goproxy.ProxyCtx) (*http.Request, *http.Response){
    22  		r.Header.Set("X-GoProxy","1")
    23  		return r, nil
    24  	})
    25  
    26  Note that the function is called before the proxy sends the request to the server
    27  
    28  For printing the content type of all incoming responses
    29  
    30  	proxy.OnResponse().DoFunc(func(r *http.Response, ctx *goproxy.ProxyCtx)*http.Response{
    31  		println(ctx.Req.Host,"->",r.Header.Get("Content-Type"))
    32  		return r
    33  	})
    34  
    35  note that we used the ProxyCtx context variable here. It contains the request
    36  and the response (Req and Resp, Resp is nil if unavailable) of this specific client
    37  interaction with the proxy.
    38  
    39  To print the content type of all responses from a certain url, we'll add a
    40  ReqCondition to the OnResponse function:
    41  
    42  	proxy.OnResponse(goproxy.UrlIs("golang.org/pkg")).DoFunc(func(r *http.Response, ctx *goproxy.ProxyCtx)*http.Response{
    43  		println(ctx.Req.Host,"->",r.Header.Get("Content-Type"))
    44  		return r
    45  	})
    46  
    47  We can write the condition ourselves, conditions can be set on request and on response
    48  
    49  	var random = ReqConditionFunc(func(r *http.Request) bool {
    50  		return rand.Intn(1) == 0
    51  	})
    52  	var hasGoProxyHeader = RespConditionFunc(func(resp *http.Response,req *http.Request)bool {
    53  		return resp.Header.Get("X-GoProxy") != ""
    54  	})
    55  
    56  Caution! If you give a RespCondition to the OnRequest function, you'll get a run time panic! It doesn't
    57  make sense to read the response, if you still haven't got it!
    58  
    59  Finally, we have convenience function to throw a quick response
    60  
    61  	proxy.OnResponse(hasGoProxyHeader).DoFunc(func(r*http.Response,ctx *goproxy.ProxyCtx)*http.Response {
    62  		r.Body.Close()
    63  		return goproxy.ForbiddenTextResponse(ctx.Req,"Can't see response with X-GoProxy header!")
    64  	})
    65  
    66  we close the body of the original repsonse, and return a new 403 response with a short message.
    67  
    68  Example use cases:
    69  
    70  1. https://github.com/elazarl/goproxy/tree/master/examples/goproxy-avgsize
    71  
    72  To measure the average size of an Html served in your site. One can ask
    73  all the QA team to access the website by a proxy, and the proxy will
    74  measure the average size of all text/html responses from your host.
    75  
    76  2. [not yet implemented]
    77  
    78  All requests to your web servers should be directed through the proxy,
    79  when the proxy will detect html pieces sent as a response to AJAX
    80  request, it'll send a warning email.
    81  
    82  3. https://github.com/elazarl/goproxy/blob/master/examples/goproxy-httpdump/
    83  
    84  Generate a real traffic to your website by real users using through
    85  proxy. Record the traffic, and try it again for more real load testing.
    86  
    87  4. https://github.com/elazarl/goproxy/tree/master/examples/goproxy-no-reddit-at-worktime
    88  
    89  Will allow browsing to reddit.com between 8:00am and 17:00pm
    90  
    91  5. https://github.com/elazarl/goproxy/tree/master/examples/goproxy-jquery-version
    92  
    93  Will warn if multiple versions of jquery are used in the same domain.
    94  
    95  6. https://github.com/elazarl/goproxy/blob/master/examples/goproxy-upside-down-ternet/
    96  
    97  Modifies image files in an HTTP response via goproxy's image extension found in ext/.
    98  
    99  */
   100  package goproxy