API (was: "FORWARD" module)

[Zooko <zooko@zooko.com>]

This message contains some advocacy about design, and it also contains a 
suggested API which is hopefully interesting and useful regardless of your 
opinion about the design of the module interfaces.


FWIW, I remain convinced that the "mix core"-specific type ("FORWARD" and 
"DROP") should be conveyed separately from the app-level extension type (the 
arbitrary type field).

In particular, I suggest that the mix core spec has only a few types: FORWARD, 
DROP, APPLICATION, and perhaps INFO and PING and that there is a separate layer 
which encodes arbitrary-length strings as "extension type".  The primary value 
of this approach is that the Mix Core stuff which can affect privacy and which 
application programmers touch is separate in specification and in implementation 
from the extensible part.  (Although I fully agree that v1.0 must specify and 
implement SMTP and other extensions!)

Another feature of this design is that the application programmer can have a 
human-readable, arbitrary-length type while the Mix Core can have a fixed-length 
(and short) type.

While re-thinking this issue just now I wrote down a prospective API for 
programmers who use MixMinion as an anonymous message layer.  (Python/JavaDoc 
syntax.)

------- proposed API (begin)

# To send a message, invoke `send_msg()':
send_msg(recipaddr, type, msg)
    """
    @param recipaddr the entire chain of addresses needed to send through the mix
    @param type string (8-bit clean, arbitrary length) (see 
        `http://mixminion.org/apptypes.html' for registry of known strings)
    @param msg string (8-bit clean, arbitrary length)
    """

# To send a message, define a receive handler which matches the following 
# interface.  Your receive handler will get invoked whenever a message arrives 
# for you.
recv_handler(surb, intype, inmsg)
    """
    @param surb a Single-Use Reply Block useful for replying to sender
    @param intype string
    @param inmsg string
    """

------- proposed API (end)


I would *not* prefer this API:

send_msg(recipaddr, type, msg)
    """
    @param recipaddr the entire chain of addresses needed to send through the mix
    @param type 2-byte type (see `http://mixminion.org/coretypes.html' for Mix 
        Core reserved numbers and `http://mixminion.org/apptypes.html' for 
        registry of known extension numbers)
    @param msg a string (8-bit clean, arbitrary length)
    """

recv_handler(surb, intype, inmsg)
    """
    @param surb a Single-Use Reply Block useful for replying to sender
    @param type 2-byte type
    @param msg string
    """


Hm.  In fact, now that I think about it I would like for the standard extension 
types (MULTIPART, GZIP, SMTP) to be MIME.  The MIME design isn't exactly how 
I would have designed it, but it is a standard and it is widely understood and 
implemented.

Regards,

Zooko