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)