fix(http): enforce documented retry contracts

[thomhurst]

Summary

• restrict transient HTTP status handling to 500-599, 408, and 429
• add deterministic contracts for Retry-After, Standard, disposal, cancellation, replay, DI lifetimes, and concurrency
• document response ownership, handler lifetime, and one-shot stream limits

Closes #26

Validation

• dotnet build Kevlar.slnx -c Release
• dotnet run --project tests/Kevlar.Tests -c Release --no-build -- --timeout 5m
• dotnet run --project tests/Kevlar.NetStandard.Tests -c Release --no-build -- --timeout 5m
• dotnet run --project tests/Kevlar.IntegrationTests -c Release --no-build -- --timeout 5m
• dotnet run --project tests/Kevlar.Analyzers.Tests -c Release --no-build -- --timeout 5m
• npm ci (docs)
• npm run build (docs)

[coderabbitai]

Warning

Review limit reached

@thomhurst, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 10 minutes

Limit details: You’ve used all 10 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fd4715a2-a3ab-4094-ac65-af79169105f3

📥 Commits

Reviewing files that changed from the base of the PR and between 1f2d8f1 and e292ef5.

📒 Files selected for processing (3)

• docs/docs/http.md
• src/Kevlar.Extensions.Http/HttpShield.cs
• tests/Kevlar.Tests/HttpContractTests.cs

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR narrows built-in transient HTTP status handling to 500–599, 408, and 429, and adds explicit tests and documentation for the HTTP resilience contracts.

• Clarifies retry response ownership, request replay limitations, and handler lifetime behavior.
• Adds coverage for Retry-After delays, cancellation, disposal, circuit breaking, DI registration, and concurrent retries.
• Introduces one non-blocking timing weakness in an asynchronous fake-time test.

Confidence Score: 4/5

The production change appears safe to merge, with only a non-blocking risk of a scheduler-dependent test timeout.

The status-classification implementation and documented contracts are consistent, but the new attempt-timeout test can miss asynchronously registered fake timers because it substitutes short real-time polling for deterministic synchronization.

Files Needing Attention: tests/Kevlar.Tests/HttpContractTests.cs

Important Files Changed

Filename	Overview
src/Kevlar.Extensions.Http/HttpShield.cs	Correctly restricts built-in transient status classification to the documented HTTP ranges.
tests/Kevlar.Tests/HttpContractTests.cs	Adds broad HTTP contract coverage, with one scheduler-sensitive fake-time wait that can make CI flaky.
docs/docs/http.md	Accurately clarifies response ownership, request replay limitations, and shield sharing across handler lifetimes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[HTTP request] --> B[30s total timeout]
    B --> C[Retry up to 3 times]
    C --> D[Circuit breaker]
    D --> E[10s attempt timeout]
    E --> F[HTTP handler]
    F --> G{Transient outcome?}
    G -->|500-599, 408, 429 or handled exception| C
    G -->|No or retries exhausted| H[Caller-owned final response]

Loading

_{Reviews (1): Last reviewed commit: "fix(http): bound transient status codes" | Re-trigger Greptile}