Go Context: Deep Dive

Ishan Khan — Fri, 31 Jul 2026 05:41:47 +0000

These notes are part of my personal learning process on Go's context package and its usages — not an AI-generated blog written for the sake of it.

What is context?

In Golang, context.Context is an inbuilt package used majorly for the following reasons in concurrent systems:

Cancel work when it's no longer needed.
Set deadlines/timeouts so work doesn't run forever.
Pass request-scoped values (like a trace ID) across API boundaries — e.g., logged-in user metadata, sharing small data values.

Golang has made context an explicit, first-class convention in the language, so people don't need to create their own abstractions and patterns for these requirements.

Why don't other languages (Java, Python, Node.js, etc.) have something like context?

Every backend language — Java, Python, Node.js, etc. — has one or another mechanism for handling the behaviours addressed by context in Go (thread locals, async locals, cancellationtokens, futures, etc.). Go simply chose to standardize it into a single, explicit type that flows through function signatures.

The core Context interface

// A Context carries a deadline, cancellation signal, and request-scoped values
// across API boundaries. Its methods are safe for simultaneous use by multiple
// goroutines.
type Context interface {
    // Done returns a channel that is closed when this Context is canceled
    // or times out.
    Done() <-chan struct{}

    // Err indicates why this context was canceled, after the Done channel
    // is closed.
    Err() error

    // Deadline returns the time when this Context will be canceled, if any.
    Deadline() (deadline time.Time, ok bool)

    // Value returns the value associated with key or nil if none.
    Value(key interface{}) interface{}
}

The context package provides functions to derive new Context values from existing ones. These values form a tree: when a Context is canceled, all Contexts derived from it arealso canceled.

Background is the root of any Context tree; it is never canceled:

// Background returns an empty Context. It is never canceled, has no deadline,
// and has no values. Background is typically used in main, init, and tests,
// and as the top-level Context for incoming requests.
func Background() Context

`context.Background()` vs `context.TODO()`

Both create an empty context and behave identically at runtime — the difference is purely semantic intent.

context.Background() — Use when you are intentionally starting a root context, i.e., you know this is the top of your context tree.
- Example: the main function of a server, the root of a controller, the start of a background worker, or a long-running goroutine.
context.TODO() — Use as a placeholder when you're unsure which context to use for now, but a proper context definitely should flow through the execution chain later.
- Example: you're mid-refactor, the caller doesn't pass a context yet but should, or you're unsure which context to use.

Usage Examples

API servers / data jobs — Each request is typically handled by a new goroutine. During the lifecycle of a request you may need to make downstream API calls, so context can be used to time out the request if the downstream API doesn't respond within its SLA. You can also pass small request-scoped data through the context (logged-in user ID, name, APM tracedata, etc.). If the request lifecycle spawns more goroutines for parallel operations, the same context can be used to signal cancellation to those child goroutines.
OpenTelemetry instrumentation — Go's OTEL libraries follow correct context patterns very efficiently. Regardless of the framework — Echo, net/http, Gorilla Mux, gRPC, etc. —the OTEL middleware hooks into every incoming request, reads trace propagation data from the HTTP headers, and derives a new context with the remote trace information and a newserver-side span embedded into it. As the request flows through the handler and triggers downstream calls (DBs, external APIs), each call derives yet another child context with a newchild span attached to the parent trace. At no point is any context mutated — every step is a new immutable derived context, forming a chain that mirrors the trace tree.

Functions

Function	Purpose
`context.Background()`	Root context — never cancelled, no values, no deadline. Entry point for all context trees.
`context.TODO()`	Placeholder root — identical to `Background()` at runtime, signals intent to replace later.
`context.WithValue(parent, key, val)`	Derives a new context embedding a key-value pair. No cancellation behaviour.
`context.WithCancel(parent)`	Derives a child that is cancelled when `cancel()` is called or the parent is cancelled.
`context.WithDeadline(parent, time.Time)`	Cancels at an absolute point in time, or when `cancel()` is called.
`context.WithTimeout(parent, duration)`	Sugar over `WithDeadline` — takes a duration instead of an absolute time.
`context.WithCancelCause(parent)`	Like `WithCancel`, but `cancel(err)` attaches a cause retrievable via `context.Cause(ctx)`.
`context.WithDeadlineCause(parent, time.Time, err)`	Like `WithDeadline`, but attaches a cause error when the deadline fires.
`context.WithTimeoutCause(parent, duration, err)`	Like `WithTimeout`, but attaches a cause error when the timeout fires.
`context.WithoutCancel(parent)`	Derives a context that is never cancelled but inherits all values from the parent. Useful for detaching background tasks from the requestlifecycle.
`context.AfterFunc(ctx, f)`	Schedules `f` to run in a new goroutine after `ctx` is cancelled. Does not create a new context.

Memory management

Allocation — where contexts live

Context values almost always escape to the heap rather than living on the stack. The Go compiler determines this via escape analysis, and contexts consistently fail to stay on the stack for three reasons:

They are passed as the Context interface, Interface boxing forces heap allocation
They frequently cross goroutine boundaries
The cancel closure returned by WithCancel/WithTimeout captures a pointer to the context, causing it to outlive the creating function

The only exception is context.Background() and context.TODO() — these are package-level singletons allocated once at program startup in the data segment. Every call to them returns the same pointer, zero allocation.

Best Practices

First parameter convention — Context must always be the first parameter of any function that involves I/O or forwards request-scoped data. Conventionally named ctx.
Immutability
- Always derive a new context from the previous one using the WithX functions. This keeps context objects atomic — child functions or APIs can't screw them up by reference, and it's much safer to use.
Memory management
- WithCancel / WithTimeout / WithDeadline must always be paired with defer cancel(), otherwise you're trading memory for convenience (goroutine/timer leaks until the parent is cancelled).

References

Go dependency injection with Uber Fx and Echo

Ishan Khan — Sat, 23 Nov 2024 09:49:08 +0000

In this post we will go through how to use Uber Fx for dependency injection/singletons with Echo Web framework.

Why Are Singletons and Dependency Injection Important?
Singletons and dependency injection are very important while working with complex backend services, Singletons are important for resource efficiency, thread safety, ex. you cannot create new DB connections for every DB query etc. Dependency injection is useful for creating loosely coupled, testable and flexible code which can be easily extended.

Uber Fx is a dependency injection framework for golang build by Uber which is integrated in all the golang services in Uber to have uniform structure of code across services, code reuse is easier and makes servers efficient.
Echo is one of the most popular go webserver framework known for being high performant, extensible and minimalist.

Case Study: Order Management Service:
Suppose we have a hypothetical Order Management Service, Where have couple of endpoints to fetch user profile details, users orders, order details etc.
The service interacts with multiple databases like MogoDB, Reids, MySQL and other components like Logger, Configuration Loader, HTTP/GRPC Client Services, Other Application Modules/Services(each with its dependencies).
Challenge: These modules rely on shared resources like database connections, logger, HTTP clients etc, Managing them manually initializing, sharing, and wiring dependencies can quickly become overwhelming. Also ensuring all the dependencies are singletons across the project adds another layer of complexity.

Manual initialisations:

func main(){
    redisConenction := db.GetRedisconnection()
    mongoConnection := db.GetMongoConnection()

    orderService := services.NewOrderService(redisConenction, mongoConnection)
    userService := services.NewUserService(redisConenction, mongoConnection, orderService)
    // Other Services...

    // Init controllers
    userController := controllers.NewUserController(userService)
    // Other controller...

    StartEchoServer(controllers)
}

Below is the code snippet required to creating all the services with UberFx.

import (
    "github.com/Ishankhan21/go-fiber-fx/controllers"
    "github.com/Ishankhan21/go-fiber-fx/db"
    "github.com/Ishankhan21/go-fiber-fx/services"
    "go.uber.org/fx"
)

func main() {
    fx.New(
        fx.Provide(
            db.GetRedisconnection,
            db.GetMongoConnection,
            services.NewUserService,
            services.NewOrderService,
            controllers.NewUserController),
        fx.Invoke(StartEchoServer)).Run()
}

Full Code in Github

Implementation Steps:
1.Define Constructors: Create constructors for your dependencies, such as database connections, logger, and HTTP clients.
2.Integrate Uber Fx: Register these constructors with Uber Fx and let it handle initialization and injection.
3.Use Dependencies in Handlers: In your Echo handlers, Uber Fx automatically injects the required dependencies.

Wrapping Up:
By combining Uber Fx with Echo, you can build clean, maintainable, and scalable backend services. Uber Fx handles the complexity of dependency management, allowing you to focus on writing business logic rather than wiring dependencies manually.

References:

DEV Community: Ishan Khan