ComponentFactory API

ComponentFactory creates and manages shared components for Loader and Parser, providing clear lifecycle management.

Type Definition

type ComponentFactory struct {
    // Contains private fields
}

Core Responsibilities:

Creates shared validators, auditors, and variable expanders
Manages component lifecycle
Supports custom parsers accessing internal components

Thread Safety: All ComponentFactory methods are thread-safe.

Methods

Validator

func (f *ComponentFactory) Validator() Validator

Returns the validator component for key name and value validation.

// Use in custom parser
validator := factory.Validator()

if err := validator.ValidateKey("MY_KEY"); err != nil {
    // Invalid key
}

if err := validator.ValidateValue("some value"); err != nil {
    // Value contains illegal content (e.g., null bytes, control characters)
}

Auditor

func (f *ComponentFactory) Auditor() FullAuditLogger

Returns the audit logging component, providing complete audit logging functionality.

auditor := factory.Auditor()
_ = auditor.Log(env.ActionSet, "KEY", "value set", true)
_ = auditor.LogError(env.ActionSet, "KEY", "validation failed")
_ = auditor.LogWithFile(env.ActionLoad, "KEY", ".env", "loaded", true)
_ = auditor.LogWithDuration(env.ActionParse, "", "parsed", true, time.Since(start))

Expander

func (f *ComponentFactory) Expander() VariableExpander

Returns the variable expander component for ${VAR} syntax variable expansion.

expander := factory.Expander()
expanded, err := expander.Expand("${BASE_URL}/api")

Close

func (f *ComponentFactory) Close() error

Releases resources held by the factory. After closing, the factory and components created through it should not be used.

Behavior:

Safe close; multiple calls return nil
Releases auditor resources
Uses atomic operations to ensure thread safety

// Usually managed automatically by Loader
loader, _ := env.New(cfg)
defer loader.Close()  // Auto-close ComponentFactory

IsClosed

func (f *ComponentFactory) IsClosed() bool

Checks whether the factory is closed.

if factory.IsClosed() {
    // Factory is closed, unusable
}

Creation Methods

Automatic Creation (Recommended)

Loader automatically creates and manages ComponentFactory during creation:

cfg := env.DefaultConfig()
loader, _ := env.New(cfg)
// Loader internally auto-creates ComponentFactory
defer loader.Close()  // Auto-close factory

Using in Custom Parsers

When registering custom parsers, get validator and auditor through ComponentFactory:

type CustomParser struct {
    cfg       env.Config
    validator env.Validator
    auditor   env.FullAuditLogger
}

func newCustomParser(cfg env.Config, factory *env.ComponentFactory) *CustomParser {
    return &CustomParser{
        cfg:       cfg,
        validator: factory.Validator(),
        auditor:   factory.Auditor(),
    }
}

// Define custom format constant (recommend using 100+ to avoid conflicts)
const FormatCustom env.FileFormat = 100

// Register parser
env.RegisterParser(FormatCustom, func(cfg env.Config, factory *env.ComponentFactory) (env.EnvParser, error) {
    return newCustomParser(cfg, factory), nil
})

Lifecycle Management

text

Config creation
     ↓
env.New(cfg)
     ↓
Auto-create ComponentFactory
     ↓
    ┌───────┼───────┐
    ↓       ↓       ↓
Validator  Auditor  Expander
    ↓       ↓       ↓
    └───────┼───────┘
            ↓
      Loader/Parser
            ↓
      Close() release

Note

Each Loader typically owns its own ComponentFactory
After calling Close(), all components created through the factory should no longer be used
Factory is thread-safe, supports concurrent access

Audit Handler Factory

NewJSONAuditHandler

func NewJSONAuditHandler(w io.Writer) *JSONAuditHandler

Creates a JSON format audit handler, outputting structured logs.

Parameters:

w - Output target (e.g., os.Stdout, file)

cfg := env.ProductionConfig()
cfg.AuditEnabled = true
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)

Example Output:

json

{"timestamp":"2024-01-15T10:30:00Z","action":"load","file":".env","success":true,"duration_ns":1234567}

NewLogAuditHandler

func NewLogAuditHandler(logger *log.Logger) *LogAuditHandler

Creates a standard log format audit handler.

Parameters:

logger - Standard log.Logger instance

import "log"

logger := log.New(os.Stderr, "[AUDIT] ", log.LstdFlags)
cfg.AuditHandler = env.NewLogAuditHandler(logger)

Example Output:

text

[AUDIT] 2024/01/15 10:30:00 load .env success (1.23ms)

NewChannelAuditHandler

func NewChannelAuditHandler(ch chan<- AuditEvent) *ChannelAuditHandler

Creates a channel audit handler for asynchronous audit event processing.

Parameters:

ch - Audit event channel

ch := make(chan env.AuditEvent, 100)
cfg.AuditHandler = env.NewChannelAuditHandler(ch)

// Process audit events asynchronously
go func() {
    for event := range ch {
        fmt.Printf("Audit: %+v\n", event)
    }
}()

NewNopAuditHandler

func NewNopAuditHandler() *NopAuditHandler

Creates a no-op audit handler for disabling audit logging.

cfg.AuditEnabled = true
cfg.AuditHandler = env.NewNopAuditHandler() // No logs recorded

NewCloseableChannelHandler

func NewCloseableChannelHandler(bufferSize int) *CloseableChannelHandler

Creates a closeable audit handler with its own buffered channel. Unlike ChannelAuditHandler which accepts an external channel, CloseableChannelHandler creates and owns its own buffered channel. Call Close() to close the handler and the channel. Use Channel() to receive events.

Parameters:

bufferSize - Buffered channel size (negative values are treated as 0)

handler := env.NewCloseableChannelHandler(64)
defer handler.Close()

go func() {
    for event := range handler.Channel() {
        fmt.Printf("Audit: %+v\n", event)
    }
}()

CloseableChannelHandler Methods

In addition to implementing the AuditHandler interface (Log / Close), CloseableChannelHandler provides the following specific methods:

func (h *CloseableChannelHandler) Channel() <-chan AuditEvent
func (h *CloseableChannelHandler) IsClosed() bool

Method Descriptions:

Method	Signature	Purpose
`Channel`	`func (h *CloseableChannelHandler) Channel() <-chan AuditEvent`	Returns the internal read-only channel for consuming audit events. After `Close()` is called, this channel is closed and the `range` loop exits accordingly
`IsClosed`	`func (h *CloseableChannelHandler) IsClosed() bool`	Checks whether the handler has been closed (thread-safe, can be called concurrently)

handler := env.NewCloseableChannelHandler(64)
defer handler.Close()

// Check status before closing
if !handler.IsClosed() {
    // Handler is still usable
}

// Consume events until the channel closes
go func() {
    for event := range handler.Channel() {
        fmt.Printf("Audit: %+v\n", event)
    }
    // After handler.Close(), the channel closes and the loop exits
}()

File System

OSFileSystem

Default file system implementation, wrapping OS file operations:

type OSFileSystem struct{}

Implements: FileSystem

// Method list
func (fs OSFileSystem) Open(name string) (File, error)
func (fs OSFileSystem) OpenFile(name string, flag int, perm os.FileMode) (File, error)
func (fs OSFileSystem) Stat(name string) (os.FileInfo, error)
func (fs OSFileSystem) MkdirAll(path string, perm os.FileMode) error
func (fs OSFileSystem) Remove(name string) error
func (fs OSFileSystem) Rename(oldpath, newpath string) error
func (fs OSFileSystem) Getenv(key string) string
func (fs OSFileSystem) Setenv(key, value string) error
func (fs OSFileSystem) Unsetenv(key string) error
func (fs OSFileSystem) LookupEnv(key string) (string, bool)

DefaultFileSystem

var DefaultFileSystem FileSystem = OSFileSystem{}

Global default file system instance.

Using Custom File System

Mock file system in tests:

type MockFileSystem struct {
    files map[string]string
    env   map[string]string
}

func (m *MockFileSystem) Open(name string) (env.File, error) {
    content, ok := m.files[name]
    if !ok {
        return nil, os.ErrNotExist
    }
    return &MockFile{content: content}, nil
}

func (m *MockFileSystem) Getenv(key string) string {
    return m.env[key]
}

func (m *MockFileSystem) Setenv(key, value string) error {
    m.env[key] = value
    return nil
}

func (m *MockFileSystem) Unsetenv(key string) error {
    delete(m.env, key)
    return nil
}

func (m *MockFileSystem) LookupEnv(key string) (string, bool) {
    val, ok := m.env[key]
    return val, ok
}

func (m *MockFileSystem) OpenFile(name string, flag int, perm os.FileMode) (env.File, error) {
    return m.Open(name)
}

func (m *MockFileSystem) Stat(name string) (os.FileInfo, error) {
    if _, ok := m.files[name]; !ok {
        return nil, os.ErrNotExist
    }
    return nil, nil
}

func (m *MockFileSystem) MkdirAll(path string, perm os.FileMode) error {
    return nil
}

func (m *MockFileSystem) Remove(name string) error {
    delete(m.files, name)
    return nil
}

func (m *MockFileSystem) Rename(oldpath, newpath string) error {
    m.files[newpath] = m.files[oldpath]
    delete(m.files, oldpath)
    return nil
}

// Usage
cfg := env.TestingConfig()
cfg.FileSystem = &MockFileSystem{
    files: map[string]string{".env": "KEY=value"},
    env:   make(map[string]string),
}

Format Detection

DetectFormat

func DetectFormat(filename string) FileFormat

Detects format based on file extension.

Parameters:

filename - File name or path

Returns:

FileFormat - Detected format

Detection Rules:

Extension	Returns
`.env`	`FormatEnv`
`.json`	`FormatJSON`
`.yaml`, `.yml`	`FormatYAML`
Other	`FormatAuto`

format := env.DetectFormat("config.json")   // FormatJSON
format := env.DetectFormat("settings.yaml") // FormatYAML
format := env.DetectFormat("app.yml")       // FormatYAML
format := env.DetectFormat(".env")          // FormatEnv
format := env.DetectFormat(".env.local")    // FormatAuto (actually processed as .env)
format := env.DetectFormat("unknown.txt")   // FormatAuto

Applied in LoadFiles:

loader.LoadFiles("config.env", "settings.json", "secrets.yaml")
// Auto-detect each file's format and use corresponding parser

FileFormat Constants

const (
    FormatAuto  FileFormat = iota  // Auto-detect
    FormatEnv                      // .env format
    FormatJSON                     // JSON format
    FormatYAML                     // YAML format
)

Custom Formats:

// Define custom format constant (recommend using 100+ to avoid conflicts)
const (
    FormatTOML  env.FileFormat = 100
    FormatINI   env.FileFormat = 101
    FormatXML   env.FileFormat = 102
)

FileFormat.String

func (f FileFormat) String() string

Returns the string representation of the format.

fmt.Println(env.FormatJSON.String())  // "json"
fmt.Println(env.FormatYAML.String())  // "yaml"
fmt.Println(env.FormatEnv.String())   // "dotenv"
fmt.Println(env.FormatAuto.String())  // "auto"
fmt.Println(env.FileFormat(999).String())  // "unknown"

Parser Registration

RegisterParser

func RegisterParser(format FileFormat, factory ParserFactory) error

Registers a custom format parser.

Parameters:

format - File format constant
factory - Parser factory function

Returns:

error - Error on registration failure

Error Cases:

Built-in formats (FormatEnv, FormatJSON, FormatYAML) cannot be overwritten
Format already registered

Notes:

Must be registered before calling env.New()
Recommend using format values 100+ to avoid conflicts with built-in formats
Factory function should return thread-safe parser

package main

import (
    "io"

    "github.com/cybergodev/env"
)

// 1. Define custom format constant
const FormatTOML env.FileFormat = 100

// 2. Implement parser interface
type TOMLParser struct {
    cfg       env.Config
    validator env.Validator
    auditor   env.FullAuditLogger
}

func (p *TOMLParser) Parse(r io.Reader, filename string) (map[string]string, error) {
    // Implement TOML parsing logic
    result := make(map[string]string)
    // ... parsing code
    return result, nil
}

// 3. Register parser in init() to ensure it runs before use
func init() {
    err := env.RegisterParser(FormatTOML, func(cfg env.Config, f *env.ComponentFactory) (env.EnvParser, error) {
        return &TOMLParser{
            cfg:       cfg,
            validator: f.Validator(),
            auditor:   f.Auditor(),
        }, nil
    })
    if err != nil {
        panic(err)
    }
}

// 4. Use custom format
func main() {
    // Registration completed in init() (runs before main)
    loader, _ := env.New(env.DefaultConfig())
    defer loader.Close()

    // Now can load .toml files
    loader.LoadFiles("config.toml")
}

ForceRegisterParser

func ForceRegisterParser(format FileFormat, factory ParserFactory) error

Force-registers a parser, allowing overwrite of built-in parsers.

Parameters:

format - File format constant
factory - Parser factory function

Returns:

error - Error on registration failure (when factory is nil)

Warning

Use with caution. Overwriting built-in parsers may introduce security vulnerabilities if the replacement parser does not implement the same security checks (key validation, value validation, size limits, etc.).

Suitable for the following advanced scenarios:

Adding custom security checks to built-in parsers
Implementing format extensions (e.g., HEREDOC, multiline values)
Using mock parsers for testing

// Overwrite default .env parser (advanced use)
err := env.ForceRegisterParser(env.FormatEnv, func(cfg env.Config, f *env.ComponentFactory) (env.EnvParser, error) {
    return &MyCustomEnvParser{
        validator: f.Validator(),
        auditor:   f.Auditor(),
    }, nil
})

ParserFactory Type

type ParserFactory func(cfg Config, factory *ComponentFactory) (EnvParser, error)

Parser factory function signature.

Parameters:

cfg - Configuration object, containing limits and security settings
factory - Component factory, can get validator and auditor

Returns:

EnvParser - Parser instance
error - Creation error

EnvParser Interface

type EnvParser interface {
    Parse(r io.Reader, filename string) (map[string]string, error)
}

Interface that parsers must implement.

Parameters:

r - File content reader
filename - File name (for error messages)

Returns:

map[string]string - Parsed key-value pairs
error - Parse error

Built-in Parsers

The library includes three built-in format parsers:

DotEnv Parser

.env format parser, supports:

KEY=value syntax
export KEY=value syntax
Single quotes 'value' and double quotes "value"
Variable expansion ${VAR} and ${VAR:-default}
Comments #

JSON Parser

JSON format parser, supports:

Key-value pair objects
Nested structures (flattened)
Number, string, boolean conversion
Arrays (flattened to KEY_0, KEY_1...)

YAML Parser

YAML format parser, supports:

Key-value pairs
Nested structures (flattened)
Multiple scalar types
Lists (flattened to indexed keys)

Complete Example

Register Custom Parser

package main

import (
    "fmt"
    "io"
    "strings"

    "github.com/cybergodev/env"
)

// Custom INI parser
type INIParser struct {
    cfg       env.Config
    validator env.Validator
    auditor   env.FullAuditLogger
}

func (p *INIParser) Parse(r io.Reader, filename string) (map[string]string, error) {
    content, err := io.ReadAll(r)
    if err != nil {
        return nil, err
    }

    result := make(map[string]string)
    lines := strings.Split(string(content), "\n")
    var section string

    for lineNum, line := range lines {
        line = strings.TrimSpace(line)

        // Skip empty lines and comments
        if line == "" || strings.HasPrefix(line, ";") || strings.HasPrefix(line, "#") {
            continue
        }

        // Section [section]
        if strings.HasPrefix(line, "[") && strings.HasSuffix(line, "]") {
            section = strings.Trim(line, "[]")
            continue
        }

        // Key=Value
        if idx := strings.Index(line, "="); idx > 0 {
            key := strings.TrimSpace(line[:idx])
            value := strings.TrimSpace(line[idx+1:])

            // Add section prefix
            if section != "" {
                key = section + "_" + key
            }

            // Validate key
            if err := p.validator.ValidateKey(key); err != nil {
                _ = p.auditor.LogError(env.ActionParse, key, err.Error())
                return nil, fmt.Errorf("line %d: %w", lineNum+1, err)
            }

            result[strings.ToUpper(key)] = value
        }
    }

    _ = p.auditor.Log(env.ActionParse, "", fmt.Sprintf("parsed %d variables from %s", len(result), filename), true)
    return result, nil
}

func main() {
    // Define custom format
    const FormatINI env.FileFormat = 101

    // Register parser
    err := env.RegisterParser(FormatINI, func(cfg env.Config, f *env.ComponentFactory) (env.EnvParser, error) {
        return &INIParser{
            cfg:       cfg,
            validator: f.Validator(),
            auditor:   f.Auditor(),
        }, nil
    })
    if err != nil {
        panic(err)
    }

    // Use custom format
    cfg := env.DefaultConfig()
    loader, _ := env.New(cfg)
    defer loader.Close()

    // Now can load .ini files
    // loader.LoadFiles("config.ini")

    fmt.Println("INI parser registered")
}

Custom File System

package main

import (
    "errors"
    "fmt"
    "os"
    "strings"
    "time"

    "github.com/cybergodev/env"
)

// In-memory file system (for testing)
type MemoryFileSystem struct {
    files map[string]string
    env   map[string]string
}

func NewMemoryFileSystem() *MemoryFileSystem {
    return &MemoryFileSystem{
        files: make(map[string]string),
        env:   make(map[string]string),
    }
}

func (m *MemoryFileSystem) Open(name string) (env.File, error) {
    content, ok := m.files[name]
    if !ok {
        return nil, os.ErrNotExist
    }
    return &MemoryFile{reader: strings.NewReader(content)}, nil
}

func (m *MemoryFileSystem) OpenFile(name string, flag int, perm os.FileMode) (env.File, error) {
    return m.Open(name)
}

func (m *MemoryFileSystem) Stat(name string) (os.FileInfo, error) {
    content, ok := m.files[name]
    if !ok {
        return nil, os.ErrNotExist
    }
    return &MemoryFileInfo{name: name, size: int64(len(content))}, nil
}

func (m *MemoryFileSystem) MkdirAll(path string, perm os.FileMode) error {
    return nil
}

func (m *MemoryFileSystem) Remove(name string) error {
    delete(m.files, name)
    return nil
}

func (m *MemoryFileSystem) Rename(oldpath, newpath string) error {
    m.files[newpath] = m.files[oldpath]
    delete(m.files, oldpath)
    return nil
}

func (m *MemoryFileSystem) Getenv(key string) string {
    return m.env[key]
}

func (m *MemoryFileSystem) Setenv(key, value string) error {
    m.env[key] = value
    return nil
}

func (m *MemoryFileSystem) Unsetenv(key string) error {
    delete(m.env, key)
    return nil
}

func (m *MemoryFileSystem) LookupEnv(key string) (string, bool) {
    val, ok := m.env[key]
    return val, ok
}

// MemoryFile implements env.File
type MemoryFile struct {
    reader *strings.Reader
}

func (f *MemoryFile) Read(p []byte) (n int, err error)  { return f.reader.Read(p) }
func (f *MemoryFile) Write(p []byte) (n int, err error) { return 0, errors.ErrUnsupported }
func (f *MemoryFile) Close() error                      { return nil }
func (f *MemoryFile) Stat() (os.FileInfo, error)        { return nil, errors.ErrUnsupported }
func (f *MemoryFile) Sync() error                       { return nil }

// MemoryFileInfo implements os.FileInfo
type MemoryFileInfo struct {
    name string
    size int64
}

func (i *MemoryFileInfo) Name() string       { return i.name }
func (i *MemoryFileInfo) Size() int64        { return i.size }
func (i *MemoryFileInfo) Mode() os.FileMode  { return 0644 }
func (i *MemoryFileInfo) ModTime() time.Time { return time.Time{} }
func (i *MemoryFileInfo) IsDir() bool        { return false }
func (i *MemoryFileInfo) Sys() interface{}   { return nil }

// Usage example
func main() {
    // Create in-memory file system
    fs := NewMemoryFileSystem()
    fs.files[".env"] = "APP_NAME=myapp\nPORT=8080\n"

    // Configure to use custom file system
    cfg := env.TestingConfig()
    cfg.FileSystem = fs

    loader, _ := env.New(cfg)
    defer loader.Close()

    loader.LoadFiles(".env")

    fmt.Println(loader.GetString("APP_NAME"))  // myapp
    fmt.Println(loader.GetInt("PORT"))         // 8080
}

Interfaces - All interface definitions
Custom Parser - Custom parser guide
Testing Scenarios - Testing with custom file system

ComponentFactory API ​

Type Definition ​

Methods ​

Validator ​

Auditor ​

Expander ​

Close ​

IsClosed ​

Creation Methods ​

Automatic Creation (Recommended) ​

Using in Custom Parsers ​

Lifecycle Management ​

Audit Handler Factory ​

NewJSONAuditHandler ​

NewLogAuditHandler ​

NewChannelAuditHandler ​

NewNopAuditHandler ​

NewCloseableChannelHandler ​

CloseableChannelHandler Methods ​

File System ​

OSFileSystem ​

DefaultFileSystem ​

Using Custom File System ​

Format Detection ​

DetectFormat ​

FileFormat Constants ​

FileFormat.String ​

Parser Registration ​

RegisterParser ​

ForceRegisterParser ​

ParserFactory Type ​

EnvParser Interface ​

Built-in Parsers ​

DotEnv Parser ​

JSON Parser ​

YAML Parser ​

Complete Example ​

Register Custom Parser ​

Custom File System ​

Related Documentation ​

ComponentFactory API

Type Definition

Methods

Validator

Auditor

Expander

Close

IsClosed

Creation Methods

Automatic Creation (Recommended)

Using in Custom Parsers

Lifecycle Management

Audit Handler Factory

NewJSONAuditHandler

NewLogAuditHandler

NewChannelAuditHandler

NewNopAuditHandler

NewCloseableChannelHandler

CloseableChannelHandler Methods

File System

OSFileSystem

DefaultFileSystem

Using Custom File System

Format Detection

DetectFormat

FileFormat Constants

FileFormat.String

Parser Registration

RegisterParser

ForceRegisterParser

ParserFactory Type

EnvParser Interface

Built-in Parsers

DotEnv Parser

JSON Parser

YAML Parser

Complete Example

Register Custom Parser

Custom File System

Related Documentation