upload

Documentation

Index

• Variables
• func Path(strings ...string) string
• func SetMaxConcurrency(n int, limiter *bottleneck.Client) func(ChunkHandler) ChunkHandler
• func SetSessionMaxAge(maxage int) func(ChunkHandler) ChunkHandler
• func SetUploadIDgenerator(uuidFn func() (string, error)) func(ChunkHandler) ChunkHandler
• type ChunkHandler
  • func Chunked(h Handler) ChunkHandler
  • func (c ChunkHandler) Configure(functions ...func(ChunkHandler) ChunkHandler) ChunkHandler
  • func (c ChunkHandler) Initializer() Initializer
  • func (c ChunkHandler) Link(hn xhttp.Handler) xhttp.HandlerLinker
  • func (h ChunkHandler) ParseUpload(w http.ResponseWriter, r *http.Request) (ParseResult, error)
  • func (c ChunkHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Field
  • func NewField(name string, sizelimit int, required bool, AcceptedContentTypes ...string) Field
  • func NewFileField(name string, sizelimit int, required bool, multiple bool, storagepath string, ...) Field
  • func (f Field) IsValid() (bool, error)
  • func (f Field) Validator(v ...func(Field) (bool, error)) Field
• type FileList
  • func (f FileList) Size() int64
• type Form
  • func NewForm(fields ...Field) Form
  • func (f Form) Get(fieldname string) (val []byte, err error)
• type Handler
  • func New(f Form, s session.Handler, uploadpath string, ...) Handler
  • func (h Handler) Link(hn xhttp.Handler) xhttp.HandlerLinker
  • func (h Handler) ParseUpload(w http.ResponseWriter, r *http.Request) (ParseResult, error)
  • func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (h Handler) WithLogger(l *log.Logger) Handler
• type Initializer
  • func (i Initializer) Link(h xhttp.HandlerLinker) xhttp.Handler
  • func (i Initializer) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Object
  • func NewFile(src io.Reader, filename string, contenttype string, uploaderID string, ...) Object
  • func (o Object) EvalPath() string
• type ParseResult
  • func ParseResults(ctx context.Context) (ParseResult, bool)
  • func (c ParseResult) Add(cancelFn ...func() error)
  • func (c ParseResult) Cancel() error

Variables

var (
	FileNameHeader    = http.CanonicalHeaderKey("filename")
	FileSizeHeader    = http.CanonicalHeaderKey("filesize")
	UploadIDHeader    = http.CanonicalHeaderKey("uploadid")
	ChunkOffsetHeader = http.CanonicalHeaderKey("chunkoffset")
	ChunksTotalHeader = http.CanonicalHeaderKey("chunkstotal")
	ChunkSizeHeader   = http.CanonicalHeaderKey("chunksize")

	ErrMissingUploadID    = errors.New("uploadid header missing")
	ErrMissingFilename    = errors.New("filename header missing")
	ErrMissingFilesize    = errors.New("filesize header missing")
	ErrMissingChunkOffset = errors.New("chunkoffset header missing")
	ErrMissingChunksTotal = errors.New("chunkstotal header missing")
	ErrMissingChunksize   = errors.New("chunksize header missing")

	TicketKey = "uploadticket"
)

var (
	AudioMIMETypes = newSet().Add("audio/mpeg", "audio/ogg", "audio/wav", "audio/webm", "audio/basic", "audio/aiff", "audio/midi", "audio/wave")
	VideoMIMETypes = newSet().Add("video/avi", "video/mpeg", "video/ogg", "video/webm", "video/mp4")
)

var (
	ErrUploadTooLarge    = errors.New("Upload too large")
	ErrNoBoundary        = errors.New("Unable to parse submitted form. Missing boundary.")
	ErrServerFormInvalid = errors.New("Server Error: upload form is invalid.")
	ErrClientFormInvalid = errors.New("Client Error: submitted upload form is invalid.")
	ErrParsingFailed     = errors.New("Failed to parse form.")
	ErrBadContentType    = errors.New("Unsupported content type.")
	ErrUploadingFailed   = errors.New("File uploading failed")
)

Functions

func Path

func Path(strings ...string) string

Path is a utility function used to create upload storage path and s3 keys.

func SetMaxConcurrency

func SetMaxConcurrency(n int, limiter *bottleneck.Client) func(ChunkHandler) ChunkHandler

func SetSessionMaxAge

func SetSessionMaxAge(maxage int) func(ChunkHandler) ChunkHandler

SetSessionMaxAge sets the upload session maxage in seconds.

func SetUploadIDgenerator

func SetUploadIDgenerator(uuidFn func() (string, error)) func(ChunkHandler) ChunkHandler

Types

type ChunkHandler

type ChunkHandler struct {
	Handler
	Session session.Handler
	// contains filtered or unexported fields
}

func Chunked

func Chunked(h Handler) ChunkHandler

New returns a handler for a chunked upload request. An upload request starts by the creation of an upload session. By defauklt, the session remains valid for seven days

func (ChunkHandler) Configure

func (c ChunkHandler) Configure(functions ...func(ChunkHandler) ChunkHandler) ChunkHandler

func (ChunkHandler) Initializer

func (c ChunkHandler) Initializer() Initializer

func (ChunkHandler) Link

func (c ChunkHandler) Link(hn xhttp.Handler) xhttp.HandlerLinker

func (ChunkHandler) ParseUpload

func (h ChunkHandler) ParseUpload(w http.ResponseWriter, r *http.Request) (ParseResult, error)

ParseUpload parses a submitted form-data POST or PUT request, uploading any submitted file within the limits defined for the endpoint in terms of upload size.

func (ChunkHandler) ServeHTTP

func (c ChunkHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Field

type Field struct {
	Name        string
	Body        []byte
	ContentType string

	Path  string
	Files FileList

	AllowedContentTypes set
	SizeLimit           int64
	Required            bool

	Validators []func(Field) (bool, error)
	// contains filtered or unexported fields
}

Field is a type used to define the structure of a form field.

func NewField

func NewField(name string, sizelimit int, required bool, AcceptedContentTypes ...string) Field

NewField is used to create the specification for a data form field with that the client request should adhere to.

func NewFileField

func NewFileField(name string, sizelimit int, required bool, multiple bool, storagepath string, uploadFn func(context.Context, Object) (bytesuploaded int64, rollbackFn func() error, err error), AcceptedContentTypes ...string) Field

NewFileField is used to create the specification for a file upload form field

with constraints that the client should adhere to and that the request parser

will verify.

func (Field) IsValid

func (f Field) IsValid() (bool, error)

IsValid rettur,s the validity of a submitted form field with an accompanying explanatory error in case of failure.

func (Field) Validator

func (f Field) Validator(v ...func(Field) (bool, error)) Field

Validators register validatiog functions for a form field .

type FileList

type FileList []Object

func (FileList) Size

func (f FileList) Size() int64

type Form

type Form []Field

Form is a type that can be used to represent the structure of a form upload as expected by the server. The server would parse a POST or PUT form-data upload and validate it. Any file is stream uploaded to its end storage thanks to a provided uploading function specified when creating the expected FileField.

func NewForm

func NewForm(fields ...Field) Form

NewForm returns an upload form specification used when parsing a form upload request.

func (Form) Get

func (f Form) Get(fieldname string) (val []byte, err error)

Get returns the vraw value sent for the (non-file) form field of the given name. It returns a non nil error if the field cannot be found after parsing.

type Handler

type Handler struct {
	Form    Form
	Session session.Handler // used to retrieve the session id

	Path string

	FileIDgenerator func() (string, error) // used to generate a file unique identifier

	Log *log.Logger
	// contains filtered or unexported fields
}

Handler handles http upload requests, verifying that the request implements the specification of the upload.Form.

func New

func New(f Form, s session.Handler, uploadpath string, fileUUIDgenerator func() (string, error)) Handler

New returns a http request handler that will parse a request in order to try and retrieve values if the structure of the request fits the expected model defined in an upload Form.

func (Handler) Link

func (h Handler) Link(hn xhttp.Handler) xhttp.HandlerLinker

func (Handler) ParseUpload

func (h Handler) ParseUpload(w http.ResponseWriter, r *http.Request) (ParseResult, error)

ParseUpload parses a submitted form-data POST or PUT request, uploading any submitted file within the limits defined for the endpoint in terms of upload size.

func (Handler) ServeHTTP

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (Handler) WithLogger

func (h Handler) WithLogger(l *log.Logger) Handler

WithLogger enables logging capabilities. Typically for logging errors. such as a failure to rollback an upload even though the parsing failed because the submitted form requets is malformed.

type Initializer

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

Initializer handles chunked upload initialization request. It creates a new session upload whose id should be transmitted to the client to attach to each chunk information. The upload id generator that should be used can be further specified via the SetUploadIDgenerator config function..

func (Initializer) Link

func (i Initializer) Link(h xhttp.HandlerLinker) xhttp.Handler

func (Initializer) ServeHTTP

func (i Initializer) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Object

type Object struct {
	UploadID   string // can be created by the upload process/function.
	UploaderID string
	Size       int64 // object size : if not chunked, Size = FileSize

	ChunkOffset int64
	ChunksTotal int64

	Filename string // If file name is absent, it shpould be replace by FileUUID
	Filesize int64
	FileUUID string // server-generated
	Path     string

	ContentType string
	Binary      io.Reader
}

Object is a structured representation for an upload file and its metadata.

func NewFile

func NewFile(src io.Reader, filename string, contenttype string, uploaderID string, uploadpath string) Object

NewFile creates a new upload.Object used to hold uploading information as well as upload data accessible via an io.Reader. The accompanying upload object info can be stored in the database once the data has been successfully uploaded.

func (Object) EvalPath

func (o Object) EvalPath() string

EvalPath replaces the placeholder strings starting by '%' with their respective value as stored in the Object type variable.

type ParseResult

type ParseResult struct {
	Form Form
	// contains filtered or unexported fields
}

ParseResult holds the results from parsing a form upload request. It holds the form filled from the parsed data and a ffunction that can be used to try and rollback the file uploads. (for instance in case registering the file data in the database failed, one could decide to rollback the file storage) Canceling/rolling back an upload should be idemptotent. Means that each file uploads returning a cancelation function should return an idempotent one.

func ParseResults

func ParseResults(ctx context.Context) (ParseResult, bool)

ParseResults attempts to retrieve the results obtained after an upload request has been parsed.

func (ParseResult) Add

func (c ParseResult) Add(cancelFn ...func() error)

func (ParseResult) Cancel

func (c ParseResult) Cancel() error