fuse/runtests: make exceptions in 'read_in_random_order' into TestFailures

fuse/blackmatch: added asynchronous (background) file download

previously, upon opening a file for reading, the open() call would block
while the entire file was retrieved from tahoe into the cache directory.
This change adds a DownloaderWithReadQueue class, and associated plumbing,
such that an open() will return promptly with the download initiated 'in
the background'.  Subsequent read() operations will block until enough
data has been downloaded to satisfy that request.  This provides a behaviour
similar to streaming, i.e. the client application will be able to read
data from the fuse interface while the remainder of the file is still being
downloaded.

fuse/runtests: added 'read_in_random_order' test

this test uploads a test file to tahoe, and then reads the file from fuse,
but reads the blocks of the file in a random order; this is designed to
exercise the asynchronous download feature of blackmatch - where the file
is downloaded from tahoe asynchronously, and rather than blocking open()
for the entirety of the download, instead individual read() calls are
blocked until enough of the file has been downloaded to satisfy them

fuse/runtests: added a --no-cleanup option

the code had a 'fullcleanup' flag internally which controlled whether
working directories were cleaned up.  this promotes that to a command
line option (negated) '--no-cleanup' defaulting to False, i.e. do cleanup

fuse/runtests: truncate expected file contents in reported error message

this avoids dumping the repr of 1Mb of random data to stdout in the event
of a test failure, but rather just dumps the start/end of the errant strings
if the amount of data is > 200 chars repr'd

fuse/blackmatch: fix platform specific problems in repr_flags

the repr_flags debug/logging function had a list of fields from the os
module that might be passed into an open() call, but it included at
least one which was available on the mac but not on linux. symmetrically
linux has numerous flags which are not present on the mac. the repr_flags
function is now tolerant of flags not being present, and has an expanded
list of flags

makefile: added 'fuse-test' target to makefile, to run 'runtests'

fuse/runtests: added a 'todo' flag, surpressing failure for implementations not expected to pass

since the current tests assume that the implementation responds to changes made
to tahoe after mount, and impl_b prefetches and cached directory data, impl_b
fails the current 'read' test suite.

rather than reflect that problem in the overall failure of the runtests exit
code, this adds a 'todo' flag to the implementations table, and sets the todo
flag for impl_b.  Thus errors will therein be reported in output, but not cause
a failing exit code.

fuse/runtests: made runtests exit code depend on success

return an exit code of 0 only if no tests failed, and 1 in the case of
linkage error, test setup failure, or individual test case failure

storage.py: assert that immutable share size will fit in the 4-byte v1 container (see #346). The struct module in py2.4 raises an error on overflow, but py2.5 merely emits a warning

NEWS: update to summarize all changes since the last update

fuse/runtest: make removal of webport file soft

previously the runtests suite removed the webport file created by
tahoe create-client in all but the first node.  now that the node config
is in tahoe.cfg by default this file might not exist.

fuse/blackmatch: update json handling to support simplejson v2

simplejson v2 returns strings as either unicode or str, depending upon its
mood.  thus the interpretation of the node's json repr of a directory, and
the serialisation of strings in the json based rpc both exploded when built
against simplejson v2.  this makes both of these places liberal in their
acceptance of either str or unicode.

fuse/blackmatch: log exception in server startup

humphf.  my build runs the fuse stuff fine, but the build from the buildslave
doesn't seem to start up properly.  hopefully this will elicit some useful info

fuse/blackmatch: add readability to some logging, fix a permissions problem

adds a couple of functions to unpack 'mode' and 'flags' for open() calls, to
facilitate debugging.

adds a fix to ensure that all tmp files created for writing are opened with
permissions 0600 - one problem I had with testing with the Finder was that
files were being opened write only (0200) and were then failing to upload
to tahoe due to internal permission denied errors.

there remain a variety of problems with finder access which I'm unable to
comprehend at this time.  sometimes copies to tahoe will work fine, sometimes
they yield "the finder cannot complete the operation because some data ...
could not be read or written. (Error code -36)" sometimes "You may need to
enter the name and password for an administrator on this computer to change
the item" sometimes "The operation cannot be completed because an item with
the name ... already exists." and sometimes "The operation cannot be completed
because the item ... is locked."  What seems to be absent is rhyme or reason.

unix operations (cp, mv) work fine, rsync works fine.

fuse/blackmatch: fix linkage problems with daemonize

the daemonize() function imported from twisted was causing problems when
run from a frozen (py2app) build.  I simply copied the daemonize function
into this file, and that fixes the problem.

also removed a couple of lines of debugging spam that slipped through.

gui/macapp: minor bugfixes

though it seemed to work before the 'fstype' passed to fuse of 'allmydata' was
today throwing errors that len(fstype) must be at most 7.

fixed a typo in changes to 'mount_filesystem()' args

bumped the delay between mounting a filesystem and 'open'ing it in Finder to
4s, as it seems to take a little longer to mount now the client and server
fuse processes need to coordinate.

fuse/blackmatch: split into client/server (twisted server)

This implements a client/server split for blackmatch, where the client
implements the fuse_main bindings and a simple blocking rpc client mechanism.
The server implements the other half of that rpc mechanism, and contains all
the actual logic for interpreting fuse requests in the context of the on disk
cache and requests to the tahoe node.  The server is based on a twisted reactor.

The rpc mechanism implements a simple method dispatch including marshalling,
using json, of basic inert data types, in a flat namespace (no objects).
The client side is written in a blocking idiom, to interface with the threading
model used by the fuse_main bindings, whereas the server side is written for a
twisted reactor-based environment, intended to facilitate implementing more
sophisticated logic in that paradigm.  The two communicate over a unix domain
socket, allocated within the nodedir.

Command line usage is unchanged; the server is launched automatically by the
client. The server daemonizes itself, to avoid preventing the original parent
process (e.g. 'runtests') from waiting upon the server exiting.

The client keeps open a 'keepalive' connection to the server; upon loss thereof
the server will exit. This addresses the fact that the python-fuse bindings
provide no notification of exit of the client process upon unmount.

The client thus provides a relatively thin 'shim' proxying requests from the
fuse_main bindings across the rpc to the server process, which handles the
logic behind each request.

For the time being, a '--no-split' option is provided to surpress the splitting
into client/server, yielding the prior behaviour.  Once the server logic gets
more complex and more entrenched in a twisted idiom, this might be removed.
The 'runtests' test harness currently tests both modes, as 'impl_c' and
'impl_c_no_split'

fuse/blackmatch: 'flatten' the fuse api implementation

the previous revision of blackmatch used a file_class to delegate all fuse
api operations on files to a specific per-file class, which is an option
given by the python-fuse bindings.

this is a pre-cursor to the 'split' client/server version, which uses a
simple, moreover flat, rpc mechanism to broker access to methods.

fuse/runtests: disable impl_a/impl_b on mac, as they don't actually work.

fuse/runtests: added write_partial_overwrite test

this tests opening a file for update, overwriting a small part of it, and
ensuring that the end result constitutes an overwrite of the original file.
This tests, e.g. the implementation doesn' open a 'fresh' file but does in
fact initialise the file to be uploaded with the contents of any extant
file before applying updates

fuse/runtests: added --tests, renamed --suites

changed the --tests option to be --suites, as it takes a prefix, e.g. 'read'
'write' (or 'all', the default) and runs those suites which are applicable to
each implementation being tested.

added a --tests option, which takes a list of tests, e.g. 'read_file_contents'
'write_overlapping_large_writes' and runs all tests specified without regard
to whether the implementation(s) under test are declared to support them.

this is basically to allow a specific test or two to be run, saving time
during development and debugging by not running the entire suite

fuse/runtests: added 'random scatter' write test

this writes the test file in a randomised order, with randomly sized writes.
also for each 'slice' of the file written, a randomly chosen overlapping
write is also made to the file.  this ensures that the file will be written
in its entirety in a thoroughly random order, with many overlapping writes.

fuse/runtests: add overlapping write tests

using both small and large blocksizes for writes, write a 1Mb file to fuse
where every write overlaps another.

This serves a useful purpose - in manual testing of blackmatch some time ago
most operations e.g. bulk copies, worked fine, but using rsync caused data
corruption on most files.  it turned out to be that rsync writes in 64K blocks,
but rather than making the last block short, the last block instead overlaps
the preceding (already written) block.  This revealed a problem where cache
files were being opened 'append' rather than 'write' and hence the overlapping
write to the fuse layer caused the overlapping portion of the file to be
duplicated in cache, leading to oversized and corrupt files being uploaded.

fuse/runtests: remove write small file test, as it's subsumed by the tiny_file test

fuse/runtests: added linear write tests for various block sizes

unit tests to test writing contiguous blocks linearly through the file,
for a variety of block sizes;  'tiny_file' is an entire file fitting within
a single io block / write operation.  'linear_{small,large}_writes' test
a 1Mb file written with each write operation containing significantly less
or more, respecitvely, data than fuse will pass into the implementation as
a single operation (which on the mac at least is 64Kib)

fuse/runtests: add a very simple 'write' test

this performs a very simple write through the fuse layer and confirms that
the file is stored correctly into the tahoe mesh.  ('simple' in the sense
that the entire file body fits trivially in a single write() operation,
disk block etc)

fuse/runtests: added a --web-open option

similar to the --debug-wait option which causes the test harness to
pause at various stages of the process to facilitate debugging, this
option simplifies that debugging by automatically opening a web browser
to the root dir of that implementation's tests when tests are commenced.

in addition, if --web-open is specfied but --debug-wait is not, the
harness will still pause after running tests but before tearing down
the tahoe grid - this allows all tests to run to completion, but
provide a debugging hook to investigate the end state of the grid's
contents thereafter.

fuse/impl_a: fix a suspected bug in caching

from my examination of the tahoe_fuse ('impl_a') code, it looks like
the intention is to cache the file contents in memory while it's open,
since it does in fact do that.  however it looks like it also ignored
that cache entirely, and made an individual tahoe webapi GET request
for each and every read() operation regardless of the relative size of
the read block and the file in question.

this changes that to make read() use the data in memory rather than
fetch the data over again.   if there's something more subtle going
on, please let me know.

gui/macapp: slew of code cleanup; unmount filesystems on quit

a handful of code cleanup, renaming and refactoring.  basically consolidating
'application logic' (mount/unmount fs) into the 'MacGuiApp' class (the wx.App)
and cleaning up various scoping things around that.  renamed all references to
'app' to refer more clearly to the 'AppContainer' or to the guiapp.

globally renamed basedir -> nodedir

also made the guiapp keep a note of each filesystem it mounts, and unmount
them upon 'quit' so as to cleanup the user's environment before the tahoe node
vanishes from out underneath the orphaned tahoe fuse processes

gui/macapp: make submenu of aliases for 'webopen'

this changes the 'open webroot' menu item to be a submenu listing all aliases
defined in ~/.tahoe.  Note that the dock menu does not support submenus, so it
only offers a single 'open webroot' option for the default tahoe: alias.

I had trouble with this at first and concluded that the submenus didn't work,
and made it a distinct 'WebUI' menu in it's own right.  on further inspection,
there are still problems but they seem to be something like once the dock menu
has been used, sometimes the app's main menubar menus will cease to function,
and this happens regardless of whether submenus or plain simple menus are used.
I have no idea what the peoblem is, but it's not submenu specific.

repairer: fix flaw in testutil.flip_one_bit() that Brian pointed out

misc/incident-gatherer: add classify_tahoe.py: a foolscap incident-gatherer classification plugin

repairer: test all different kinds of corruption that can happen to share files on disk

util/time_format.py: accept space separator, add unit tests

test_storage: use different filenames, poor stupid windows

scripts/debug.py: emit the immutable-share version number, tolerate v2

storage.py: improve some precondition() error messages

storage: introduce v2 immutable shares, with 8-byte offsets fields, to remove two of the three size limitations in #346. This code handles v2 shares but does not generate them. We'll make a release with this v2-tolerance, wait a while, then make a second release that actually generates v2 shares, to avoid compatibility problems.

debug.py: oops, add missing import for ReadBucketProxy

storage: split WriteBucketProxy and ReadBucketProxy out into immutable/layout.py . No behavioral changes.

interfaces: loosen a few max-size constraints which would limit us to a mere 1.09 TB maximum file size

These constraints were originally intended to protect against attacks on the
storage server protocol layer which exhaust memory in the peer.  However,
defending against that sort of DoS is hard -- probably it isn't completely
achieved -- and it costs development time to think about it, and it sometimes
imposes limits on legitimate users which we don't necessarily want to impose.
So, for now we forget about limiting the amount of RAM that a foolscap peer can
cause you to start using.

util/limiter: add a repr

dirnode.build_manifest: include node.list in the limiter, that's the most important thing to slow down

web/directory: t=manifest output=html: make the caps into clickable hrefs

web/directory: factor out the get_root function

web/directory.py: remove unused imports

test_web: deep-size is more variable than I thought, so assert less

web: change t=manifest to return a list of (path,read/writecap) tuples, instead of a list of verifycaps. Add output=html,text,json.

web: rewrite t=deep-size in terms of deep-stats, update test to match inclusion of directory sizes

ftpd: hush pyflakes

ftpd: make sure we're using a patched/fixed Twisted, to avoid confusion later

ftp: change the twisted hack necessary for async-write-close, to one more agreeable to the twisted-dev folks, add a copy of the necessary patch to docs/ftp.txt

ftpd: remove debug messages

ftpd: add native_client.php -based HTTP authentication scheme

ftpd: add ftp.accounts checker, remove InMemoryPasswordChecker

test_system: add test coverage for immutable download.ConsumerAdapter, remove debug messages

ftp server: initial implementation. Still needs unit tests, custom Twisted patches. For #512

test_cli.py: remove unused imports

CLI: remove 'tahoe admin generate-keypair', since the pycryptopp ecdsa API is about to change incompatibly. We'll undo this once pycryptopp is updated

docs: update architecture.txt 's section on the vdrive a.k.a. filesystem layer
Remove some obsolete parts (correct at the time, now incorrect), change terminology to reflect my preference: s/vdrive/filesystem/ and s/dirnode/directory/, and make a few other small changes.

dirnode: fix my remarkably-consistent 'metdadata' typo

interfaces: fix minor typo

dirnode: add get_child_and_metadata_at_path

stop using 'as' as an identifier: as with 'with', 'as' has become a reserved word in python 2.6

scripts/admin: split up generate_keypair code so that unit tests can use it more easily

docs: add some notes about things to do for a Tahoe release on pypi, freshmeat, and launchpad

misc/cpu-watcher.tac: use writeaside-and-rename for the history.pickle file

misc/spacetime: use async polling so we can add a 60-second timeout, add an index to the 'url' Axiom column for 2x speedup

#518: replace various BASEDIR/* config files with a single BASEDIR/tahoe.cfg, with backwards-compatibility of course

tolerate simplejson-2.0.0 and newer, which frequently return bytestrings instead of unicode objects. Closes #523

munin/tahoe_doomsday: oops, tolerate 'null' in the timeleft results, to unbreak the 2wk/4wk graphs

test_node: improve coverage of advertised_ip_addresses a bit

testutil.PollMixin: set default timeout (to 100s), emit a more helpful error when the timeout is hit

repair: fix test to map from storage index to directory structure properly (thanks, cygwin buildbot, for being so kloodgey that you won't accept random binary filenames and thus making me notice this bug)

repairer: assert that the test code isn't accidentally allowing the repairer code which is being tested to do impossible things

repairer: enhance the repairer tests
Make sure the file can actually be downloaded afterward, that it used one of the
deleted and then repaired shares to do so, and that it repairs from multiple
deletions at once (without using more than a reasonable amount of calls to
storage server allocate).

netstring: add required_trailer= argument

test_netstring.py: move netstring tests to a separate file

move netstring() and split_netstring() into a separate util.netstring module

repairer: remove a test that doesn't apply to the repair-from-corruption case

repairer: add a test that repairer fixes corrupted shares (in addition to the test that it fixes deleted shares)

docs: proposed mutable file crypto design with ECDSA, 96-bit private keys, and semi-private keys (from http://allmydata.org/~zooko/lafs.pdf )

docs: mutable file crypto design (from http://allmydata.org/~zooko/lafs.pdf )

repairer: fix swapped docstrings; thanks Brian

trivial: remove unused imports; thanks, pyflakes

trivial: remove unused imports -- thanks, pyflakes

repairer: add basic test of repairer, move tests of immutable checker/repairer from test_system to test_immutable_checker, remove obsolete test helper code from test_filenode
Hm...  "Checker" ought to be renamed to "CheckerRepairer" or "Repairer" at some point...

setup: remove a few minimal unit tests from test_filenode which have been obviated by much better tests in test_mutable and test_system

gui/macapp: rough cut of ui tweaks; configurability, auto-mount

chatting with peter, two things the mac gui needed were the ability to mount
the 'allmydata drive' automatically upon launching the app, and open the
Finder to reveal it.  (also a request to hide the debug 'open webroot' stuff)

this (somewhat rough) patch implements all the above as default behaviour

it also contains a quick configuration mechanism for the gui - rather than a
preferences gui, running with a more 'tahoe' styled mechanism, the contents
of a few optional files can modify the default behaviour, specifically file
in ~/.tahoe/gui.conf control behaviour as follows:

auto-mount (bool): if set (the default) then the mac app will, upon launch
automatically mount the 'tahoe:' alias with the display name 'Allmydata'
using a mountpoint of ~/.tahoe/mnt/__auto__

auto-open (bool): if set (the default) then upon mounting a file system
(including the auto-mount if set) finder will be opened to the mountpoint
of the filesystem, which essentially reveals the newly mounted drive in a
Finder window

show-webopen (bool): if set (false by default) then the 'open webroot'
action will be made available in both the dock and file menus of the app

daemon-timout (int): sets the daemon-timeout option passed into tahoe fuse
when a filesystem is mounted. this defaults to 5 min

files of type (int) much, naturally contain a parsable int representation.
files of type (bool) are considered true if their (case-insensitive) contents
are any of ['y', 'yes', 'true', 'on', '1'] and considered false otherwise.

gui/macapp: improve 'about' box

adds exactly 1 metric dollop of professionalism to the previously
rather amateurish looking about box.

fuse/impl_c: UNDO --auto-fsid option

rolling back:

Thu Sep 25 14:42:23 BST 2008  robk-tahoe@allmydata.com
  * fuse/impl_c: add --auto-fsid option

  this was inspired by reading the fuse docs and discovering the 'fsid' option
  to fuse_main, and was _intended_ to support a sort of 'stability' to the
  filesystem (specifically derived from the root-uri mounted, whether directly
  or via an alias) to support mac aliases across unmount/remount etc.

  some experimentation shows that that doesn't actually work, and that, at
  least for mac aliases in my testing, they're tied to path-to-mountpoint and
  not to the fsid - which seems to have no bearing.  perhaps the 'local' flag
  is causing weirdness therein.

  at any rate, I'm recording it simply for posterity, in case it turns out to
  be useful after all somewhere down the road.

    M ./contrib/fuse/impl_c/blackmatch.py +13

fuse/impl_c: add --auto-fsid option

this was inspired by reading the fuse docs and discovering the 'fsid' option
to fuse_main, and was _intended_ to support a sort of 'stability' to the
filesystem (specifically derived from the root-uri mounted, whether directly
or via an alias) to support mac aliases across unmount/remount etc.

some experimentation shows that that doesn't actually work, and that, at
least for mac aliases in my testing, they're tied to path-to-mountpoint and
not to the fsid - which seems to have no bearing.  perhaps the 'local' flag
is causing weirdness therein.

at any rate, I'm recording it simply for posterity, in case it turns out to
be useful after all somewhere down the road.

manhole: be more tolerant of authorized_keys. files in .tahoe

both peter and I independently tried to do the same thing to eliminate the
authorized_keys file which was causing problems with the broken mac build
(c.f. #522) namely mv authorized_keys.8223{,.bak}  but the node is, ahem,
let's say 'intolerant' of the trailing .bak - rather than disable the
manhole as one might expect, it instead causes the node to explode on
startup.  this patch makes it skip over anything that doesn't pass the
'parse this trailing stuff as an int' test.

fuse/impl_c: move mac tahoefuse impl out into contrib/fuse

For a variety of reasons, high amongst them the fact that many people
interested in fuse support for tahoe seem to have missed its existence,
the existing fuse implementation for tahoe, previously 'mac/tahoefuse.py'
has been renamed and moved.

It was suggested that, even though the mac build depends upon it, that
the mac/tahoefuse implementation be moved into contrib/fuse along with
the other fuse implementations.  The fact that it's not as extensively
covered by unit tests as mainline tahoe was given as corroboration.

In a bid to try and stem the confusion inherent in having tahoe_fuse,
tfuse and tahoefuse jumbled together (not necessarily helped by
referring to them as impl_a, b and c respectively) I'm hereby renaming
tahoefuse as 'blackmatch'  (black match is, per wikipedia "a type of
crude fuse" hey, I'm a punny guy)  Maybe one day it'll be promoted to
be 'quickmatch' instead...

Anyway, this patch moves mac/tahoefuse.py out to contrib/fuse/impl_c/
as blackmatch.py, and makes appropriate changes to the mac build process
to transclude blackmatch therein.  this leaves the extant fuse.py and
fuseparts business in mac/ as-is and doesn't attempt to address such
issues in contrib/fuse/impl_c.

it is left as an exercise to the reader (or the reader of a message
to follow) as to how to deal with the 'fuse' python module on the mac.

as of this time, blackmatch should work on both mac and linux, and
passes the four extant tests in runtests.  (fwiw neither impl_a nor
impl_b have I managed to get working on the mac yet)

since blackmatch supports a read-write and caching fuse interface to
tahoe, some write tests obviously need to be added to runtests.

macapp: changes to support aliases, updated tahoefuse command line options

the tahoefuse command line options changed to support the runtests harness,
and as part of that gained support for named aliases via --alias

this changes the mac app's invocation of tahoefuse to match that, and also
changes the gui to present the list of defined aliases as valid mounts

this replaces the previous logic which examined the ~/.tahoe/private directory
looking for files ending in '.cap' - an ad-hoc alias mechanism.

if a file is found matching ~/.tahoe/private/ALIASNAME.icns then that will still
be passed to tahoefuse as the icon to display for that filesystem. if no such
file is found, the allmydata icon will be used by default.

the '-olocal' option is passed to tahoefuse.  this is potentially contentious.
specifically this is telling the OS that this is a 'local' filesystem, which is
intended to be used to locally attached devices.  however leopard (OSX 10.5)
will only display non-local filesystems in the Finder's side bar if they are of
fs types specifically known by Finder to be network file systems (nfs, cifs,
webdav, afp)  hence the -olocal flag is the only way on leopard to cause finder
to display the mounted filesystem in the sidebar, but it displays as a 'device'.
there is a potential (i.e. the fuse docs carry warnings) that this may cause
vague and unspecified undesirable behaviour.
(c.f. http://code.google.com/p/macfuse/wiki/FAQ specifically Q4.3 and Q4.1)

fuse/impl_c: reworking of mac/tahoefuse, command line options, test integration

a handful of changes to the tahoefuse implementation used by the mac build, to
make command line option parsing more flexible and robust, and moreover to
facilitate integration of this implementation with the 'runtests' test harness
used to test the other two implementations.

this patch includes;
- improvements to command line option parsing [ see below ]
- support for 'aliases' akin to other tahoe tools
- tweaks to support linux (ubuntu hardy)

the linux support tweaks are, or at least seem to be, a result of the fact that
hardy ships with fuse 0.2pre3, as opposed to the fuse0.2 that macfuse is based
upon.  at least the versions I was working with have discrepencies in their
interfaces, but on reflection this is probably a 'python-fuse' version issue
rather than fuse per se.  At any rate, the fixes to handling the Stat objects
should be safe against either version, it's just that the bindings on hardy
lacked code that was in the 'fuse' python module on the mac...

command line options:

the need for more flexible invocation in support of the runtests harness led
me to rework the argument parsing from some simple positional hacks with a
pass-through of the remainder to the fuse binding's 'fuse_main' to a system
using twisted.usage to parse arguments, and having just one option '-o' being
explicitly a pass-through for -o options to fuse_main. the options are now:

--node-directory NODEDIR : this is used to look up the node-url to connect
to if that's not specified concretely on the command line, and also used to
determine the location of the cache directory used by the implementation,
specifically '_cache' within the nodedir.  default value: ~/.tahoe

--node-url NODEURL : specify a node-url taking precendence over that found
in the node.url file within the nodedir

--alias ALIAS : specifies the named alias should be mounted. a lookup is
performed in the alias table within 'nodedir' to find the root dir cap
the named alias must exist in the alias table of the specified nodedir

--root-uri ROOTURI : specifies that the given directory uri should be mounted

at least one of --alias and --root-uri must be given (which directory to mount
must be specified somehow)  if both are given --alias takes precedence.

--cache-timeout TIMEOUTSECS : specifies the number of seconds that cached
directory data should be considered valid for.  this tahoefuse implementation
implements directory caching for a limited time; largely because the mac (i.e.
the Finder in particular) tends to make a large number of requests in quick
successsion when browsing the filesystem.  on the flip side, the 'runtests'
unit tests fail in the face of such caching because the changes made to the
underlying tahoe directories are not reflected in the fuse presentation.  by
specifying a cache-timeout of 0 seconds, runtests can force the fuse layer
into refetching directory data upon each request.

any number of -oname=value options may be specified on the command line,
and they will all be passed into the underlying fuse_main call.

a single non-optional argument, the mountpoint, must also be given.

fuse/tests: slew of changes to fuse 'runtests'

This patch makes a significant number of changes to the fuse 'runtests' script
which stem from my efforts to integrate the third fuse implementation into this
framework.  Perhaps not all were necessary to that end, and I beg nejucomo's
forebearance if I got too carried away.

- cleaned up the blank lines; imho blank lines should be empty

- made the unmount command switch based on platform, since macfuse just uses
'umount' not the 'fusermount' command (which doesn't exist)

- made the expected working dir for runtests the contrib/fuse dir, not the
top-level tahoe source tree - see also discussion of --path-to-tahoe below

- significantly reworked the ImplProcManager class.  rather than subclassing
for each fuse implementation to be tested, the new version is based on
instantiating objects and providing relevant config info to the constructor.
this was motivated by a desire to eliminate the duplication of similar but
subtly different code between instances, framed by consideration of increasing
the number of platforms and implementations involved. each implementation to
test is thus reduced to the pertinent import and an entry in the
'implementations' table defining how to handle that implementation. this also
provides a way to specify which sets of tests to run for each implementation,
more on that below.

- significantly reworked the command line options parsing, using twisted.usage;

what used to be a single optional argument is now represented by the
--test-type option which allows one to choose between running unittests, the
system tests, or both.

the --implementations option allows for a specific (comma-separated) list of
implemenations to be tested, or the default 'all'

the --tests option allows for a specific (comma-separated) list of tests sets
to be run, or the default 'all'.  note that only the intersection of tests
requested on the command line and tests relevant to each implementation will
be run. see below for more on tests sets.

the --path-to-tahoe open allows for the path to the 'tahoe' executable to be
specified. it defaults to '../../bin/tahoe' which is the location of the tahoe
script in the source tree relative to the contrib/fuse dir by default.

the --tmp-dir option controls where temporary directories (and hence
mountpoints) are created during the test.  this defaults to /tmp - a change
from the previous behaviour of using the system default dir for calls to
tempfile.mkdtemp(), a behaviour which can be obtained by providing an empty
value, e.g. "--tmp-dir="

the --debug-wait flag causes the test runner to pause waiting upon user
input at various stages through the testing, which facilitates debugging e.g.
by allowing the user to open a browser and explore or modify the contents of
the ephemeral grid after it has been instantiated but before tests are run,
or make environmental adjustments before actually triggering fuse mounts etc.
note that the webapi url for the first client node is printed out upon its
startup to facilitate this sort of debugging also.

- the default tmp dir was changed, and made configurable. previously the
default behaviour of tempfile.mkdtemp() was used.  it turns out that, at least
on the mac, that led to temporary directories to be created in a location
which ultimately led to mountpoint paths longer than could be handled by
macfuse - specifically mounted filesystems could not be unmounted and would
'leak'. by changing the default location to be rooted at /tmp this leads to
mountpoint paths short enough to be supported without problems.

- tests are now grouped into 'sets' by method name prefix.  all the existing
tests have been moved into the 'read' set, i.e. with method names starting
'test_read_'. this is intended to facilitate the fact that some implementations
are read-only, and some support write, so the applicability of tests will vary
by implementation. the 'implementations' table, which governs the configuration
of the ImplProcManager responsible for a given implementation, provides a list
of 'test' (i.e test set names) which are applicable to that implementation.
note no 'write' tests yet exist, this is merely laying the groundwork.

- the 'expected output' of the tahoe command, which is checked for 'surprising'
output by regex match, can be confused by spurious output from libraries.
specfically, testing on the mac produced a warning message about zope interface
resolution various multiple eggs.  the 'check_tahoe_output()' function now has
a list of 'ignorable_lines' (each a regex) which will be discarded before the
remainder of the output of the tahoe script is matched against expectation.

- cleaned up a typo, and a few spurious imports caught by pyflakes

fuse/impl_{a,b}: improve node-url handling

specifically change the expectation of the code to be such that the node-url
(self.url) always includes the trailing slash to be a correctly formed url

moreover read the node-url from the 'node.url' file found in the node 'basedir'
and only if that doesn't exist, then fall back to reading the 'webport' file
from therein and assuming localhost.  This then supports the general tahoe
pattern that tools needing only a webapi server can be pointed at a directory
containing the node.url file, which can optionally point to another server,
rather than requiring a complete node dir and locally running node instance.

fuse/impl_b: tweaks from testing on hardy

from testing on linux (specifically ubuntu hardy) the libfuse dll has a
different name, specifically libfuse.so.2. this patch tries libfuse.so
and then falls back to trying .2 if the former fails.

it also changes the unmount behaviour, to simply return from the handler's
loop_forever() loop upon being unmounted, rather than raising an EOFError,
since none of the client code I looked at actually handled that exception,
but did seem to expect to fall off of main() when loop_forever() returned.
Additionally, from my testing unmount typically led to an OSError from the
fuse fd read, rather than an empty read, as the code seemed to expect.

also removed a spurious import pyflakes quibbled about.