Updated docs

praekeltfoundation · Feb 8, 2016 · 80772e4 · 80772e4
1 parent b6939d1
commit 80772e4
Show file tree

Hide file tree

Showing 3 changed files with 87 additions and 30 deletions.
diff --git a/docs/http-proxy.rst b/docs/http-proxy.rst
@@ -1,15 +1,71 @@
-vumi-http-proxy Package
-=======================
+vumi_http_proxy Package Docs
+============================
 
+Class Documentation
 
+http_proxy Module
+^^^^^^^^^^^^^^^^^
 
+.. automodule:: vumi_http_proxy.http_proxy
 
 
-.. py:module:: vumi_http_proxy.http_proxy
+.. autoclass:: CheckProxyRequest
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: Initialize
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
+.. autoclass:: Proxy
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
+.. autoclass:: ProxyFactory
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-.. autoclass:: CheckProxyRequest
+.. autoclass:: StringProducer
     :members:
     :undoc-members:
     :show-inheritance:
+
+
+queen-of-ni Module
+^^^^^^^^^^^^^^^^^^
+
+.. automodule:: vumi_http_proxy.queen_of_ni
+    :members:
+
+.. autoclass:: cli
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+servicemaker Module
+^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: vumi_http_proxy.servicemaker
+    :members:
+
+.. autoclass:: Options
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: ProxyWorkerServiceMaker
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+config_reader Module
+^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: vumi_http_proxy.config_reader
+    :members:
diff --git a/docs/project-outline.rst b/docs/project-outline.rst
@@ -22,21 +22,4 @@ Vumi’s Javascript sandbox allows application developers to access HTTP
 resources, we need a proxy that intercepts these outbound HTTP calls and checks
 whether the calls to the specified resources are allowed or not. This boils down
 to maintaining a blacklist of disallowed HTTP resources and per request checking
-against the blacklist.
-
-And now for something completely different::
-
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-░░░░░░░░░░▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄░░░░░░░░░
-░░░░░░░░▄▀░░░░░░░░░░░░▄░░░░░░░▀▄░░░░░░░
-░░░░░░░░█░░▄░░░░▄░░░░░░░░░░░░░░█░░░░░░░
-░░░░░░░░█░░░░░░░░░░░░▄█▄▄░░▄░░░█░▄▄▄░░░
-░▄▄▄▄▄░░█░░░░░░▀░░░░▀█░░▀▄░░░░░█▀▀░██░░
-░██▄▀██▄█░░░▄░░░░░░░██░░░░▀▀▀▀▀░░░░██░░
-░░▀██▄▀██░░░░░░░░▀░██▀░░░░░░░░░░░░░▀██░
-░░░░▀████░▀░░░░▄░░░██░░░▄█░░░░▄░▄█░░██░
-░░░░░░░▀█░░░░▄░░░░░██░░░░▄░░░▄░░▄░░░██░
-░░░░░░░▄█▄░░░░░░░░░░░▀▄░░▀▀▀▀▀▀▀▀░░▄▀░░
-░░░░░░█▀▀█████████▀▀▀▀████████████▀░░░░
-░░░░░░████▀░░███▀░░░░░░▀███░░▀██▀░░░░░░
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+against the blacklist.
diff --git a/vumi_http_proxy/http_proxy.py b/vumi_http_proxy/http_proxy.py
@@ -27,7 +27,12 @@ def buildProtocol(self, addr):
 
 
 class CheckProxyRequest(proxy.ProxyRequest):
+    """
+    Receives request, processes request and returns response
+    """
     def process(self):
+        """ Attain hostname, return deferred on resolver.getHostByName
+        """
         host, _, port = self.getAllHeaders()['host'].partition(':')
         d = self.channel.resolver.getHostByName(host)
         d.addCallback(self.setIP, host)
@@ -42,6 +47,9 @@ def handleError(self, failure):
         return
 
     def setIP(self, ip_addr, host):
+        """
+        Process corresponding ip address to allow or deny.
+        """
         if not ip_addr:
             self.setResponseCode(400)
             self.write("<html>ERROR: No IP adresses found for name %r" %
@@ -61,6 +69,9 @@ def setIP(self, ip_addr, host):
         return d
 
     def replaceHostWithIP(self, uri, ip_addr):
+        """
+        Parse request to find host, replace with IP and port (if applicable).
+        """
         scheme, netloc, path, params, query, fragment = urlparse(uri)
         _, _, port = netloc.partition(':')
         if port:
@@ -69,6 +80,9 @@ def replaceHostWithIP(self, uri, ip_addr):
 
     @inlineCallbacks
     def sendResponseBack(self, r):
+        """
+        Fetch response and response code, send to client.
+        """
         self.setResponseCode(r.code)
         for key, value in r.headers.getAllRawHeaders():
             self.responseHeaders.addRawHeader(key, value)
@@ -78,6 +92,9 @@ def sendResponseBack(self, r):
 
 
 class StringProducer(object):
+    """
+    Parse response body.
+    """
     def __init__(self, body):
         self.body = body
         self.length = len(body)
@@ -94,7 +111,9 @@ def stopProducing(self):
 
 
 class Proxy(proxy.Proxy):
-
+    """
+    Start proxy with CheckProxyRequest as requestFactory.
+    """
     requestFactory = CheckProxyRequest
 
     def __init__(self, blacklist, resolver, http_client):
@@ -109,6 +128,12 @@ class Initialize(object):
     This class initialises the proxy based on the configuration specified
     """
     def __init__(self, blacklist, dnsservers, ip, port):
+        self.blacklist = blacklist
+        self.dnsservers = dnsservers
+        self.ip = ip
+        self.port = port
+
+    def main(self):
         """
         :param blacklist: List of disallowed ip addresses.
         :type blacklist: list
@@ -119,13 +144,6 @@ def __init__(self, blacklist, dnsservers, ip, port):
         :param port: Port of server to initialize proxy
         :type port: int
         """
-        self.blacklist = blacklist
-        self.dnsservers = dnsservers
-        self.ip = ip
-        self.port = port
-
-    def main(self):
-
         resolver = client.createResolver(self.dnsservers)
         http_client = Agent(reactor)
         factory = ProxyFactory(self.blacklist, resolver, http_client)