From e37f8f89b044f769573752dca7b00416299efc15 Mon Sep 17 00:00:00 2001 From: Marius Date: Fri, 11 Mar 2016 21:50:00 +0100 Subject: [PATCH] Improve README's content --- README.md | 57 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 509a43e..f40e0b2 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,10 @@ # tusd -[![Build Status](https://travis-ci.org/tus/tusd.svg?branch=master)](https://travis-ci.org/tus/tusd) -[![Build status](https://ci.appveyor.com/api/projects/status/2y6fa4nyknoxmyc8/branch/master?svg=true)](https://ci.appveyor.com/project/Acconut/tusd/branch/master) +> **tus** is a protocol based on HTTP for *resumable file uploads*. Resumable +> means that an upload can be interrupted at any moment and can be resumed without +> re-uploading the previous data again. An interruption may happen willingly, if +> the user wants to pause, or by accident in case of an network issue or server +> outage. tusd is the official reference implementation of the [tus resumable upload protocol](http://www.tus.io/protocols/resumable-upload.html). The protocol @@ -13,6 +16,14 @@ moment allowing to continue seamlessly after e.g. network interruptions. ## Getting started +### Download pre-builts binaries (recommended) + +You can download ready-to-use packages including binaries for OS X, Linux and +Windows in various formats of the +[latest release](https://github.com/tus/tusd/releases/latest). + +### Compile from source + **Requirements:** * [Go](http://golang.org/doc/install) (1.3 or newer) @@ -35,7 +46,7 @@ go run cmd/tusd/main.go ## Using tusd manually Besides from running tusd using the provided binary, you can embed it into -your own Golang program: +your own Go program: ```go package main @@ -56,20 +67,26 @@ func main() { 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. + // A storage backend for tusd may consist of multiple different parts which + // handle upload creation, locking, termination and so on. The composer is a + // place where all those seperated pieces are joined together. In this example + // we only use the file store but you may plug in multiple. + composer := tusd.NewStoreComposer() + store.UseIn(composer) + + // Create a new HTTP handler for the tusd server by providing a configuration. + // The StoreComposer property must be set to allow the handler to function. handler, err := tusd.NewHandler(tusd.Config{ - BasePath: "files/", - DataStore: store, + BasePath: "files/", + StoreComposer: composer, }) 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 + // Right now, nothing has happened since we need to start the HTTP server on + // our own. In the end, tusd will start listening on and accept request at + // http://localhost:8080/files http.Handle("files/", http.StripPrefix("files/", handler)) err = http.ListenAndServe(":8080", nil) if err != nil { @@ -78,8 +95,8 @@ func main() { } ``` -If you need to customize the GET and DELETE endpoints use -`tusd.NewUnroutedHandler` instead of `tusd.NewHandler`. +Please consult the [online documentation](https://godoc.org/github.com/tus/tusd) +for more details about tusd's APIs and its sub-packages. ## Implementing own storages @@ -95,8 +112,22 @@ interface and using the new struct in the [configuration object](https://godoc.o Please consult the documentation about detailed information about the required methods. +## Packages + +This repository does not only contain the HTTP server's code but also other +useful tools: + +* [**s3store**](https://godoc.org/github.com/tus/tusd/s3store): A storage backend using AWS S3 +* [**filestore**](https://godoc.org/github.com/tus/tusd/filestore): A storage backend using the local file system +* [**memorylocker**](https://godoc.org/github.com/tus/tusd/memorylocker): An in-memory locker for handling concurrent uploads +* [**consullocker**](https://godoc.org/github.com/tus/tusd/consullocker): A locker using the distributed Consul service +* [**limitedstore**](https://godoc.org/github.com/tus/tusd/limitedstore): A storage wrapper limiting the total used space for uploads + ## Running the testsuite +[![Build Status](https://travis-ci.org/tus/tusd.svg?branch=master)](https://travis-ci.org/tus/tusd) +[![Build status](https://ci.appveyor.com/api/projects/status/2y6fa4nyknoxmyc8/branch/master?svg=true)](https://ci.appveyor.com/project/Acconut/tusd/branch/master) + ```bash go test -v ./... ```