mutable files: expose version info to HTTP clients

[warner]

in #328, we overhauled the internal API for mutable files, to make them safe to use for structured data that requires test-and-set semantics. But this is not currently exposed to the webapi: clients using HTTP can only blindly overwrite mutable files, making them unsuitable for carrying more structured data that must be manipulated outside the tahoe node.

I'm not convinced that passing a servermap outside (and back into!) the tahoe node over HTTP is a good idea. Maybe passing a handle to one might be safe.

If you like this ticket, you might also like #906.

[warner]

Zooko and chatted a bit about this tonight. It might be sufficient to pass a single version identifier. Mutable files have a sequence-number / roothash pair which points to a specific version of the file's contents. This does not contain as much information as the full servermap, but it might be enough.

The webapi for this might look like:

• the t=json form of a directory listing could include "version=XYZ" as an extra element in the JSON
• dirnode operations could accept a new argument which provides test-and-set semantics, perhaps "if-old-version-is=XYZ". The webapi protocol would only apply the requested changes if the "current best version" is also described as XYZ
• the human-oriented "wui" could acquire if-old-version-is= arguments on all the buttons it provides. If the directory has been changed between the time the directory page was rendered and the time someone clicks a button, the operation would be rejected with a note encouraging the user to reload the page (and thus get the latest version).

Both mutable files and directories could have a control like this.

[davidsarah]

I don't think that the sequence number alone is sufficient for test-and-set semantics, since there might be different shares with the same sequence number. By 'roothash', do you mean a hash that depends on the contents of the (encrypted and encoded) current version, or one that only depends on which file this is? If the former then a (sequence_number, roothash) pair would be sufficient.

#993 will probably add an internal API to get the sequence number. Should this get the (sequence_number, roothash) pair instead?

[zooko]

"roothash" means the root of the Merkle Tree over the (encrypted) shares of one specific version of the file, so it is sufficient to uniquely identify one version. Yes, everything that talks about "versions" of mutable files should specify the version as a (sequence_number, roothash) tuple.

[daira]

Let's split the more ambitious second and third bullets of comment:2 into a separate ticket and just make this about exposing the sequence number and roothash in t=json and t=info -- otherwise it's too much to implement in one go.

[daira]

Replying to daira:

Let's split the more ambitious second and third bullets of comment:2 into a separate ticket...

Filed as #2040.

[daira]

Okay, so we should represent the version info in some way that can be put in an HTTP query arg without encoding. How about a decimal sequence number, a '.' (which is unreserved in URIs), and a zbase32 hash?