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

wui: s/TahoeLAFS/Tahoe-LAFS/

tests: bump up the timeout on test_repairer to see if 120 seconds was too short for François's ARM box to do the test even when it was doing it right.

dirnode.pack_children(): add deep_immutable= argument

This will be used by DIR2:CHK to enforce the deep-immutability requirement.

webapi: use t=mkdir-with-children instead of a children= arg to t=mkdir .

This is safer: in the earlier API, an old webapi server would silently ignore
the initial children, and clients trying to set them would have to fetch the
newly-created directory to discover the incompatibility. In the new API,
clients using t=mkdir-with-children against an old webapi server will get a
clear error.

nodemaker.create_new_mutable_directory: pack_children() in initial_contents=
instead of creating an empty file and then adding the children later.

This should speed up mkdir(initial_children) considerably, removing two
roundtrips and an entire read-modify-write cycle, probably bringing it down
to a single roundtrip. A quick test (against the volunteergrid) suggests a
30% speedup.

test_dirnode: add new tests to enforce the restrictions that interfaces.py
claims for create_new_mutable_directory(): no UnknownNodes, metadata dicts

test_dirnode.py: add tests of initial_children= args to client.create_dirnode
and nodemaker.create_new_mutable_directory

update many dirnode interfaces to accept dict-of-nodes instead of dict-of-caps

interfaces.py: define INodeMaker, document argument values, change
               create_new_mutable_directory() to take dict-of-nodes. Change
               dirnode.set_nodes() and dirnode.create_subdirectory() too.
nodemaker.py: use INodeMaker, update create_new_mutable_directory()
client.py: have create_dirnode() delegate initial_children= to nodemaker
dirnode.py (Adder): take dict-of-nodes instead of list-of-nodes, which
                    updates set_nodes() and create_subdirectory()
web/common.py (convert_initial_children_json): create dict-of-nodes
web/directory.py: same
web/unlinked.py: same
test_dirnode.py: update tests to match

dirnode.py: move pack_children() out to a function, for eventual use by others

move dirnode.CachingDict to dictutil.AuxValueDict, generalize method names,
improve tests. Let dirnode _pack_children accept either dict or AuxValueDict.

test/common.py: update FakeMutableFileNode to new contents= callable scheme

The initial_children= argument to nodemaker.create_new_mutable_directory is
now enabled.

client.create_mutable_file(contents=) now accepts a callable, which is
invoked with the new MutableFileNode and is supposed to return the initial
contents. This can be used by e.g. a new dirnode which needs the filenode's
writekey to encrypt its initial children.

create_mutable_file() still accepts a bytestring too, or None for an empty
file.

webapi: t=mkdir now accepts initial children, using the same JSON that t=json
emits.

client.create_dirnode(initial_children=) now works.

replace dirnode.create_empty_directory() with create_subdirectory(), which
takes an initial_children= argument

dirnode.set_children: change return value: fire with self instead of None

dirnode.set_nodes: change return value: fire with self instead of None

dirnode.set_children: take a dict, not a list

dirnode.set_uri/set_children: change signature to take writecap+readcap
instead of a single cap. The webapi t=set_children call benefits too.

replace Client.create_empty_dirnode() with create_dirnode(), in anticipation
of adding initial_children= argument.

Includes stubbed-out initial_children= support.

test_web.py: use a less-fake client, making test harness smaller

webapi.txt: document t=set_children, other small edits

Verifier: check the full cryptext-hash tree on each share. Removed .todos
from the last few test_repairer tests that were waiting on this.

Verifier: check the full block-hash-tree on each share

Removed the .todo from two test_repairer tests that check this. The only
remaining .todos are on the three crypttext-hash-tree tests.

Verifier: check the full share-hash chain on each share

Removed the .todo from two test_repairer tests that check this.

test_repairer: rename Verifier test cases to be more precise and less verbose

immutable/checker.py: rearrange code a little bit, make it easier to follow

test/common.py: wrap docstrings to 80cols so I can read them more easily

immutable/download.py: wrap to 80cols, no functional changes

CHK-hashes.svg: cross out plaintext hashes, since we don't include
them (until we finish #453)

docs: a few licensing clarifications requested by Ubuntu

setup: remove binary WinFUSE modules
I would prefer to have just source code, or indications of what 3rd-party packages are required, under revision control, and have the build process generate o
r acquire the binaries as needed.  Also, having these in our release tarballs is interfering with getting Tahoe-LAFS uploaded into Ubuntu Karmic.  (Technicall
y, they would accept binary modules as long as they came with the accompanying source so that they could satisfy their obligations under GPL2+ and TGPPL1+, bu
t it is easier for now to remove the binaries from the source tree.)
In this case, the binaries are from the tahoe-w32-client project: http://allmydata.org/trac/tahoe-w32-client , from which you can also get the source.

setup: remove binary _fusemodule.so 's
I would prefer to have just source code, or indications of what 3rd-party packages are required, under revision control, and have the build process generate or acquire the binaries as needed.  Also, having these in our release tarballs is interfering with getting Tahoe-LAFS uploaded into Ubuntu Karmic.  (Technically, they would accept binary modules as long as they came with the accompanying source so that they could satisfy their obligations under GPL2+ and TGPPL1+, but it is easier for now to remove the binaries from the source tree.)
In this case, these modules come from the MacFUSE project: http://code.google.com/p/macfuse/

doc: add a copy of LGPL2 for documentation purposes for ubuntu

setup: remove a convenience copy of figleaf, to ease inclusion into Ubuntu Karmic Koala
We need to carefully document the licence of figleaf in order to get Tahoe-LAFS into Ubuntu Karmic Koala.  However, figleaf isn't really a part of Tahoe-LAFS per se -- this is just a "convenience copy" of a development tool.  The quickest way to make Tahoe-LAFS acceptable for Karmic then, is to remove figleaf from the Tahoe-LAFS tarball itself.  People who want to run figleaf on Tahoe-LAFS (as everyone should want) can install figleaf themselves.  I haven't tested this -- there may be incompatibilities between upstream figleaf and the copy that we had here...

setup: shebang for misc/build-deb.py to fail quickly
Without this patch, when I ran "chmod +x ./misc/build-deb.py && ./misc/build-deb.py" then it hung indefinitely.  (I wonder what it was doing.)

docs: Shawn Willden grants permission for his contributions under GPL2+|TGPPL1+

docs: Csaba Henk granted permission to license fuse.py under the same terms as Tahoe-LAFS itself

setup: mark setup.py as having utf-8 encoding in it

doc: licensing cleanups
Use nice utf-8 © instead of "(c)". Remove licensing statements on utility modules that have been assigned to allmydata.com by their original authors. (Nattraverso was not assigned to allmydata.com -- it was LGPL'ed -- but I checked and src/allmydata/util/iputil.py was completely rewritten and doesn't contain any line of code from nattraverso.)  Add notes to misc/debian/copyright about licensing on files that aren't just allmydata.com-licensed.

build-deb.py: run darcsver early, otherwise we get the wrong version later on

new approach for debian packaging, sharing pieces across distributions. Still experimental, still only works for sid.

new experimental deb-packaging rules. Only works for sid so far.

setup.py: read _version.py and pass to setup(version=), so more commands work
like "setup.py --version" and "setup.py --fullname"

test/check_speed.py: fix shbang line

setup: remove bundled version of darcsver-1.2.1
That version of darcsver emits a scary error message when the darcs executable or the _darcs subdirectory is not found.
This error is hidden (unless the --loud option is passed) in darcsver >= 1.3.1.
Fixes #788.

de-Service-ify Helper, pass in storage_broker and secret_holder directly.
This makes it more obvious that the Helper currently generates leases with
the Helper's own secrets, rather than getting values from the client, which
is arguably a bug that will likely be resolved with the Accounting project.

immutable.Downloader: pass StorageBroker to constructor, stop being a Service
child of the client, access with client.downloader instead of
client.getServiceNamed("downloader"). The single "Downloader" instance is
scheduled for demolition anyways, to be replaced by individual
filenode.download calls.

tests: double the timeout on test_runner.RunNode.test_introducer since feisty hit a timeout
I'm not sure if this is an actual timing issue (feisty is running on an overloaded VM if I recall correctly), or it there is a deeper bug.

stop making History be a Service, it wasn't necessary

Overhaul IFilesystemNode handling, to simplify tests and use POLA internally.

* stop using IURI as an adapter
* pass cap strings around instead of URI instances
* move filenode/dirnode creation duties from Client to new NodeMaker class
* move other Client duties to KeyGenerator, SecretHolder, History classes
* stop passing Client reference to dirnode/filenode constructors
  - pass less-powerful references instead, like StorageBroker or Uploader
* always create DirectoryNodes by wrapping a filenode (mutable for now)
* remove some specialized mock classes from unit tests

Detailed list of changes (done one at a time, then merged together)

always pass a string to create_node_from_uri(), not an IURI instance
always pass a string to IFilesystemNode constructors, not an IURI instance
stop using IURI() as an adapter, switch on cap prefix in create_node_from_uri()
client.py: move SecretHolder code out to a separate class
test_web.py: hush pyflakes
client.py: move NodeMaker functionality out into a separate object
LiteralFileNode: stop storing a Client reference
immutable Checker: remove Client reference, it only needs a SecretHolder
immutable Upload: remove Client reference, leave SecretHolder and StorageBroker
immutable Repairer: replace Client reference with StorageBroker and SecretHolder
immutable FileNode: remove Client reference
mutable.Publish: stop passing Client
mutable.ServermapUpdater: get StorageBroker in constructor, not by peeking into Client reference
MutableChecker: reference StorageBroker and History directly, not through Client
mutable.FileNode: removed unused indirection to checker classes
mutable.FileNode: remove Client reference
client.py: move RSA key generation into a separate class, so it can be passed to the nodemaker
move create_mutable_file() into NodeMaker
test_dirnode.py: stop using FakeClient mockups, use NoNetworkGrid instead. This simplifies the code, but takes longer to run (17s instead of 6s). This should come down later when other cleanups make it possible to use simpler (non-RSA) fake mutable files for dirnode tests.
test_mutable.py: clean up basedir names
client.py: move create_empty_dirnode() into NodeMaker
dirnode.py: get rid of DirectoryNode.create
remove DirectoryNode.init_from_uri, refactor NodeMaker for customization, simplify test_web's mock Client to match
stop passing Client to DirectoryNode, make DirectoryNode.create_with_mutablefile the normal DirectoryNode constructor, start removing client from NodeMaker
remove Client from NodeMaker
move helper status into History, pass History to web.Status instead of Client
test_mutable.py: fix minor typo

docs: edits for docs/running.html from Sam Mason

docs: install.html: instruct Debian users to use this document and not to go find the DownloadDebianPackages page, ignore the warning at the top of it, and try it
http://allmydata.org/pipermail/tahoe-dev/2009-August/002507.html

docs: relnotes.txt: reflow to 63 chars wide because google groups and some web forms seem to wrap to that

docs: about.html: fix English usage noticed by Amber

docs: fix mis-spelled word in about.html

TAG allmydata-tahoe-1.5.0

docs: update install.html to point to 1.5.0 and edit the instructions (broadening the recommendation on Python versions to bless >= v2.4.2 <= v2.6.x)

docs: relnotes.txt: fix edits noticed by Amber

docs: update relnotes.txt, relnotes-short.txt, and others documentation bits for v1.5.0 release!

docs: CREDITS: boost Shawn Willden's CREDITS
(The better of a Tahoe-LAFS hacker you are, the shorter and more general your D: line.)

docs: about.html: edit (hopefully improve) the "What Makes Tahoe-LAFS Different" copy