Free the mouse Replay HTTPFS
Home | Changes | Index | Search | Go

HTTPFS

Introduction

The Replay 4000 series uses a simple protocol for filesystem access over HTTP; requests are made using standard GET and POST HTTP requests.

General Form

HTTPFS URLs are in the form http://address/httpfs-command?arguments.

arguments are one or more arguments, separated by ampersands, each of the form name=value.

value may be contained in double quotes, which will be stripped off; these should be used for arguments that may contain special characters, such as filenames. Numeric arguments can be expressed in any format interpretable by strtoul(...,...,0); that is, decimal, octal starting with 0, or hexadecimal starting with 0x.

Visible and Invisible exports

Filesystems exported via HTTPFS come in two varieties, 'visible' and 'invisible'. Visible exports are visible to any client that speaks HTTPFS; invisible exports are only visible to a client whose User-Agent is Replay-HTTPFS/1.

With standard 4000 software, /Photo is the only visible export; /Video and /SnapshotDir are invisible exports.

Encrypted exports

Starting with GaeaSoftware 4.3, HTTPFS exports also come in 'plaintext okay' and 'encryption required' varieties. For encryption required exports, the HTTP query string must really be the HttpEncryptedQuery version of the strings described here. /Video requires encryption; the others don't (but will accept it).

Writable and Read-Only exports

Filesystems are exported either writable or read-only; as the terms imply, commands that modify files or directories fail when applied to filesystems mounted read-only.

With standard 4000 software, /Photo and /SnapshotDir are exported writable. /Video is exported read-only.

Response format

Most commands return a status code on the first line of their response body, a hexadecimal number that's 0 for success or non-zero for failure; the status code is separated from the rest of the body by a newline, and may be a single character 0 or may be longer; use the newline to find the end of it.

The error codes I know of are:

80820005
No such file
80820018
File already exists
80820024
Insufficiant permission

Some commands that don't have any data to return may use HTTP return code 204 rather than 200, indicating there is no body. In this case, there is no status code; I believe you can assume the command succeeded in these cases.

HTTP/1.1 and chunking

The Replay 4000's webserver is an HTTP/1.1 server, and as a client it makes 1.1 requests. When a 1.1 server receives a 1.1 request, it may choose to use Transfer-Encoding: chunked; the Replay server normally does do so.

If chunked encoding is used, then rather than the body being sent in one long batch, it's split into multiple chunks. Each chunk looks like chunk-sizeCRLFchunk-dataCRLF. The chunk-size is a hexadecimal number giving the size of the chunk-data in bytes; it may be followed by a semi-colon and a 'chunk extension'; the Replay's webserver doesn't seem to ever do this. The end of the body is signalled by a chunk-size of 0; following the 0 CRLF there are 0 or more lines of trailer, which should be treated just like HTTP headers, terminated by a final blank CRLF terminated line. The Replay doesn't use trailers, either, so the final chunk can be treated for now as just 0 CRLF CRLF. The Replay is perfectly happy to service HTTP/1.0 requests, which don't allow chunked responses.

Commands

cp

cp copies files.

Arguments:

src Source filename to copy from
dest Destination filename to copy to

create

create creates new files.

Arguments:

name Filename name of file to create

fstat

fstat returns file status.

Arguments:

name Filename name of file to return status for

The response body is a series of newline-separated lines, each of the form name=value. Possible names are:

type Filetype f for file or d for directory
size Filesize size in bytes, for files; always -1 for directories
ctime Creation time file's creation time, in milliseconds since midnight January 1 1970 UTC; divide by 1000 to get a unix-style time_t value. Always returns 0 for directories
perm Permissions contains 'r' for read and 'w' for write; the filesystem's writable status isn't taken into account, and 'w' may be returned even for files which can't actually be written

ls

ls lists files in a directory.

Arguments:

name Directory name name of directory to list

If an invalid directory name is given, the list of exported filesystems is returned instead of an error.

The response body contains just filenames, listed one per newline-terminated line.

mkdir

mkdir creates a directory.

Arguments:

name Directory name name of directory to create

mv

mv renames or moves files.

Arguments:

old Source old name of file
new Destination new name of file

readfile

readfile reads the contents of a file and returns it.

Arguments:

name Filename the name of the file to read from
pos Position byte offset into the file to start reading from; if omitted, reads from the beginning of the file
size Size the number of bytes to read; if omitted, reads to the end of the file

rm

rm deletes files.

Arguments:

name Filename name of file to delete

volinfo

volinfo returns filesystem status.

Arguments:

name Filename name of filesystem to return status for

The response body is a series of newline-separated lines, each of the form name=value.

Possible names are:

cap Capacity the size of the filesystem, in bytes
inuse Used the number of bytes currently in use in the filesystem

writefile

writefile writes contents to a file.

Arguments:

name Filename the name of the file to write to; it must already exist
pos Position a byte offset into the file to start writing to; if omitted, writes to the beginning of the file
size Size the number of bytes to write; if omitted all the data sent is written.

writefile requests must use the POST HTTP method, and the request header must include a Content-Length header giving the size of the body. The request body should be the desired file contents with no encoding or modifications.

-- ToddLarason - 09 Mar 2002


Your post will appear before this form in chronological order (newest at bottom)

Topic HTTPFS . { Edit | Attach | Ref-By | Printable | Diffs | r1.5 | > | r1.4 | > | r1.3 | More }
Revision r1.5 - 01 Apr 2003 - 04:23 GMT - TWikiGuest
Parents: WebHome
Copyright © 2001 by the contributing authors. All material on this collaboration tool is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback.