rig

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 4, 2025 License: MIT Imports: 7 Imported by: 2

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.

 

Go Reference Go Tests Go Report Card GitHub Tag License

 

Features

  • Zero Dependencies - Only the Go standard library
  • 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
  • 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

 

🔝 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

 

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

 

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

Constants

This section is empty.

Variables

This section is empty.

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.
	// Use "*" to allow all origins.
	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 added in v1.1.0 

type CheckFunc func() error

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

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 added in v1.1.0 

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

Health manages liveness and readiness probes.

func NewHealth added in v1.1.0 

func NewHealth() *Health

NewHealth creates a new Health manager.

func (*Health) AddLivenessCheck added in v1.1.0 

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) AddReadinessCheck added in v1.1.0 

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) LiveHandler added in v1.1.0 

func (h *Health) LiveHandler() HandlerFunc

LiveHandler returns a Rig HandlerFunc for liveness probes.

func (*Health) ReadyHandler added in v1.1.0 

func (h *Health) ReadyHandler() HandlerFunc

ReadyHandler returns a Rig HandlerFunc for readiness probes.

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.

Example: 

r := rig.New()
r.Use(rig.CORS(rig.CORSConfig{
    AllowOrigins: []string{"https://example.com"},
    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.

Example: 

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

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. This is a convenience method that wraps http.ListenAndServe.

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)

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").

Example: 

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

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.

Source Files

View all Source files

Directories

Path Synopsis
Example demonstrates how to use the rig HTTP library.
 Example demonstrates how to use the rig HTTP library.
render module
swagger module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.