[tahoe-dev] using URIs from the command line

[Brian Warner]

As part of our discussion today, Zooko and I were discussing ways to shape
the CLI syntax so that you can conveniently use file- and dir-caps directly
from the command line.

My hope is that the CLI tools will help reinforce the idea that each
directory/file has a URI, and that any other name you might use to reference
them is just a convenience. One way to accomplish this is to treat the URI as
the fundamental type of argument, and then make a clear and obvious way to
abbreviate these things for common use. We've mostly accomplished this for
the web interface: /uri/$URI is the thing that you bookmark. The CLI tools
don't have bookmarks per se, but we can use a config file somewhere as the
equivalent, maybe ~/.tahoe/private/aliases , and some simple tool to add
entries to it:

  tahoe set-alias work DIRURI
  tahoe ls work:


To pick a couple of use-cases, I'd like to be able to upload a file, get its
read-cap, and paste it to my friend through IM or email. My friend wants to
take the read-cap and get the contents of the file.

Also, I'd like to create a directory, get its read-cap, and paste it to my
friend. She wants to be able to list the directory and copy files out of it.
If we're going to keep using this directory in the future, she'd like a way
to remember the read-cap and refer to it conveniently.. perhaps with some
sort of bookmark, or by attaching it to her pre-existing tahoe space as an
subdir named "shared-with-brian".

Some workflows we can imagine to do this:

 tahoe put coolness.pdf >URI        # uploads and emits a URI
 mail -s "this is cool" zooko <URI
 # then zooko does one of:
 tahoe get URI |xpdf
 tahoe get URI >might-be-cool.pdf
 tahoe cp (something)URI ./might-be-cool.pdf

 tahoe mkdir >DIRURI
 # send DIRURI to alice, who does
 tahoe ls (something)URI
 tahoe cp (something)URI/foo.txt from-brian/foo.txt
 tahoe set-alias brian URI
 tahoe get brian:foo.txt
 tahoe ln (something)URI stuff/shared-with-brian

Where the (something) prefix is uncertain: the purpose of this email is to
figure out what that prefix ought to be.

'tahoe cp' is for copying files from one place to another, where one of those
places might be your local disk. As described in my other letter, we're
planning on using scp-style alias: prefixes to indicate which place is in
use. The tricky part is that the places that a 'tahoe cp' can refer to are
less human-meaningful than the hostname that 'scp' works with. The "place" is
defined specifically by a directory cap, which is currently an 88-character
string that starts with "URI:DIR2:" and has a bunch of crypto goo in it. When
we get to ECDSA-based mutable files, that will shrink to something like 40
characters that have no colons and start with a "D" (for "Directory"), but
will still be random-looking.

The current question is how to unambiguously allow a URI or an alias (or
neither, to stick with the default) in the CLI arguments. We need a syntax
that allows:

 nothing
 a convenient-to-type human-generated alias
 an inconvenient-to-type random URI
   current ones start are URI:DIR2:stuff:stuff
   future ones will be Dstuff

My initial suggestion was that tools should look for a colon to distinguish
between nothing and an alias-or-URI, and if some prefix is found, look it up
in the alias table. If nothing is found in the alias table, then treat the
prefix as a URI. This would result in commands like the following (to dump a
file from a given tahoe directory):

 tahoe get foo.txt
 tahoe get work:foo.txt
 tahoe get URI:DIR2:djrdkfawoqihigoett4g6auz6a:jx5mplfpwexnoqff7y5e4zjus4lidm76dcuarpct7cckorh2dpgq:foo.txt
 tahoe get D0ZrDNAHuxs0XhYJNmkdicBUFxsgiHzMdm:foo.txt

The last one will be after we've implemented #217, DSA-based mutable files,
and condensed the cap format, and depends upon how we emit dircaps.. there is
discussion afoot to make them real URIs, which really just means a scheme:
prefix. This would make the command look like:

 tahoe get x-tahoe:D0ZrDNAHuxs0XhYJNmkdicBUFxsgiHzMdm:foo.txt

A related question is how to make it convenient to list a directory by its
URI. The shortest thing I can think of is:

 tahoe ls URI:DIR2:djrdkfawoqihigoett4g6auz6a:jx5mplfpwexnoqff7y5e4zjus4lidm76dcuarpct7cckorh2dpgq
 tahoe ls D0ZrDNAHuxs0XhYJNmkdicBUFxsgiHzMdm

but both of those are hard to distinguish from listing a weirdly-named file
or directory in your default root directory. If we use the same alias: prefix
as described above, these would become:

 tahoe ls URI:DIR2:djrdkfawoqihigoett4g6auz6a:jx5mplfpwexnoqff7y5e4zjus4lidm76dcuarpct7cckorh2dpgq:
 tahoe ls D0ZrDNAHuxs0XhYJNmkdicBUFxsgiHzMdm:

and we'd need to rely upon a useful error message like "couldn't find XXX in
default root directory YYY" to help people discover that they need to add the
colon.


Zooko was concerned about the potential ambiguity between the alias name and
the directory cap: as caps get shorter and carry less redundancy (like the
current URI:DIR2: header), they'll look more and more like regular strings.
Likewise, he feels that people may use long alias names that get close to the
length of the dircaps, so you might wind up with an alias that would be
impossible to visually distinguish from a real (but remarkably lucky)
directory cap:

 tahoe get DataThatWantsToGetBackedUpForWork:foo.txt

The only way to tell that this is an alias and not a dircap is to look inside
the alias table.

One idea that was floated was to use another out-of-band character (beyond
the colon) to mark a dircap, as distinct from a long alias name:

 tahoe get @D0ZrDNAHuxs0XhYJNmkdicBUFxsgiHzMdm:foo.txt
 tahoe get DoNotthinkThisIsACap:foo.txt


We tabled this issue until later.. meanwhile I'm going to document and
implement the alias-only (no caps) approach.

Thoughts?

 -Brian