doc

Author: Pascal Minder

cachePersistence.go

@@ -3,6 +3,7 @@ package geoblock
 import (
 	"bytes"
 	"context"
+	"fmt"
 	"log"
 	"os"
 	"path/filepath"
@@ -12,26 +13,59 @@ import (
 	lru "github.com/PascalMinder/geoblock/lrucache"
 )
 
-func InitializeCache(ctx context.Context, logger *log.Logger, name string, cacheSize int, cachePath string) (*lru.LRUCache, *CachePersist) {
-	cache, err := lru.NewLRUCache(cacheSize)
+// Options configures cache initialization and persistence behavior.
+type Options struct {
+	// CacheSize specifies the number of entries to store in memory.
+	CacheSize int
+
+	// CachePath is the file path used for on-disk persistence.
+	// Leave empty to disable persistence.
+	CachePath string
+
+	// PersistInterval defines how often the cache is automatically
+	// flushed to disk. Defaults to 15 seconds if zero.
+	PersistInterval time.Duration
+
+	// Logger is used for diagnostic messages.
+	Logger *log.Logger
+
+	// Name is included in log messages to identify the cache instance.
+	Name string
+}
+
+// InitializeCache creates a new LRU cache and, if a valid persistence
+// path is provided, starts a background goroutine to periodically
+// save snapshots to disk.
+//
+// The returned `CachePersist` can be used to mark the cache as dirty when
+// data changes. If persistence is disabled, it is a no-op.
+//
+// Callers should cancel the provided context to stop persistence
+// and ensure a final snapshot is written.
+func InitializeCache(ctx context.Context, opts Options) (*lru.LRUCache, *CachePersist, error) {
+	if opts.PersistInterval <= 0 {
+		opts.PersistInterval = 15 * time.Second
+	}
+
+	cache, err := lru.NewLRUCache(opts.CacheSize)
 	if err != nil {
-		logger.Fatal(err)
+		return nil, nil, fmt.Errorf("create LRU cache: %w", err)
 	}
 
 	var ipDB *CachePersist // stays nil if disabled
-	if path, err := ValidatePersistencePath(cachePath); len(path) > 0 {
+	if path, err := ValidatePersistencePath(opts.CachePath); len(path) > 0 {
 		// load existing cache
 		if err := cache.ImportFromFile(path); err != nil && !os.IsNotExist(err) {
-			logger.Printf("%s: could not load IP DB snapshot (%s): %v", name, path, err)
+			opts.Logger.Printf("%s: could not load IP DB snapshot (%s): %v", opts.Name, path, err)
 		}
 
 		ipDB = &CachePersist{
 			path:           path,
 			persistTicker:  time.NewTicker(15 * time.Second),
 			persistChannel: make(chan struct{}, 1),
 			cache:          cache,
-			log:            logger,
-			name:           name,
+			log:            opts.Logger,
+			name:           opts.Name,
 		}
 
 		go func(ctx context.Context, p *CachePersist) {
@@ -49,16 +83,17 @@ func InitializeCache(ctx context.Context, logger *log.Logger, name string, cache
 			}
 		}(ctx, ipDB)
 
-		logger.Printf("%s: IP database persistence enabled -> %s", name, path)
+		opts.Logger.Printf("%s: IP database persistence enabled -> %s", opts.Name, path)
 	} else if err != nil {
-		logger.Printf("%s: IP database persistence disabled: %v", name, err)
+		opts.Logger.Printf("%s: IP database persistence disabled: %v", opts.Name, err)
 	} else {
-		logger.Printf("%s: IP database persistence disabled (no path)", name)
+		opts.Logger.Printf("%s: IP database persistence disabled (no path)", opts.Name)
 	}
 
-	return cache, ipDB
+	return cache, ipDB, nil
 }
 
+// CachePersist periodically snapshots a cache to disk.
 type CachePersist struct {
 	path           string
 	persistTicker  *time.Ticker
@@ -70,6 +105,7 @@ type CachePersist struct {
 	name  string
 }
 
+// MarkDirty marks the cache as modified and schedules a snapshot.
 func (p *CachePersist) MarkDirty() {
 	if p == nil { // feature OFF
 		return
@@ -81,6 +117,7 @@ func (p *CachePersist) MarkDirty() {
 	}
 }
 
+// Snapshot writes the cache to disk if it has been marked dirty.
 func (p *CachePersist) snapshotToDisk() {
 	if p == nil || atomic.LoadUint32(&p.ipDirty) == 0 {
 		return

geoblock.go

@@ -142,7 +142,17 @@ func New(ctx context.Context, next http.Handler, config *Config, name string) (h
 	}
 
 	// initialize local IP lookup cache
-	cache, ipDB := InitializeCache(ctx, infoLogger, name, config.CacheSize, config.IPDatabaseCachePath)
+	cacheOptions := Options{
+		CacheSize:       config.CacheSize,
+		CachePath:       config.IPDatabaseCachePath,
+		PersistInterval: 15 * time.Second,
+		Logger:          infoLogger,
+		Name:            name,
+	}
+	cache, ipDB, err := InitializeCache(ctx, cacheOptions)
+	if err != nil {
+		infoLogger.Fatal(err)
+	}
 
 	return &GeoBlock{
 		next:                         next,

logPersistence.go

@@ -7,41 +7,61 @@ import (
 	"os"
 )
 
+// CreateCustomLogTarget configures the provided logger to write to a custom
+// log file and automatically restores standard output when the given context
+// is canceled.
+//
+// It returns the opened *os.File handle, which is also closed automatically
+// when the context is done.
+//
+// If logFilePath is empty or invalid, the logger remains unchanged and no
+// file is created.
+//
+// The logger output will be reset to stdout when the context is canceled.
 func CreateCustomLogTarget(ctx context.Context, logger *log.Logger, name string, logFilePath string) (*os.File, error) {
-	logFile, err := initializeLogFile(logFilePath, logger)
+	logFile, err := openLogFile(logFilePath, logger)
 	if err != nil {
-		return nil, fmt.Errorf("error initializing log file: %v", err)
+		return nil, fmt.Errorf("initialize log file: %w", err)
 	}
 
-	// Set up a goroutine to close the file when the context is done
 	if logFile != nil {
 		go func(logger *log.Logger) {
-			<-ctx.Done() // Wait for context cancellation
+			<-ctx.Done()
 			logger.SetOutput(os.Stdout)
-			logFile.Close()
-			logger.Printf("%s: Log file closed for middleware\n", name)
+			if cerr := logFile.Close(); cerr != nil {
+				logger.Printf("%s: error closing log file: %v", name, cerr)
+			}
+			logger.Printf("%s: log file closed for middleware", name)
 		}(logger)
 	}
 
-	logger.Printf("%s: Log file opened for middleware\n", name)
+	logger.Printf("%s: log file opened for middleware", name)
 	return logFile, nil
 }
 
-func initializeLogFile(logFilePath string, logger *log.Logger) (*os.File, error) {
+// openLogFile validates the provided path and opens the target log file.
+//
+// If the path is empty, it returns (nil, nil).
+// If the folder is not writable or validation fails, an error is returned.
+//
+// The logger’s output is redirected to the newly opened file.
+// The caller is responsible for closing the returned file when done.
+func openLogFile(logFilePath string, logger *log.Logger) (*os.File, error) {
 	if len(logFilePath) == 0 {
 		return nil, nil
 	}
 
 	path, err := ValidatePersistencePath(logFilePath)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("validate persistence path: %w", err)
 	} else if len(path) == 0 {
-		return nil, fmt.Errorf("folder is not writeable (%s)", path)
+		return nil, fmt.Errorf("folder is not writable: %s", logFilePath)
 	}
 
+	const filePermissions = 0o600
 	logFile, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_APPEND, filePermissions)
 	if err != nil {
-		return nil, fmt.Errorf("failed to open log file (%s): %v", path, err)
+		return nil, fmt.Errorf("open log file %q: %w", path, err)
 	}
 
 	logger.SetOutput(logFile)