Extension Development
Tahoe has a programmatic API which enables building custom applications on top of the storage infrastructure. This RESTful interface uses HTTP, so extensions can be implemented as separate processes across a network.
- The docs/frontends/webapi.txt document shows how to control a Tahoe node programmatically.
Extension Projects
Extension Implementation Issues
Caching Tips
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.
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-CHK:... : immutable
- URI:DIR-LIT:... : immutable
- URI:DIR:... : mutable, writable
- URI:DIR-RO:... : mutable, not writable
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
The api relies on four HTTP methods defined as per the standard GET, POST, PUT, and DELETE, which map intuitively to storage operations.
Although these are standard HTTP methods, some clients do not offer good support for them.
- The following clients are known to support all methods:
- curl 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:
- 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. For Windows only, a useful debugging proxy for capturing HTTP requests made by browsers and other clients is Fiddler2.
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 URIs in preference to paths.
