[tahoe-dev] different encodings of capabilities

[zooko]

Folks:

We have caps, for example a WriteableSSKFileURI [1] comprises a write  
key and a fingerprint.

We have the encoding of a cap into string form.  This is currently  
implemented with to_string() [2] and init_from_string() [3].  It  
looks like this:

URI:DIR2- 
RO:u5hex69szcwxp6n9468yp66nwy:offjaid5b5f4zi711swapw97xchd4p9r5ayd3fayjr 
fgszshy83o

In working on #115, I'm making it so that if the user cuts and pastes  
a cap into ~/.tahoe/private/root_dir.cap, then the tahoe command-line  
tools will use that cap.

We want the decoding of this cap to be more liberal, so for example  
if the user copies the cap out of their browser's URL widget, then it  
might come out looking like:

URI%3ADIR2-RO%3Au5hex69szcwxp6n9468yp66nwy% 
3Aoffjaid5b5f4zi711swapw97xchd4p9r5ayd3fayjrfgszshy83o/

or even:

http://127.0.0.1:8123/uri/URI%3ADIR2-RO%3Au5hex69szcwxp6n9468yp66nwy% 
3Aoffjaid5b5f4zi711swapw97xchd4p9r5ayd3fayjrfgszshy83o/

I could loosen the init_from_string to accept these, but we would  
prefer tighter constraints on automated production and consumption of  
caps.  Also we eventually want to *emit* caps prefixed with http:// 
127.0.0.1:8123/uri/, in case a human wants to click on it.

This shows how we really need two separate encodings -- one for use  
by computers (such as embedding in another data structure or  
transmitting to a remote computer) and another for use by humans.

For now, I'm going to make to_human_encoding() and  
init_from_human_encoding(), and in the future I hope that we make  
functions like to_computer_encoding() and init_from_computer_encoding 
(), which will hopefully not do ascii-armoring nor include useful-to- 
humans redundancy such as separator chars or spelling out types.   
Eventually, I think we should stop using to_string() and  
init_from_string(), as evolving usage has rendered those methods  
ambiguous.

Regards,

Zooko

[1] http://allmydata.org/trac/tahoe/browser/src/allmydata/uri.py? 
rev=1704#L198
[2] http://allmydata.org/trac/tahoe/browser/src/allmydata/uri.py? 
rev=1704#L218
[3] http://allmydata.org/trac/tahoe/browser/src/allmydata/uri.py? 
rev=1704#L212