golib/file/perm

Perm Package

Type-safe, portable file permission handling with support for multiple formats, serialization protocols, and configuration frameworks.

---

Table of Contents

• Overview
• Architecture
• Performance
• Use Cases
• Quick Start
• API Reference
• Best Practices
• Contributing
• Improvements & Security
• Resources
• AI Transparency
• License

---

Overview

The perm package provides a robust, type-safe wrapper around os.FileMode for handling file permissions across different platforms and configuration formats. It simplifies permission parsing, validation, conversion, and serialization.

Design Philosophy

1. Format Flexibility: Support octal strings ("0644"), symbolic notation ("rwxr-xr-x"), and numeric values
2. Type Safety: Strong typing prevents accidental misuse of permission values
3. Serialization Support: Built-in marshaling for JSON, YAML, TOML, CBOR, and plain text
4. Configuration Integration: Seamless Viper integration via custom decoder hooks
5. Cross-Platform: Consistent behavior across Linux, macOS, and Windows

Why Use This Package?

• Configuration Files: Parse permissions from YAML, JSON, TOML config files
• Type Safety: Catch permission errors at compile time instead of runtime
• Format Agnostic: Accept permissions in multiple formats (octal, symbolic)
• Validation: Automatic validation of permission values
• Serialization: Automatic conversion between formats
• Viper Integration: Direct support for Viper configuration library

Key Features

• Multiple Input Formats: Octal ("0644"), symbolic ("rwxr-xr-x"), integers (420)
• Quote Handling: Automatic stripping of single/double quotes
• Marshaling Support: JSON, YAML, TOML, CBOR, Text encoding/decoding
• Type Conversions: Convert to/from int, uint, FileMode, string
• Special Permissions: Support for setuid, setgid, sticky bit
• File Type Support: Parse symbolic notation with file type indicators (d, l, c, b, p, s)
• 91.9% Test Coverage: Comprehensive test suite with race detection
• Zero External Dependencies: Only standard library + golib packages

---

Architecture

Package Structure

file/perm/
├── interface.go         # Public API with Parse* functions and Perm type
├── format.go           # Type conversion methods (String, Int*, Uint*, FileMode)
├── parse.go            # Parsing logic for octal and symbolic formats
├── encode.go           # Marshaling/unmarshaling for JSON, YAML, TOML, CBOR
├── model.go            # Viper integration via decoder hooks
├── doc.go              # Comprehensive package documentation
└── *_test.go           # Test files

Component Overview

┌──────────────────────────────────────────────────────────┐
│                   Input Sources                          │
│  "0644"  │  "rwxr-xr-x"  │  420  │  JSON/YAML/TOML/CBOR  │
└────┬─────┴────────┬──────┴───┬───┴──────────┬────────────┘
     │              │          │              │
     ▼              ▼          ▼              ▼
┌─────────────────────────────────────────────────────────┐
│            Parsing & Unmarshaling Layer                 │
│  parseString() │ parseLetterString() │ Unmarshal*()     │
└────────────────────────┬────────────────────────────────┘
                         ▼
                   ┌──────────┐
                   │   Perm   │  (os.FileMode wrapper)
                   └─────┬────┘
                         │
     ┌───────────────────┼───────────────────┐
     ▼                   ▼                   ▼
┌─────────┐      ┌────────────┐      ┌────────────┐
│ String()│      │ FileMode() │      │ Marshal*() │
│ Int*()  │      │ Uint*()    │      │ formats    │
└─────────┘      └────────────┘      └────────────┘

Component	Responsibility	Thread-Safe
Perm	Type wrapper	✅ immutable
Parse*	Input parsing	✅ stateless
Marshal*	Serialization	✅ stateless
Unmarshal*	Deserialization	✅ stateless
ViperDecoderHook	Config integration	✅ stateless

Permission Formats

1. Octal Strings (Most Common):

"0644"    - Standard file (rw-r--r--)
"0755"    - Executable (rwxr-xr-x)
"0777"    - All permissions (rwxrwxrwx)
"644"     - Without leading zero (accepted)
"'0644'"  - Quoted (quotes stripped)

2. Symbolic Notation (Unix ls -l format):

"rwxr-xr-x"    - 0755
"rw-r--r--"    - 0644
"-rwxr-xr-x"   - Regular file with 0755
"drwxr-xr-x"   - Directory with 0755

3. Numeric Values:

Parse("644")      - String parsed as octal
ParseInt(420)     - Decimal 420 = octal 0644
ParseInt64(493)   - Decimal 493 = octal 0755

---

Performance

Memory Efficiency

Minimal Overhead - Perm is a thin wrapper around os.FileMode:

Type Size:            8 bytes (uint64 internally, uint32 effectively)
Allocation:           0 for value types, 1 for pointer types
Memory Growth:        ZERO (no internal state)

Operation Performance

Operation	Time Complexity	Allocations	Notes
Parse("0644")	O(n)	1-2	n = string length
Parse("rwxr-xr-x")	O(n)	1-2	n = 9-10 chars
ParseInt(420)	O(1)	1-2	Integer to octal conversion
p.String()	O(1)	1	Format to octal string
p.FileMode()	O(1)	0	Direct type conversion
p.Uint64()	O(1)	0	Direct access
MarshalJSON()	O(1)	2	String + JSON encoding
UnmarshalJSON()	O(n)	2-3	Parsing + validation

Benchmark Results

BenchmarkParse-8              5000000    250 ns/op    32 B/op    2 allocs/op
BenchmarkParseSymbolic-8      3000000    400 ns/op    32 B/op    2 allocs/op
BenchmarkString-8            10000000    150 ns/op    24 B/op    1 allocs/op
BenchmarkMarshalJSON-8        5000000    300 ns/op    56 B/op    2 allocs/op

Benchmarks on AMD64, actual performance may vary

---

Use Cases

1. Configuration File Permissions

Problem: Manage file permissions from YAML/JSON configuration files.

import (
    "github.com/nabbar/golib/file/perm"
    "github.com/spf13/viper"
)

type Config struct {
    LogFileMode    perm.Perm `yaml:"log_file_mode"`
    DataFileMode   perm.Perm `yaml:"data_file_mode"`
    ConfigFileMode perm.Perm `yaml:"config_file_mode"`
}

// config.yaml:
// log_file_mode: "0640"
// data_file_mode: "0600"
// config_file_mode: "0644"

Real-world: Web servers, CLI tools, configuration management systems.

2. Dynamic Permission Validation

Problem: Validate and sanitize user-provided file permissions.

func setFilePermission(path string, permStr string) error {
    perm, err := perm.Parse(permStr)
    if err != nil {
        return fmt.Errorf("invalid permission: %w", err)
    }
    
    // Enforce security policy: no world-writable
    if perm.Uint64() & 0002 != 0 {
        return errors.New("world-writable not allowed")
    }
    
    return os.Chmod(path, perm.FileMode())
}

Real-world: Admin panels, file managers, deployment tools.

3. Cross-Platform File Creation

Problem: Create files with consistent permissions across platforms.

func createSecureFile(path string) (*os.File, error) {
    perm, _ := perm.Parse("0600") // Owner read/write only
    
    return os.OpenFile(path, 
        os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 
        perm.FileMode())
}

Real-world: Credential storage, temporary files, sensitive data.

4. Permission Serialization

Problem: Store and transmit permission settings in JSON APIs.

type FileMetadata struct {
    Path        string    `json:"path"`
    Size        int64     `json:"size"`
    Permissions perm.Perm `json:"permissions"`
    ModTime     time.Time `json:"mod_time"`
}

// JSON output:
// {
//   "path": "/data/file.txt",
//   "size": 1024,
//   "permissions": "0644",
//   "mod_time": "2025-11-30T22:00:00Z"
// }

Real-world: File sync services, backup systems, REST APIs.

---

Quick Start

Installation

go get github.com/nabbar/golib/file/perm

Basic Usage (Octal String)

package main

import (
    "fmt"
    "os"
    
    "github.com/nabbar/golib/file/perm"
)

func main() {
    // Parse permission from string
    p, err := perm.Parse("0644")
    if err != nil {
        panic(err)
    }
    
    // Use with file operations
    file, err := os.OpenFile("data.txt", 
        os.O_CREATE|os.O_WRONLY, 
        p.FileMode())
    if err != nil {
        panic(err)
    }
    defer file.Close()
    
    fmt.Printf("Created file with %s permissions\n", p.String())
}

Symbolic Notation

package main

import (
    "fmt"
    
    "github.com/nabbar/golib/file/perm"
)

func main() {
    // Parse from symbolic notation (like ls -l)
    p, err := perm.Parse("rwxr-xr-x")
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Symbolic: rwxr-xr-x\n")
    fmt.Printf("Octal: %s\n", p.String())         // "0755"
    fmt.Printf("Decimal: %d\n", p.Uint64())       // 493
}

JSON Configuration

package main

import (
    "encoding/json"
    
    "github.com/nabbar/golib/file/perm"
)

type Config struct {
    FileMode perm.Perm `json:"file_mode"`
}

func main() {
    // Unmarshal from JSON
    jsonData := []byte(`{"file_mode": "0755"}`)
    
    var cfg Config
    if err := json.Unmarshal(jsonData, &cfg); err != nil {
        panic(err)
    }
    
    fmt.Printf("Loaded permission: %s\n", cfg.FileMode.String())
}

Viper Integration

package main

import (
    "github.com/spf13/viper"
    "github.com/nabbar/golib/file/perm"
)

type AppConfig struct {
    LogPerm  perm.Perm `mapstructure:"log_perm"`
    DataPerm perm.Perm `mapstructure:"data_perm"`
}

func main() {
    v := viper.New()
    v.SetConfigFile("config.yaml")
    v.ReadInConfig()
    
    var cfg AppConfig
    opts := viper.DecoderConfigOption(func(c *mapstructure.DecoderConfig) {
        c.DecodeHook = perm.ViperDecoderHook()
    })
    
    v.Unmarshal(&cfg, opts)
    
    fmt.Printf("Log: %s, Data: %s\n", 
        cfg.LogPerm.String(), 
        cfg.DataPerm.String())
}

Type Conversions

package main

import (
    "fmt"
    
    "github.com/nabbar/golib/file/perm"
)

func main() {
    p, _ := perm.Parse("0755")
    
    // Convert to various types
    fmt.Printf("String:   %s\n", p.String())      // "0755"
    fmt.Printf("Uint64:   %d\n", p.Uint64())      // 493
    fmt.Printf("Int:      %d\n", p.Int())         // 493
    fmt.Printf("FileMode: %v\n", p.FileMode())    // -rwxr-xr-x
}

---

API Reference

Types

Perm

type Perm os.FileMode

Type-safe wrapper around os.FileMode for file permissions.

Functions

Parse

func Parse(s string) (Perm, error)

Parses a string representation into a Perm. Supports:

• Octal strings: "0644", "0755", "644"
• Symbolic notation: "rwxr-xr-x", "rw-r--r--"
• File type prefix: "-rwxr-xr-x", "drwxr-xr-x"
• Quoted strings: "'0644'", ""0755""

Returns: Parsed Perm value or error for invalid input.

ParseFileMode

func ParseFileMode(p os.FileMode) Perm

Converts os.FileMode to Perm. Useful for converting file mode from os.Stat().

ParseInt

func ParseInt(i int) (Perm, error)

Parses decimal integer as octal permission. Example: ParseInt(420) → Perm(0644).

ParseInt64

func ParseInt64(i int64) (Perm, error)

Parses 64-bit decimal integer as octal permission.

ParseByte

func ParseByte(p []byte) (Perm, error)

Parses byte slice as permission string.

ViperDecoderHook

func ViperDecoderHook() DecodeHookFuncType

Returns a Viper decoder hook for automatic Perm unmarshaling from config files.

Methods

String

func (p Perm) String() string

Returns octal string representation (e.g., "0644").

FileMode

func (p Perm) FileMode() os.FileMode

Converts to os.FileMode for use with os package functions.

Type Conversions

func (p Perm) Uint64() uint64
func (p Perm) Uint32() uint32
func (p Perm) Uint() uint
func (p Perm) Int64() int64
func (p Perm) Int32() int32
func (p Perm) Int() int

Convert to various integer types with overflow protection.

Marshaling

func (p Perm) MarshalJSON() ([]byte, error)
func (p *Perm) UnmarshalJSON(b []byte) error
func (p Perm) MarshalYAML() (interface{}, error)
func (p *Perm) UnmarshalYAML(value *yaml.Node) error
func (p Perm) MarshalTOML() ([]byte, error)
func (p *Perm) UnmarshalTOML(i interface{}) error
func (p Perm) MarshalText() ([]byte, error)
func (p *Perm) UnmarshalText(b []byte) error
func (p Perm) MarshalCBOR() ([]byte, error)
func (p *Perm) UnmarshalCBOR(b []byte) error

Automatic serialization/deserialization for various formats.

---

Best Practices

Permission Selection

Use standard, secure permissions:

// ✅ GOOD: Standard permissions
perm.Parse("0644")  // Regular files (rw-r--r--)
perm.Parse("0755")  // Executables (rwxr-xr-x)
perm.Parse("0600")  // Sensitive files (rw-------)
perm.Parse("0700")  // Private executables (rwx------)

// ❌ BAD: Insecure permissions
perm.Parse("0777")  // World-writable (dangerous!)
perm.Parse("0666")  // World-writable file (risky)

Error Handling

Always check errors from Parse functions:

// ✅ GOOD: Proper error handling
p, err := perm.Parse(userInput)
if err != nil {
    return fmt.Errorf("invalid permission %q: %w", userInput, err)
}

// ❌ BAD: Ignoring errors
p, _ := perm.Parse(userInput)  // May panic later!

Configuration Files

Use Perm type in config structs:

// ✅ GOOD: Type-safe configuration
type Config struct {
    LogMode  perm.Perm `yaml:"log_mode"`
    DataMode perm.Perm `yaml:"data_mode"`
}

// ❌ BAD: Using strings or ints
type Config struct {
    LogMode  string `yaml:"log_mode"`   // No validation
    DataMode int    `yaml:"data_mode"`  // Ambiguous (octal? decimal?)
}

Validation

Validate permissions before applying:

// ✅ GOOD: Security validation
func setPermission(path string, permStr string) error {
    p, err := perm.Parse(permStr)
    if err != nil {
        return err
    }
    
    // Check for world-writable
    if p.Uint64() & 0002 != 0 {
        return errors.New("world-writable not allowed")
    }
    
    return os.Chmod(path, p.FileMode())
}

Testing

The package includes comprehensive tests with 91.9% coverage and zero race conditions.

Run tests:

go test ./...                          # All tests
go test -cover ./...                   # With coverage
CGO_ENABLED=1 go test -race ./...      # Race detection

See TESTING.md for detailed testing documentation.

---

Contributing

Contributions are welcome! Please follow these guidelines:

1. Code Quality

   • Follow Go best practices and idioms
   • Maintain or improve code coverage (target: >80%)
   • Pass all tests including race detector
   • Use gofmt and golint

2. AI Usage Policy

   • ❌ AI must NEVER be used to generate package code or core functionality
   • ✅ AI assistance is limited to:
     • Testing (writing and improving tests)
     • Debugging (troubleshooting and bug resolution)
     • Documentation (comments, README, TESTING.md)
   • All AI-assisted work must be reviewed and validated by humans

3. Testing

   • Add tests for new features
   • Use Ginkgo v2 / Gomega for test framework
   • Ensure zero race conditions with go test -race
   • Test all supported formats (octal, symbolic, numeric)

4. Documentation

   • Update GoDoc comments for public APIs
   • Add examples for new features
   • Update README.md and TESTING.md if needed

5. Pull Request Process

   • Fork the repository
   • Create a feature branch
   • Write clear commit messages
   • Ensure all tests pass
   • Update documentation
   • Submit PR with description of changes

See CONTRIBUTING.md for detailed guidelines.

---

Improvements & Security

Current Status

The package is production-ready with no urgent improvements or security vulnerabilities identified.

Code Quality Metrics

• ✅ 91.9% test coverage (target: >80%)
• ✅ Zero race conditions detected with -race flag
• ✅ 169 test specifications covering all major use cases
• ✅ Format validation prevents invalid permissions
• ✅ Type safety catches errors at compile time

Future Enhancements (Non-urgent)

The following enhancements could be considered for future versions:

Parser Improvements:

1. Support for ACL (Access Control List) parsing
2. Windows-specific permission mapping
3. Umask calculation and application
4. Permission diff/comparison utilities

Format Support:

1. Additional file type indicators
2. Extended attributes support
3. SELinux context parsing
4. Custom format templates

Validation Features:

1. Permission policy enforcement
2. Security audit logging
3. Whitelist/blacklist validation
4. Umask-aware validation

Integration:

1. Support for additional config frameworks
2. Database schema validation
3. Kubernetes SecurityContext integration
4. Docker permission mapping

These are optional improvements and not required for production use. The current implementation is stable, performant, and feature-complete for its intended use cases.

Suggestions and contributions are welcome via GitHub issues.

---

Resources

Package Documentation

• GoDoc - Complete API reference with function signatures, method descriptions, and runnable examples. Essential for understanding the public interface.

• doc.go - In-depth package documentation including design philosophy, permission formats, parsing algorithms, serialization support, and best practices.

• TESTING.md - Comprehensive test suite documentation covering test architecture, BDD methodology with Ginkgo v2, 91.9% coverage analysis, and testing guidelines.

Related golib Packages

• github.com/nabbar/golib/file/progress - File I/O progress tracking. Can be combined with perm for progress-tracked file operations with specific permissions.

• github.com/nabbar/golib/file/bandwidth - Bandwidth throttling for file I/O. Complements perm for controlled file creation with specific permissions.

Standard Library References

• os - Operating system functionality including FileMode type. The perm package wraps and extends os.FileMode.

• os.FileMode - File mode and permission bits. Understanding FileMode is essential for using the perm package effectively.

• strconv - String conversions. Used internally for parsing octal strings.

Configuration Libraries

• Viper - Configuration management library. The perm package provides a decoder hook for seamless Viper integration.

• mapstructure - Decoding generic map values. Used by the ViperDecoderHook function.

Serialization Formats

• encoding/json - JSON encoding/decoding
• gopkg.in/yaml.v3 - YAML v3 support
• github.com/fxamacker/cbor/v2 - CBOR encoding

External References

• File Permissions - Wikipedia article on file system permissions covering concepts, history, and platform-specific implementations.

• chmod Manual - Linux chmod command documentation explaining octal and symbolic notation.

• Effective Go - Official Go programming guide. The perm package follows these conventions for idiomatic code.

Community & Support

• GitHub Issues - Report bugs, request features, or ask questions. Check existing issues before creating new ones.

• Contributing Guide - Guidelines for contributing code, tests, and documentation.

---

AI Transparency

In compliance with EU AI Act Article 50.4: AI assistance was used for testing, documentation, and bug resolution under human supervision. All core functionality is human-designed and validated.

---

License

MIT License - See LICENSE file for details.

Copyright (c) 2025 Nicolas JUHEL

---

Maintained by: Nicolas JUHEL
Package: github.com/nabbar/golib/file/perm
Version: See releases for versioning