[minion-cvs] Add heavily modified patch from Brian Warner for status...

[nickm@seul.org (Nick Mathewson)]

Update of /home/minion/cvsroot/src/minion/doc
In directory moria.mit.edu:/tmp/cvs-serv7396/doc

Added Files:
	statusfd.txt 
Log Message:
Add heavily modified patch from Brian Warner for status-fd and packet-counting; refactor argument parsing; add unit tests

--- NEW FILE: statusfd.txt ---

The following messages are emitted on whatever file descriptor 'N' you pass
(by number) into the --status-fd=N argument. They are designed to be machine
parseable. Each message, once made available in an official Mixminion
release, will not be removed or shortened. New arguments may be added, so
parse these with regular expressions which match from the left. All
status-fd messages are prefixed with the string '[MIXMINION:] ', which may
help distinguish them if for some reason you are forced to intermingle them
with stderr.

These are intended for use by front-end programs. Each message is listed
with a python-style regular expression that can be used to parse the line.

COUNT_PACKETS  <surbcount>

 r'COUNT_PACKETS (\d+)'

 Emitted by the 'count-packets' command, which determines the number of
 packets that will be needed to encode a given message.

GENERATED_SURB <surbid>

 r'GENERATED_SURB (\S+)'

 Emitted in the 'generate-surb' and 'generate-surbs' commands, one per SURB
 generated. <surbid> is the SURB's base64-encoded "decoding handle", which
 is only available to the creator of the SURB (at generation time) and the
 final recipient of the reply message, both of which are usually the same
 person. It is not visible in the finished SURB, and the user who sends a
 message through this SURB will not be able to see it.

 The decoding handle will eventually be visible in the final delivered
 message. When that last message is delivered in ascii-armored form, it will
 be the value of the "Decoding-Handle:" header.

INSPECT_SURB <surbdigest> <expiretime> <used>

 r'INSPECT_SURB (\w+) (\d+) ([01])'

 Emitted in the 'inspect-surb' command, one per SURB inspected. <surbdigest>
 is the (hex) hash of the SURB itself, useable as an identifying handle.
 Unlike the decoding handle, this digest is for use by the sender of the
 reply message, and is visible by anyone who holds the SURB. <expiretime> is
 the timestamp (seconds since the epoch) of the last time at which the SURB
 is guaranteed to be useable. After this time, one or more of the component
 remailer keys may have expired, rendering the SURB incapable of reaching
 its final destination. <used> is 1 if this instance of mixminion remembers
 sending a message with this SURB (thus rendering it unusable, as SURBs are
 Single-Use), otherwise it is 0.