= Capabilities =

An overview from the mailing list archives - originally by [http://allmydata.org/pipermail/tahoe-dev/2009-February/001110.html Feb 2009 - Brian Warner],
but updated to take into account literal caps and immutable directories:

{{{
 1: immutable file read-only capability string            URI:CHK:
 2: immutable file verify capability string               URI:CHK-Verifier:
 3: immutable LIT file read-only capability string        URI:LIT:

 4: mutable file read-write capability string             URI:SSK:
 5: mutable file read-only capability string              URI:SSK-RO:
 6: mutable file verify capability string                 URI:SSK-Verifier:

 7: immutable directory read-only capability string       URI:DIR2-CHK:
 8: immutable directory verify capability string          URI:DIR2-CHK-Verifier:
 9: immutable LIT directory read-only capability string   URI:DIR2-LIT:

10: mutable directory read-write capability string        URI:DIR2:
11: mutable directory read-only capability string         URI:DIR2-RO:
12: mutable directory verify capability string            URI:DIR2-Verifier:

13: unknown/future capability strings                     <anything else>

In Tahoe, directories are built out of mutable files (a directory is really
just a particular way to interpret the contents of a given mutable file), and
non-directory mutable files aren't used very much. All normal data files are
uploaded into immutable files by default.

Some capabilities can be used to derive others. If you have #1, you can
derive #2 (but not the other way around). The full table is:

  write   read  verify
  --------------------
           #1 ->  #2
    #4 ->  #5 ->  #6
           #7 ->  #8
   #10 -> #11 -> #12

Deriving a weaker capability from a strong one is called "diminishing" the stronger one.

So we use "filecap" to talk about #1..6, but (since most files are immutable)
we're usually talking about #1. We use "dircap" to talk about #7..12.
We use "readcap" to talk about #{1,3,5,7,9,11}, but usually we refer to
#{7,9,11} as a "directory readcap". We use "writecap" to talk about #4 and #10.

A "literal cap" or "LIT cap" stores the contents of a small file (#3) or
directory (#9) in the capability itself.

A "verifycap" is the weakest capability that still allows every bit of every
share to be validated (hashes checked, signatures verified, etc). That means
#{2,6,8,12}.

When we talk about a "repaircap", we mean "the weakest capability that can
still be used to repair the file". Given the current limitations of the
repairer and our webapi, that means we're talking about #{1,4,7,10}.
Eventually we'll fix this limitation, and any verifycap should be useable as
a repaircap too. (There's much less work involved to let #2 repair a file or
#8 repair a directory... it's just an incomplete API, rather than a fundamental
redesign of the server protocol.)

We then use the somewhat-vague term "rootcap" to refer to a cap (usually a
directory write cap) that is not present inside any directory, so the only
way to ever reach it is to remember it somewhere outside of Tahoe. It might
be remembered in the allmydata.com rootcap database (indexed by account name
plus password), or it might be remembered in a ~/.tahoe/private/aliases file,
or it might just be written down on a piece of paper. The point is that you
have to start from somewhere, and we refer to such a starting point as a
"rootcap".

}}}