Golang Context

1---2name: golang-context3description: "Idiomatic context.Context usage in Golang — creation, propagation, cancellation, timeouts, deadlines, context values, and cross-service tracing. Apply when working with context.Context in any Go code."4user-invocable: true5license: MIT6compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.7metadata:8  author: samber9  version: "1.1.1"10  openclaw:11    emoji: "🔗"12    homepage: https://github.com/samber/cc-skills-golang13    requires:14      bins:15        - go16    install: []17allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent18---19 20> **Community default.** A company skill that explicitly supersedes `samber/cc-skills-golang@golang-context` skill takes precedence.21 22# Go context.Context Best Practices23 24`context.Context` is Go's mechanism for propagating cancellation signals, deadlines, and request-scoped values across API boundaries and between goroutines. Think of it as the "session" of a request — it ties together every operation that belongs to the same unit of work.25 26## Best Practices Summary27 281. The same context MUST be propagated through the entire request lifecycle: HTTP handler → service → DB → external APIs292. `ctx` MUST be the first parameter, named `ctx context.Context`303. NEVER store context in a struct — pass explicitly through function parameters314. NEVER pass `nil` context — use `context.TODO()` if unsure325. `cancel()` MUST always be deferred immediately after `WithCancel`/`WithTimeout`/`WithDeadline`336. `context.Background()` MUST only be used at the top level (main, init, tests)347. **Use `context.TODO()`** as a placeholder when you know a context is needed but don't have one yet358. NEVER create a new `context.Background()` in the middle of a request path369. Context value keys MUST be unexported types to prevent collisions3710. Context values MUST only carry request-scoped metadata — NEVER function parameters3811. **Use `context.WithoutCancel`** (Go 1.21+) when spawning background work that must outlive the parent request39 40## Creating Contexts41 42| Situation | Use |43| --- | --- |44| Entry point (main, init, test) | `context.Background()` |45| Function needs context but caller doesn't provide one yet | `context.TODO()` |46| Inside an HTTP handler | `r.Context()` |47| Need cancellation control | `context.WithCancel(parentCtx)` |48| Need a deadline/timeout | `context.WithTimeout(parentCtx, duration)` |49 50## Context Propagation: The Core Principle51 52The most important rule: **propagate the same context through the entire call chain**. When you propagate correctly, cancelling the parent context cancels all downstream work automatically.53 54```go55// ✗ Bad — creates a new context, breaking the chain56func (s *OrderService) Create(ctx context.Context, order Order) error {57    return s.db.ExecContext(context.Background(), "INSERT INTO orders ...", order.ID)58}59 60// ✓ Good — propagates the caller's context61func (s *OrderService) Create(ctx context.Context, order Order) error {62    return s.db.ExecContext(ctx, "INSERT INTO orders ...", order.ID)63}64```65 66## Deep Dives67 68- **[Cancellation, Timeouts & Deadlines](./references/cancellation.md)** — How cancellation propagates: `WithCancel` for manual cancellation, `WithTimeout` for automatic cancellation after a duration, `WithDeadline` for absolute time deadlines. Patterns for listening (`<-ctx.Done()`) in concurrent code, `AfterFunc` callbacks, and `WithoutCancel` for operations that must outlive their parent request (e.g., audit logs).69 70- **[Context Values & Cross-Service Tracing](./references/values-tracing.md)** — Safe context value patterns: unexported key types to prevent namespace collisions, when to use context values (request ID, user ID) vs function parameters. Trace context propagation: OpenTelemetry trace headers, correlation IDs for log aggregation, and marshaling/unmarshaling context across service boundaries.71 72- **[Context in HTTP Servers & Service Calls](./references/http-services.md)** — HTTP handler context: `r.Context()` for request-scoped cancellation, middleware integration, and propagating to services. HTTP client patterns: `NewRequestWithContext`, client timeouts, and retries with context awareness. Database operations: always use `*Context` variants (`QueryContext`, `ExecContext`) to respect deadlines.73 74## Cross-References75 76- → See the `samber/cc-skills-golang@golang-concurrency` skill for goroutine cancellation patterns using context77- → See the `samber/cc-skills-golang@golang-database` skill for context-aware database operations (QueryContext, ExecContext)78- → See the `samber/cc-skills-golang@golang-observability` skill for trace context propagation with OpenTelemetry79- → See the `samber/cc-skills-golang@golang-design-patterns` skill for timeout and resilience patterns80 81## Enforce with Linters82 83Many context pitfalls are caught automatically by linters: `govet`, `staticcheck`. → See the `samber/cc-skills-golang@golang-linter` skill for configuration and usage.