Merge branch 'neXT' of github.com:tus/tusd into neXT

README.md

@@ -4,14 +4,10 @@
 [![Build status](https://ci.appveyor.com/api/projects/status/2y6fa4nyknoxmyc8?svg=true)](https://ci.appveyor.com/project/Acconut/tusd)
 
 tusd is the official reference implementation of the [tus resumable upload
-protocol](http://www.tus.io/protocols/resumable-upload.html).
+protocol](http://www.tus.io/protocols/resumable-upload.html). The protocol
-
+specifies a flexible method to upload files to remote servers using HTTP.
-This means it is meant for client authors to verify their implementations as
+The special feature is the ability to pause and resume uploads at any
-well as server authors who may look at it for inspiration.
+moment allowing to continue seamlessly after e.g. network interruptions.
-
-In the future tusd may be extended with additional functionality to make it
-suitable as a standalone production upload server, but for now this is not a
-priority.
 
 **Protocol version:** 1.0.0
 
@@ -36,6 +32,66 @@ Now you can run tusd:
 go run tusd/main.go
 ```
 
+## Using tusd manually
+
+Besides from running tusd using the provided binary, you can embed it into
+your own Golang program:
+
+```go
+package main
+
+import (
+	"github.com/tus/tusd"
+	"github.com/tus/tusd/filestore"
+	"net/http"
+)
+
+func main() {
+	// Create a new FileStore instance which is responsible for
+	// storing the uploaded file on disk in the specified directory.
+	// If you want to save them on a different medium, for example
+	// a remote FTP server, you can implement your own storage backend
+	// by implementing the tusd.DataStore interface.
+	store := filestore.FileStore{
+		Path: "./uploads",
+	}
+
+	// Create a new HTTP handler for the tusd server by providing
+	// a configuration object. The DataStore property must be set
+	// in order to allow the handler to function.
+	handler, err := tusd.NewHandler(tusd.Config{
+		BasePath:              "files/",
+		DataStore:             store,
+	})
+	if err != nil {
+		panic("Unable to create handler: %s", err)
+	}
+
+	// Right now, nothing has happened since we need to start the
+	// HTTP server on our own. In the end, tusd will listen on
+	// and accept request at http://localhost:8080/files
+	http.Handle("files/", http.StripPrefix("files/", handler))
+	err = http.ListenAndServe(":8080", nil)
+	if err != nil {
+		panic("Unable to listen: %s", err)
+	}
+}
+```
+
+## Implementing own storages
+
+The tusd server is built to be as flexible as possible and to allow the use
+of different upload storage mechanisms. By default the tusd binary includes
+[`filestore`](github.com/tus/tusd/filestore/) which will save every upload
+to a specific directory on disk.
+
+If you have different requirements, you can build your own storage backend
+which will save the files to S3, a remote FTP server or similar. Doing so
+is as simple as implementing the [`tusd.DateStore`](http://godoc.org/github.com/tus/tusd/#DataStore)
+interface and using the new struct in the [configuration object](github.com/tus/tusd/#Config).
+Please consult the documentation about detailed information about the
+required methods.
+
 ## Running the testsuite
 
 ```bash