Skip to Content
DocumentationPackage LibraryStorage

Storage

The storage package provides a unified file storage interface with support for local filesystem and Amazon S3 (or S3-compatible) backends. It handles file uploads, downloads, deletion, and signed URL generation.

Import

import "github.com/gofastadev/gofasta/pkg/storage"

Key Types

Storage

type Storage interface {
    Put(ctx context.Context, path string, content io.Reader, opts ...PutOption) error
    Get(ctx context.Context, path string) (io.ReadCloser, error)
    Delete(ctx context.Context, path string) error
    Exists(ctx context.Context, path string) (bool, error)
    URL(path string) string
    SignedURL(ctx context.Context, path string, expiry time.Duration) (string, error)
    List(ctx context.Context, prefix string) ([]FileInfo, error)
}

FileInfo

type FileInfo struct {
    Path         string    `json:"path"`
    Size         int64     `json:"size"`
    ContentType  string    `json:"content_type"`
    LastModified time.Time `json:"last_modified"`
}

StorageConfig

The storage configuration uses koanf struct tags and is part of the root AppConfig. Environment variables use the GOFASTA_ prefix (e.g., GOFASTA_STORAGE_DRIVER). S3 storage uses minio-go under the hood.

type StorageConfig struct {
    Driver string             `koanf:"driver"`
    Local  LocalStorageConfig `koanf:"local"`
    S3     S3Config           `koanf:"s3"`
}
 
type LocalStorageConfig struct {
    Path string `koanf:"path"`
}
 
type S3Config struct {
    Endpoint  string `koanf:"endpoint"`
    Bucket    string `koanf:"bucket"`
    AccessKey string `koanf:"access_key"`
    SecretKey string `koanf:"secret_key"`
    Region    string `koanf:"region"`
    UseSSL    bool   `koanf:"use_ssl"`
}

PutOption

type PutOption func(*putOptions)
 
func WithContentType(ct string) PutOption
func WithACL(acl string) PutOption
func WithMetadata(meta map[string]string) PutOption

Key Functions

FunctionSignatureDescription
NewStoragefunc NewStorage(cfg StorageConfig) (Storage, error)Creates a storage instance based on the configured driver
NewLocalStoragefunc NewLocalStorage(cfg StorageConfig) StorageCreates a local filesystem storage
NewS3Storagefunc NewS3Storage(cfg StorageConfig) (Storage, error)Creates an S3-compatible storage

Usage

Uploading Files

store, err := storage.NewStorage(storage.StorageConfig{
    Driver: "s3",
    S3: storage.S3Config{
        Bucket:    "my-bucket",
        Region:    "us-east-1",
        AccessKey: "AKIA...",
        SecretKey: "secret",
        UseSSL:    true,
    },
})
if err != nil {
    log.Fatalf("failed to create storage: %v", err)
}
 
file, header, _ := r.FormFile("avatar")
defer file.Close()
 
path := fmt.Sprintf("avatars/%s/%s", userID, header.Filename)
err = store.Put(ctx, path, file,
    storage.WithContentType(header.Header.Get("Content-Type")),
    storage.WithACL("public-read"),
)

Downloading Files

reader, err := store.Get(ctx, "avatars/user-123/photo.jpg")
if err != nil {
    return errors.NotFound("File", path)
}
defer reader.Close()
 
io.Copy(w, reader)

Generating Signed URLs

url, err := store.SignedURL(ctx, "documents/report.pdf", 15*time.Minute)
if err != nil {
    return err
}
// url is a time-limited pre-signed URL for the file

Listing Files

files, err := store.List(ctx, "avatars/user-123/")
if err != nil {
    return err
}
 
for _, f := range files {
    fmt.Printf("Path: %s, Size: %d, Type: %s\n", f.Path, f.Size, f.ContentType)
}

Deleting Files

err := store.Delete(ctx, "avatars/user-123/old-photo.jpg")

Local Filesystem Storage

store := storage.NewLocalStorage(storage.StorageConfig{
    Driver: "local",
    Local: storage.LocalStorageConfig{
        Path: "./uploads",
    },
})
 
url := store.URL("avatars/photo.jpg")
// -> "./uploads/avatars/photo.jpg"

Configuration via config.yaml

storage:
  driver: s3          # "local" or "s3"
  local:
    path: "./uploads"
  s3:
    endpoint: "s3.amazonaws.com"
    bucket: my-bucket
    region: us-east-1
    access_key: "AKIA..."
    secret_key: "secret"
    use_ssl: true

Environment variable overrides use the GOFASTA_ prefix:

export GOFASTA_STORAGE_DRIVER=s3
export GOFASTA_STORAGE_S3_BUCKET=my-bucket
export GOFASTA_STORAGE_S3_ACCESS_KEY=AKIA...
Last updated on
CacheMailer