blitzkit

BlitzKit: High-Performance Go Web Framework Foundation

Repository: github.com/r-via/blitzkit

1. Overview

BlitzKit is a high-performance, reusable toolkit for building modern web applications in Go. Leveraging the speed and efficiency of the Fiber v2 web framework, BlitzKit provides a solid foundation by integrating essential features such as an intelligent L1/L2 caching system (in-memory & BadgerDB), optimized static asset processing, structured slog logging, and Prometheus monitoring capabilities.

Designed to be configurable yet "batteries-included" for core infrastructure, BlitzKit handles common web server complexities, allowing developers to focus on business logic and application-specific routing.

Key Features:

• Fiber v2 Core: Built on the fast and Express.js-inspired Fiber v2 framework.
• Hybrid L1/L2 Caching:
  • L1 Cache (In-Memory): patrickmn/go-cache for ultra-fast access to frequently used data.
  • L2 Cache (Disk-Persistent): dgraph-io/badger/v4 for persistent caching, complete with background garbage collection (GC).
  • Cache-Aware Rendering: RenderPage (for templ.Component or similar) and RenderBytesPage (for raw byte content like XML, JSON) methods to serve content through the cache.
• Programmatic Cache Control:
  • Invalidate(key string): Remove specific keys from L1 and L2 caches.
  • Flush(): Clear all data from both L1 and L2 caches (destructive).
• Cache Warmup:
  • RegisterForPageWarmup and RegisterForBytesWarmup to register content generator functions.
  • ExecuteWarmup to pre-populate L1/L2 caches on application startup, running concurrently.
• Static Asset Pipeline (StaticProcessor):
  • Automated CSS/JS minification (from SourcesDir) and static file copying (from StaticsDir) to a PublicDir during server initialization.
  • Powered by tdewolff/minify/v2.
  • Prioritizes .debug.js files in development mode for easier debugging.
• Integrated Observability:
  • Prometheus Metrics: Exposes detailed metrics via /metrics if Config.EnableMetrics is true (uses ansrivas/fiberprometheus/v2). Tracks Fiber requests, cache performance (hits, misses, sets, errors), warmup statistics, and page generation durations.
  • Health Check Endpoint: GET /health endpoint to verify server status and L2 cache (BadgerDB) readability.
• Structured Logging with slog:
  • Uses Go's standard log/slog for all internal logging.
  • Allows injection of a custom slog.Logger via Config.Logger.
  • Includes a detailed, structured request logging middleware.
• Centralized Error Handling:
  • A default Fiber ErrorHandler that logs errors and returns appropriate responses (HTML via Config.ErrorComponentGenerator or JSON based on Accept header).
• Flexible Configuration:
  • Comprehensive Config struct for fine-grained control.
  • Overrides for key settings via standard environment variables (e.g., PORT, CACHE_L1_DEFAULT_TTL).
• Startup Validation: Rigorous checks for critical directory paths and permissions.
• Utilities: Helper functions for sitemap XML generation (GenerateSitemapXMLBytes), client IP extraction, default value handling, and more.

2. Getting Started

2.1 Prerequisites

• Go 1.21 or newer installed.
• A Go project initialized (go mod init yourproject).
• (Optional) Templ CLI installed if you are using Templ for HTML generation: go install github.com/a-h/templ/cmd/templ@latest.

2.2 Installation

Install BlitzKit into your project:

go get github.com/r-via/blitzkit@v0.1.4 # Or your desired version
go mod tidy

2.3 Minimal main.go Example

This example demonstrates basic server setup, a cached HTML page, a cached XML sitemap, static file serving, and graceful shutdown.

package main

import (
	"fmt"
	"log/slog"
	"os"
	"os/signal"
	"syscall"
	"time"

	// Assuming you have a 'views' package generated by Templ (or similar)
	"yourproject/views" // Replace with your actual views package path

	"github.com/a-h/templ"
	"github.com/gofiber/fiber/v2"
	"github.com/gofiber/fiber/v2/middleware/csrf"    // For CSRF protection
	"github.com/gofiber/fiber/v2/middleware/limiter" // For Rate Limiting

	"github.com/r-via/blitzkit" // Import BlitzKit directly
)

// --- Page Generators ---

// HomePageGenerator creates the home page component.
func HomePageGenerator(server *blitzkit.Server, title string) blitzkit.PageGeneratorFunc {
	return func() (templ.Component, int64, error) {
		server.GetLogger().Info("Generating component for home page", "title", title)
		// In a real app, you might fetch data here.
		// For Templ, ensure views.HomePage exists and takes a string.
		return views.HomePage(title), time.Now().Unix(), nil
	}
}

// SitemapGenerator creates the sitemap.xml content.
func SitemapGenerator(server *blitzkit.Server) blitzkit.BytesGeneratorFunc {
	return func() ([]byte, int64, error) {
		server.GetLogger().Info("Generating sitemap.xml")
		now := time.Now()
		entries := []blitzkit.SitemapEntry{ // Assuming SitemapEntry is part of the blitzkit package
			{URL: "https://example.com/", LastMod: &now, ChangeFreq: blitzkit.SitemapChangeFreqDaily, Priority: 1.0},
			{URL: "https://example.com/about", LastMod: &now, ChangeFreq: blitzkit.SitemapChangeFreqMonthly, Priority: 0.8},
			// Add more entries dynamically based on your content
		}
		xmlBytes, err := blitzkit.GenerateSitemapXMLBytes(entries)
		return xmlBytes, now.Unix(), err
	}
}

// ErrorPageGenerator creates a custom error page component.
func CustomErrorComponentGenerator(isDevMode bool) blitzkit.ErrorComponentGenerator {
	return func(err error, code int, isDev bool) templ.Component {
		errMsg := "An unexpected error occurred."
		if fe, ok := err.(*fiber.Error); ok {
			errMsg = fe.Message
		} else if isDevMode { // Only show detailed error in dev mode
			errMsg = err.Error()
		}

		if !isDevMode && code >= 500 {
			errMsg = "Internal Server Error. Please try again later."
		}
		// Ensure views.ErrorPage exists and takes these parameters.
		return views.ErrorPage(fmt.Sprintf("Error %d", code), errMsg, isDev)
	}
}

// --- HTTP Handlers (using Fiber's standard signature) ---

// homeHandler serves the home page using BlitzKit's cached rendering.
func homeHandler(server *blitzkit.Server) fiber.Handler {
	return func(c *fiber.Ctx) error {
		cacheKey := "home"
		// Use a default TTL from config (IsInfinite: false)
		return server.RenderPage(c, cacheKey, blitzkit.CacheTTLInfo{IsInfinite: false},
			HomePageGenerator(server, "Welcome to BlitzKit!"))
	}
}

// sitemapHandler serves the sitemap.xml using BlitzKit's cached byte rendering.
func sitemapHandler(server *blitzkit.Server) fiber.Handler {
	return func(c *fiber.Ctx) error {
		cacheKey := "sitemap.xml"
		contentType := fiber.MIMEApplicationXMLCharsetUTF8 // Use Fiber's constants
		// Sitemap changes infrequently, good candidate for effectively infinite cache
		return server.RenderBytesPage(c, cacheKey, contentType, blitzkit.CacheTTLInfo{IsInfinite: true},
			SitemapGenerator(server))
	}
}

// adminInvalidateCacheHandler (example for programmatic cache invalidation)
// IMPORTANT: This endpoint MUST be secured in a real application (e.g., auth middleware).
func adminInvalidateCacheHandler(server *blitzkit.Server) fiber.Handler {
	return func(c *fiber.Ctx) error {
		keyToInvalidate := c.Query("key")
		if keyToInvalidate == "" {
			return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "Missing 'key' query parameter"})
		}

		if err := server.Invalidate(keyToInvalidate); err != nil {
			server.GetLogger().Error("Failed to invalidate cache", "key", keyToInvalidate, "error", err)
			return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "Cache invalidation failed"})
		}
		server.GetLogger().Info("Cache invalidated successfully", "key", keyToInvalidate)
		return c.JSON(fiber.Map{"message": fmt.Sprintf("Cache key '%s' invalidated", keyToInvalidate)})
	}
}

// notFoundHandler serves a custom 404 page.
func notFoundHandler(server *blitzkit.Server) fiber.Handler {
	return func(c *fiber.Ctx) error {
		// The default ErrorHandler in BlitzKit will try to use ErrorComponentGenerator
		// if the error is a fiber.Error with status 404.
		// So, we just need to return the fiber.ErrNotFound.
		return fiber.ErrNotFound // This will be caught by server.handleError
	}
}

func main() {
	// --- 1. Logger Setup ---
	isDev := os.Getenv("APP_ENV") == "development"
	logLevel := slog.LevelInfo
	if isDev {
		logLevel = slog.LevelDebug
	}
	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
		Level:     logLevel,
		AddSource: isDev, // Adds source file:line in dev logs
	}))
	slog.SetDefault(logger) // Optional: set as global default logger

	// --- 2. Configuration ---
	cfg := blitzkit.Config{
		Port:              blitzkit.GetEnvOrDefault(logger, "PORT", "", "8080"),
		DevMode:           isDev,
		Logger:            logger, // Inject our configured logger
		SourcesDir:        "./webroot/sources",   // CSS/JS source files for minification
		StaticsDir:        "./webroot/statics",   // Static assets like images, fonts
		PublicDir:         "./webroot/public",    // Output directory for processed & served assets
		CacheDir:          "./runtime/cache",     // Directory for L2 BadgerDB cache
		ReadTimeout:       30 * time.Second,
		WriteTimeout:      30 * time.Second,
		IdleTimeout:       60 * time.Second,
		EnableMetrics:     true, // Enable /metrics endpoint
		CacheL1DefaultTTL: 10 * time.Minute,
		CacheL2DefaultTTL: 24 * time.Hour,
		BadgerGCInterval:  1 * time.Hour,
		WarmupConcurrency: 4,      // Max goroutines for cache warmup
		SecurityHeaders: map[string]string{ // Basic security headers
			"X-Frame-Options":           "DENY",
			"X-Content-Type-Options":    "nosniff",
			"Referrer-Policy":           "strict-origin-when-cross-origin",
			"Strict-Transport-Security": "max-age=31536000; includeSubDomains", // Use HSTS with caution!
			// "Content-Security-Policy": "default-src 'self';", // Example CSP (adapt carefully!)
		},
		// CSRF Configuration (used if you enable the CSRF middleware)
		EnableCSRF:         true, // Flag to indicate intent; middleware must be added manually
		CSRFKeyLookup:      "header:X-CSRF-Token, form:_csrf",
		CSRFCookieName:     "__Host-csrf", // Use __Host- prefix for security if served over HTTPS
		CSRFExpiration:     12 * time.Hour,
		CSRFCookieSameSite: "Lax", // Or "Strict"
		// Rate Limiter Configuration (used if you enable the Limiter middleware)
		EnableRateLimiter:     true, // Flag to indicate intent
		RateLimiterMax:        100,  // Max requests per window per IP
		RateLimiterExpiration: 1 * time.Minute,
		// Custom Error Page Renderer
		ErrorComponentGenerator: CustomErrorComponentGenerator(isDev),
	}

	// --- 3. Server Initialization ---
	server, err := blitzkit.NewServer(cfg)
	if err != nil {
		logger.Error("Failed to initialize BlitzKit server", "error", err)
		os.Exit(1)
	}

	app := server.App() // Get the underlying Fiber app instance

	// --- 4. Configure Middlewares (e.g., CSRF, Rate Limiter) ---
	// These are added manually using the configuration from `cfg`.
	// BlitzKit's base middlewares (recover, CORS, request logging, security headers) are already set up.
	if cfg.EnableCSRF {
		app.Use(csrf.New(csrf.Config{
			KeyLookup:      cfg.CSRFKeyLookup,
			CookieName:     cfg.CSRFCookieName,
			CookieSameSite: cfg.CSRFCookieSameSite,
			Expiration:     cfg.CSRFExpiration,
			// Next: func(c *fiber.Ctx) bool {
			//  // Example: skip CSRF for API routes
			// 	return strings.HasPrefix(c.Path(), "/api/")
			// },
			ContextKey: blitzkit.CSRFContextKey, // Makes CSRF token available via c.Locals(blitzkit.CSRFContextKey)
		}))
		logger.Info("CSRF Protection Middleware enabled.")
	}

	if cfg.EnableRateLimiter {
		app.Use(limiter.New(limiter.Config{
			Max:        cfg.RateLimiterMax,
			Expiration: cfg.RateLimiterExpiration,
			KeyGenerator: func(c *fiber.Ctx) string {
				return blitzkit.GetClientIP(c.Get(fiber.HeaderXForwardedFor), c.IP())
			},
			// LimitReached: func(c *fiber.Ctx) error {
			// 	 return c.Status(fiber.StatusTooManyRequests).JSON(fiber.Map{"error": "Too many requests"})
			// },
		}))
		logger.Info("Rate Limiting Middleware enabled.")
	}

	// --- 5. Define Application Routes ---
	app.Get("/", homeHandler(server))
	app.Get("/sitemap.xml", sitemapHandler(server))

	// Example POST route (CSRF token would be required if CSRF middleware is active)
	app.Post("/form-submit", func(c *fiber.Ctx) error {
		// CSRF middleware (if enabled) handles validation automatically.
		// Your form processing logic here...
		return c.SendString("Form submitted successfully!")
	})

	// Admin/Protected route for cache invalidation (example)
	// In a real app, add authentication/authorization middleware here
	adminRoutes := app.Group("/admin") // Create a group for admin routes
	// adminRoutes.Use(yourAuthMiddleware) // Apply auth middleware
	adminRoutes.Post("/cache/invalidate", adminInvalidateCacheHandler(server))
	adminRoutes.Post("/cache/flush", func(c *fiber.Ctx) error { // Example flush route
		// server.Flush() // Call this carefully!
		return c.SendString("Cache flush endpoint (implement with caution and security)")
	})


	// --- 6. Register Static File Middleware ---
	// This serves files from `cfg.PublicDir`.
	// It's often placed after application routes unless specific prefix overlaps are desired.
	if cfg.PublicDir != "" {
		app.Static("/", cfg.PublicDir, fiber.Static{
			Compress:      true,
			ByteRange:     true, // Enable byte range requests for seeking in media files
			Browse:        false, // Disable directory browsing for security
			CacheDuration: 24 * time.Hour, // Example browser cache duration for static assets
			MaxAge:        int((24 * time.Hour).Seconds()), // For Cache-Control header
		})
		logger.Info("Static file middleware enabled", "serving_from", cfg.PublicDir)
	}

	// --- 7. Cache Warmup (Optional) ---
	// Register items for warmup
	server.RegisterForPageWarmup("home", blitzkit.CacheTTLInfo{IsInfinite: false},
		HomePageGenerator(server, "Welcome! (Warmed Up)"))
	server.RegisterForBytesWarmup("sitemap.xml", blitzkit.CacheTTLInfo{IsInfinite: true},
		SitemapGenerator(server))

	// Execute warmup in a goroutine to avoid blocking server startup
	go func() {
		logger.Info("Starting cache warmup process...")
		if err := server.ExecuteWarmup(); err != nil {
			logger.Error("Cache warmup process failed", "error", err)
		} else {
			logger.Info("Cache warmup process finished successfully.")
		}
	}()

	// --- 8. Register 404 Not Found Handler (Must be the last middleware/handler) ---
	app.Use(notFoundHandler(server))

	// --- 9. Start Server and Handle Graceful Shutdown ---
	go func() {
		logger.Info("Starting BlitzKit server...", "address", fmt.Sprintf(":%s", cfg.Port))
		if err := server.Start(); err != nil {
			// http.ErrServerClosed is expected on graceful shutdown
			if err.Error() != "http: Server closed" {
				logger.Error("Server failed to start or stopped unexpectedly", "error", err)
				// Consider a mechanism to signal the main goroutine to exit if startup fails critically
			}
		}
	}()

	// Wait for interrupt signal to gracefully shut down the server
	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	<-quit // Block until a signal is received

	logger.Info("Shutdown signal received. Shutting down BlitzKit server gracefully...")

	// Perform server shutdown (closes Fiber app & L2 cache)
	// shutdownTimeout := 30 * time.Second // server.Shutdown() already has an internal timeout
	if err := server.Shutdown(); err != nil {
		logger.Error("Server shutdown failed", "error", err)
		os.Exit(1) // Exit with an error code
	}

	logger.Info("Server shutdown complete.")
}

3. Configuration (blitzkit.Config)

The blitzkit.Config struct allows fine-grained control over the server's behavior.

Environment Variables: BlitzKit recognizes these environment variables to override Config defaults (see NewServer and utils.go for parsing logic):

• PORT
• APP_ENV (set to "development" for DevMode)
• CACHE_L1_DEFAULT_TTL (e.g., "15m", "1h")
• CACHE_L2_DEFAULT_TTL
• BADGER_GC_INTERVAL
• CACHE_L1_CLEANUP_INTERVAL (default 10m used by NewCache internally if not overridden)
• CORS_ALLOW_ORIGINS (comma-separated list, e.g., "http://localhost:3000,https://app.example.com")

4. Core Components & API

4.1 Server Lifecycle

• blitzkit.NewServer(cfg Config) (*Server, error): Initializes and returns a new *Server instance. This is the primary entry point. It sets up logging, caching, static processing, base middlewares, and monitoring.
• (*Server) App() *fiber.App: Returns the underlying *fiber.App instance. Use this to register your application routes, specific middlewares, etc.
• (*Server) Start() error: Starts the Fiber HTTP server. This is a blocking call.
• (*Server) Shutdown() error: Initiates a graceful shutdown of the Fiber server and closes the L2 cache.

4.2 Caching System

The caching system is a core part of BlitzKit, designed for performance.

• CacheEntry struct: Defines the structure stored in L1/L2 cache (Data []byte, LastModified int64, ExpiresAt int64).
• CacheTTLInfo struct: (IsInfinite bool) Specifies if a cache entry should have an "infinite" TTL (no time-based expiration, relying on manual invalidation or L1/L2 eviction policies). If false, CacheL1DefaultTTL and CacheL2DefaultTTL are used.

Rendering with Cache:

• (*Server) RenderPage(ctx *fiber.Ctx, key string, ttlInfo CacheTTLInfo, generatorFunc PageGeneratorFunc) error
  • Renders HTML content (typically from a templ.Component via the PageGeneratorFunc) using the L1/L2 cache.
  • PageGeneratorFunc: func() (page templ.Component, lastModified int64, err error)
  • Handles cache lookup (L1 -> L2), content generation on miss, and storing in both caches.
  • Sets Content-Type: text/html; charset=utf-8 and X-Cache-Status header.
• (*Server) RenderBytesPage(ctx *fiber.Ctx, key string, contentType string, ttlInfo CacheTTLInfo, generatorFunc BytesGeneratorFunc) error
  • Similar to RenderPage but for raw []byte content (e.g., XML, JSON).
  • BytesGeneratorFunc: func() (data []byte, lastModified int64, err error)
  • Sets the provided contentType and X-Cache-Status header.

Manual Cache Management:

• (*Server) Invalidate(key string) error: Removes a specific key from both L1 and L2 caches. Logs the operation and increments Prometheus counters.
• (*Server) Flush() error: Destructive operation. Clears all items from the L1 cache and drops all data from the L2 BadgerDB store. Use with caution.

Cache Warmup:

• (*Server) RegisterForPageWarmup(key string, ttlInfo CacheTTLInfo, generator PageGeneratorFunc): Registers a PageGeneratorFunc for cache warmup.
• (*Server) RegisterForBytesWarmup(key string, ttlInfo CacheTTLInfo, generator BytesGeneratorFunc): Registers a BytesGeneratorFunc for cache warmup.
• (*Server) ExecuteWarmup() error: Executes the warmup process for all registered items. It generates content (if not already in L1) and stores it in L1 and L2 caches. Runs concurrently based on Config.WarmupConcurrency. Logs progress and errors, updates Prometheus metrics.

4.3 Static Asset Processing (StaticProcessor)

Executed once during NewServer initialization:

1. Purges Config.PublicDir: Removes the existing public directory and recreates it.
2. Minifies Sources: Iterates through Config.SourcesDir.
   • Minifies .css and .js files using tdewolff/minify/v2.
   • If Config.DevMode is true, .debug.js files are prioritized over regular .js files for the same base name (e.g., script.debug.js over script.js).
   • Writes minified output to Config.PublicDir, preserving relative subdirectory structure.
3. Copies Statics: Recursively copies all files and directories from Config.StaticsDir to Config.PublicDir.

Your application should then serve static files from Config.PublicDir using Fiber's app.Static("/", cfg.PublicDir) middleware.

4.4 Error Handling

• BlitzKit sets up a default error handler (server.handleError) for the Fiber application.
• It intercepts errors returned by handlers or from c.Next(err).
• Logic:
  1. Determines HTTP status code (defaults to 500, uses fiber.Error.Code if available).
  2. Logs the error with request details (path, method, IP, original error).
  3. Sets the response status code.
  4. Response Formatting:
     • If blitzkit.WantsJSON(c) is true (client Accept header contains application/json): Sends a JSON response: {"error": "message"}. In DevMode, internal error details might be included.
     • Else, if Config.ErrorComponentGenerator is provided: Attempts to render the templ.Component returned by this generator.
     • Else (fallback): Sends a plain text response: <code>: <message>.
     • In production (!DevMode), 5xx error messages are generic ("Internal Server Error").
• blitzkit.ErrorComponentGenerator type: func(err error, code int, isDev bool) templ.Component. Allows you to provide a function that generates a templ.Component for displaying error pages.

4.5 Middlewares

Base Middlewares (Applied Automatically by NewServer):

• Recovery: github.com/gofiber/fiber/v2/middleware/recover. Stack traces enabled in DevMode.
• CORS: github.com/gofiber/fiber/v2/middleware/cors. Configured using CORS_ALLOW_ORIGINS environment variable. Strict in production regarding * with credentials.
• Security Headers: A custom middleware applies headers defined in Config.SecurityHeaders.
• Request Logging: server.logRequests provides structured slog logs for each request (method, path, status, duration, IP, response size, user-agent, request ID, cache status).
• Custom Middlewares: Any fiber.Handlers provided in Config.CustomMiddlewares are added.

Optional Middlewares (Manual Setup Required by User):

• CSRF Protection: If Config.EnableCSRF is true, you should add Fiber's CSRF middleware using settings from Config (e.g., CSRFKeyLookup, CSRFCookieName). Use blitzkit.CSRFContextKey ("csrf") as the ContextKey in csrf.Config to make the token accessible via c.Locals(blitzkit.CSRFContextKey).
• Rate Limiting: If Config.EnableRateLimiter is true, add Fiber's Limiter middleware using settings from Config (e.g., RateLimiterMax, RateLimiterExpiration).

4.6 Monitoring

• Prometheus Metrics (Config.EnableMetrics: true):
  • Endpoint: /metrics.
  • Uses github.com/ansrivas/fiberprometheus/v2 for Fiber metrics.
  • Custom BlitzKit metrics (see monitoring.go for full list, prefixed with blitzkit_):
    • Cache L1/L2: hits, misses, sets, l1_loaded_from_l2, l2_set_errors.
    • Invalidation: invalidations_total, invalidation_errors_total.
    • Warmup: warmup_skipped_total, warmup_errors_total, warmup_item_duration_seconds (histogram), warmup_total_duration_seconds (gauge).
    • Page Generation: page_generation_duration_seconds (histogram vec, labeled by cache_key).
• Health Check Endpoint (GET /health):
  • Always enabled.
  • Checks basic server responsiveness.
  • If Config.CacheDir (L2 cache) is configured, performs a quick read check on BadgerDB.
  • Returns JSON: {"status": "ok|error", "l2_cache": "ok|unhealthy|unavailable", "l2_cache_error": "details if unhealthy"}.
  • HTTP Status: 200 OK if all checks pass, 503 Service Unavailable if a critical component (like L2 cache) fails.

4.7 Utilities

• blitzkit.SitemapEntry struct & blitzkit.GenerateSitemapXMLBytes([]SitemapEntry) ([]byte, error): For creating sitemap.xml content.
• blitzkit.GetClientIP(xForwardedFor, remoteAddr string) string: Extracts client IP, prioritizing X-Forwarded-For.
• blitzkit.WantsJSON(c *fiber.Ctx) bool: Checks if the request Accept header prefers JSON.
• blitzkit.GetEnvOrDefault(logger *slog.Logger, key, configValue, defaultValue string) string: Utility to fetch environment variables with fallbacks.
• Other helpers in utils.go for directory management (ensureDirExists, checkDirWritable), default values (defaultDuration, defaultInt), and duration parsing (parseDurationEnv).

5. Advanced Usage & Internals

5.1 Cache Workflow (RenderPage / RenderBytesPage)

1. HTTP Request arrives -> Fiber processes base middlewares.
2. User-defined middlewares (CSRF, Limiter, etc.) run.
3. Fiber routes to your application handler.
4. Handler calls server.RenderPage(...) or server.RenderBytesPage(...).
5. L1 Cache Lookup:
   • Hit: Content served from L1. X-Cache-Status: HIT-L1. Metrics updated. Request ends.
   • Miss: Proceed to L2. Metrics updated.
6. L2 Cache Lookup:
   • Hit (Valid & Unmarshaled): Content served from L2. Content is promoted to L1. X-Cache-Status: HIT-L2. Metrics updated. Request ends.
   • Miss / Expired / Unmarshal Error: Proceed to generation. Metrics updated.
7. Content Generation: The provided PageGeneratorFunc or BytesGeneratorFunc is executed.
   • For PageGeneratorFunc, the templ.Component is rendered to []byte.
   • Duration is measured and recorded (Prometheus metric).
8. Store in Cache:
   • Generated content is stored in L1 (with L1 TTL or no expiration). Metrics updated.
   • Generated content (as CacheEntry) is marshaled to JSON and stored in L2 (with L2 TTL or no expiration). Metrics updated.
9. Serve Generated Content: X-Cache-Status: MISS. Request ends.

5.2 BadgerDB L2 Cache GC

• If Config.BadgerGCInterval is positive, a background goroutine (runBadgerGC) periodically runs L2.RunValueLogGC(Config.BadgerGCDiscardRatio).
• This helps reclaim disk space in BadgerDB. It stops gracefully on server shutdown.

6. Best Practices

• Fiber Handlers: Use the standard func(c *fiber.Ctx) error signature for your route handlers.
• Cache Keys: Use unique, descriptive, and consistent cache keys. Consider namespacing (e.g., "page:/about", "data:user:123").
• CacheTTLInfo: Use IsInfinite: true for content that rarely changes or is invalidated manually (e.g., sitemaps, global configuration data). Use false (with appropriate CacheL1/L2DefaultTTL) for dynamic content that benefits from temporary caching.
• Generator Functions: Keep them focused on data fetching and content creation. Log within them if necessary. They should be idempotent if possible.
• Selective Warmup: Only warmup critical or frequently accessed pages/resources to avoid excessive startup load.
• Configuration: Prefer environment variables for deployment-specific settings (port, TTLs, secrets). Use the Config struct for application defaults and structural configuration.
• Middleware Order: Remember that middleware order is crucial in Fiber. Typically, your 404 handler and app.Static middleware should be registered last.
• Security for Cache Control: If you expose endpoints to trigger server.Invalidate() or server.Flush() (e.g., for admin purposes), these endpoints MUST be strongly secured with authentication and authorization.

7. Troubleshooting

• "Directory not writable" errors at startup: Check permissions for Config.CacheDir and Config.PublicDir. The server process needs write access.
• Static Assets Not Found (404):
  • Ensure app.Static("/", cfg.PublicDir) is correctly configured and typically called after specific application routes that might share URL prefixes.
  • Verify the contents of Config.PublicDir after server startup to confirm assets were processed.
  • Check that the requested URL doesn't match any fiber.Static exclusion patterns if you've configured them.
• Cache Not Invalidating / Stale Content:
  • Verify configured TTLs (CacheL1DefaultTTL, CacheL2DefaultTTL) and the IsInfinite flag used during RenderPage/RenderBytesPage or warmup registration.
  • Check server logs for L2 cache errors (Prometheus metric blitzkit_cache_l2_set_errors_total can also indicate issues).
  • When using server.Invalidate(key), ensure the key exactly matches the one used for caching.
• CSRF Issues (if manually enabled):
  • Double-check your csrf.Config settings against Config values from BlitzKit.
  • Ensure your frontend is sending the CSRF token correctly (matching CSRFKeyLookup).
  • Use browser developer tools to inspect cookies (CSRFCookieName) and request headers/form data.
• 503 Errors / Health Check Fails: Check server logs for BadgerDB errors. Ensure Config.CacheDir is accessible and not corrupted.

8. Potential Roadmap / Future Enhancements

• Automatic cache busting for static assets (e.g., appending content hashes to filenames).
• More granular cache TTL options (e.g., per-key prefix or as an option to render methods).
• OpenTelemetry integration for distributed tracing.
• Allow applications to register custom health checks.
• Further improvements to StaticProcessor (e.g., option not to purge PublicDir, support for SASS/TypeScript pre-processing).