Skip to content

Reference

Every exported constructor, config field and default in transit, with what happens when a value is wrong. Four pages, one per package boundary:

  • HTTP server middleware — Chain, LoggingMiddleware, OTelMiddleware, RateLimitMiddleware, ClientIPKey.
  • HTTP client middleware — ClientChain, NewRetryTransport, WithCircuitBreaker, WithBearerToken, WithBasicAuth, WithRateLimit, WithRequestLogging.
  • gRPC interceptors — InterceptorChain, LoggingInterceptor, RateLimitInterceptor, OTelStatsHandler, OTelClientHandler, CircuitBreakerInterceptor, PeerKey.
  • resilience primitives — Breaker and Store, the transport-neutral core both transports wrap.

Signatures and doc comments are also published on pkg.go.dev. These pages carry the behaviour that a signature does not show: clamping rules, precedence between fields, and the failure mode of a bad value.

Every default in one table

Setting Package Default Set by
Log format http FormatStructured WithFormat
Log level for successful requests http, grpc slog.LevelInfo WithLogLevel, WithGRPCLogLevel
Trust X-Forwarded-For / X-Real-IP http off WithTrustedProxy
Logged header value length cap http 256 bytes not configurable
Rate limit — requests per second http, grpc 50 RateLimitConfig.RequestsPerSecond
Rate limit — burst http, grpc 100 RateLimitConfig.Burst
Rate limit — tracked keys http, grpc, resilience 8192 RateLimitConfig.MaxTrackedKeys
Rate limit — key function http, grpc nil (one global bucket) RateLimitConfig.KeyFunc
Retry — attempts after the first http 3 RetryConfig.MaxRetries
Retry — initial backoff http 500ms RetryConfig.InitialBackoff
Retry — backoff cap http 30s RetryConfig.MaxBackoff
Retry — status codes http 429, 502, 503, 504 RetryConfig.RetryableStatusCodes
Retry — eligible methods http GET, HEAD, OPTIONS, PUT, DELETE RetryConfig.RetryableMethods
Circuit breaker — failures to trip http, grpc, resilience 5 CircuitBreakerConfig.FailureThreshold
Circuit breaker — cooldown http, grpc, resilience 30s CircuitBreakerConfig.Cooldown
Circuit breaker — half-open trials http, grpc, resilience 1 CircuitBreakerConfig.HalfOpenMaxRequests

The circuit-breaker and key-store defaults are exported by the resilience package — DefaultFailureThreshold, DefaultCooldown, DefaultHalfOpenMax and DefaultMaxTrackedKeys — so both transports and any caller reference one source of truth. The rate and burst figures, and the retry defaults, are unexported package constants; read them from DefaultRateLimitConfig() and DefaultRetryConfig() rather than hard-coding them.

What a zero-value config does

Two of the three config structs are safe to leave zero; one is not.

Struct Zero value behaviour
http.RateLimitConfig{} / grpc.RateLimitConfig{} Clamped to the defaults above — 50 rps, burst 100, one global bucket.
http.CircuitBreakerConfig{} / grpc.CircuitBreakerConfig{} Clamped to the defaults above — trip at 5, 30s cooldown, 1 trial.
http.RetryConfig{} Not clamped to the defaults. MaxRetries is 0, so the transport makes exactly one attempt and never retries. Use DefaultRetryConfig() to get retries.

The asymmetry is deliberate: for the limiter and the breaker there is no meaningful "off" that a zero value could mean, so a zero field is read as "unset". For retry, zero retries is a legitimate, explicit choice, so it is honoured.

Where transit gets its defaults wrong for you

Every default here is tuned for a modest internal management or API server. Three are worth revisiting before production:

  • 50 rps / burst 100 is an admission ceiling for a single process, not a service-level quota. A fleet of ten replicas admits ten times that.
  • A 30-second breaker cooldown is long for a fast-recovering downstream and short for one that takes minutes to restart.
  • Three retries with a 30-second backoff cap. Under the exponential schedule alone the three waits are bounded by 500ms, 1s and 2s, so a call finishes quickly. But a server that answers with Retry-After overrides that schedule, and transit clamps the header only to MaxBackoff — three responses carrying Retry-After: 60 will hold the caller for 90 seconds. Lower MaxBackoff, or set a request deadline: retry aborts as soon as the request context is done.