Go-Core-xfs

Go-Core-xfs

Aeon Digital rianna@aeondigital.com.br

Cross-platform filesystem utilities with a testable package bridge boundary.

This package provides a robust set of helper functions to resolve paths, inspect filesystem entities, safely manipulate files and directories, and dynamically locate standard user storage structures. It is designed for absolute, cross-platform stability and isolates external operating system operations via an internal package bridge contract to guarantee painless, concurrent unit testing.

1. INSTALLATION

Install the package from its current repository location:

go get github.com/AeonDigital/Go-Core-xfs@latest

2. PURPOSE

xfs centralizes common filesystem operations behind a consistent, predictable API. It simplifies and standardizes tasks such as:

• Path Normalization — resolving absolute layouts, handling cross-platform separators, and expanding ~ home directory shortcuts.
• Structural Inspections — checking the existence and integrity of files, directories, and tracking low-level properties like device permission bits.
• Safe Manipulations — reading, writing, copying, and removing targets while using defensive guards to prevent accidental directory loss.
• Dynamic Volume Auditing — calculating real-time drive space availability across different platform architectures while respecting storage quotas.

The package is built to avoid direct global system calls in business code, favoring a single bridge contract (IPkgBridgeXFS) that can be completely intercepted and mocked during tests.

3. MULTI-PLATFORM LAYOUT MAPPING

The package dynamically translates standard user paths according to the runtime operating system ecosystem conventions, abstracting complex specifications into clean API endpoints:

4. BASIC USAGE

4.1. Path Resolution & Verification

Paths are automatically cleaned, cross-platform separators are normalized, and the tilde prefix (~) is safely expanded to the current user's home directory.

// Fully resolves and cleans absolute paths natively
path, err := xfs.RetrieveFullPath("~/workspace/../projects")
if err != nil {
    return err
}

// Inspect structural entities safely
if xfs.Exists(path) && xfs.IsDir(path) {
    isEmpty, _ := xfs.IsEmptyDir(path)
}

4.2. Directory & File Manipulations

Creation and modification methods accept standard optional variadic os.FileMode arguments, applying sensible environment defaults when omitted.

// Creates a complete nested path tree using 0o755 permissions by default
err := xfs.CreateDirPath("~/tmp/storage/configs")
if err != nil {
    return err
}

// Explicitly overrides default permissions with custom file modes
file, err := xfs.CreateFile("~/tmp/storage/configs/app.json", 0o600)
if err != nil {
    return err
}
defer file.Close()

4.3. Permission Bounds & Safetiness

xfs verifies read and write capabilities accurately across different operating systems without altering target descriptors. Directory writability is safely evaluated by attempting non-destructive transient actions under the hood.

path := "~/tmp/storage"

if xfs.IsReadable(path) && xfs.IsWritable(path) {
    // Current application process has sufficient execution permissions
    perm, err := xfs.GetPermission(path)
}

4.4. Low-Level Volume Integrity

If a target path does not exist yet on the filesystem, HasSpaceAvailable automatically walks upward through the directory hierarchy to locate the closest valid storage boundary, executing native syscall audits against user quotas.

// Safely matches volume space bounds before triggering large write payloads
requiredBytes := uint64(2 * 1024 * 1024 * 1024) // 2 GB

hasSpace, err := xfs.HasSpaceAvailable("~/downloads/incoming/payload.bin", requiredBytes)
if err != nil {
    return err
}

if !hasSpace {
    return errors.New("aborted: insufficient disk space on target volume")
}

6. TESTING AND MOCKS INTEGRATION

The package is engineered explicitly around the IPkgBridgeXFS interface contract boundary. In production execution, it routes calls natively without intermediate overhead to the Go standard library or platform-specific syscalls (unix.Statfs, unix.Statvfs, or Win32 GetDiskFreeSpaceEx).

During your unit testing phases, you can completely substitute external system dependencies with predictable mock structures generated by tools like xmocks:

# Generate automated mocks for your independent test suite
xmocks

// Example of overriding the default bridge behavior within tests
func TestYourBusinessLogic(t *testing.T) {
    // xmocks generated structures can be injected directly into the internal hook
    // to bypass real disk interactions completely
}

7. ADDITIONAL INFORMATION

This project uses the Semantic Versioning system proposed by Tom Preston-Werner.

8. LICENSE

This project is offered under the MIT license.