Simplified the README.md

Author: AdrienCastex

README.md

@@ -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).