Middleware

Okapi Middleware

Middleware and MiddlewareFunc are type aliases of HandlerFunc — func(*Context) error. Inside a middleware, call c.Next() to pass control down the chain. Anything before c.Next() runs on the way in, anything after runs on the way out.

func custom(c *okapi.Context) error {
    start := time.Now()
    err := c.Next()
    log.Printf("Request took %v", time.Since(start))
    return err
}

o.Use(custom)

> Signature change (v0.5.0). Middleware is no longer func(next HandlerFunc) HandlerFunc. Drop the outer wrapper and replace next(c) with c.Next(): > > ``go > // Before (v0.4.x) // After (v0.5.0+) > func mw(next okapi.HandlerFunc) okapi.HandlerFunc { func mw(c *okapi.Context) error { > return func(c *okapi.Context) error { err := c.Next() > err := next(c) return err > return err } > } > } > ` > > A middleware that needs configuration returns a closure with the new signature: func RateLimit(rps int) okapi.Middleware { return func(c *okapi.Context) error { ... } }`.

Built-in Middleware

| Middleware | Purpose | |------------|---------| | okapi.LoggerMiddleware | Structured access logging (method, URL, IP, status, duration, referer, UA). Skips WebSocket upgrades and SSE streams. Enabled in okapi.Default(). | | okapi.RequestID() | Reads X-Request-ID or generates a UUID; stores in context ("request_id") and echoes the header. | | okapi.BasicAuth{...}.Middleware | Basic auth — constant-time compare; sends WWW-Authenticate on failure. | | okapi.JWTAuth{...}.Middleware | JWT validation (HS256 / RS256 / JWKS), claims expression DSL, claim forwarding. | | `okapi.BodyLimit{MaxBytes: 1 RequestID -> cacheMiddleware -> handler

### Standard Library Middleware Bridge

`UseMiddleware` accepts the classic `func(http.Handler) http.Handler` signature, so the whole net/http ecosystem (Gorilla handlers, gziphandler, otelhttp, etc.) plugs in directly:

```go
import "github.com/gorilla/handlers"

o.UseMiddleware(handlers.CORS(
    handlers.AllowedOrigins([]string{"*"}),
    handlers.AllowedMethods([]string{"GET", "POST"}),
))

Writing a Reusable Middleware

func RateLimit(rps int) okapi.Middleware {
    bucket := newBucket(rps)
    return func(c *okapi.Context) error {
        if !bucket.Allow() {
            return c.AbortTooManyRequests("rate limit exceeded")
        }
        return c.Next()
    }
}

o.Use(RateLimit(100))
api.Use(RateLimit(20)) // tighter limit on /api

Aborting in Middleware

Return a non-nil error from c.Abort* to short-circuit the chain. Do not call c.Next() afterwards.

func requireTenant(c *okapi.Context) error {
    if c.Header("X-Tenant") == "" {
        return c.AbortBadRequest("X-Tenant header is required")
    }
    return c.Next()
}

The response is committed once an Abort* helper runs, so a later write elsewhere in the chain is a silent no-op — always propagate the returned error.

Middleware and Standard Handlers

The chain applies to HandleStd / HandleHTTP routes too, but those handlers receive (http.ResponseWriter, *http.Request) rather than *Context. Middleware written against *Context still runs; see the std_compat/ skill.

Related Skills

• Auth middleware configuration (JWT, Basic, CORS): authentication/
• Runtime enable/disable of routes and groups: dynamic_routes/
• net/http middleware interop: std_compat/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jkaninda
• Source: jkaninda/okapi-skills
• License: MIT

Install and usage instructions live in the source repository linked above.