Improve README's content

This commit is contained in:
Marius 2016-03-11 21:50:00 +01:00
parent 2e44bad1b0
commit e37f8f89b0
1 changed files with 44 additions and 13 deletions

View File

@ -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 ./...
```