[Katyara11]

Summary

Implements the roadmap item: logging, authentication and correlation as transport-agnostic
middleware. DelegatingHandler is where these would normally live and only exists in
HttpClient-land, so anything built on it cannot be reused for RestSharp — this sits above
IHttpTransport instead, for the same reason serialization, retries and the capability check do.

Each stage is independently opt-in, and a client with no stages pays nothing: the pipeline is the
transport call.

services.AddRunaxClient<IRepositoryClient>()
        .UseCorrelation()
        .UseLogging()
        .UseBearerToken(() => tokenCache.Current)
        .WithRetry(3);

Changes

• IHttpMiddleware, RequestPipelineStep, RequestContext, HttpMiddlewareOrder and the
  internal composer, under src/Runax.Http/Pipeline/.
• Three built-in stages — LoggingMiddleware, AuthenticationMiddleware (with
  IAccessTokenProvider and DelegateAccessTokenProvider), CorrelationMiddleware.
• Builder surface — Use(...), UseLogging(...), UseBearerToken(...) ×3, UseCorrelation(...),
  backed by RunaxClientOptions.MiddlewareFactories.
• Executor — composes the pipeline once per client and invokes it per attempt. +30/−10 lines,
  kept deliberately small.
• Tests — 153 new (1272 total): ordering, per-attempt invocation, token refresh across a retry,
  correlation stability, Activity/traceparent propagation, every redaction rule, short-circuit.
• Docs — new docs/pipeline.md, linked from the guides table; src/Runax.Http/README.md;
  CHANGELOG.md.

Type

• Feature
• Bug fix
• Refactor
• Chore (CI, deps, config)

Checklist

• Code builds without errors
• Tests added/updated

Notes for review

Where the pipeline sits relative to retries

This was the real design question, and neither obvious answer works:

	Outside the retry loop	Inside the retry loop
Token refreshed after a failure	stale on every retry ✗	re-read per attempt ✓
Correlation id	stable ✓	regenerated per attempt ✗
Log line per attempt	one line for three tries ✗	one each ✓

So the pipeline runs inside the loop — once per attempt — and RequestContext is created
once per call and reused across attempts. Stages that must be fresh simply are; anything that
must stay constant lives on the context. CorrelationMiddleware is the whole pattern in one line:

context.CorrelationId ??= Activity.Current?.TraceId.ToHexString() ?? NewTraceId();

context.Attempt distinguishes the tries, so one call yields one id and a log line per attempt.

Logging redaction

Redaction is the default and, in two places, not optional:

• Bodies are never logged. No option. A body is the likeliest place for a credential or personal
  data; logs ship to third-party aggregators and are kept for months; and a switch like that gets
  enabled during an incident and left on.
• Header values are an allow-list, empty by default — a deny-list protects the headers someone
  thought of, and the one that leaks is always the one nobody did.
• Authorization, Proxy-Authorization, Cookie, Set-Cookie render as *** even when
  explicitly allow-listed. Enough to answer "was auth attached?" without carrying the token, and
  deliberately not switchable: an option that can print a bearer token into a log aggregator would
  eventually be used.
• The query string is logged by default, since a path without it rarely identifies the
  request. LogQueryString = false for APIs that take a credential as a query parameter — though
  RXH005 exists partly to stop that happening by accident.

A cancellation logs at request level, not as an error, so a cancelled shutdown does not fill the log
with errors nobody can act on.

Bug found along the way

ToTransportRequest() handed out the context's live header list. On a retry, the next attempt's
SetHeader therefore rewrote a request that had already been sent — and TransportRequest is
documented as immutable with transports entitled to hold one. It surfaced as the first attempt
appearing to carry the second attempt's token, caught by the test written to prove refresh worked.
Headers are snapshotted now, with a test pinning it.

Deliberate limitation

A stage may only change headers. RequiredCapabilities is derived from the body, proxy, timeout
and HTTP version, and the capability check runs before the pipeline — so a stage altering one of
those could introduce a requirement nothing had checked. Lifting this means moving the capability
check inside the loop, which also requires excluding TransportCapabilityException from the retry
catch (it currently derives from TransportException, which the loop catches). That is a design
change rather than a configuration one, and I left it out rather than half-doing it. Documented in
IHttpMiddleware and docs/pipeline.md.

Also left out

• No span creation. Correlation propagates identity and reads an ambient Activity; creating
  spans, tracing and metrics belong with the separate observability roadmap item.
• IHttpTransport, the transports and the generator are untouched.

Verification

1272 tests across net8.0/net9.0/net10.0; dotnet build --warnaserror clean, dotnet format --verify-no-changes clean, and the native AOT publish takes a client through all three built-in
stages plus a custom one with zero trim warnings, then runs.

Conflict note

Touches src/Runax.Http/HttpContractExecutor.cs (+30/−10) and CHANGELOG.md, both of which the
parallel [Retry] attribute PR also touches. The executor edits are concentrated in the constructor
and SendWithRetriesAsync's signature plus its send call.