[tor-commits] [ooni-probe/master] Add some documentation to b0wser protocol and server

[art at torproject.org]

commit 4391e65f226f9b45ceaa08465f466903de14f8e0
Author: Arturo Filastò <hellais at torproject.org>
Date:   Wed Jul 11 12:54:09 2012 +0200

    Add some documentation to b0wser protocol and server
---
 oonib/b0wser.py |   39 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 39 insertions(+), 0 deletions(-)

diff --git a/oonib/b0wser.py b/oonib/b0wser.py
index 6da1997..4b01cc7 100644
--- a/oonib/b0wser.py
+++ b/oonib/b0wser.py
@@ -5,6 +5,12 @@ from ooni.plugoo import reports
 from ooni.protocols.b0wser import Mutator
 
 class B0wserProtocol(protocol.Protocol):
+    """
+    This implements the B0wser protocol for the server side.
+    It gets instanced once for every client that connects to the oonib.
+    For every instance of protocol there is only 1 mutation.
+    Once the last step is reached the connection is closed on the serverside.
+    """
     steps = [{'data': "STEP1", 'wait': 4},
              {'data': "STEP2", 'wait': 4},
              {'data': "STEP3", 'wait': 4}]
@@ -16,12 +22,22 @@ class B0wserProtocol(protocol.Protocol):
     report = reports.Report('b0wser', 'b0wser.yamlooni')
 
     def next_state(self):
+        """
+        This is called once I have completed one step of the protocol and need
+        to proceed to the next step.
+        """
         data = self.mutator.get_mutation(self.state)
         self.transport.write(data)
         self.state += 1
         self.received_data = 0
 
     def dataReceived(self, data):
+        """
+        This is called every time some data is received. I transition to the
+        next step once the amount of data that I expect to receive is received.
+
+        @param data: the data that has been sent by the client.
+        """
         if len(self.steps) <= self.state:
             self.transport.loseConnection()
             return
@@ -31,6 +47,17 @@ class B0wserProtocol(protocol.Protocol):
             self.next_state()
 
     def censorship_detected(self, report):
+        """
+        I have detected the possible presence of censorship we need to write a
+        report on it.
+
+        @param report: a dict containing the report to be written. Must contain
+                       the keys 'reason', 'proto_state' and 'mutator_state'.
+                       The reason is the reason for which the connection was
+                       closed. The proto_state is the current state of the
+                       protocol instance and mutator_state is what was being
+                       mutated.
+        """
         print "The connection was closed because of %s" % report['reason']
         print "I may have matched the censorship fingerprint"
         print "State %s, Mutator %s" % (report['proto_state'],
@@ -39,6 +66,10 @@ class B0wserProtocol(protocol.Protocol):
 
 
     def connectionLost(self, reason):
+        """
+        The connection was closed. This may be because of a legittimate reason
+        or it may be because of a censorship event.
+        """
         report = {'reason': reason, 'proto_state': self.state,
                 'mutator_state': self.mutator.state(), 'trigger': None}
 
@@ -53,6 +84,14 @@ class B0wserProtocol(protocol.Protocol):
             self.censorship_detected(report)
 
 class B0wserServer(protocol.ServerFactory):
+    """
+    This is the main class that deals with the b0wser server side component.
+    We keep track of global state of every client here.
+    Every client is identified by their IP address and the state of mutation is
+    stored by using their IP address as a key. This may lead to some bugs if
+    two different clients are sharing the same IP, but hopefully the
+    probability of such thing is not that likely.
+    """
     protocol = B0wserProtocol
     mutations = {}
     def buildProtocol(self, addr):