deep-check-and-repair: improve results and their HTML representation

test_repairer.py: hush pyflakes: remove duplicate/shadowed function name, by using the earlier definition (which is identical)

hush pyflakes by removing unused imports

immutable repairer
This implements an immutable repairer by marrying a CiphertextDownloader to a CHKUploader.  It extends the IDownloadTarget interface so that the downloader can provide some metadata that the uploader requires.
The processing is incremental -- it uploads the first segments before it finishes downloading the whole file.  This is necessary so that you can repair large files without running out of RAM or using a temporary file on the repairer.
It requires only a verifycap, not a readcap.  That is: it doesn't need or use the decryption key, only the integrity check codes.
There are several tests marked TODO and several instances of XXX in the source code.  I intend to open tickets to document further improvements to functionality and testing, but the current version is probably good enough for Tahoe-1.3.0.

util: dictutil: add DictOfSets.union(key, values) and DictOfSets.update(otherdictofsets)

setup: update doc in setup.cfg

setup: Point setuptools at a directory on the allmydata.org test grid to find dependencies.
Don't include an unrouteable IP address in find_links (fixes #574).

immutable: separate tests of immutable upload/download from tests of immutable checking/repair

trivial: minor changes to in-line comments -- mark plaintext-hash-tree as obsolete

immutable: make the web display of upload results more human-friendly, like they were before my recent change to the meaning of the "sharemap"

immutable: fix edit-o in interfaces.py documentation introduced in recent patch

immutable: redefine the "sharemap" member of the upload results to be a map from shnum to set of serverids
It used to be a map from shnum to a string saying "placed this share on XYZ server".  The new definition is more in keeping with the "sharemap" object that results from immutable file checking and repair, and it is more useful to the repairer, which is a consumer of immutable upload results.

naming: finish renaming "CheckerResults" to "CheckResults"

storage.py : replace 4294967295 with 2**32-1: python does constant folding, I measured this statement as taking 50ns, versus the 400ns for the call to min(), or the 9us required for the 'assert not os.path.exists' syscall

storage.py: announce a maximum-immutable-share-size based upon a 'df' of the disk. Fixes #569, and this should be the last requirement for #346 (remove 12GiB filesize limit)

set bin/tahoe executable permissions and leave build_tahoe in sys.argv

setup: merge relaxation of the version of setuptools that we require at runtime with an indentation change

setup: remove custom Trial class inside our setup.py and use the setuptools_trial plugin

setup: we require pywin32 if building on Windows (plus some formatting and comment fixes)

fix bin/tahoe executable for Windows

use subprocess.call instead of os.execve in bin/tahoe

setup: attempt to remove the custom setuptools-ish logic in setup.py -- the result works on my Windows box but doesn't yield a working ./bin/tahoe on Windows, and hasn't been tested yet on other platforms

setup: integrate the bundled setuptools_trial plugin with Chris Galvan's patch to use that plugin

use_setuptools_trial.patch

setup: bundle setuptools_trial in misc/dependencies/

test_helper: hush pyflakes by avoiding use of 'uri' as a variable, since it shadows an import of the same name

immutable/checker: include a summary (with 'Healthy' or 'Not Healthy' and a count of shares) in the checker results

webapi/deep-manifest t=JSON: don't return the (large) manifest/SI/verifycap lists unless the operation has completed, to avoid the considerable CPU+memory cost of creating the JSON (for 330k dirnodes, it could take two minutes to generate 275MB of JSON). They must be paid eventually, but not on every poll

dirnode deep-traversal: remove use of Limiter, stick with strict depth-first-traversal, to reduce memory usage during very large (300k+ dirnode) traversals

immutable: add a monitor API to CiphertextDownloader with which to tell it to stop its work

naming: Rename a few things which I touched or changed in the recent patch to download-without-decrypting.
Rename "downloadable" to "target".
Rename "u" to "v" in FileDownloader.__init__().
Rename "_uri" to "_verifycap" in FileDownloader.
Rename "_downloadable" to "_target" in FileDownloader.
Rename "FileDownloader" to "CiphertextDownloader".

immutable: refactor download to do only download-and-decode, not decryption
FileDownloader takes a verify cap and produces ciphertext, instead of taking a read cap and producing plaintext.
FileDownloader does all integrity checking including the mandatory ciphertext hash tree and the optional ciphertext flat hash, rather than expecting its target to do some of that checking.
Rename immutable.download.Output to immutable.download.DecryptingOutput. An instance of DecryptingOutput can be passed to FileDownloader to use as the latter's target.  Text pushed to the DecryptingOutput is decrypted and then pushed to *its* target.
DecryptingOutput satisfies the IConsumer interface, and if its target also satisfies IConsumer, then it forwards and pause/unpause signals to its producer (which is the FileDownloader).
This patch also changes some logging code to use the new logging mixin class.
Check integrity of a segment and decrypt the segment one block-sized buffer at a time instead of copying the buffers together into one segment-sized buffer (reduces peak memory usage, I think, and is probably a tad faster/less CPU, depending on your encoding parameters).
Refactor FileDownloader so that processing of segments and of tail-segment share as much code is possible.
FileDownloader and FileNode take caps as instances of URI (Python objects), not as strings.

trivial: tiny changes to test code

immutable: Make more parts of download use logging mixins and know what their "parent msg id" is.

trivial: M-x whitespace-cleanup on src/immutable/download.py

immutable: ValidatedExtendedURIProxy computes and stores the tail data size as a convenience to its caller.
The "tail data size" is how many of the bytes of the tail segment are data (as opposed to padding).

immutable: define a new interface IImmutableFileURI and declare that CHKFileURI and LiteralFileURI provide it

util: log: allow empty msgs (because downloader is using the "format" alternative with no "msg" argument)

'tahoe cp -r', upon encountering a dangling symlink, would assert out.
This was somewhat sad; the assertion didn't say what path caused the
error, what went wrong.  So... silently skip over things that are
neither dirs nor files.

immutable: fix error in validation of ciphertext hash tree and add test for that code
pyflakes pointed out to me that I had committed some code that is untested, since it uses an undefined name.  This patch exercises that code -- the validation of the ciphertext hash tree -- by corrupting some of the share files in a very specific way, and also fixes the bug.

immutable: do not catch arbitrary exceptions/failures from the attempt to get a crypttext hash tree -- catch only ServerFailure, IntegrityCheckReject, LayoutInvalid, ShareVersionIncompatible, and DeadReferenceError
Once again I inserted a bug into the code, and once again it was hidden by something catching arbitrary exception/failure and assuming that it means the server failed to provide valid data.

download: make sure you really get all the crypttext hashes
We were not making sure that we really got all the crypttext hashes during download.  If a server were to return less than the complete set of crypttext hashes, then our subsequent attempt to verify the correctness of the ciphertext would fail.  (And it wouldn't be obvious without very careful debugging why it had failed.)
This patch makes it so that you keep trying to get ciphertext hashes until you have a full set or you run out of servers to ask.

util: deferredutil: undo my recent patch to use our own implementation of gatherResults
It seems to cause lots of failures on some builders.

util: deferredutil: implement our own gatherResults instead of using Twisted's
Because we want to maintain backwards compatibility to Twisted 2.4.0.

trivial: M-x whitespace-cleanup

util: deferredutil: add basic test for deferredutil.gatherResults
Also I checked and Twisted 2.4.0 supports .subFailure and the other parts of the API that we require.

trivial: fix redefinition of name "log" in imports (pyflakes)

immutable: refactor uploader to do just encoding-and-uploading, not encryption
This makes Uploader take an EncryptedUploadable object instead of an Uploadable object.  I also changed it to return a verify cap instead of a tuple of the bits of data that one finds in a verify cap.
This will facilitate hooking together an Uploader and a Downloader to make a Repairer.
Also move offloaded.py into src/allmydata/immutable/.

trivial: whitespace and docstring tidyups

storage.py: explain what this large and hard-to-recognize 4294967295 number is

rename "checker results" to "check results", because it is more parallel to "check-and-repair results"

immutable: tests: verifier doesn't always catch corrupted share hashes
Maybe it already got one of the corrupted hashes from a different server and it doesn't double-check that the hash from every server is correct.  Or another problem.  But in any case I'm marking this as TODO because an even better (more picky) verifier is less urgent than repairer.

immutable: fix the writing of share data size into share file in case the share file is used by a < v1.3.0 storage server
Brian noticed that the constant was wrong, and in fixing that I noticed that we should be saturating instead of modding.
This code would never matter unless a server downgraded or a share migrated from Tahoe >= v1.3.0 to Tahoe < v1.3.0.  Even in that case, this bug would never matter unless the share size were exactly 4,294,967,296 bytes long.
Brian, for good reason, wanted this to be spelled "2**32" instead of "4294967296", but I couldn't stand to see a couple of more Python bytecodes interpreted in the middle of a core, frequent operation on the server like immutable share creation.

trivial: whitespace cleanup

util: base32: require str-not-unicode inputs -- effectively rolls back [3306] and [3307]

trivial: fix a bunch of pyflakes complaints

cli: make startstop_node wait 40 seconds instead of 20 for a process to go away after we signalled it to go away, before emitting a warning
Because the unit tests on the VirtualZooko? buildslave failed when it took 31 seconds for a process to go away.
Perhaps getting warning message after only 5 seconds instead of 40 seconds is desirable, and we should change the unit tests and set this back to 5, but I don't know exactly how to change the unit tests. Perhaps match this particular warning message about the shutdown taking a while and allow the code under test to pass if the only stderr that it emits is this warning.

immutable: new checker and verifier
New checker and verifier use the new download class.  They are robust against various sorts of failures or corruption.  They return detailed results explaining what they learned about your immutable files.  Some grotesque sorts of corruption are not properly handled yet, and those ones are marked as TODO or commented-out in the unit tests.
There is also a repairer module in this patch with the beginnings of a repairer in it.  That repairer is mostly just the interface to the outside world -- the core operation of actually reconstructing the missing data blocks and uploading them is not in there yet.
This patch also refactors the unit tests in test_immutable so that the handling of each kind of corruption is reported as passing or failing separately, can be separately TODO'ified, etc.  The unit tests are also improved in various ways to require more of the code under test or to stop requiring unreasonable things of it.  :-)

trivial: fix inline comment in test code

immutable: handle another form of share corruption with LayoutInvalid exception instead of AssertionError

trivial: remove unused import (pyflakes)

immutable: skip the test of large files, because that is too hard on the host if it doesn't efficiently handle sparse files

immutable: raise a LayoutInvalid exception instead of an AssertionError if the share is corrupted so that the sharehashtree is the wrong size

immutable: stop reading past the end of the sharefile in the process of optimizing download -- Tahoe storage servers < 1.3.0 return an error if you read past the end of the share file

immutable: tidy up the notification of waiters for ReadBucketProxy

immutable: refactor downloader to be more reusable for checker/verifier/repairer (and better)

The code for validating the share hash tree and the block hash tree has been rewritten to make sure it handles all cases, to share metadata about the file (such as the share hash tree, block hash trees, and UEB) among different share downloads, and not to require hashes to be stored on the server unnecessarily, such as the roots of the block hash trees (not needed since they are also the leaves of the share hash tree), and the root of the share hash tree (not needed since it is also included in the UEB).  It also passes the latest tests including handling corrupted shares well.

ValidatedReadBucketProxy takes a share_hash_tree argument to its constructor, which is a reference to a share hash tree shared by all ValidatedReadBucketProxies for that immutable file download.

ValidatedReadBucketProxy requires the block_size and share_size to be provided in its constructor, and it then uses those to compute the offsets and lengths of blocks when it needs them, instead of reading those values out of the share.  The user of ValidatedReadBucketProxy therefore has to have first used a ValidatedExtendedURIProxy to compute those two values from the validated contents of the URI.  This is pleasingly simplifies safety analysis: the client knows which span of bytes corresponds to a given block from the validated URI data, rather than from the unvalidated data stored on the storage server.  It also simplifies unit testing of verifier/repairer, because now it doesn't care about the contents of the "share size" and "block size" fields in the share.  It does not relieve the need for share data v2 layout, because we still need to store and retrieve the offsets of the fields which come after the share data, therefore we still need to use share data v2 with its 8-byte fields if we want to store share data larger than about 2^32.

Specify which subset of the block hashes and share hashes you need while downloading a particular share.  In the future this will hopefully be used to fetch only a subset, for network efficiency, but currently all of them are fetched, regardless of which subset you specify.

ReadBucketProxy hides the question of whether it has "started" or not (sent a request to the server to get metadata) from its user.

Download is optimized to do as few roundtrips and as few requests as possible, hopefully speeding up download a bit.

util: add gatherResults which is a deferred-list-like thing that doesn't wrap failures in a FirstError

immutable: fix think-o in previous patch which caused all reads to return "", and also optimize by not opening the file when the answer is going to be ""

immutable: when storage server reads from immutable share, don't try to read past the end of the file (Python allocates space according to the amount of data requested, so if there is corruption and that number is huge it will do a huge memory allocation)

immutable: mark a failing download test as "todo", because I think it is revealing a limitation of the current downloader's handling of corrupted shares

docs: update install.html to recommend Python v2 instead of Python v2.5.2

trivial: remove unused import (pyflakes)

merge_install.patch

setup: new install doc -- doesn't require GNU make or a C++ compiler any more!

immutable: fix test for truncated reads of URI extension block size

immutable: further loosen the performance-regression test to allow up to 45 reads
This does raise the question of if there is any point to this test, since I apparently don't know what the answer *should* be, and whenever one of the buildbots fails then I redefine success.

But, I'm about to commit a bunch of patches to implement checker, verifier, and repairer as well as to refactor downloader, and I would really like to know if these patches *increase* the number of reads required even higher than it currently is.

trivial: another place where I accidentally committed a note-to-self about the lease fields in the server-side share file

immutable: fix detection of truncated shares to take into account the fieldsize -- either 4 or 8

immutable: raise LayoutInvalid instead of struct.error when a share is truncated
To fix this error from the Windows buildslave:

[ERROR]: allmydata.test.test_immutable.Test.test_download_from_only_3_remaining_shares

Traceback (most recent call last):
  File "C:\Documents and Settings\buildslave\windows-native-tahoe\windows\build\src\allmydata\immutable\download.py", line 135, in _bad
    raise NotEnoughSharesError("ran out of peers, last error was %s" % (f,))
allmydata.interfaces.NotEnoughSharesError: ran out of peers, last error was [Failure instance: Traceback: <class 'struct.error'>: unpack requires a string argument of length 4
c:\documents and settings\buildslave\windows-native-tahoe\windows\build\support\lib\site-packages\foolscap-0.3.2-py2.5.egg\foolscap\call.py:667:_done
c:\documents and settings\buildslave\windows-native-tahoe\windows\build\support\lib\site-packages\foolscap-0.3.2-py2.5.egg\foolscap\call.py:53:complete
c:\Python25\lib\site-packages\twisted\internet\defer.py:239:callback
c:\Python25\lib\site-packages\twisted\internet\defer.py:304:_startRunCallbacks
--- <exception caught here> ---
c:\Python25\lib\site-packages\twisted\internet\defer.py:317:_runCallbacks
C:\Documents and Settings\buildslave\windows-native-tahoe\windows\build\src\allmydata\immutable\layout.py:374:_got_length
C:\Python25\lib\struct.py:87:unpack
]
===============================================================================

immutable: whoops, it actually takes up to 39 reads sometimes to download a corrupted file

immutable: add more detailed tests of download, including testing the count of how many reads different sorts of downloads take

trivial: a few improvements to in-line doc and code, and renaming of test/test_immutable_checker.py to test/test_immutable.py
That file currently tests checker and verifier and repairer, and will soon also test downloader.

immutable: fix name change from BadOrMissingShareHash to BadOrMissingHash
One of the instances of the name accidentally didn't get changed, and pyflakes noticed.  The new downloader/checker/verifier/repairer unit tests would also have noticed, but those tests haven't been rolled into a patch and applied to this repo yet...

trivial: remove unused import -- thanks, pyflakes

immutable: download.py: Raise the appropriate type of exception to indicate the cause of failure, e.g. BadOrMissingHash, ServerFailure, IntegrityCheckReject (which is a supertype of BadOrMissingHash).  This helps users (such as verifier/repairer) catch certain classes of reasons for "why did this download not work".  The tests of verifier/repairer test this code and rely on this code.

immutable: ReadBucketProxy defines classes of exception: LayoutInvalid and its two subtypes RidiculouslyLargeURIExtensionBlock and ShareVersionIncompatible.  This helps users (such as verifier/repairer) catch certain classes of reasons for "why did this download not work".  This code gets exercised by the verifier/repairer unit tests, which corrupt the shares on disk in order to trigger problems like these.

immutable: ValidatedExtendedURIProxy computes and stores block_size and share_size for the convenience of its users

remove_sumo_install.patch

doc: remove notes to self that I accidentally included in a recent patch

docs: remove caveat about Nevow incompatibility with Python 2.6 since the latest version of Nevow has fixed it

immutable: make the test of large files more likely to work by requesting to allocate space for only one huge share, not three

trivial: "M-x whitespace-cleanup", and also remove an unused variable

immutable: storage servers accept any size shares now
Nathan Wilcox observed that the storage server can rely on the size of the share file combined with the count of leases to unambiguously identify the location of the leases.  This means that it can hold any size share data, even though the field nominally used to hold the size of the share data is only 32 bits wide.

With this patch, the storage server still writes the "size of the share data" field (just in case the server gets downgraded to an earlier version which requires that field, or the share file gets moved to another server which is of an earlier vintage), but it doesn't use it.  Also, with this patch, the server no longer rejects requests to write shares which are >= 2^32 bytes in size, and it no longer rejects attempts to read such shares.

This fixes http://allmydata.org/trac/tahoe/ticket/346 (increase share-size field to 8 bytes, remove 12GiB filesize limit), although there remains open a question of how clients know that a given server can handle large shares (by using the new versioning scheme, probably).

Note that share size is also limited by another factor -- how big of a file we can store on the local filesystem on the server.  Currently allmydata.com typically uses ext3 and I think we typically have block size = 4 KiB, which means that the largest file is about 2 TiB.  Also, the hard drives themselves are only 1 TB, so the largest share is definitely slightly less than 1 TB, which means (when K == 3), the largest file is less than 3 TB.

This patch also refactors the creation of new sharefiles so that only a single fopen() is used.

This patch also helps with the unit-testing of repairer, since formerly it was unclear what repairer should expect to find if the "share data size" field was corrupted (some corruptions would have no effect, others would cause failure to download).  Now it is clear that repairer is not required to notice if this field is corrupted since it has no effect on download.  :-)

trivial: "M-x whitespace-cleanup" on immutable/layout.py

trivial: remove unused import -- thanks, pyflakes

rrefutil: generically wrap any errback from callRemote() in a ServerFailure instance
This facilitates client code to easily catch ServerFailures without also catching exceptions arising from client-side code.
See also:
http://foolscap.lothar.com/trac/ticket/105 # make it easy to distinguish server-side failures/exceptions from client-side

immutable: more detailed tests for checker/verifier/repairer
There are a lot of different ways that a share could be corrupted, or that attempting to download it might fail.  These tests attempt to exercise many of those ways and require the checker/verifier/repairer to handle each kind of failure well.

docs: add note about non-ascii chars in cli to NEWS

cli: make startstop_node wait 20 seconds instead of 5 for a process to go away after we signalled it to go away
Because the unit tests on the VirtualZooko buildslave failed when it took 16 seconds for a process to go away.
Perhaps getting notification after only 5 seconds instead of 20 seconds is desirable, and we should change the unit tests and set this back to 5, but I don't know exactly how to change the unit tests.  Perhaps match this particular warning message about the shutdown taking a while and allow the code under test to pass if the only stderr that it emits is this warning.

docs: editing changes and updated news in known_issues.txt