diff --git a/NewCapDesign.md b/NewCapDesign.md index 18f3eb5..b310853 100644 --- a/NewCapDesign.md +++ b/NewCapDesign.md @@ -14,10 +14,34 @@ 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) + 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, + nyou 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 `` 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 @@ -34,7 +58,7 @@ established sense). To make them real, we need to: 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 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 @@ -49,7 +73,10 @@ established sense). To make them real, we need to: 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...`). + 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 @@ -74,7 +101,12 @@ established sense). To make them real, we need to: * 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. + 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.