storage

Documentation

Overview

Purpose: This file implements the LocalStorage driver for the Vault storage subsystem of GoStack. It provides a standard file-system storage backend complying with the Storage interface.

Philosophy: Storage engines must be unified and secure. Writing raw paths directly in application logic causes host platform locks. Additionally, un-sanitized user file path inputs expose applications to directory traversal exploits. This driver prevents that by resolving all operations strictly within a configured root directory.

Architecture: A standalone framework package (`github.com/Charledeon77/gostack/framework/storage`). Implements the `contract.Storage` interface.

Choice: We chose a local OS file-system backend using standard `os` and `filepath` primitives, ensuring zero-dependency footprint. The path resolution uses strict prefix checking against the root directory to guarantee sandbox safety.

Implementation: - LocalStorage: implements storage operations.

• NewLocalStorage(rootDir): initializes and establishes root directory.
• Put(): writes file content, creating missing subdirectories automatically.
• Get(): reads file content.
• Delete(): removes file.
• Exists(): verifies file presence.
• resolvePath(): sanitizes and validates bounds constraints.

Index

• type LocalStorage
  • func NewLocalStorage(rootDir string) (*LocalStorage, error)
  • func (s *LocalStorage) Delete(path string) error
  • func (s *LocalStorage) Exists(path string) bool
  • func (s *LocalStorage) Get(path string) ([]byte, error)
  • func (s *LocalStorage) Put(path string, contents []byte) error
• type S3Config
• type S3Driver
  • func NewS3Driver(cfg S3Config) (*S3Driver, error)
  • func (s *S3Driver) Delete(path string) error
  • func (s *S3Driver) Exists(path string) bool
  • func (s *S3Driver) Get(path string) ([]byte, error)
  • func (s *S3Driver) Put(path string, contents []byte) error

Types

type LocalStorage

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

LocalStorage handles file-system operations securely confined to a root path.

func NewLocalStorage

func NewLocalStorage(rootDir string) (*LocalStorage, error)

NewLocalStorage instantiates a LocalStorage driver bound to the specified root directory.

func (*LocalStorage) Delete

func (s *LocalStorage) Delete(path string) error

Delete removes the file at the relative target path.

func (*LocalStorage) Exists

func (s *LocalStorage) Exists(path string) bool

Exists asserts whether the relative target path matches an existing file on disk.

func (*LocalStorage) Get

func (s *LocalStorage) Get(path string) ([]byte, error)

Get reads the file contents at the relative target path.

func (*LocalStorage) Put

func (s *LocalStorage) Put(path string, contents []byte) error

Put writes contents to the relative target path, creating parent folders if missing.

type S3Config

type S3Config struct {
	Region          string
	Bucket          string
	Prefix          string // Optional path prefix for all keys
	AccessKeyID     string
	SecretAccessKey string
	Endpoint        string // Optional: set for MinIO / Cloudflare R2
}

S3Config holds the configuration parameters for an S3 connection.

type S3Driver

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

S3Driver implements contract.Storage backed by AWS S3 (or any S3-compatible endpoint).

func NewS3Driver

func NewS3Driver(cfg S3Config) (*S3Driver, error)

NewS3Driver creates a new S3Driver from the given configuration.

func (*S3Driver) Delete

func (s *S3Driver) Delete(path string) error

Delete removes the file at the given path from S3.

func (*S3Driver) Exists

func (s *S3Driver) Exists(path string) bool

Exists returns true if the given S3 key exists, using a cheap HeadObject call.

func (*S3Driver) Get

func (s *S3Driver) Get(path string) ([]byte, error)

Get downloads the file at the given path from S3 and returns its bytes.

func (*S3Driver) Put

func (s *S3Driver) Put(path string, contents []byte) error

Put uploads data bytes to S3 under the given path key.