Skip to content

Middleware ​

Added: v1.0.0

Zen middleware has the signature func(*zen.Ctx) - a function that receives the request context. Call c.Next() to pass control downstream; return without calling it to short-circuit. Middleware runs in registration order.

Global Middleware ​

Applied to every route on the router:

go
r := zen.New(":8080")
r.Use(middleware.Recover)
r.Use(middleware.Logger)

Per-Route (Route-Level) Middleware ​

Middleware can be applied to a single route. Pass middleware before the final handler - the LAST argument is the endpoint handler, all preceding arguments are per-route middleware:

go
r.GET("/admin", authMiddleware, adminHandler)

Any number of route-level middleware can be chained:

go
r.POST("/api/data", validateBody, rateLimit, auditLog, createHandler)

This works with all HTTP method helpers: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.

The chain is compiled at startup and executes in this order:

Group Middleware → Route Middleware → Handler → Route Middleware → Group Middleware

Route Group Middleware ​

Applied to all routes in a group (see Route Groups):

go
admin := r.Group("/admin", authMiddleware)
admin.GET("/dashboard", dashboard)

Group and per-route middleware compose:

go
admin := r.Group("/admin", auditMiddleware)
admin.GET("/dashboard", rateLimitMiddleware, dashboardHandler)
// Order: audit → rateLimit → handler

Custom Middleware ​

Write custom middleware to add authentication, logging, rate limiting, or any cross-cutting concern.

Pattern A: Simple Function ​

go
func RequestLogger(c *zen.Ctx) {
    start := time.Now()
    c.Next()
    log.Printf("%s %s took %v", c.Request.Method, c.Request.URL.Path, time.Since(start))
}

r.Use(RequestLogger)

Pattern B: With Configuration (Closure) ​

Return a zen.HandlerFunc from a config function:

go
type LoggerConfig struct {
    Format string
}

func Logger(config LoggerConfig) zen.HandlerFunc {
    return func(c *zen.Ctx) {
        start := time.Now()
        c.Next()
        if config.Format == "json" {
            slog.LogAttrs(c.Request.Context(), slog.LevelInfo, "request",
                slog.String("method", c.Request.Method),
                slog.String("path", c.Request.URL.Path),
                slog.Duration("duration", time.Since(start)),
            )
        }
    }
}

r.Use(Logger(LoggerConfig{Format: "json"}))

Pattern C: With SkipFunc ​

Accept an optional zen.SkipFunc to conditionally bypass middleware:

go
func LoggerWithSkipper(config LoggerConfig, skip zen.SkipFunc) zen.HandlerFunc {
    return func(c *zen.Ctx) {
        if skip != nil && skip(c.Request) {
            c.Next()
            return
        }
        // ... middleware logic ...
        c.Next()
    }
}

zen.SkipFunc is func(*http.Request) bool. Use the helpers in the auth package: zen.SkipPaths, zen.SkipPrefixes, zen.SkipMethodsAndPaths.

Passing Data Between Middleware ​

Use c.Set() and c.Get() to share data across the chain:

go
func LoadUser(c *zen.Ctx) {
    user := fetchUser(c.Request.Header.Get("Authorization"))
    c.Set("user", user)
    c.Next()
}

func RequireAdmin(c *zen.Ctx) {
    user, ok := c.Get("user")
    if !ok || !user.(*User).IsAdmin {
        c.Error(403, "forbidden")
        return
    }
    c.Next()
}

r.GET("/admin", LoadUser, RequireAdmin, adminHandler)

Error Handling in Middleware ​

Set error values on the context or respond directly to short-circuit:

go
func ValidateAPIKey(c *zen.Ctx) {
    key := c.Request.Header.Get("X-API-Key")
    if !isValid(key) {
        c.Error(401, "invalid API key")
        return // short-circuits the chain
    }
    c.Next()
}

func RateLimitMiddleware(c *zen.Ctx) {
    if rateLimitExceeded(c.Request) {
        c.Response.Header().Set("Retry-After", "60")
        c.Error(429, "rate limit exceeded")
        return
    }
    c.Next()
}

Short-Circuiting ​

Stop the chain by returning without calling c.Next():

go
func AuthRequired(c *zen.Ctx) {
    token := c.Request.Header.Get("Authorization")
    if token == "" {
        c.Error(401, "unauthorized")
        return
    }
    c.Next()
}

Order of Execution ​

Middleware runs in registration order. The first middleware registered wraps the next, forming a chain. On each request:

  1. Middleware pre-processing runs from first registered → last registered
  2. The handler runs
  3. Middleware post-processing runs from last registered → first registered
go
r.Use(middleware.Recover)
r.Use(middleware.Logger)

// For a request, the execution order is:
//   Recover (pre) → Logger (pre) → Handler → Logger (post) → Recover (post)

Global, Group, and Per-Route ​

When all three are present, the execution order is:

Global → Group → Per-Route → Handler → Per-Route → Group → Global
go
r.Use(authMiddleware)               // global

admin := r.Group("/admin", audit)   // group
admin.GET("/dashboard", rateLimit, handler) // per-route

// Order: auth → audit → rateLimit → handler

Global middleware runs outermost, then group middleware, then per-route middleware, then the handler - and unwinds in reverse.

Example: Full Stack ​

go
r.Use(middleware.Recover)
r.Use(middleware.RequestID())
r.Use(middleware.Logger)

r.GET("/api/users", listUsers)
// Order: Recover → RequestID → Logger → listUsers
// On panic:  Recover catches it
// On response: Logger logs it with the request ID

Skip Functions ​

Many middleware accept zen.SkipFunc to bypass processing for specific routes:

Released under the MIT License.