storagex

package
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package storagex HTTP companions (storage-walk #14): the serving handler for the /uploads/ URL convention LocalBackend.URL() produces, and the multipart parsing helper for upload endpoints. Both are opt-in building blocks — authentication and upload policy (who may store what, size/type ceilings per route) remain product decisions and live in the product's own handler wrapping these.

Index

Constants

This section is empty.

Variables

View Source
var ErrUploadTooLarge = errors.New("storagex: upload exceeds the configured limit")

ErrUploadTooLarge wraps the MaxBytesReader breach so products can map it to 413 without string matching.

Functions

func ServeUploads added in v0.7.1

func ServeUploads(store Store) http.Handler

ServeUploads serves previously stored objects under the URL space the backend's URL() produces ("/uploads/{key}" for Local). GET/HEAD only; Content-Type from the stored metadata; immutable caching (objects are content-addressed by key convention — products that overwrite keys in place should lower the max-age); Content-Disposition inherits the safe-default (inline for non-scriptable types, attachment otherwise) the store already decided at Put time. Range requests are not implemented — media streaming products should front this with their own handler.

func ValidKey

func ValidKey(key string) bool

Types

type LocalBackend

type LocalBackend struct {
	Root string
	// contains filtered or unexported fields
}

func NewLocal

func NewLocal(root string) (*LocalBackend, error)

func (*LocalBackend) Delete

func (l *LocalBackend) Delete(_ context.Context, key string) error

func (*LocalBackend) DeleteMulti

func (l *LocalBackend) DeleteMulti(ctx context.Context, keys ...string) error

func (*LocalBackend) List added in v0.7.1

func (l *LocalBackend) List(ctx context.Context, prefix string) ([]Object, error)

List walks the on-disk tree under the escaped prefix and materializes Objects from the sidecar .meta.json files (storage-walk #10). Objects whose sidecar is missing or unreadable are skipped rather than failing the walk — a half-written or externally tampered file must not break quota accounting for everything else.

func (*LocalBackend) LoadMeta

func (l *LocalBackend) LoadMeta(key string) (meta, error)

func (*LocalBackend) Open

func (*LocalBackend) Presign

func (l *LocalBackend) Presign(_ context.Context, key string, _ time.Duration) (string, error)

func (*LocalBackend) Put

func (l *LocalBackend) Put(_ context.Context, key, contentType string, r io.Reader) (Object, error)

func (*LocalBackend) URL

func (l *LocalBackend) URL(key string) string

type Object

type Object struct {
	Key         string `json:"key"`
	ContentType string `json:"content_type"`
	Size        int64  `json:"size"`
	SHA256      string `json:"sha256"`
}

type S3Backend

type S3Backend struct {
	Client     *s3.Client
	Uploader   *manager.Uploader
	Presigner  *s3.PresignClient
	Bucket     string
	Prefix     string
	PublicBase string
}

func NewS3

func NewS3(ctx context.Context, o S3Options) (*S3Backend, error)

func (*S3Backend) Delete

func (s *S3Backend) Delete(ctx context.Context, key string) error

func (*S3Backend) DeleteMulti

func (s *S3Backend) DeleteMulti(ctx context.Context, keys ...string) error

func (*S3Backend) List added in v0.7.1

func (s *S3Backend) List(ctx context.Context, prefix string) ([]Object, error)

List pages through ListObjectsV2 under the configured prefix (storage-walk #10); returned keys are stripped of the backend prefix so callers see the same key space they Put with.

func (*S3Backend) Open

func (s *S3Backend) Open(ctx context.Context, key string) (io.ReadCloser, Object, error)

func (*S3Backend) Presign

func (s *S3Backend) Presign(ctx context.Context, key string, ttl time.Duration) (string, error)

func (*S3Backend) Put

func (s *S3Backend) Put(ctx context.Context, key, contentType string, r io.Reader) (Object, error)

func (*S3Backend) URL

func (s *S3Backend) URL(key string) string

type S3Options

type S3Options struct {
	Endpoint   string
	Region     string
	AccessKey  string
	SecretKey  string
	Bucket     string
	Prefix     string
	PublicBase string
	PathStyle  bool
}

type Store

type Store interface {
	Put(ctx context.Context, key, contentType string, r io.Reader) (Object, error)

	Open(ctx context.Context, key string) (io.ReadCloser, Object, error)

	// List enumerates objects whose key starts with prefix, sorted by key
	// (storage-walk #10): the enumeration surface for per-workspace quota
	// accounting and orphan cleanup — without it, products had to track every
	// key in their own tables just to know what exists. Empty prefix lists
	// everything. Object metadata only (no bodies opened).
	List(ctx context.Context, prefix string) ([]Object, error)

	Delete(ctx context.Context, key string) error

	DeleteMulti(ctx context.Context, keys ...string) error

	URL(key string) string

	Presign(ctx context.Context, key string, ttl time.Duration) (string, error)
}

type Uploaded added in v0.7.1

type Uploaded struct {
	Filename    string
	ContentType string
	Data        []byte
}

Uploaded is one parsed multipart file part.

func ParseUpload added in v0.7.1

func ParseUpload(r *http.Request, maxBytes int64) (Uploaded, error)

ParseUpload reads exactly one file part from a multipart request body ("file" by field name; use ParseUploadField for another name). The request body MUST already be wrapped by http.MaxBytesReader at or above maxBytes — this helper enforces its own cap on the buffered part and reports ErrUploadTooLarge on breach. Use it for the common "one file per request" product endpoint; multi-file endpoints should iterate r.MultipartForm() themselves with the same size discipline.

func ParseUploadField added in v0.7.1

func ParseUploadField(r *http.Request, maxBytes int64, field string) (Uploaded, error)

ParseUploadField is ParseUpload with an explicit form field name.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL