From 97dca3d3254a81d9f1d352a37fbff6b2ec7ab990 Mon Sep 17 00:00:00 2001 From: Marius Date: Wed, 15 Jul 2015 14:40:14 +0200 Subject: [PATCH] Imporive README --- README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 64 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 45909d7..47c0c4d 100644 --- a/README.md +++ b/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). - -This means it is meant for client authors to verify their implementations as -well as server authors who may look at it for inspiration. - -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](http://www.tus.io/protocols/resumable-upload.html). The protocol +specifies a flexible method to upload files to remote servers using HTTP. +The special feature is the ability to pause and resume uploads at any +moment allowing to continue seamlessly after e.g. network interruptions. **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