transit

README

transit

Shared HTTP & gRPC transport middleware for Go services — logging, OpenTelemetry, circuit breaking, rate limiting and retry, framework-free

Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base. Docs: transit.go.phpboyscout.uk

---

gitlab.com/phpboyscout/go/transit — the reusable transport middleware shared by a Go service's HTTP and gRPC edges: structured request logging, OpenTelemetry instrumentation, circuit breaking, rate limiting and client-side retry, plus the resilience primitives (a circuit breaker and a keyed token-bucket store) they are built on.

It is the middleware layer extracted from go-tool-base, which consumes it behind its pkg/http and pkg/grpc server/client constructors. It is framework-free: it carries the gRPC SDK and the OpenTelemetry gRPC/HTTP contrib instrumentation (that is the middleware's job) but nothing else — no config framework, no TUI, no go-tool-base.

Design

• Framework-free. Dependencies are the gRPC SDK, the OTel contrib instrumentation, golang.org/x/time/rate, go/redact and cockroachdb/errors. A depfootprint_test.go guard forbids go-tool-base, Viper/Cobra, Charm and the cloud SDKs.
• *slog.Logger at the seam. Middleware that logs takes a plain *slog.Logger, so nothing here depends on a logging framework.
• Client and server, both transports. Each of http and grpc provides server handlers/interceptors and client round-trippers/interceptors, so a service and the clients it calls share one implementation of each concern.
• Resilience is one package. The circuit breaker and the rate-limiter store live together in resilience; the HTTP and gRPC layers wrap them into transport-shaped middleware.

Install

go get gitlab.com/phpboyscout/go/transit

Quick start

package main

import (
	"log/slog"
	"net/http"

	transithttp "gitlab.com/phpboyscout/go/transit/http"
)

func main() {
	log := slog.Default()

	chain := transithttp.NewChain(
		transithttp.LoggingMiddleware(log),
		transithttp.OTelMiddleware("my-service"),
	)

	mux := http.NewServeMux()
	// mux.Handle("/", ...)

	_ = http.ListenAndServe(":8080", chain.Then(mux))
}

What's inside

• resilience — the transport-neutral primitives: a Breaker (closed → open → half-open state machine) and a keyed token-bucket Store for rate limiting.
• http — server middleware (NewChain, LoggingMiddleware, OTelMiddleware, WithCircuitBreaker, RateLimitMiddleware) and client round-trippers (NewRetryTransport, the ClientChain with WithBearerToken / WithBasicAuth / WithRateLimit / WithRequestLogging).
• grpc — server interceptors (NewInterceptorChain, LoggingInterceptor, OTelStatsHandler, CircuitBreakerInterceptor, RateLimitInterceptor) and the OTelClientHandler client dial option.

Compatibility

The gRPC and OpenTelemetry dependency versions are pinned and kept in lockstep with go-tool-base (currently grpc v1.82.0, otel v1.44.0 and the gRPC/HTTP contrib instrumentation) so a service and this module share one build graph. Grouped Renovate updates keep them aligned.

Documentation

Full guides and the middleware model: transit.go.phpboyscout.uk. API reference: pkg.go.dev.

License

See LICENSE.