Documentation Index
Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
Use this file to discover all available pages before exploring further.
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:
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