use go module for dependencies (#594)

mediaapi/README.md

@@ -0,0 +1,27 @@
+# Media API
+
+This server is responsible for serving `/media` requests as per:
+
+http://matrix.org/docs/spec/client_server/r0.2.0.html#id43
+
+## Scaling libraries
+
+### nfnt/resize (default)
+
+Thumbnailing uses https://github.com/nfnt/resize by default which is a pure golang image scaling library relying on image codecs from the standard library. It is ISC-licensed.
+
+It is multi-threaded and uses Lanczos3 so produces sharp images. Using Lanczos3 all the way makes it slower than some other approaches like bimg. (~845ms in total for pre-generating 32x32-crop, 96x96-crop, 320x240-scale, 640x480-scale and 800x600-scale from a given JPEG image on a given machine.)
+
+See the sample below for image quality with nfnt/resize:
+
+![](nfnt-96x96-crop.jpg)
+
+### bimg (uses libvips C library)
+
+Alternatively one can use `gb build -tags bimg` to use bimg from https://github.com/h2non/bimg (MIT-licensed) which uses libvips from https://github.com/jcupitt/libvips (LGPL v2.1+ -licensed). libvips is a C library and must be installed/built separately. See the github page for details. Also note that libvips in turn has dependencies with a selection of FOSS licenses.
+
+bimg and libvips have significantly better performance than nfnt/resize but produce slightly less-sharp images. bimg uses a box filter for downscaling to within about 200% of the target scale and then uses Lanczos3 for the last bit. This is a much faster approach but comes at the expense of sharpness. (~295ms in total for pre-generating 32x32-crop, 96x96-crop, 320x240-scale, 640x480-scale and 800x600-scale from a given JPEG image on a given machine.)
+
+See the sample below for image quality with bimg:
+
+![](bimg-96x96-crop.jpg)

mediaapi/fileutils/fileutils.go

@@ -0,0 +1,191 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package fileutils
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+	"io"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	log "github.com/sirupsen/logrus"
+)
+
+// GetPathFromBase64Hash evaluates the path to a media file from its Base64Hash
+// 3 subdirectories are created for more manageable browsing and use the remainder as the file name.
+// For example, if Base64Hash is 'qwerty', the path will be 'q/w/erty/file'.
+func GetPathFromBase64Hash(base64Hash types.Base64Hash, absBasePath config.Path) (string, error) {
+	if len(base64Hash) < 3 {
+		return "", fmt.Errorf("Invalid filePath (Base64Hash too short - min 3 characters): %q", base64Hash)
+	}
+	if len(base64Hash) > 255 {
+		return "", fmt.Errorf("Invalid filePath (Base64Hash too long - max 255 characters): %q", base64Hash)
+	}
+
+	filePath, err := filepath.Abs(filepath.Join(
+		string(absBasePath),
+		string(base64Hash[0:1]),
+		string(base64Hash[1:2]),
+		string(base64Hash[2:]),
+		"file",
+	))
+	if err != nil {
+		return "", fmt.Errorf("Unable to construct filePath: %q", err)
+	}
+
+	// check if the absolute absBasePath is a prefix of the absolute filePath
+	// if so, no directory escape has occurred and the filePath is valid
+	// Note: absBasePath is already absolute
+	if !strings.HasPrefix(filePath, string(absBasePath)) {
+		return "", fmt.Errorf("Invalid filePath (not within absBasePath %v): %v", absBasePath, filePath)
+	}
+
+	return filePath, nil
+}
+
+// MoveFileWithHashCheck checks for hash collisions when moving a temporary file to its final path based on metadata
+// The final path is based on the hash of the file.
+// If the final path exists and the file size matches, the file does not need to be moved.
+// In error cases where the file is not a duplicate, the caller may decide to remove the final path.
+// Returns the final path of the file, whether it is a duplicate and an error.
+func MoveFileWithHashCheck(tmpDir types.Path, mediaMetadata *types.MediaMetadata, absBasePath config.Path, logger *log.Entry) (types.Path, bool, error) {
+	// Note: in all error and success cases, we need to remove the temporary directory
+	defer RemoveDir(tmpDir, logger)
+	duplicate := false
+	finalPath, err := GetPathFromBase64Hash(mediaMetadata.Base64Hash, absBasePath)
+	if err != nil {
+		return "", duplicate, fmt.Errorf("failed to get file path from metadata: %q", err)
+	}
+
+	var stat os.FileInfo
+	// Note: The double-negative is intentional as os.IsExist(err) != !os.IsNotExist(err).
+	// The functions are error checkers to be used in different cases.
+	if stat, err = os.Stat(finalPath); !os.IsNotExist(err) {
+		duplicate = true
+		if stat.Size() == int64(mediaMetadata.FileSizeBytes) {
+			return types.Path(finalPath), duplicate, nil
+		}
+		return "", duplicate, fmt.Errorf("downloaded file with hash collision but different file size (%v)", finalPath)
+	}
+	err = moveFile(
+		types.Path(filepath.Join(string(tmpDir), "content")),
+		types.Path(finalPath),
+	)
+	if err != nil {
+		return "", duplicate, fmt.Errorf("failed to move file to final destination (%v): %q", finalPath, err)
+	}
+	return types.Path(finalPath), duplicate, nil
+}
+
+// RemoveDir removes a directory and logs a warning in case of errors
+func RemoveDir(dir types.Path, logger *log.Entry) {
+	dirErr := os.RemoveAll(string(dir))
+	if dirErr != nil {
+		logger.WithError(dirErr).WithField("dir", dir).Warn("Failed to remove directory")
+	}
+}
+
+// WriteTempFile writes to a new temporary file
+func WriteTempFile(reqReader io.Reader, maxFileSizeBytes config.FileSizeBytes, absBasePath config.Path) (hash types.Base64Hash, size types.FileSizeBytes, path types.Path, err error) {
+	size = -1
+
+	tmpFileWriter, tmpFile, tmpDir, err := createTempFileWriter(absBasePath)
+	if err != nil {
+		return
+	}
+	defer (func() { err = tmpFile.Close() })()
+
+	// The amount of data read is limited to maxFileSizeBytes. At this point, if there is more data it will be truncated.
+	limitedReader := io.LimitReader(reqReader, int64(maxFileSizeBytes))
+	// Hash the file data. The hash will be returned. The hash is useful as a
+	// method of deduplicating files to save storage, as well as a way to conduct
+	// integrity checks on the file data in the repository.
+	hasher := sha256.New()
+	teeReader := io.TeeReader(limitedReader, hasher)
+	bytesWritten, err := io.Copy(tmpFileWriter, teeReader)
+	if err != nil && err != io.EOF {
+		return
+	}
+
+	err = tmpFileWriter.Flush()
+	if err != nil {
+		return
+	}
+
+	hash = types.Base64Hash(base64.RawURLEncoding.EncodeToString(hasher.Sum(nil)[:]))
+	size = types.FileSizeBytes(bytesWritten)
+	path = tmpDir
+	return
+}
+
+// moveFile attempts to move the file src to dst
+func moveFile(src types.Path, dst types.Path) error {
+	dstDir := filepath.Dir(string(dst))
+
+	err := os.MkdirAll(dstDir, 0770)
+	if err != nil {
+		return fmt.Errorf("Failed to make directory: %q", err)
+	}
+	err = os.Rename(string(src), string(dst))
+	if err != nil {
+		return fmt.Errorf("Failed to move directory: %q", err)
+	}
+	return nil
+}
+
+func createTempFileWriter(absBasePath config.Path) (*bufio.Writer, *os.File, types.Path, error) {
+	tmpDir, err := createTempDir(absBasePath)
+	if err != nil {
+		return nil, nil, "", fmt.Errorf("Failed to create temp dir: %q", err)
+	}
+	writer, tmpFile, err := createFileWriter(tmpDir)
+	if err != nil {
+		return nil, nil, "", fmt.Errorf("Failed to create file writer: %q", err)
+	}
+	return writer, tmpFile, tmpDir, nil
+}
+
+// createTempDir creates a tmp/<random string> directory within baseDirectory and returns its path
+func createTempDir(baseDirectory config.Path) (types.Path, error) {
+	baseTmpDir := filepath.Join(string(baseDirectory), "tmp")
+	if err := os.MkdirAll(baseTmpDir, 0770); err != nil {
+		return "", fmt.Errorf("Failed to create base temp dir: %v", err)
+	}
+	tmpDir, err := ioutil.TempDir(baseTmpDir, "")
+	if err != nil {
+		return "", fmt.Errorf("Failed to create temp dir: %v", err)
+	}
+	return types.Path(tmpDir), nil
+}
+
+// createFileWriter creates a buffered file writer with a new file
+// The caller should flush the writer before closing the file.
+// Returns the file handle as it needs to be closed when writing is complete
+func createFileWriter(directory types.Path) (*bufio.Writer, *os.File, error) {
+	filePath := filepath.Join(string(directory), "content")
+	file, err := os.Create(filePath)
+	if err != nil {
+		return nil, nil, fmt.Errorf("Failed to create file: %v", err)
+	}
+
+	return bufio.NewWriter(file), file, nil
+}

mediaapi/mediaapi.go

@@ -0,0 +1,40 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package mediaapi
+
+import (
+	"github.com/matrix-org/dendrite/clientapi/auth/storage/devices"
+	"github.com/matrix-org/dendrite/common/basecomponent"
+	"github.com/matrix-org/dendrite/mediaapi/routing"
+	"github.com/matrix-org/dendrite/mediaapi/storage"
+	"github.com/matrix-org/gomatrixserverlib"
+	"github.com/sirupsen/logrus"
+)
+
+// SetupMediaAPIComponent sets up and registers HTTP handlers for the MediaAPI
+// component.
+func SetupMediaAPIComponent(
+	base *basecomponent.BaseDendrite,
+	deviceDB *devices.Database,
+) {
+	mediaDB, err := storage.Open(string(base.Cfg.Database.MediaAPI))
+	if err != nil {
+		logrus.WithError(err).Panicf("failed to connect to media db")
+	}
+
+	routing.Setup(
+		base.APIMux, base.Cfg, mediaDB, deviceDB, gomatrixserverlib.NewClient(),
+	)
+}

mediaapi/routing/download.go

@@ -0,0 +1,699 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package routing
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+
+	"github.com/matrix-org/dendrite/clientapi/jsonerror"
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/dendrite/mediaapi/fileutils"
+	"github.com/matrix-org/dendrite/mediaapi/storage"
+	"github.com/matrix-org/dendrite/mediaapi/thumbnailer"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	"github.com/matrix-org/gomatrixserverlib"
+	"github.com/matrix-org/util"
+	"github.com/pkg/errors"
+	log "github.com/sirupsen/logrus"
+)
+
+const mediaIDCharacters = "A-Za-z0-9_=-"
+
+// Note: unfortunately regex.MustCompile() cannot be assigned to a const
+var mediaIDRegex = regexp.MustCompile("[" + mediaIDCharacters + "]+")
+
+// downloadRequest metadata included in or derivable from a download or thumbnail request
+// https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-media-r0-download-servername-mediaid
+// http://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-media-r0-thumbnail-servername-mediaid
+type downloadRequest struct {
+	MediaMetadata      *types.MediaMetadata
+	IsThumbnailRequest bool
+	ThumbnailSize      types.ThumbnailSize
+	Logger             *log.Entry
+}
+
+// Download implements /download amd /thumbnail
+// Files from this server (i.e. origin == cfg.ServerName) are served directly
+// Files from remote servers (i.e. origin != cfg.ServerName) are cached locally.
+// If they are present in the cache, they are served directly.
+// If they are not present in the cache, they are obtained from the remote server and
+// simultaneously served back to the client and written into the cache.
+func Download(
+	w http.ResponseWriter,
+	req *http.Request,
+	origin gomatrixserverlib.ServerName,
+	mediaID types.MediaID,
+	cfg *config.Dendrite,
+	db *storage.Database,
+	client *gomatrixserverlib.Client,
+	activeRemoteRequests *types.ActiveRemoteRequests,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	isThumbnailRequest bool,
+) {
+	dReq := &downloadRequest{
+		MediaMetadata: &types.MediaMetadata{
+			MediaID: mediaID,
+			Origin:  origin,
+		},
+		IsThumbnailRequest: isThumbnailRequest,
+		Logger: util.GetLogger(req.Context()).WithFields(log.Fields{
+			"Origin":  origin,
+			"MediaID": mediaID,
+		}),
+	}
+
+	if dReq.IsThumbnailRequest {
+		width, err := strconv.Atoi(req.FormValue("width"))
+		if err != nil {
+			width = -1
+		}
+		height, err := strconv.Atoi(req.FormValue("height"))
+		if err != nil {
+			height = -1
+		}
+		dReq.ThumbnailSize = types.ThumbnailSize{
+			Width:        width,
+			Height:       height,
+			ResizeMethod: strings.ToLower(req.FormValue("method")),
+		}
+		dReq.Logger.WithFields(log.Fields{
+			"RequestedWidth":        dReq.ThumbnailSize.Width,
+			"RequestedHeight":       dReq.ThumbnailSize.Height,
+			"RequestedResizeMethod": dReq.ThumbnailSize.ResizeMethod,
+		})
+	}
+
+	// request validation
+	if req.Method != http.MethodGet {
+		dReq.jsonErrorResponse(w, util.JSONResponse{
+			Code: http.StatusMethodNotAllowed,
+			JSON: jsonerror.Unknown("request method must be GET"),
+		})
+		return
+	}
+
+	if resErr := dReq.Validate(); resErr != nil {
+		dReq.jsonErrorResponse(w, *resErr)
+		return
+	}
+
+	metadata, err := dReq.doDownload(
+		req.Context(), w, cfg, db, client,
+		activeRemoteRequests, activeThumbnailGeneration,
+	)
+	if err != nil {
+		// TODO: Handle the fact we might have started writing the response
+		dReq.jsonErrorResponse(w, util.ErrorResponse(err))
+		return
+	}
+
+	if metadata == nil {
+		dReq.jsonErrorResponse(w, util.JSONResponse{
+			Code: http.StatusNotFound,
+			JSON: jsonerror.NotFound("File not found"),
+		})
+		return
+	}
+
+}
+
+func (r *downloadRequest) jsonErrorResponse(w http.ResponseWriter, res util.JSONResponse) {
+	// Marshal JSON response into raw bytes to send as the HTTP body
+	resBytes, err := json.Marshal(res.JSON)
+	if err != nil {
+		r.Logger.WithError(err).Error("Failed to marshal JSONResponse")
+		// this should never fail to be marshalled so drop err to the floor
+		res = util.MessageResponse(http.StatusInternalServerError, "Internal Server Error")
+		resBytes, _ = json.Marshal(res.JSON)
+	}
+
+	// Set status code and write the body
+	w.WriteHeader(res.Code)
+	r.Logger.WithField("code", res.Code).Infof("Responding (%d bytes)", len(resBytes))
+
+	// we don't really care that much if we fail to write the error response
+	w.Write(resBytes) // nolint: errcheck
+}
+
+// Validate validates the downloadRequest fields
+func (r *downloadRequest) Validate() *util.JSONResponse {
+	if !mediaIDRegex.MatchString(string(r.MediaMetadata.MediaID)) {
+		return &util.JSONResponse{
+			Code: http.StatusNotFound,
+			JSON: jsonerror.NotFound(fmt.Sprintf("mediaId must be a non-empty string using only characters in %v", mediaIDCharacters)),
+		}
+	}
+	// Note: the origin will be validated either by comparison to the configured server name of this homeserver
+	// or by a DNS SRV record lookup when creating a request for remote files
+	if r.MediaMetadata.Origin == "" {
+		return &util.JSONResponse{
+			Code: http.StatusNotFound,
+			JSON: jsonerror.NotFound("serverName must be a non-empty string"),
+		}
+	}
+
+	if r.IsThumbnailRequest {
+		if r.ThumbnailSize.Width <= 0 || r.ThumbnailSize.Height <= 0 {
+			return &util.JSONResponse{
+				Code: http.StatusBadRequest,
+				JSON: jsonerror.Unknown("width and height must be greater than 0"),
+			}
+		}
+		// Default method to scale if not set
+		if r.ThumbnailSize.ResizeMethod == "" {
+			r.ThumbnailSize.ResizeMethod = types.Scale
+		}
+		if r.ThumbnailSize.ResizeMethod != types.Crop && r.ThumbnailSize.ResizeMethod != types.Scale {
+			return &util.JSONResponse{
+				Code: http.StatusBadRequest,
+				JSON: jsonerror.Unknown("method must be one of crop or scale"),
+			}
+		}
+	}
+	return nil
+}
+
+func (r *downloadRequest) doDownload(
+	ctx context.Context,
+	w http.ResponseWriter,
+	cfg *config.Dendrite,
+	db *storage.Database,
+	client *gomatrixserverlib.Client,
+	activeRemoteRequests *types.ActiveRemoteRequests,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+) (*types.MediaMetadata, error) {
+	// check if we have a record of the media in our database
+	mediaMetadata, err := db.GetMediaMetadata(
+		ctx, r.MediaMetadata.MediaID, r.MediaMetadata.Origin,
+	)
+	if err != nil {
+		return nil, errors.Wrap(err, "error querying the database")
+	}
+	if mediaMetadata == nil {
+		if r.MediaMetadata.Origin == cfg.Matrix.ServerName {
+			// If we do not have a record and the origin is local, the file is not found
+			return nil, nil
+		}
+		// If we do not have a record and the origin is remote, we need to fetch it and respond with that file
+		resErr := r.getRemoteFile(
+			ctx, client, cfg, db, activeRemoteRequests, activeThumbnailGeneration,
+		)
+		if resErr != nil {
+			return nil, resErr
+		}
+	} else {
+		// If we have a record, we can respond from the local file
+		r.MediaMetadata = mediaMetadata
+	}
+	return r.respondFromLocalFile(
+		ctx, w, cfg.Media.AbsBasePath, activeThumbnailGeneration,
+		cfg.Media.MaxThumbnailGenerators, db,
+		cfg.Media.DynamicThumbnails, cfg.Media.ThumbnailSizes,
+	)
+}
+
+// respondFromLocalFile reads a file from local storage and writes it to the http.ResponseWriter
+// If no file was found then returns nil, nil
+func (r *downloadRequest) respondFromLocalFile(
+	ctx context.Context,
+	w http.ResponseWriter,
+	absBasePath config.Path,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	dynamicThumbnails bool,
+	thumbnailSizes []config.ThumbnailSize,
+) (*types.MediaMetadata, error) {
+	filePath, err := fileutils.GetPathFromBase64Hash(r.MediaMetadata.Base64Hash, absBasePath)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to get file path from metadata")
+	}
+	file, err := os.Open(filePath)
+	defer file.Close() // nolint: errcheck, staticcheck, megacheck
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to open file")
+	}
+	stat, err := file.Stat()
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to stat file")
+	}
+
+	if r.MediaMetadata.FileSizeBytes > 0 && int64(r.MediaMetadata.FileSizeBytes) != stat.Size() {
+		r.Logger.WithFields(log.Fields{
+			"fileSizeDatabase": r.MediaMetadata.FileSizeBytes,
+			"fileSizeDisk":     stat.Size(),
+		}).Warn("File size in database and on-disk differ.")
+		return nil, errors.New("file size in database and on-disk differ")
+	}
+
+	var responseFile *os.File
+	var responseMetadata *types.MediaMetadata
+	if r.IsThumbnailRequest {
+		thumbFile, thumbMetadata, resErr := r.getThumbnailFile(
+			ctx, types.Path(filePath), activeThumbnailGeneration, maxThumbnailGenerators,
+			db, dynamicThumbnails, thumbnailSizes,
+		)
+		if thumbFile != nil {
+			defer thumbFile.Close() // nolint: errcheck
+		}
+		if resErr != nil {
+			return nil, resErr
+		}
+		if thumbFile == nil {
+			r.Logger.WithFields(log.Fields{
+				"UploadName":    r.MediaMetadata.UploadName,
+				"Base64Hash":    r.MediaMetadata.Base64Hash,
+				"FileSizeBytes": r.MediaMetadata.FileSizeBytes,
+				"ContentType":   r.MediaMetadata.ContentType,
+			}).Info("No good thumbnail found. Responding with original file.")
+			responseFile = file
+			responseMetadata = r.MediaMetadata
+		} else {
+			r.Logger.Info("Responding with thumbnail")
+			responseFile = thumbFile
+			responseMetadata = thumbMetadata.MediaMetadata
+		}
+	} else {
+		r.Logger.WithFields(log.Fields{
+			"UploadName":    r.MediaMetadata.UploadName,
+			"Base64Hash":    r.MediaMetadata.Base64Hash,
+			"FileSizeBytes": r.MediaMetadata.FileSizeBytes,
+			"ContentType":   r.MediaMetadata.ContentType,
+		}).Info("Responding with file")
+		responseFile = file
+		responseMetadata = r.MediaMetadata
+	}
+
+	w.Header().Set("Content-Type", string(responseMetadata.ContentType))
+	w.Header().Set("Content-Length", strconv.FormatInt(int64(responseMetadata.FileSizeBytes), 10))
+	contentSecurityPolicy := "default-src 'none';" +
+		" script-src 'none';" +
+		" plugin-types application/pdf;" +
+		" style-src 'unsafe-inline';" +
+		" object-src 'self';"
+	w.Header().Set("Content-Security-Policy", contentSecurityPolicy)
+
+	if _, err := io.Copy(w, responseFile); err != nil {
+		return nil, errors.Wrap(err, "failed to copy from cache")
+	}
+	return responseMetadata, nil
+}
+
+// Note: Thumbnail generation may be ongoing asynchronously.
+// If no thumbnail was found then returns nil, nil, nil
+func (r *downloadRequest) getThumbnailFile(
+	ctx context.Context,
+	filePath types.Path,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	dynamicThumbnails bool,
+	thumbnailSizes []config.ThumbnailSize,
+) (*os.File, *types.ThumbnailMetadata, error) {
+	var thumbnail *types.ThumbnailMetadata
+	var err error
+
+	if dynamicThumbnails {
+		thumbnail, err = r.generateThumbnail(
+			ctx, filePath, r.ThumbnailSize, activeThumbnailGeneration,
+			maxThumbnailGenerators, db,
+		)
+		if err != nil {
+			return nil, nil, err
+		}
+	}
+	// If dynamicThumbnails is true but there are too many thumbnails being actively generated, we can fall back
+	// to trying to use a pre-generated thumbnail
+	if thumbnail == nil {
+		var thumbnails []*types.ThumbnailMetadata
+		thumbnails, err = db.GetThumbnails(
+			ctx, r.MediaMetadata.MediaID, r.MediaMetadata.Origin,
+		)
+		if err != nil {
+			return nil, nil, errors.Wrap(err, "error looking up thumbnails")
+		}
+
+		// If we get a thumbnailSize, a pre-generated thumbnail would be best but it is not yet generated.
+		// If we get a thumbnail, we're done.
+		var thumbnailSize *types.ThumbnailSize
+		thumbnail, thumbnailSize = thumbnailer.SelectThumbnail(r.ThumbnailSize, thumbnails, thumbnailSizes)
+		// If dynamicThumbnails is true and we are not over-loaded then we would have generated what was requested above.
+		// So we don't try to generate a pre-generated thumbnail here.
+		if thumbnailSize != nil && !dynamicThumbnails {
+			r.Logger.WithFields(log.Fields{
+				"Width":        thumbnailSize.Width,
+				"Height":       thumbnailSize.Height,
+				"ResizeMethod": thumbnailSize.ResizeMethod,
+			}).Info("Pre-generating thumbnail for immediate response.")
+			thumbnail, err = r.generateThumbnail(
+				ctx, filePath, *thumbnailSize, activeThumbnailGeneration,
+				maxThumbnailGenerators, db,
+			)
+			if err != nil {
+				return nil, nil, err
+			}
+		}
+	}
+	if thumbnail == nil {
+		return nil, nil, nil
+	}
+	r.Logger = r.Logger.WithFields(log.Fields{
+		"Width":         thumbnail.ThumbnailSize.Width,
+		"Height":        thumbnail.ThumbnailSize.Height,
+		"ResizeMethod":  thumbnail.ThumbnailSize.ResizeMethod,
+		"FileSizeBytes": thumbnail.MediaMetadata.FileSizeBytes,
+		"ContentType":   thumbnail.MediaMetadata.ContentType,
+	})
+	thumbPath := string(thumbnailer.GetThumbnailPath(types.Path(filePath), thumbnail.ThumbnailSize))
+	thumbFile, err := os.Open(string(thumbPath))
+	if err != nil {
+		thumbFile.Close() // nolint: errcheck
+		return nil, nil, errors.Wrap(err, "failed to open file")
+	}
+	thumbStat, err := thumbFile.Stat()
+	if err != nil {
+		thumbFile.Close() // nolint: errcheck
+		return nil, nil, errors.Wrap(err, "failed to stat file")
+	}
+	if types.FileSizeBytes(thumbStat.Size()) != thumbnail.MediaMetadata.FileSizeBytes {
+		thumbFile.Close() // nolint: errcheck
+		return nil, nil, errors.New("thumbnail file sizes on disk and in database differ")
+	}
+	return thumbFile, thumbnail, nil
+}
+
+func (r *downloadRequest) generateThumbnail(
+	ctx context.Context,
+	filePath types.Path,
+	thumbnailSize types.ThumbnailSize,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+) (*types.ThumbnailMetadata, error) {
+	r.Logger.WithFields(log.Fields{
+		"Width":        thumbnailSize.Width,
+		"Height":       thumbnailSize.Height,
+		"ResizeMethod": thumbnailSize.ResizeMethod,
+	})
+	busy, err := thumbnailer.GenerateThumbnail(
+		ctx, filePath, thumbnailSize, r.MediaMetadata,
+		activeThumbnailGeneration, maxThumbnailGenerators, db, r.Logger,
+	)
+	if err != nil {
+		return nil, errors.Wrap(err, "error creating thumbnail")
+	}
+	if busy {
+		return nil, nil
+	}
+	var thumbnail *types.ThumbnailMetadata
+	thumbnail, err = db.GetThumbnail(
+		ctx, r.MediaMetadata.MediaID, r.MediaMetadata.Origin,
+		thumbnailSize.Width, thumbnailSize.Height, thumbnailSize.ResizeMethod,
+	)
+	if err != nil {
+		return nil, errors.Wrap(err, "error looking up thumbnail")
+	}
+	return thumbnail, nil
+}
+
+// getRemoteFile fetches the remote file and caches it locally
+// A hash map of active remote requests to a struct containing a sync.Cond is used to only download remote files once,
+// regardless of how many download requests are received.
+// Note: The named errorResponse return variable is used in a deferred broadcast of the metadata and error response to waiting goroutines.
+func (r *downloadRequest) getRemoteFile(
+	ctx context.Context,
+	client *gomatrixserverlib.Client,
+	cfg *config.Dendrite,
+	db *storage.Database,
+	activeRemoteRequests *types.ActiveRemoteRequests,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+) (errorResponse error) {
+	// Note: getMediaMetadataFromActiveRequest uses mutexes and conditions from activeRemoteRequests
+	mediaMetadata, resErr := r.getMediaMetadataFromActiveRequest(activeRemoteRequests)
+	if resErr != nil {
+		return resErr
+	} else if mediaMetadata != nil {
+		// If we got metadata from an active request, we can respond from the local file
+		r.MediaMetadata = mediaMetadata
+	} else {
+		// Note: This is an active request that MUST broadcastMediaMetadata to wake up waiting goroutines!
+		// Note: broadcastMediaMetadata uses mutexes and conditions from activeRemoteRequests
+		defer func() {
+			// Note: errorResponse is the named return variable so we wrap this in a closure to re-evaluate the arguments at defer-time
+			if err := recover(); err != nil {
+				r.broadcastMediaMetadata(activeRemoteRequests, errors.New("paniced"))
+				panic(err)
+			}
+			r.broadcastMediaMetadata(activeRemoteRequests, errorResponse)
+		}()
+
+		// check if we have a record of the media in our database
+		mediaMetadata, err := db.GetMediaMetadata(
+			ctx, r.MediaMetadata.MediaID, r.MediaMetadata.Origin,
+		)
+		if err != nil {
+			return errors.Wrap(err, "error querying the database.")
+		}
+
+		if mediaMetadata == nil {
+			// If we do not have a record, we need to fetch the remote file first and then respond from the local file
+			err := r.fetchRemoteFileAndStoreMetadata(
+				ctx, client,
+				cfg.Media.AbsBasePath, *cfg.Media.MaxFileSizeBytes, db,
+				cfg.Media.ThumbnailSizes, activeThumbnailGeneration,
+				cfg.Media.MaxThumbnailGenerators,
+			)
+			if err != nil {
+				return errors.Wrap(err, "error querying the database.")
+			}
+		} else {
+			// If we have a record, we can respond from the local file
+			r.MediaMetadata = mediaMetadata
+		}
+	}
+	return nil
+}
+
+func (r *downloadRequest) getMediaMetadataFromActiveRequest(activeRemoteRequests *types.ActiveRemoteRequests) (*types.MediaMetadata, error) {
+	// Check if there is an active remote request for the file
+	mxcURL := "mxc://" + string(r.MediaMetadata.Origin) + "/" + string(r.MediaMetadata.MediaID)
+
+	activeRemoteRequests.Lock()
+	defer activeRemoteRequests.Unlock()
+
+	if activeRemoteRequestResult, ok := activeRemoteRequests.MXCToResult[mxcURL]; ok {
+		r.Logger.Info("Waiting for another goroutine to fetch the remote file.")
+
+		// NOTE: Wait unlocks and locks again internally. There is still a deferred Unlock() that will unlock this.
+		activeRemoteRequestResult.Cond.Wait()
+		if activeRemoteRequestResult.Error != nil {
+			return nil, activeRemoteRequestResult.Error
+		}
+
+		if activeRemoteRequestResult.MediaMetadata == nil {
+			return nil, nil
+		}
+
+		return activeRemoteRequestResult.MediaMetadata, nil
+	}
+
+	// No active remote request so create one
+	activeRemoteRequests.MXCToResult[mxcURL] = &types.RemoteRequestResult{
+		Cond: &sync.Cond{L: activeRemoteRequests},
+	}
+
+	return nil, nil
+}
+
+// broadcastMediaMetadata broadcasts the media metadata and error response to waiting goroutines
+// Only the owner of the activeRemoteRequestResult for this origin and media ID should call this function.
+func (r *downloadRequest) broadcastMediaMetadata(activeRemoteRequests *types.ActiveRemoteRequests, err error) {
+	activeRemoteRequests.Lock()
+	defer activeRemoteRequests.Unlock()
+	mxcURL := "mxc://" + string(r.MediaMetadata.Origin) + "/" + string(r.MediaMetadata.MediaID)
+	if activeRemoteRequestResult, ok := activeRemoteRequests.MXCToResult[mxcURL]; ok {
+		r.Logger.Info("Signalling other goroutines waiting for this goroutine to fetch the file.")
+		activeRemoteRequestResult.MediaMetadata = r.MediaMetadata
+		activeRemoteRequestResult.Error = err
+		activeRemoteRequestResult.Cond.Broadcast()
+	}
+	delete(activeRemoteRequests.MXCToResult, mxcURL)
+}
+
+// fetchRemoteFileAndStoreMetadata fetches the file from the remote server and stores its metadata in the database
+func (r *downloadRequest) fetchRemoteFileAndStoreMetadata(
+	ctx context.Context,
+	client *gomatrixserverlib.Client,
+	absBasePath config.Path,
+	maxFileSizeBytes config.FileSizeBytes,
+	db *storage.Database,
+	thumbnailSizes []config.ThumbnailSize,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+) error {
+	finalPath, duplicate, err := r.fetchRemoteFile(
+		ctx, client, absBasePath, maxFileSizeBytes,
+	)
+	if err != nil {
+		return err
+	}
+
+	r.Logger.WithFields(log.Fields{
+		"Base64Hash":    r.MediaMetadata.Base64Hash,
+		"UploadName":    r.MediaMetadata.UploadName,
+		"FileSizeBytes": r.MediaMetadata.FileSizeBytes,
+		"ContentType":   r.MediaMetadata.ContentType,
+	}).Info("Storing file metadata to media repository database")
+
+	// FIXME: timeout db request
+	if err := db.StoreMediaMetadata(ctx, r.MediaMetadata); err != nil {
+		// If the file is a duplicate (has the same hash as an existing file) then
+		// there is valid metadata in the database for that file. As such we only
+		// remove the file if it is not a duplicate.
+		if !duplicate {
+			finalDir := filepath.Dir(string(finalPath))
+			fileutils.RemoveDir(types.Path(finalDir), r.Logger)
+		}
+		// NOTE: It should really not be possible to fail the uniqueness test here so
+		// there is no need to handle that separately
+		return errors.New("failed to store file metadata in DB")
+	}
+
+	go func() {
+		busy, err := thumbnailer.GenerateThumbnails(
+			context.Background(), finalPath, thumbnailSizes, r.MediaMetadata,
+			activeThumbnailGeneration, maxThumbnailGenerators, db, r.Logger,
+		)
+		if err != nil {
+			r.Logger.WithError(err).Warn("Error generating thumbnails")
+		}
+		if busy {
+			r.Logger.Warn("Maximum number of active thumbnail generators reached. Skipping pre-generation.")
+		}
+	}()
+
+	r.Logger.WithFields(log.Fields{
+		"UploadName":    r.MediaMetadata.UploadName,
+		"Base64Hash":    r.MediaMetadata.Base64Hash,
+		"FileSizeBytes": r.MediaMetadata.FileSizeBytes,
+		"ContentType":   r.MediaMetadata.ContentType,
+	}).Infof("Remote file cached")
+
+	return nil
+}
+
+func (r *downloadRequest) fetchRemoteFile(
+	ctx context.Context,
+	client *gomatrixserverlib.Client,
+	absBasePath config.Path,
+	maxFileSizeBytes config.FileSizeBytes,
+) (types.Path, bool, error) {
+	r.Logger.Info("Fetching remote file")
+
+	// create request for remote file
+	resp, err := r.createRemoteRequest(ctx, client)
+	if err != nil {
+		return "", false, err
+	}
+	if resp == nil {
+		// Remote file not found
+		return "", false, nil
+	}
+	defer resp.Body.Close() // nolint: errcheck
+
+	// get metadata from request and set metadata on response
+	contentLength, err := strconv.ParseInt(resp.Header.Get("Content-Length"), 10, 64)
+	if err != nil {
+		r.Logger.WithError(err).Warn("Failed to parse content length")
+		return "", false, errors.Wrap(err, "invalid response from remote server")
+	}
+	if contentLength > int64(maxFileSizeBytes) {
+		// TODO: Bubble up this as a 413
+		return "", false, fmt.Errorf("remote file is too large (%v > %v bytes)", contentLength, maxFileSizeBytes)
+	}
+	r.MediaMetadata.FileSizeBytes = types.FileSizeBytes(contentLength)
+	r.MediaMetadata.ContentType = types.ContentType(resp.Header.Get("Content-Type"))
+	_, params, err := mime.ParseMediaType(resp.Header.Get("Content-Disposition"))
+	if err == nil && params["filename"] != "" {
+		r.MediaMetadata.UploadName = types.Filename(params["filename"])
+	}
+
+	r.Logger.Info("Transferring remote file")
+
+	// The file data is hashed but is NOT used as the MediaID, unlike in Upload. The hash is useful as a
+	// method of deduplicating files to save storage, as well as a way to conduct
+	// integrity checks on the file data in the repository.
+	// Data is truncated to maxFileSizeBytes. Content-Length was reported as 0 < Content-Length <= maxFileSizeBytes so this is OK.
+	hash, bytesWritten, tmpDir, err := fileutils.WriteTempFile(resp.Body, maxFileSizeBytes, absBasePath)
+	if err != nil {
+		r.Logger.WithError(err).WithFields(log.Fields{
+			"MaxFileSizeBytes": maxFileSizeBytes,
+		}).Warn("Error while downloading file from remote server")
+		fileutils.RemoveDir(tmpDir, r.Logger)
+		return "", false, errors.New("file could not be downloaded from remote server")
+	}
+
+	r.Logger.Info("Remote file transferred")
+
+	// It's possible the bytesWritten to the temporary file is different to the reported Content-Length from the remote
+	// request's response. bytesWritten is therefore used as it is what would be sent to clients when reading from the local
+	// file.
+	r.MediaMetadata.FileSizeBytes = types.FileSizeBytes(bytesWritten)
+	r.MediaMetadata.Base64Hash = hash
+
+	// The database is the source of truth so we need to have moved the file first
+	finalPath, duplicate, err := fileutils.MoveFileWithHashCheck(tmpDir, r.MediaMetadata, absBasePath, r.Logger)
+	if err != nil {
+		return "", false, errors.Wrap(err, "failed to move file")
+	}
+	if duplicate {
+		r.Logger.WithField("dst", finalPath).Info("File was stored previously - discarding duplicate")
+		// Continue on to store the metadata in the database
+	}
+
+	return types.Path(finalPath), duplicate, nil
+}
+
+func (r *downloadRequest) createRemoteRequest(
+	ctx context.Context, matrixClient *gomatrixserverlib.Client,
+) (*http.Response, error) {
+	resp, err := matrixClient.CreateMediaDownloadRequest(ctx, r.MediaMetadata.Origin, string(r.MediaMetadata.MediaID))
+	if err != nil {
+		return nil, fmt.Errorf("file with media ID %q could not be downloaded from %q", r.MediaMetadata.MediaID, r.MediaMetadata.Origin)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		if resp.StatusCode == http.StatusNotFound {
+			return nil, nil
+		}
+		r.Logger.WithFields(log.Fields{
+			"StatusCode": resp.StatusCode,
+		}).Warn("Received error response")
+		return nil, fmt.Errorf("file with media ID %q could not be downloaded from %q", r.MediaMetadata.MediaID, r.MediaMetadata.Origin)
+	}
+
+	return resp, nil
+}

mediaapi/routing/routing.go

@@ -0,0 +1,104 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package routing
+
+import (
+	"net/http"
+
+	"github.com/matrix-org/dendrite/clientapi/auth"
+	"github.com/matrix-org/dendrite/clientapi/auth/authtypes"
+
+	"github.com/gorilla/mux"
+	"github.com/matrix-org/dendrite/clientapi/auth/storage/devices"
+	"github.com/matrix-org/dendrite/common"
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/dendrite/mediaapi/storage"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	"github.com/matrix-org/gomatrixserverlib"
+	"github.com/matrix-org/util"
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+const pathPrefixR0 = "/_matrix/media/r0"
+
+// Setup registers the media API HTTP handlers
+func Setup(
+	apiMux *mux.Router,
+	cfg *config.Dendrite,
+	db *storage.Database,
+	deviceDB *devices.Database,
+	client *gomatrixserverlib.Client,
+) {
+	r0mux := apiMux.PathPrefix(pathPrefixR0).Subrouter()
+
+	activeThumbnailGeneration := &types.ActiveThumbnailGeneration{
+		PathToResult: map[string]*types.ThumbnailGenerationResult{},
+	}
+	authData := auth.Data{
+		AccountDB:   nil,
+		DeviceDB:    deviceDB,
+		AppServices: nil,
+	}
+
+	// TODO: Add AS support
+	r0mux.Handle("/upload", common.MakeAuthAPI(
+		"upload", authData,
+		func(req *http.Request, _ *authtypes.Device) util.JSONResponse {
+			return Upload(req, cfg, db, activeThumbnailGeneration)
+		},
+	)).Methods(http.MethodPost, http.MethodOptions)
+
+	activeRemoteRequests := &types.ActiveRemoteRequests{
+		MXCToResult: map[string]*types.RemoteRequestResult{},
+	}
+	r0mux.Handle("/download/{serverName}/{mediaId}",
+		makeDownloadAPI("download", cfg, db, client, activeRemoteRequests, activeThumbnailGeneration),
+	).Methods(http.MethodGet, http.MethodOptions)
+	r0mux.Handle("/thumbnail/{serverName}/{mediaId}",
+		makeDownloadAPI("thumbnail", cfg, db, client, activeRemoteRequests, activeThumbnailGeneration),
+	).Methods(http.MethodGet, http.MethodOptions)
+}
+
+func makeDownloadAPI(
+	name string,
+	cfg *config.Dendrite,
+	db *storage.Database,
+	client *gomatrixserverlib.Client,
+	activeRemoteRequests *types.ActiveRemoteRequests,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+) http.HandlerFunc {
+	return prometheus.InstrumentHandler(name, http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		req = util.RequestWithLogging(req)
+
+		// Set common headers returned regardless of the outcome of the request
+		util.SetCORSHeaders(w)
+		// Content-Type will be overridden in case of returning file data, else we respond with JSON-formatted errors
+		w.Header().Set("Content-Type", "application/json")
+
+		vars := mux.Vars(req)
+		Download(
+			w,
+			req,
+			gomatrixserverlib.ServerName(vars["serverName"]),
+			types.MediaID(vars["mediaId"]),
+			cfg,
+			db,
+			client,
+			activeRemoteRequests,
+			activeThumbnailGeneration,
+			name == "thumbnail",
+		)
+	}))
+}

mediaapi/routing/upload.go

@@ -0,0 +1,269 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package routing
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"path"
+	"strings"
+
+	"github.com/matrix-org/dendrite/clientapi/jsonerror"
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/dendrite/mediaapi/fileutils"
+	"github.com/matrix-org/dendrite/mediaapi/storage"
+	"github.com/matrix-org/dendrite/mediaapi/thumbnailer"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	"github.com/matrix-org/gomatrixserverlib"
+	"github.com/matrix-org/util"
+	log "github.com/sirupsen/logrus"
+)
+
+// uploadRequest metadata included in or derivable from an upload request
+// https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-media-r0-upload
+// NOTE: The members come from HTTP request metadata such as headers, query parameters or can be derived from such
+type uploadRequest struct {
+	MediaMetadata *types.MediaMetadata
+	Logger        *log.Entry
+}
+
+// uploadResponse defines the format of the JSON response
+// https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-media-r0-upload
+type uploadResponse struct {
+	ContentURI string `json:"content_uri"`
+}
+
+// Upload implements /upload
+// This endpoint involves uploading potentially significant amounts of data to the homeserver.
+// This implementation supports a configurable maximum file size limit in bytes. If a user tries to upload more than this, they will receive an error that their upload is too large.
+// Uploaded files are processed piece-wise to avoid DoS attacks which would starve the server of memory.
+// TODO: We should time out requests if they have not received any data within a configured timeout period.
+func Upload(req *http.Request, cfg *config.Dendrite, db *storage.Database, activeThumbnailGeneration *types.ActiveThumbnailGeneration) util.JSONResponse {
+	r, resErr := parseAndValidateRequest(req, cfg)
+	if resErr != nil {
+		return *resErr
+	}
+
+	if resErr = r.doUpload(req.Context(), req.Body, cfg, db, activeThumbnailGeneration); resErr != nil {
+		return *resErr
+	}
+
+	return util.JSONResponse{
+		Code: http.StatusOK,
+		JSON: uploadResponse{
+			ContentURI: fmt.Sprintf("mxc://%s/%s", cfg.Matrix.ServerName, r.MediaMetadata.MediaID),
+		},
+	}
+}
+
+// parseAndValidateRequest parses the incoming upload request to validate and extract
+// all the metadata about the media being uploaded.
+// Returns either an uploadRequest or an error formatted as a util.JSONResponse
+func parseAndValidateRequest(req *http.Request, cfg *config.Dendrite) (*uploadRequest, *util.JSONResponse) {
+	if req.Method != http.MethodPost {
+		return nil, &util.JSONResponse{
+			Code: http.StatusMethodNotAllowed,
+			JSON: jsonerror.Unknown("HTTP request method must be POST."),
+		}
+	}
+
+	r := &uploadRequest{
+		MediaMetadata: &types.MediaMetadata{
+			Origin:        cfg.Matrix.ServerName,
+			FileSizeBytes: types.FileSizeBytes(req.ContentLength),
+			ContentType:   types.ContentType(req.Header.Get("Content-Type")),
+			UploadName:    types.Filename(url.PathEscape(req.FormValue("filename"))),
+		},
+		Logger: util.GetLogger(req.Context()).WithField("Origin", cfg.Matrix.ServerName),
+	}
+
+	if resErr := r.Validate(*cfg.Media.MaxFileSizeBytes); resErr != nil {
+		return nil, resErr
+	}
+
+	return r, nil
+}
+
+func (r *uploadRequest) doUpload(
+	ctx context.Context,
+	reqReader io.Reader,
+	cfg *config.Dendrite,
+	db *storage.Database,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+) *util.JSONResponse {
+	r.Logger.WithFields(log.Fields{
+		"UploadName":    r.MediaMetadata.UploadName,
+		"FileSizeBytes": r.MediaMetadata.FileSizeBytes,
+		"ContentType":   r.MediaMetadata.ContentType,
+	}).Info("Uploading file")
+
+	// The file data is hashed and the hash is used as the MediaID. The hash is useful as a
+	// method of deduplicating files to save storage, as well as a way to conduct
+	// integrity checks on the file data in the repository.
+	// Data is truncated to maxFileSizeBytes. Content-Length was reported as 0 < Content-Length <= maxFileSizeBytes so this is OK.
+	hash, bytesWritten, tmpDir, err := fileutils.WriteTempFile(reqReader, *cfg.Media.MaxFileSizeBytes, cfg.Media.AbsBasePath)
+	if err != nil {
+		r.Logger.WithError(err).WithFields(log.Fields{
+			"MaxFileSizeBytes": *cfg.Media.MaxFileSizeBytes,
+		}).Warn("Error while transferring file")
+		fileutils.RemoveDir(tmpDir, r.Logger)
+		return &util.JSONResponse{
+			Code: http.StatusBadRequest,
+			JSON: jsonerror.Unknown("Failed to upload"),
+		}
+	}
+
+	r.MediaMetadata.FileSizeBytes = bytesWritten
+	r.MediaMetadata.Base64Hash = hash
+	r.MediaMetadata.MediaID = types.MediaID(hash)
+
+	r.Logger = r.Logger.WithField("MediaID", r.MediaMetadata.MediaID)
+
+	r.Logger.WithFields(log.Fields{
+		"Base64Hash":    r.MediaMetadata.Base64Hash,
+		"UploadName":    r.MediaMetadata.UploadName,
+		"FileSizeBytes": r.MediaMetadata.FileSizeBytes,
+		"ContentType":   r.MediaMetadata.ContentType,
+	}).Info("File uploaded")
+
+	// check if we already have a record of the media in our database and if so, we can remove the temporary directory
+	mediaMetadata, err := db.GetMediaMetadata(
+		ctx, r.MediaMetadata.MediaID, r.MediaMetadata.Origin,
+	)
+	if err != nil {
+		r.Logger.WithError(err).Error("Error querying the database.")
+		resErr := jsonerror.InternalServerError()
+		return &resErr
+	}
+
+	if mediaMetadata != nil {
+		r.MediaMetadata = mediaMetadata
+		fileutils.RemoveDir(tmpDir, r.Logger)
+		return &util.JSONResponse{
+			Code: http.StatusOK,
+			JSON: uploadResponse{
+				ContentURI: fmt.Sprintf("mxc://%s/%s", cfg.Matrix.ServerName, r.MediaMetadata.MediaID),
+			},
+		}
+	}
+
+	return r.storeFileAndMetadata(
+		ctx, tmpDir, cfg.Media.AbsBasePath, db, cfg.Media.ThumbnailSizes,
+		activeThumbnailGeneration, cfg.Media.MaxThumbnailGenerators,
+	)
+}
+
+// Validate validates the uploadRequest fields
+func (r *uploadRequest) Validate(maxFileSizeBytes config.FileSizeBytes) *util.JSONResponse {
+	if r.MediaMetadata.FileSizeBytes < 1 {
+		return &util.JSONResponse{
+			Code: http.StatusLengthRequired,
+			JSON: jsonerror.Unknown("HTTP Content-Length request header must be greater than zero."),
+		}
+	}
+	if maxFileSizeBytes > 0 && r.MediaMetadata.FileSizeBytes > types.FileSizeBytes(maxFileSizeBytes) {
+		return &util.JSONResponse{
+			Code: http.StatusRequestEntityTooLarge,
+			JSON: jsonerror.Unknown(fmt.Sprintf("HTTP Content-Length is greater than the maximum allowed upload size (%v).", maxFileSizeBytes)),
+		}
+	}
+	// TODO: Check if the Content-Type is a valid type?
+	if r.MediaMetadata.ContentType == "" {
+		return &util.JSONResponse{
+			Code: http.StatusBadRequest,
+			JSON: jsonerror.Unknown("HTTP Content-Type request header must be set."),
+		}
+	}
+	if strings.HasPrefix(string(r.MediaMetadata.UploadName), "~") {
+		return &util.JSONResponse{
+			Code: http.StatusBadRequest,
+			JSON: jsonerror.Unknown("File name must not begin with '~'."),
+		}
+	}
+	// TODO: Validate filename - what are the valid characters?
+	if r.MediaMetadata.UserID != "" {
+		// TODO: We should put user ID parsing code into gomatrixserverlib and use that instead
+		//       (see https://github.com/matrix-org/gomatrixserverlib/blob/3394e7c7003312043208aa73727d2256eea3d1f6/eventcontent.go#L347 )
+		//       It should be a struct (with pointers into a single string to avoid copying) and
+		//       we should update all refs to use UserID types rather than strings.
+		// https://github.com/matrix-org/synapse/blob/v0.19.2/synapse/types.py#L92
+		if _, _, err := gomatrixserverlib.SplitID('@', string(r.MediaMetadata.UserID)); err != nil {
+			return &util.JSONResponse{
+				Code: http.StatusBadRequest,
+				JSON: jsonerror.BadJSON("user id must be in the form @localpart:domain"),
+			}
+		}
+	}
+	return nil
+}
+
+// storeFileAndMetadata moves the temporary file to its final path based on metadata and stores the metadata in the database
+// See getPathFromMediaMetadata in fileutils for details of the final path.
+// The order of operations is important as it avoids metadata entering the database before the file
+// is ready, and if we fail to move the file, it never gets added to the database.
+// Returns a util.JSONResponse error and cleans up directories in case of error.
+func (r *uploadRequest) storeFileAndMetadata(
+	ctx context.Context,
+	tmpDir types.Path,
+	absBasePath config.Path,
+	db *storage.Database,
+	thumbnailSizes []config.ThumbnailSize,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+) *util.JSONResponse {
+	finalPath, duplicate, err := fileutils.MoveFileWithHashCheck(tmpDir, r.MediaMetadata, absBasePath, r.Logger)
+	if err != nil {
+		r.Logger.WithError(err).Error("Failed to move file.")
+		return &util.JSONResponse{
+			Code: http.StatusBadRequest,
+			JSON: jsonerror.Unknown("Failed to upload"),
+		}
+	}
+	if duplicate {
+		r.Logger.WithField("dst", finalPath).Info("File was stored previously - discarding duplicate")
+	}
+
+	if err = db.StoreMediaMetadata(ctx, r.MediaMetadata); err != nil {
+		r.Logger.WithError(err).Warn("Failed to store metadata")
+		// If the file is a duplicate (has the same hash as an existing file) then
+		// there is valid metadata in the database for that file. As such we only
+		// remove the file if it is not a duplicate.
+		if !duplicate {
+			fileutils.RemoveDir(types.Path(path.Dir(string(finalPath))), r.Logger)
+		}
+		return &util.JSONResponse{
+			Code: http.StatusBadRequest,
+			JSON: jsonerror.Unknown("Failed to upload"),
+		}
+	}
+
+	go func() {
+		busy, err := thumbnailer.GenerateThumbnails(
+			context.Background(), finalPath, thumbnailSizes, r.MediaMetadata,
+			activeThumbnailGeneration, maxThumbnailGenerators, db, r.Logger,
+		)
+		if err != nil {
+			r.Logger.WithError(err).Warn("Error generating thumbnails")
+		}
+		if busy {
+			r.Logger.Warn("Maximum number of active thumbnail generators reached. Skipping pre-generation.")
+		}
+	}()
+
+	return nil
+}

mediaapi/storage/media_repository_table.go

@@ -0,0 +1,114 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package storage
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	"github.com/matrix-org/gomatrixserverlib"
+)
+
+const mediaSchema = `
+-- The media_repository table holds metadata for each media file stored and accessible to the local server,
+-- the actual file is stored separately.
+CREATE TABLE IF NOT EXISTS mediaapi_media_repository (
+    -- The id used to refer to the media.
+    -- For uploads to this server this is a base64-encoded sha256 hash of the file data
+    -- For media from remote servers, this can be any unique identifier string
+    media_id TEXT NOT NULL,
+    -- The origin of the media as requested by the client. Should be a homeserver domain.
+    media_origin TEXT NOT NULL,
+    -- The MIME-type of the media file as specified when uploading.
+    content_type TEXT NOT NULL,
+    -- Size of the media file in bytes.
+    file_size_bytes BIGINT NOT NULL,
+    -- When the content was uploaded in UNIX epoch ms.
+    creation_ts BIGINT NOT NULL,
+    -- The file name with which the media was uploaded.
+    upload_name TEXT NOT NULL,
+    -- Alternate RFC 4648 unpadded base64 encoding string representation of a SHA-256 hash sum of the file data.
+    base64hash TEXT NOT NULL,
+    -- The user who uploaded the file. Should be a Matrix user ID.
+    user_id TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS mediaapi_media_repository_index ON mediaapi_media_repository (media_id, media_origin);
+`
+
+const insertMediaSQL = `
+INSERT INTO mediaapi_media_repository (media_id, media_origin, content_type, file_size_bytes, creation_ts, upload_name, base64hash, user_id)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+`
+
+const selectMediaSQL = `
+SELECT content_type, file_size_bytes, creation_ts, upload_name, base64hash, user_id FROM mediaapi_media_repository WHERE media_id = $1 AND media_origin = $2
+`
+
+type mediaStatements struct {
+	insertMediaStmt *sql.Stmt
+	selectMediaStmt *sql.Stmt
+}
+
+func (s *mediaStatements) prepare(db *sql.DB) (err error) {
+	_, err = db.Exec(mediaSchema)
+	if err != nil {
+		return
+	}
+
+	return statementList{
+		{&s.insertMediaStmt, insertMediaSQL},
+		{&s.selectMediaStmt, selectMediaSQL},
+	}.prepare(db)
+}
+
+func (s *mediaStatements) insertMedia(
+	ctx context.Context, mediaMetadata *types.MediaMetadata,
+) error {
+	mediaMetadata.CreationTimestamp = types.UnixMs(time.Now().UnixNano() / 1000000)
+	_, err := s.insertMediaStmt.ExecContext(
+		ctx,
+		mediaMetadata.MediaID,
+		mediaMetadata.Origin,
+		mediaMetadata.ContentType,
+		mediaMetadata.FileSizeBytes,
+		mediaMetadata.CreationTimestamp,
+		mediaMetadata.UploadName,
+		mediaMetadata.Base64Hash,
+		mediaMetadata.UserID,
+	)
+	return err
+}
+
+func (s *mediaStatements) selectMedia(
+	ctx context.Context, mediaID types.MediaID, mediaOrigin gomatrixserverlib.ServerName,
+) (*types.MediaMetadata, error) {
+	mediaMetadata := types.MediaMetadata{
+		MediaID: mediaID,
+		Origin:  mediaOrigin,
+	}
+	err := s.selectMediaStmt.QueryRowContext(
+		ctx, mediaMetadata.MediaID, mediaMetadata.Origin,
+	).Scan(
+		&mediaMetadata.ContentType,
+		&mediaMetadata.FileSizeBytes,
+		&mediaMetadata.CreationTimestamp,
+		&mediaMetadata.UploadName,
+		&mediaMetadata.Base64Hash,
+		&mediaMetadata.UserID,
+	)
+	return &mediaMetadata, err
+}

mediaapi/storage/prepare.go

@@ -0,0 +1,37 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// FIXME: This should be made common!
+
+package storage
+
+import (
+	"database/sql"
+)
+
+// a statementList is a list of SQL statements to prepare and a pointer to where to store the resulting prepared statement.
+type statementList []struct {
+	statement **sql.Stmt
+	sql       string
+}
+
+// prepare the SQL for each statement in the list and assign the result to the prepared statement.
+func (s statementList) prepare(db *sql.DB) (err error) {
+	for _, statement := range s {
+		if *statement.statement, err = db.Prepare(statement.sql); err != nil {
+			return
+		}
+	}
+	return
+}

mediaapi/storage/sql.go

@@ -0,0 +1,35 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package storage
+
+import (
+	"database/sql"
+)
+
+type statements struct {
+	media     mediaStatements
+	thumbnail thumbnailStatements
+}
+
+func (s *statements) prepare(db *sql.DB) (err error) {
+	if err = s.media.prepare(db); err != nil {
+		return
+	}
+	if err = s.thumbnail.prepare(db); err != nil {
+		return
+	}
+
+	return
+}

mediaapi/storage/storage.go

@@ -0,0 +1,105 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package storage
+
+import (
+	"context"
+	"database/sql"
+
+	// Import the postgres database driver.
+	_ "github.com/lib/pq"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	"github.com/matrix-org/gomatrixserverlib"
+)
+
+// Database is used to store metadata about a repository of media files.
+type Database struct {
+	statements statements
+	db         *sql.DB
+}
+
+// Open opens a postgres database.
+func Open(dataSourceName string) (*Database, error) {
+	var d Database
+	var err error
+	if d.db, err = sql.Open("postgres", dataSourceName); err != nil {
+		return nil, err
+	}
+	if err = d.statements.prepare(d.db); err != nil {
+		return nil, err
+	}
+	return &d, nil
+}
+
+// StoreMediaMetadata inserts the metadata about the uploaded media into the database.
+// Returns an error if the combination of MediaID and Origin are not unique in the table.
+func (d *Database) StoreMediaMetadata(
+	ctx context.Context, mediaMetadata *types.MediaMetadata,
+) error {
+	return d.statements.media.insertMedia(ctx, mediaMetadata)
+}
+
+// GetMediaMetadata returns metadata about media stored on this server.
+// The media could have been uploaded to this server or fetched from another server and cached here.
+// Returns nil metadata if there is no metadata associated with this media.
+func (d *Database) GetMediaMetadata(
+	ctx context.Context, mediaID types.MediaID, mediaOrigin gomatrixserverlib.ServerName,
+) (*types.MediaMetadata, error) {
+	mediaMetadata, err := d.statements.media.selectMedia(ctx, mediaID, mediaOrigin)
+	if err != nil && err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return mediaMetadata, err
+}
+
+// StoreThumbnail inserts the metadata about the thumbnail into the database.
+// Returns an error if the combination of MediaID and Origin are not unique in the table.
+func (d *Database) StoreThumbnail(
+	ctx context.Context, thumbnailMetadata *types.ThumbnailMetadata,
+) error {
+	return d.statements.thumbnail.insertThumbnail(ctx, thumbnailMetadata)
+}
+
+// GetThumbnail returns metadata about a specific thumbnail.
+// The media could have been uploaded to this server or fetched from another server and cached here.
+// Returns nil metadata if there is no metadata associated with this thumbnail.
+func (d *Database) GetThumbnail(
+	ctx context.Context,
+	mediaID types.MediaID,
+	mediaOrigin gomatrixserverlib.ServerName,
+	width, height int,
+	resizeMethod string,
+) (*types.ThumbnailMetadata, error) {
+	thumbnailMetadata, err := d.statements.thumbnail.selectThumbnail(
+		ctx, mediaID, mediaOrigin, width, height, resizeMethod,
+	)
+	if err != nil && err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return thumbnailMetadata, err
+}
+
+// GetThumbnails returns metadata about all thumbnails for a specific media stored on this server.
+// The media could have been uploaded to this server or fetched from another server and cached here.
+// Returns nil metadata if there are no thumbnails associated with this media.
+func (d *Database) GetThumbnails(
+	ctx context.Context, mediaID types.MediaID, mediaOrigin gomatrixserverlib.ServerName,
+) ([]*types.ThumbnailMetadata, error) {
+	thumbnails, err := d.statements.thumbnail.selectThumbnails(ctx, mediaID, mediaOrigin)
+	if err != nil && err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return thumbnails, err
+}

mediaapi/storage/thumbnail_table.go

@@ -0,0 +1,170 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package storage
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	"github.com/matrix-org/gomatrixserverlib"
+)
+
+const thumbnailSchema = `
+-- The mediaapi_thumbnail table holds metadata for each thumbnail file stored and accessible to the local server,
+-- the actual file is stored separately.
+CREATE TABLE IF NOT EXISTS mediaapi_thumbnail (
+    -- The id used to refer to the media.
+    -- For uploads to this server this is a base64-encoded sha256 hash of the file data
+    -- For media from remote servers, this can be any unique identifier string
+    media_id TEXT NOT NULL,
+    -- The origin of the media as requested by the client. Should be a homeserver domain.
+    media_origin TEXT NOT NULL,
+    -- The MIME-type of the thumbnail file.
+    content_type TEXT NOT NULL,
+    -- Size of the thumbnail file in bytes.
+    file_size_bytes BIGINT NOT NULL,
+    -- When the thumbnail was generated in UNIX epoch ms.
+    creation_ts BIGINT NOT NULL,
+    -- The width of the thumbnail
+    width INTEGER NOT NULL,
+    -- The height of the thumbnail
+    height INTEGER NOT NULL,
+    -- The resize method used to generate the thumbnail. Can be crop or scale.
+    resize_method TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS mediaapi_thumbnail_index ON mediaapi_thumbnail (media_id, media_origin, width, height, resize_method);
+`
+
+const insertThumbnailSQL = `
+INSERT INTO mediaapi_thumbnail (media_id, media_origin, content_type, file_size_bytes, creation_ts, width, height, resize_method)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+`
+
+// Note: this selects one specific thumbnail
+const selectThumbnailSQL = `
+SELECT content_type, file_size_bytes, creation_ts FROM mediaapi_thumbnail WHERE media_id = $1 AND media_origin = $2 AND width = $3 AND height = $4 AND resize_method = $5
+`
+
+// Note: this selects all thumbnails for a media_origin and media_id
+const selectThumbnailsSQL = `
+SELECT content_type, file_size_bytes, creation_ts, width, height, resize_method FROM mediaapi_thumbnail WHERE media_id = $1 AND media_origin = $2
+`
+
+type thumbnailStatements struct {
+	insertThumbnailStmt  *sql.Stmt
+	selectThumbnailStmt  *sql.Stmt
+	selectThumbnailsStmt *sql.Stmt
+}
+
+func (s *thumbnailStatements) prepare(db *sql.DB) (err error) {
+	_, err = db.Exec(thumbnailSchema)
+	if err != nil {
+		return
+	}
+
+	return statementList{
+		{&s.insertThumbnailStmt, insertThumbnailSQL},
+		{&s.selectThumbnailStmt, selectThumbnailSQL},
+		{&s.selectThumbnailsStmt, selectThumbnailsSQL},
+	}.prepare(db)
+}
+
+func (s *thumbnailStatements) insertThumbnail(
+	ctx context.Context, thumbnailMetadata *types.ThumbnailMetadata,
+) error {
+	thumbnailMetadata.MediaMetadata.CreationTimestamp = types.UnixMs(time.Now().UnixNano() / 1000000)
+	_, err := s.insertThumbnailStmt.ExecContext(
+		ctx,
+		thumbnailMetadata.MediaMetadata.MediaID,
+		thumbnailMetadata.MediaMetadata.Origin,
+		thumbnailMetadata.MediaMetadata.ContentType,
+		thumbnailMetadata.MediaMetadata.FileSizeBytes,
+		thumbnailMetadata.MediaMetadata.CreationTimestamp,
+		thumbnailMetadata.ThumbnailSize.Width,
+		thumbnailMetadata.ThumbnailSize.Height,
+		thumbnailMetadata.ThumbnailSize.ResizeMethod,
+	)
+	return err
+}
+
+func (s *thumbnailStatements) selectThumbnail(
+	ctx context.Context,
+	mediaID types.MediaID,
+	mediaOrigin gomatrixserverlib.ServerName,
+	width, height int,
+	resizeMethod string,
+) (*types.ThumbnailMetadata, error) {
+	thumbnailMetadata := types.ThumbnailMetadata{
+		MediaMetadata: &types.MediaMetadata{
+			MediaID: mediaID,
+			Origin:  mediaOrigin,
+		},
+		ThumbnailSize: types.ThumbnailSize{
+			Width:        width,
+			Height:       height,
+			ResizeMethod: resizeMethod,
+		},
+	}
+	err := s.selectThumbnailStmt.QueryRowContext(
+		ctx,
+		thumbnailMetadata.MediaMetadata.MediaID,
+		thumbnailMetadata.MediaMetadata.Origin,
+		thumbnailMetadata.ThumbnailSize.Width,
+		thumbnailMetadata.ThumbnailSize.Height,
+		thumbnailMetadata.ThumbnailSize.ResizeMethod,
+	).Scan(
+		&thumbnailMetadata.MediaMetadata.ContentType,
+		&thumbnailMetadata.MediaMetadata.FileSizeBytes,
+		&thumbnailMetadata.MediaMetadata.CreationTimestamp,
+	)
+	return &thumbnailMetadata, err
+}
+
+func (s *thumbnailStatements) selectThumbnails(
+	ctx context.Context, mediaID types.MediaID, mediaOrigin gomatrixserverlib.ServerName,
+) ([]*types.ThumbnailMetadata, error) {
+	rows, err := s.selectThumbnailsStmt.QueryContext(
+		ctx, mediaID, mediaOrigin,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	var thumbnails []*types.ThumbnailMetadata
+	for rows.Next() {
+		thumbnailMetadata := types.ThumbnailMetadata{
+			MediaMetadata: &types.MediaMetadata{
+				MediaID: mediaID,
+				Origin:  mediaOrigin,
+			},
+		}
+		err = rows.Scan(
+			&thumbnailMetadata.MediaMetadata.ContentType,
+			&thumbnailMetadata.MediaMetadata.FileSizeBytes,
+			&thumbnailMetadata.MediaMetadata.CreationTimestamp,
+			&thumbnailMetadata.ThumbnailSize.Width,
+			&thumbnailMetadata.ThumbnailSize.Height,
+			&thumbnailMetadata.ThumbnailSize.ResizeMethod,
+		)
+		if err != nil {
+			return nil, err
+		}
+		thumbnails = append(thumbnails, &thumbnailMetadata)
+	}
+
+	return thumbnails, err
+}

mediaapi/thumbnailer/thumbnailer.go

@@ -0,0 +1,249 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package thumbnailer
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/dendrite/mediaapi/storage"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	log "github.com/sirupsen/logrus"
+)
+
+type thumbnailFitness struct {
+	isSmaller      int
+	aspect         float64
+	size           float64
+	methodMismatch int
+	fileSize       types.FileSizeBytes
+}
+
+// thumbnailTemplate is the filename template for thumbnails
+const thumbnailTemplate = "thumbnail-%vx%v-%v"
+
+// GetThumbnailPath returns the path to a thumbnail given the absolute src path and thumbnail size configuration
+func GetThumbnailPath(src types.Path, config types.ThumbnailSize) types.Path {
+	srcDir := filepath.Dir(string(src))
+	return types.Path(filepath.Join(
+		srcDir,
+		fmt.Sprintf(thumbnailTemplate, config.Width, config.Height, config.ResizeMethod),
+	))
+}
+
+// SelectThumbnail compares the (potentially) available thumbnails with the desired thumbnail and returns the best match
+// The algorithm is very similar to what was implemented in Synapse
+// In order of priority unless absolute, the following metrics are compared; the image is:
+// * the same size or larger than requested
+// * if a cropped image is desired, has an aspect ratio close to requested
+// * has a size close to requested
+// * if a cropped image is desired, prefer the same method, if scaled is desired, absolutely require scaled
+// * has a small file size
+// If a pre-generated thumbnail size is the best match, but it has not been generated yet, the caller can use the returned size to generate it.
+// Returns nil if no thumbnail matches the criteria
+func SelectThumbnail(desired types.ThumbnailSize, thumbnails []*types.ThumbnailMetadata, thumbnailSizes []config.ThumbnailSize) (*types.ThumbnailMetadata, *types.ThumbnailSize) {
+	var chosenThumbnail *types.ThumbnailMetadata
+	var chosenThumbnailSize *types.ThumbnailSize
+	bestFit := newThumbnailFitness()
+
+	for _, thumbnail := range thumbnails {
+		if desired.ResizeMethod == types.Scale && thumbnail.ThumbnailSize.ResizeMethod != types.Scale {
+			continue
+		}
+		fitness := calcThumbnailFitness(thumbnail.ThumbnailSize, thumbnail.MediaMetadata, desired)
+		if isBetter := fitness.betterThan(bestFit, desired.ResizeMethod == types.Crop); isBetter {
+			bestFit = fitness
+			chosenThumbnail = thumbnail
+		}
+	}
+
+	for _, thumbnailSize := range thumbnailSizes {
+		if desired.ResizeMethod == types.Scale && thumbnailSize.ResizeMethod != types.Scale {
+			continue
+		}
+		fitness := calcThumbnailFitness(types.ThumbnailSize(thumbnailSize), nil, desired)
+		if isBetter := fitness.betterThan(bestFit, desired.ResizeMethod == types.Crop); isBetter {
+			bestFit = fitness
+			chosenThumbnailSize = (*types.ThumbnailSize)(&thumbnailSize)
+		}
+	}
+
+	return chosenThumbnail, chosenThumbnailSize
+}
+
+// getActiveThumbnailGeneration checks for active thumbnail generation
+func getActiveThumbnailGeneration(dst types.Path, _ types.ThumbnailSize, activeThumbnailGeneration *types.ActiveThumbnailGeneration, maxThumbnailGenerators int, logger *log.Entry) (isActive bool, busy bool, errorReturn error) {
+	// Check if there is active thumbnail generation.
+	activeThumbnailGeneration.Lock()
+	defer activeThumbnailGeneration.Unlock()
+	if activeThumbnailGenerationResult, ok := activeThumbnailGeneration.PathToResult[string(dst)]; ok {
+		logger.Info("Waiting for another goroutine to generate the thumbnail.")
+
+		// NOTE: Wait unlocks and locks again internally. There is still a deferred Unlock() that will unlock this.
+		activeThumbnailGenerationResult.Cond.Wait()
+		// Note: either there is an error or it is nil, either way returning it is correct
+		return false, false, activeThumbnailGenerationResult.Err
+	}
+
+	// Only allow thumbnail generation up to a maximum configured number. Above this we fall back to serving the
+	// original. Or in the case of pre-generation, they maybe get generated on the first request for a thumbnail if
+	// load has subsided.
+	if len(activeThumbnailGeneration.PathToResult) >= maxThumbnailGenerators {
+		return false, true, nil
+	}
+
+	// No active thumbnail generation so create one
+	activeThumbnailGeneration.PathToResult[string(dst)] = &types.ThumbnailGenerationResult{
+		Cond: &sync.Cond{L: activeThumbnailGeneration},
+	}
+
+	return true, false, nil
+}
+
+// broadcastGeneration broadcasts that thumbnail generation completed and the error to all waiting goroutines
+// Note: This should only be called by the owner of the activeThumbnailGenerationResult
+func broadcastGeneration(dst types.Path, activeThumbnailGeneration *types.ActiveThumbnailGeneration, _ types.ThumbnailSize, errorReturn error, logger *log.Entry) {
+	activeThumbnailGeneration.Lock()
+	defer activeThumbnailGeneration.Unlock()
+	if activeThumbnailGenerationResult, ok := activeThumbnailGeneration.PathToResult[string(dst)]; ok {
+		logger.Info("Signalling other goroutines waiting for this goroutine to generate the thumbnail.")
+		// Note: errorReturn is a named return value error that is signalled from here to waiting goroutines
+		activeThumbnailGenerationResult.Err = errorReturn
+		activeThumbnailGenerationResult.Cond.Broadcast()
+	}
+	delete(activeThumbnailGeneration.PathToResult, string(dst))
+}
+
+func isThumbnailExists(
+	ctx context.Context,
+	dst types.Path,
+	config types.ThumbnailSize,
+	mediaMetadata *types.MediaMetadata,
+	db *storage.Database,
+	logger *log.Entry,
+) (bool, error) {
+	thumbnailMetadata, err := db.GetThumbnail(
+		ctx, mediaMetadata.MediaID, mediaMetadata.Origin,
+		config.Width, config.Height, config.ResizeMethod,
+	)
+	if err != nil {
+		logger.Error("Failed to query database for thumbnail.")
+		return false, err
+	}
+	if thumbnailMetadata != nil {
+		return true, nil
+	}
+	// Note: The double-negative is intentional as os.IsExist(err) != !os.IsNotExist(err).
+	// The functions are error checkers to be used in different cases.
+	if _, err = os.Stat(string(dst)); !os.IsNotExist(err) {
+		// Thumbnail exists
+		return true, nil
+	}
+	return false, nil
+}
+
+// init with worst values
+func newThumbnailFitness() thumbnailFitness {
+	return thumbnailFitness{
+		isSmaller:      1,
+		aspect:         math.Inf(1),
+		size:           math.Inf(1),
+		methodMismatch: 0,
+		fileSize:       types.FileSizeBytes(math.MaxInt64),
+	}
+}
+
+func calcThumbnailFitness(size types.ThumbnailSize, metadata *types.MediaMetadata, desired types.ThumbnailSize) thumbnailFitness {
+	dW := desired.Width
+	dH := desired.Height
+	tW := size.Width
+	tH := size.Height
+
+	fitness := newThumbnailFitness()
+	// In all cases, a larger metric value is a worse fit.
+	// compare size: thumbnail smaller is true and gives 1, larger is false and gives 0
+	fitness.isSmaller = boolToInt(tW < dW || tH < dH)
+	// comparison of aspect ratios only makes sense for a request for desired cropped
+	fitness.aspect = math.Abs(float64(dW*tH - dH*tW))
+	// compare sizes
+	fitness.size = math.Abs(float64((dW - tW) * (dH - tH)))
+	// compare resize method
+	fitness.methodMismatch = boolToInt(size.ResizeMethod != desired.ResizeMethod)
+	if metadata != nil {
+		// file size
+		fitness.fileSize = metadata.FileSizeBytes
+	}
+
+	return fitness
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+func (a thumbnailFitness) betterThan(b thumbnailFitness, desiredCrop bool) bool {
+	// preference means returning -1
+
+	// prefer images that are not smaller
+	// e.g. isSmallerDiff > 0 means b is smaller than desired and a is not smaller
+	if a.isSmaller > b.isSmaller {
+		return false
+	} else if a.isSmaller < b.isSmaller {
+		return true
+	}
+
+	// prefer aspect ratios closer to desired only if desired cropped
+	// only cropped images have differing aspect ratios
+	// desired scaled only accepts scaled images
+	if desiredCrop {
+		if a.aspect > b.aspect {
+			return false
+		} else if a.aspect < b.aspect {
+			return true
+		}
+	}
+
+	// prefer closer in size
+	if a.size > b.size {
+		return false
+	} else if a.size < b.size {
+		return true
+	}
+
+	// prefer images using the same method
+	// e.g. methodMismatchDiff > 0 means b's method is different from desired and a's matches the desired method
+	if a.methodMismatch > b.methodMismatch {
+		return false
+	} else if a.methodMismatch < b.methodMismatch {
+		return true
+	}
+
+	// prefer smaller files
+	if a.fileSize > b.fileSize {
+		return false
+	} else if a.fileSize < b.fileSize {
+		return true
+	}
+
+	return false
+}

mediaapi/thumbnailer/thumbnailer_bimg.go

@@ -0,0 +1,248 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +build bimg
+
+package thumbnailer
+
+import (
+	"context"
+	"os"
+	"time"
+
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/dendrite/mediaapi/storage"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	log "github.com/sirupsen/logrus"
+	"gopkg.in/h2non/bimg.v1"
+)
+
+// GenerateThumbnails generates the configured thumbnail sizes for the source file
+func GenerateThumbnails(
+	ctx context.Context,
+	src types.Path,
+	configs []config.ThumbnailSize,
+	mediaMetadata *types.MediaMetadata,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	logger *log.Entry,
+) (busy bool, errorReturn error) {
+	buffer, err := bimg.Read(string(src))
+	if err != nil {
+		logger.WithError(err).WithField("src", src).Error("Failed to read src file")
+		return false, err
+	}
+	img := bimg.NewImage(buffer)
+	for _, config := range configs {
+		// Note: createThumbnail does locking based on activeThumbnailGeneration
+		busy, err = createThumbnail(
+			ctx, src, img, config, mediaMetadata, activeThumbnailGeneration,
+			maxThumbnailGenerators, db, logger,
+		)
+		if err != nil {
+			logger.WithError(err).WithField("src", src).Error("Failed to generate thumbnails")
+			return false, err
+		}
+		if busy {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+// GenerateThumbnail generates the configured thumbnail size for the source file
+func GenerateThumbnail(
+	ctx context.Context,
+	src types.Path,
+	config types.ThumbnailSize,
+	mediaMetadata *types.MediaMetadata,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	logger *log.Entry,
+) (busy bool, errorReturn error) {
+	buffer, err := bimg.Read(string(src))
+	if err != nil {
+		logger.WithError(err).WithFields(log.Fields{
+			"src": src,
+		}).Error("Failed to read src file")
+		return false, err
+	}
+	img := bimg.NewImage(buffer)
+	// Note: createThumbnail does locking based on activeThumbnailGeneration
+	busy, err = createThumbnail(
+		ctx, src, img, config, mediaMetadata, activeThumbnailGeneration,
+		maxThumbnailGenerators, db, logger,
+	)
+	if err != nil {
+		logger.WithError(err).WithFields(log.Fields{
+			"src": src,
+		}).Error("Failed to generate thumbnails")
+		return false, err
+	}
+	if busy {
+		return true, nil
+	}
+	return false, nil
+}
+
+// createThumbnail checks if the thumbnail exists, and if not, generates it
+// Thumbnail generation is only done once for each non-existing thumbnail.
+func createThumbnail(
+	ctx context.Context,
+	src types.Path,
+	img *bimg.Image,
+	config types.ThumbnailSize,
+	mediaMetadata *types.MediaMetadata,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	logger *log.Entry,
+) (busy bool, errorReturn error) {
+	logger = logger.WithFields(log.Fields{
+		"Width":        config.Width,
+		"Height":       config.Height,
+		"ResizeMethod": config.ResizeMethod,
+	})
+
+	// Check if request is larger than original
+	if isLargerThanOriginal(config, img) {
+		return false, nil
+	}
+
+	dst := GetThumbnailPath(src, config)
+
+	// Note: getActiveThumbnailGeneration uses mutexes and conditions from activeThumbnailGeneration
+	isActive, busy, err := getActiveThumbnailGeneration(dst, config, activeThumbnailGeneration, maxThumbnailGenerators, logger)
+	if err != nil {
+		return false, err
+	}
+	if busy {
+		return true, nil
+	}
+
+	if isActive {
+		// Note: This is an active request that MUST broadcastGeneration to wake up waiting goroutines!
+		// Note: broadcastGeneration uses mutexes and conditions from activeThumbnailGeneration
+		defer func() {
+			// Note: errorReturn is the named return variable so we wrap this in a closure to re-evaluate the arguments at defer-time
+			if err := recover(); err != nil {
+				broadcastGeneration(dst, activeThumbnailGeneration, config, err.(error), logger)
+				panic(err)
+			}
+			broadcastGeneration(dst, activeThumbnailGeneration, config, errorReturn, logger)
+		}()
+	}
+
+	exists, err := isThumbnailExists(ctx, dst, config, mediaMetadata, db, logger)
+	if err != nil || exists {
+		return false, err
+	}
+
+	start := time.Now()
+	width, height, err := resize(dst, img, config.Width, config.Height, config.ResizeMethod == "crop", logger)
+	if err != nil {
+		return false, err
+	}
+	logger.WithFields(log.Fields{
+		"ActualWidth":  width,
+		"ActualHeight": height,
+		"processTime":  time.Now().Sub(start),
+	}).Info("Generated thumbnail")
+
+	stat, err := os.Stat(string(dst))
+	if err != nil {
+		return false, err
+	}
+
+	thumbnailMetadata := &types.ThumbnailMetadata{
+		MediaMetadata: &types.MediaMetadata{
+			MediaID: mediaMetadata.MediaID,
+			Origin:  mediaMetadata.Origin,
+			// Note: the code currently always creates a JPEG thumbnail
+			ContentType:   types.ContentType("image/jpeg"),
+			FileSizeBytes: types.FileSizeBytes(stat.Size()),
+		},
+		ThumbnailSize: types.ThumbnailSize{
+			Width:        config.Width,
+			Height:       config.Height,
+			ResizeMethod: config.ResizeMethod,
+		},
+	}
+
+	err = db.StoreThumbnail(ctx, thumbnailMetadata)
+	if err != nil {
+		logger.WithError(err).WithFields(log.Fields{
+			"ActualWidth":  width,
+			"ActualHeight": height,
+		}).Error("Failed to store thumbnail metadata in database.")
+		return false, err
+	}
+
+	return false, nil
+}
+
+func isLargerThanOriginal(config types.ThumbnailSize, img *bimg.Image) bool {
+	imgSize, err := img.Size()
+	if err == nil && config.Width >= imgSize.Width && config.Height >= imgSize.Height {
+		return true
+	}
+	return false
+}
+
+// resize scales an image to fit within the provided width and height
+// If the source aspect ratio is different to the target dimensions, one edge will be smaller than requested
+// If crop is set to true, the image will be scaled to fill the width and height with any excess being cropped off
+func resize(dst types.Path, inImage *bimg.Image, w, h int, crop bool, logger *log.Entry) (int, int, error) {
+	inSize, err := inImage.Size()
+	if err != nil {
+		return -1, -1, err
+	}
+
+	options := bimg.Options{
+		Type:    bimg.JPEG,
+		Quality: 85,
+	}
+	if crop {
+		options.Width = w
+		options.Height = h
+		options.Crop = true
+	} else {
+		inAR := float64(inSize.Width) / float64(inSize.Height)
+		outAR := float64(w) / float64(h)
+
+		if inAR > outAR {
+			// input has wider AR than requested output so use requested width and calculate height to match input AR
+			options.Width = w
+			options.Height = int(float64(w) / inAR)
+		} else {
+			// input has narrower AR than requested output so use requested height and calculate width to match input AR
+			options.Width = int(float64(h) * inAR)
+			options.Height = h
+		}
+	}
+
+	newImage, err := inImage.Process(options)
+	if err != nil {
+		return -1, -1, err
+	}
+
+	if err = bimg.Write(string(dst), newImage); err != nil {
+		logger.WithError(err).Error("Failed to resize image")
+		return -1, -1, err
+	}
+
+	return options.Width, options.Height, nil
+}

mediaapi/thumbnailer/thumbnailer_nfnt.go

@@ -0,0 +1,272 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +build !bimg
+
+package thumbnailer
+
+import (
+	"context"
+	"image"
+	"image/draw"
+	// Imported for gif codec
+	_ "image/gif"
+	"image/jpeg"
+	// Imported for png codec
+	_ "image/png"
+	"os"
+	"time"
+
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/dendrite/mediaapi/storage"
+	"github.com/matrix-org/dendrite/mediaapi/types"
+	"github.com/nfnt/resize"
+	log "github.com/sirupsen/logrus"
+)
+
+// GenerateThumbnails generates the configured thumbnail sizes for the source file
+func GenerateThumbnails(
+	ctx context.Context,
+	src types.Path,
+	configs []config.ThumbnailSize,
+	mediaMetadata *types.MediaMetadata,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	logger *log.Entry,
+) (busy bool, errorReturn error) {
+	img, err := readFile(string(src))
+	if err != nil {
+		logger.WithError(err).WithField("src", src).Error("Failed to read src file")
+		return false, err
+	}
+	for _, singleConfig := range configs {
+		// Note: createThumbnail does locking based on activeThumbnailGeneration
+		busy, err = createThumbnail(
+			ctx, src, img, types.ThumbnailSize(singleConfig), mediaMetadata,
+			activeThumbnailGeneration, maxThumbnailGenerators, db, logger,
+		)
+		if err != nil {
+			logger.WithError(err).WithField("src", src).Error("Failed to generate thumbnails")
+			return false, err
+		}
+		if busy {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+// GenerateThumbnail generates the configured thumbnail size for the source file
+func GenerateThumbnail(
+	ctx context.Context,
+	src types.Path,
+	config types.ThumbnailSize,
+	mediaMetadata *types.MediaMetadata,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	logger *log.Entry,
+) (busy bool, errorReturn error) {
+	img, err := readFile(string(src))
+	if err != nil {
+		logger.WithError(err).WithFields(log.Fields{
+			"src": src,
+		}).Error("Failed to read src file")
+		return false, err
+	}
+	// Note: createThumbnail does locking based on activeThumbnailGeneration
+	busy, err = createThumbnail(
+		ctx, src, img, config, mediaMetadata, activeThumbnailGeneration,
+		maxThumbnailGenerators, db, logger,
+	)
+	if err != nil {
+		logger.WithError(err).WithFields(log.Fields{
+			"src": src,
+		}).Error("Failed to generate thumbnails")
+		return false, err
+	}
+	if busy {
+		return true, nil
+	}
+	return false, nil
+}
+
+func readFile(src string) (image.Image, error) {
+	file, err := os.Open(src)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close() // nolint: errcheck
+
+	img, _, err := image.Decode(file)
+	if err != nil {
+		return nil, err
+	}
+
+	return img, nil
+}
+
+func writeFile(img image.Image, dst string) (err error) {
+	out, err := os.Create(dst)
+	if err != nil {
+		return err
+	}
+	defer (func() { err = out.Close() })()
+
+	return jpeg.Encode(out, img, &jpeg.Options{
+		Quality: 85,
+	})
+}
+
+// createThumbnail checks if the thumbnail exists, and if not, generates it
+// Thumbnail generation is only done once for each non-existing thumbnail.
+func createThumbnail(
+	ctx context.Context,
+	src types.Path,
+	img image.Image,
+	config types.ThumbnailSize,
+	mediaMetadata *types.MediaMetadata,
+	activeThumbnailGeneration *types.ActiveThumbnailGeneration,
+	maxThumbnailGenerators int,
+	db *storage.Database,
+	logger *log.Entry,
+) (busy bool, errorReturn error) {
+	logger = logger.WithFields(log.Fields{
+		"Width":        config.Width,
+		"Height":       config.Height,
+		"ResizeMethod": config.ResizeMethod,
+	})
+
+	// Check if request is larger than original
+	if config.Width >= img.Bounds().Dx() && config.Height >= img.Bounds().Dy() {
+		return false, nil
+	}
+
+	dst := GetThumbnailPath(src, config)
+
+	// Note: getActiveThumbnailGeneration uses mutexes and conditions from activeThumbnailGeneration
+	isActive, busy, err := getActiveThumbnailGeneration(dst, config, activeThumbnailGeneration, maxThumbnailGenerators, logger)
+	if err != nil {
+		return false, err
+	}
+	if busy {
+		return true, nil
+	}
+
+	if isActive {
+		// Note: This is an active request that MUST broadcastGeneration to wake up waiting goroutines!
+		// Note: broadcastGeneration uses mutexes and conditions from activeThumbnailGeneration
+		defer func() {
+			// Note: errorReturn is the named return variable so we wrap this in a closure to re-evaluate the arguments at defer-time
+			// if err := recover(); err != nil {
+			// 	broadcastGeneration(dst, activeThumbnailGeneration, config, err.(error), logger)
+			// 	panic(err)
+			// }
+			broadcastGeneration(dst, activeThumbnailGeneration, config, errorReturn, logger)
+		}()
+	}
+
+	exists, err := isThumbnailExists(ctx, dst, config, mediaMetadata, db, logger)
+	if err != nil || exists {
+		return false, err
+	}
+
+	start := time.Now()
+	width, height, err := adjustSize(dst, img, config.Width, config.Height, config.ResizeMethod == types.Crop, logger)
+	if err != nil {
+		return false, err
+	}
+	logger.WithFields(log.Fields{
+		"ActualWidth":  width,
+		"ActualHeight": height,
+		"processTime":  time.Since(start),
+	}).Info("Generated thumbnail")
+
+	stat, err := os.Stat(string(dst))
+	if err != nil {
+		return false, err
+	}
+
+	thumbnailMetadata := &types.ThumbnailMetadata{
+		MediaMetadata: &types.MediaMetadata{
+			MediaID: mediaMetadata.MediaID,
+			Origin:  mediaMetadata.Origin,
+			// Note: the code currently always creates a JPEG thumbnail
+			ContentType:   types.ContentType("image/jpeg"),
+			FileSizeBytes: types.FileSizeBytes(stat.Size()),
+		},
+		ThumbnailSize: types.ThumbnailSize{
+			Width:        config.Width,
+			Height:       config.Height,
+			ResizeMethod: config.ResizeMethod,
+		},
+	}
+
+	err = db.StoreThumbnail(ctx, thumbnailMetadata)
+	if err != nil {
+		logger.WithError(err).WithFields(log.Fields{
+			"ActualWidth":  width,
+			"ActualHeight": height,
+		}).Error("Failed to store thumbnail metadata in database.")
+		return false, err
+	}
+
+	return false, nil
+}
+
+// adjustSize scales an image to fit within the provided width and height
+// If the source aspect ratio is different to the target dimensions, one edge will be smaller than requested
+// If crop is set to true, the image will be scaled to fill the width and height with any excess being cropped off
+func adjustSize(dst types.Path, img image.Image, w, h int, crop bool, logger *log.Entry) (int, int, error) {
+	var out image.Image
+	var err error
+	if crop {
+		inAR := float64(img.Bounds().Dx()) / float64(img.Bounds().Dy())
+		outAR := float64(w) / float64(h)
+
+		var scaleW, scaleH uint
+		if inAR > outAR {
+			// input has shorter AR than requested output so use requested height and calculate width to match input AR
+			scaleW = uint(float64(h) * inAR)
+			scaleH = uint(h)
+		} else {
+			// input has taller AR than requested output so use requested width and calculate height to match input AR
+			scaleW = uint(w)
+			scaleH = uint(float64(w) / inAR)
+		}
+
+		scaled := resize.Resize(scaleW, scaleH, img, resize.Lanczos3)
+
+		xoff := (scaled.Bounds().Dx() - w) / 2
+		yoff := (scaled.Bounds().Dy() - h) / 2
+
+		tr := image.Rect(0, 0, w, h)
+		target := image.NewRGBA(tr)
+		draw.Draw(target, tr, scaled, image.Pt(xoff, yoff), draw.Src)
+		out = target
+	} else {
+		out = resize.Thumbnail(uint(w), uint(h), img, resize.Lanczos3)
+		if err != nil {
+			return -1, -1, err
+		}
+	}
+
+	if err = writeFile(out, string(dst)); err != nil {
+		logger.WithError(err).Error("Failed to encode and write image")
+		return -1, -1, err
+	}
+
+	return out.Bounds().Max.X, out.Bounds().Max.Y, nil
+}

mediaapi/types/types.go

@@ -0,0 +1,110 @@
+// Copyright 2017 Vector Creations Ltd
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types
+
+import (
+	"sync"
+
+	"github.com/matrix-org/dendrite/common/config"
+	"github.com/matrix-org/gomatrixserverlib"
+)
+
+// FileSizeBytes is a file size in bytes
+type FileSizeBytes int64
+
+// ContentType is an HTTP Content-Type header string representing the MIME type of a request body
+type ContentType string
+
+// Filename is a string representing the name of a file
+type Filename string
+
+// Base64Hash is a base64 URLEncoding string representation of a SHA-256 hash sum
+type Base64Hash string
+
+// Path is an absolute or relative UNIX filesystem path
+type Path string
+
+// MediaID is a string representing the unique identifier for a file (could be a hash but does not have to be)
+type MediaID string
+
+// RequestMethod is an HTTP request method i.e. GET, POST, etc
+type RequestMethod string
+
+// MatrixUserID is a Matrix user ID string in the form @user:domain e.g. @alice:matrix.org
+type MatrixUserID string
+
+// UnixMs is the milliseconds since the Unix epoch
+type UnixMs int64
+
+// MediaMetadata is metadata associated with a media file
+type MediaMetadata struct {
+	MediaID           MediaID
+	Origin            gomatrixserverlib.ServerName
+	ContentType       ContentType
+	FileSizeBytes     FileSizeBytes
+	CreationTimestamp UnixMs
+	UploadName        Filename
+	Base64Hash        Base64Hash
+	UserID            MatrixUserID
+}
+
+// RemoteRequestResult is used for broadcasting the result of a request for a remote file to routines waiting on the condition
+type RemoteRequestResult struct {
+	// Condition used for the requester to signal the result to all other routines waiting on this condition
+	Cond *sync.Cond
+	// MediaMetadata of the requested file to avoid querying the database for every waiting routine
+	MediaMetadata *MediaMetadata
+	// An error, nil in case of no error.
+	Error error
+}
+
+// ActiveRemoteRequests is a lockable map of media URIs requested from remote homeservers
+// It is used for ensuring multiple requests for the same file do not clobber each other.
+type ActiveRemoteRequests struct {
+	sync.Mutex
+	// The string key is an mxc:// URL
+	MXCToResult map[string]*RemoteRequestResult
+}
+
+// ThumbnailSize contains a single thumbnail size configuration
+type ThumbnailSize config.ThumbnailSize
+
+// ThumbnailMetadata contains the metadata about an individual thumbnail
+type ThumbnailMetadata struct {
+	MediaMetadata *MediaMetadata
+	ThumbnailSize ThumbnailSize
+}
+
+// ThumbnailGenerationResult is used for broadcasting the result of thumbnail generation to routines waiting on the condition
+type ThumbnailGenerationResult struct {
+	// Condition used for the generator to signal the result to all other routines waiting on this condition
+	Cond *sync.Cond
+	// Resulting error from the generation attempt
+	Err error
+}
+
+// ActiveThumbnailGeneration is a lockable map of file paths being thumbnailed
+// It is used to ensure thumbnails are only generated once.
+type ActiveThumbnailGeneration struct {
+	sync.Mutex
+	// The string key is a thumbnail file path
+	PathToResult map[string]*ThumbnailGenerationResult
+}
+
+// Crop indicates we should crop the thumbnail on resize
+const Crop = "crop"
+
+// Scale indicates we should scale the thumbnail on resize
+const Scale = "scale"