• This repository has been archived on 06/Apr/2021
  • Stars
    star
    111
  • Rank 314,510 (Top 7 %)
  • Language
    JavaScript
  • Created over 12 years ago
  • Updated almost 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A http friendly stream based vfs system for node.js

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.

More Repositories

1

core

Cloud9 Core - Part of the Cloud9 SDK for Plugin Development https://c9.github.io/core/ https://c9.io
JavaScript
2,564
star
2

architect

A simple yet powerful plugin system for large-scale node applications
JavaScript
981
star
3

install

Cloud9 SSH installer
Shell
180
star
4

docs.c9.io

The documentation. For Cloud9 IDE.
HTML
90
star
5

smith

Smith is an RPC agent system for Node.JS used in vfs.
JavaScript
82
star
6

smith.io

JavaScript
74
star
7

vfs-local

A VFS implementation for the local file-system.
JavaScript
32
star
8

node-gnu-tools

GNU tools installer for npm
C
27
star
9

vfs-http-adapter

A Restful front-end to a vfs instance
JavaScript
26
star
10

node-bitbucket

node.js library to access the Bitbucket API
JavaScript
26
star
11

c9.ide.language.python

The repository for c9.ide.language.python, a Cloud9 core plugin
JavaScript
23
star
12

templates

Cloud9 Templates
Shell
22
star
13

c9.ide.collab

The repository for c9.ide.collab, a Cloud9 core plugin
JavaScript
15
star
14

node-http-error

Expose HTTP error codes as Error objects
JavaScript
14
star
15

connect-architect

build a connect server using architect plugins
JavaScript
14
star
16

c9.ide.run.debug

The repository for c9.ide.run.debug, a Cloud9 core plugin
JavaScript
13
star
17

c9.ide.run.debug.xdebug

Cloud9 debugger plugin for Xdebug
JavaScript
12
star
18

open-in-c9-extension

JavaScript
12
star
19

vfs-socket

A wrapper to use vfs instances remotely over a socket-like transport.
JavaScript
12
star
20

node-netutil

utils to find free ports in a range, checking if a port is open, etc
JavaScript
12
star
21

c9.ide.run

The repository for c9.ide.run, a Cloud9 core plugin
JavaScript
11
star
22

c9.ide.language.codeintel

The repository for c9.ide.language.codeintel, a Cloud9 core plugin
JavaScript
10
star
23

c9.ide.language.go

The repository for c9.ide.language.go, a Cloud9 core plugin
JavaScript
9
star
24

c9.ide.installer

The repository for c9.ide.installer, a Cloud9 core plugin
JavaScript
7
star
25

google.cloud

Cloud9 + Google Cloud Platform custom integration
JavaScript
7
star
26

vfs-architect

Architect plugins for VFS
JavaScript
7
star
27

c9.ide.ace.repl

The repository for c9.ide.ace.repl, a Cloud9 core plugin
JavaScript
6
star
28

c9.ide.format

The repository for c9.ide.format, a Cloud9 core plugin
JavaScript
6
star
29

c9.ide.language.javascript.tern

The repository for c9.ide.language.javascript.tern, a Cloud9 core plugin
JavaScript
5
star
30

c9.ide.run.build

The repository for c9.ide.run.build, a Cloud9 core plugin
JavaScript
5
star
31

vfs-ftp

A FTP client for vfs
JavaScript
5
star
32

architect-build

A simple utility to package architect apps
JavaScript
5
star
33

c9.ide.language

The repository for c9.ide.language, a Cloud9 core plugin
JavaScript
4
star
34

c9.ide.mount

The repository for c9.ide.mount, a Cloud9 core plugin
JavaScript
4
star
35

c9.ide.language.javascript

The repository for c9.ide.language.javascript, a Cloud9 core plugin
JavaScript
4
star
36

grav

Cloud9 plugin for the grav CMS
JavaScript
4
star
37

c9.ide.preview.browser

The repository for c9.ide.preview.browser, a Cloud9 core plugin
JavaScript
4
star
38

c9.ide.preview.markdown

The repository for c9.ide.preview.markdown, a Cloud9 core plugin
HTML
4
star
39

c9.ide.example

JavaScript
4
star
40

c9.ide.imgeditor

The repository for c9.ide.imgeditor, a Cloud9 core plugin
JavaScript
4
star
41

vfs-nodefs-adapter

A node-style api wrapper around vfs for quick migration of code.
JavaScript
3
star
42

c9.ide.remote

The repository for c9.ide.remote, a Cloud9 core plugin
JavaScript
3
star
43

c9.ide.ace.keymaps

The repository for c9.ide.ace.keymaps, a Cloud9 core plugin
JavaScript
3
star
44

c9.ide.scm

The repository for c9.ide.scm, a Cloud9 core plugin
JavaScript
3
star
45

c9.ide.language.core

The repository for c9.ide.language.core, a Cloud9 core plugin
JavaScript
3
star
46

c9.ide.find

The repository for c9.ide.find, a Cloud9 core plugin
JavaScript
3
star
47

c9.ide.language.javascript.infer

The repository for c9.ide.language.javascript.infer, a Cloud9 core plugin
JavaScript
3
star
48

c9.ide.local

The repository for c9.ide.local, a Cloud9 core plugin
JavaScript
3
star
49

c9.ide.test

The repository for c9.ide.test, a Cloud9 core plugin
JavaScript
3
star
50

c9.ide.preview

The repository for c9.ide.preview, a Cloud9 core plugin
JavaScript
3
star
51

c9.ide.language.html

The repository for c9.ide.language.html, a Cloud9 core plugin
JavaScript
3
star
52

c9.ide.navigate

The repository for c9.ide.navigate, a Cloud9 core plugin
JavaScript
3
star
53

c9.ide.language.javascript.immediate

The repository for c9.ide.language.javascript.immediate, a Cloud9 core plugin
JavaScript
3
star
54

c9.ide.find.infiles

The repository for c9.ide.find.infiles, a Cloud9 core plugin
JavaScript
3
star
55

c9.ide.immediate

The repository for c9.ide.immediate, a Cloud9 core plugin
JavaScript
3
star
56

c9.ide.pubsub

The repository for c9.ide.pubsub, a Cloud9 core plugin
JavaScript
3
star
57

c9.ide.ace.emmet

The repository for c9.ide.ace.emmet, a Cloud9 core plugin
JavaScript
3
star
58

c9.ide.language.html.diff

The repository for c9.ide.language.html.diff, a Cloud9 core plugin
JavaScript
3
star
59

c9.ide.language.css

The repository for c9.ide.language.css, a Cloud9 core plugin
JavaScript
3
star
60

c9.ide.ace.gotoline

The repository for c9.ide.ace.gotoline, a Cloud9 core plugin
JavaScript
2
star
61

c9.ide.ace.statusbar

The repository for c9.ide.ace.statusbar, a Cloud9 core plugin
JavaScript
2
star
62

c9.ide.welcome

The repository for c9.ide.welcome, a Cloud9 core plugin
JavaScript
2
star
63

c9.ide.save

The repository for c9.ide.save, a Cloud9 core plugin
JavaScript
2
star
64

c9.ide.fontawesome

The repository for c9.ide.fontawesome, a Cloud9 core plugin
JavaScript
2
star
65

c9.ide.ace.split

The repository for c9.ide.ace.split, a Cloud9 core plugin
JavaScript
2
star
66

c9.ide.readonly

The repository for c9.ide.readonly, a Cloud9 core plugin
JavaScript
2
star
67

c9.ide.find.replace

The repository for c9.ide.find.replace, a Cloud9 core plugin
JavaScript
2
star
68

c9.ide.recentfiles

The repository for c9.ide.recentfiles, a Cloud9 core plugin
JavaScript
2
star
69

c9.ide.closeconfirmation

The repository for c9.ide.closeconfirmation, a Cloud9 core plugin
JavaScript
2
star
70

c9.ide.openfiles

The repository for c9.ide.openfiles, a Cloud9 core plugin
JavaScript
2
star
71

c9.ide.language.javascript.eslint

The repository for c9.ide.language.javascript.eslint, a Cloud9 core plugin
JavaScript
2
star
72

c9.ide.guide

JavaScript
2
star
73

c9.ide.configuration

The repository for c9.ide.configuration, a Cloud9 core plugin
JavaScript
2
star
74

c9.ide.language.generic

The repository for c9.ide.language.generic, a Cloud9 core plugin
JavaScript
2
star
75

vfs-lint

A simple API lint wrapper for vfs instances.
JavaScript
2
star
76

c9.ide.processlist

The repository for c9.ide.processlist, a Cloud9 core plugin
JavaScript
2
star
77

c9.ide.behaviors

The repository for c9.ide.behaviors, a Cloud9 core plugin
JavaScript
2
star
78

c9.ide.dialog.wizard

The repository for c9.ide.dialog.wizard, a Cloud9 core plugin
JavaScript
2
star
79

c9.automate

The repository for c9.automate, a Cloud9 core plugin
JavaScript
2
star
80

c9.ide.terminal.monitor

The repository for c9.ide.terminal.monitor, a Cloud9 core plugin
JavaScript
2
star
81

c9.ide.ace.stripws

The repository for c9.ide.ace.stripws, a Cloud9 core plugin
JavaScript
2
star
82

c9.ide.undo

The repository for c9.ide.undo, a Cloud9 core plugin
JavaScript
2
star
83

vfs-shell-interop

This module is an extension to VFS which allows shell scripts to talk to VFS agents.
JavaScript
2
star
84

c9.ide.newresource

The repository for c9.ide.newresource, a Cloud9 core plugin
JavaScript
2
star
85

c9.ide.theme.flat

The repository for c9.ide.theme.flat, a Cloud9 core plugin
JavaScript
2
star
86

c9.ide.help.support

The repository for c9.ide.help.support, a Cloud9 core plugin
JavaScript
2
star
87

c9.ide.test.mocha

The repository for c9.ide.test.mocha, a Cloud9 core plugin
JavaScript
2
star
88

open-bitbucket-in-cloud9

Extension to open a BitBucket repository in Cloud9
2
star
89

c9.ide.upload

The repository for c9.ide.upload, a Cloud9 core plugin
JavaScript
2
star
90

c9.ide.language.jsonalyzer

The repository for c9.ide.language.jsonalyzer, a Cloud9 core plugin
JavaScript
2
star
91

c9.ide.threewaymerge

The repository for c9.ide.threewaymerge, a Cloud9 core plugin
JavaScript
2
star