filesystem

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Oct 31, 2025 License: MIT Imports: 22 Imported by: 0

README

Filesystem

Tests Go Report Card PkgGoDev

filesystem provides a lightweight, driver-based abstraction over file storage backends. It exposes a single StorageInterface with helpers for common operations—copying, moving, deleting, listing, and reading files—while delegating the underlying work to the disk driver you configure.

Features

  • Unified interface for reading, writing, listing, and deleting files and directories @StorageInterface.go#5-18
  • Disk configuration struct that captures S3, SQL, and static driver options @Disk.go#5-30
  • S3 driver backed by the AWS SDK for Go v2, with automatic endpoint resolution and public-read uploads @S3Storage.go#21-315
  • SQL driver that persists files inside a relational database using github.com/dracory/sqlfilestore, including optional automigrations @SqlStorage.go#17-406
  • Static driver for CDN-style, read-only access that constructs public URLs without mutating state @StaticStorage.go#9-68

Installation

go get github.com/dracory/filesystem

Getting Started

All drivers begin with a Disk definition that captures the settings for the backend. NewStorage validates the disk and returns an implementation of StorageInterface. @Storage.go#11-87

package main

import (
    "log"

    "github.com/dracory/filesystem"
)

func main() {
    storage, err := filesystem.NewStorage(filesystem.Disk{
        DiskName:             "media",
        Driver:               filesystem.DRIVER_S3,
        Url:                  "https://example.cdn.net",
        Region:               "us-east-1",
        Key:                  "ACCESS_KEY",
        Secret:               "SECRET_KEY",
        Bucket:               "my-bucket",
        UsePathStyleEndpoint: true,
    })
    if err != nil {
        log.Fatal(err)
    }

    if err := storage.Put("uploads/hello.txt", []byte("hello world")); err != nil {
        log.Fatal(err)
    }
}
S3 driver

The S3 driver targets any S3-compatible provider. Required disk settings are Url, Region, Key, Secret, and Bucket. Optional UsePathStyleEndpoint toggles path-style addressing for services like MinIO. @Disk.go#18-28

The driver supports:

  1. Object CRUD (Copy, Move, DeleteFile, ReadFile, Put) @S3Storage.go#52-315
  2. Directory helpers (Directories, Files, DeleteDirectory, MakeDirectory) @S3Storage.go#94-266
  3. Existence checks and signed metadata through Exists and Missing @S3Storage.go#207-257
SQL driver

The SQL driver stores files and directories inside a database table managed by github.com/dracory/sqlfilestore. Use NewSqlStorage when you need a structured datastore or offline storage.

db, _ := sql.Open("sqlite", ":memory:")
storage, err := filesystem.NewSqlStorage(filesystem.SqlStorageOptions{
    DB:                 db,
    FilestoreTable:     "filestore",
    URL:                "https://media.example.com",
    AutomigrateEnabled: true,
})
  • Put, ReadFile, Move, DeleteFile, and DeleteDirectory map to SQL operations and maintain directory hierarchies. @SqlStorage.go#99-368
  • Helpers like Exists, Files, and Directories normalise paths and return database-backed results. @SqlStorage.go#235-369
  • Optional URL prefixing allows generating absolute media URLs via Url(). @SqlStorage.go#503-516
Static driver

The static driver exposes CDN-like, read-only access. It returns deterministic URLs and rejects mutating operations. Use it to map a logical disk to pre-existing assets.

storage := &filesystem.StaticStorage{disk: filesystem.Disk{
    DiskName: "cdn",
    Driver:   filesystem.DRIVER_STATIC,
    Url:      "https://cdn.example.com",
}}

url, _ := storage.Url("images/logo.png")
// url == "https://cdn.example.com/images/logo.png"

Testing

go test ./...

The SQL storage driver ships with basic tests covering file persistence. @SqlStorage_test.go#23-80

License

This project is released under the MIT License. See LICENSE for details.

Documentation

Index

Constants

View Source 
const CDN = "cdn"
View Source 
const DEFAULT = "default"
View Source 
const DRIVER_S3 = "s3"
View Source 
const DRIVER_SQL = "sql"
View Source 
const DRIVER_STATIC = "static"
View Source 
const PATH_SEPARATOR = "/"
View Source 
const ROOT_PATH = PATH_SEPARATOR

Variables

This section is empty.

Functions

This section is empty.

Types

type Disk 

type Disk struct {
	DiskName   string
	Driver     string
	Url        string
	Visibility string // public, private (not implemented)

	// SQL options
	DB        *sql.DB // for sql
	TableName string  // for sql

	// Local options
	Root string // for local filesystem (not implemented)

	// S3 options
	Key      string // for s3
	Secret   string // for s3
	Region   string // for s3
	Bucket   string // for s3
	Endpoint string // for s3

	// Allows you to enable the client to use path-style addressing, i.e.,
	// https://s3.amazonaws.com/BUCKET/KEY . By default, the S3 client will use virtual
	// hosted bucket addressing when possible( https://BUCKET.s3.amazonaws.com/KEY ).
	UsePathStyleEndpoint bool // for s3

	Throw bool // for s3 (not implemented)
}

type S3Storage 

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

S3Storage implements the StorageInterface for an S3 compliant file storage, i.e. AWS S3, DigitalOcean Spaces, Minio, etc

func (*S3Storage) Copy 

func (s *S3Storage) Copy(originFile, targetFile string) error

func (*S3Storage) DeleteDirectory 

func (s *S3Storage) DeleteDirectory(directory string) error

DeleteDirectory deletes a directory

func (*S3Storage) DeleteFile 

func (s *S3Storage) DeleteFile(filePaths []string) error

func (*S3Storage) Directories 

func (s *S3Storage) Directories(dir string) ([]string, error)

Directories lists the sub-directories in the specified directory

func (*S3Storage) Exists 

func (s *S3Storage) Exists(file string) (bool, error)

func (*S3Storage) Files 

func (s *S3Storage) Files(dir string) ([]string, error)

Files lists the files in the specified directory

func (*S3Storage) LastModified 

func (s *S3Storage) LastModified(file string) (time.Time, error)

func (*S3Storage) MakeDirectory 

func (s *S3Storage) MakeDirectory(directory string) error

func (*S3Storage) Missing 

func (s *S3Storage) Missing(file string) (bool, error)

func (*S3Storage) Move 

func (s *S3Storage) Move(oldFile, newFile string) error

func (*S3Storage) Put 

func (s *S3Storage) Put(filePath string, content []byte) error

func (*S3Storage) PutFile 

func (s *S3Storage) PutFile(filePath string, source filesystem.File) (string, error)

func (*S3Storage) PutFileAs 

func (s *S3Storage) PutFileAs(filePath string, source filesystem.File, name string) (string, error)

func (*S3Storage) ReadFile 

func (s *S3Storage) ReadFile(file string) ([]byte, error)

func (*S3Storage) Size 

func (s *S3Storage) Size(file string) (int64, error)

func (*S3Storage) Url 

func (s *S3Storage) Url(file string) (string, error)

type SQLStorage 

type SQLStorage struct {
	DB                 *sql.DB
	FilestoreTable     string
	URL                string
	AutomigrateEnabled bool
	DebugEnabled       bool
	// contains filtered or unexported fields
}

func NewSqlStorage 

func NewSqlStorage(options SqlStorageOptions) (*SQLStorage, error)

func (*SQLStorage) Copy 

func (s *SQLStorage) Copy(originFilePath, targetFilePath string) error

func (*SQLStorage) DeleteDirectory 

func (s *SQLStorage) DeleteDirectory(directoryPath string) error

DeleteDirectory deletes a directory

func (*SQLStorage) DeleteFile 

func (s *SQLStorage) DeleteFile(filePaths []string) error

func (*SQLStorage) Directories 

func (s *SQLStorage) Directories(directoryPath string) ([]string, error)

Directories lists the sub-directories in the specified directory

func (*SQLStorage) Exists 

func (s *SQLStorage) Exists(path string) (bool, error)

func (*SQLStorage) Files 

func (s *SQLStorage) Files(directoryPath string) ([]string, error)

Files lists the files in the specified directory

func (*SQLStorage) LastModified 

func (s *SQLStorage) LastModified(filePath string) (time.Time, error)

func (*SQLStorage) MakeDirectory 

func (s *SQLStorage) MakeDirectory(directoryPath string) error

func (*SQLStorage) Move 

func (s *SQLStorage) Move(originFilePath, targetFilePath string) error

func (*SQLStorage) Put 

func (s *SQLStorage) Put(filePath string, content []byte) error

func (*SQLStorage) PutFile 

func (s *SQLStorage) PutFile(filePath string, source string) (string, error)

func (*SQLStorage) ReadFile 

func (s *SQLStorage) ReadFile(filePath string) ([]byte, error)

func (*SQLStorage) Size 

func (s *SQLStorage) Size(filePath string) (int64, error)

func (*SQLStorage) Url 

func (s *SQLStorage) Url(filePath string) (string, error)

type SqlStorageOptions 

type SqlStorageOptions struct {
	DB                 *sql.DB
	FilestoreTable     string
	URL                string
	AutomigrateEnabled bool
	DebugEnabled       bool
}

type StaticStorage 

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

StaticStorage implements StorageInterface it represents a static (read only) storage, i.e. CDN the only supported method is Url(filepath)

func (*StaticStorage) Copy 

func (s *StaticStorage) Copy(originFile, targetFile string) error

func (*StaticStorage) DeleteDirectory 

func (s *StaticStorage) DeleteDirectory(dirPath string) error

func (*StaticStorage) DeleteFile 

func (s *StaticStorage) DeleteFile(filePaths []string) error

func (*StaticStorage) Directories 

func (s *StaticStorage) Directories(dirPath string) ([]string, error)

func (*StaticStorage) Exists 

func (s *StaticStorage) Exists(filePath string) (bool, error)

func (*StaticStorage) Files 

func (s *StaticStorage) Files(dirPath string) ([]string, error)

func (*StaticStorage) LastModified 

func (s *StaticStorage) LastModified(filePath string) (time.Time, error)

func (*StaticStorage) MakeDirectory 

func (s *StaticStorage) MakeDirectory(dirPath string) error

func (*StaticStorage) Move 

func (s *StaticStorage) Move(originFile, targetFile string) error

func (*StaticStorage) Put 

func (s *StaticStorage) Put(filePath string, content []byte) error

func (*StaticStorage) ReadFile 

func (s *StaticStorage) ReadFile(filePath string) ([]byte, error)

func (*StaticStorage) Size 

func (s *StaticStorage) Size(filePath string) (int64, error)

func (*StaticStorage) Url 

func (s *StaticStorage) Url(filePath string) (string, error)

type StorageInterface 

type StorageInterface interface {
	Copy(originFile, targetFile string) error
	DeleteDirectory(dirPath string) error
	DeleteFile(filePaths []string) error
	Directories(dir string) ([]string, error)
	Exists(filePath string) (bool, error)
	Files(dir string) ([]string, error)
	MakeDirectory(dir string) error
	Move(originFile, targetFile string) error
	Put(filePath string, content []byte) error
	ReadFile(filePath string) ([]byte, error)
	Size(filePath string) (int64, error)
	LastModified(file string) (time.Time, error)
	Url(file string) (string, error)
}

func NewStorage 

func NewStorage(disk Disk) (StorageInterface, error)

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.