srv

srv - HTTP Server Utilities

The srv package provides comprehensive HTTP server utilities for Go applications, including middleware support, graceful shutdown, HTTP context abstraction, and enhanced routing capabilities.

Features

• 🛠️ HTTP Context: Convenient request/response wrapper with value storage
• 📦 Request Parsing: Universal parsing of JSON, form data, and query parameters with struct tags and custom type support
• 🔀 Enhanced Router: Extended ServeMux with RESTful HTTP method helpers
• 🔄 URL Reversing: Named routes with automatic URL generation and parameter substitution
• 🔗 Middleware System: Composable HTTP middleware with easy chaining
• 📊 Built-in Middleware: Logging, panic recovery, CORS, trailing slash, and session management included
• 🍪 Session Stores: In-memory and encrypted cookie-based session storage options
• 🛑 Graceful Shutdown: HTTP server with signal-based graceful shutdown
• 📝 Structured Logging: Integration with Go's structured logging (log/slog)
• 🔗 ERM Integration: Uses the erm package for standardized error handling and HTTP status codes
• ⚡ Minimal Dependencies: Uses Go standard library plus c3p0-box/utils/erm for errors

Installation

go get github.com/c3p0-box/utils/srv

Quick Start

package main

import (
    "crypto/rand"
    "errors"
    "log"
    "github.com/c3p0-box/utils/srv"
    "github.com/c3p0-box/utils/erm"
)

func main() {
    // Create enhanced router with error handling
    mux := srv.NewMux()
    
    // Add encrypted session middleware (for stateless apps)
    key := make([]byte, 32) // AES-256 key
    if _, err := rand.Read(key); err != nil {
        log.Fatal(err)
    }
    store, err := srv.NewCookieStore("app-session", key, srv.NewOptions())
    if err != nil {
        log.Fatal(err)
    }
    mux.Middleware(srv.SessionMiddleware(store, "app-session"))
    
    // Alternative: In-memory session store (for single-instance apps)
    // store := srv.NewInMemoryStore("app-session", srv.NewOptions())
    // defer store.Close()
    // mux.Middleware(srv.SessionMiddleware(store, "app-session"))
    
    // Add named routes for URL generation
    mux.Get("users", "/users", func(ctx srv.Context) error {
        // Generate URL to create user endpoint
        createURL, _ := mux.Reverse("users", nil)
        return ctx.JSON(200, map[string]interface{}{
            "message": "Users list",
            "create_url": createURL,
        })
    })
    
    mux.Post("users", "/users", func(ctx srv.Context) error {
        name := ctx.FormValue("name")
        if name == "" {
            return errors.New("name is required")  // Error handled automatically
        }
        // Generate URL to view the created user
        userURL, _ := mux.Reverse("user", map[string]string{"id": "123"})
        return ctx.JSON(201, map[string]interface{}{
            "created": name,
            "user_url": userURL,
        })
    })
    
    mux.Get("user", "/users/{id}", func(ctx srv.Context) error {
        return ctx.JSON(200, map[string]string{"id": ctx.Param("id")})
    })
    
    // Set custom error handler with erm integration (optional)
    mux.ErrorHandler(func(ctx srv.Context, err error) {
        log.Printf("Handler error: %v", err)
        // erm errors provide proper HTTP status codes
        status := erm.Status(err)  // Extract HTTP status from erm error
        message := erm.Message(err) // Get user-safe message
        ctx.JSON(status, map[string]string{"error": message})
    })
    
    // Add middleware
    mux.Middleware(srv.LoggingMiddleware)
    mux.Middleware(srv.RecoverMiddleware)
    
    // Run server with graceful shutdown
    err := srv.RunServer(mux, "localhost", "8080", func() error {
        log.Println("Cleaning up...")
        return nil
    })
    
    if err != nil {
        log.Fatal(err)
    }
}

API Reference

🛠️ HttpContext - Request/Response Wrapper

Overview

HttpContext provides a convenient wrapper around http.Request and http.ResponseWriter with additional functionality for value storage, parameter handling, and response generation.

Constructor

func NewHttpContext(w http.ResponseWriter, r *http.Request) *HttpContext

Value Store (Thread-Safe)

ctx.Set("user", userObj)           // Store value
user := ctx.Get("user")            // Retrieve value

Request Information

method := ctx.Method()             // HTTP method: "GET", "POST", etc.
path := ctx.Path()                 // URL path: "/api/users"
isTLS := ctx.IsTLS()              // true for HTTPS requests
isWS := ctx.IsWebSocket()         // true for WebSocket upgrades

Parameters & Headers

// Query parameters
name := ctx.QueryParam("name")     // Single query parameter
query := ctx.Query()               // All query parameters

// Path parameters (Go 1.22+ ServeMux)
id := ctx.Param("id")              // Path parameter: /users/{id}

// Form data
username := ctx.FormValue("username")

// Headers
auth := ctx.GetHeader("Authorization")
ctx.SetHeader("Content-Type", "application/json")
ctx.AddHeader("X-Custom", "value")

Cookies

// Read cookies
cookie, err := ctx.Cookie("session")
allCookies := ctx.Cookies()

// Set cookies
ctx.SetCookie(&http.Cookie{
    Name:  "session",
    Value: "abc123",
    Path:  "/",
})

Response Methods

// JSON response (with error handling)
err := ctx.JSON(200, data)

// Text response
err := ctx.String(200, "Hello, World!")

// HTML response
err := ctx.HTML(200, "<h1>Welcome</h1>")

// HTML Blob response
err := ctx.HTMLBlob(200, []byte("<h1>Welcome</h1>"))

// Redirects
ctx.Redirect(302, "/login")

// Custom status code
ctx.WriteHeader(204)

📦 ParseRequest - Universal Request Parsing

Overview

ParseRequest provides unified parsing of HTTP request data, automatically handling both request body content (JSON, form data, multipart forms) and URL query parameters. It uses struct tags to map data to Go structs with proper type conversion and error handling.

Function Signature

func ParseRequest(r *http.Request, target interface{}) erm.Error

Supported Features

Content Types:

• application/json - JSON payload parsing
• application/x-www-form-urlencoded - HTML form data
• multipart/form-data - File uploads and form data
• Query parameters (always parsed regardless of Content-Type)

Struct Tags:

• json:"field_name" - Maps JSON fields
• form:"field_name" - Maps form data fields
• query:"field_name" - Maps URL query parameters

Supported Types:

• string, int, int8, int16, int32, int64
• uint, uint8, uint16, uint32, uint64
• float32, float64, bool
• Custom types implementing encoding.TextUnmarshaler interface

Basic Usage

// Custom type example
type UserID [16]byte

func (u *UserID) UnmarshalText(text []byte) error {
    if len(text) != 32 {
        return fmt.Errorf("invalid UserID length")
    }
    _, err := hex.Decode(u[:], text)
    return err
}

type UserRequest struct {
    // JSON/Form body fields
    Name     string  `json:"name" form:"name"`
    Email    string  `json:"email" form:"email"`
    Age      int     `json:"age" form:"age"`
    Active   bool    `json:"active" form:"active"`
    
    // Query parameters (including custom types)
    ID       UserID  `query:"user_id"`    // Custom type with TextUnmarshaler
    Page     int     `query:"page"`
    Sort     string  `query:"sort"`
    Limit    int     `query:"limit"`
    Debug    bool    `query:"debug"`
}

// Handler function
func createUser(ctx *srv.HttpContext) error {
    var req UserRequest
    if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
        return err  // Error handled automatically
    }
    
    // Use both body data and query parameters
    log.Printf("Creating user: %s (page=%d, sort=%s)", req.Name, req.Page, req.Sort)
    
    // Process the request...
    return ctx.JSON(201, map[string]interface{}{
        "user":  req.Name,
        "debug": req.Debug,
    })
}

JSON Request with Query Parameters

// POST /users?page=2&sort=name&debug=true
// Content-Type: application/json
// Body: {"name": "John", "email": "john@example.com", "age": 30}

type CreateUserRequest struct {
    // From JSON body
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
    
    // From query parameters
    Page  int    `query:"page"`
    Sort  string `query:"sort"`
    Debug bool   `query:"debug"`
}

func handler(ctx *srv.HttpContext) error {
    var req CreateUserRequest
    if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
        return err
    }
    
    // req.Name = "John" (from JSON)
    // req.Page = 2 (from query)
    // req.Debug = true (from query)
    
    return ctx.JSON(200, req)
}

Form Data with Query Parameters

// POST /users?page=1&sort=email
// Content-Type: application/x-www-form-urlencoded
// Body: name=Jane&email=jane@example.com&active=true

type FormUserRequest struct {
    // From form data
    Name   string `form:"name"`
    Email  string `form:"email"`
    Active bool   `form:"active"`
    
    // From query parameters
    Page   int    `query:"page"`
    Sort   string `query:"sort"`
}

func handler(ctx *srv.HttpContext) error {
    var req FormUserRequest
    if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
        return err
    }
    
    // req.Name = "Jane" (from form)
    // req.Page = 1 (from query)
    
    return ctx.JSON(200, req)
}

Multipart Form with File Upload

type FileUploadRequest struct {
    // From multipart form
    Title       string `form:"title"`
    Description string `form:"description"`
    
    // From query parameters
    Folder string `query:"folder"`
    Public bool   `query:"public"`
}

func uploadHandler(ctx *srv.HttpContext) error {
    var req FileUploadRequest
    if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
        return err
    }
    
    // Handle file upload
    file, header, err := ctx.Request().FormFile("file")
    if err != nil {
        return err
    }
    defer file.Close()
    
    // Use form data and query parameters
    log.Printf("Uploading %s to folder %s (public=%v)", 
        header.Filename, req.Folder, req.Public)
    
    return ctx.JSON(200, map[string]string{
        "title":    req.Title,
        "filename": header.Filename,
        "folder":   req.Folder,
    })
}

Custom Types with TextUnmarshaler

ParseRequest supports custom types that implement the encoding.TextUnmarshaler interface, allowing you to parse complex data types from form and query parameters.

import (
    "encoding"
    "encoding/hex"
    "fmt"
    "time"
)

// Custom 16-byte user identifier
type UserID [16]byte

func (u *UserID) UnmarshalText(text []byte) error {
    if len(text) != 32 { // hex encoded 16 bytes = 32 characters
        return fmt.Errorf("invalid UserID length: expected 32, got %d", len(text))
    }
    _, err := hex.Decode(u[:], text)
    return err
}

func (u UserID) String() string {
    return hex.EncodeToString(u[:])
}

// Custom time format
type CustomDate time.Time

func (cd *CustomDate) UnmarshalText(text []byte) error {
    t, err := time.Parse("2006-01-02", string(text))
    if err != nil {
        return err
    }
    *cd = CustomDate(t)
    return nil
}

func (cd CustomDate) String() string {
    return time.Time(cd).Format("2006-01-02")
}

// Custom enum-like type
type Priority int

const (
    PriorityLow Priority = iota
    PriorityMedium
    PriorityHigh
)

func (p *Priority) UnmarshalText(text []byte) error {
    switch string(text) {
    case "low":
        *p = PriorityLow
    case "medium":
        *p = PriorityMedium
    case "high":
        *p = PriorityHigh
    default:
        return fmt.Errorf("invalid priority: %s", string(text))
    }
    return nil
}

// Usage in request struct
type TaskRequest struct {
    // Custom types in form/query parameters
    UserID      UserID     `form:"user_id" query:"user_id"`
    DueDate     CustomDate `form:"due_date" query:"due_date"`
    Priority    Priority   `form:"priority" query:"priority"`
    
    // Pointer versions (automatically handled)
    AssigneeID  *UserID     `form:"assignee_id" query:"assignee_id"`
    StartDate   *CustomDate `form:"start_date" query:"start_date"`
    
    // Regular fields
    Title       string `json:"title" form:"title"`
    Description string `json:"description" form:"description"`
}

func createTaskHandler(ctx *srv.HttpContext) error {
    var req TaskRequest
    if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
        return err // Automatic error handling for invalid formats
    }
    
    // All custom types are automatically parsed
    log.Printf("Creating task for user %s, due %s, priority %d", 
        req.UserID.String(), req.DueDate.String(), req.Priority)
    
    return ctx.JSON(201, map[string]interface{}{
        "message":    "Task created successfully",
        "user_id":    req.UserID.String(),
        "due_date":   req.DueDate.String(),
        "priority":   req.Priority,
        "assignee":   req.AssigneeID, // nil if not provided
    })
}

Example Requests:

Form Data:

POST /tasks
Content-Type: application/x-www-form-urlencoded

user_id=0123456789abcdef0123456789abcdef&due_date=2024-12-25&priority=high&title=Complete+project

Query Parameters:

GET /tasks?user_id=fedcba9876543210fedcba9876543210&due_date=2024-01-15&priority=medium

Multipart Form:

POST /tasks
Content-Type: multipart/form-data

user_id: abcdef0123456789abcdef0123456789
due_date: 2024-06-30
priority: low
title: Review documentation
description: Review and update project documentation

JSON with Query Parameters:

POST /tasks?user_id=1234567890abcdef1234567890abcdef&priority=high
Content-Type: application/json

{
  "title": "Fix bug #123",
  "description": "Critical security fix"
}

Error Handling:

Custom types can return specific errors that are automatically handled:

type ProductCode string

func (pc *ProductCode) UnmarshalText(text []byte) error {
    s := string(text)
    if len(s) < 3 {
        return fmt.Errorf("product code too short: minimum 3 characters")
    }
    if !strings.HasPrefix(s, "PRD-") {
        return fmt.Errorf("product code must start with 'PRD-'")
    }
    *pc = ProductCode(s)
    return nil
}

// Invalid product codes in form/query will return 400 Bad Request

Advanced Tag Usage

type AdvancedRequest struct {
    // Custom field names
    UserID    int    `query:"user_id"`
    SearchTerm string `query:"q"`
    
    // Skip fields
    Password string `json:"password" form:"password"`
    Internal string `query:"-"`  // Never parsed from query
    
    // Fields without tags use lowercase field name
    Page  int     // Uses "page" as query parameter name
    Limit int     // Uses "limit" as query parameter name
}

Query-Only Requests (GET)

// GET /search?q=golang&page=2&limit=20&sort=date&active=true

type SearchRequest struct {
    Query  string `query:"q"`
    Page   int    `query:"page"`
    Limit  int    `query:"limit"`
    Sort   string `query:"sort"`
    Active bool   `query:"active"`
}

func searchHandler(ctx *srv.HttpContext) error {
    var req SearchRequest
    if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
        return err
    }
    
    // All fields populated from query parameters
    results := performSearch(req.Query, req.Page, req.Limit)
    
    return ctx.JSON(200, map[string]interface{}{
        "results": results,
        "query":   req.Query,
        "page":    req.Page,
    })
}

Error Handling

func handlerWithValidation(ctx *srv.HttpContext) error {
    var req UserRequest
    if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
        // Common errors:
        // - Invalid JSON format
        // - Type conversion errors (e.g., "abc" -> int)
        // - Malformed Content-Type header
        return err  // Returns 400 Bad Request with details
    }
    
    // Additional validation
    if req.Name == "" {
        return erm.BadRequest("Name is required", nil)
    }
    if req.Age < 0 {
        return erm.BadRequest("Age must be positive", nil)
    }
    
    return ctx.JSON(200, req)
}

Type Conversion Examples

// URL: /api/users?page=5&active=true&score=95.5&tags=&user_id=1234567890abcdef1234567890abcdef

type TypeExampleRequest struct {
    Page    int     `query:"page"`    // "5" -> 5
    Active  bool    `query:"active"`  // "true" -> true
    Score   float64 `query:"score"`   // "95.5" -> 95.5
    Tags    string  `query:"tags"`    // "" -> "" (empty string)
    UserID  UserID  `query:"user_id"` // "1234567890abcdef1234567890abcdef" -> UserID via UnmarshalText
    Missing int     `query:"missing"` // (not provided) -> 0 (zero value)
}

Best Practices

1. Combine Tags: Use multiple tags for flexibility

type FlexibleRequest struct {
    Name string `json:"name" form:"name" query:"name"`
}

1. Validation: Always validate parsed data

if req.Page < 1 {
    req.Page = 1  // Set default
}

1. Error Handling: Return meaningful errors

if err := srv.ParseRequest(ctx.Request(), &req); err != nil {
    return erm.BadRequest("Invalid request format", err)
}

1. Custom Types: Implement TextUnmarshaler for complex parsing

type ProductID string

func (p *ProductID) UnmarshalText(text []byte) error {
    s := string(text)
    if !strings.HasPrefix(s, "prod_") {
        return fmt.Errorf("invalid product ID format")
    }
    *p = ProductID(s)
    return nil
}

1. Documentation: Document expected parameters

// UserListRequest handles GET /users?page=N&sort=field&limit=N
type UserListRequest struct {
    Page  int    `query:"page"`  // Page number (default: 1)
    Sort  string `query:"sort"`  // Sort field: "name", "email", "created"
    Limit int    `query:"limit"` // Items per page (default: 20, max: 100)
}

🔀 Mux - Enhanced HTTP Router

Overview

Mux wraps Go's standard http.ServeMux with convenient HTTP method helpers, RESTful routing support, and centralized error handling.

HandlerFunc Type

type HandlerFunc func(ctx *HttpContext) error

The new HandlerFunc signature provides several advantages:

• Automatic HttpContext: No need to manually create HttpContext
• Error Handling: Return errors instead of writing error responses manually
• Cleaner Code: Less boilerplate, more focused business logic

Constructor

mux := srv.NewMux()  // Includes default error handler

HTTP Method Helpers with Optional Naming

// Named routes for URL generation
mux.Get("user-list", "/users", func(ctx *HttpContext) error {
    return ctx.JSON(200, users)
})

mux.Post("user-create", "/users", func(ctx *HttpContext) error {
    user := parseUser(ctx)
    if err := validateUser(user); err != nil {
        return err  // Automatically handled by error handler
    }
    return ctx.JSON(201, user)
})

// Unnamed routes (empty string name)
mux.Get("", "/health", func(ctx *HttpContext) error {
    return ctx.String(200, "OK")
})

// Same name for different methods (RESTful pattern)
mux.Get("users", "/users", listUsersHandler)      // GET /users
mux.Post("users", "/users", createUserHandler)    // POST /users
mux.Get("user", "/users/{id}", getUserHandler)    // GET /users/{id}
mux.Put("user", "/users/{id}", updateUserHandler) // PUT /users/{id}
mux.Delete("user", "/users/{id}", deleteUserHandler) // DELETE /users/{id}

// All HTTP methods supported
mux.Patch("user-patch", "/users/{id}", handler)  // PATCH requests
mux.Head("health-check", "/ping", handler)       // HEAD requests
mux.Options("cors", "/api/*", handler)           // OPTIONS requests

URL Reversing (Simplified)

// Generate URLs from route names (no method parameter needed)
usersURL, err := mux.Reverse("users", nil)
// Returns: "/users" (works for both GET and POST since same pattern)

userURL, err := mux.Reverse("user", map[string]string{"id": "123"})
// Returns: "/users/123" (works for GET, PUT, DELETE since same pattern)

// Error handling with erm package integration
userURL, err := mux.Reverse("non-existent", nil)
// Returns: "", erm.NotFound error with 404 status

userURL, err := mux.Reverse("user-profile", nil)  // Missing {id} parameter
// Returns: "", erm.RequiredError for missing parameters

URL Generation in Handlers

mux.Get("users", "/users", func(ctx *HttpContext) error {
    // Generate URLs to related endpoints
    createURL, _ := mux.Reverse("users", nil)  // Simplified: no method needed
    
    return ctx.JSON(200, map[string]interface{}{
        "users": getUsersList(),
        "links": map[string]string{
            "create": createURL,
        },
    })
})

mux.Get("user", "/users/{id}", func(ctx *HttpContext) error {
    id := ctx.Param("id")
    
    // Generate URLs with dynamic parameters (no method needed)
    editURL, _ := mux.Reverse("user", map[string]string{"id": id})
    
    return ctx.JSON(200, map[string]interface{}{
        "user": getUser(id),
        "links": map[string]string{
            "edit": editURL,  // Same URL for PUT, DELETE since same pattern
        },
    })
})

Error Handling

// Custom error handler (optional)
mux.ErrorHandler(func(ctx *HttpContext, err error) {
    log.Printf("Handler error: %v", err)
    
    // Handle different error types
    switch e := err.(type) {
    case *ValidationError:
        ctx.JSON(400, map[string]string{"error": e.Error()})
    case *NotFoundError:
        ctx.JSON(404, map[string]string{"error": "Not found"})
    default:
        ctx.JSON(500, map[string]string{"error": "Internal server error"})
    }
})

// Default error handler returns 500 with generic message

Standard ServeMux Methods (Traditional Handlers)

mux.Handle("/api/", apiHandler)         // Register http.Handler
mux.HandleFunc("/health", healthFunc)   // Register http.HandlerFunc

Access Underlying ServeMux

stdMux := mux.Mux()  // Get *http.ServeMux for advanced usage

🔗 Middleware System

The srv package uses HandlerFunc-based middleware that works seamlessly with the Context interface and error handling system.

Built-in Middleware

Logging Middleware

mux.Middleware(srv.LoggingMiddleware)  // Structured logging with slog

Captures: method, path, user agent, remote address, and processing duration

Recovery Middleware

mux.Middleware(srv.RecoverMiddleware)  // Panic recovery with error conversion

Converts panics to errors that are handled by the error handler

CORS Middleware

// Default CORS configuration (allows all origins)
mux.Middleware(srv.CORSMiddleware(srv.DefaultCORSConfig))

// Production CORS configuration with security best practices
corsConfig := srv.CORSConfig{
    AllowOrigins:     []string{"https://app.example.com", "https://admin.example.com"},
    AllowMethods:     []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
    AllowHeaders:     []string{"Content-Type", "Authorization", "X-API-Key"},
    AllowCredentials: true,
    ExposeHeaders:    []string{"X-Total-Count", "X-Rate-Limit", "X-Page-Count"},
    MaxAge:           3600, // Cache preflight responses for 1 hour
}
mux.Middleware(srv.CORSMiddleware(corsConfig))

// Note: For preflight requests, register OPTIONS handlers explicitly
mux.Options("", "/api/*", func(ctx Context) error { return nil })

Handles Cross-Origin Resource Sharing with W3C-compliant preflight support, origin validation, credential handling, expose headers, and security hardening. Includes automatic Vary header management and protection against common CORS misconfigurations.

Trailing Slash Middleware

// Default configuration (internal forward)
mux.Middleware(srv.AddTrailingSlashMiddleware(srv.DefaultTrailingSlashConfig))

// Redirect configuration
redirectConfig := srv.TrailingSlashConfig{RedirectCode: 301}
mux.Middleware(srv.AddTrailingSlashMiddleware(redirectConfig))

Adds trailing slashes to URLs for consistency and SEO. Can either redirect or forward internally

Session Middleware

// Create in-memory session store
store := srv.NewInMemoryStore("app-session", srv.NewOptions())
defer store.Close()  // Important: cleanup store on shutdown

// Add session middleware
mux.Middleware(srv.SessionMiddleware(store, "app-session"))

// Use sessions in handlers
mux.Get("profile", "/profile", func(ctx srv.Context) error {
    session := ctx.Get("session").(*srv.Session)
    userID := session.Get("userID")
    if userID == "" {
        return ctx.Redirect(302, "/login")
    }
    return ctx.JSON(200, map[string]interface{}{"userID": userID})
})

mux.Post("login", "/login", func(ctx srv.Context) error {
    session := ctx.Get("session").(*srv.Session)
    session.Set("userID", "12345")
    session.Set("username", "john_doe")
    return ctx.JSON(200, map[string]string{"status": "logged in"})
})

Session features include:

• Thread-safe in-memory storage with automatic cleanup of expired sessions
• Configurable cookie options (Path, Domain, MaxAge, Secure, HttpOnly, SameSite)
• Cryptographically secure session IDs generated with crypto/rand
• Context integration for easy session access in handlers
• Store interface for custom session storage backends (Redis, database, etc.)

Custom session configuration:

// Custom session options
options := &srv.Options{
    Path:     "/api",                    // Cookie path
    Domain:   "example.com",             // Cookie domain
    MaxAge:   3600,                      // Session timeout (seconds)
    Secure:   true,                      // HTTPS only
    HttpOnly: true,                      // Prevent XSS
    SameSite: http.SameSiteStrictMode,   // CSRF protection
}
store := srv.NewInMemoryStore("secure-session", options)

// Use with middleware
mux.Middleware(srv.SessionMiddleware(store, "secure-session"))

// Custom store implementation (example)
type RedisStore struct {
    client *redis.Client
    options *srv.Options
}

func (r *RedisStore) Get(req *http.Request, name string) (*srv.Session, error) {
    // Custom Redis implementation
}

Cookie Store (Encrypted Client-Side Storage)

For stateless applications or when you want to avoid server-side session storage, use the CookieStore that encrypts all session data and stores it directly in cookies:

// Generate a secure encryption key (32 bytes for AES-256)
key := make([]byte, 32)
if _, err := rand.Read(key); err != nil {
    log.Fatal(err)
}

// Create encrypted cookie store
store, err := srv.NewCookieStore("secure-session", key, &srv.Options{
    Path:     "/",
    MaxAge:   3600,                      // 1 hour session timeout
    Secure:   true,                      // HTTPS only in production
    HttpOnly: true,                      // Prevent XSS attacks
    SameSite: http.SameSiteStrictMode,   // CSRF protection
})
if err != nil {
    log.Fatal(err)
}

// Use with session middleware (no defer Close() needed for cookie store)
mux.Middleware(srv.SessionMiddleware(store, "secure-session"))

// Session usage remains the same
mux.Post("login", "/login", func(ctx srv.Context) error {
    session := ctx.Get("session").(*srv.Session)
    
    // Authenticate user...
    if validCredentials {
        session.Set("userID", 12345)
        session.Set("role", "admin")
        session.Set("loginTime", time.Now())
        return ctx.JSON(200, map[string]string{"status": "logged in"})
    }
    
    return ctx.JSON(401, map[string]string{"error": "invalid credentials"})
})

CookieStore Features:

• 🔒 AES-GCM Encryption: Authenticated encryption ensures data confidentiality and integrity
• 🗃️ Client-side Storage: No server-side session storage required (stateless)
• 🔑 Configurable Keys: Supports AES-128, AES-192, or AES-256 (16, 24, or 32-byte keys)
• 📏 Size Monitoring: Automatic validation of cookie size limits (~4KB)
• 🧮 Gob Serialization: Supports complex Go data types (maps, slices, structs)
• ⚡ Thread-safe: Safe for concurrent use across multiple requests

Security Considerations:

• Store encryption keys securely (use environment variables, key management systems)
• Rotate encryption keys periodically
• Use different keys for different environments (dev, staging, prod)
• Set appropriate cookie security options (Secure, HttpOnly, SameSite)
• Be mindful of session data size (cookie limit ~4KB)

Key Management Example:

// Production key management
func getEncryptionKey() []byte {
    keyStr := os.Getenv("SESSION_ENCRYPTION_KEY")
    if keyStr == "" {
        log.Fatal("SESSION_ENCRYPTION_KEY environment variable required")
    }
    
    key, err := base64.StdEncoding.DecodeString(keyStr)
    if err != nil {
        log.Fatal("Invalid SESSION_ENCRYPTION_KEY format")
    }
    
    if len(key) != 32 { // Require AES-256
        log.Fatal("SESSION_ENCRYPTION_KEY must be 32 bytes for AES-256")
    }
    
    return key
}

// Generate key for new deployment
func generateKey() {
    key := make([]byte, 32)
    if _, err := rand.Read(key); err != nil {
        log.Fatal(err)
    }
    fmt.Printf("SESSION_ENCRYPTION_KEY=%s\n", base64.StdEncoding.EncodeToString(key))
}

Store Comparison:

Feature	InMemoryStore	CookieStore
Storage Location	Server memory	Client cookies
Scalability	Single instance	Stateless/multi-instance
Data Size Limit	Memory available	~4KB per session
Persistence	Lost on restart	Survives restarts
Security	Server-side only	Encrypted client-side
Performance	Fast lookup	Encryption overhead
Use Cases	Single-server apps	Load-balanced/stateless apps

Session management provides:

• Automatic cookie handling - Sessions are loaded and saved automatically
• Error resilience - Failed session operations don't crash handlers
• Memory efficiency - Expired sessions are automatically cleaned up
• Security - Uses secure defaults and cryptographic session IDs

Middleware Chaining

// Add multiple middleware (applied in order added - first added = outermost wrapper)
mux.Middleware(srv.LoggingMiddleware)                                    // Outermost: logs all requests
mux.Middleware(srv.RecoverMiddleware)                                    // Recovers from panics
mux.Middleware(srv.AddTrailingSlashMiddleware(srv.DefaultTrailingSlashConfig)) // URL normalization
mux.Middleware(srv.CORSMiddleware(srv.DefaultCORSConfig))               // CORS headers
mux.Middleware(srv.SessionMiddleware(store, "app-session"))             // Session management
// Add your custom middleware...
mux.Middleware(func(next srv.HandlerFunc) srv.HandlerFunc {
    return func(ctx srv.Context) error {
        // Custom middleware logic here
        return next(ctx)
    }
})

🛑 RunServer - Graceful Server

Function Signature

func RunServer(handler http.Handler, host string, port string, cleanup func() error) error

Parameters

• handler: HTTP handler (can be Mux, middleware chain, etc.)
• host: Host to bind to (defaults to "0.0.0.0" if empty)
• port: Port to listen on (defaults to "8000" if empty)
• cleanup: Function called during shutdown for resource cleanup

Graceful Shutdown Process

1. Listens for SIGINT/SIGTERM signals
2. Stops accepting new requests
3. Waits up to 10 seconds for existing requests to complete
4. Calls the cleanup function
5. Returns any errors that occurred

Usage Examples

Basic RESTful API

mux := srv.NewMux()

// Set custom error handler for better error responses
mux.ErrorHandler(func(ctx *srv.HttpContext, err error) {
    log.Printf("API Error: %v", err)
    ctx.JSON(500, map[string]string{"error": err.Error()})
})

// Users API with enhanced naming and URL generation
mux.Get("users", "/users", listUsers)
mux.Post("users", "/users", createUser)
mux.Get("user", "/users/{id}", getUser)
mux.Put("user", "/users/{id}", updateUser)
mux.Delete("user", "/users/{id}", deleteUser)

func getUser(ctx *srv.HttpContext) error {
    // Get path parameter
    id := ctx.Param("id")
    
    // Store in context for other middleware
    ctx.Set("userID", id)
    
    // Get user with error handling
    user, err := getUserByID(id)
    if err != nil {
        return err  // Automatically handled by error handler
    }
    
    // Generate URLs to related endpoints
    editURL, _ := mux.Reverse("user", map[string]string{"id": id})
    
    // Return JSON response with links
    return ctx.JSON(200, map[string]interface{}{
        "user": user,
        "links": map[string]string{
            "edit": editURL,
        },
    })
}

func createUser(ctx *srv.HttpContext) error {
    var user User
    if err := json.NewDecoder(ctx.Request().Body).Decode(&user); err != nil {
        return fmt.Errorf("invalid JSON: %w", err)
    }
    
    if err := validateUser(user); err != nil {
        return err
    }
    
    createdUser, err := saveUser(user)
    if err != nil {
        return fmt.Errorf("failed to save user: %w", err)
    }
    
    return ctx.JSON(201, createdUser)
}

// Start server
srv.RunServer(mux, "localhost", "8080", func() error {
    return db.Close()
})

Advanced Middleware Integration

// Create mux with comprehensive middleware stack
mux := srv.NewMux()

// Add session middleware first
store := srv.NewInMemoryStore("app-session", srv.NewOptions())
defer store.Close()
mux.Middleware(srv.SessionMiddleware(store, "app-session"))

// Add HandlerFunc middleware (recommended)
mux.Middleware(srv.LoggingMiddleware)    // Structured logging
mux.Middleware(srv.RecoverMiddleware)    // Panic recovery

// Add custom authentication middleware
mux.Middleware(func(next srv.HandlerFunc) srv.HandlerFunc {
    return func(ctx srv.Context) error {
        token := ctx.GetHeader("Authorization")
        if token == "" {
            return erm.Unauthorized("missing authorization", nil)
        }
        
        // Validate token and store user
        user, err := validateToken(token)
        if err != nil {
            return erm.Unauthorized("invalid token", err)
        }
        ctx.Set("user", user)
        
        return next(ctx)
    }
})

// Add CORS middleware
mux.Middleware(srv.CORSMiddleware(srv.CORSConfig{
    AllowOrigins:     []string{"https://example.com"},
    AllowCredentials: true,
    ExposeHeaders:    []string{"X-Total-Count"},
}))

// Register routes (middleware automatically applied)
mux.Get("users", "/users", listUsersHandler)
mux.Post("users", "/users", createUserHandler)

// All middleware is now configured and will be applied to all routes registered afterward

Enhanced HandlerFunc with Middleware and Error Handling

// Create mux and add middleware
mux := srv.NewMux()

// Add authentication middleware
mux.Middleware(func(next srv.HandlerFunc) srv.HandlerFunc {
    return func(ctx srv.Context) error {
        token := ctx.GetHeader("Authorization")
        if token == "" {
            return erm.Unauthorized("missing authorization", nil)
        }
        // Store authenticated user in context
        ctx.Set("user", getUserFromToken(token))
        return next(ctx)
    }
})

// Add logging middleware
mux.Middleware(srv.LoggingMiddleware)

// Register handler with automatic Context and error handling
mux.Post("user-create", "/users", createUserHandler)

func createUserHandler(ctx srv.Context) error {
	// Parse form data (Context provided automatically)
	name := ctx.FormValue("name")
	email := ctx.FormValue("email")
	
	// Validate input - return error instead of manual response
	if name == "" || email == "" {
		return erm.BadRequest("name and email are required", nil)
	}
	
	// Get authenticated user from middleware context
	authUser, ok := ctx.Get("user").(*User)
	if !ok {
		return erm.Unauthorized("authentication required", nil)
	}
	
	// Create user
	user := &User{
		Name:      name,
		Email:     email,
		CreatedBy: authUser.ID,
	}
	
	// Database operation with error handling
	if err := saveUser(user); err != nil {
		return fmt.Errorf("failed to create user: %w", err)
	}
	
	// Generate URL to view the created user
	userURL, _ := mux.Reverse("user", map[string]string{"id": user.ID})
	
	// Return created user with links (errors handled automatically)
	return ctx.JSON(201, map[string]interface{}{
		"user": user,
		"links": map[string]string{"self": userURL},
	})
}

// Error handling patterns
func advancedErrorHandling(ctx *srv.HttpContext) error {
    // Custom error types for different HTTP status codes
    user, err := validateAndGetUser(ctx)
    if err != nil {
        switch {
        case errors.Is(err, ErrUserNotFound):
            return &HTTPError{Code: 404, Message: "User not found"}
        case errors.Is(err, ErrValidation):
            return &HTTPError{Code: 400, Message: err.Error()}
        default:
            return err  // 500 from default error handler
        }
    }
    
    return ctx.JSON(200, user)
}

// Custom error type for specific HTTP responses
type HTTPError struct {
    Code    int
    Message string
}

func (e *HTTPError) Error() string {
    return e.Message
}

// Custom error handler that understands HTTPError
mux.ErrorHandler(func(ctx *srv.HttpContext, err error) {
    if httpErr, ok := err.(*HTTPError); ok {
        ctx.JSON(httpErr.Code, map[string]string{"error": httpErr.Message})
        return
    }
    
    // Default error handling
    log.Printf("Unexpected error: %v", err)
    ctx.JSON(500, map[string]string{"error": "Internal server error"})
})

File Upload Handling

mux.Post("/upload", func(ctx *srv.HttpContext) error {
    // Parse multipart form (32MB max)
    if err := ctx.Request().ParseMultipartForm(32 << 20); err != nil {
        return fmt.Errorf("invalid form: %w", err)
    }
    
    // Get uploaded file
    file, header, err := ctx.Request().FormFile("file")
    if err != nil {
        return errors.New("no file uploaded")
    }
    defer file.Close()
    
    // Validate file type
    if !isValidFileType(header.Filename) {
        return errors.New("invalid file type")
    }
    
    // Process file with error handling
    savedPath, err := saveUploadedFile(file, header.Filename)
    if err != nil {
        return fmt.Errorf("failed to save file: %w", err)
    }
    
    // Return success response
    return ctx.JSON(200, map[string]string{
        "message":  "File uploaded successfully",
        "filename": header.Filename,
        "path":     savedPath,
    })
})

// Helper functions with proper error handling
func isValidFileType(filename string) bool {
    validTypes := []string{".jpg", ".jpeg", ".png", ".pdf", ".txt"}
    ext := strings.ToLower(filepath.Ext(filename))
    for _, validType := range validTypes {
        if ext == validType {
            return true
        }
    }
    return false
}

func saveUploadedFile(file multipart.File, filename string) (string, error) {
    // Create unique filename
    uniqueName := fmt.Sprintf("%d_%s", time.Now().Unix(), filename)
    destPath := filepath.Join("/uploads", uniqueName)
    
    // Create destination file
    dest, err := os.Create(destPath)
    if err != nil {
        return "", err
    }
    defer dest.Close()
    
    // Copy file content
    if _, err := io.Copy(dest, file); err != nil {
        return "", err
    }
    
    return destPath, nil
}

Testing

The package includes comprehensive tests covering all functionality:

# Run tests
go test ./srv

# Run tests with coverage
go test -cover ./srv

# Run tests with verbose output
go test -v ./srv

# Run benchmarks
go test -bench=. ./srv

Test Coverage

• ✅ HttpContext: Value store, request/response methods, thread safety
• ✅ Mux: HTTP method helpers, routing, integration tests
• ✅ URL Reversing: Named routes, parameter substitution, edge cases, integration
• ✅ Middleware: Type safety, chaining, logging, recovery, CORS, trailing slash
• ✅ RunServer: Parameter validation, error handling, cleanup
• ✅ Integration: Cross-component functionality tests
• ✅ Benchmarks: Performance testing for all components

Current Coverage: 94.2% of statements

Performance

Benchmark results on Apple M1 Max:

BenchmarkHttpContext_ValueStore     99.00 ns/op    21 B/op    2 allocs/op
BenchmarkHttpContext_JSON          938.8 ns/op  1280 B/op   17 allocs/op  
BenchmarkMux_RouteMatching         271.8 ns/op   224 B/op    5 allocs/op

Best Practices

1. Middleware Order

Place middleware in logical order - logging first, authentication/authorization before business logic:

mux.Middleware(srv.LoggingMiddleware)                                    // First: log everything
mux.Middleware(srv.RecoverMiddleware)                                    // Second: catch panics
mux.Middleware(srv.AddTrailingSlashMiddleware(srv.DefaultTrailingSlashConfig)) // Third: URL normalization
mux.Middleware(srv.CORSMiddleware(srv.DefaultCORSConfig))               // Fourth: CORS headers
mux.Middleware(AuthenticationMiddleware)                                  // Fifth: auth before business logic
mux.Middleware(RateLimitingMiddleware)                                    // Last: rate limiting

2. Context Usage

Use HttpContext consistently for request/response operations:

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := srv.NewHttpContext(w, r)
    // Use ctx for all operations instead of w/r directly
}

3. Error Handling

Always handle errors from response methods:

if err := ctx.JSON(200, data); err != nil {
    log.Printf("Failed to write JSON response: %v", err)
}

4. CORS Configuration

Configure CORS appropriately for your security requirements:

// Development - permissive CORS (use only for development)
mux.Middleware(srv.CORSMiddleware(srv.DefaultCORSConfig))

// Production - restrictive CORS with security best practices
prodCorsConfig := srv.CORSConfig{
    // Specify exact origins - avoid wildcards in production
    AllowOrigins:     []string{"https://yourdomain.com", "https://app.yourdomain.com"},
    
    // Include OPTIONS for preflight support
    AllowMethods:     []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
    
    // Explicitly list allowed headers
    AllowHeaders:     []string{"Content-Type", "Authorization", "X-API-Key"},
    
    // Enable credentials for authenticated requests
    AllowCredentials: true,
    
    // Expose custom headers to clients
    ExposeHeaders:    []string{"X-Total-Count", "X-Rate-Limit", "Link"},
    
    // Cache preflight responses for better performance
    MaxAge:           3600,
}
mux.Middleware(srv.CORSMiddleware(prodCorsConfig))

// Register OPTIONS handlers for preflight requests
mux.Options("", "/api/users", func(ctx Context) error { return nil })
mux.Options("", "/api/users/{id}", func(ctx Context) error { return nil })

Security Guidelines:

• Never use ["*"] for AllowOrigins with AllowCredentials: true
• Use specific origins instead of wildcards in production
• Only expose headers that clients actually need via ExposeHeaders
• Set appropriate MaxAge to balance performance and security
• Always validate that your frontend origins match exactly

5. Trailing Slash Configuration

Configure trailing slash behavior based on your needs:

// Default - internal forward (no redirect)
mux.Middleware(srv.AddTrailingSlashMiddleware(srv.DefaultTrailingSlashConfig))

// SEO-friendly permanent redirect
seoConfig := srv.TrailingSlashConfig{RedirectCode: 301}
mux.Middleware(srv.AddTrailingSlashMiddleware(seoConfig))

// Temporary redirect for testing
testConfig := srv.TrailingSlashConfig{RedirectCode: 302}
mux.Middleware(srv.AddTrailingSlashMiddleware(testConfig))

6. Resource Cleanup

Always provide cleanup functions for graceful shutdown:

srv.RunServer(handler, host, port, func() error {
    db.Close()
    cache.Close()
    return nil
})

Advanced Configuration

For custom server configurations, use the individual components:

mux := srv.NewMux()
mux.Middleware(srv.LoggingMiddleware)
mux.Middleware(srv.RecoverMiddleware)

server := &http.Server{
    Addr:         ":8080",
    Handler:      mux,
    ReadTimeout:  15 * time.Second,
    WriteTimeout: 15 * time.Second,
    IdleTimeout:  60 * time.Second,
}

log.Fatal(server.ListenAndServe())

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

This package is part of the c3p0-box/utils collection and follows the same license terms.