Documentation
¶
Overview ¶
Package uploads provides file upload storage as a burrow contrib app. It offers a pluggable Store interface with a local filesystem implementation and content-hashed filenames for deduplication.
Index ¶
- Variables
- func StoreFile(r *http.Request, fieldName string, storage Store, opts StoreOptions) (string, error)
- func URL(ctx context.Context, key string) string
- func WithStorage(ctx context.Context, s Store) context.Context
- type App
- func (a *App) AllowedTypes() []string
- func (a *App) Configure(cmd *cli.Command) error
- func (a *App) Flags(configSource func(key string) cli.ValueSource) []cli.Flag
- func (a *App) Middleware() []func(http.Handler) http.Handler
- func (a *App) Name() string
- func (a *App) Register(_ *burrow.AppConfig) error
- func (a *App) Routes(r chi.Router)
- func (a *App) Store() Store
- type LocalStorage
- func (s *LocalStorage) Delete(_ context.Context, key string) error
- func (s *LocalStorage) Open(_ context.Context, key string) (io.ReadCloser, error)
- func (s *LocalStorage) Path(key string) (string, error)
- func (s *LocalStorage) Store(_ context.Context, file io.Reader, opts StoreOptions) (string, error)
- func (s *LocalStorage) URL(key string) string
- type Option
- type Store
- type StoreOptions
Constants ¶
This section is empty.
Variables ¶
var ( ErrTypeNotAllowed = errors.New("uploads: file type not allowed") ErrFileTooLarge = errors.New("uploads: file too large") ErrEmptyFile = errors.New("uploads: empty file") ErrMissingField = errors.New("uploads: missing form field") )
Sentinel errors for upload validation.
var ErrPathTraversal = errors.New("uploads: key escapes root directory")
ErrPathTraversal is returned when a storage key attempts to escape the root directory.
Functions ¶
func StoreFile ¶
StoreFile extracts a file from a multipart request and stores it. It returns the storage key on success.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App implements the uploads contrib app for file storage and serving.
func New ¶
New creates an uploads app with sensible defaults:
- Upload directory: ./uploads (relative to working directory)
- URL prefix: /uploads/
- Allowed types: all
Use options to customize, or override at runtime via CLI flags (--upload-dir, --upload-url-prefix, --upload-allowed-types).
func (*App) AllowedTypes ¶
AllowedTypes returns the globally configured allowed MIME types.
type LocalStorage ¶
type LocalStorage struct {
// contains filtered or unexported fields
}
LocalStorage stores files on the local filesystem.
func NewLocalStorage ¶
func NewLocalStorage(root, urlPrefix string) (*LocalStorage, error)
NewLocalStorage creates a LocalStorage that persists files under root and serves them at urlPrefix.
func (*LocalStorage) Delete ¶
func (s *LocalStorage) Delete(_ context.Context, key string) error
Delete removes the file at the given key. It does not return an error if the file does not exist. Returns ErrPathTraversal if the key would escape the root directory.
func (*LocalStorage) Open ¶
func (s *LocalStorage) Open(_ context.Context, key string) (io.ReadCloser, error)
Open returns a reader for the file at the given key. Returns ErrPathTraversal if the key would escape the root directory.
func (*LocalStorage) Path ¶
func (s *LocalStorage) Path(key string) (string, error)
Path returns the filesystem path for the given storage key. Returns ErrPathTraversal if the key would escape the root directory. This is specific to LocalStorage and not part of the Store interface.
func (*LocalStorage) Store ¶
func (s *LocalStorage) Store(_ context.Context, file io.Reader, opts StoreOptions) (string, error)
Store persists a file and returns its content-hashed storage key.
func (*LocalStorage) URL ¶
func (s *LocalStorage) URL(key string) string
URL returns the public URL for the given storage key.
type Option ¶
type Option func(*App)
Option configures the uploads app.
func WithAllowedTypes ¶
WithAllowedTypes sets the default allowed MIME types for uploads. Per-call StoreOptions.AllowedTypes overrides this default.
func WithBaseDir ¶
WithBaseDir sets the base directory for uploads. The upload directory becomes {baseDir}/uploads. Defaults to "data" (i.e. data/uploads).
func WithURLPrefix ¶
WithURLPrefix sets the URL prefix for serving uploaded files.
type Store ¶ added in v0.7.0
type Store interface {
// Store persists a file and returns its storage key.
Store(ctx context.Context, file io.Reader, opts StoreOptions) (key string, err error)
// Delete removes a file by its storage key.
Delete(ctx context.Context, key string) error
// Open returns a reader for the file at the given key.
Open(ctx context.Context, key string) (io.ReadCloser, error)
// URL returns the public URL for the given storage key.
URL(key string) string
}
Store defines the interface for file storage backends.
func GetStorage ¶ added in v0.6.0
GetStorage is a deprecated alias for Storage.
type StoreOptions ¶
type StoreOptions struct {
Prefix string // subdirectory, e.g. "avatars"
Filename string // original filename (for extension extraction)
AllowedTypes []string // e.g. ["image/jpeg", "image/png"]; empty = all
MaxSize int64 // per-file limit in bytes (0 = no limit)
}
StoreOptions configures a single file store operation.
Source Files