From 6a4e3d93abb18610f956a5c579207fae70e7fcfa Mon Sep 17 00:00:00 2001
From: davidsarah <>
Date: Sun, 4 Apr 2010 15:41:02 +0000
Subject: [PATCH] URI formats for immutable dirs; recommended HTTP debugging
 tools; web browsers don't support PUT/DELETE

[Imported from Trac: page Extensions, version 14]
---
 Extensions.md | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/Extensions.md b/Extensions.md
index 34f920c..044bf9b 100644
--- a/Extensions.md
+++ b/Extensions.md
@@ -15,19 +15,22 @@ see [RelatedProject page](RelatedProjects)
 
 Tahoe URIs may refer to either immutable or mutable content.  URIs for immutable data are simple to cache by mapping the URI to the contents.
 
-Mutability is independent of read-only capabilities.  A read-only capability may refer to mutable content (i.e. *you* can't write to it, but somebody else might be able to).
+A read-only capability is not necessarily immutable.  It may refer to mutable content (i.e. *you* can't write to it, but somebody else might be able to).
 
 To determine the mutability of a URI, parse the second field of the URI (delimited by ':'):
 
- * URI:CHK:...    : immutable
- * URI:LIT:...    : immutable
- * URI:SSK:...    : mutable, writable
- * URI:SSK-RO:... : mutable, not writable
- * URI:DIR:...    : mutable, writable
- * URI:DIR-RO:... : mutable, not writable
+ * URI:CHK:...     : immutable
+ * URI:LIT:...     : immutable
+ * URI:SSK:...     : mutable, writable
+ * URI:SSK-RO:...  : mutable, not writable
+ * URI:DIR-CHK:... : immutable
+ * URI:DIR-LIT:... : immutable
+ * URI:DIR:...     : mutable, writable
+ * URI:DIR-RO:...  : mutable, not writable
 
-Note: Currently most files are immutable, and all directories are mutable, but in the future the node type (file or directory) and the mutability will be independent.  It's a bad idea to rely on the node type to determine mutability.
+Note: Currently most files are immutable, and directories are mutable by default (except those created by `tahoe backup`), but mutable files and immutable directries are possible.  It's a bad idea to rely on the node type to determine mutability.
 
+In Python code that is part of or linked with Tahoe, you should probably avoid parsing the URI yourself. Instead create an `IURI` object using `uri.from_string`, then call `is_mutable()` or `is_readonly()` on the result (note that these will throw an exception if the node `is_unknown()`).
 
 ### HTTP methods
 
@@ -38,13 +41,13 @@ Although these are standard HTTP methods, some clients do not offer good support
    * [curl](http://curl.haxx.se/) is an open source client which supports arbitrary methods with the '-X' option.
    * Python 2.5's stdlib modules (`httplib`, `urllib`) provide good support for arbitrary methods.
  * The following clients do not seem to support either `PUT` and `DELETE`:
-   * ...
- * We have not yet determined if the following have support for arbitrary methods:
-   * Common web browsers. In general, HTML forms can only cause GET and POST operations. Javascript might have more abilities.
+   * Common web browsers. In general, HTML forms can only cause GET and POST operations. `XMLHttpRequest` is similarly restricted, I think.
+
+A good command-line HTTP client (written in Python) that supports making arbitrary HTTP requests is [restez](http://code.google.com/p/restez/). For Windows only, a useful debugging proxy for capturing HTTP requests made by browsers and other clients is [Fiddler2](http://www.fiddler2.com).
 
 ### Race Conditions
 
-Race conditions commonly exist in programs which use traditional directory structure interfaces.  The webapi.txt document describes how to avoid many of these situations by relying on file URI's, instead of their vdrive names.
+Race conditions commonly exist in programs which use traditional directory structure interfaces.  The webapi.txt document describes how to avoid many of these situations by relying on file URIs in preference to paths.
 
 # See Also
 Our [RelatedProject page](RelatedProjects)
\ No newline at end of file