From beagle-go
Provides idiomatic Go HTTP middleware for context propagation, structured slog logging, error handling, and panic recovery. Use when writing middleware, adding request tracing, or cross-cutting concerns.
How this skill is triggered — by the user, by Claude, or both
Slash command
/beagle-go:go-middlewareThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
| Topic | Reference |
| Topic | Reference |
|---|---|
| Context keys, request IDs, user metadata | references/context-propagation.md |
| slog setup, logging middleware, child loggers | references/structured-logging.md |
| AppHandler pattern, domain errors, recovery | references/error-handling-middleware.md |
All middleware follows the standard func(http.Handler) http.Handler pattern. This is the composable building block for cross-cutting concerns in Go HTTP servers.
// Standard middleware signature
func RequestID(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := r.Header.Get("X-Request-ID")
if id == "" {
id = uuid.New().String()
}
ctx := context.WithValue(r.Context(), requestIDKey, id)
w.Header().Set("X-Request-ID", id)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
// Type-safe context keys
type contextKey string
const requestIDKey contextKey = "request_id"
func RequestIDFromContext(ctx context.Context) string {
id, _ := ctx.Value(requestIDKey).(string)
return id
}
Key points:
http.Handler, return http.Handler -- alwaysnext.ServeHTTP(w, r) to pass control to the next handlerr.WithContext(ctx) to propagate new context values downstreamUse context.WithValue for request-scoped data that crosses API boundaries (request IDs, authenticated users, tenant IDs). Always use typed keys to avoid collisions.
type contextKey string
const (
requestIDKey contextKey = "request_id"
userKey contextKey = "user"
)
Provide typed helper functions for extraction:
func RequestIDFromContext(ctx context.Context) string {
id, _ := ctx.Value(requestIDKey).(string)
return id
}
See references/context-propagation.md for user metadata patterns, downstream propagation, and timeouts.
Use slog (standard library, Go 1.21+) for structured logging in middleware. Wrap http.ResponseWriter to capture the status code.
func Logger(logger *slog.Logger) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
wrapped := &statusWriter{ResponseWriter: w, status: http.StatusOK}
next.ServeHTTP(wrapped, r)
logger.Info("request completed",
"method", r.Method,
"path", r.URL.Path,
"status", wrapped.status,
"duration_ms", time.Since(start).Milliseconds(),
"request_id", RequestIDFromContext(r.Context()),
)
})
}
}
See references/structured-logging.md for JSON/text handler setup, log levels, and child loggers.
Define a custom handler type that returns error so handlers don't need to write error responses themselves:
type AppHandler func(w http.ResponseWriter, r *http.Request) error
func (fn AppHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if err := fn(w, r); err != nil {
handleError(w, r, err)
}
}
Map domain errors to HTTP status codes in a single handleError function. Never leak internal error details to clients.
See references/error-handling-middleware.md for the full pattern with AppError, errors.As, and JSON responses.
Catch panics to prevent a single bad request from crashing the server:
func Recovery(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if rec := recover(); rec != nil {
slog.Error("panic recovered",
"panic", rec,
"stack", string(debug.Stack()),
"request_id", RequestIDFromContext(r.Context()),
)
writeJSON(w, 500, map[string]string{"error": "internal server error"})
}
}()
next.ServeHTTP(w, r)
})
}
Recovery must be the outermost middleware so it catches panics from all inner middleware and handlers. See references/error-handling-middleware.md for details.
Apply middleware outermost-first. The first middleware in the chain wraps all others.
// Nested style (outermost first)
handler := Recovery(
RequestID(
Logger(
Auth(
router,
),
),
),
)
// Or with a chain helper
func Chain(h http.Handler, middleware ...func(http.Handler) http.Handler) http.Handler {
for i := len(middleware) - 1; i >= 0; i-- {
h = middleware[i](h)
}
return h
}
handler := Chain(router, Recovery, RequestID, Logger(slog.Default()), Auth)
// BAD: collisions with other packages
ctx = context.WithValue(ctx, "user", user)
// GOOD: unexported typed key
type contextKey string
const userKey contextKey = "user"
ctx = context.WithValue(ctx, userKey, user)
// BAD: writes response then continues chain
func Bad(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK) // too early!
next.ServeHTTP(w, r)
})
}
// BAD: swallows the request
func Bad(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
log.Println("got request")
// forgot next.ServeHTTP(w, r)
})
}
Context values should be small, request-scoped metadata (IDs, tokens, user structs). Never store database connections, file handles, or large payloads.
If a function needs a value to do its job, pass it as an explicit parameter. Context is for cross-cutting metadata that passes through APIs, not for avoiding function signatures.
If recovery is not the outermost middleware, panics in outer middleware will crash the server. Always apply recovery first.
npx claudepluginhub existential-birds/beagle --plugin beagle-goComposes structured logging pipelines in Go using samber/slog-* packages — multi-handler, sampling, formatting, HTTP middleware, and backend routing to Datadog, Sentry, Loki, etc.
Provides idiomatic Go patterns for backend APIs with Gin, Echo, Fiber: standard project structure, custom error handling, handler dependency injection, concurrency best practices.
Guides stacking of recovery, logger, and publisher middleware in Go event-driven services using the xgodev/boost bootstrap framework.