cv-site/internal/validation/README.md

Validation Package

High-performance struct tag-based validation system with zero external dependencies.

Features

• Struct Tag Validation: Declarative validation using Go struct tags
• High Performance: Reflection caching achieves ~260µs per validation (12x faster than manual validation)
• Zero Dependencies: Pure Go stdlib implementation
• UTF-8 Aware: Proper Unicode handling for international names
• Security First: Email injection prevention, honeypot detection, timing validation
• Thread-Safe: Safe for concurrent use
• Backward Compatible: Existing manual validation functions preserved

Quick Start

// Define struct with validation tags
type ContactFormRequest struct {
    Name      string `json:"name"      validate:"required,trim,max=100,pattern=name,no_injection"`
    Email     string `json:"email"     validate:"required,trim,max=254,email,no_injection"`
    Company   string `json:"company"   validate:"optional,trim,max=100,pattern=company"`
    Subject   string `json:"subject"   validate:"required,trim,max=200,pattern=subject,no_injection"`
    Message   string `json:"message"   validate:"required,trim,max=5000,sanitize"`
    Honeypot  string `json:"website"   validate:"honeypot"`
    Timestamp int64  `json:"timestamp" validate:"timing=2:86400"`
}

// Validate
req := &ContactFormRequest{...}
if err := ValidateContactFormV2(req); err != nil {
    // Handle validation errors
    if verrs, ok := err.(ValidationErrors); ok {
        for _, e := range verrs {
            fmt.Printf("%s: %s\n", e.Field, e.Message)
        }
    }
}

Available Validation Rules

Required/Optional

• required - Field must not be empty (after trimming)
• optional - Explicit marker for optional fields

Transformations

• trim - Auto-trim whitespace from field value
• sanitize - Remove newlines and escape HTML (for message body)

Length Validation (UTF-8 aware)

• min=N - Minimum rune count (e.g., min=3)
• max=N - Maximum rune count (e.g., max=100)

Format Validation

• email - RFC 5322 email validation
• pattern=TYPE - Predefined regex patterns:
  • pattern=name - Letters, spaces, hyphens, apostrophes (international names)
  • pattern=subject - Alphanumeric + safe punctuation including #
  • pattern=company - Alphanumeric + business punctuation (&, -, etc.)

Security Rules

• no_injection - Prevent email header injection attacks
• honeypot - Must be empty (bot detection)
• timing=min:max - Timestamp validation in seconds (e.g., timing=2:86400 = 2s to 24h)

Rule Execution Order

1. Transformations applied first: trim, sanitize
2. Validations executed in tag order: required, min, max, email, pattern, no_injection, etc.
3. Multiple errors can be returned for a single field

Validation Errors

// FieldError - single field error
type FieldError struct {
    Field   string `json:"field"`            // Field name
    Tag     string `json:"tag"`              // Validation tag that failed
    Param   string `json:"param,omitempty"`  // Optional parameter
    Message string `json:"message"`          // Human-readable message
}

// ValidationErrors - collection of field errors
type ValidationErrors []FieldError

// Helper methods
func (ve ValidationErrors) HasErrors() bool
func (ve ValidationErrors) GetFieldError(field string) *FieldError
func (ve ValidationErrors) GetFieldErrors(field string) []FieldError

Performance

Benchmarks on Apple M-series (12 cores):

Operation                          Time/op    Speed vs Manual
──────────────────────────────────────────────────────────────
Manual Validation                  3,089 µs   1x (baseline)
First Validation (no cache)         718 µs   4.3x faster
Cached Validation                   363 µs   8.5x faster
Global Validator (cached)           260 µs   11.9x faster ✓

Key Performance Features:

• Struct metadata caching (sync.Map) - first validation ~500ns, cached ~50ns
• Pre-compiled regex patterns at init time
• UTF-8 aware length validation with utf8.RuneCountInString()
• Minimal allocations: ~90KB, ~477 allocs per validation

Advanced Usage

Custom Validator Instance

// Create reusable validator with cached metadata
v := NewValidator()

// Validate multiple structs (metadata cached per type)
err1 := v.Validate(&user1)
err2 := v.Validate(&user2)

Error Handling

err := ValidateContactFormV2(req)
if err != nil {
    // Type assert to ValidationErrors
    verrs, ok := err.(ValidationErrors)
    if !ok {
        // Not a validation error
        return err
    }

    // Get specific field error
    if nameErr := verrs.GetFieldError("name"); nameErr != nil {
        fmt.Printf("Name error: %s\n", nameErr.Message)
    }

    // Get all errors for a field
    emailErrors := verrs.GetFieldErrors("email")

    // Iterate all errors
    for _, e := range verrs {
        fmt.Printf("%s: %s (tag=%s)\n", e.Field, e.Message, e.Tag)
    }
}

Multiple Validations

// Tags are executed left to right
validate:"required,trim,max=100,pattern=name,no_injection"

// Execution order:
// 1. trim (transform)
// 2. required (validate)
// 3. max=100 (validate)
// 4. pattern=name (validate)
// 5. no_injection (validate)

Security Features

Email Header Injection Prevention

Detects and blocks attempts to inject email headers via newlines or header patterns:

"Name\nBcc: evil@example.com"  // ❌ Blocked by no_injection
"Bcc: evil@example.com"         // ❌ Blocked by no_injection
"Normal Name"                   // ✓ Valid

Bot Detection

Two-layer bot protection:

// Honeypot field (must be empty)
Honeypot string `validate:"honeypot"`

// Timing validation (2 seconds minimum, 24 hours maximum)
Timestamp int64 `validate:"timing=2:86400"`

Input Sanitization

Message field automatically sanitized:

// Before: "<script>alert('XSS')</script>"
// After:  "&lt;script&gt;alert('XSS')&lt;/script&gt;"
Message string `validate:"sanitize"`

Backward Compatibility

Legacy manual validation functions remain available:

// V1 - Manual validation (still works)
err := ValidateContactForm(req)

// V2 - Struct tag validation (recommended)
err := ValidateContactFormV2(req)

// Helper functions (still available)
IsValidEmail(email string) bool
IsValidName(name string) bool
IsValidSubject(subject string) bool
IsValidCompany(company string) bool
ContainsEmailInjection(s string) bool
SanitizeContactForm(req *ContactFormRequest)

Testing

# Run all tests
go test ./internal/validation/...

# Run with coverage
go test -cover ./internal/validation/...

# Run benchmarks
go test -bench=. -benchmem ./internal/validation/...

# Run specific test
go test -run TestValidatorV2_EmailValidation ./internal/validation/...

Examples

Example 1: Contact Form

req := &ContactFormRequest{
    Name:      "  John O'Connor  ",  // Will be trimmed
    Email:     "john@example.com",
    Company:   "Acme Corp",          // Optional
    Subject:   "Question #123",
    Message:   "<b>Hello</b>",       // Will be sanitized
    Honeypot:  "",                   // Must be empty
    Timestamp: time.Now().Unix() - 10,
}

if err := ValidateContactFormV2(req); err != nil {
    log.Fatal(err)
}

// req.Name is now "John O'Connor" (trimmed)
// req.Message is now "&lt;b&gt;Hello&lt;/b&gt;" (sanitized)

Example 2: Handling Multiple Errors

req := &ContactFormRequest{
    Name:    strings.Repeat("a", 101), // Too long
    Email:   "invalid-email",          // Invalid format
    Subject: "",                       // Missing required
    Message: "Valid message",
}

err := ValidateContactFormV2(req)
verrs := err.(ValidationErrors)

// Output all errors
// name: name must be 100 characters or less (max=100)
// email: Invalid email address format (email)
// subject: subject is required (required)

Example 3: International Names

// All valid international names
names := []string{
    "José María",      // Spanish
    "François Dubois", // French
    "Müller",          // German
    "田中太郎",         // Japanese
    "Anne-Marie",      // Hyphenated
    "O'Connor",        // Apostrophe
}

for _, name := range names {
    req := &ContactFormRequest{Name: name, ...}
    if err := ValidateContactFormV2(req); err != nil {
        log.Printf("Valid name rejected: %s", name)
    }
}

Thread Safety

All validation functions are thread-safe:

// Safe for concurrent use
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
    wg.Add(1)
    go func() {
        defer wg.Done()
        err := ValidateContactFormV2(req)
        // Process err...
    }()
}
wg.Wait()

Architecture

validator.go      - Core reflection engine with caching
rules.go          - Built-in validation rules
errors.go         - Error types and helpers
contact.go        - Contact form struct and legacy functions
contact_test.go   - Legacy validation tests
validator_test.go - Struct tag validation tests

Design Principles

1. Performance First: Reflection caching, pre-compiled regex, minimal allocations
2. Security First: Defense in depth against injection attacks
3. Developer Experience: Clear error messages, type-safe APIs
4. Zero Dependencies: Pure Go stdlib for easy maintenance
5. Backward Compatible: Existing code continues to work
6. UTF-8 Aware: Proper international character support

Future Extensions

The validator can be extended with custom rules:

// Custom rule example (not yet implemented)
validationRules["custom"] = func(field, value, param string) *FieldError {
    // Your custom validation logic
    return nil
}

License

Part of the CV Site project - see project LICENSE file.