[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[minion-cvs] Improve documentation
Update of /home/minion/cvsroot/src/minion/lib/mixminion/server
In directory moria.mit.edu:/tmp/cvs-serv20109/lib/mixminion/server
Modified Files:
MMTPServer.py Modules.py
Log Message:
Improve documentation
Index: MMTPServer.py
===================================================================
RCS file: /home/minion/cvsroot/src/minion/lib/mixminion/server/MMTPServer.py,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- MMTPServer.py 13 Jan 2003 06:18:01 -0000 1.18
+++ MMTPServer.py 4 Feb 2003 02:05:02 -0000 1.19
@@ -242,7 +242,8 @@
# __terminator: None, or a string which will terminate the current read.
# __outbuf: None, or the remainder of the string we're currently
# writing.
- # DOCDOC __servermode
+ # __servermode: If true, we're the server side of the connection.
+ # Else, we're the client side.
def __init__(self, sock, tls, serverMode, address=None):
"""Create a new SimpleTLSConnection.
@@ -392,14 +393,16 @@
self.finished()
def __handshakeFn(self):
- "DOCDOC"
- assert not self.__serverMode #DOCDOC
+ """Callback used when we're renegotiating the connection key. Must
+ only be used from client mode."""
+ assert not self.__serverMode
self.__con.do_handshake() #may throw want*
self.__server.unregister(self)
self.finished()
def startRenegotiate(self):
- "DOCDOC"
+ """Begin renegotiation the connection key. Must only be called from
+ client mode."""
self.__con.renegotiate() # Succeeds immediately.
self.__state = self.__handshakeFn
self.__server.registerBoth(self) #????
@@ -511,7 +514,10 @@
# messageConsumer: a function to call with all received messages.
# finished: callback when we're done with a read or write; see
# SimpleTLSConnection.
- # DOCDOC protocol
+ # protocol: The MMTP protocol version we're currently using, or None
+ # if negotiation hasn't completed.
+ # PROTOCOL_VERSIONS: (static) a list of protocol versions we allow,
+ # in decreasing order of preference.
PROTOCOL_VERSIONS = [ '0.2', '0.1' ]
def __init__(self, sock, tls, consumer):
"""Create an MMTP connection to receive messages sent along a given
@@ -621,7 +627,15 @@
## Fields:
# ip, port, keyID, messageList, handleList, sendCallback, failCallback:
# As described in the docstring for __init__ below.
- # DOCDOC protocol
+ # junk: A list of 32KB padding chunks that we're going to send. We
+ # pregenerate these to avoid timing attacks.
+ # isJunk: flag. Is the current chunk padding?
+ # expectedDigest: The digest we expect to receive in response to the
+ # current chunk.
+ # protocol: The MMTP protocol version we're currently using, or None
+ # if negotiation hasn't completed.
+ # PROTOCOL_VERSIONS: (static) a list of protocol versions we allow,
+ # in the order we offer them.
PROTOCOL_VERSIONS = [ '0.1', '0.2' ]
def __init__(self, context, ip, port, keyID, messageList, handleList,
sentCallback=None, failCallback=None):
@@ -631,8 +645,9 @@
ip -- The IP of the destination server.
port -- The port to connect to.
keyID -- None, or the expected SHA1 hash of the server's public key
- messageList -- a list of message payloads to send
- DOCDOC, or 'JUNK', or 'RENEGOTIATE'.
+ messageList -- a list of message payloads and control strings.
+ The control string "JUNK" sends 32KB of padding; the control
+ string "RENEGOTIATE" renegotiates the connection key.
handleList -- a list of objects corresponding to the messages in
messageList. Used for callback.
sentCallback -- None, or a function of (msg, handle) to be called
@@ -737,11 +752,11 @@
return
self.expectedDigest = sha1(msg+"RECEIVED JUNK")
msg = JUNK_CONTROL+msg+sha1(msg+"JUNK")
- self.isJunk = 1 #DOCDOC
+ self.isJunk = 1
else:
self.expectedDigest = sha1(msg+"RECEIVED")
msg = SEND_CONTROL+msg+sha1(msg+"SEND")
- self.isJunk = 0 #DOCDOC
+ self.isJunk = 0
assert len(msg) == SEND_RECORD_LEN
self.beginWrite(msg)
Index: Modules.py
===================================================================
RCS file: /home/minion/cvsroot/src/minion/lib/mixminion/server/Modules.py,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -d -r1.25 -r1.26
--- Modules.py 13 Jan 2003 06:35:52 -0000 1.25
+++ Modules.py 4 Feb 2003 02:05:02 -0000 1.26
@@ -18,7 +18,6 @@
import sys
import smtplib
import socket
-import base64
import threading
if sys.version_info[:2] >= (2,3):
@@ -62,7 +61,8 @@
pass
def getRetrySchedule(self):
- "DOCDOC"
+ """Return a retry schedule for this module's queue, as specified
+ in ServerQueue.DeliveryQueue.setRetrySchedule."""
return None
def getConfigSyntax(self):
@@ -243,9 +243,9 @@
# queueMessage and sendReadyMessages as in DeliveryQueue.)
# _isConfigured: flag: has this modulemanager's configure method been
# called?
- # DOCDOC threaded, thread.
-
- def __init__(self, threaded=0):
+ # thread: None, or a DeliveryThread object.
+
+ def __init__(self):
"Create a new ModuleManager"
self.syntax = {}
self.modules = []
@@ -266,6 +266,8 @@
self.thread = None
def startThreading(self):
+ """Begin delivering messages in a separte thread. Should only
+ be called once."""
self.thread = DeliveryThread(self)
self.thread.start()
@@ -377,7 +379,9 @@
del self.enabled[module.getName()]
def queueDecodedMessage(self, packet):
- #DOCDOC
+ """Given a packet of type DeliveryPacket, try to find an appropriate
+ exit module, and queue the packet for delivey by that exit module.
+ """
exitType = packet.getExitType()
mod = self.typeToModule.get(exitType, None)
@@ -391,8 +395,8 @@
queue.queueDeliveryMessage(packet)
- #DOCDOC
def shutdown(self):
+ """Tell the delivery thread (if any) to stop."""
if self.thread is not None:
self.thread.shutdown()
@@ -400,14 +404,19 @@
if self.thread is not None:
self.thread.join()
- # XXXX refactor, document
def sendReadyMessages(self):
+ """Begin message delivery, either by telling every module's queue to
+ try sending its pending messages, or by telling the delivery
+ thread to do so if we're threading."""
if self.thread is not None:
self.thread.beginSending()
else:
self._sendReadyMessages()
def _sendReadyMessages(self):
+ """Actual implementation of message delivery. Tells every module's
+ queue to send pending messages. This is called directly if
+ we aren't threading, and from the delivery thread if we are."""
for name, queue in self.queues.items():
queue.sendReadyMessages()
@@ -591,7 +600,7 @@
self.addresses = {}
def getRetrySchedule(self):
- return self.retrySchedule #DOCDOC
+ return self.retrySchedule
def getConfigSyntax(self):
# FFFF There should be some way to say that fields are required
@@ -746,7 +755,7 @@
SMTPModule.__init__(self)
def getRetrySchedule(self):
- return self.retrySchedule #DOCDOC
+ return self.retrySchedule
def getConfigSyntax(self):
return { "Delivery/SMTP" :
@@ -845,7 +854,7 @@
SMTPModule.__init__(self)
def getRetrySchedule(self):
- return self.retrySchedule #DOCDOC
+ return self.retrySchedule
def getConfigSyntax(self):
return { "Delivery/SMTP-Via-Mixmaster" :
@@ -961,12 +970,7 @@
it is not plaintext ascii, and wrap it in some standard
boilerplate. Add a disclaimer if the message is not ascii.
- msg -- A (possibly decoded) message
- tag -- One of: a 20-byte decoding tag [if the message is encrypted
- or a reply]
- None [if the message is in plaintext]
- 'err' [if the message was invalid.]
- 'long' [if the message might be a zlib bomb'].
+ packet -- an instance of DeliveryPacket
Returns None on an invalid message."""
if packet.isError():
@@ -990,18 +994,5 @@
assert packet.isPlaintext()
junk_msg = ""
- if packet.isEncrypted():
- tag = "Decoding handle: %s\n"%packet.getAsciiTag()
- else:
- tag = ""
-
- contents = packet.getAsciiContents()
- if contents and contents[-1] != '\n':
- extra_newline = "\n"
- else:
- extra_newline = ""
-
- return """\
-%s======= TYPE III ANONYMOUS MESSAGE BEGINS ========
-%s%s%s======== TYPE III ANONYMOUS MESSAGE ENDS =========
-""" %(junk_msg, tag, contents, extra_newline)
+ encMsg = packet.getAsciiEncodedMessage()
+ return "%s%s"%(junk_msg, encMsg.pack())