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 focused set of features for building web applications in Go. Each feature is designed to feel familiar if you already know Go’s standard library.
Routing
Routing connects URLs to handler functions. Mizu uses Go 1.22’s enhanced ServeMux which supports path parameters natively.
app.Get("/users/{id}", getUser) // GET /users/123
app.Post("/users", createUser) // POST /users
app.Delete("/users/{id}", deleteUser) // DELETE /users/123
- Path parameters using
{param} syntax (Go 1.22 ServeMux patterns)
- HTTP method helpers:
Get, Post, Put, Patch, Delete, Head, Connect, Trace
- Route groups with
Group() and Prefix() for organizing related endpoints
- Scoped middleware with
With() to apply middleware to specific routes
- Mount http.Handler with
Mount() for interoperability with standard handlers
// Group routes under a prefix
app.Group("/api", func(r *mizu.Router) {
r.Get("/users", listUsers) // GET /api/users
r.Get("/users/{id}", getUser) // GET /api/users/123
})
Request handling
Reading data from requests is explicit and straightforward. Each method does one thing clearly.
| Method | Purpose | Example |
|---|
c.Param("id") | Path parameter from URL | /users/{id} → c.Param("id") |
c.Query("page") | Single query parameter | ?page=2 → c.Query("page") |
c.QueryValues() | All query parameters | Returns url.Values |
c.Form() | Form data (POST) | Returns url.Values, error |
c.MultipartForm(max) | File uploads | Returns form, cleanup, error |
c.BindJSON(&v, max) | JSON body to struct | Validates and parses |
c.Cookie("name") | Read a cookie | Returns *http.Cookie, error |
func getUser(c *mizu.Ctx) error {
// Path parameter from /users/{id}
id := c.Param("id")
// Query parameter from ?include=email
include := c.Query("include")
return c.JSON(200, map[string]string{"id": id, "include": include})
}
Response helpers
Response methods write data with appropriate headers and status codes.
| Method | Content-Type | Usage |
|---|
c.Text(code, s) | text/plain | Plain text responses |
c.JSON(code, v) | application/json | Structs, maps, slices |
c.HTML(code, s) | text/html | HTML strings |
c.File(code, path) | Auto-detected | Serve files from disk |
c.Download(code, path, name) | With disposition | Force download |
c.Stream(fn) | Custom | Streaming responses |
c.SSE(ch) | text/event-stream | Server-Sent Events |
c.Redirect(code, url) | - | HTTP redirects |
c.NoContent() | - | 204 No Content |
// Return JSON
return c.JSON(200, user)
// Serve a file with content-type auto-detection
return c.File(200, "./public/image.png")
// Force browser to download with a specific filename
return c.Download(200, "./reports/data.csv", "report-2024.csv")
Middleware
Middleware wraps handlers to add behavior before or after request processing. The pattern is simple: take a handler, return a handler.
type Middleware func(Handler) Handler
// Global middleware - runs for all routes
app.Use(myMiddleware)
// Scoped middleware - only for routes on this router
admin := app.With(authRequired)
admin.Get("/settings", adminSettings)
// Standard net/http middleware works too
app.Compat.Use(existingMiddleware)
func timing() mizu.Middleware {
return func(next mizu.Handler) mizu.Handler {
return func(c *mizu.Ctx) error {
start := time.Now()
err := next(c)
c.Logger().Info("request", "duration", time.Since(start))
return err
}
}
}
Logging
Mizu includes a request logger that uses Go’s slog package for structured logging.
// Built-in logger is enabled by default
app := mizu.New() // Includes Logger middleware
// Access the logger in any handler
c.Logger().Info("processing", "user_id", userID)
// Configure logging behavior
app.Use(mizu.Logger(mizu.LoggerOptions{
Mode: mizu.Dev, // Dev (text) or Prod (JSON)
Color: true, // Colored output for terminals
UserAgent: true, // Include User-Agent in logs
}))
mizu.Auto - Colored text for terminals, JSON for non-terminals (default)mizu.Dev - Human-readable text formatmizu.Prod - JSON lines for log collectors
Error handling
Handlers return errors directly. Mizu catches returned errors and recovered panics in one central place.
// Handlers can return errors
func getUser(c *mizu.Ctx) error {
user, err := findUser(c.Param("id"))
if err != nil {
return err // Caught by error handler
}
return c.JSON(200, user)
}
// Set a global error handler
app.ErrorHandler(func(c *mizu.Ctx, err error) {
// Check for panics
if perr, ok := err.(*mizu.PanicError); ok {
c.Logger().Error("panic", "value", perr.Value)
}
c.JSON(500, map[string]string{"error": "internal error"})
})
Server lifecycle
Mizu handles graceful shutdown automatically. When your server receives SIGINT (Ctrl+C) or SIGTERM, it:
- Stops accepting new connections
- Waits for active requests to complete (up to timeout)
- Shuts down cleanly
app := mizu.New()
// Configure shutdown timeout (default: 15 seconds)
app.ShutdownTimeout = 30 * time.Second
// Start methods
app.Listen(":3000") // HTTP
app.ListenTLS(":443", "cert.pem", "key.pem") // HTTPS
app.Serve(listener) // Custom listener
// Liveness probe - always returns 200
http.Handle("/livez", app.LivezHandler())
// Readiness probe - returns 503 during shutdown
http.Handle("/readyz", app.ReadyzHandler())
Static files
Serve files from disk or embedded filesystems.
// Serve ./public folder at /assets
app.Static("/assets/", http.Dir("public"))
// Access: /assets/logo.png → ./public/logo.png
// Serve embedded files (Go 1.16+)
//go:embed public/*
var publicFS embed.FS
sub, _ := fs.Sub(publicFS, "public")
app.Static("/assets/", http.FS(sub))
Summary
Mizu stays small and predictable. Everything is plain Go code with no hidden behavior.
| Category | Key point |
|---|
| Routing | Go 1.22 ServeMux patterns with {param} syntax |
| Request | Explicit methods: Param, Query, Form, BindJSON |
| Response | Type helpers: Text, JSON, HTML, File, SSE |
| Middleware | Simple func(Handler) Handler signature |
| Logging | Built-in with slog, configurable modes |
| Errors | Return from handlers, catch in one place |
| Lifecycle | Graceful shutdown with configurable timeout |