= 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-LAFS, 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
           #3
    #4 ->  #5 ->  #6
           #7 ->  #8
           #9
   #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 a Tahoe-LAFS
filesystem. 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".

}}}