gott / gott.go

package gott

import (
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "errors"
    "html"
    "io/fs"
    "net/http"
    "net/url"
    "os"
    "os/signal"
    "path"
    "strings"
    "sync"
    "syscall"
)

// Renderer is the main template engine. It processes TT2-style templates
// with support for blocks, includes, filters, and virtual methods.
type Renderer struct {
    mu             sync.RWMutex
    includePaths   []fs.FS                                   // filesystems for INCLUDE lookups, searched in order
    filters        map[string]func(string, ...string) string // text transformation filters
    virtualMethods map[string]func(any) (any, bool)          // custom virtual methods for variables
    cache          *astCache                                 // in-memory LRU cache for parsed templates
    diskCache      *diskCache                                // optional disk-based cache (nil if not configured)
    stopSIGHUP     chan struct{}                             // channel to stop SIGHUP handler goroutine
}

// Config holds initialization options for creating a new Renderer.
type Config struct {
    IncludePaths []fs.FS                                   // filesystems for template includes (e.g., os.DirFS, embed.FS)
    Filters      map[string]func(string, ...string) string // custom filters to register
    CachePath    string                                    // directory for disk-based cache (optional, empty = memory only)
    MaxCacheSize int                                       // max entries in memory cache (0 = unlimited)
    EnableSIGHUP bool                                      // if true, clears cache on SIGHUP signal
}

var ErrTemplateNotFound = errors.New("template not found")
var ErrPathTraversal = errors.New("path traversal attempt detected")

// sanitizePath cleans a template path and ensures it cannot escape the include directories.
// It rejects any path containing ".." components to prevent directory traversal attacks.
// Leading slashes are stripped so paths are always relative to the configured IncludePaths.
func sanitizePath(name string) (string, error) {
    // Check for path traversal attempts BEFORE cleaning
    // This catches ".." even if path.Clean would normalize it away
    if strings.Contains(name, "..") {
        return "", ErrPathTraversal
    }

    // Clean the path to resolve any . or redundant separators
    cleaned := path.Clean(name)

    // Strip leading slash to make it relative
    cleaned = strings.TrimPrefix(cleaned, "/")

    // Reject empty paths
    if cleaned == "" || cleaned == "." {
        return "", ErrTemplateNotFound
    }

    return cleaned, nil
}

// New creates a Renderer with the given config. Registers default filters
// (upper, lower, html, uri) unless overridden in config.
// Returns an error if disk cache path is specified but cannot be created.
func New(config *Config) (*Renderer, error) {
    r := &Renderer{
        filters:        make(map[string]func(string, ...string) string),
        virtualMethods: make(map[string]func(any) (any, bool)),
    }

    maxCacheSize := 0
    if config != nil {
        r.includePaths = config.IncludePaths
        maxCacheSize = config.MaxCacheSize
        if config.Filters != nil {
            for k, v := range config.Filters {
                r.filters[k] = v
            }
        }

        // Initialize disk cache if path is specified
        if config.CachePath != "" {
            dc, err := newDiskCache(config.CachePath)
            if err != nil {
                return nil, err
            }
            r.diskCache = dc
        }

        // Set up SIGHUP handler if enabled
        if config.EnableSIGHUP {
            r.stopSIGHUP = make(chan struct{})
            go r.handleSIGHUP()
        }
    }

    // Initialize in-memory cache
    r.cache = newCache(maxCacheSize)

    // Default filters
    if r.filters["upper"] == nil {
        r.filters["upper"] = func(s string, args ...string) string {
            return strings.ToUpper(s)
        }
    }
    if r.filters["lower"] == nil {
        r.filters["lower"] = func(s string, args ...string) string {
            return strings.ToLower(s)
        }
    }
    if r.filters["html"] == nil {
        r.filters["html"] = func(s string, args ...string) string {
            return html.EscapeString(s)
        }
    }
    if r.filters["uri"] == nil {
        r.filters["uri"] = func(s string, args ...string) string {
            return url.QueryEscape(s)
        }
    }

    return r, nil
}

// handleSIGHUP listens for SIGHUP signals and clears the cache.
func (r *Renderer) handleSIGHUP() {
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGHUP)

    for {
        select {
        case <-sigChan:
            r.ClearCache()
        case <-r.stopSIGHUP:
            signal.Stop(sigChan)
            return
        }
    }
}

// ClearCache removes all entries from both memory and disk caches.
func (r *Renderer) ClearCache() {
    if r.cache != nil {
        r.cache.Clear()
    }
    if r.diskCache != nil {
        r.diskCache.Clear()
    }
}

// Close stops background goroutines and releases resources.
// Should be called when the Renderer is no longer needed.
func (r *Renderer) Close() {
    if r.stopSIGHUP != nil {
        close(r.stopSIGHUP)
    }
}

// AddFilter registers a custom filter function. Returns the Renderer for chaining.
// Note: This should only be called during initialization, not concurrently.
func (r *Renderer) AddFilter(name string, fn func(string, ...string) string) *Renderer {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.filters[name] = fn
    return r
}

// AddVirtualMethod registers a custom virtual method for variable access.
// The function receives a value and returns (result, ok).
// Note: This should only be called during initialization, not concurrently.
func (r *Renderer) AddVirtualMethod(name string, fn func(any) (any, bool)) *Renderer {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.virtualMethods[name] = fn
    return r
}

// getFilter safely retrieves a filter
func (r *Renderer) getFilter(name string) (func(string, ...string) string, bool) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    fn, ok := r.filters[name]
    return fn, ok
}

// getVirtualMethod safely retrieves a virtual method
func (r *Renderer) getVirtualMethod(name string) (func(any) (any, bool), bool) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    fn, ok := r.virtualMethods[name]
    return fn, ok
}

// loadFile attempts to load a template file from the configured filesystems.
// Searches each fs.FS in IncludePaths order, returning the first match.
// Returns ErrTemplateNotFound if not found in any filesystem.
// Returns ErrPathTraversal if the path attempts directory traversal.
func (r *Renderer) loadFile(name string) (string, error) {
    // Sanitize the path to prevent directory traversal attacks
    safeName, err := sanitizePath(name)
    if err != nil {
        return "", err
    }

    r.mu.RLock()
    paths := r.includePaths
    r.mu.RUnlock()

    for _, fsys := range paths {
        data, err := fs.ReadFile(fsys, safeName)
        if err == nil {
            return string(data), nil
        }
    }
    return "", ErrTemplateNotFound
}

// ProcessFile loads a template file and processes it with the given variables.
// Uses cached AST if available, otherwise parses and caches.
func (r *Renderer) ProcessFile(filename string, vars map[string]any) (string, error) {
    // Sanitize the path first to get a consistent cache key
    safeName, err := sanitizePath(filename)
    if err != nil {
        return "", err
    }

    // Use file path as cache key (prefixed to distinguish from content hashes)
    cacheKey := "file:" + safeName

    tmpl, err := r.getOrParseCached(cacheKey, func() (string, error) {
        return r.loadFile(filename)
    })
    if err != nil {
        return "", err
    }

    // Evaluate the AST
    eval := NewEvaluator(r, vars)
    return eval.Eval(tmpl)
}

// Process processes a template string with the given variables.
// Uses an AST-based parser and evaluator for template processing.
// Caches the parsed AST using a hash of the input content.
func (r *Renderer) Process(input string, vars map[string]any) (string, error) {
    // Use content hash as cache key
    cacheKey := "content:" + hashContent(input)

    tmpl, err := r.getOrParseCached(cacheKey, func() (string, error) {
        return input, nil
    })
    if err != nil {
        return "", err
    }

    // Evaluate the AST
    eval := NewEvaluator(r, vars)
    return eval.Eval(tmpl)
}

// hashContent creates a SHA256 hash of the template content for use as a cache key.
func hashContent(content string) string {
    h := sha256.Sum256([]byte(content))
    return hex.EncodeToString(h[:])
}

// getOrParseCached retrieves a cached template or parses and caches it.
// The loadContent function is called only if the template is not in cache.
func (r *Renderer) getOrParseCached(cacheKey string, loadContent func() (string, error)) (*Template, error) {
    // Check in-memory cache first
    if tmpl, ok := r.cache.Get(cacheKey); ok {
        return tmpl, nil
    }

    // Check disk cache if available
    if r.diskCache != nil {
        tmpl, err := r.diskCache.Get(cacheKey)
        if err != nil {
            return nil, err
        }
        if tmpl != nil {
            // Found on disk, add to memory cache
            r.cache.Put(cacheKey, tmpl)
            return tmpl, nil
        }
    }

    // Load and parse the template
    content, err := loadContent()
    if err != nil {
        return nil, err
    }

    parser := NewParser(content)
    tmpl, parseErrs := parser.Parse()
    if len(parseErrs) > 0 {
        return nil, parseErrs[0]
    }

    // Store in both caches
    r.cache.Put(cacheKey, tmpl)
    if r.diskCache != nil {
        // Best effort - don't fail if disk write fails
        r.diskCache.Put(cacheKey, tmpl)
    }

    return tmpl, nil
}

// parseTemplate parses a template for use by includes/wrappers with caching.
// This is used internally by the evaluator.
func (r *Renderer) parseTemplate(name string, content string) (*Template, error) {
    // Use the include/wrapper path as the cache key
    cacheKey := "file:" + name

    return r.getOrParseCached(cacheKey, func() (string, error) {
        return content, nil
    })
}

// Render processes a template file and writes the result to an http.ResponseWriter.
// Sets Content-Type to text/html and handles 400/404/500 errors appropriately.
func (r *Renderer) Render(w http.ResponseWriter, filename string, vars map[string]any) {
    output, err := r.ProcessFile(filename, vars)
    if err != nil {
        if errors.Is(err, ErrTemplateNotFound) {
            http.Error(w, "404 Not Found", http.StatusNotFound)
        } else if errors.Is(err, ErrPathTraversal) {
            http.Error(w, "400 Bad Request", http.StatusBadRequest)
        } else {
            http.Error(w, "500 Internal Server Error", http.StatusInternalServerError)
        }
        return
    }

    w.Header().Set("Content-Type", "text/html; charset=utf-8")
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(output))
}

// RenderWithStatus processes a template file and writes it with a custom status code.
func (r *Renderer) RenderWithStatus(w http.ResponseWriter, statusCode int, filename string, vars map[string]any) {
    output, err := r.ProcessFile(filename, vars)
    if err != nil {
        if errors.Is(err, ErrTemplateNotFound) {
            http.Error(w, "404 Not Found", http.StatusNotFound)
        } else if errors.Is(err, ErrPathTraversal) {
            http.Error(w, "400 Bad Request", http.StatusBadRequest)
        } else {
            http.Error(w, "500 Internal Server Error", http.StatusInternalServerError)
        }
        return
    }

    w.Header().Set("Content-Type", "text/html; charset=utf-8")
    w.WriteHeader(statusCode)
    w.Write([]byte(output))
}

// Render204 writes a 204 No Content response.
func (r *Renderer) Render204(w http.ResponseWriter) {
    w.WriteHeader(204)
    w.Write([]byte(""))
}

// RenderJSON serializes json_data to JSON and writes it to the http.ResponseWriter.
// Sets Content-Type to application/json. Returns 500 error on serialization failure.
func (r *Renderer) RenderJSON(w http.ResponseWriter, json_data any) {
    data, err := json.Marshal(json_data)
    if err != nil {
        http.Error(w, "500 Internal Server Error", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusOK)
    w.Write(data)
}

// RenderJSONWithStatus serializes json_data and writes it with a custom status code.
func (r *Renderer) RenderJSONWithStatus(w http.ResponseWriter, statusCode int, json_data any) {
    data, err := json.Marshal(json_data)
    if err != nil {
        http.Error(w, "500 Internal Server Error", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(statusCode)
    w.Write(data)
}