storage

Documentation

Overview

Package storage provides a file storage abstraction with a path-confined local driver and an S3-compatible driver.

Index

• Variables
• func SaveUpload(c *gin.Context, disk Disk, field, destPath string) (int64, error)
• type Disk
  • func New(options Options) (Disk, error)
• type Local
  • func (l *Local) Delete(_ context.Context, name string) error
  • func (l *Local) Exists(_ context.Context, name string) (bool, error)
  • func (l *Local) Get(_ context.Context, name string) (io.ReadCloser, error)
  • func (l *Local) Put(_ context.Context, name string, r io.Reader, _ ...PutOption) error
  • func (l *Local) Size(_ context.Context, name string) (int64, error)
  • func (l *Local) URL(_ context.Context, name string) (string, error)
• type LocalOptions
• type Options
• type PutOption
  • func WithContentType(contentType string) PutOption
  • func WithSize(size int64) PutOption
• type PutOptions
• type S3
  • func (s *S3) Delete(ctx context.Context, name string) error
  • func (s *S3) Exists(ctx context.Context, name string) (bool, error)
  • func (s *S3) Get(ctx context.Context, name string) (io.ReadCloser, error)
  • func (s *S3) Put(ctx context.Context, name string, r io.Reader, opts ...PutOption) error
  • func (s *S3) Size(ctx context.Context, name string) (int64, error)
  • func (s *S3) URL(ctx context.Context, name string) (string, error)
• type S3Options

Variables

var (
	// ErrNotFound is returned by every driver for missing files.
	ErrNotFound = errors.New("storage: file not found")
	// ErrURLUnavailable is returned by URL when no public base URL is
	// configured for the disk.
	ErrURLUnavailable = errors.New("storage: no public URL configured")
)

Functions

func SaveUpload

func SaveUpload(c *gin.Context, disk Disk, field, destPath string) (int64, error)

SaveUpload stores the multipart file from the named form field onto the disk at destPath, returning the stored size in bytes. The upload's declared content type is forwarded to the disk.

Types

type Disk

type Disk interface {
	// Put define an operation required by this interface.
	Put(ctx context.Context, path string, r io.Reader, opts ...PutOption) error
	// Get define an operation required by this interface.
	Get(ctx context.Context, path string) (io.ReadCloser, error)
	// Exists define an operation required by this interface.
	Exists(ctx context.Context, path string) (bool, error)
	// Size define an operation required by this interface.
	Size(ctx context.Context, path string) (int64, error)
	// Delete removes the file and is a no-op for missing paths.
	Delete(ctx context.Context, path string) error
	// URL returns a public or presigned URL for the file.
	URL(ctx context.Context, path string) (string, error)
}

Disk stores and retrieves files under slash-separated paths.

func New

func New(options Options) (Disk, error)

New builds a Disk for the configured driver.

type Local

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

Local stores files under a confined root directory.

func (*Local) Delete

func (l *Local) Delete(_ context.Context, name string) error

Delete performs this package operation.

func (*Local) Exists

func (l *Local) Exists(_ context.Context, name string) (bool, error)

Exists performs this package operation.

func (*Local) Get

func (l *Local) Get(_ context.Context, name string) (io.ReadCloser, error)

Get performs this package operation.

func (*Local) Put

func (l *Local) Put(_ context.Context, name string, r io.Reader, _ ...PutOption) error

Put writes atomically: the content lands in a temp file that is renamed into place, so readers never observe partial writes.

func (*Local) Size

func (l *Local) Size(_ context.Context, name string) (int64, error)

Size performs this package operation.

func (*Local) URL

func (l *Local) URL(_ context.Context, name string) (string, error)

URL performs this package operation.

type LocalOptions

type LocalOptions struct {
	// Root is the directory that confines every file, defaulting to
	// ./storage. It is created when missing.
	Root string
	// BaseURL makes URL() return BaseURL + "/" + path when set.
	BaseURL string
}

LocalOptions defines an implementation type used by this package.

type Options

type Options struct {
	// Driver selects the disk: "local" (default) or "s3".
	Driver string
	// Local store data used by this type.
	Local LocalOptions
	// S3 store data used by this type.
	S3 S3Options
}

Options defines an implementation type used by this package.

type PutOption

type PutOption func(*PutOptions)

PutOption defines an implementation type used by this package.

func WithContentType

func WithContentType(contentType string) PutOption

WithContentType performs this package operation.

func WithSize

func WithSize(size int64) PutOption

WithSize performs this package operation.

type PutOptions

type PutOptions struct {
	// ContentType store data used by this type.
	ContentType string
	// Size is the number of bytes when known, or -1 to stream.
	Size int64
}

PutOptions defines an implementation type used by this package.

type S3

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

S3 stores files in any S3-compatible object store (AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces).

func (*S3) Delete

func (s *S3) Delete(ctx context.Context, name string) error

Delete performs this package operation.

func (*S3) Exists

func (s *S3) Exists(ctx context.Context, name string) (bool, error)

Exists performs this package operation.

func (*S3) Get

func (s *S3) Get(ctx context.Context, name string) (io.ReadCloser, error)

Get performs this package operation.

func (*S3) Put

func (s *S3) Put(ctx context.Context, name string, r io.Reader, opts ...PutOption) error

Put performs this package operation.

func (*S3) Size

func (s *S3) Size(ctx context.Context, name string) (int64, error)

Size performs this package operation.

func (*S3) URL

func (s *S3) URL(ctx context.Context, name string) (string, error)

URL performs this package operation.

type S3Options

type S3Options struct {
	Endpoint string // host[:port] without scheme, e.g. s3.amazonaws.com
	// Region store data used by this type.
	Region string
	// Bucket store data used by this type.
	Bucket string
	// AccessKey store data used by this type.
	AccessKey string
	// SecretKey store data used by this type.
	SecretKey string
	// UseSSL defaults to true.
	UseSSL *bool
	// UsePathStyle addresses buckets as endpoint/bucket (MinIO style).
	UsePathStyle bool
	// PresignTTL bounds presigned URLs, defaulting to 15 minutes.
	PresignTTL time.Duration
	// PublicBaseURL makes URL() return a plain public URL instead of a
	// presigned one.
	PublicBaseURL string
}

S3Options defines an implementation type used by this package.