= 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) (#683)
 * 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?
 * according to #683, a URI '''identifies''' a resource, but does not
   necessarily provide enough information to actually access it (i.e. if you
   have a URI and somebody pointed you at a file, you could confidently tell
   them whether or not it was the right file, but if you only have the URI,
   then you might not be able to find the file without additional information). If
   the cap has both identifying and location information, it's called a URL.
 * Tahoe filecaps are meant to be URLs (they are intended to provide location
   information), but to really make that work, you also need to define which
   grid you're talking about. So far this has always been implicit, but that
   has caused us problems. #403 talks about making an explicit "gridid" and
   would provide a procedure to get from a gridid string to a set of storage
   servers. The existing tahoe codebase could use the introducer FURL as a
   gridid, if there were a good place to put it in the filecap (#683 touches
   on this).
  * from the point of view of a web browser, you also need a gateway service
    (the Tahoe client node with a webapi frontend). The tahoe URLs that we've
    been passing around so far always reference one of these, either by
    assuming that {{{http://localhost:8123}}} is a suitable gateway or by
    explicitly referencing an external gateway like testgrid.allmydata.org
    (with deleterious effects on security and availability). I hope that our
    new filecaps are defined independently of a webapi gateway used to access
    them, and that we have a clear procedure for starting with a filecap and
    a gateway HTTP URL, and ending with the contents of the file.


== 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. Note that {{{tahoe:}}} is an easy target, but
   {{{x-tahoe:}}} is not (you'd have to double-click on the "x").
 * 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-then-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, especially because the
   crypto bits will be using the same character set ({{{FRIDWM...}}}). It
   might be a good idea to separate the type prefix from the cryptobits:
   {{{FRI-cryptobits}}} or {{{FRI/cryptobits}}}.
  * 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. But
   remember that URIs should identify objects, not the action that you want
   to do on it: a webapi scheme may use a POST/PUT/DELETE method, or append a
   t=json adverb, or alternatively encode the verb/adverb into the HTTP url
   (think {{{GET .../filecap/json}}} or {{{PUT unlinked/ciphertext}}}), but
   these are independent of the underlying filecap.
 * 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)
 * #102 and #217 have notes on dircaps