Skip to content

Commit

Permalink
Simplified the README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@AdrienCastex
AdrienCastex committed Jun 14, 2017
1 parent 4781457 commit 0bc3801
Showing 1 changed file with 23 additions and 335 deletions.
358 changes: 23 additions & 335 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,365 +7,53 @@
[![License](https://img.shields.io/npm/l/webdav-server.svg)](http://unlicense.org/)
[![npm Version](https://img.shields.io/npm/v/webdav-server.svg)](https://www.npmjs.com/package/webdav-server)

# Index
# Description

* Disclaimer / Project information
* Install
* Usage
* Import
* Create server
* Options
* Sample
* Resources
* Root resource
* Resource creation
* Authentication / Privileges / User management
* User management
* Authentication
* Privileges
* Control the response body type
* Persistence
* Overview
* Example
* Save
* Load
This server can use physical resources (files and folders on a hard drive, for instance), virtual resources (in-memory files and folders), processed/computed resources (for instance a file which provide the content of a remote web page), customized resources (whatever you created, whatever you can imagine), and use all of them on the same server instance. And it's easy to integrate in your JavaScript code!

# Disclaimer / Project information
You can use it to provide human readable content, easily manageable thanks to the WebDAV clients, or use a temporary and virtual file system to share information between running programs, or store crypted documents while still being able to use them as if they were not crypted (take a look at [`cwdav`](https://www.npmjs.com/package/cwdav)), etc...

This is a fully configurable server. You can use you own user manager, your own resources, your own HTTP methods, your own way to save the state of the server, etc... Find more in the [documentation](https://github.com/OpenMarshal/npm-WebDAV-Server/wiki).

# Project information

You can find the documentation [here](https://github.com/OpenMarshal/npm-WebDAV-Server/wiki).

Find more details on the development process at [https://github.com/OpenMarshal/npm-WebDAV-Server/projects/1](https://github.com/OpenMarshal/npm-WebDAV-Server/projects/1).

This project rely upon the [RFC4918](http://www.webdav.org/specs/rfc4918.html).

The full set of the standard WebDAV methods are implemented :
* HEAD (resource ping)
* GET (file get content)
* MKCOL (directory creation)
* PROPFIND (get file information)
* PROPPATCH (set/remove resource properties)
* PUT/POST (set the content of a file and create it if it doesn't exist)
* OPTIONS (list available methods)
* DELETE (delete a resource)
* MOVE (move a resource)
* COPY (copy a resource)
* LOCK/UNLOCK (reserve a resource for use)

This is an active project. Do not hesitate to post an issue if you have an idea or if you encounter a problem.

Currently working on providing a real documentation of the module.
The documentation on this page will lightened. The more complete version will be available [here](https://github.com/OpenMarshal/npm-WebDAV-Server/wiki).

# Install

```bash
npm install webdav-server
```

# Usage
# Quick usage

## Import

### NodeJS
```javascript
const webdav = require('webdav-server')
```

### TypeScript
```typescript
import * as webdav from 'webdav-server'
```

## Create server

### NodeJS / TypeScript
```javascript
const server = new webdav.WebDAVServer(options);
```

*options* is of type `WebDAVServerOptions`. This interface can be found in `webdav.WebDAVServerOptions`

### Options
Key | Default value | Description
-|-|-
requireAuthentification | `false` | Define if your require to be authenticated.
httpAuthentication | `new HTTPBasicAuthentication('default realm')` | Define the object which will provide the authentication method (HTTP : Basic, Digest, custom, etc).
privilegeManager | `new FakePrivilegeManager()` | Allow to check the privileges of the user (grant or restrict access).
rootResource | `new RootResource()` | The root resource to use as `/`.
userManager | `new SimpleUserManager()` | Define the object which will provide the users.
lockTimeout | `3600` | Define the lock timeout.
canChunk | `true` | Define if the server must recreate the full message or if it must keep it splitted (if `false`, `IResource.append(...)` will never be called, only `IResource.write(...)`). Set the value to `false` if you encounter a problem with the order of the content, this feature hasn't been tested enough.
hostname | `'::'` | Define the scope of the listening server.
port | `1900` | The default port to use if no port is specified when calling `server.start()`.
strictMode | `false` | Define if the server must blindly follow the WebDAV RFC (`true`) or allow more flexibility (`false`) (for instance disallow a body in a request which doesn't use a body).
autoSave | `null` | Define an auto-saver to automatically save the state of the server and taking care of any conflict which can happen while writing the persistence file and limit the number of writes when some are not required (3 PUT in a row will lead to 2 writes, the first and last ones) (the GET request, for instance, doesn't lead to a write). The `autoSave` option is an `object` of type : `{ treeFilePath : string, tempTreeFilePath : string, onSaveError ?: (error : Error) => void, streamProvider ?: (inputStream : Writable, callback : (outputStream ?: Writable) => void) => void }`.

## Sample

### NodeJS / TypeScript
```javascript
// Typescript
// TypeScript
import * as webdav from 'webdav-server'
// Javascript
const webdav = require('webdav-server');

// Create a WebDAV server with options
const um = new webdav.SimpleUserManager();
const user = um.addUser('myUsername', 'myPassword', false);

const pm = new webdav.SimplePathPrivilegeManager();
pm.setRights(user, '/', [ 'all' ]);

const server = new webdav.WebDAVServer({
privilegeManager: pm,
userManager: um,
isVerbose: true,
port: 1900
});

// Create a virtual file
var file = new webdav.VirtualFile('testFile.txt');
// Set the content of the virtual file
file.write(true, (e, writer) => {
if(e) throw e;

writer.end('The content of the virtual file.', (e) => {
if(e) throw e;

// Add the virtual resources to the root folder
// Note that you can add resources even when the
// server is running
server.addResourceTree({
r: new webdav.VirtualFolder('testFolder'),
c: [{
r: new webdav.VirtualFolder('test1'),
c: new webdav.VirtualFile('test2')
}, {
r: new webdav.VirtualFolder('test2'),
c: [{
r: new webdav.VirtualFolder('test1'),
c: new webdav.VirtualFile('test2')
},{
r: new webdav.VirtualFolder('test2'),
c: new webdav.VirtualFile('test2')
}]
}]
}, (e) => {
if(e) throw e;

// Start the server
server.start(httpServer => {
console.log('Server started with success on the port : ' + httpServer.address().port);

// [...]

// Stop the server
server.stop(() => {
console.log('Server stopped with success!');
})
});
});
});
})
server.start(() => console.log('READY'));
```

In this example, the resource tree will be the following :
Path|Class
-|-
`/` | RootResource
`/testFile.txt` | VirtualFile
`/testFolder` | VirtualFolder
`/testFolder/testFile2.txt` | PhysicalFile
`/testFolder/testFolder2` | PhysicalFolder

# Resources

There are two kinds of resource provided : the virtual file/folder and the physical file/folder. The virtual resource is a resource you create and keep in memory. The physical resource is a resource present in your current file system.

You can create a custom resource by creating an object or a class which will inherit the members of the IResource class.

The type of a resource can be (class ResourceType) :

-|Is a directory|Is not a directory
-|-|-
**Is a file**|Hibrid|File
**Is not a file**|Directory|NoResource

Here are the differences between the resource types :
-|Hibrid|File|Directory|NoResource
-|-|-|-|-
**Can have content**|yes|yes|no|no
**Can have child resource**|yes|no|yes|no
**Is standard (RFC)**|no|yes|yes|no

## Root resource
More examples at the [example page of the wiki](https://github.com/OpenMarshal/npm-WebDAV-Server/wiki/Examples).

The root resource (`class RootResource`) is a resource which disallow almost everything (no copy, no move, etc), but provides a static root folder. It is instanciated by default if no `option.rootResource` is provided to the constructor of the server. This resource is a virtual resource. That's why, if you create a child through the WebDAV interface (HTTP), it will be a virtual resource.

Method|Must be allowed?||Method|Must be allowed?
-|-|-|-|-
**create** | no || **delete** | no
**moveTo** | no || **rename** | no
**append** | may || **write** | may
**read** | may || **mimeType** | may
**size** | may || **getLocks** | yes
**setLock** | yes || **removeLock** | yes
**canLock** | yes || **getAvailableLocks** | yes
**canRemoveLock** | yes || **getLock** | yes
**addChild** | yes || **removeChild** | yes
**getChildren** | yes || **setProperty** | yes
**getProperty** | yes || **removeProperty** | yes
**getProperties** | yes || **creationDate** | yes
**lastModifiedDate** | may || **webName** | yes
**type** | yes

## Resource creation

When a user create a resource through the WebDAV interface (HTTP), it will inherit the parent file system manager. For instance, if you create a file or a folder as a child of the path `/myFolder` and `myFolder` contains a virtual file system manager, then the file or folder created will be a virtual file or a virtual folder. The same reflection can be made with the physical resources and custom resources. The file system manager is in charge of the creation of the resource object (not to call `.create(...)`, just the object). This way, you can have a behavior for a resource (the resource class itself) and a different behavior for its children (the file system manager).

If you create a resource through the module (for instance in JavaScript), you can add as child of a resource the kind of resource you want. You are limited only by the type of the parent resource and its implementation.

# Authentication / Privileges / User management

## User management

The user management is get through an instance of the class `IUserManager` which provide users of the class `IUser`.

A `IUserManager` class must contains the following public fields :
```typescript
interface IUserManager
{
getUserByName(name : string, callback : (error : Error, user : IUser) => void)
getDefaultUser(callback : (user : IUser) => void)
getUsers(callback : (error : Error, users : IUser[]) => void)
}
```

A `IUser` class must contains the following public fields :
```typescript
interface IUser
{
isAdministrator : boolean
isDefaultUser : boolean
password : string
username : string
}
```

The `IUserManager` class can get a user by name ; it can get the list of all users ; and it can get the default user.

The default user is the user which is given to an unauthentication user. This way, an unauthenticated user will have the privileges of the default user. If the server's option `requireAuthentification` equals `true`, the default user will not be used.

Thanks to the server's option `userManager`, the user manager can be set with a custom instance. This way, you can create a user manager which, for instance, retrieve its users from a database.

## Authentication

The authentication is made through the HTTP authentication system. The standard authentication systems use a HTTP header to get the user credentials.

Thanks to the server's option `httpAuthentication`, it is possible to define the authentication system you want to use, even a custom one.

It musts inherit from the interface `HTTPAuthentication` :
```typescript
interface HTTPAuthentication
{
realm : string

askForAuthentication() : any
getUser(arg : MethodCallArgs, userManager : IUserManager, callback : (error : Error, user : IUser) => void)
}
```

The `askForAuthentication()` method is used by the server to know what headers the method needs to add to its response.

The `getUser()` method is used by the server to get the user of the current request.

There are two authentication system implemented in the modules : `HTTPBasicAuthentication` and `HTTPDigestAuthentication`.

The class `HTTPBasicAuthentication` implements the `Basic` authentication system and is the most commonly used on internet. The class `HTTPDigestAuthentication` implements the `Digest` authentication system and provides a more secure way to authenticate.

## Privileges

The privileges of a user upon a resource is defined by the instance of the interface `IPrivilegeManager` provided in the server's option `privilegeManager`. This object provides a list of methods to tell the server that a resource is accessible by a user or if it is not.

Here is the interface `IPrivilegeManager` :
```typescript
interface IPrivilegeManager
{
canCreate : PrivilegeManagerMethod
canDelete : PrivilegeManagerMethod
canMove : PrivilegeManagerMethod
canRename : PrivilegeManagerMethod
canAppend : PrivilegeManagerMethod
canWrite : PrivilegeManagerMethod
canRead : PrivilegeManagerMethod
canSource : PrivilegeManagerMethod // Allow to access to the source
// of a resource when it is
// requested by the 'source' header
canGetMimeType : PrivilegeManagerMethod
canGetSize : PrivilegeManagerMethod
canListLocks : PrivilegeManagerMethod
canSetLock : PrivilegeManagerMethod
canRemoveLock : PrivilegeManagerMethod
canGetAvailableLocks : PrivilegeManagerMethod
canGetLock : PrivilegeManagerMethod
canAddChild : PrivilegeManagerMethod
canRemoveChild : PrivilegeManagerMethod
canGetChildren : PrivilegeManagerMethod
canSetProperty : PrivilegeManagerMethod
canGetProperty : PrivilegeManagerMethod
canGetProperties : PrivilegeManagerMethod
canRemoveProperty : PrivilegeManagerMethod
canGetCreationDate : PrivilegeManagerMethod
canGetLastModifiedDate : PrivilegeManagerMethod
canGetWebName : PrivilegeManagerMethod
canGetType : PrivilegeManagerMethod
}
```
With :
```typescript
type PrivilegeManagerCallback = (error : Error, hasAccess : boolean) => void;
type PrivilegeManagerMethod = (arg : MethodCallArgs, resource : IResource, callback : PrivilegeManagerCallback) => void
```
The request relative information (the user, the request, etc) are in the `arg` parameter.
# Control the response body type
By default, when there is a body in the WebDAV response, it will be in XML. If there is a `Accept` header in the request with the `json` type as a priority, the result will be in JSON.
# Persistence
## Overview
It is possible to save your architecture using `server.save(...)` and you can reload it with `server.load(...)`.
The serialization/unserialization is made by the file system manager of the resource.
The children of a resource are managed by the server itself, not by the file system manager.
You can save and load while the server is running, but if a request is processing, it may lead to an inconsistent state.
A trick would be to save when a request is completed (`server.afterRequest(...)`).
## Example
### Save
```javascript
server.save((e, data) => {
if(e)
throw e;

fs.writeFile('persistence.data', JSON.stringify(data), (e) => {
if(e)
throw e;

// [...]
})
})
```
### Load
```javascript
fs.readFile('persistence.data', (e, data) => {
if(e)
throw e;

server.load(JSON.parse(data), [
new webdav.PhysicalFSManager(),
new webdav.VirtualFSManager(),
new webdav.RootFSManager()
], (e) => {
if(e)
throw e;

// [...]
});
})
```
More information/possibilities in the [documentation](https://github.com/OpenMarshal/npm-WebDAV-Server/wiki).

0 comments on commit 0bc3801

Please sign in to comment.