Digest Authentication for all webserver connections.
-The client provides some small number of "virtual drives". In the 0.4.0
+The client provides some small number of "virtual drives". In the 0.5
release, this number is two: the first is the global shared vdrive, the
second is the private non-shared vdrive. We will call these "global" and
"private" for now.
(GET/PUT/POST/DELETE) and by appending a type-indicating query argument, we
control how what we want to do with the data and how it should be presented.
-In the following examples, FILEURL and DIRURL are abbreviations for the
+In the following examples, URL, FILEURL and DIRURL are abbreviations for the
previously listed examples. In addition. NEWFILEURL and NEWDIRURL are URLs
for files and directories which do not yet exist.
-=== Files ===
- GET FILEURL
+=== Files and Directories ===
+
+ GET URL
+
+ If the given place in the vdrive contains a file, then this simply
+ retrieves the contents of the file. The Content-Type is set according to
+ the vdrive's metadata (if available) or by using the usual
+ filename-extension-magic built into most webservers. The file's contents
+ are provided in the body of the HTTP response.
+
+ If the given place contains a directory, then this returns an HTML page,
+ intended to be used by humans, which contains HREF links to all files and
+ directories reachable from this dirnode. These HREF links do not have a t=
+ argument, meaning that a human who follows them will get pages also meant
+ for a human. It also contains forms to upload new files, and to delete
+ files and directories. These forms use POST methods to do their job.
- This simply retrives the contents of the file at the given place in the
- vdrive. The Content-Type is set according to the vdrive's metadata (if
- available) or by using the usual filename-extension-magic built into most
- webservers. The file's contents are provided in the body of the HTTP
- response.
+ GET URL?t=json
- (thought: we could conceivably provide some measure of gathering-peers
- progress and pre-plaintext status information by emitting some extra
- X-Tahoe-Status headers. Of course, once the headers are done and we start
- sending plaintext, we have to stop sending such headers)
+ This returns machine-parseable information about the named file or
+ directory in the HTTP response body. This information contains a flag that
+ indicates whether the thing is a file or a directory.
+
+ If it is a file, then the information includes file size, metadata (like
+ Content-Type), and URIs, like this:
+
+ [ 'filenode', { 'mutable': bool, 'uri': file_uri, 'size': bytes } ]
+
+ If it is a directory, then it includes a flag to indicate whether this is a
+ read-write dirnode or a read-only dirnode, and information about the
+ children of this directory, as a mapping from child name to a set of
+ metadata about the child (the same data that would appear in a
+ corresponding GET?t=json of the child itself). Like this:
+
+ [ 'dirnode', { 'mutable': bool, 'uri': uri, 'children': children } ]
+
+ where 'children' is a dictionary in which the keys are child names
+ and the values depend upon whether the child is a file or a directory:
+
+ 'foo.txt': [ 'filenode', { 'mutable': bool, 'uri': uri, 'size': bytes } ]
+ 'subdir': [ 'dirnode', { 'mutable': bool, 'uri': uri } ]
+
+ note that the value is the same as the JSON representation of the
+ corresponding FILEURL or DIRURL (except that dirnodes do not recurse --
+ the "children" entry of the child is omitted).
+
+
+=== Files ===
+
+ GET FILEURL?t=file
+
+ If the given place in the vdrive contains a file, then this simply
+ retrieves the contents of the file, exactly as described in the "GET URL"
+ paragraph of the "Files and Directories" section. If the given place does
+ not contain a file then this returns an error. XYZ specify the error
PUT NEWFILEURL
'DELETE NEWFILEURL' does not necessarily return the vdrive to its original
state (it may leave some intermediate directory nodes).
- GET FILEURL?t=json
-
- This returns machine-parseable information about the file in the HTTP
- response body, including file size, metadata (like Content-Type), and URIs.
- This information is also required to contain a flag that distinguishes
- between files and directories. Programatic clients are expected to use this
- query before actually downloading the file's contents.
-
- The JSON data is as follows:
-
- [ 'filenode', { 'mutable': bool, 'uri': file_uri, 'size': bytes } ]
-
-
GET FILEURL?t=download&localfile=$FILENAME
This instructs the client to download the given file and write its contents
(we could indicate upload progress too. The response body could contain
the URI of the uploaded file)
-
GET FILEURL?t=uri
This returns the URI of the given file in the HTTP response body.
immutable, so t=uri and t=readonly-uri return the same value. In the
future, when we have mutable files, they will return different values.
-=== Directories ===
-
- GET DIRURL
-
- This returns an HTML page, intended to be used by humans, which contains
- HREF links to all files and directories reachable from this dirnode. These
- HREF links do not have a t= argument, meaning that a human who follows them
- will get pages also meant for a human. It also contains forms to upload new
- files, and to delete files and directories. These forms use POST methods to
- do their job.
-
- GET DIRURL?t=json
-
- This returns machine-parseable information about this directory in the HTTP
- response body. This information first contains a flag to indicate that
- DIRURL referenced a directory (as opposed to a file). Then it contains a
- flag to indicate whether this is a read-write dirnode or a read-only
- dirnode. Finally it also contains information about the children of this
- directory, probably as a mapping from child name to a set of metadata about
- the child (basically the same data that would appear in a corresponding
- GET?t=json of the child itself). A programmatic client should be able to use
- the information from this query to display filesystem navigation choices to
- a human user.
-
- The JSON data is as follows:
-
- [ 'dirnode', { 'mutable': bool, 'uri': uri, 'children': children } ]
-
- where 'children' is a dictionary in which the keys are child names
- and the values depend upon whether the child is a file or a directory:
-
- 'foo.txt': [ 'filenode', { 'mutable': bool, 'uri': uri, 'size': bytes } ]
- 'subdir': [ 'dirnode', { 'mutable': bool, 'uri': uri } ]
-
- note that the value is the same as the JSON representation of the
- corresponding FILEURL or DIRURL (except that dirnodes do not recurse).
+=== Directories ===
GET DIRURL?t=uri
GET DIRURL?t=readonly-uri
'from_name' field of that form. i.e. this presents a form offering to
rename $CHILDNAME, requesting the new name, and submitting POST rename
+
== POST Forms ==
POST DIRURL
for 'to_name'. This is unconditional and will replace any child already
present under 'to_name', akin to 'mv -f' in unix parlance.
+
== URI ==
http://localhost:8011/uri/$URI
when URIs are used in this form, they must be specially quoted. All slashes
in the URI must be replaced by '!' characters.
-
PUT NEWFILEURL?t=uri
This attaches a child (either a file or a directory) to the vdrive at the
redirection provided will escape the slashes with exclamation points, as
described above.
+
== XMLRPC ==
http://localhost:8011/xmlrpc
projects / tahoe-lafs / tahoe-lafs.git / commitdiff