Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge proxy-docs-399

Author: jesstess
Reviewer: exarkun
Fixes: #399

Add a web howto section on proxies and reverse proxies and add more
proxy examples to the web examples directory.



git-svn-id: svn://svn.twistedmatrix.com/svn/Twisted/trunk@33262 bbbe8e31-12d6-0310-92fd-ac37d47ddeeb
  • Loading branch information...
commit e5478d7f3502b64285ddd41e0f7e0b62a2ec9192 1 parent 2d53b41
jesstess authored
View
19 doc/web/examples/index.xhtml
@@ -35,16 +35,23 @@
<h2>Virtual hosts and proxies</h2>
<ul>
+ <li><a href="proxy.py">proxy.py</a> -
+ use <code>twisted.web.proxy.Proxy</code> to make the simplest
+ proxy</li>
+ <li><a href="logging-proxy.py">logging-proxy.py</a> - example of
+ subclassing the core classes of <code>twisted.web.proxy</code>
+ to log requests through a proxy</li>
+ <li><a href="reverse-proxy.py">reverse-proxy.py</a> - use
+ <code>twisted.web.proxy.ReverseProxyResource</code> to make
+ any HTTP request to the proxy port get applied to a specified
+ website</li>
<li><a href="rootscript.py">rootscript.py</a> - example use of
<code>twisted.web.vhost.NameVirtualHost</code></li>
<li><a href="web.py">web.py</a> - an example of both using the
- <code>processors</code> attribute to set how certain file types
- are treated and using
- <code>twisted.web.vhost.VHostMonsterResource</code> to reverse
+ <code>processors</code> attribute to set how certain file types
+ are treated and using
+ <code>twisted.web.vhost.VHostMonsterResource</code> to reverse
proxy</li>
- <li><a href="proxy.py">proxy.py</a> - use
- <code>twisted.web.proxy</code> to make any HTTP request to the
- proxy port get applied to a specified website</li>
</ul>
<h2>.rpys and ResourceTemplate</h2>
View
28 doc/web/examples/logging-proxy.py
@@ -0,0 +1,28 @@
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+# Run this example with:
+# python logging-proxy.py
+#
+# Then configure your web browser to use localhost:8080 as a proxy,
+# and visit a URL. This proxy is proxying the connection to that URL's
+# host and will log the client IP and hostname.
+
+from twisted.internet import reactor
+from twisted.web import proxy, http
+
+class LoggingProxyRequest(proxy.ProxyRequest):
+ def process(self):
+ print "Request from %s for %s" % (
+ self.getClientIP(), self.getAllHeaders()['host'])
+ proxy.ProxyRequest.process(self)
+
+class LoggingProxy(proxy.Proxy):
+ requestFactory = LoggingProxyRequest
+
+class LoggingProxyFactory(http.HTTPFactory):
+ def buildProtocol(self, addr):
+ return LoggingProxy()
+
+reactor.listenTCP(8080, LoggingProxyFactory())
+reactor.run()
View
16 doc/web/examples/proxy.py
@@ -1,11 +1,19 @@
-
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.
+# Run this example with:
+# python proxy.py
+#
+# Then configure your web browser to use localhost:8080 as a proxy and
+# visit a URL. This proxy is proxying the connection to that URL's
+# host.
+from twisted.web import proxy, http
from twisted.internet import reactor
-from twisted.web import proxy, server
-site = server.Site(proxy.ReverseProxyResource('www.yahoo.com', 80, ''))
-reactor.listenTCP(8080, site)
+class ProxyFactory(http.HTTPFactory):
+ def buildProtocol(self, addr):
+ return proxy.Proxy()
+
+reactor.listenTCP(8080, ProxyFactory())
reactor.run()
View
15 doc/web/examples/reverse-proxy.py
@@ -0,0 +1,15 @@
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+# Run this example with:
+# python reverse-proxy.py
+#
+# Then visit http://localhost:8080 in your web browser. The reverse
+# proxy will proxy your connection to www.yahoo.com.
+
+from twisted.internet import reactor
+from twisted.web import proxy, server
+
+site = server.Site(proxy.ReverseProxyResource('www.yahoo.com', 80, ''))
+reactor.listenTCP(8080, site)
+reactor.run()
View
89 doc/web/howto/using-twistedweb.xhtml
@@ -201,6 +201,95 @@ arguments passed to the resource regardless of whether they used GET
<img src="../img/web-session.png" />
+<h3>Proxies and reverse proxies</h3>
+<a name="proxies" />
+
+<p>A proxy is a general term for a server that functions as an intermediary
+between clients and other servers.</p>
+
+<p>Twisted supports two main proxy variants: a <code class="API"
+base="twisted.web.proxy">Proxy</code> and a <code class="API"
+base="twisted.web.proxy">ReverseProxy</code>.</p>
+
+<h4>Proxy</h4>
+
+<p>A proxy forwards requests made by a client to a destination server. Proxies
+typically sit on the internal network for a client or out on the internet, and
+have many uses, including caching, packet filtering, auditing, and circumventing
+local access restrictions to web content.</p>
+
+<p>Here is an example of a simple but complete web proxy:</p>
+
+<pre class="python">
+from twisted.web import proxy, http
+from twisted.internet import reactor
+
+class ProxyFactory(http.HTTPFactory):
+ def buildProtocol(self, addr):
+ return proxy.Proxy()
+
+reactor.listenTCP(8080, ProxyFactory())
+reactor.run()
+</pre>
+
+<p>With this proxy running, you can configure your web browser to use
+<code>localhost:8080</code> as a proxy. After doing so, when browsing the web
+all requests will go through this proxy.</p>
+
+<p><code class="API" base="twisted.web.proxy">Proxy</code> inherits
+from <code class="API" base="twisted.web">http.HTTPChannel</code>. Each client
+request to the proxy generates a <code class="API"
+base="twisted.web.proxy">ProxyRequest</code> from the proxy to the destination
+server on behalf of the client. <code>ProxyRequest</code> uses
+a <code class="API" base="twisted.web.proxy">ProxyClientFactory</code> to create
+an instance of the <code class="API" base="twisted.web.proxy">ProxyClient</code>
+protocol for the connection. <code>ProxyClient</code> inherits
+from <code class="API"
+base="twisted.web">http.HTTPClient</code>. Subclass <code>ProxyRequest</code> to
+customize the way requests are processed or logged.</p>
+
+<h4>ReverseProxyResource</h4>
+
+<p>A reverse proxy retrieves resources from other servers on behalf of a
+client. Reverse proxies typically sit inside the server's internal network and
+are used for caching, application firewalls, and load balancing.</p>
+
+<p>Here is an example of a basic reverse proxy:</p>
+
+<pre class="python">
+from twisted.internet import reactor
+from twisted.web import proxy, server
+
+site = server.Site(proxy.ReverseProxyResource('www.yahoo.com', 80, ''))
+reactor.listenTCP(8080, site)
+reactor.run()
+</pre>
+
+<p>With this reverse proxy running locally, you can
+visit <code>http://localhost:8080</code> in your web browser, and the reverse
+proxy will proxy your connection to
+<code>www.yahoo.com</code>.</p>
+
+<p>In this example we use <code base="twisted.web">server.Site</code> to serve
+a <code base="twisted.web.proxy">ReverseProxyResource</code> directly. There is
+also a <code>ReverseProxy</code> family of classes
+in <code>twisted.web.proxy</code> mirroring those of the <code>Proxy</code>
+family:</p>
+
+<p>Like <code>Proxy</code>, <code class="API"
+base="twisted.web.proxy">ReverseProxy</code> inherits
+from <code>http.HTTPChannel</code>. Each client request to the reverse proxy
+generates a <code class="API"
+base="twisted.web.proxy">ReverseProxyRequest</code> to the destination
+server. Like <code>ProxyRequest</code>, <code class="API"
+base="twisted.web.proxy">ReverseProxyRequest</code> uses a <code class="API"
+base="twisted.web.proxy">ProxyClientFactory</code> to create an instance of
+the <code class="API" base="twisted.web.proxy">ProxyClient</code> protocol for
+the connection.</p>
+
+<p>Additional examples of proxies and reverse proxies can be found in
+the <a href="../examples/index.html">Twisted web examples</a>.</p>
+
<h2>Advanced Configuration</h2>
<p>Non-trivial configurations of Twisted Web are achieved with Python
View
2  twisted/web/proxy.py
@@ -220,7 +220,7 @@ class ReverseProxy(HTTPChannel):
"""
Implements a simple reverse proxy.
- For details of usage, see the file examples/proxy.py.
+ For details of usage, see the file examples/reverse-proxy.py.
"""
requestFactory = ReverseProxyRequest
View
1  twisted/web/topfiles/399.doc
@@ -0,0 +1 @@
+The Twisted Web howto now has a section on proxies and reverse proxies.
Please sign in to comment.
Something went wrong with that request. Please try again.