[Tahoe-dev] conceptual complexity reified in an API

[zooko at zooko.com]

One way to think about the conceptual complexity mentioned in item #4 of my
previous message [1] is to write out an API, such as for an XML-RPC interface
(trac ticket #48 [2]), or a command-line interface (trac ticket #53 [3]). 

If you have a Merkle Tree covering plaintext, then you can offer an API
something like this [4]:

class IDownloadTarget(Interface):
    def open():
        """Called before any calls to write() or close()."""
    def write(data):
        """Output some data to the target.  This will be called only after the 
        data has been checked for integrity, so you may rely upon the 
        correctness of the data."""
    def close():
        """Inform the target that there is no more data to be written."""
    def fail():
        """fail() is called to indicate that the download has failed. No
        further methods will be invoked on the IDownloadTarget after fail()."""

def download(uri, target):
    """ @param target: provides IDownloadTarget """


If you also have a hash covering the same plaintext, then the semantics of
write() and close() must be amended:

    def write(data):
        """Output some data to the target.  This will be called only after the 
        data has been checked for integrity, so you may rely upon the 
        correctness of the data.  However, there may be a bug in our integrity 
        checking code, in which case the call to close() will inform you that 
        such a bug was detected."""
    def close(success):
        """Inform the target that there is no more data to be written.  If 
        success is True, then the extra integrity check at the end passed, 
        showing that there was no bug in the incremental integrity check that 
        was already performed.  If success if False, then there must have been 
        bug in the incremental integrity check, and the data earlier passed to 
        write() was not actually correct."""


An important thing to consider is: what will the programmer do to handle the
added failure mode in the second interface?

Regards,

Zooko

[1] http://allmydata.org/pipermail/tahoe-dev/2007-May/000020.html
[2] http://allmydata.org/trac/tahoe/ticket/48
[3] http://allmydata.org/trac/tahoe/ticket/53
[4] http://allmydata.org/trac/tahoe/browser/src/allmydata/interfaces.py