Overview - 💧 Mizu

Mizu provides a rich set of middlewares to handle common web application concerns. All middlewares follow these principles:

Zero external dependencies - Only uses Go standard library
Sensible defaults - Works out of the box
Options pattern - Fully configurable when needed
Concurrent safe - Safe for use across goroutines

Installation

Middlewares are included with Mizu. Import the specific middleware you need:

import (
    "github.com/go-mizu/mizu"
    "github.com/go-mizu/mizu/middlewares/recover"
    "github.com/go-mizu/mizu/middlewares/requestid"
    "github.com/go-mizu/mizu/middlewares/timeout"
)

Quick Start

A typical production setup:

package main

import (
    "time"

    "github.com/go-mizu/mizu"
    "github.com/go-mizu/mizu/middlewares/helmet"
    "github.com/go-mizu/mizu/middlewares/ratelimit"
    "github.com/go-mizu/mizu/middlewares/recover"
    "github.com/go-mizu/mizu/middlewares/requestid"
    "github.com/go-mizu/mizu/middlewares/timeout"
)

func main() {
    app := mizu.New()

    // Essential middlewares
    app.Use(recover.New())              // Panic recovery
    app.Use(requestid.New())            // Request tracing
    app.Use(timeout.New(30*time.Second)) // Request timeout
    app.Use(helmet.Default())           // Security headers
    app.Use(ratelimit.PerMinute(100))   // Rate limiting

    app.Get("/", func(c *mizu.Ctx) error {
        return c.Text(200, "Hello, World!")
    })

    app.Listen(":3000")
}

Categories

Authentication

Secure your endpoints with various authentication methods:

Middleware	Description
basicauth	HTTP Basic Authentication
bearerauth	Bearer token authentication
keyauth	API key authentication
csrf	Cross-Site Request Forgery protection
csrf2	Enhanced CSRF with double submit
jwt	JWT token authentication
oauth2	OAuth 2.0 authentication flows
oidc	OpenID Connect authentication

Security

Protect your application from common web vulnerabilities:

Middleware	Description
helmet	Security headers (CSP, HSTS, etc.)
secure	HTTPS enforcement and security features
ipfilter	IP whitelist/blacklist
honeypot	Detect and block malicious requests
captcha	CAPTCHA verification (reCAPTCHA, hCaptcha, Turnstile)
cors	Cross-Origin Resource Sharing
cors2	Enhanced CORS with preflight caching
rbac	Role-based access control
signature	Request signature verification

Rate Limiting & Resilience

Control request rates and protect against overload:

Middleware	Description
ratelimit	Token bucket rate limiting
circuitbreaker	Circuit breaker pattern
bulkhead	Bulkhead isolation pattern
throttle	Request throttling
concurrency	Concurrency limiting
adaptive	Adaptive rate limiting

Request Processing

Validate and transform incoming requests:

Middleware	Description
bodylimit	Limit request body size
contenttype	Validate Content-Type
validator	Request validation rules
header	Header manipulation
methodoverride	HTTP method override
bodyclose	Auto-close request body
bodydump	Dump request/response bodies
requestsize	Request size tracking
sanitizer	Input sanitization
transformer	Request/response transformation
filter	Request filtering

Response Processing

Transform and enhance outgoing responses:

Middleware	Description
compress	Gzip/deflate compression
envelope	Response envelope wrapper
responsesize	Response size tracking
vary	Vary header management
errorpage	Custom error pages
hypermedia	Hypermedia response helpers

Caching

Control HTTP caching behavior:

Middleware	Description
cache	Set Cache-Control headers
nocache	Prevent caching
etag	ETag generation
lastmodified	Last-Modified headers

URL Handling

Redirect and rewrite URLs:

Middleware	Description
redirect	URL redirection (HTTPS, WWW)
slash	Trailing slash handling
rewrite	URL rewriting

Networking & Proxy

Handle proxy headers and reverse proxying:

Middleware	Description
proxy	Reverse proxy
forwarded	X-Forwarded-* headers
realip	Extract real client IP
h2c	HTTP/2 cleartext support
surrogate	CDN surrogate headers

Request Context

Enhance request handling:

Middleware	Description
requestid	Generate/propagate request IDs
timeout	Request timeout
recover	Panic recovery
timing	Server-Timing header
trace	Distributed tracing context
conditional	Conditional middleware execution

Real-time

Support real-time communication:

Middleware	Description
websocket	WebSocket connections
sse	Server-Sent Events

Static Files

Serve static content:

Middleware	Description
static	Static file serving
spa	Single Page Application support
favicon	Favicon serving
embed	Embedded filesystem serving

Operations & Monitoring

Tools for production operations:

Middleware	Description
version	API versioning
maintenance	Maintenance mode
pprof	Profiling endpoints
healthcheck	Health check endpoints
metrics	Custom metrics collection
prometheus	Prometheus metrics endpoint
expvar	Expvar metrics endpoint
logger	Request logging
requestlog	Detailed request logging
responselog	Response logging

Advanced

Specialized functionality:

Middleware	Description
feature	Feature flags
multitenancy	Multi-tenant support
chaos	Chaos engineering
mirror	Request mirroring
fingerprint	Request fingerprinting
canary	Canary deployment routing
audit	Audit logging
idempotency	Idempotency key handling
retry	Automatic request retries
hedge	Hedged requests
fallback	Fallback handlers
mock	Request mocking

Connection & Protocol

Connection and protocol handling:

Middleware	Description
keepalive	Connection keep-alive control
maxconns	Maximum connections limit
msgpack	MessagePack handling
jsonrpc	JSON-RPC protocol support
graphql	GraphQL request handling
xml	XML request/response handling

Internationalization

Locale and timezone handling:

Middleware	Description
language	Language detection
timezone	Timezone detection
nonce	Cryptographic nonce generation

External Integrations

Third-party service integrations:

Middleware	Description
otel	OpenTelemetry integration
sentry	Sentry error tracking
session	Session management

Bot & Client Detection

Client identification and validation:

Middleware	Description
bot	Bot detection
xrequestedwith	X-Requested-With validation

Usage Patterns

Global middleware

Apply to all routes:

app.Use(recover.New())

Route-specific middleware

Apply to specific routes:

app.Get("/admin", adminHandler, basicauth.New(credentials))

Group middleware

Apply to a group of routes:

api := app.Group("/api")
api.Use(keyauth.New(validateKey))

api.Get("/users", listUsers)
api.Post("/users", createUser)

Conditional middleware

Skip middleware based on conditions:

app.Use(ratelimit.WithOptions(ratelimit.Options{
    Rate:     100,
    Interval: time.Minute,
    Skip: func(c *mizu.Ctx) bool {
        return c.Request().URL.Path == "/health"
    },
}))

Best Practices

Order matters - Place recover first to catch all panics
Use timeouts - Always set request timeouts in production
Rate limit - Protect public endpoints from abuse
Security headers - Use helmet for recommended security headers
Request IDs - Add requestid for tracing and debugging

Next Steps

Learn about writing custom middleware
Explore individual middleware documentation in the sidebar

​Installation

​Quick Start

​Categories

​Authentication

​Security

​Rate Limiting & Resilience

​Request Processing

​Response Processing

​Caching

​URL Handling

​Networking & Proxy

​Request Context

​Real-time

​Static Files

​Operations & Monitoring

​Advanced

​Connection & Protocol

​Internationalization

​External Integrations

​Bot & Client Detection

​Usage Patterns

​Global middleware

​Route-specific middleware

​Group middleware

​Conditional middleware

​Best Practices

​Next Steps