Skip to content
This repository has been archived by the owner on Apr 6, 2021. It is now read-only.
/ vfs Public archive

A http friendly stream based vfs system for node.js

Notifications You must be signed in to change notification settings

c9/vfs

Repository files navigation

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

vfs.mkdir(path, options, callback)

Create a directory.

There are no options for this function.

meta in the response is empty.

vfs.rmfile(path, options, callback)

Remove a file

There are no options for this function.

meta in the response is empty.

vfs.rmdir(path, options, callback)

Remove a directory

options can include:

  • options.recursive - (optional, default is false) whether to delete everything within this directory.

meta in the response is empty.

vfs.rename(path, options, callback)

Rename a file or directory

options can include:

  • options.from - the file we want to rename.

meta in the response is empty.

vfs.copy(path, options, callback)

Copy a file

options can include:

  • options.from - the file we want to copy from.

meta in the response is empty.

vfs.symlink(path, options, callback)

Create a symlink

options can include:

  • options.target - The data contents of the symlink

meta in the response is empty.

About

A http friendly stream based vfs system for node.js

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Packages

No packages published