Documentation
¶
Overview ¶
Package authz provides role-based authorization middleware.
NewRequireRoleMiddleware keeps the v2-compatible single-return constructor shape. Invalid configuration fails closed at request time. Use NewRequireRoleMiddlewareChecked when application startup should fail fast on an empty required role or nil RolesFromContext resolver.
During route wiring, use ValidateRequireRoleMiddleware(method, route, middleware) or ValidateRequireRoleMiddlewareRoutes for startup checks over route registries.
Route registry recommendation:
checks := []authz.RequireRoleRouteSpec{
{Method: http.MethodGet, Route: "/admin", Middleware: adminMw},
{Method: http.MethodPost, Route: "/billing", Middleware: billingMw},
}
if err := authz.ValidateRequireRoleMiddlewareRoutes(checks); err != nil {
return fmt.Errorf("route contract scan failed: %w", err)
}
chi route bootstrap helper:
if err := chiAdapter.ValidateRequireRoleMiddlewareRoutes(router.Mux, func(method, route string, _ http.Handler) *authz.RequireRoleMiddleware {
switch route {
case "/admin":
return adminMw
}
return nil
}); err != nil {
return fmt.Errorf("route contract scan failed: %w", err)
}
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrRequireRoleMissingResolver = errors.New("rolesFromContext resolver is missing")
ErrRequireRoleMissingResolver indicates RolesFromContext was not configured.
var ErrRequireRoleMissingRole = errors.New("required role is missing")
ErrRequireRoleMissingRole indicates required role was not provided.
Functions ¶
func ValidateRequireRoleMiddleware ¶ added in v2.1.0
func ValidateRequireRoleMiddleware(method, route string, middleware *RequireRoleMiddleware) error
ValidateRequireRoleMiddleware validates a configured role middleware against route and method context. Use this during bootstrap to fail fast on missing role wiring before serving traffic.
func ValidateRequireRoleMiddlewareRoutes ¶ added in v2.1.0
func ValidateRequireRoleMiddlewareRoutes(routes []RequireRoleRouteSpec) error
ValidateRequireRoleMiddlewareRoutes validates a route registry in one pass.
Useful at startup for CI and server bootstrap to fail fast when a route middleware is missing required role wiring.
Types ¶
type RequireRoleMiddleware ¶
type RequireRoleMiddleware struct {
// contains filtered or unexported fields
}
RequireRoleMiddleware enforces a required role for a request.
func NewRequireRoleMiddleware ¶
func NewRequireRoleMiddleware(role string, rolesFromCtx RolesFromContext) *RequireRoleMiddleware
NewRequireRoleMiddleware constructs a role enforcement middleware.
This constructor keeps the v2-compatible single-return shape. Invalid configuration is retained on the middleware and fails closed at request time; callers that want startup validation should use NewRequireRoleMiddlewareChecked or ValidateRequireRoleMiddleware.
func NewRequireRoleMiddlewareChecked ¶ added in v2.1.0
func NewRequireRoleMiddlewareChecked(role string, rolesFromCtx RolesFromContext) (*RequireRoleMiddleware, error)
NewRequireRoleMiddlewareChecked constructs a role enforcement middleware and returns configuration errors for startup validation.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"github.com/aatuh/api-toolkit/v2/middleware/auth/authz"
)
func main() {
rolesFromContext := func(context.Context) []string {
return []string{"admin"}
}
admin, err := authz.NewRequireRoleMiddlewareChecked("admin", rolesFromContext)
if err != nil {
panic(err)
}
if err := authz.ValidateRequireRoleMiddlewareRoutes([]authz.RequireRoleRouteSpec{
{Method: http.MethodGet, Route: "/admin", Middleware: admin},
}); err != nil {
panic(err)
}
fmt.Println("authz startup checks passed")
}
Output: authz startup checks passed
type RequireRoleRouteSpec ¶ added in v2.1.0
type RequireRoleRouteSpec struct {
Method string
Route string
Middleware *RequireRoleMiddleware
}
RequireRoleRouteSpec provides route-level metadata for bootstrap validation.
type RolesFromContext ¶
RolesFromContext returns the roles associated with the current request context. Callers should return a stable slice (copy if needed) if the backing store is mutable.
Source Files