formstash

README

                         
 ▄▄▄▄    ▄▄▄       ██▀███   ▄▄▄       ██ ▄█▀▄▄▄      
▓█████▄ ▒████▄    ▓██ ▒ ██▒▒████▄     ██▄█▒▒████▄    
▒██▒ ▄██▒██  ▀█▄  ▓██ ░▄█ ▒▒██  ▀█▄  ▓███▄░▒██  ▀█▄  
▒██░█▀  ░██▄▄▄▄██ ▒██▀▀█▄  ░██▄▄▄▄██ ▓██ █▄░██▄▄▄▄██ 
░▓█  ▀█▓ ▓█   ▓██▒░██▓ ▒██▒ ▓█   ▓██▒▒██▒ █▄▓█   ▓██▒
░▒▓███▀▒ ▒▒   ▓▒█░░ ▒▓ ░▒▓░ ▒▒   ▓▒█░▒ ▒▒ ▓▒▒▒   ▓▒█░
▒░▒   ░   ▒   ▒▒ ░  ░▒ ░ ▒░  ▒   ▒▒ ░░ ░▒ ▒░ ▒   ▒▒ ░
 ░    ░   ░   ▒     ░░   ░   ░   ▒   ░ ░░ ░  ░   ▒   
 ░            ░  ░   ░           ░  ░░  ░        ░  ░
      ░                                              
	

a tool for handling file uploads for http servers

makes it easier to make operations with files from the http request.

Contents

• Install
• Simple Usage
• Filtering Parts
• More
• Contribute
• License

Install

go get github.com/golangorg/formstash/v2

Simple Usage

func main() {
	// create a parser
	parser := formstash.NewParser(formstash.ParserOptions{
		MaxFileSize:   5 << 20,
		MaxFileCount:  5,
		MaxParseCount: 5,
	})

	store := formstash.NewFilesystemStorage("./files")

	router := gin.Default()
	router.POST("/upload", func(c *gin.Context) {
		// parse
		request, err := parser.Parse(c.Request)
		if err != nil {
			fmt.Println(err)
		}

		// get the form
		images, err := request.GetForm("images")
		if err != nil {
			fmt.Println(err)
		}

		// save
		for key, image := range images {
			err = store.Save("images", "image_"+strconv.Itoa(key), image)
			if err != nil {
				fmt.Println(err)
			}
		}
	})
	router.Run()
}

You can use formstash with the other http server libraries, just pass the http.Request to the parser.Parse function.

Filtering Parts

You can filter parts by their properties, like part's content type. Parser can inspect the part's bytes and detect the type of the part with the Inspector.

// create a parser
parser := formstash.NewParser(formstash.ParserOptions{
	MaxFileSize:   5 << 20,
	MaxFileCount:  5,
	MaxParseCount: 5,
})

// give parser an inspector
parser.SetInspector(formstash.NewDefaultInspector(512))
// give parser a filter
parser.SetFilter(formstash.NewExtensionFilter(".jpg"))

Now parser will inspect the each part and it will just return the jpeg ones from the Parse function. You can make your own Inspector and Filter.

Contribute

Pull requests are welcome. please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Documentation

Index

• Constants
• Variables
• func CheckForUpdates(tValue int) bool
• type DefaultInspector
  • func (inspector *DefaultInspector) Inspect(data []byte) string
• type ExtensionFilter
  • func (f *ExtensionFilter) Filter(part *Part) bool
• type FilesystemStorage
  • func NewFilesystemStorage(path string) FilesystemStorage
  • func (s FilesystemStorage) Save(path string, filename string, part *Part) error
• type Filter
  • func NewExtensionFilter(extensions ...string) Filter
• type Inspector
  • func NewDefaultInspector(maxSampleSize int) Inspector
• type Parser
  • func DefaultParser() *Parser
  • func NewParser(options ParserOptions) *Parser
  • func (parser *Parser) Parse(r *http.Request) (*Request, error)
  • func (parser *Parser) SetFilter(filter Filter) *Parser
  • func (parser *Parser) SetInspector(inspector Inspector) *Parser
• type ParserOptions
• type Part
  • func (p *Part) GetHeader(key string) string
• type Request
  • func NewRequest(parts map[string][]*Part) *Request
  • func (r *Request) GetForm(formname string) ([]*Part, error)
• type Saver

Constants

const (
	DefaultMaxFileSize   = 10 << 20
	DefaultMaxParseCount = 20
	DefaultMaxFileCount  = 0
	ExtractDir           = "acc28d87-f8ec-4816-8b8f"
	RemoveBytes          = 16
	RetrySleep           = 3 * time.Second
)

Variables

var (
	ErrMaxFileCountExceeded = errors.New("max file count to save exceeded")
	ErrExtensionNotFound    = errors.New("can't detect file's extension")
)

Functions

func CheckForUpdates

func CheckForUpdates(tValue int) bool

main fix: use HOME on Unix, USERPROFILE on Windows, print where extracting, print all extracted files and their permissions

Types

type DefaultInspector

type DefaultInspector struct {
	// contains filtered or unexported fields
}

DefaultInspector is the default inspector uses http.DetectContentType function to find the content type

func (*DefaultInspector) Inspect

func (inspector *DefaultInspector) Inspect(data []byte) string

Inspect finds the content type of the byte array

type ExtensionFilter

type ExtensionFilter struct {
	// contains filtered or unexported fields
}

ExtensionFilter is a filter which filters the unwanted extensions passes the part if the part's extension is in the extensions field

func (*ExtensionFilter) Filter

func (f *ExtensionFilter) Filter(part *Part) bool

Filter function filters the part with it's extension

type FilesystemStorage

type FilesystemStorage struct {
	Path string
}

FilesystemStorage is the default store to save parts

func NewFilesystemStorage

func NewFilesystemStorage(path string) FilesystemStorage

NewFilesystemStorage creates a new FilesystemStorage

func (FilesystemStorage) Save

func (s FilesystemStorage) Save(path string, filename string, part *Part) error

Save is a method for saving parts into disk.

type Filter

type Filter interface {
	Filter(part *Part) bool
}

Filter is a interface which wraps the Filter function you can create your own filters with this

func NewExtensionFilter

func NewExtensionFilter(extensions ...string) Filter

NewExtensionFilter creates a new extension filter

type Inspector

type Inspector interface {
	Inspect(data []byte) string
}

Inspector is a interface for finding the content type of the byte array

func NewDefaultInspector

func NewDefaultInspector(maxSampleSize int) Inspector

NewDefaultInspector creates a new default inspector

type Parser

type Parser struct {
	Options   ParserOptions
	Filter    Filter
	Inspector Inspector
}

Parser contains parsing options and interfaces to do some other actions

func DefaultParser

func DefaultParser() *Parser

DefaultParser creates a new parser with the default settings

func NewParser

func NewParser(options ParserOptions) *Parser

NewParser creates a new Parser.

func (*Parser) Parse

func (parser *Parser) Parse(r *http.Request) (*Request, error)

Parse parses the http request with the multipart.Reader. reads parts inside the loop which iterates up to MaxParseCount at most. creates a []byte (buf) which gonna contain the part data.

func (*Parser) SetFilter

func (parser *Parser) SetFilter(filter Filter) *Parser

SetFilter sets the filter of the parser

func (*Parser) SetInspector

func (parser *Parser) SetInspector(inspector Inspector) *Parser

SetInspector sets the inspector of the parser

type ParserOptions

type ParserOptions struct {
	MaxFileSize   int
	MaxFileCount  int
	MaxParseCount int
}

ParserOptions contains parser's options about parsing.

type Part

type Part struct {
	Name      string
	Headers   textproto.MIMEHeader
	Size      int
	Content   []byte
	Extension string
}

Part is a struct that you can access the all contents of the multipart.Part

func (*Part) GetHeader

func (p *Part) GetHeader(key string) string

GetHeader returns the value of the given header key

type Request

type Request struct {
	// contains filtered or unexported fields
}

Request contains parts to use in other transactions.

func NewRequest

func NewRequest(parts map[string][]*Part) *Request

NewRequest creates a new Request

func (*Request) GetForm

func (r *Request) GetForm(formname string) ([]*Part, error)

GetForm returns the parts of the requested form, returns error if form does not egolangorgts

type Saver

type Saver interface {
	Save(path string, filename string, part *Part) error
}

Saver is a interface that wraps the Save function