rig

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 and CORS middleware
• Health Checks - Liveness and readiness probes for Kubernetes
• 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

 

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

 

🔝 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
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"},
}))

 

🔝 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
AddReadinessCheck(name, fn)	Adds a check for traffic readiness (DB, Redis, etc.)
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

 

🔝 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

 

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

 

🔝 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

_{© 2025 Cloudresty}