VFS - Virtual File System

This repo is being broken up into several smaller repos. For example, see vfs-local, vfs-socket and vfs-http-adapter.

This module is a vfs implementation for node.js. Originally it was created for our internal needs at Cloud9IDE. Eventually it grew to be generally useful so we're releasing it here as a general purpose vfs system.

The basic use case for this system is to expose a common http friendly, streaming, filesystem interface. It's doesn't assume http and can be used in other contexts, but it does provide support for http Range requests, ETag based conditional queries, HEAD requests, and file streaming for reading and writing. Also it provides streaming directory listing using weak ETags.

Also included is a connect/stack middleware module that allows mounting these vfs instances and exposing them with a simple RESTful API.

HTTP RESTful Interface

See the docs in the http-adapter for specifics.

https://github.com/c9/vfs-http-adapter

JavaScript Interface

The various vfs implementations all follow the same JavaScript interface so that they are interchangable.

setup(options)

At the top of the module (often the module itself) is a setup function. This takes a single options object as configuration and returns a vfs instance.

Available options vary by module. See the indivual modules for specifics.

Within a vfs, paths are relative to that vfs and files outside that tree cannot be accessed.

All functions have the same signature (path, options, callback(err, meta){}).

path is always the path to the resource in question. It's a virtual path relative to the vfs instance.

vfs.readfile(path, options, callback)

Read a file and stream it's contents.

options can include:

options.etag - the browser sent an If-None-Match header with etag
options.head - the request was a HEAD request
options.range - the request had a Range header, this object can have "start", "end" and/or "etag".

meta in the response can include:

meta.notModified - truthy if the server should send 304 (etag matched)
meta.rangeNotSatisfiable - truthy if the server should send 416
meta.partialContent - object if server should send 206 and contains "start", "end", and "size" needed for the "Content-Range" header.
meta.mime - the mime type of the file
meta.size - the size of the file
meta.etag - the etag of the file (embeds inode, size and mtime)
meta.stream - a readable stream if the response should have a body.

vfs.readdir(path, options, callback)

Read a directory and get a listing of it's contents as JSON. Note the stream is a data stream (already JSON serialized), not an object stream.

options can include:

options.etag - the browser sent an If-None-Match header with etag
options.head - the request was a HEAD request

meta in the response can include:

meta.notModified - truthy if the server should send 304 (etag matched)
meta.etag - The weak etag of the directory (embeds inode, size and mtime)
meta.mime - The mime of the directory "inode/directory"
meta.stream - The json stream (unless options.head was truthy)

The format of the stream is a JSON array with an object for each entry in the directory. Entries contain:

name: the filename
path: the path relative to the vfs root
href: a full href to the resource (useful for the jsonview plugin to enable hyperlinking)
mime: the mime type of the file, this includes directories, symlinks, sockets, etc..
access: An integer bitfield showing the access permissions of the vfs. (4 - read, 2 - write, 1 - execute/search)
size: The size of the file as reported by stat
etag: The etag of this file or directory
link: (optional) The data contents of a symlink if the entry is a symlink.

vfs.stat(path, options, callback)

Returns the file system attributes of a directory or a file and returns it using the same format as the readdir command.

meta in the response can include:

meta.etag - The weak etag of the directory (embeds inode, size and mtime)
meta.mime - The mime of the directory "inode/directory"
name: the filename
path: the path relative to the vfs root
href: a full href to the resource (useful for the jsonview plugin to enable hyperlinking)
access: An integer bitfield showing the access permissions of the vfs. (4 - read, 2 - write, 1 - execute/search)
size: The size of the file as reported by stat
link: (optional) The data contents of a symlink if the entry is a symlink.

vfs.mkfile(path, options, callback)

Saves a file stream to the vfs. Always first creates a tmp file and then renames for atomic writes.

There are no options for this function.

meta in the response can include:

meta.stream - a writable stream to the filesystem.
meta.tmpPath - the actual filepath of the tmpfile