add deep-copy function to web API

[warner]

The web API should provide a convenient facility to do a deep copy of everything below a given directory node. The caller should get to choose whether the new tree is made up of mutable RW dirnodes or immutable dirnodes.

This can then be used as a primitive by higher-level applications. When a user indicates to their agent that they want to share a folder with a friend by dragging it from their desktop and dropping it on to their friend's icon, the default mode can be to deep-copy this folder into an immutable tree. This seems like it would provide the least surprising result; whereas if the friend receives an exact reference to the original dirnode, the friend now has write access to anything in that folder or referenced by that folder.

A different GUI action (shift-dragging or something) can be used to indicate that the user wants to share a "live" folder, and the agent should remember that the folder was thus shared, and mark the folder with a little "plugged in" icon (like the old Mac AppleTalk?-shared folders did.. I don't know how they show this these days). It can also remember who you first shared it with.

Once you have one of these read-only copies, you can make a RW deep-copy to be able to write to it again. The act of making the copy should make it clear that you are not setting some sort of non-existent read-write flag on the source folder, but rather you are creating a brand new tree that just happens to have the same files as the original.

I'm not sure what the webapi for this should be.. maybe:

POST /$URI?t=deepcopy-rw -> new-URI POST /$URI?t=deepcopy-ro -> new-URI

although really there are three modes:

• RW: use mutable dirnodes to make a new tree, return the RW cap of the root
• RO: same, but return the RO cap of the root and discard the RW cap
• immutable: use immutable dirnodes to make a new tree, return the root

I think the second case is a waste of CPU cycles, generating RSA keys for every node and then never using them again. On the other hand, we have to build immutable dirnodes before the third option is available to us.

[warner]

The 'tahoe backup' command is currently using readonly dirnodes, since we don't have immutable dirnodes (#607) yet. Also, this ticket is more about a webapi interface than the dirnode format.

[davidsarah]

This operation could also be used to support #835 efficiently.

I don't think the second mode mentioned in this bug's description is needed; the client can always attenuate the write cap to a read cap. But we do now have immutable dirnodes (#607) so the third mode is implementable.

[davidsarah]

WebDAV defines a COPY operation, that is essentially this deep-copy operation when the Depth: infinity header is specified.