Miscellaneous documentation, test, and code formatting tweaks.

Prevent mutable objects from being retrieved from an immutable directory, and associated forward-compatibility improvements.

test_runner: cleanup, refactor common code into a non-executable method

Having both test_node() and test_client() (one of which calls the other) felt
confusing to me, so I changed it to have test_node(), test_client(), and a
common do_create() helper method.

scripts/runner.py: simplify David-Sarah's clever grouped-commands usage trick

tahoe backup: skip all symlinks, with warning. Fixes #850, addresses #641.

NEWS: update with all recent user-visible changes

"tahoe backup": fix --exclude-vcs docs to include Git

docs: fix references to --no-storage, explanation of [storage] section

docs: further CREDITS level-ups for Nils, Kevan, David-Sarah

Patch to accept t=set-children as well as t=set_children

Fix boodlegrid use of set_children

ftpd: clearer error message if Twisted needs a patch (by Nils Durner)

Add 'docs/performance.txt', which (for the moment) describes mutable file performance issues

docs: more CREDITS for François, Kevan, and David-Sarah

tahoe_backup.py: display warnings on errors instead of stopping the whole backup. Fix #729.

This patch displays a warning to the user in two cases:

  1. When special files like symlinks, fifos, devices, etc. are found in the
     local source.

  2. If files or directories are not readables by the user running the 'tahoe
     backup' command.

In verbose mode, the number of skipped files and directories is printed at the
end of the backup.

Exit status returned by 'tahoe backup':

  - 0 everything went fine
  - 1 the backup failed
  - 2 files were skipped during the backup

Warn about test failures due to setting FLOG* env vars

Message saying that we couldn't find bin/tahoe should say where we looked

Change running.html to describe 'tahoe run'

cli: merge the better version of David-Sarah's split-usage-and-help patch with the earlier version that I mistakenly committed

Split tahoe --help options into groups.

cli: split usage strings into groups (patch by David-Sarah Hopwood)

Add create-node CLI command, and make create-client equivalent to create-node --no-storage (fixes #760)

Remove replace= parameter to mkdir-immutable and mkdir-with-children

contrib/fuse/runtests.py: Fix #888, configure settings in tahoe.cfg and don't treat warnings as failure

Fix a few bitrotten pieces in the FUSE test script.  It now configures tahoe
node settings by editing tahoe.cfg which is the new supported method.

It alos tolerate warnings issued by the mount command, the cause of these
warnings is the same as in #876 (contrib/fuse/runtests.py doesn't tolerate
deprecations warnings).

Fix webapi t=mkdir with multpart/form-data, as on the Welcome page. Closes #919.

tahoe_add_alias.py: minor refactoring

test_dirnode.py: reduce scope of a Client instance, suggested by Kevan.

test_provisioning: STAN is not always a list. Fix by David-Sarah Hopwood.

web/directory.py mkdir-immutable: hush pyflakes, add TODO for #903 behavior

hush pyflakes-0.4.0 warnings: slightly less-trivial fixes. Closes #900.

This includes one fix (in test_web) which was testing the wrong thing.

hush pyflakes-0.4.0 warnings: remove trivial unused variables. For #900.

tahoe add-alias/create-alias: don't corrupt non-newline-terminated alias
file. Closes #741.

change docs and --help to use "grid" instead of "virtual drive": closes #892.

Thanks to David-Sarah Hopwood for the patch.

backupdb.txt: fix ST_CTIME reference

client.py: fix/update comments on KeyGenerator

Clean up log.err calls, for one of the issues in #889.

allmydata.util.log.err() either takes a Failure as the first positional
argument, or takes no positional arguments and must be invoked in an
exception handler. Fixed its signature to match both foolscap.logging.log.err
and twisted.python.log.err . Included a brief unit test.

tidy up DeadReferenceError handling, ignore them in add_lease calls

Stop checking separately for ConnectionDone/ConnectionLost, since those have
been folded into DeadReferenceError since foolscap-0.3.1 . Write
rrefutil.trap_deadref() in terms of rrefutil.trap_and_discard() to improve
code coverage.

NEWS: improve "tahoe backup" notes, mention first-backup-after-upgrade duration

Thanks to Francois Deppierraz for the suggestion.

test_repairer: add (commented-out) test_each_byte, to see exactly what the
Verifier misses

The results (described in #819) match our expectations: it misses corruption
in unused share fields and in most container fields (which are only visible
to the storage server, not the client). 1265 bytes of a 2753 byte
share (hosting a 56-byte file with an artifically small segment size) are
unused, mostly in the unused tail of the overallocated UEB space (765 bytes),
and the allocated-but-unwritten plaintext_hash_tree (480 bytes).

repairer: fix some wrong offsets in the randomized verifier tests, debugged by Brian
fixes #819

test_repairer: fix colliding basedir names, which caused test inconsistencies

repairer: add deterministic test for #819, mark as TODO

contrib/fuse/runtests.py: Tolerate the tahoe CLI returning deprecation warnings

Depending on the versions of external libraries such as Twisted of Foolscap,
the tahoe CLI can display deprecation warnings on stdout.  The tests should
not interpret those warnings as a failure if the node is in fact correctly
started.

See http://allmydata.org/trac/tahoe/ticket/859 for an example of deprecation
warnings.

fixes #876

contrib: fix fuse_impl_c to use new Python API
original patch by Thomas Delaet, fixed by François, reviewed by Brian, committed by me

docs: CREDITS: add David-Sarah to the CREDITS file

mutable/publish: don't loop() right away upon DeadReferenceError. Closes #877

The bug was that a disconnected server could cause us to re-enter the initial
loop() call, sending multiple queries to a single server, provoking an
incorrect UCWE. To fix it, stall the loop() with an eventual.fireEventually()

immutable/checker.py: oops, forgot some imports. Also hush pyflakes.

mutable repair: return successful=False when numshares<k (thus repair fails),
instead of weird errors. Closes #874 and #786.

Previously, if the file had 0 shares, this would raise TypeError as it tried
to call download_version(None). If the file had some shares but fewer than
'k', it would incorrectly raise MustForceRepairError.

Added get_successful() to the IRepairResults API, to give repair() a place to
report non-code-bug problems like this.

node.py/interfaces.py: minor docs fixes

NEWS: fix 1.4.1 announcement w.r.t. add-lease behavior in older releases

checker: don't let failures in add-lease affect checker results. Closes #875.

Mutable servermap updates and the immutable checker, when run with
add_lease=True, send both the do-you-have-block and add-lease commands in
parallel, to avoid an extra round trip time. Many older servers have problems
with add-lease and raise various exceptions, which don't generally matter.
The client-side code was catching+ignoring some of them, but unrecognized
exceptions were passed through to the DYHB code, concealing the DYHB results
from the checker, making it think the server had no shares.

The fix is to separate the code paths. Both commands are sent at the same
time, but the errback path from add-lease is handled separately. Known
exceptions are ignored, the others (both unknown-remote and all-local) are
logged (log.WEIRD, which will trigger an Incident), but neither will affect
the DYHB results.

The add-lease message is sent first, and we know that the server handles them
synchronously. So when the checker is done, we can be sure that all the
add-lease messages have been retired. This makes life easier for unit tests.

test_cli: verify fix for "tahoe get" not creating empty file on error (#121)

addendum to "Fix 'tahoe ls' on files (#771)"

tahoe_ls.py: tolerate missing metadata
web/filenode.py: minor cleanups
test_cli.py: test 'tahoe ls FILECAP'

Fix 'tahoe ls' on files (#771). Patch adapted from Kevan Carstensen.

web/filenode.py: also serve edge metadata when using t=json on a
                 DIRCAP/childname object.
tahoe_ls.py: list file objects as if we were listing one-entry directories.
             Show edge metadata if we have it, which will be true when doing
             'tahoe ls DIRCAP/filename' and false when doing 'tahoe ls
             FILECAP'

tahoe_get: don't create the output file on error. Closes #121.

webapi: don't accept zero-length childnames during traversal. Closes #358, #676.

This forbids operations that would implicitly create a directory with a
zero-length (empty string) name, like what you'd get if you did "tahoe put
local /oops/blah" (#358) or "POST /uri/CAP//?t=mkdir" (#676). The error
message is fairly friendly too.

Also added code to "tahoe put" to catch this error beforehand and suggest the
correct syntax (i.e. without the leading slash).

CLI: send 'Accept:' header to ask for text/plain tracebacks. Closes #646.

The webapi has been looking for an Accept header since 1.4.0, but it treats a
missing header as equal to */* (to honor RFC2616). This change finally
modifies our CLI tools to ask for "text/plain, application/octet-stream",
which seems roughly correct (we either want a plain-text traceback or error
message, or an uninterpreted chunk of binary data to save to disk). Some day
we'll figure out how JSON fits into this scheme.

Makefile: upload-tarballs: switch from xfer-client to flappclient, closes #350

I've also set up a new flappserver on source@allmydata.org to receive the
tarballs. We still need to replace the gutsy buildslave (which is where the
tarballs used to be generated+uploaded) and give it the new FURL.

misc/ringsim.py: make it deterministic, more detail about grid-is-full behavior

misc/ringsim.py: tool to discuss #302

docs: fix helper.txt to describe new config style

docs/stats.txt: add TOC, notes about controlling gatherer's listening port

Thanks to Jody Harris for the suggestions.

Add docs/stats.py, explaining Tahoe stats, the gatherer, and the munin plugins.

more #859: avoid deprecation warning for unit tests too, hush pyflakes

* factor maybe-import-sha logic into util.hashutil

use hashlib module if available, thus avoiding a DeprecationWarning for importing the old sha module; fixes #859

docs: reflow architecture.txt to 78-char lines

docs: update the about.html a little

docs: remove obsolete doc file "codemap.txt"
I started to update this to reflect the current codebase, but then I thought (a) nobody seemed to notice that it hasn't been updated since December 2007, and (b) it will just bit-rot again, so I'm removing it.

mutable/retrieve.py: stop reaching into private MutableFileNode attributes

mutable/servermap.py: stop reaching into private MutableFileNode attributes

mutable/servermap.py: oops, query N+e servers in MODE_WRITE, not k+e

under normal conditions, this wouldn't cause any problems, but if the shares
are really sparse (perhaps because new servers were added), then
file-modifies might stop looking too early and leave old shares in place

control.py: fix speedtest: use download_best_version (not read) on mutable nodes

FTP-and-SFTP.txt: fix ssh-keygen pointer

setup: ignore _darcs in the "test-clean" test and make the "clean" step remove all .egg's in the root dir

remove MutableFileNode.download(), prefer download_best_version() instead

Simplify immutable download API: use just filenode.read(consumer, offset, size)

* remove Downloader.download_to_data/download_to_filename/download_to_filehandle
* remove download.Data/FileName/FileHandle targets
* remove filenode.download/download_to_data/download_to_filename methods
* leave Downloader.download (the whole Downloader will go away eventually)
* add util.consumer.MemoryConsumer/download_to_data, for convenience
  (this is mostly used by unit tests, but it gets used by enough non-test
   code to warrant putting it in allmydata.util)
* update tests
* removes about 180 lines of code. Yay negative code days!

Overall plan is to rewrite immutable/download.py and leave filenode.read() as
the sole read-side API.

server.py: undo my bogus 'correction' of David-Sarah's comment fix

and move it to a better line

Implement more coherent behavior when copying with dircaps/filecaps (closes #761). Patch by Kevan Carstensen.

storage.py: update comment

storage server: detect disk space usage on Windows too (fixes #637)

make status of finished operations consistently "Finished"

NEWS: update with all user-visible changes since the last release

update "tahoe backup" docs, and webapi.txt's mkdir-with-children

Add dirnodes to backupdb and "tahoe backup", closes #606.

* backups now share dirnodes with any previous backup, in any location,
  so renames and moves are handled very efficiently
* "tahoe backup" no longer bothers reading the previous snapshot
* if you switch grids, you should delete ~/.tahoe/private/backupdb.sqlite,
  to force new uploads of all files and directories

webapi: fix t=check for DIR2-LIT (i.e. empty immutable directories)

PipelineError: fix str() on python2.4 . Closes #842.

test_uri.py: s/NewDirnode/Dirnode/ , now that they aren't "new" anymore

interface name cleanups: IFileNode, IImmutableFileNode, IMutableFileNode

The proper hierarchy is:
 IFilesystemNode
 +IFileNode
 ++IMutableFileNode
 ++IImmutableFileNode
 +IDirectoryNode

Also expand test_client.py (NodeMaker) to hit all IFilesystemNode types.

class name cleanups: s/FileNode/ImmutableFileNode/

also fix test/bench_dirnode.py for recent dirnode changes

Use DIR-IMM and t=mkdir-immutable for "tahoe backup", for #828

web/directory.py: use "DIR-IMM" to describe immutable directories, not DIR-RO

web/info.py: hush pyflakes

make get_size/get_current_size consistent for all IFilesystemNode classes

* stop caching most_recent_size in dirnode, rely upon backing filenode for it
* start caching most_recent_size in MutableFileNode
* return None when you don't know, not "?"
* only render None as "?" in the web "more info" page
* add get_size/get_current_size to UnknownNode

ImmutableDirectoryURIVerifier: fix verifycap handling

Add t=mkdir-immutable to the webapi. Closes #607.

* change t=mkdir-with-children to not use multipart/form encoding. Instead,
  the request body is all JSON. t=mkdir-immutable uses this format too.
* make nodemaker.create_immutable_dirnode() get convergence from SecretHolder,
  but let callers override it
* raise NotDeepImmutableError instead of using assert()
* add mutable= argument to DirectoryNode.create_subdirectory(), default True

move convergence secret into SecretHolder, next to lease secret

nodemaker: implement immutable directories (internal interface), for #607

* nodemaker.create_from_cap() now handles DIR2-CHK and DIR2-LIT
* client.create_immutable_dirnode() is used to create them
* no webapi yet

stop using IURI()/etc as an adapter

clean up uri-vs-cap terminology, emphasize cap instances instead of URI strings

 * "cap" means a python instance which encapsulates a filecap/dircap (uri.py)
 * "uri" means a string with a "URI:" prefix
 * FileNode instances are created with (and retain) a cap instance, and
   generate uri strings on demand
 * .get_cap/get_readcap/get_verifycap/get_repaircap return cap instances
 * .get_uri/get_readonly_uri return uri strings

* add filenode.download_to_filename() for control.py, should find a better way
* use MutableFileNode.init_from_cap, not .init_from_uri
* directory URI instances: use get_filenode_cap, not get_filenode_uri
* update/cleanup bench_dirnode.py to match, add Makefile target to run it

add parser for immutable directory caps: DIR2-CHK, DIR2-LIT, DIR2-CHK-Verifier