Backpressure in Microservices

Companion source code for Production Field Manuals: Backpressure in Microservices.

The package implements a small bounded worker queue for Go services. It demonstrates non-blocking enqueue, explicit drop policies, worker lifecycle, context cancellation, deadlines, and dependency overload simulation.

This module keeps the implementation intentionally small:

• bounded admission queue for overload control
• non-blocking TryEnqueue with explicit failure
• worker pool with owned lifecycle
• RejectNew and DropOldest policies
• worker deadlines through context.Context
• metric snapshots without a Prometheus dependency
• local lab with a fake downstream dependency and traffic generator

Quickstart

go test ./...
go run ./examples/basic

Package

q := backpressure.NewQueue[int](backpressure.Config{
    Capacity: 128,
    Workers:  8,
    Policy:   backpressure.RejectNew,
}, func(ctx context.Context, item int) error {
    return nil
})
err := q.TryEnqueue(context.Background(), 42)
_ = q.Close(context.Background())

Lab

The lab uses a fake downstream dependency and a traffic generator:

go run ./examples/lab/dependency
go run ./examples/lab/generator -rps 400 -seconds 20 -capacity 64 -workers 8 -delay-ms 80 -policy reject

The generator is the client-side pressure source for the lab. It creates synthetic incoming jobs at the configured -rps, tries to admit each job into the bounded queue, and reports the queue counters once per second. Accepted jobs are processed by the queue workers, and each worker calls the fake dependency with the configured -delay-ms.

The purpose of the lab is to make overload behavior visible on a local machine. By changing -rps, -capacity, -workers, -delay-ms, and -policy, you can see when work is accepted, rejected, dropped, delayed, or failed, and how bounded queues and worker limits protect both the service and its downstream dependency.

See examples/lab/README.md for failure injection and expected signals.

Production Notes

Use this code as an educational baseline, not a universal library. Real services should connect queue metrics to their telemetry pipeline, tune capacity from measured service time and memory cost, and align the drop policy with product semantics.