From a03e63a92d6319a003931bdb938de1b3c78143b2 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Mon, 1 Dec 2014 21:52:16 +0000 Subject: [PATCH] Doc changes that require more careful review. refs #2345 Signed-off-by: Daira Hopwood --- docs/architecture.rst | 7 +----- docs/frontends/CLI.rst | 11 ++++---- docs/frontends/webapi.rst | 43 ++++++++++++++++---------------- docs/specifications/dirnodes.rst | 30 +++++++++++----------- src/allmydata/scripts/cli.py | 4 +-- 5 files changed, 47 insertions(+), 48 deletions(-) diff --git a/docs/architecture.rst b/docs/architecture.rst index 75026a76..ea113ad4 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -491,12 +491,7 @@ validate-capability, but not vice versa). These capabilities may be expressly delegated (irrevocably) by simply transferring the relevant secrets. The application layer can provide whatever access model is desired, built on -top of this capability access model. The first big user of this system so far -is allmydata.com. The allmydata.com access model currently works like a -normal web site, using username and password to give a user access to her -"virtual drive". In addition, allmydata.com users can share individual files -(using a file sharing interface built on top of the immutable file read -capabilities). +top of this capability access model. Reliability diff --git a/docs/frontends/CLI.rst b/docs/frontends/CLI.rst index a50e54d5..5b241bde 100644 --- a/docs/frontends/CLI.rst +++ b/docs/frontends/CLI.rst @@ -199,12 +199,13 @@ and later will use it if necessary. However, once you've set a ``tahoe:`` alias with "``tahoe set-alias``", that will override anything in the old ``root_dir.cap`` file. -The Tahoe-LAFS CLI commands use the same path syntax as ``scp`` and +The Tahoe-LAFS CLI commands use a similar path syntax to ``scp`` and ``rsync`` -- an optional ``ALIAS:`` prefix, followed by the pathname or -filename. Some commands (like "``tahoe cp``") use the lack of an alias to -mean that you want to refer to a local file, instead of something from the -Tahoe-LAFS filesystem. [TODO] Another way to indicate this is to start -the pathname with a dot, slash, or tilde. +filename. Commands that can accept either local paths or paths in the +Tahoe-LAFS file store, such as "``tahoe cp``", use the lack of an alias +to deduce that you want to refer to a local file. On Windows, aliases +cannot be a single character, so that it is possible to distinguish a +path relative to an alias from a path starting with a local drive specifier. When you're dealing a single starting directory, the ``tahoe:`` alias is all you need. But when you want to refer to something that isn't yet diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst index 8637c31c..22220136 100644 --- a/docs/frontends/webapi.rst +++ b/docs/frontends/webapi.rst @@ -1988,20 +1988,22 @@ Summary: use explicit file- and dir- caps whenever possible, to reduce the potential for surprises when the file store structure is changed. Tahoe-LAFS provides a mutable file store, but the ways that the store can -change are limited. The only thing that can change is that the mapping from -child names to child objects that each directory contains can be changed by -adding a new child name pointing to an object, removing an existing child name, -or changing an existing child name to point to a different object. - -Obviously if you query Tahoe for information about the filesystem and then act -to change the filesystem (such as by getting a listing of the contents of a -directory and then adding a file to the directory), then the filesystem might -have been changed after you queried it and before you acted upon it. However, -if you use the URI instead of the pathname of an object when you act upon the -object, then the only change that can happen is if the object is a directory -then the set of child names it has might be different. If, on the other hand, -you act upon the object using its pathname, then a different object might be in -that place, which can result in more kinds of surprises. +change are limited. The only things that can change are: + * that the mapping from child names to child objects that each mutable + directory contains can be changed (by adding a new child name pointing + to an object, removing an existing child name, or changing an existing + child name to point to a different object); + * that the contents of mutable files can change. + +Obviously if you query for information about the file store and then act +to change it (such as by getting a listing of the contents of a mutable +directory and then adding a file to the directory), then the store might +have been changed after you queried it and before you acted upon it. +However, if you use the URI instead of the pathname of an object when you +act upon the object, then it will be the same object; only its contents +can change (if it is mutable). If, on the other hand, you act upon the +object using its pathname, then a different object might be in that place, +which can result in more kinds of surprises. For example, suppose you are writing code which recursively downloads the contents of a directory. The first thing your code does is fetch the listing @@ -2009,15 +2011,14 @@ of the contents of the directory. For each child that it fetched, if that child is a file then it downloads the file, and if that child is a directory then it recurses into that directory. Now, if the download and the recurse actions are performed using the child's name, then the results might be -wrong, because for example a child name that pointed to a sub-directory when +wrong, because for example a child name that pointed to a subdirectory when you listed the directory might have been changed to point to a file (in which -case your attempt to recurse into it would result in an error and the file -would be skipped), or a child name that pointed to a file when you listed the -directory might now point to a sub-directory (in which case your attempt to -download the child would result in a file containing HTML text describing the -sub-directory!). +case your attempt to recurse into it would result in an error), or a child +name that pointed to a file when you listed the directory might now point to +a subdirectory (in which case your attempt to download the child would result +in a file containing HTML text describing the subdirectory!). -If your recursive algorithm uses the uri of the child instead of the name of +If your recursive algorithm uses the URI of the child instead of the name of the child, then those kinds of mistakes just can't happen. Note that both the child's name and the child's URI are included in the results of listing the parent directory, so it isn't any harder to use the URI for this purpose. diff --git a/docs/specifications/dirnodes.rst b/docs/specifications/dirnodes.rst index 24c7690f..d3a1b5b6 100644 --- a/docs/specifications/dirnodes.rst +++ b/docs/specifications/dirnodes.rst @@ -425,20 +425,22 @@ Mounting and Sharing Directories ================================ The biggest benefit of this dirnode approach is that sharing individual -directories is almost trivial. Alice creates a subdirectory that she wants to -use to share files with Bob. This subdirectory is attached to Alice's -filesystem at "~alice/share-with-bob". She asks her filesystem for the -read-write directory URI for that new directory, and emails it to Bob. When -Bob receives the URI, he asks his own local vdrive to attach the given URI, -perhaps at a place named "~bob/shared-with-alice". Every time either party -writes a file into this directory, the other will be able to read it. If -Alice prefers, she can give a read-only URI to Bob instead, and then Bob will -be able to read files but not change the contents of the directory. Neither -Alice nor Bob will get access to any files above the mounted directory: there -are no 'parent directory' pointers. If Alice creates a nested set of -directories, "~alice/share-with-bob/subdir2", and gives a read-only URI to -share-with-bob to Bob, then Bob will be unable to write to either -share-with-bob/ or subdir2/. +directories is almost trivial. Alice creates a subdirectory that she wants +to use to share files with Bob. This subdirectory is attached to Alice's +file store at "alice:shared-with-bob". She asks her file store for the +read-only directory URI for that new directory, and emails it to Bob. When +Bob receives the URI, he attaches the given URI into one of his own +directories, perhaps at a place named "bob:shared-with-alice". Every time +Alice writes a file into this directory, Bob will be able to read it. +(It is also possible to share read-write URIs between users, but that makes +it difficult to follow the `Prime Coordination Directive`_ .) Neither +Alice nor Bob will get access to any files above the mounted directory: +there are no 'parent directory' pointers. If Alice creates a nested set of +directories, "alice:shared-with-bob/subdir2", and gives a read-only URI to +shared-with-bob to Bob, then Bob will be unable to write to either +shared-with-bob/ or subdir2/. + +.. _`Prime Coordination Directive`: ../write_coordination.rst A suitable UI needs to be created to allow users to easily perform this sharing action: dragging a folder their vdrive to an IM or email user icon, diff --git a/src/allmydata/scripts/cli.py b/src/allmydata/scripts/cli.py index b0e4e6de..0c574861 100644 --- a/src/allmydata/scripts/cli.py +++ b/src/allmydata/scripts/cli.py @@ -129,8 +129,8 @@ class ListOptions(FilesystemOptions): Otherwise the size of the file, when known, is given in bytes. The size of mutable files or unknown objects is shown as '?'. - The date/time shows when this link in the Tahoe filesystem was - last modified. + The date/time shows when this link in the Tahoe grid was last + modified. """ class GetOptions(FilesystemOptions): -- 2.45.2