existential-birds/beagle / plugins/beagle-go/skills/go-middleware
go-middleware
VerifiedIdiomatic Go HTTP middleware patterns with context propagation, structured logging via slog, centralized error handling, and panic recovery. Use when writing middleware, adding request tracing, or implementing cross-cutting concerns.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/context-propagation.md | markdown | 6.9 KB |
| references/error-handling-middleware.md | markdown | 8.6 KB |
| references/structured-logging.md | markdown | 7.7 KB |
references/context-propagation.md
View on GitHub# Context Propagation in Go Middleware
## Type-Safe Context Keys
Never use plain `string` or `int` as context keys. Define an unexported type so keys from different packages cannot collide.
```go
// Define in your middleware package
type contextKey string
const (
requestIDKey contextKey = "request_id"
userKey contextKey = "user"
tenantIDKey contextKey = "tenant_id"
)
```
Why this matters:
- `context.WithValue` uses interface equality for key comparison
- Two packages using `"user"` as a string key would overwrite each other
- An unexported `contextKey` type is unique to your package
## Request ID Propagation
Assign a request ID early in the middleware chain. Propagate it through context so every layer can include it in logs, error reports, and outgoing requests.
```go
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))
})
}
func RequestIDFromContext(ctx context.Context) string {
id, _ := ctx.Value(requestIDKey).(string)
return id
}
```
Usage in downstream code:
```go
func handleOrder(w http.ResponseWriter, r *http.Request) {
reqID := RequestIDFromContext(r.Context())
slog.Info("processing order", "request_id", reqID)
// Pass to outgoing HTTP calls
outReq, _ := http.NewRequestWithContext(r.Context(), "GET", url, nil)
outReq.Header.Set("X-Request-ID", reqID)
}
```
## User Metadata
Store authenticated user information in context after validation in auth middleware.
```go
type User struct {
ID string
Email string
Roles []string
}
const userKey contextKey = "user"
func AuthMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
user, err := validateToken(token)
if err != nil {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
ctx := context.WithValue(r.Context(), userKey, user)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
func UserFromContext(ctx context.Context) (*User, bool) {
u, ok := ctx.Value(userKey).(*User)
return u, ok
}
```
### Multi-Tenant Context
For multi-tenant applications, propagate the tenant ID alongside the user:
```go
const tenantIDKey contextKey = "tenant_id"
func TenantMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
user, ok := UserFromContext(r.Context())
if !ok {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
tenantID := extractTenantID(user)
ctx := context.WithValue(r.Context(), tenantIDKey, tenantID)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
func TenantIDFromContext(ctx context.Context) string {
id, _ := ctx.Value(tenantIDKey).(string)
return id
}
```
## Typed Helper Functions
Always provide exported helper functions for extracting context values. This encapsulates the key and type assertion in one place.
```go
// Good: callers use typed helpers
user, ok := UserFromContext(ctx)
reqID := RequestIDFromContext(ctx)
tenantID := TenantIDFromContext(ctx)
// Bad: callers reach into context directly
user := ctx.Value("user").(*User) // unsafe, untyped key
```
Always check the `ok` return from type assertions:
```go
func UserFromContext(ctx context.Context) (*User, bool) {
u, ok := ctx.Value(userKey).(*User)
return u, ok
}
// In handlers
user, ok := UserFromContext(r.Context())
if !ok {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
```
## Passing Context to Downstream Services
### Database Queries
Pass `r.Context()` to database calls so they respect request cancellation:
```go
func getUser(ctx context.Context, db *sql.DB, id string) (*User, error) {
row := db.QueryRowContext(ctx, "SELECT id, email FROM users WHERE id = $1", id)
var u User
if err := row.Scan(&u.ID, &u.Email); err != nil {
return nil, fmt.Errorf("querying user %s: %w", id, err)
}
return &u, nil
}
```
### Outgoing HTTP Requests
Use `http.NewRequestWithContext` to propagate cancellation and pass along tracing headers:
```go
func callDownstream(ctx context.Context, url string) (*http.Response, error) {
req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return nil, fmt.Errorf("creating request: %w", err)
}
req.Header.Set("X-Request-ID", RequestIDFromContext(ctx))
return http.DefaultClient.Do(req)
}
```
## Context Timeout and Cancellation
For long operations, derive a context with a timeout to prevent requests from hanging:
```go
func slowHandler(w http.ResponseWriter, r *http.Request) {
// Give the operation 5 seconds max
ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
defer cancel()
result, err := longRunningQuery(ctx)
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
http.Error(w, "request timed out", http.StatusGatewayTimeout)
return
}
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(result)
}
```
### Timeout Middleware
Apply a blanket timeout to all requests:
```go
func Timeout(duration time.Duration) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx, cancel := context.WithTimeout(r.Context(), duration)
defer cancel()
next.ServeHTTP(w, r.WithContext(ctx))
})
}
}
```
Note: this cancels the context but does not stop the handler goroutine. Handlers must check `ctx.Done()` or use context-aware I/O to actually stop work.
## Anti-patterns
### Using context.WithValue for function parameters
```go
// BAD: hiding dependencies in context
ctx = context.WithValue(ctx, "db", db)
// ...later...
db := ctx.Value("db").(*sql.DB)
// GOOD: explicit parameter
func handleOrder(ctx context.Context, db *sql.DB, orderID string) error {
// ...
}
```
Context is for request-scoped metadata that crosses API boundaries, not for dependency injection.
### Storing large objects in context
```go
// BAD: large payload in context
ctx = context.WithValue(ctx, "body", largeRequestBody)
// GOOD: pass as parameter or store a reference/ID
ctx = context.WithValue(ctx, requestIDKey, reqID)
```
### Not checking ok from type assertion
```go
// BAD: panics if value is nil or wrong type
user := ctx.Value(userKey).(*User)
// GOOD: always check
user, ok := ctx.Value(userKey).(*User)
if !ok {
return ErrUnauthorized
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |