Ticket #1552: add-format-docs.darcs.patch

Sun Oct  9 19:55:29 PDT 2011  kevan@isnotajoke.com
  * docs/frontends/webapi.rst: document the format argument

New patches:

[docs/frontends/webapi.rst: document the format argument
kevan@isnotajoke.com**20111010025529
 Ignore-this: 2a7b8d711dc369bd9a23e2853824cfb0
] {
hunk ./docs/frontends/webapi.rst 381
  file is replaced with the data from the HTTP request body. For an
  immutable file, the "offset" parameter is not valid.
 
- When creating a new file, if "mutable=true" is in the query arguments, the
- operation will create a mutable file instead of an immutable one.
+ When creating a new file, you can control the type of file created by
+ specifying a format= argument in the query string. format=mdmf creates an MDMF
+ mutable file. format=sdmf creates an SDMF mutable file. format=chk creates an
+ immutable file. The value of the format argument is case-insensitive. For
+ compatibility with previous versions of Tahoe-LAFS, the webapi will also
+ accept a mutable=true argument in the query string. If mutable=true is given,
+ then the new file will be mutable, and its format will be the default mutable
+ file format, as configured on the Tahoe-LAFS node hosting the webapi server.
+ Use of mutable=true is discouraged; new code should use format= instead of
+ mutable=true.  If neither format= nor mutable=true are given, the
+ newly-created file will be immutable.
 
  This returns the file-cap of the resulting file. If a new file was created
  by this method, the HTTP response code (as dictated by rfc2616) will be set
hunk ./docs/frontends/webapi.rst 407
  attach the file into the filesystem. No directories will be modified by
  this operation. The file-cap is returned as the body of the HTTP response.
 
- If "mutable=true" is in the query arguments, the operation will create a
- mutable file, and return its write-cap in the HTTP respose. The default is
- to create an immutable file, returning the read-cap as a response. If
- you create a mutable file, you can also use the "mutable-type" query
- parameter. If "mutable-type=sdmf", then the mutable file will be created
- in the old SDMF mutable file format. This is desirable for files that
- need to be read by old clients. If "mutable-type=mdmf", then the file
- will be created in the new MDMF mutable file format. MDMF mutable files
- can be downloaded more efficiently, and modified in-place efficiently,
- but are not compatible with older versions of Tahoe-LAFS. If no
- "mutable-type" argument is given, the file is created in whatever
- format was configured in tahoe.cfg.
-
+ This method accepts format= and mutable=true as query string arguments, and
+ interprets those arguments in the same way as the linked forms of PUT
+ described immediately above.
 
 Creating A New Directory
 ------------------------
hunk ./docs/frontends/webapi.rst 423
  filesystem. The "PUT" operation is provided for backwards compatibility:
  new code should use POST.
 
+ This supports a format= argument in the query string. The format=
+ argument, if specified, controls the format of the directory. format=mdmf
+ indicates that the directory should be stored as an MDMF file; format=sdmf
+ indicates that the directory should be stored as an SDMF file. The value of
+ the format= argument is case-insensitive. If no format= argument is
+ given, the directory's format is determined by the default mutable file
+ format, as configured on the Tahoe-LAFS node responding to the request.
+
 ``POST /uri?t=mkdir-with-children``
 
  Create a new directory, populated with a set of child nodes, and return its
hunk ./docs/frontends/webapi.rst 437
  write-cap as the HTTP response body. The new directory is not attached to
  any other directory: the returned write-cap is the only reference to it.
 
+ The format of the directory can be controlled with the format= argument in
+ the query string, as described above.
+
  Initial children are provided as the body of the POST form (this is more
  efficient than doing separate mkdir and set_children operations). If the
  body is empty, the new directory will be empty. If not empty, the body will
hunk ./docs/frontends/webapi.rst 551
 
  If the final directory is created, it will be empty.
 
+ This accepts a format= argument in the query string, which controls the
+ format of the named target directory, if it does not already exist. format=
+ is interpreted in the same way as in the POST /uri?t=mkdir form. Note that
+ format= only controls the format of the named target directory;
+ intermediate directories, if created, are created based on the default
+ mutable type, as configured on the Tahoe-LAFS server responding to the
+ request.
+
  This operation 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; or if it would require changing an immutable directory.
hunk ./docs/frontends/webapi.rst 573
  intermediate mutable directories as necessary. If the final directory is
  created, it will be populated with initial children from the POST request
  body, as described above.
+
+ This accepts a format= argument in the query string, which controls the
+ format of the target directory, if the target directory is created as part
+ of the operation. format= is interpreted in the same way as in the POST/
+ uri?t=mkdir-with-children operation. Note that format= only controls the
+ format of the named target directory; intermediate directories, if created,
+ are created using the default mutable type setting, as configured on the
+ Tahoe-LAFS server responding to the request.
  
  This operation will return an error if a blocking file is present at any of
  the parent names, preventing the server from creating the necessary parent
hunk ./docs/frontends/webapi.rst 605
  Create a new empty mutable directory and attach it to the given existing
  directory. This will create additional intermediate directories as necessary.
 
+ This accepts a format= argument in the query string, which controls the
+ format of the named target directory, if it does not already exist. format=
+ is interpreted in the same way as in the POST /uri?t=mkdir form. Note that
+ format= only controls the format of the named target directory;
+ intermediate directories, if created, are created based on the default
+ mutable type, as configured on the Tahoe-LAFS server responding to the
+ request.
+
  This operation 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, or if it would require changing any immutable directory.
hunk ./docs/frontends/webapi.rst 626
  Like /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=NAME, but the new directory will
  be populated with initial children via the POST request body. This command
  will create additional intermediate mutable directories as necessary.
- 
+
+ This accepts a format= argument in the query string, which controls the
+ format of the target directory, if the target directory is created as part
+ of the operation. format= is interpreted in the same way as in the POST/
+ uri?t=mkdir-with-children operation. Note that format= only controls the
+ format of the named target directory; intermediate directories, if created,
+ are created using the default mutable type setting, as configured on the
+ Tahoe-LAFS server responding to the request.
+
  This operation 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; or if it would require changing an immutable directory; or if
hunk ./docs/frontends/webapi.rst 680
         "ro_uri": file_uri,
         "verify_uri": verify_uri,
         "size": bytes,
-        "mutable": false
+        "mutable": false,
+     "format": "chk"
         } ]
 
  If it is a capability to a directory followed by a path from that directory
hunk ./docs/frontends/webapi.rst 695
         "verify_uri": verify_uri,
         "size": bytes,
         "mutable": false,
+     "format": "chk",
         "metadata": {
           "ctime": 1202777696.7564139,
           "mtime": 1202777696.7564139,
hunk ./docs/frontends/webapi.rst 719
         "ro_uri": read_only_uri,
         "verify_uri": verify_uri,
         "mutable": true,
+     "format": "sdmf",
         "children": {
           "foo.txt": [ "filenode", {
                   "ro_uri": uri,
hunk ./docs/frontends/webapi.rst 1079
  * access caps (URIs): verify-cap, read-cap, write-cap (for mutable objects)
  * check/verify/repair form
  * deep-check/deep-size/deep-stats/manifest (for directories)
- * replace-conents form (for mutable files)
+ * replace-contents form (for mutable files)
 
 
 Creating a Directory
hunk ./docs/frontends/webapi.rst 1099
  /uri/$DIRCAP page. There is a "create directory" button on the Welcome page
  to invoke this action.
 
+ This accepts a format= argument in the query string. Refer to the
+ documentation of the PUT /uri?t=mkdir operation in `Creating A
+ New Directory`_ for information on the behavior of the format= argument.
+
  If "redirect_to_result=true" is not provided (or is given a value of
  "false"), then the HTTP response body will simply be the write-cap of the
  new directory.
hunk ./docs/frontends/webapi.rst 1112
  This creates a new empty directory as a child of the designated SUBDIR. This
  will create additional intermediate directories as necessary.
 
+ This accepts a format= argument in the query string. Refer to the
+ documentation of POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=CHILDNAME in
+ `Creating A New Directory`_ for information on the behavior of the format=
+ argument.
+
  If a "when_done=URL" argument is provided, the HTTP response will cause the
  web browser to redirect to the given URL. This provides a convenient way to
  return the browser to the directory that was just modified. Without a
hunk ./docs/frontends/webapi.rst 1153
  about which storage servers were used for the upload, how long each
  operation took, etc.
 
- If a "mutable=true" argument is provided, the operation will create a
- mutable file, and the response body will contain the write-cap instead of
- the upload results page. The default is to create an immutable file,
- returning the upload results page as a response. If you create a
- mutable file, you may choose to specify the format of that mutable file
- with the "mutable-type" parameter. If "mutable-type=mdmf", then the
- file will be created as an MDMF mutable file. If "mutable-type=sdmf",
- then the file will be created as an SDMF mutable file. If no value is
- specified, the file will be created in whatever format is specified in
- tahoe.cfg.
-
+ This accepts format= and mutable=true query string arguments. Refer to
+ `Writing/Uploading A File`_ for information on the behavior of format= and
+ mutable=true.
 
 ``POST /uri/$DIRCAP/[SUBDIRS../]?t=upload``
 
hunk ./docs/frontends/webapi.rst 1191
  /uri/$DIRCAP/[SUBDIRS../]", it is likely that the parent directory will
  already exist.
 
- If a "mutable=true" argument is provided, any new file that is created will
- be a mutable file instead of an immutable one. <input type="checkbox"
- name="mutable" /> will give the user a way to set this option.
+ This accepts format= and mutable=true query string arguments. Refer to
+ `Writing/Uploading A File`_ for information on the behavior of format= and
+ mutable=true.
 
  If a "when_done=URL" argument is provided, the HTTP response will cause the
  web browser to redirect to the given URL. This provides a convenient way to
}

Context:

[test/test_runner.py: BinTahoe.test_path has rare nondeterministic failures; this patch probably fixes a problem where the actual cause of failure is masked by a string conversion error.
david-sarah@jacaranda.org**20110927225336
 Ignore-this: 6f1ad68004194cc9cea55ace3745e4af
] 
[docs/configuration.rst: add section about the types of node, and clarify when setting web.port enables web-API service. fixes #1444
zooko@zooko.com**20110926203801
 Ignore-this: ab94d470c68e720101a7ff3c207a719e
] 
[TAG allmydata-tahoe-1.9.0a2
warner@lothar.com**20110925234811
 Ignore-this: e9649c58f9c9017a7d55008938dba64f
] 
Patch bundle hash:
0bf59c7eb21cf2d6d01229724790cb192b8ae0b0