Implement filedrop as a standalone server

Also improve README.md and library documentation.

Closes #3.

Author: foxcpp

README.md

@@ -6,10 +6,62 @@ filedrop
 [![Issues](https://img.shields.io/github/issues-raw/foxcpp/filedrop.svg?style=flat-square)](https://github.com/foxcpp/filedrop/issues)
 [![License](https://img.shields.io/github/license/foxcpp/filedrop.svg?style=flat-square)](https://github.com/foxcpp/filedrop/blob/master/LICENSE)
 
-Too lightweight file storage server with HTTP API.
+Lightweight file storage server with HTTP API.
 
-**Currently filedrop is implemented only as a library. Sections below also
-document ideas for standalone server. See issue #3.**
+### Features
+- Painless configuration! You don't even have to `rewrite` requests on your reverse proxy!
+- Limits support! Link usage count, file size and storage time.
+- Embeddable! Can run as part of your application.
+
+You can use filedrop either as a standalone server or as a part of your application.
+In former case you want to check `filedropd` subpackage, in later case just
+import `filedrop` package and pass config stucture to `filedrop.New`, returned
+object implements `http.Handler` so you can use it how you like.
+
+### Installation
+
+This repository uses Go 1.11 modules. Things may work with old `GOPATH`
+approach but we don't support it so don't report cryptic compilation errors
+caused by wrong dependency version.
+
+`master` branch contains code from latest (pre-)release. `dev` branch
+contains bleeding-edge code. You probably want to use one of [tagged
+releases](https://github.com/foxcpp/filedrop/releases).
+
+#### SQL drivers
+
+filedrop uses SQL database as a meta-information storage so you need a
+SQL driver for it to use.
+
+When building standalone server you may want to enable one of the
+supported SQL DBMS using build tags:
+* `postgres` for PostgreSQL
+* `sqlite3` for SQLite3
+* `mysql` for MySQL
+
+**Note:** No SQL server support is planned. However if you would like
+to see it - PRs are welcome.
+
+When using filedrop as a library you are given more freedom. Just make
+sure that you import driver you use.
+
+#### Library
+
+Just use `github.com/foxcpp/filedrop` as any other library. Documentation
+is here: [godoc.org](https://godoc.org/github.com/foxcpp/filedrop).
+
+#### Standalone server
+
+See `fildropd` subdirectory. To start server you need a configuration
+file. See example [here](filedrop.example.yml). It should be pretty
+straightforward. Then just pass path to configuration file in
+command-line arguments.
+
+```
+filedropd /etc/filedropd.yml
+```
+
+systemd unit file is included for your convenience.
 
 ### HTTP API
 
@@ -49,27 +101,7 @@ and allow it to be downloaded not more than 10 times.
 
 ### Authorization
 
-filedrop supports very basic access control. Basically, it can execute SQL
-query with contents of `Authorization` header and file name. If query returns 1 - access 
-will be allowed, if query returns 0 or fails - client will get 403.
-
-Also if you are using filedrop as a library, you can instead just pass custom 
-authorization callback. 
-
-See [configuration example](filedrop.example.yml) for details.
-
-### Installation
-
-`go get` or clone this repo and build binary from `filedropd` package. Pass
-path to configuration in first argument. You are perfect.
-
-### Configuration
-
-[Documented example](filedrop.example.yml) is included in repo, check it out.
-
-### Embedding
+When using filedrop as a library you can setup custom callbacks
+for access control.
 
-If your backend server is written in Golang or you are not a big fan of
-microservices architecture - you can run filedrop server as part of your
-program. See [documentation](godocs.org/github.com/foxcpp/filedrop) for
-details.
+See `filedrop.AuthConfig` documentation.

config.go

@@ -3,30 +3,49 @@ package filedrop
 import "net/http"
 
 type LimitsConfig struct {
-	MaxUses      uint `yaml:"max_uses"`
+	// MaxUses is how much much times file can be accessed. Note that it also counts HEAD requests
+	// and incomplete downloads (byte-range requests).
+	// Per-file max-uses parameter can't exceed this value but can be smaller.
+	MaxUses  uint `yaml:"max_uses"`
+
+	// MaxStoreSecs specifies max time for which files will be stored on
+	// filedrop server. Per-file store-secs parameter can't exceed this value but
+	// can be smaller.
 	MaxStoreSecs uint `yaml:"max_store_secs"`
+
+	// MaxFileSize is a maximum file size in bytes that can uploaded to filedrop.
 	MaxFileSize  uint `yaml:"max_file_size"`
 }
 
 type DBConfig struct {
+	// Driver is a database/sql driver name.
 	Driver string `yaml:"driver"`
-	DSN    string `yaml:"dsn"`
+
+	// Data Source Name.
+	DSN  string `yaml:"dsn"`
 }
 
 type AuthConfig struct {
-	//Query string TODO
-
-	// Used only in embedded interface.
+	// Callback is called to check access before processing any request.
+	// If Callback is null, no check will be performed.
 	Callback func(*http.Request) bool `yaml:"omitempty"`
 }
 
 type Config struct {
+	// ListenOn specifies endpoint to listen on in format ADDR:PORT. Used only by filedropd.
+	ListenOn string `yaml:"listen_on"`
+
 	Limits          LimitsConfig `yaml:"limits"`
 	DB              DBConfig     `yaml:"db"`
 	DownloadAuth    AuthConfig   `yaml:"download_auth"`
 	UploadAuth      AuthConfig   `yaml:"upload_auth"`
-	StorageDir      string       `yaml:"storage_dir"`
-	HTTPSDownstream bool         `yaml:"https_downstream"`
+
+	// StorageDir is where files will be saved on disk.
+	StorageDir  string  `yaml:"storage_dir"`
+
+	// HTTPSDownstream specifies whether filedrop should return links with https scheme or not.
+	// Overridden by X-HTTPS-Downstream header.
+	HTTPSDownstream bool `yaml:"https_downstream"`
 
 	// Internal, used only for testing. Always 60 secs in production.
 	CleanupIntervalSecs int `yaml:"-"`

filedropd/.gitignore

@@ -0,0 +1,5 @@
+filedropd
+filedropd.yml
+test.yml
+*.db*
+filedrop

filedropd/filedropd.example.yml

@@ -0,0 +1,37 @@
+# IP:PORT to listen on.
+# Use 0.0.0.0 to listen on all interfaces, however we recommend using
+# reverse proxy for caching and stuff.
+listen_on: "127.0.0.1:8000"
+
+limits:
+  # How much much times file can be accessed. Note that it also counts HEAD requests
+  # and incomplete downloads (byte-range requests).
+  # Per-file max-uses parameter can't exceed this value but can be smaller.
+  max_uses: 60
+
+  # Max time for which files will be stored on filedrop server. Per-file store-secs
+  # parameter can't exceed this value but can be smaller.
+  max_store_secs: 3600
+
+  # Maximum size of file which can be uploaded to filedrop, in bytes.
+  max_file_size: 1073741824
+
+db:
+  # Driver to use for SQL DB (same as build tag you used to enable it).
+  driver: sqlite3
+
+  # Data Source Name, see underlying driver documentation for exact format you should use:
+  # - PostgreSQL https://godoc.org/github.com/lib/pq
+  #   TLDR: `postgres://user:password@address/dbname`
+  # - MySQL https://github.com/go-sql-driver/mysql
+  #   TLDR: `username:password@protocol(address)/dbname`
+  # - SQLite3 https://github.com/mattn/go-sqlite3
+  #   TLDR: `filepath`
+  dsn: /var/lib/filedrop/index.db
+
+# Where files will be saved on disk.
+storage_dir: /var/lib/filedrop
+
+# Specifies whether filedrop should return links with https scheme or not.
+# Overridden by X-HTTPS-Downstream header.
+https_downstream: true

filedropd/filedropd.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=filedrop standalone server
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/filedropd /etc/filedropd.yml
+Restart=on-failure
+DynamicUser=true
+StateDirectory=filedrop
+
+[Install]
+WantedBy=multi-user.target

filedropd/main.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/foxcpp/filedrop"
+	"gopkg.in/yaml.v2"
+)
+
+func main() {
+	if len(os.Args) != 2 {
+		fmt.Println("Usage:", os.Args[0], "<config file>")
+		os.Exit(1)
+	}
+
+	confBlob, err := ioutil.ReadFile(os.Args[1])
+	if err != nil {
+		log.Fatalln("Failed to read config file:", err)
+	}
+
+	config := filedrop.Config{}
+	if err := yaml.Unmarshal(confBlob, &config); err != nil {
+		log.Fatalln("Failed to parse config file:", err)
+	}
+
+	serv, err := filedrop.New(config)
+	if err != nil {
+		log.Fatalln("Failed to start server:", err)
+	}
+
+	go func() {
+		log.Println("Listening on", config.ListenOn + "...")
+		http.ListenAndServe(config.ListenOn, serv)
+	}()
+
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, os.Interrupt, syscall.SIGTERM, syscall.SIGINT, syscall.SIGHUP)
+	<-sig
+}

go.mod

@@ -7,4 +7,5 @@ require (
 	github.com/mattn/go-sqlite3 v1.9.0
 	github.com/pkg/errors v0.8.0
 	google.golang.org/appengine v1.2.0 // indirect
+	gopkg.in/yaml.v2 v2.2.1
 )

go.sum

@@ -13,3 +13,7 @@ golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73r
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 google.golang.org/appengine v1.2.0 h1:S0iUepdCWODXRvtE+gcRDd15L+k+k1AiHlMiMjefH24=
 google.golang.org/appengine v1.2.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.1 h1:mUhvW9EsL+naU5Q3cakzfE91YhliOondGd6ZrsDBHQE=
+gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=

server.go

@@ -19,7 +19,7 @@ import (
 
 var ErrFileDoesntExists = errors.New("file doesn't exists")
 
-// filedrop server structure, implements http.Handler.
+// Main filedrop server structure, implements http.Handler.
 type Server struct {
 	DB          *db
 	Conf        Config
@@ -29,6 +29,10 @@ type Server struct {
 	fileCleanerStopChan chan bool
 }
 
+// Create and initialize new server instance using passed configuration.
+//
+// serv.Logger will be redirected to os.Stderr by default.
+// Created instances should be closed by using serv.Close.
 func New(conf Config) (*Server, error) {
 	s := new(Server)
 	var err error
@@ -138,6 +142,8 @@ func (s *Server) removeFile(tx *sql.Tx, fileUUID string) error {
 	return nil
 }
 
+// OpenFile opens file for reading without any other side-effects
+// applied (such as "link" usage counting).
 func (s *Server) OpenFile(fileUUID string) (io.ReadSeeker, error) {
 	// Just to check validity.
 	_, err := uuid.FromString(fileUUID)
@@ -334,6 +340,10 @@ func (s *Server) serveFile(w http.ResponseWriter, r *http.Request) {
 	http.ServeContent(w, r, fileUUID, time.Time{}, reader)
 }
 
+// ServeHTTP implements http.Handler for filedrop.Server.
+//
+// Note that filedrop code is URL prefix-agnostic, so request URI doesn't
+// matters much.
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.Method == http.MethodPost {
 		s.acceptFile(w, r)