storage

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package storage is part of the GoFastr framework. See https://github.com/DonaldMurillo/gofastr for documentation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Register 

func Register(t StorageType, factory BackendFactory)

Register adds a backend factory for the given storage type. Panics on duplicate registration (a programming error caught at boot). A nil factory is rejected so a later New call doesn't nil-pointer.

Types

type BackendFactory 

type BackendFactory func(config map[string]interface{}) (Storage, error)

BackendFactory creates a Storage instance from a type and generic config.

type Battery added in v0.3.2 

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

Battery is the framework.Battery adapter for the storage battery. It participates in the App's dependency-resolved lifecycle so host apps can declare that other batteries depend on the file-storage backend being available.

Construct via NewBattery and register: 

st := storage.NewLocalStorage("/var/uploads")
app.Batteries.Register(storage.NewBattery(st))

The battery's Init is a no-op — the backend is fully constructed before registration. None of the built-in backends (LocalStorage, MemoryStorage, S3Storage) run background goroutines, so no OnStop hook is needed. If a future backend does, implement io.Closer on that type.

func NewBattery added in v0.3.2 

func NewBattery(s Storage) *Battery

NewBattery wraps s in a framework lifecycle adapter.

func (*Battery) Init added in v0.3.2 

func (b *Battery) Init(_ *framework.App) error

Init implements framework.Battery. The backend is fully constructed by the caller before registration so Init is a no-op.

func (*Battery) Name added in v0.3.2 

func (b *Battery) Name() string

Name implements framework.Battery.

func (*Battery) Storage added in v0.3.2 

func (b *Battery) Storage() Storage

Storage returns the underlying Storage so callers can inject it where needed without reaching through the battery wrapper.

type DefaultKeyValidator 

type DefaultKeyValidator struct{}

DefaultKeyValidator implements basic key validation.

func (DefaultKeyValidator) ValidateKey 

func (DefaultKeyValidator) ValidateKey(key string) error

ValidateKey checks that a key does not contain path traversal sequences.

type FileMeta 

type FileMeta struct {
	Size       int64
	ModifiedAt time.Time
}

FileMeta holds metadata about a stored file.

type KeyValidator 

type KeyValidator interface {
	ValidateKey(key string) error
}

KeyValidator validates storage keys to prevent path traversal and other attacks.

type LocalOption 

type LocalOption func(*LocalStorage)

LocalOption configures a LocalStorage instance.

func WithPermissions 

func WithPermissions(mode os.FileMode) LocalOption

WithPermissions sets the file permission mode for saved files.

func WithTempDir 

func WithTempDir(dir string) LocalOption

WithTempDir sets a custom temporary directory for atomic writes.

type LocalStorage 

type LocalStorage struct {
	BaseDir string
	// contains filtered or unexported fields
}

LocalStorage implements Storage backed by the local filesystem. Writes are atomic: data is first written to a temporary file, then renamed to the final path.

func NewLocalStorage 

func NewLocalStorage(baseDir string, opts ...LocalOption) *LocalStorage

NewLocalStorage creates a LocalStorage rooted at baseDir. The directory is created if it does not exist.

func (*LocalStorage) Delete 

func (ls *LocalStorage) Delete(ctx context.Context, key string) error

Delete removes the file identified by key from the filesystem. It is not an error if the file does not exist.

func (*LocalStorage) Exists 

func (ls *LocalStorage) Exists(ctx context.Context, key string) (bool, error)

Exists reports whether a file exists for the given key.

func (*LocalStorage) Get 

func (ls *LocalStorage) Get(ctx context.Context, key string) (io.ReadCloser, error)

Get opens the file identified by key and returns a ReadCloser for its contents.

func (*LocalStorage) Save 

func (ls *LocalStorage) Save(ctx context.Context, key string, r io.Reader) error

Save writes the contents of r to a file under BaseDir identified by key. The write is atomic: data is first written to a temporary file in the same directory, then renamed to the final path. Intermediate directories are created as needed.

type MemoryStorage 

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

MemoryStorage implements Storage backed by an in-memory map. It is safe for concurrent use via sync.RWMutex.

func NewMemoryStorage 

func NewMemoryStorage() *MemoryStorage

NewMemoryStorage creates a new empty MemoryStorage.

func (*MemoryStorage) Delete 

func (ms *MemoryStorage) Delete(_ context.Context, key string) error

Delete removes the file identified by key. It is not an error if the key does not exist.

func (*MemoryStorage) Exists 

func (ms *MemoryStorage) Exists(_ context.Context, key string) (bool, error)

Exists reports whether a file exists for the given key.

func (*MemoryStorage) Get 

func (ms *MemoryStorage) Get(_ context.Context, key string) (io.ReadCloser, error)

Get returns a ReadCloser for the file identified by key.

func (*MemoryStorage) Save 

func (ms *MemoryStorage) Save(_ context.Context, key string, r io.Reader) error

Save stores the contents of r under the given key. Reads at most maxMemoryFileSize bytes to prevent unbounded memory allocation.

type Presigner 

type Presigner interface {
	PresignGet(ctx context.Context, bucket, key string, expires time.Duration) (*url.URL, error)
	PresignPut(ctx context.Context, bucket, key string, expires time.Duration) (*url.URL, error)
}

Presigner generates presigned URLs for direct browser uploads/downloads.

type ReadCloser 

type ReadCloser struct {
	io.Reader
}

ReadCloser wraps an io.Reader to implement io.ReadCloser with a no-op Close.

func (ReadCloser) Close 

func (ReadCloser) Close() error

Close is a no-op.

type S3Client 

type S3Client interface {
	PutObject(ctx context.Context, bucket, key string, r io.Reader, size int64, contentType string) error
	GetObject(ctx context.Context, bucket, key string) (io.ReadCloser, error)
	DeleteObject(ctx context.Context, bucket, key string) error
	HeadObject(ctx context.Context, bucket, key string) (bool, error)
}

S3Client is a minimal interface for S3-compatible operations. This avoids importing the AWS SDK directly; callers provide their own implementation or use the PresignedURL field for direct browser uploads.

type S3Option 

type S3Option func(*S3Storage)

S3Option configures an S3Storage instance.

func WithPresigner 

func WithPresigner(p Presigner) S3Option

WithPresigner sets the URL presigner for generating presigned URLs.

func WithS3Client 

func WithS3Client(client S3Client) S3Option

WithS3Client sets the S3 client implementation.

func WithS3Endpoint 

func WithS3Endpoint(endpoint string) S3Option

WithS3Endpoint sets a custom S3-compatible endpoint.

type S3Storage 

type S3Storage struct {
	Bucket   string
	Region   string
	Endpoint string
	Client   S3Client
	// contains filtered or unexported fields
}

S3Storage implements Storage backed by an S3-compatible object store. It uses a minimal S3Client interface so no AWS SDK is imported directly.

func NewS3Storage 

func NewS3Storage(bucket, region string, opts ...S3Option) *S3Storage

NewS3Storage creates a new S3Storage for the given bucket and region. Use WithS3Client to inject an actual client before calling Save/Get/etc.

func (*S3Storage) Delete 

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

Delete removes the S3 object identified by key.

func (*S3Storage) Exists 

func (s *S3Storage) Exists(ctx context.Context, key string) (bool, error)

Exists reports whether an S3 object exists for the given key.

func (*S3Storage) Get 

func (s *S3Storage) Get(ctx context.Context, key string) (io.ReadCloser, error)

Get returns a ReadCloser for the S3 object identified by key.

func (*S3Storage) PresignedGetURL 

func (s *S3Storage) PresignedGetURL(ctx context.Context, key string, expires time.Duration) (*url.URL, error)

PresignedGetURL returns a presigned URL for downloading the object.

func (*S3Storage) PresignedPutURL 

func (s *S3Storage) PresignedPutURL(ctx context.Context, key string, expires time.Duration) (*url.URL, error)

PresignedPutURL returns a presigned URL for uploading the object directly.

func (*S3Storage) Save 

func (s *S3Storage) Save(ctx context.Context, key string, r io.Reader) error

Save stores the contents of r as an S3 object with the given key.

type Storage 

type Storage = upload.Storage

Storage is a re-export of the upload.Storage interface for convenience.

func New 

func New(t StorageType, config map[string]interface{}) (Storage, error)

New creates a Storage backend by type name using the registered factory. Returns a typed error if the type is unknown or the registered factory is nil — never panics, so a malformed config can't crash startup.

type StorageType 

type StorageType int

StorageType enumerates available storage backend types. 

const (
	Local StorageType = iota
	S3
	Memory
)

func (StorageType) String 

func (t StorageType) String() string

String returns a human-readable name for the StorageType.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.