diff --git a/NewCapDesign.md b/NewCapDesign.md new file mode 100644 index 0000000..18f3eb5 --- /dev/null +++ b/NewCapDesign.md @@ -0,0 +1,85 @@ +# 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 ``). (#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)