+== connecting to the tahoe node ==
-Writing "8011" into CLIENTDIR/webport causes the client to run a webserver on
-port 8011. Writing "tcp:8011:interface=127.0.0.1" into CLIENTDIR/webport does
+Writing "8011" into NODEDIR/webport causes the node to run a webserver on
+port 8011. Writing "tcp:8011:interface=127.0.0.1" into NODEDIR/webport does
the same but binds to the loopback interface, ensuring that only the programs
on the local host can connect. Using
"ssl:8011:privateKey=mykey.pem:certKey=cert.pem" would run an SSL server. See
twisted.application.strports for more details.
-If CLIENTDIR/webpassword exists, it will be used (somehow) to require HTTP
-Digest Authentication for all webserver connections.
+If NODEDIR/webpassword exists, it will be used (somehow) to require HTTP
+Digest Authentication for all webserver connections. XXX specify how
-The client provides some small number of "virtual drives". In the 0.5
+== vdrive ==
+
+The node 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.
private/Pictures/tractors.jpg
-== vdrive ==
-
Within the webserver, there is a tree of resources. The top-level "vdrive"
resource gives access to files and directories in all of the user's virtual
drives. For example, the URL that corresponds to notes.txt would be:
-FILEURL = http://localhost:8011/vdrive/global/Documents/notes.txt
+http://localhost:8011/vdrive/global/Documents/notes.txt
and the URL for tractors.jpg would be:
- http://localhost:8011/vdrive/private/Pictures/tractors.jpg
+http://localhost:8011/vdrive/private/Pictures/tractors.jpg
In addition, each directory has a corresponding URL. The Pictures URL is:
-DIRURL = http://localhost:8011/vdrive/private/Pictures
+http://localhost:8011/vdrive/private/Pictures
Now, what can we do with these URLs? By varying the HTTP "method"
(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, 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.
+In the following examples "$URL" is a shorthand for a URL like the ones
+described above. "$NEWURL" is a shorthand for a URL pointing to a location
+in the vdrive where currently nothing exists.
-=== Files and Directories ===
+=== files or directories ===
- GET URL
+ 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
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 URL?t=json
+ GET $URL?t=json
This returns machine-parseable information about the named file or
directory in the HTTP response body. This information contains a flag that
corresponding FILEURL or DIRURL (except that dirnodes do not recurse --
the "children" entry of the child is omitted).
+ DELETE $URL
-=== Files ===
+ This deletes the given file or directory from the vdrive. If it is a
+ directory then this deletes all of its chilren. Note that this *does not*
+ delete any parent directories, so a sequence of 'PUT NEWURL' and 'DELETE
+ NEWURL' does not necessarily return the vdrive to its original state (it
+ may leave some intermediate directory nodes).
- GET FILEURL?t=file
+ GET $URL?t=uri
- 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
+ This returns the URI of the given file or directory in the HTTP response
+ body. If you have read-write access to that resource then this returns a
+ URI which provides read-write access. If you have read-only access to that
+ resource then this returns a URI which provides read-only access.
- PUT NEWFILEURL
+ GET $URL?t=readonly-uri
- This uploads a file to the given place in the vdrive. It will create
- intermediate directory nodes as necessary. The file's contents are taken
- from the body of the HTTP request. For convenience, the HTTP response
- contains the URI that results from uploading the file, although the client
- is not obligated to do anything with the URI. According to the HTTP/1.1
- specification (rfc2616), this should return a 200 (OK) code when modifying
- an existing file, and a 201 (Created) code when creating a new file.
+ This returns the URI providing read-only access to the given file or
+ directory (whether or not you have read-only or read-write access).
+ (Currently all files are immutable so everyone has read-only access to all
+ files.)
- To use this, run 'curl -T localfile http://localhost:8011/vdrive/global/newfile'
+ GET $URL?t=download&localfile=$LOCALPATH
- DELETE FILEURL
+ This instructs the node to download the given file or directory and write
+ it into the local filesystem at $LOCALPATH. This request will only be
+ accepted from an HTTP client connection originating at 127.0.0.1 . This
+ request is most useful when the client node and the HTTP client are
+ operated by the same user. $LOCALPATH should be an absolute pathname.
- This deletes the given file from the vdrive. Note that this *does not*
- delete any parent directories, so a sequence of 'PUT NEWFILEURL' and
- 'DELETE NEWFILEURL' does not necessarily return the vdrive to its original
- state (it may leave some intermediate directory nodes).
+ PUT $NEWURL?t=upload&localfile=$LOCALPATH
- GET FILEURL?t=download&localfile=$FILENAME
+ This uploads a file or directory from the node's local filesystem to the
+ vdrive. As with "GET $URL?t=download&localfile=$LOCALPATH", this request
+ will only be accepted from an HTTP connection originating from 127.0.0.1.
- This instructs the client to download the given file and write its contents
- into the local filesystem at $FILENAME. This request will only be accepted
- from an HTTP client connection originating at 127.0.0.1 . This request is
- most useful when the client node and the HTTP client are operated by the
- same user. $FILENAME should be an absolute pathname.
+ If $LOCALPATH points to a directory on the node's local filesystem, then
+ the node performs a recursive upload of the directory into the vdrive at
+ the given location. $NEWURL will be created if necessary. When the
+ operation is complete, the directory referenced by $NEWURL will contain all
+ of the files and directories that were present in $LOCALPATH, so this is
+ equivalent to the unix commands:
- (thoughts: we could use either the response headers or the response body
- to indicate download progress)
+ mkdir -p $NEWURL; cp -r $LOCALPATH/* $NEWURL/
- PUT NEWFILEURL?t=upload&localfile=$FILENAME
+ Note that the "curl" utility can be used to provoke this sort of recursive
+ upload, since the -T option will make it use an HTTP 'PUT':
- This uploads file to the vdrive and gets the contents from a file in the
- client's local filesystem. As with GET, this request will only be accepted
- from an HTTP connection originating from 127.0.0.1.
+ curl -T /dev/null 'http://localhost:8011/vdrive/global/newdir?t=upload&localdir=/home/user/directory-to-upload'
- (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.
+=== just for files ===
- GET FILEURL?t=readonly-uri
+ GET $URL?t=file
- This also returns the URI of the given file. For now, all files are
- 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.
+ 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 $NEWURL
-=== Directories ===
+ This uploads a file to the given place in the vdrive. It will create
+ intermediate directory nodes as necessary. The file's contents are taken
+ from the body of the HTTP request. For convenience, the HTTP response
+ contains the URI that results from uploading the file, although the node
+ is not obligated to do anything with the URI. According to the HTTP/1.1
+ specification (rfc2616), this should return a 200 (OK) code when modifying
+ an existing file, and a 201 (Created) code when creating a new file.
+
+ To use this, run 'curl -T localfile http://localhost:8011/vdrive/global/newfile'
- GET DIRURL?t=uri
- GET DIRURL?t=readonly-uri
- Return a URI for this dirnode in the HTTP response body. If the dirnode is
- read-only, the t=uri and t=readonly-uri responses will be the same.
+=== just for directories ===
- GET DIRURL?t=manifest
+ GET $URL?t=manifest
Return an HTML-formatted manifest of the given directory, for debugging.
- PUT NEWDIRURL?t=mkdir
+ PUT $NEWURL?t=mkdir
Create a new empty directory at the given path. The HTTP response contains
the URI of the given directory, although the client is not obligated to do
anything with it.
- DELETE DIRURL
-
- This deletes the given directory (and all of its children). Note that this
- *does not* delete any parent directories, so a sequence of 'PUT
- NEWDIRURL?t=mkdir' and 'DELETE NEWDIRURL does not necessarily return the
- vdrive to its original state (it may leave some intermediate directory
- nodes).
-
- GET DIRURL?t=download&localdir=$DIRNAME
-
- This instructs the client to perform a recursive download of the given
- directory and all its descendant files and directories, writing the results
- to the local filesystem starting at DIRNAME.
-
- (thoughts: we could use the response headers or the response body to
- indicate download progress)
-
- PUT NEWDIRURL?t=upload&localdir=$DIRNAME
-
- This instructs the client to perform a recursive upload of a directory on
- the local filesystem into the vdrive at the given location. NEWDIRURL will
- be created if necessary. When the operation is complete, the directory
- referenced by NEWDIRURL will contain all of the files and directories that
- were present in DIRNAME, so this is equivalent to the unix commands:
-
- mkdir -p NEWDIRURL; cp -r DIRNAME/* NEWDIRURL/
-
- Note that the "curl" utility can be used to provoke this sort of recursive
- upload, since the -T option will make it use an HTTP 'PUT':
-
- curl -T /dev/null 'http://localhost:8011/vdrive/global/newdir?t=upload&localdir=/home/user/directory-to-upload'
-
- GET DIRURL?t=rename-form&name=$CHILDNAME
+ GET $URL?t=rename-form&name=$CHILDNAME
- This provides a useful facility to browser-based user interfaces.
- It returns a page containing a form targetting the POST DIRURL t=rename
- functionality listed below, with the provided $CHILDNAME present in the
+ This provides a useful facility to browser-based user interfaces. It
+ returns a page containing a form targetting the "POST $URL t=rename"
+ functionality described below, with the provided $CHILDNAME present in the
'from_name' field of that form. i.e. this presents a form offering to
- rename $CHILDNAME, requesting the new name, and submitting POST rename
+ rename $CHILDNAME, requesting the new name, and submitting POST rename.
-== POST Forms ==
+== POST forms ==
- POST DIRURL
+ POST $URL
t=upload
name=childname (optional)
file=newfile
- This instructs the client to upload a file into the given dirnode. We need
+ This instructs the node to upload a file into the given dirnode. We need
this because forms are the only way for a web browser to upload a file
(browsers do not know how to do PUT or DELETE). The file's contents and the
new child name will be included in the form's arguments. This can only be
used to upload a single file at a time. To avoid confusion, name= is not
allowed to contain a slash (a 400 Bad Request error will result).
- POST DIRURL
+ POST $URL
t=mkdir
name=childname
- This instructs the client to create a new empty directory. The name of the
+ This instructs the node to create a new empty directory. The name of the
new child directory will be included in the form's arguments.
- POST DIRURL
+ POST $URL
t=uri
name=childname
uri=newuri
- This instructs the client to attach a child that is referenced by URI (just
- like the PUT NEWFILEURL?t=uri method). The name and URI of the new child
+ This instructs the node to attach a child that is referenced by URI (just
+ like the PUT $URL?t=uri method). The name and URI of the new child
will be included in the form's arguments.
- POST DIRURL
+ POST $URL
t=delete
name=childname
- This instructs the client to delete a file from the given dirnode. The name
+ This instructs the node to delete a file from the given dirnode. The name
of the child to be deleted will be included in the form's arguments.
- POST DIRURL
+ POST $URL
t=rename
from_name=oldchildname
to_name=newchildname
- This instructs the client to rename a child within the given dirnode. The
+ This instructs the node to rename a child within the given dirnode. The
child specified by 'from_name' is removed, and reattached as a child named
for 'to_name'. This is unconditional and will replace any child already
present under 'to_name', akin to 'mv -f' in unix parlance.
-== URI ==
+== URIs ==
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
+ PUT $URL?t=uri
This attaches a child (either a file or a directory) to the vdrive at the
given location. The URI is provided in the body of the HTTP request. This
projects / tahoe-lafs / tahoe-lafs.git / commitdiff