= Goals for new filecaps =

This is a place to record desiderata for the next version of our
mutable/immutable filecaps. Many of the design requirements are spread out
across separate tickets: this page is here to consolidate them. We should not
release a new filecap format without checking it against everything on this
list.

Ticket #432 was the starting point: it contained a list of features.

== make them real URIs ==

Kevin Reid points out that the Tahoe calls URIs are not actually URIs (in the
established sense). To make them real, we need to:

 * make then start with {{{x-tahoe:}}} or {{{tahoe:}}}, register {{{tahoe:}}}
   with IANA (#418)
 * understand how URI/URL/URNs are built, decide about hierarchical segments
   vs non-hierarchical segments. What's magical about a leading double-slash?
   Do we need one?

== other features ==

 * Enable convenient cut-and-paste. If caps are too long they'll wrap in
   email. If they contain lots of word-breaking characters then you have to
   drag after you've double clicked (this is probably ok). If the word-broken
   sections are small and at the beginning or end then you have to be very
   precise about that drag. The best design would be a single short
   non-word-breaking string. The next best will be to have a large
   non-word-breaking string at the start and end, with smaller segments (if
   necessary) in the middle.
 * Usable in a browser. Specifically, it should be easy to actually use a
   filecap that you get in email or IM, and many email/IM clients will look
   for http URLs and make them clickable. If tahoe filecaps start with
   {{{http:}}}, then they'll be made clickable. This is at odds with the
   IANA-friendly {{{tahoe:}}} prefix. Clients may make {{{tahoe:}}} URIs
   clickable too (I've seen them make other letters-than-colon strings
   clickable, even when the letters are not "http"), so perhaps a reasonable
   solution is to provide an OS-level URI handler for the {{{tahoe:}}}
   scheme, which could embed the filecap in an http URL and submit it to a
   webbrowser (i.e. when you click on {{{tahoe:foo}}}, a helper program is
   launched with {{{tahoe:foo}}}, and that in turn launches your web browser
   with {{{http://localhost:8123/foo}}}). (#52)
 * Self-identifying. It should be visually clear what sort of filecap the
   string represents: read-write or read-only, mutable-or-immutable,
   file-or-directory. This is especially important when sharing tahoe objects
   over out-of-band channels like IM and email: it should be easy for the
   user to tell whether they're giving away readonly access or read-write
   access. We've considered prefixes like {{{DWM..}}} for "Directory
   Writeable Mutable" and {{{FRI..}}} for "File Readonly Immutable". If these
   are jammed against the (base62) crypto bits it may be difficult to tell
   where the prefix ends and the crypto bits begin ({{{FRIDWM...}}}).
  * in addition, tahoe URIs should be distinguishable from local filenames by
    a CLI tool, so that {{{tahoe cp $CAP local/foo.txt}}} is unambiguous.
    (unfortunately, the current practice of using "tahoe:" as a default alias
    name collides with this badly, but perhaps if the new URIs include the
    double-slash, this won't be a problem:
    {{{tahoe cp tahoe://CAP local/foo.txt}}} copies from a specific URI,
    while {{{tahoe cp tahoe:blah local/foo.txt}}} copies from a child of
    the "tahoe:" alias).
  * I'd like to make it easy to layer uses on top of one another: since
    directories are just a specific way of interpreting the contents of a
    (mutable) file, let's make the directory cap be closely related to the
    underlying filecap. For example, if we end up using
    {{{tahoe://MR/cryptobits}}} to describe a read-only mutable file
    referenced by "cryptobits", then we could use
    {{{tahoe://D/MR/cryptobits}}} for the directory that uses it as a backing
    store. The rule would be that {{{tahoe://D/$A}}} would be handled by
    fetching {{{tahoe://$A}}} and then interpreting its contents as a
    directory structure. Then reading immutable-dirnodes (#607) would be
    trivial. Another way to think about this is that if our filecaps were
    verbose s-expressions, these caps could be expressed as "(readonly
    (mutable cryptobits))" and "(directory (readonly (mutable cryptobits)))".
 * provide for verifycaps, repaircaps, and traversalcaps. Repaircaps in
   particular may require a grant of storage authority, which might entail a
   cap format that can accept arbitrary extra non-hierarchical fields.
   Appendcaps or "drop-box" writecaps might fall into this same space.
 * provide ciphertext access. Reading from a verifycap should give you
   ciphertext. It should be possible to upload ciphertext directly.
 * provide for a grid-identifier, possibly on the MSB end, e.g.
   {{{tahoe://grid1234/IR/cryptobits}}}. Perhaps let some contexts define a
   "default grid id", such that {{{tahoe://IR/cryptobits}}} is expanded to
   mean {{{tahoe://grid1234/IR/cryptobits}}}. Something like
   {{{tahoe://grid1234/D/MR/cryptobits}}} should reference
   {{{tahoe://grid1234/MR/cryptobits}}}. (#403)