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, CircuitBreakerStreamInterceptor, 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, so 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.