diff --git a/Capabilities.md b/Capabilities.md index 8523fb4..5d2d482 100644 --- a/Capabilities.md +++ b/Capabilities.md @@ -21,15 +21,16 @@ but updated to take into account literal caps and immutable directories: 12: mutable directory verify capability string URI:DIR2-Verifier: 13: unknown/future capability strings +``` In Tahoe-LAFS, mutable directories are built out of mutable files (a mutable 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: - +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 } @@ -39,27 +40,28 @@ derive #2 (but not the other way around). The full table is: #7 -> #8 } #9 } dircaps #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. +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 "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}. +!#{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 +repairer and our web-API, that means we're talking about !#{1,4,7,10}. +Eventually we'll fix this limitation, and any verifycap should be usable 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 @@ -67,8 +69,6 @@ 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 +`~/.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". - -``` \ No newline at end of file