Reference server implementation in Go of tus: the open protocol for resumable file uploads
Go to file
Kevin van Zonneveld 154e6a2813 Switch to HCL-based Frey (#63) 2016-09-15 12:49:15 +02:00
.hooks Add pre-create hook for validation before upload creation 2016-07-11 22:40:19 +02:00
.infra Switch to HCL-based Frey (#63) 2016-09-15 12:49:15 +02:00
cmd/tusd Prevent making uploaded file executable for everyone 2016-07-25 20:59:01 +02:00
consullocker Document functions for handling StoreComposers 2016-03-11 20:17:43 +01:00
filestore Prevent making uploaded file executable for everyone 2016-07-25 20:59:01 +02:00
limitedstore Add initial draft of StoreComposr 2016-02-21 23:25:35 +01:00
memorylocker Document functions for handling StoreComposers 2016-03-11 20:17:43 +01:00
prometheuscollector Allow exposing metrics for Prometheus and Co. 2016-05-24 17:04:28 +02:00
s3store Update mocked S3API implementation for tests 2016-08-26 17:14:33 +02:00
uid rewrite tusd 2015-02-01 14:57:57 +01:00
vendor/github.com Remove aws-go-sdk and consul package from vendor directory 2016-08-26 16:20:10 +02:00
.gitignore Ignore Apple's .DS_Store 2016-09-15 10:17:41 +02:00
.gitmodules Remove aws-go-sdk and consul package from vendor directory 2016-08-26 16:20:10 +02:00
.travis.yml Add Go 1.7 to automated tests 2016-08-26 16:30:40 +02:00
LICENSE.txt rewrite tusd 2015-02-01 14:57:57 +01:00
Makefile Switch to HCL-based Frey (#63) 2016-09-15 12:49:15 +02:00
README.md Improve README's content 2016-03-11 21:50:00 +01:00
appveyor.yml Do not run test verbose on AppVeyor 2016-01-17 15:55:00 +01:00
composer.go Document functions for handling StoreComposers 2016-03-11 20:17:43 +01:00
composer.mgo Document functions for handling StoreComposers 2016-03-11 20:17:43 +01:00
composer_test.go Add example for NewStoreComposer() 2016-03-04 22:14:46 +01:00
concat_test.go Add support for Creation With Upload extension 2016-08-28 22:06:37 +02:00
config.go Improve documentation for complete uploads notifications 2016-03-12 22:28:24 +01:00
config_test.go Add tests for Config structure 2016-03-11 20:46:34 +01:00
cors_test.go Use 200 OK in responses for preflight requests 2016-05-10 11:58:43 +02:00
datastore.go Add initial draft of StoreComposr 2016-02-21 23:25:35 +01:00
doc.go Add documentation about using tusd 2016-03-04 22:13:13 +01:00
get_test.go Suggest original filename when downloading 2016-04-19 11:22:32 +02:00
handler.go Embed UnroutedHandler into Handler 2016-03-12 22:01:12 +01:00
handler_test.go Remove unused GetReader function from tests 2016-01-23 22:45:31 +01:00
head_test.go Respond with the correct 200 OK code for HEAD requests 2016-08-28 15:26:12 +02:00
metrics.go Allow OPTIONS and other methods in metrics 2016-05-24 17:27:07 +02:00
options_test.go Add support for Creation With Upload extension 2016-08-28 22:06:37 +02:00
patch_test.go Do not pass chunk for uploaded uploads to data store 2016-04-09 22:09:22 +02:00
post_test.go Add support for Creation With Upload extension 2016-08-28 22:06:37 +02:00
terminate_test.go Add support for Creation With Upload extension 2016-08-28 22:06:37 +02:00
unrouted_handler.go Add support for Creation With Upload extension 2016-08-28 22:06:37 +02:00

README.md

tusd

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

Getting started

You can download ready-to-use packages including binaries for OS X, Linux and Windows in various formats of the latest release.

Compile from source

Requirements:

  • Go (1.3 or newer)

Running tusd from source:

Clone the git repository and cd into it.

git clone git@github.com:tus/tusd.git
cd tusd

Now you can run tusd:

go run cmd/tusd/main.go

Using tusd manually

Besides from running tusd using the provided binary, you can embed it into your own Go program:

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",
	}

	// 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/",
		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 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 {
		panic("Unable to listen: %s", err)
	}
}

Please consult the online documentation for more details about tusd's APIs and its sub-packages.

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 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.DataStore interface and using the new struct in the configuration object. 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: A storage backend using AWS S3
  • filestore: A storage backend using the local file system
  • memorylocker: An in-memory locker for handling concurrent uploads
  • consullocker: A locker using the distributed Consul service
  • limitedstore: A storage wrapper limiting the total used space for uploads

Running the testsuite

Build Status Build status

go test -v ./...

License

This project is licensed under the MIT license, see LICENSE.txt.