wapi: add mkdir-with-children

[warner]

the "tahoe cp -r" command would benefit from this: instead of two operations (mkdir, set-children), we could create the directory in a single frontend call. This would be faster on the backend too, basically create-mutable-file with initial contents, instead of a create-empty-mutable-file followed by a modify.

This API could also be used for immutable dirnodes.

[warner]

The initial children would be provided as a JSON-encoded PUT body or POST field to the existing t=mkdir operation. The syntax for this would be as follows:

Creating A New Directory

POST /uri?t=mkdir PUT /uri?t=mkdir

Create a new directory (either empty or with some initial children) and return its write-cap as the HTTP response body. This does not make the newly created directory visible from the virtual drive. The "PUT" operation is provided for backwards compatibility: new code should use POST.

If the request body of the PUT is empty, the new directory will be empty.

If the request body of the PUT is non-empty, it will be interpreted as a JSON-encoded list of children with which the new directory should be populated. This is more efficient than doing separate mkdir and add-children operations. Each entry in the list should be a list of (child-name, child-URI, metadata-dict). For example, the body could be:

  [["English", "URI:CHK:...", {"ctime": 1226009151}],
   ["Fran\u00e7ais", "URI:DIR2:..", {}],
   ["Espa\u00f1ol", "URI:CHK-RO:..", {}]]

POST /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir PUT /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir

Create new directories as necessary to make sure that the named target ($DIRCAP/SUBDIRS../SUBDIR) is a directory. This will create additional intermediate directories as necessary. If the named target directory already exists, this will make no changes to it.

Initial children can be provided as the request body of the PUT, or as a "children" field of the POST form. In both cases the initial children are provided as a JSON-encoded list of (name, URI, metadata) tuples. If the PUT request body is empty, or if the POST form has no 'children' field, then the new directory will be empty.

This will return an error if a blocking file is present at any of the parent names, preventing the server from creating the necessary parent directory.

The write-cap of the new directory will be returned as the HTTP response body.

POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=NAME

Create a new directory and attach it to the given existing directory. This will create additional intermediate directories as necessary.

Initial children can be provided as a "children" field of the POST form, in a JSON-encoded list of (name, URI, metadata) tuples. If the POST form has no 'children' field, then the new directory will be empty.

The URL of this form points to the parent of the bottom-most new directory, whereas the previous form has a URL that points directly to the bottom-most new directory.

[warner]

I implemented this in 768c76aa5fbe2c7f, using (safer) t=mkdir-with-children instead of (unsafe) just adding an argument to the old t=mkdir (which would cause problems when a new client sent ignored arguments to an old webapi server).

"cp -r" and "tahoe backup" do not yet use this API, though. (see #828 for that part)

[warner]

I just updated t=mkdir-with-children to accept the JSON dictionary of children as the full POST request body, rather than as the children= portion of a multipart/form body. This should be a lot easier to use.

Finally closing this ticket. #828 is still open (to update the CLI commands to use the new API).