rig

README

Rig

Home  /

 

Rig is a lightweight HTTP framework for Go that wraps net/http with zero external dependencies. Built for Go 1.22+, it provides the ergonomics of popular frameworks while staying true to the standard library.

 

 

Features

• Zero Dependencies - Only the Go standard library (core package)
• Go 1.22+ Pattern Matching - Full support for method routing and path parameters
• Middleware - Global, group, and per-route middleware with onion-style execution
• Route Groups - Organize routes with shared prefixes and middleware
• JSON Handling - Bind, BindStrict, and JSON response helpers
• Static Files - Serve directories with a single line
• Production Middleware - Built-in Recover, CORS, and Timeout middleware
• Production-Safe Timeouts - Server and request timeouts with Slowloris protection
• Graceful Shutdown - Zero-downtime deployments with RunGracefully()
• Health Checks - Liveness and readiness probes with timeout support for Kubernetes
• HTML Templates - Template rendering with layouts, partials, embed.FS, and content negotiation (render/ sub-package)
• Authentication - API Key and Bearer Token middleware (auth/ sub-package)
• Request ID - ULID-based request tracking (requestid/ sub-package)
• Logging - Structured request logging with JSON support (logger/ sub-package)
• Swagger UI - Optional sub-package for API documentation
• Type-Safe Context - Generic GetType[T] for dependency injection
• 99%+ Test Coverage - Battle-tested and production-ready

 

🔝 back to top

 

Installation

go get github.com/cloudresty/rig

Requires Go 1.22 or later.

 

🔝 back to top

 

Quick Start

package main

import (
    "net/http"

    "github.com/cloudresty/rig"
)

func main() {
    r := rig.New()

    // Add middleware
    r.Use(rig.Recover())
    r.Use(rig.DefaultCORS())

    // Simple route
    r.GET("/", func(c *rig.Context) error {
        return c.JSON(http.StatusOK, map[string]string{
            "message": "Hello, World!",
        })
    })

    // Path parameters (Go 1.22+)
    r.GET("/users/{id}", func(c *rig.Context) error {
        id := c.Param("id")
        return c.JSON(http.StatusOK, map[string]string{
            "user_id": id,
        })
    })

    http.ListenAndServe(":8080", r)
}

 

🔝 back to top

 

Route Groups

Organize routes with shared prefixes and middleware:

r := rig.New()

// API group with authentication middleware
api := r.Group("/api")
api.Use(authMiddleware)

api.GET("/users", listUsers)       // GET /api/users
api.POST("/users", createUser)     // POST /api/users
api.GET("/users/{id}", getUser)    // GET /api/users/{id}

// Nested groups
v1 := api.Group("/v1")
v1.GET("/status", getStatus)       // GET /api/v1/status

 

🔝 back to top

 

Middleware

Middleware follows the decorator pattern with onion-style execution:

// Custom middleware
func Logger() rig.MiddlewareFunc {
    return func(next rig.HandlerFunc) rig.HandlerFunc {
        return func(c *rig.Context) error {
            start := time.Now()
            err := next(c)
            log.Printf("%s %s %v", c.Method(), c.Path(), time.Since(start))
            return err
        }
    }
}

// Apply middleware
r.Use(rig.Recover())    // Global - catches panics
r.Use(rig.DefaultCORS()) // Global - enables CORS
r.Use(Logger())          // Global - logs requests

 

Built-in Middleware

Middleware	Description
Recover()	Catches panics and returns a 500 JSON error
DefaultCORS()	Permissive CORS (allows all origins)
CORS(config)	Configurable CORS with specific origins/methods/headers
Timeout(duration)	Cancels request context after specified duration

 

Additional middleware sub-packages (see sections below):

Package	Description
auth/	API Key and Bearer Token authentication
requestid/	ULID-based request ID generation
logger/	Structured request logging (text/JSON)

 

🔝 back to top

 

Request Handling

Path Parameters

r.GET("/users/{id}", func(c *rig.Context) error {
    id := c.Param("id")
    // ...
})

 

Query Parameters

r.GET("/search", func(c *rig.Context) error {
    q := c.Query("q")                    // Single value
    tags := c.QueryArray("tag")          // Multiple values: ?tag=a&tag=b
    page := c.QueryDefault("page", "1")  // With default
    // ...
})

 

JSON Body

r.POST("/users", func(c *rig.Context) error {
    var user User
    if err := c.Bind(&user); err != nil {
        return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
    }
    // Use c.BindStrict(&user) to reject unknown fields
    // ...
})

 

Form Data

r.POST("/login", func(c *rig.Context) error {
    username := c.FormValue("username")      // Body takes precedence over query
    password := c.PostFormValue("password")  // Body only
    // ...
})

 

🔝 back to top

 

Response Helpers

// JSON response
c.JSON(http.StatusOK, data)

// String response
c.WriteString("Hello")

// Redirect
c.Redirect(http.StatusFound, "/new-location")

// Serve a file
c.File("./reports/monthly.pdf")

// Raw bytes
c.Data(http.StatusOK, "image/png", pngBytes)

// Set status only
c.Status(http.StatusNoContent)

 

🔝 back to top

 

Static Files

Serve a directory of static files:

r.Static("/assets", "./public")
// GET /assets/css/style.css → serves ./public/css/style.css

 

Cache Control for Static Assets

For production, enable cache headers to improve performance:

// Cache for 1 year (recommended for versioned assets like app.v1.2.3.js)
r.Static("/assets", "./public", rig.StaticConfig{
    CacheControl: "public, max-age=31536000",
})

// Cache for 1 day (for assets that may change)
r.Static("/images", "./images", rig.StaticConfig{
    CacheControl: "public, max-age=86400",
})

// No caching (for development or dynamic assets)
r.Static("/uploads", "./uploads", rig.StaticConfig{
    CacheControl: "no-cache",
})

 

Cache-Control Value	Use Case
public, max-age=31536000	Versioned assets (CSS, JS with hash in filename)
public, max-age=86400	Assets that may change daily
public, max-age=3600	Assets that may change hourly
no-cache	Always revalidate with server
no-store	Never cache (sensitive data)

 

🔝 back to top

 

Dependency Injection

Use the context store for request-scoped values:

// Middleware: inject dependencies
func InjectDB(db *Database) rig.MiddlewareFunc {
    return func(next rig.HandlerFunc) rig.HandlerFunc {
        return func(c *rig.Context) error {
            c.Set("db", db)
            return next(c)
        }
    }
}

// Handler: retrieve with type safety
r.GET("/users", func(c *rig.Context) error {
    db, err := rig.GetType[*Database](c, "db")
    if err != nil {
        return err
    }
    // Use db...
})

 

🔝 back to top

 

CORS Configuration

// Permissive (all origins)
r.Use(rig.DefaultCORS())

// Restrictive with exact origins
r.Use(rig.CORS(rig.CORSConfig{
    AllowOrigins: []string{"https://myapp.com", "https://admin.myapp.com"},
    AllowMethods: []string{"GET", "POST", "PUT", "DELETE"},
    AllowHeaders: []string{"Content-Type", "Authorization"},
}))

// Wildcard subdomain support
r.Use(rig.CORS(rig.CORSConfig{
    AllowOrigins: []string{
        "https://*.myapp.com",           // Matches any subdomain
        "https://*.staging.myapp.com",   // Matches nested subdomains
        "https://api.production.com",    // Exact match also works
    },
    AllowMethods: []string{"GET", "POST", "PUT", "DELETE"},
    AllowHeaders: []string{"Content-Type", "Authorization"},
}))

 

AllowOrigins patterns:

Pattern	Matches	Does Not Match
"*"	All origins	-
"https://example.com"	Exact match only	https://sub.example.com
"https://*.example.com"	https://app.example.com, https://a.b.example.com	https://example.com, http://app.example.com

 

🔝 back to top

 

Health Checks

Rig provides an opt-in health utility for liveness and readiness probes, perfect for Kubernetes deployments:

func main() {
    r := rig.New()
    db := connectDB()

    // Create the Health manager
    health := rig.NewHealth()

    // Add readiness check (don't send traffic if DB is down)
    health.AddReadinessCheck("database", func() error {
        return db.Ping()
    })

    // Add liveness check (is the app running?)
    health.AddLivenessCheck("ping", func() error {
        return nil // Always healthy
    })

    // Mount the handlers (user chooses the paths)
    h := r.Group("/health")
    h.GET("/live", health.LiveHandler())
    h.GET("/ready", health.ReadyHandler())

    r.Run(":8080")
}

 

Response format:

// GET /health/ready (all checks pass)
{ "status": "OK", "checks": { "database": "OK" } }

// GET /health/ready (a check fails)
{ "status": "Service Unavailable", "checks": { "database": "FAIL: connection refused" } }

 

Method	Description
NewHealth()	Creates a new Health manager with default 5s timeout
NewHealthWithConfig(config)	Creates a Health manager with custom configuration
AddReadinessCheck(name, fn)	Adds a check for traffic readiness (DB, Redis, etc.)
AddReadinessCheckContext(name, fn)	Adds a context-aware check that respects timeouts
AddLivenessCheck(name, fn)	Adds a check for app liveness (deadlock detection, etc.)
LiveHandler()	Returns a handler for liveness probes
ReadyHandler()	Returns a handler for readiness probes

 

Health Check Timeouts

Health checks have built-in timeout protection to prevent slow checks from blocking health endpoints:

// Custom timeout configuration
config := rig.HealthConfig{
    CheckTimeout: 10 * time.Second,  // Per-check timeout (default: 5s)
    Parallel:     true,              // Run checks concurrently (default: false)
}
health := rig.NewHealthWithConfig(config)

// Context-aware check (receives timeout via context)
health.AddReadinessCheckContext("database", func(ctx context.Context) error {
    return db.PingContext(ctx)  // Respects the timeout
})

// Per-check timeout override
health.AddReadinessCheckWithTimeout("slow-service", 30*time.Second, func(ctx context.Context) error {
    return slowService.HealthCheck(ctx)
})

 

🔝 back to top

 

Timeouts

Rig provides production-safe timeout defaults to protect against Slowloris attacks and cascading failures.

 

Server Timeouts (Infrastructure Layer)

The Run() method applies production-safe defaults automatically:

r := rig.New()
r.Run(":8080")  // Uses DefaultServerConfig()

 

Default	Value	Purpose
ReadHeaderTimeout	5s	Critical Slowloris protection (headers only)
WriteTimeout	10s	Prevents slow response consumption
IdleTimeout	120s	Allows keep-alive but not indefinitely
ReadTimeout	0	No body limit (allows slow uploads)
MaxHeaderBytes	1MB	Prevents header size attacks

 

Custom Configuration:

config := rig.DefaultServerConfig()
config.Addr = ":8080"
config.WriteTimeout = 30 * time.Second  // Allow longer responses

r.RunWithConfig(config)

 

🔝 back to top

 

Request Timeouts (Application Layer)

Use Timeout() middleware to cancel slow handlers and prevent cascading failures:

r := rig.New()
r.Use(rig.Timeout(5 * time.Second))

r.GET("/api/data", func(c *rig.Context) error {
    // This query will be cancelled if it takes > 5s
    result, err := db.QueryContext(c.Context(), "SELECT ...")
    if err != nil {
        return err  // Returns context.DeadlineExceeded if timed out
    }
    return c.JSON(http.StatusOK, result)
})

 

Custom timeout response:

r.Use(rig.TimeoutWithConfig(rig.TimeoutConfig{
    Timeout: 5 * time.Second,
    OnTimeout: func(c *rig.Context) error {
        return c.JSON(http.StatusGatewayTimeout, map[string]string{
            "error": "Request timed out",
        })
    },
}))

 

 
IMPORTANT
Handlers must check c.Context() for this to work effectively. Use db.QueryContext(c.Context(), ...) instead of db.Query(...).
 

 

🔝 back to top

 

Graceful Shutdown

Rig provides zero-downtime deployment support with RunGracefully(). When the server receives a shutdown signal (SIGINT or SIGTERM), it:

1. Stops accepting new connections
2. Waits for in-flight requests to complete
3. Exits cleanly after the timeout

This prevents dropped connections and 502 errors during deployments.

func main() {
    r := rig.New()

    r.GET("/", func(c *rig.Context) error {
        time.Sleep(2 * time.Second) // Simulate work
        return c.JSON(http.StatusOK, map[string]string{"status": "done"})
    })

    // Ctrl+C will wait for the 2s request to finish before exiting
    if err := r.RunGracefully(":8080"); err != nil {
        log.Fatal(err)
    }
}

 

Method	Description
Run(addr)	Simple start for development/testing
RunGracefully(addr)	Production-ready with graceful shutdown (recommended)
RunWithGracefulShutdown(config)	Graceful shutdown with custom configuration
RunWithConfig(config)	Custom config without graceful shutdown

 

Custom shutdown timeout:

config := rig.DefaultServerConfig()
config.Addr = ":8080"
config.ShutdownTimeout = 30 * time.Second  // Wait longer for in-flight requests

if err := r.RunWithGracefulShutdown(config); err != nil {
    log.Fatal(err)
}

 

🔝 back to top

 

Swagger UI

Rig provides optional Swagger UI support via a separate sub-package to keep the core framework dependency-free:

go get github.com/cloudresty/rig/swagger

 

Basic Usage with swaggo/swag

package main

import (
    "github.com/cloudresty/rig"
    "github.com/cloudresty/rig/swagger"
    _ "myapp/docs" // Generated by: swag init
)

func main() {
    r := rig.New()

    // Your API routes
    r.GET("/api/v1/users", handleUsers)

    // Register Swagger UI at /docs/
    sw := swagger.NewFromSwag("swagger")
    sw.Register(r, "/docs")

    r.Run(":8080")
}
// Access Swagger UI at http://localhost:8080/docs/

 

Usage with Custom Spec

spec := `{"openapi":"3.0.0","info":{"title":"My API","version":"1.0"}}`
sw := swagger.New(spec).
    WithTitle("My API Documentation").
    WithDocExpansion("list")
sw.Register(r, "/api-docs")

 

Usage with Route Groups

api := r.Group("/api/v1")
sw := swagger.NewFromSwag("swagger")
sw.RegisterGroup(api, "/docs")
// Access at /api/v1/docs/

 

Method	Description
New(specJSON)	Creates Swagger UI with a JSON spec string
NewFromSwag(name)	Creates Swagger UI from swaggo/swag registered spec
WithTitle(title)	Sets the page title
WithDeepLinking(bool)	Enables/disables URL deep linking (default: true)
WithDocExpansion(mode)	Sets expansion mode: "list", "full", "none"
Register(router, path)	Registers routes on a Router
RegisterGroup(group, path)	Registers routes on a RouteGroup

 

🔝 back to top

 

Authentication Middleware

The auth/ sub-package provides API Key and Bearer Token authentication:

go get github.com/cloudresty/rig/auth

 

API Key Authentication

import "github.com/cloudresty/rig/auth"

// Simple: validate against a list of keys
api := r.Group("/api")
api.Use(auth.APIKeySimple("key1", "key2", "key3"))

// Advanced: custom validation with identity
api.Use(auth.APIKey(auth.APIKeyConfig{
    Name:   "X-API-Key",        // Header name (default)
    Source: "header",           // "header" or "query"
    Validator: func(key string) (identity string, valid bool) {
        if key == os.Getenv("API_KEY") {
            return "my-service", true
        }
        return "", false
    },
}))

// In handlers, get the authenticated identity
r.GET("/profile", func(c *rig.Context) error {
    identity := auth.GetIdentity(c)  // Returns identity from Validator
    method := auth.GetMethod(c)      // Returns "api_key" or "bearer"
    return c.JSON(http.StatusOK, map[string]string{"user": identity})
})

 

Bearer Token Authentication

api.Use(auth.Bearer(auth.BearerConfig{
    Realm: "API",
    Validator: func(token string) (identity string, valid bool) {
        // Validate JWT or lookup token
        claims, err := validateJWT(token)
        if err != nil {
            return "", false
        }
        return claims.UserID, true
    },
}))

 

Function	Description
APIKeySimple(keys...)	Simple API key validation (constant-time comparison)
APIKey(config)	Configurable API key middleware
Bearer(config)	Bearer token middleware (RFC 6750)
GetIdentity(c)	Get authenticated identity from context
GetMethod(c)	Get auth method ("api_key" or "bearer")
IsAuthenticated(c)	Check if request is authenticated

 

🔝 back to top

 

Request ID Middleware

The requestid/ sub-package generates unique request IDs using ULIDs:

go get github.com/cloudresty/rig/requestid

 

import "github.com/cloudresty/rig/requestid"

r := rig.New()

// Add request ID middleware (generates ULID for each request)
r.Use(requestid.New())

// With custom configuration
r.Use(requestid.New(requestid.Config{
    Header:     "X-Request-ID",  // Response header (default)
    TrustProxy: true,            // Trust incoming X-Request-ID header
    Generator: func() (string, error) {
        return uuid.New().String(), nil  // Use UUID instead of ULID
    },
}))

// In handlers, get the request ID
r.GET("/", func(c *rig.Context) error {
    reqID := requestid.Get(c)
    return c.JSON(http.StatusOK, map[string]string{
        "request_id": reqID,
    })
})

 

Function	Description
New()	Create middleware with default config
New(config)	Create middleware with custom config
Get(c)	Get request ID from context

 

🔝 back to top

 

Logger Middleware

The logger/ sub-package provides structured request logging:

go get github.com/cloudresty/rig/logger

 

import "github.com/cloudresty/rig/logger"

r := rig.New()

// Add request ID first (logger will include it)
r.Use(requestid.New())

// Add logger middleware
r.Use(logger.New(logger.Config{
    Format:    logger.FormatJSON,              // FormatText or FormatJSON
    Output:    os.Stdout,                       // io.Writer
    SkipPaths: []string{"/health", "/ready"},  // Don't log these paths
}))

 

Text format output:

2024/01/15 10:30:45 | 200 |    1.234ms | 192.168.1.1 | GET /api/users | req_id: 01HQ...

JSON format output:

{"time":"2024-01-15T10:30:45Z","status":200,"latency":"1.234ms","latency_ms":1.234,"client_ip":"192.168.1.1","method":"GET","path":"/api/users","request_id":"01HQ..."}

 

Option	Description
Format	FormatText (default) or FormatJSON
Output	io.Writer for log output (default: os.Stdout)
SkipPaths	Paths to exclude from logging (e.g., health checks)

 

🔝 back to top

 

HTML Template Rendering

The render sub-package provides HTML template rendering with layouts, partials, hot reloading, and content negotiation.

go get github.com/cloudresty/rig/render

 

Basic Usage

import (
    "github.com/cloudresty/rig"
    "github.com/cloudresty/rig/render"
)

func main() {
    engine := render.New(render.Config{
        Directory: "./templates",
    })

    r := rig.New()
    r.Use(engine.Middleware())

    r.GET("/", func(c *rig.Context) error {
        return render.HTML(c, http.StatusOK, "home", map[string]any{
            "Title": "Welcome",
            "User":  "John",
        })
    })

    r.Run(":8080")
}

 

🔝 back to top

 

Embedded Templates (embed.FS)

For single-binary deployments, embed templates directly into your Go binary:

import (
    "embed"
    "github.com/cloudresty/rig/render"
)

//go:embed templates/*
var templateFS embed.FS

func main() {
    engine := render.New(render.Config{
        FileSystem: templateFS,
        Directory:  "templates",
    })
    // Templates are now compiled into the binary!
}

 

🔝 back to top

 

With Layouts

engine := render.New(render.Config{
    Directory: "./templates",
    Layout:    "layouts/base", // Base layout template
})

 

Layout template (templates/layouts/base.html):

<!DOCTYPE html>
<html>
<head><title>{{.Data.Title}}</title></head>
<body>
    <header>My Site</header>
    <main>{{.Content}}</main>
    <footer>© 2026</footer>
</body>
</html>

 

Page template (templates/home.html):

<h1>Welcome, {{.User}}!</h1>

 

Layout Data Access:

In layouts, data is available via {{.Data}} (works with both structs and maps):

Expression	Description
{{.Content}}	Rendered page content
{{.Data.Title}}	Access data fields (works with structs!)
{{.Title}}	Direct access (backward compatible with maps)

 

🔝 back to top

 

Partials

Templates starting with underscore (_) are automatically treated as partials and available to all templates:

templates/
├── _sidebar.html    ← Partial (available everywhere)
├── _footer.html     ← Partial (available everywhere)
├── home.html
└── about.html

 

Use partials in any template:

<div class="page">
    {{template "_sidebar" .}}
    <main>{{.Content}}</main>
    {{template "_footer" .}}
</div>

 

🔝 back to top

 

Shared Directories (Component-Based Architecture)

For larger applications, use SharedDirs to designate entire directories as globally available partials. This enables component-based architecture without requiring underscore prefixes:

engine := render.New(render.Config{
    Directory:  "./templates",
    Layout:     "layouts/base",
    SharedDirs: []string{"components", "layouts", "base"},
})

 

Example directory structure:

templates/
├── components/           ← Shared (available everywhere)
│   ├── button.html
│   ├── card.html
│   └── forms/
│       └── input.html
├── base/                 ← Shared (available everywhere)
│   └── modal.html
├── layouts/              ← Shared (available everywhere)
│   └── base.html
└── features/             ← Feature templates (isolated)
    ├── dashboard/
    │   └── index.html
    └── users/
        ├── list.html
        └── profile.html

 

Feature templates can include shared components:

<!-- features/dashboard/index.html -->
<h1>Dashboard</h1>
{{template "components/button" "Click Me"}}
{{template "components/card" .Stats}}
{{template "base/modal" .ModalData}}

 

This approach keeps feature pages isolated while sharing common components across the application. The underscore convention still works alongside SharedDirs - files starting with _ are always treated as partials regardless of their directory.

 

🔝 back to top

 

Rendering Partials Directly (HTMX / AJAX)

For HTMX requests, AJAX updates, or any scenario where you need to render a fragment without the layout wrapper, use Partial():

// HTMX endpoint - returns just the table rows, no layout
r.GET("/users/table", func(c *rig.Context) error {
    users := getUsers()
    return render.Partial(c, http.StatusOK, "components/user-table", map[string]any{
        "Users": users,
    })
})

// Dynamic widget update
r.GET("/dashboard/stats", func(c *rig.Context) error {
    stats := getStats()
    return render.Partial(c, http.StatusOK, "_stats-widget", stats)
})

 

Function	Description
render.Partial(c, status, name, data)	Render partial via middleware (recommended)
render.PartialDirect(c, engine, status, name, data)	Render partial with explicit engine
engine.RenderPartial(name, data)	Low-level: returns HTML string

 

Key differences from HTML():

• Looks up templates in the shared partials set only (not regular templates)
• Never wraps output in a layout
• Perfect for HTMX hx-get / hx-post responses

 

🔝 back to top

 

JSON and XML Responses

Render JSON or XML directly without templates:

// JSON response
r.GET("/api/users", func(c *rig.Context) error {
    return render.JSON(c, http.StatusOK, users)
})

// XML response
r.GET("/api/users.xml", func(c *rig.Context) error {
    return render.XML(c, http.StatusOK, users)
})

 

🔝 back to top

 

Content Negotiation

Use Auto() to automatically select the response format based on the Accept header:

r.GET("/users", func(c *rig.Context) error {
    // Returns HTML for browsers, JSON for API clients
    return render.Auto(c, http.StatusOK, "users/list", users)
})

 

Accept Header	Response Format
application/json	JSON
application/xml or text/xml	XML
text/html or other	HTML (if template provided)
No template provided	JSON (fallback)

 

🔝 back to top

 

Error Pages (Production)

Use HTMLSafe() to automatically render a pretty error page when template rendering fails:

r.GET("/page", func(c *rig.Context) error {
    return render.HTMLSafe(c, http.StatusOK, "page", data, "errors/500")
})

 

If "page" fails to render, it automatically falls back to "errors/500" with error details:

<!-- templates/errors/500.html -->
<h1>Something went wrong</h1>
<p>Error: {{.Error}}</p>
<p>Status: {{.StatusCode}}</p>

 

🔝 back to top

 

Development Mode

Enable hot reloading during development:

engine := render.New(render.Config{
    Directory: "./templates",
    DevMode:   true, // Reloads templates on each request
})

 

🔝 back to top

 

HTML Minification

Enable HTML minification for production to reduce bandwidth and improve page load times:

engine := render.New(render.Config{
    Directory: "./templates",
    Minify:    true, // Minify HTML output
})

 

The minifier is enterprise-grade and safe:

Feature	Description
Block element optimization	Removes whitespace between block elements (<div>, <p>, <section>, etc.)
Inline element preservation	Preserves spaces between inline elements (<span>A</span> <span>B</span> stays intact)
Protected blocks	Preserves whitespace in <pre>, <script>, <style>, and <textarea>
Comment removal	Removes HTML comments while preserving IE conditional comments
JavaScript safety	Preserves // comments and formatting inside <script> tags

 

🔝 back to top

 

Custom Template Functions

engine := render.New(render.Config{
    Directory: "./templates",
    Funcs: template.FuncMap{
        "upper": strings.ToUpper,
        "formatDate": func(t time.Time) string {
            return t.Format("Jan 2, 2006")
        },
    },
})
// Or use chained methods:
engine.AddFunc("lower", strings.ToLower)

 

Use in templates: {{upper .Name}} or {{formatDate .CreatedAt}}

 

🔝 back to top

 

Built-in Functions

Function	Description	Usage
safe	Render trusted HTML without escaping	{{safe .RawHTML}}
safeAttr	Render trusted HTML attribute	{{safeAttr .Attr}}
safeURL	Render trusted URL	{{safeURL .Link}}
dump	Debug helper - outputs data as formatted JSON	{{dump .}}

 

The dump function is invaluable during development:

<!-- Debug: see what data was passed to the template -->
{{dump .Data}}

Outputs:

<pre>{
  "Title": "My Page",
  "User": {
    "Name": "John"
  }
}</pre>

 

🔝 back to top

 

Using Sprig Functions

For 100+ additional template functions (string manipulation, math, dates, etc.), integrate Sprig:

import "github.com/Masterminds/sprig/v3"

engine := render.New(render.Config{
    Directory: "./templates",
})
engine.AddFuncs(sprig.FuncMap())

 

Now you can use functions like {{.Name | upper}}, {{now | date "2006-01-02"}}, and many more.

 

🔝 back to top

 

Custom Delimiters (Vue.js / Angular / Alpine.js)

When using frontend frameworks that also use {{ }} syntax, configure custom delimiters:

engine := render.New(render.Config{
    Directory: "./templates",
    Delims:    []string{"[[", "]]"}, // Use [[ ]] for Go templates
})

 

Now your templates can mix Go and Vue/Angular syntax:

<div>
    <!-- Go template (rendered on server) -->
    <h1>[[ .Title ]]</h1>

    <!-- Vue.js binding (rendered on client) -->
    <p>{{ message }}</p>
</div>

 

🔝 back to top

 

Debugging

List loaded templates and partials:

engine.TemplateNames() // Returns all template names
engine.PartialNames()  // Returns all partial names (files starting with _)

 

🔝 back to top

 

Examples

The examples/ directory contains runnable examples:

Example	Description
basic-api	REST API with middleware, dependency injection, and route groups
health-checks	Kubernetes-style liveness and readiness probes
swagger-ui	API with integrated Swagger UI documentation
auth-middleware	API Key authentication using the auth/ package
logging	Request logging with request ID tracking
render-templates	HTML templates with layouts, partials, and content negotiation

 

🔝 back to top

 

API Reference

Context Methods

Method	Description
Param(name)	Get path parameter
Query(key)	Get query parameter
QueryDefault(key, def)	Get query parameter with default
QueryArray(key)	Get all values for a query parameter
FormValue(key)	Get form value (body precedence)
PostFormValue(key)	Get form value (body only)
GetHeader(key)	Get request header
SetHeader(key, value)	Set response header
Bind(v)	Decode JSON body
BindStrict(v)	Decode JSON body (reject unknown fields)
JSON(code, v)	Send JSON response
Status(code)	Set status code
Redirect(code, url)	Send redirect
File(path)	Serve a file
Data(code, contentType, data)	Send raw bytes
Set(key, value)	Store request-scoped value
Get(key)	Retrieve stored value
MustGet(key)	Retrieve stored value (panics if missing)
Context()	Get context.Context
SetContext(ctx)	Set context.Context
Request()	Get *http.Request
Writer()	Get http.ResponseWriter

 

Router Methods

Method	Description
New()	Create a new router
Use(middleware...)	Add global middleware
Handle(pattern, handler)	Register a handler
GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD(path, handler)	Register method-specific handler
Group(prefix)	Create a route group
Static(path, root)	Serve static files
ServeHTTP(w, r)	Implement http.Handler

 

🔝 back to top

 

License

This project is licensed under the MIT License - see the LICENSE file for details.

 

🔝 back to top

 

 

---

Cloudresty

Website  |  LinkedIn  |  BlueSky  |  GitHub  |  Docker Hub

_{© Cloudresty - All rights reserved}

 

Documentation

Overview

Package rig provides a thin, zero-dependency wrapper around the Go standard library's net/http package. It offers ergonomic benefits similar to frameworks like Gin or Echo while relying purely on the Go standard library.

Index

• func DefaultErrorHandler(c *Context, err error)
• func GetType[T any](c *Context, key string) (T, error)
• type CORSConfig
• type CheckFunc
• type CheckFuncContext
• type Context
  • func (c *Context) Bind(v any) error
  • func (c *Context) BindStrict(v any) error
  • func (c *Context) Context() context.Context
  • func (c *Context) Data(code int, contentType string, data []byte)
  • func (c *Context) File(filepath string)
  • func (c *Context) FormValue(key string) string
  • func (c *Context) Get(key string) (any, bool)
  • func (c *Context) GetHeader(key string) string
  • func (c *Context) Header() http.Header
  • func (c *Context) JSON(code int, v any) error
  • func (c *Context) Method() string
  • func (c *Context) MustGet(key string) any
  • func (c *Context) Param(name string) string
  • func (c *Context) Path() string
  • func (c *Context) PostFormValue(key string) string
  • func (c *Context) Query(key string) string
  • func (c *Context) QueryArray(key string) []string
  • func (c *Context) QueryDefault(key, defaultValue string) string
  • func (c *Context) Redirect(code int, url string)
  • func (c *Context) Request() *http.Request
  • func (c *Context) Set(key string, value any)
  • func (c *Context) SetContext(ctx context.Context)
  • func (c *Context) SetHeader(key, value string)
  • func (c *Context) Status(code int)
  • func (c *Context) Write(data []byte) (int, error)
  • func (c *Context) WriteString(s string) (int, error)
  • func (c *Context) Writer() http.ResponseWriter
  • func (c *Context) Written() bool
• type ErrorHandler
• type HandlerFunc
• type Health
  • func NewHealth() *Health
  • func NewHealthWithConfig(config HealthConfig) *Health
  • func (h *Health) AddLivenessCheck(name string, check CheckFunc)
  • func (h *Health) AddLivenessCheckContext(name string, check CheckFuncContext)
  • func (h *Health) AddLivenessCheckWithTimeout(name string, timeout time.Duration, check CheckFuncContext)
  • func (h *Health) AddReadinessCheck(name string, check CheckFunc)
  • func (h *Health) AddReadinessCheckContext(name string, check CheckFuncContext)
  • func (h *Health) AddReadinessCheckWithTimeout(name string, timeout time.Duration, check CheckFuncContext)
  • func (h *Health) LiveHandler() HandlerFunc
  • func (h *Health) ReadyHandler() HandlerFunc
• type HealthConfig
  • func DefaultHealthConfig() HealthConfig
• type LogFunc
• type MiddlewareFunc
  • func CORS(config CORSConfig) MiddlewareFunc
  • func DefaultCORS() MiddlewareFunc
  • func Recover() MiddlewareFunc
  • func RecoverWithConfig(config RecoverConfig) MiddlewareFunc
  • func Timeout(d time.Duration) MiddlewareFunc
  • func TimeoutWithConfig(config TimeoutConfig) MiddlewareFunc
• type RecoverConfig
• type RouteGroup
  • func (g *RouteGroup) DELETE(path string, handler HandlerFunc)
  • func (g *RouteGroup) GET(path string, handler HandlerFunc)
  • func (g *RouteGroup) Group(prefix string) *RouteGroup
  • func (g *RouteGroup) PATCH(path string, handler HandlerFunc)
  • func (g *RouteGroup) POST(path string, handler HandlerFunc)
  • func (g *RouteGroup) PUT(path string, handler HandlerFunc)
  • func (g *RouteGroup) Use(mw ...MiddlewareFunc)
• type Router
  • func New() *Router
  • func (r *Router) DELETE(path string, handler HandlerFunc)
  • func (r *Router) GET(path string, handler HandlerFunc)
  • func (r *Router) Group(prefix string) *RouteGroup
  • func (r *Router) HEAD(path string, handler HandlerFunc)
  • func (r *Router) Handle(pattern string, handler HandlerFunc)
  • func (r *Router) Handler() http.Handler
  • func (r *Router) OPTIONS(path string, handler HandlerFunc)
  • func (r *Router) PATCH(path string, handler HandlerFunc)
  • func (r *Router) POST(path string, handler HandlerFunc)
  • func (r *Router) PUT(path string, handler HandlerFunc)
  • func (r *Router) Run(addr string) error
  • func (r *Router) RunGracefully(addr string) error
  • func (r *Router) RunUnsafe(addr string) error
  • func (r *Router) RunWithConfig(config ServerConfig) error
  • func (r *Router) RunWithGracefulShutdown(config ServerConfig) error
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) SetErrorHandler(handler ErrorHandler)
  • func (r *Router) Static(path, root string, config ...StaticConfig)
  • func (r *Router) Use(mw ...MiddlewareFunc)
• type ServerConfig
  • func DefaultServerConfig() ServerConfig
• type StaticConfig
• type TimeoutConfig

Functions

func DefaultErrorHandler

func DefaultErrorHandler(c *Context, err error)

DefaultErrorHandler is the default error handler that writes a 500 Internal Server Error response when a handler returns an error.

func GetType

func GetType[T any](c *Context, key string) (T, error)

GetType retrieves a value from the context's key-value store and asserts its type safely using generics. This is the recommended way to retrieve typed values as it avoids panics from incorrect type assertions.

Example:

db, err := rig.GetType[*Database](c, "db")
if err != nil {
    return err
}
db.Query(...)

Types

type CORSConfig

type CORSConfig struct {
	// AllowOrigins is a list of origins that are allowed to access the resource.
	// Supports three formats:
	//   - "*" to allow all origins
	//   - Exact match: "https://example.com"
	//   - Wildcard subdomain: "https://*.example.com" (matches any subdomain)
	AllowOrigins []string

	// AllowMethods is a list of methods allowed when accessing the resource.
	AllowMethods []string

	// AllowHeaders is a list of headers that can be used during the request.
	AllowHeaders []string
}

CORSConfig defines the configuration for CORS middleware.

type CheckFunc

type CheckFunc func() error

CheckFunc is a function that returns nil if healthy, or an error if unhealthy.

type CheckFuncContext

type CheckFuncContext func(ctx context.Context) error

CheckFuncContext is a function that accepts a context for cancellation/timeout support. Use this for health checks that make external calls (database pings, HTTP requests).

type Context

type Context struct {
	// contains filtered or unexported fields
}

Context wraps http.ResponseWriter and *http.Request to provide convenient helper methods for HTTP handlers.

func (*Context) Bind

func (c *Context) Bind(v any) error

Bind decodes the request body into the provided struct v. It expects the request body to be JSON and handles closing the body. The struct v should be a pointer.

By default, unknown fields in the JSON are silently ignored. For stricter APIs that should reject unknown fields, use BindStrict instead.

func (*Context) BindStrict

func (c *Context) BindStrict(v any) error

BindStrict decodes the request body into the provided struct v, but returns an error if the JSON contains fields that are not present in the target struct. This is useful for security-sensitive APIs where you want to reject unexpected data.

Example error: "json: unknown field \"admin\""

func (*Context) Context

func (c *Context) Context() context.Context

Context returns the request's context.Context. This is crucial for passing to database drivers and other libraries that listen for cancellation signals.

func (*Context) Data

func (c *Context) Data(code int, contentType string, data []byte)

Data writes raw bytes to the response with the specified status code and content type.

Example:

c.Data(http.StatusOK, "image/png", pngBytes)

func (*Context) File

func (c *Context) File(filepath string)

File writes the specified file into the response body. It uses http.ServeFile which handles Content-Type detection, range requests, and Last-Modified headers automatically.

Example:

c.File("./reports/monthly.pdf")

func (*Context) FormValue

func (c *Context) FormValue(key string) string

FormValue returns the first value for the named component of the query. POST and PUT body parameters take precedence over URL query string values. This is useful for handling HTML form submissions (application/x-www-form-urlencoded).

func (*Context) Get

func (c *Context) Get(key string) (any, bool)

Get retrieves a value from the context's key-value store. Returns the value and a boolean indicating whether the key was found.

func (*Context) GetHeader

func (c *Context) GetHeader(key string) string

GetHeader returns the value of the specified request header.

func (*Context) Header

func (c *Context) Header() http.Header

Header returns the response header map.

func (*Context) JSON

func (c *Context) JSON(code int, v any) error

JSON writes a JSON response with the given status code. It sets the Content-Type header to "application/json; charset=utf-8" and encodes the provided value v to the response body.

Note: Headers and status code can only be written once. If you've already called Status(), Write(), or WriteString(), the headers set here will be ignored.

func (*Context) Method

func (c *Context) Method() string

Method returns the HTTP method of the request.

func (*Context) MustGet

func (c *Context) MustGet(key string) any

MustGet retrieves a value from the context's key-value store. It panics if the key is not found. Use this only when you are certain the key exists (e.g., set by middleware earlier in the chain).

func (*Context) Param

func (c *Context) Param(name string) string

Param returns the value of a path parameter from the request. This uses Go 1.22+ PathValue feature.

func (*Context) Path

func (c *Context) Path() string

Path returns the URL path of the request.

func (*Context) PostFormValue

func (c *Context) PostFormValue(key string) string

PostFormValue returns the first value for the named component of the POST, PATCH, or PUT request body. URL query parameters are ignored. Use this when you want to explicitly read only from the request body.

func (*Context) Query

func (c *Context) Query(key string) string

Query returns the value of a query string parameter. Query parameters are parsed once and cached for efficient repeated access.

func (*Context) QueryArray

func (c *Context) QueryArray(key string) []string

QueryArray returns all values for a query string parameter. This is useful for parameters that can have multiple values like ?tag=a&tag=b. Query parameters are parsed once and cached for efficient repeated access.

func (*Context) QueryDefault

func (c *Context) QueryDefault(key, defaultValue string) string

QueryDefault returns the value of a query string parameter, or the default value if the parameter is not present or empty. Query parameters are parsed once and cached for efficient repeated access.

func (*Context) Redirect

func (c *Context) Redirect(code int, url string)

Redirect sends an HTTP redirect to the specified URL. The code should be a redirect status code (3xx), typically:

• http.StatusMovedPermanently (301) for permanent redirects
• http.StatusFound (302) for temporary redirects
• http.StatusSeeOther (303) for POST-to-GET redirects
• http.StatusTemporaryRedirect (307) to preserve method
• http.StatusPermanentRedirect (308) for permanent, method-preserving redirects

func (*Context) Request

func (c *Context) Request() *http.Request

Request returns the underlying *http.Request.

func (*Context) Set

func (c *Context) Set(key string, value any)

Set stores a value in the context's key-value store. The store is lazily initialized on first use to save memory.

func (*Context) SetContext

func (c *Context) SetContext(ctx context.Context)

SetContext updates the underlying request's context. Use this when middleware needs to set a timeout, deadline, or add tracing/telemetry data (e.g., OpenTelemetry spans) to the request.

Example:

ctx, cancel := context.WithTimeout(c.Context(), 5*time.Second)
defer cancel()
c.SetContext(ctx)

func (*Context) SetHeader

func (c *Context) SetHeader(key, value string)

SetHeader sets a response header with the given key and value.

func (*Context) Status

func (c *Context) Status(code int)

Status writes the HTTP status code to the response. This should be called before writing any body content.

func (*Context) Write

func (c *Context) Write(data []byte) (int, error)

Write writes data to the response body.

func (*Context) WriteString

func (c *Context) WriteString(s string) (int, error)

WriteString writes a string to the response body.

func (*Context) Writer

func (c *Context) Writer() http.ResponseWriter

Writer returns the underlying http.ResponseWriter.

func (*Context) Written

func (c *Context) Written() bool

Written returns true if the response has been written.

type ErrorHandler

type ErrorHandler func(*Context, error)

ErrorHandler is a function type for handling errors returned by handlers. It receives the Context and the error, allowing custom error responses.

type HandlerFunc

type HandlerFunc func(*Context) error

HandlerFunc is the custom handler signature for rig handlers. Unlike http.HandlerFunc, it accepts a *Context and returns an error, allowing handlers to return errors for centralized error handling.

type Health

type Health struct {
	// contains filtered or unexported fields
}

Health manages liveness and readiness probes.

func NewHealth

func NewHealth() *Health

NewHealth creates a new Health manager with default configuration.

func NewHealthWithConfig

func NewHealthWithConfig(config HealthConfig) *Health

NewHealthWithConfig creates a new Health manager with custom configuration.

func (*Health) AddLivenessCheck

func (h *Health) AddLivenessCheck(name string, check CheckFunc)

AddLivenessCheck adds a check that determines if the app is running (usually just a simple ping, or checking for deadlocks).

func (*Health) AddLivenessCheckContext

func (h *Health) AddLivenessCheckContext(name string, check CheckFuncContext)

AddLivenessCheckContext adds a context-aware liveness check. Use this for checks that make external calls and should respect timeouts.

func (*Health) AddLivenessCheckWithTimeout

func (h *Health) AddLivenessCheckWithTimeout(name string, timeout time.Duration, check CheckFuncContext)

AddLivenessCheckWithTimeout adds a liveness check with a custom timeout. This overrides the global CheckTimeout for this specific check.

func (*Health) AddReadinessCheck

func (h *Health) AddReadinessCheck(name string, check CheckFunc)

AddReadinessCheck adds a check that must pass for the app to receive traffic (e.g., database connection, Redis, upstream API).

func (*Health) AddReadinessCheckContext

func (h *Health) AddReadinessCheckContext(name string, check CheckFuncContext)

AddReadinessCheckContext adds a context-aware readiness check. Use this for checks that make external calls and should respect timeouts.

Example:

health.AddReadinessCheckContext("database", func(ctx context.Context) error {
    return db.PingContext(ctx)
})

func (*Health) AddReadinessCheckWithTimeout

func (h *Health) AddReadinessCheckWithTimeout(name string, timeout time.Duration, check CheckFuncContext)

AddReadinessCheckWithTimeout adds a readiness check with a custom timeout. This overrides the global CheckTimeout for this specific check.

func (*Health) LiveHandler

func (h *Health) LiveHandler() HandlerFunc

LiveHandler returns a Rig HandlerFunc for liveness probes.

func (*Health) ReadyHandler

func (h *Health) ReadyHandler() HandlerFunc

ReadyHandler returns a Rig HandlerFunc for readiness probes.

type HealthConfig

type HealthConfig struct {
	// CheckTimeout is the maximum duration allowed for each individual health check.
	// If a check exceeds this timeout, it is considered failed.
	// Default: 5 seconds.
	CheckTimeout time.Duration

	// Parallel controls whether checks run concurrently.
	// When true, all checks run in parallel (faster but uses more resources).
	// When false, checks run sequentially (slower but predictable resource usage).
	// Default: false (sequential).
	Parallel bool
}

HealthConfig defines configuration for the Health manager.

func DefaultHealthConfig

func DefaultHealthConfig() HealthConfig

DefaultHealthConfig returns production-safe default configuration.

type LogFunc

type LogFunc func(format string, args ...any)

LogFunc is a function type for logging server lifecycle events. It follows the same signature as log.Printf.

type MiddlewareFunc

type MiddlewareFunc func(HandlerFunc) HandlerFunc

MiddlewareFunc is a function that wraps a HandlerFunc to provide additional functionality (logging, authentication, dependency injection, etc.). It follows the standard decorator pattern: it takes a handler and returns a new handler that wraps the original.

func CORS

func CORS(config CORSConfig) MiddlewareFunc

CORS creates middleware that sets the necessary headers for Cross-Origin requests.

Supports wildcard subdomains in AllowOrigins:

r.Use(rig.CORS(rig.CORSConfig{
    AllowOrigins: []string{
        "https://*.example.com",  // Matches any subdomain
        "https://api.other.com",  // Exact match
    },
    AllowMethods: []string{"GET", "POST"},
    AllowHeaders: []string{"Content-Type", "Authorization"},
}))

func DefaultCORS

func DefaultCORS() MiddlewareFunc

DefaultCORS creates CORS middleware with a permissive default configuration. It allows all origins and common HTTP methods and headers.

Example:

r := rig.New()
r.Use(rig.DefaultCORS())

func Recover

func Recover() MiddlewareFunc

Recover creates middleware that recovers from panics and returns a 500 error. This ensures the server never crashes from unhandled panics in handlers.

Panics are logged to stderr with a full stack trace for debugging. The client receives a generic 500 error to avoid leaking internal details.

Example:

r := rig.New()
r.Use(rig.Recover())

func RecoverWithConfig

func RecoverWithConfig(config RecoverConfig) MiddlewareFunc

RecoverWithConfig creates recover middleware with custom configuration. This allows you to customize panic logging (e.g., send to structured logger).

Example:

r.Use(rig.RecoverWithConfig(rig.RecoverConfig{
    Logger: func(err any, stack []byte) {
        slog.Error("panic recovered",
            "error", err,
            "stack", string(stack),
        )
    },
}))

func Timeout

func Timeout(d time.Duration) MiddlewareFunc

Timeout creates middleware that cancels the request context if the handler takes longer than the specified duration.

This is crucial for preventing cascading failures when downstream services (databases, APIs) are slow. It works at the application layer, cancelling the context that handlers should be checking.

IMPORTANT: For this to work effectively, your handlers MUST:

1. Use c.Context() when making external calls (DB queries, HTTP requests)
2. Check ctx.Done() in long-running loops
3. Stop writing to the response immediately when context is cancelled

WARNING: If your handler ignores ctx.Done() and continues writing to the response after timeout, a race condition may occur. This is the standard trade-off in high-performance Go frameworks (Gin, Echo use the same pattern). Always check ctx.Err() before writing responses in long-running handlers.

Example:

r.Use(rig.Timeout(5 * time.Second))

r.GET("/slow", func(c *rig.Context) error {
    // This query will be cancelled if it takes > 5s
    result, err := db.QueryContext(c.Context(), "SELECT ...")
    if err != nil {
        return err // Returns context.DeadlineExceeded if timed out
    }
    return c.JSON(http.StatusOK, result)
})

func TimeoutWithConfig

func TimeoutWithConfig(config TimeoutConfig) MiddlewareFunc

TimeoutWithConfig creates timeout middleware with custom configuration. This allows you to customize the timeout response.

Example:

r.Use(rig.TimeoutWithConfig(rig.TimeoutConfig{
    Timeout: 5 * time.Second,
    OnTimeout: func(c *rig.Context) error {
        return c.JSON(http.StatusGatewayTimeout, map[string]string{
            "error":   "Request timed out",
            "timeout": "5s",
        })
    },
}))

type RecoverConfig

type RecoverConfig struct {
	// Logger is called when a panic is recovered.
	// It receives the panic value and stack trace.
	// If nil, logs to stderr using the standard log package.
	// Set to a no-op function to disable logging:
	//   config.Logger = func(err any, stack []byte) {}
	// Default: logs to stderr with "[RIG] PANIC:" prefix
	Logger func(err any, stack []byte)
}

RecoverConfig defines the configuration for the Recover middleware.

type RouteGroup

type RouteGroup struct {
	// contains filtered or unexported fields
}

RouteGroup represents a group of routes with a common prefix. Groups can have their own middleware that applies only to routes in the group.

func (*RouteGroup) DELETE

func (g *RouteGroup) DELETE(path string, handler HandlerFunc)

DELETE registers a handler for DELETE requests at the given path within the group. The path must be empty or begin with '/'. Panics if the path is invalid.

func (*RouteGroup) GET

func (g *RouteGroup) GET(path string, handler HandlerFunc)

GET registers a handler for GET requests at the given path within the group. The path must be empty or begin with '/'. Panics if the path is invalid.

func (*RouteGroup) Group

func (g *RouteGroup) Group(prefix string) *RouteGroup

Group creates a nested route group with an additional prefix. The nested group inherits the parent group's middleware. The prefix must begin with '/'. Panics if the prefix is invalid.

func (*RouteGroup) PATCH

func (g *RouteGroup) PATCH(path string, handler HandlerFunc)

PATCH registers a handler for PATCH requests at the given path within the group. The path must be empty or begin with '/'. Panics if the path is invalid.

func (*RouteGroup) POST

func (g *RouteGroup) POST(path string, handler HandlerFunc)

POST registers a handler for POST requests at the given path within the group. The path must be empty or begin with '/'. Panics if the path is invalid.

func (*RouteGroup) PUT

func (g *RouteGroup) PUT(path string, handler HandlerFunc)

PUT registers a handler for PUT requests at the given path within the group. The path must be empty or begin with '/'. Panics if the path is invalid.

func (*RouteGroup) Use

func (g *RouteGroup) Use(mw ...MiddlewareFunc)

Use appends one or more middleware to the group's middleware stack. These middleware only apply to routes registered on this group.

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router wraps http.ServeMux to provide a convenient API for routing HTTP requests with the custom HandlerFunc signature.

func New

func New() *Router

New creates a new Router with a fresh http.ServeMux.

func (*Router) DELETE

func (r *Router) DELETE(path string, handler HandlerFunc)

DELETE registers a handler for DELETE requests at the given path. The path must begin with '/'. Panics if the path is invalid.

func (*Router) GET

func (r *Router) GET(path string, handler HandlerFunc)

GET registers a handler for GET requests at the given path. The path must begin with '/'. Panics if the path is invalid.

func (*Router) Group

func (r *Router) Group(prefix string) *RouteGroup

Group creates a new route group with the given prefix. All routes registered on the group will have the prefix prepended. The prefix must begin with '/'. Panics if the prefix is invalid.

func (*Router) HEAD

func (r *Router) HEAD(path string, handler HandlerFunc)

HEAD registers a handler for HEAD requests at the given path. The path must begin with '/'. Panics if the path is invalid.

func (*Router) Handle

func (r *Router) Handle(pattern string, handler HandlerFunc)

Handle registers a handler for the given pattern with any HTTP method. The pattern follows Go 1.22+ ServeMux patterns (e.g., "GET /users/{id}"). The handler is wrapped with all registered middleware before being added.

func (*Router) Handler

func (r *Router) Handler() http.Handler

Handler returns the underlying http.ServeMux as an http.Handler.

func (*Router) OPTIONS

func (r *Router) OPTIONS(path string, handler HandlerFunc)

OPTIONS registers a handler for OPTIONS requests at the given path. The path must begin with '/'. Panics if the path is invalid.

func (*Router) PATCH

func (r *Router) PATCH(path string, handler HandlerFunc)

PATCH registers a handler for PATCH requests at the given path. The path must begin with '/'. Panics if the path is invalid.

func (*Router) POST

func (r *Router) POST(path string, handler HandlerFunc)

POST registers a handler for POST requests at the given path. The path must begin with '/'. Panics if the path is invalid.

func (*Router) PUT

func (r *Router) PUT(path string, handler HandlerFunc)

PUT registers a handler for PUT requests at the given path. The path must begin with '/'. Panics if the path is invalid.

func (*Router) Run

func (r *Router) Run(addr string) error

Run starts the HTTP server on the given address with production-safe default timeouts. This protects against Slowloris attacks and connection leaks.

For custom timeouts (e.g., long-polling endpoints), use RunWithConfig instead.

Default timeouts applied:

• ReadTimeout: 5s
• WriteTimeout: 10s
• IdleTimeout: 120s
• ReadHeaderTimeout: 2s
• MaxHeaderBytes: 1MB

func (*Router) RunGracefully

func (r *Router) RunGracefully(addr string) error

RunGracefully starts the HTTP server with production-safe defaults and waits for a termination signal (SIGINT or SIGTERM) to shut down gracefully.

It ensures that active connections are given time to complete before the process exits. This is the recommended method for production deployments, especially in containerized environments (Docker, Kubernetes).

The server will:

1. Listen for SIGINT (Ctrl+C) and SIGTERM (Docker stop, Kubernetes terminate)
2. Stop accepting new connections when a signal is received
3. Wait up to 5 seconds for active requests to complete
4. Forcefully close remaining connections after the timeout

Example:

func main() {
    r := rig.New()
    r.GET("/", handler)
    if err := r.RunGracefully(":8080"); err != nil {
        log.Fatal(err)
    }
}

func (*Router) RunUnsafe

func (r *Router) RunUnsafe(addr string) error

RunUnsafe starts the HTTP server without any timeouts. WARNING: This is only for development or testing. In production, this makes your server vulnerable to Slowloris attacks and connection leaks. Use Run() or RunWithConfig() instead.

func (*Router) RunWithConfig

func (r *Router) RunWithConfig(config ServerConfig) error

RunWithConfig starts the HTTP server with specific configuration. This is the recommended method for production deployments where you need custom timeouts (e.g., long-polling, file uploads, streaming responses).

Example:

config := rig.DefaultServerConfig()
config.Addr = ":8080"
config.WriteTimeout = 30 * time.Second // Allow longer responses
r.RunWithConfig(config)

func (*Router) RunWithGracefulShutdown

func (r *Router) RunWithGracefulShutdown(config ServerConfig) error

RunWithGracefulShutdown starts the server with specific configuration and handles graceful shutdown automatically. Use this when you need custom timeouts or shutdown behavior.

Example:

config := rig.DefaultServerConfig()
config.Addr = ":8080"
config.WriteTimeout = 30 * time.Second  // Allow longer responses
config.ShutdownTimeout = 10 * time.Second  // More time for shutdown
r.RunWithGracefulShutdown(config)

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface. This allows the Router to be used directly with http.ListenAndServe.

func (*Router) SetErrorHandler

func (r *Router) SetErrorHandler(handler ErrorHandler)

SetErrorHandler sets a custom error handler for the router. This handler is called when a HandlerFunc returns an error.

func (*Router) Static

func (r *Router) Static(path, root string, config ...StaticConfig)

Static registers a route to serve static files from a directory. path is the URL path prefix (e.g., "/assets"). root is the local file system directory (e.g., "./public"). config is an optional StaticConfig for setting cache headers.

Example:

r.Static("/assets", "./public")
// GET /assets/css/style.css -> serves ./public/css/style.css

With cache control (recommended for production):

r.Static("/assets", "./public", rig.StaticConfig{
    CacheControl: "public, max-age=31536000", // 1 year
})

func (*Router) Use

func (r *Router) Use(mw ...MiddlewareFunc)

Use appends one or more middleware to the router's middleware stack. Middleware are executed in the order they are added.

type ServerConfig

type ServerConfig struct {
	// Addr is the TCP address to listen on (e.g., ":8080" or "127.0.0.1:8080").
	Addr string

	// ReadTimeout is the maximum duration for reading the entire request,
	// including the body. Setting this too low (e.g., 5s) will kill file uploads
	// on slow connections. Use ReadHeaderTimeout for Slowloris protection instead.
	// Default: 0 (no timeout - body reads are not time-limited).
	ReadTimeout time.Duration

	// WriteTimeout is the maximum duration before timing out writes of the
	// response. This prevents slow clients from consuming server resources.
	// Default: 10 seconds.
	WriteTimeout time.Duration

	// IdleTimeout is the maximum amount of time to wait for the next request
	// when keep-alives are enabled. If zero, the value of ReadTimeout is used.
	// Default: 120 seconds.
	IdleTimeout time.Duration

	// ReadHeaderTimeout is the amount of time allowed to read request headers.
	// This is the critical defense against Slowloris attacks where attackers
	// send headers very slowly to exhaust server resources.
	// Default: 5 seconds.
	ReadHeaderTimeout time.Duration

	// MaxHeaderBytes controls the maximum number of bytes the server will
	// read parsing the request header's keys and values.
	// Default: 1MB (1 << 20).
	MaxHeaderBytes int

	// ShutdownTimeout is the maximum duration to wait for active connections
	// to finish during graceful shutdown. After this timeout, the server
	// forcefully closes remaining connections.
	// Only used by RunGracefully and RunWithGracefulShutdown.
	// Default: 5 seconds.
	ShutdownTimeout time.Duration

	// Logger is called to log server lifecycle events (startup, shutdown).
	// If nil, logs to stderr using the standard log package.
	// Set to a no-op function to disable logging:
	//   config.Logger = func(format string, args ...any) {}
	// Default: log.Printf
	Logger LogFunc
}

ServerConfig holds the configuration for the HTTP server. Use DefaultServerConfig() to get production-safe defaults that protect against Slowloris attacks and connection leaks.

func DefaultServerConfig

func DefaultServerConfig() ServerConfig

DefaultServerConfig returns production-safe default timeouts. These settings protect against Slowloris attacks while remaining permissive for legitimate slow clients (e.g., mobile file uploads).

The defaults are:

• ReadTimeout: 0 - no body read timeout (use Timeout middleware for request limits)
• ReadHeaderTimeout: 5s - critical Slowloris protection (headers only)
• WriteTimeout: 10s - prevents slow response consumption
• IdleTimeout: 120s - allows keep-alive but not indefinitely
• MaxHeaderBytes: 1MB - prevents header size attacks
• ShutdownTimeout: 5s - time for graceful shutdown
• Logger: log.Printf - logs to stderr

type StaticConfig

type StaticConfig struct {
	// CacheControl sets the Cache-Control header for static files.
	// Common values:
	//   - "public, max-age=31536000" (1 year, for versioned assets)
	//   - "public, max-age=86400" (1 day)
	//   - "no-cache" (always revalidate)
	// If empty, no Cache-Control header is set.
	CacheControl string
}

StaticConfig holds configuration options for serving static files.

type TimeoutConfig

type TimeoutConfig struct {
	// Timeout is the maximum duration allowed for the handler to complete.
	// After this duration, the context is cancelled and an error response is sent.
	Timeout time.Duration

	// OnTimeout is called when the handler times out.
	// If nil, a default JSON response with 504 Gateway Timeout is returned.
	OnTimeout func(c *Context) error
}

TimeoutConfig defines the configuration for the Timeout middleware.