imup

README

imup

imup is an image upload handler written in Go.

Managing image uploads over HTTP in Go can be difficult when taking into account file type and request length checks, handling request cancellation, and so on. This package was built to abstract those details away and provide a simple API to make dealing with image uploads easier.

Special Thanks to @vcabbage for the brilliant max file size solution!

This project was created for MailDB.io, check us out!

Features

• Handles all MIME image types defined in the standard http lib:
  GIF, PNG, JPEG, BMP, WEBP, ICO
• Set allowable image formats
• Supports max file size limit
• Reads data only up to max file size limit, will not eat up bandwidth
• Handles spoofed Content-Length header

Installation

Fetch the package from GitHub:

go get github.com/beeker1121/imup

Import to your project:

import "github.com/beeker1121/imup"

Usage

func handler(w http.ResponseWriter, r *http.Request) {
	// Parse the uploaded file.
	ui, err = imup.New("file", r, &imup.Options{
		MaxFileSize:  1 * 1024 * 1024,   // 1 MB
		AllowedTypes: imup.PopularTypes,
	})
	if err != nil {
		...
	}

	// Save the image.
	filename, err := ui.Save("images/test")
	if err != nil {
		...
	}

	fmt.Println(filename) // images/test.png
}

License

MIT license

Documentation

Index

• Constants
• Variables
• type ImageTypes
• type Options
• type UploadedImage
  • func New(key string, r *http.Request, opts *Options) (*UploadedImage, error)
  • func (ui *UploadedImage) Close() error
  • func (ui *UploadedImage) Save(filename string) (string, error)

Constants

const (
	GIF  = "image/gif"
	PNG  = "image/png"
	JPEG = "image/jpeg"
	BMP  = "image/bmp"
	WEBP = "image/webp"
	ICO  = "image/vnd.microsoft.icon"
)

Image types according to the MIME specification.

Variables

var (
	// ErrDisallowedType is returned when the uploaded
	// file type is not allowed.
	ErrDisallowedType = errors.New("File type is not allowed")

	// ErrFileSize is returned when the uploaded file
	// size exceeds the max file size limit.
	ErrFileSize = errors.New("File size exceeds max limit")
)

var (
	PopularTypes = ImageTypes{GIF, PNG, JPEG}
	AllTypes     = ImageTypes{GIF, PNG, JPEG, BMP, WEBP, ICO}
)

Convenience set of image types.

Types

type ImageTypes

type ImageTypes []string

ImageTypes defines the allowed types for an uploaded image.

type Options

type Options struct {
	MaxFileSize  int64
	AllowedTypes ImageTypes
}

Options defines the available options for an image upload.

type UploadedImage

type UploadedImage struct {
	Type string
	// contains filtered or unexported fields
}

UploadedImage defines an uploaded image.

func New

func New(key string, r *http.Request, opts *Options) (*UploadedImage, error)

New returns a new UploadedImage object if the uploaded file could be parsed and validated as an image, otherwise it returns an error.

The key parameter should refer to the name of the file input from the multipart form.

func (*UploadedImage) Close

func (ui *UploadedImage) Close() error

Close closes an uploaded image.

func (*UploadedImage) Save

func (ui *UploadedImage) Save(filename string) (string, error)

Save saves the uploaded image to the given location and returns the location with the correct image extension added on.

The underlying multipart image file is automatically closed.