upload

type Claimer interface {
	// Pending claims key for scope, which nothing has been stored under
	// yet, leased until until: Save publishes nothing under key after it.
	Pending(ctx context.Context, key, scope string, until time.Time) error
	// Stage claims key for scope, for a direct upload to StagingKey(key)
	// (Authorize).
	Stage(ctx context.Context, key, scope string, until time.Time) error
	// Promote moves a key staged for scope to promoting, leased until
	// until, and reports whether it did: only then may Confirm copy the
	// staged object to key.
	Promote(ctx context.Context, key, scope string, until time.Time) (bool, error)
	// Lookup reports the scope key is claimed for, and whether that claim
	// is live (not being deleted, nor gone).
	Lookup(ctx context.Context, key string) (scope string, live bool, err error)
	// Publishing records the token of the promotion's copy on the key's
	// promoting claim, before it is published (storage.PreparePublish).
	Publishing(ctx context.Context, key, token string) error
	// Unpromote moves a promoting key back to pending (nothing was copied).
	Unpromote(ctx context.Context, key string) error
	// Abandon deletes the object of key and its claim if the claim is
	// still pending, and reports whether it did; it leaves any other key
	// alone.
	Abandon(ctx context.Context, key string) (bool, error)
}

type CleanupError struct {
	Key string
	Err error // why the delete failed
}

type Detector func(head []byte) string

type File struct {
	storage.ObjectInfo
	// Filename is the client's filename, cleaned (empty when it sent none):
	// for display and Content-Disposition only, never a path. It is the
	// stored FilenameMetadata (ObjectInfo.StoredFilename).
	Filename string
}

type Grant struct {
	// Key is where the file will be: Policy.Prefix and a random id.
	Key string `json:"key"`
	// Request is the upload for the client to make.
	Request storage.UploadRequest `json:"upload"`
}

type Policy struct {
	// MaxBytes is the largest file accepted, in bytes. Required.
	MaxBytes int64
	// Types lists the media types accepted, as detected from the file's
	// content: "image/png", or "image/*" for a whole top-level type.
	// Required: "*/*" accepts any type, and must be asked for.
	Types []string
	// Prefix starts every generated key ("avatars/"): empty, or a valid
	// key path ending with '/'.
	Prefix string
	// Field is the multipart form field holding the file (DefaultField
	// when empty). Receive only.
	Field string
	// Detect detects the media type (http.DetectContentType when nil). The
	// default recognizes common images, audio, video, PDF, archives, and
	// fonts, and reports text as text/plain or text/html; it never reports
	// image/svg+xml or application/json. Supply a Detector for types it
	// does not recognize.
	Detect Detector
	// Metadata is stored with every file, besides FilenameMetadata (which
	// it must not set).
	Metadata map[string]string
	// GrantExpiry is how long a direct upload grant (Authorize) works,
	// counted from the start of the second it is signed in, as for any
	// signed URL (DefaultGrantExpiry when zero; whole seconds, at most
	// storage.MaxURLExpiry).
	GrantExpiry time.Duration
	// UploadTimeout bounds how long the application may take to write a
	// claimed key under Claims (DefaultUploadTimeout when zero): Save's and
	// Receive's Put, and Confirm's copy of a staged upload, are aborted
	// then, before they publish, so the key's claim can lease it until a
	// known time (storage/claims). Unused without Claims.
	UploadTimeout time.Duration
	// Claims, when set, puts uploads under an ownership protocol
	// (storage/claims: a *claims.Claims). Each generated key is claimed
	// (Pending) before anything is stored or granted under it, and a
	// failure to claim fails the upload. A file that fails (an invalid
	// request, a refused confirmation) is deleted through Abandon, which
	// deletes it only while its claim is pending: never a file a record
	// holds, nor one under a key that was never claimed.
	Claims Claimer
	// Scope names who the uploads are for under Claims (a field:
	// "document.attachment"), at most 255 bytes. Each key is claimed for
	// it, and Confirm accepts only a key claimed for the same scope: a
	// grant from one field cannot be attached to another, whatever their
	// prefixes. Give every policy sharing a store under Claims its own.
	Scope string
}