more notes

[Imported from Trac: page NewCapDesign, version 2]

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 `<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
 
@@ -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.