Failures, Retries, and Drain

Errors retain causal chains

Most stack boundaries normalize to a boxed shared error while concrete marker types identify policy rejection, failfast, timeout, TLS, routing, and discovery causes. Helpers inspect the source chain for metrics and HTTP/gRPC response mapping without requiring one monolithic error enum.

Retry requires replayability and permission

An HTTP request body may be a stream that cannot be cloned. Linkerd buffers only up to a configured replay limit; exceeding it disables replay. Route policy classifies failures, retry budgets limit additional traffic, and timeouts bound the whole operation. A retry is therefore a conjunction: policy says retryable, body is replayable, budget is available, and deadline remains.

Reconnect is a state machine

Reconnect moves through disconnected, backoff, connecting, and connected service states. Readiness drives reconnection rather than spawning an unbounded retry loop.

Shutdown drains ownership

SIGTERM completes a drain signal watched by servers. Listeners stop admitting new connections; active connection/request tasks receive drain context and are given time to finish. Readiness, queues, bodies, and connection handles already encode outstanding ownership, so graceful shutdown follows the same boundaries as normal traffic rather than maintaining a separate request registry.