refactor(protocol): use typed HTTP status codes

[bhuvan002]

What

This commit refactors the raw u16 status fields with more meaningful http::StatusCode types. This allows us to get rid of magic numbers at a lot of places and also use the existing helper functions in the http crate. This change also removes an unnecessary StatusCode -> u16 -> StatusCode round trip when propagating upstream HTTP errors to the server response.

Why

Makes the code more readable and safe.

Closes #

How tested

• cargo fmt --all --check
• cargo check --workspace --all-targets
• cargo clippy --workspace --all-targets -- -D warnings
• Tests for switchyard-protocol, switchyard-libsy,
  switchyard-llm-client, and switchyard-server
• uv run ruff check . clean
• uv run mypy switchyard clean
• uv run pytest tests/ green

Checklist

• Unit tests updated to cover the typed status codes.
• No customer-facing documentation changes required.
• Commits signed off (Signed-off-by: Your Name <email>) per the DCO.

Notes for reviewers

Anything reviewers should pay extra attention to — risky paths, follow-up tickets, intentional trade-offs.

Summary by CodeRabbit

• Bug Fixes
  • Improved handling of upstream HTTP errors and status codes.
  • Retry and fallback behavior now correctly recognizes timeouts, rate limits, forbidden responses, and server errors.
  • Preserved accurate upstream status information in error responses, including mid-stream failures.
  • Improved error classification and telemetry reporting for upstream failures.
• Tests
  • Expanded coverage for server errors, redirects, and upstream failure scenarios.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-457/
Built to branch gh-pages at 2026-08-17 19:57 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f3655cd4-bcad-4c74-ab60-c18aa0b2380c

📥 Commits

Reviewing files that changed from the base of the PR and between f9b2df6 and 41fbe2c.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock, !Cargo.lock

📒 Files selected for processing (9)

• crates/libsy-llm-client/src/client.rs
• crates/libsy-llm-client/src/observability.rs
• crates/libsy-llm-client/src/run.rs
• crates/libsy-llm-client/tests/observability.rs
• crates/libsy/Cargo.toml
• crates/libsy/src/algorithms/util/llm_judge.rs
• crates/protocol/src/client.rs
• crates/protocol/src/stream.rs
• crates/switchyard-server/src/lib.rs

Included review availability: Your plan includes up to 12 reviews per rolling hour; 11 remain after this review.

---

Walkthrough

The change replaces numeric upstream HTTP statuses with http::StatusCode across protocol errors, LLM client failures, retry classification, fallback routing, telemetry conversion, server responses, and tests.

Changes

Typed HTTP status flow

Layer / File(s)	Summary
Protocol status contract crates/protocol/src/client.rs, crates/protocol/src/stream.rs	LlmClientError::UpstreamHttp.status and MID_STREAM_UPSTREAM_STATUS now use StatusCode.
Client status propagation and retry handling crates/libsy-llm-client/src/client.rs, crates/libsy-llm-client/src/observability.rs	Client failures and retry metadata retain typed statuses. Telemetry converts statuses to numbers only at recording boundaries.
Fallback and server response classification crates/libsy-llm-client/src/run.rs, crates/libsy/src/algorithms/util/llm_judge.rs, crates/switchyard-server/src/lib.rs, crates/libsy/Cargo.toml, crates/libsy-llm-client/tests/observability.rs	Fallback and 5xx checks use StatusCode predicates. Error construction, tests, and development dependencies use typed statuses.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 41fbe

This refactor replaces raw HTTP status integers with typed status codes without any identified merge-blocking risk; it is merge-ready after normal checks and review.

Poem

I’m a rabbit with statuses bright,
Typed through the client day and night.
Retries read codes with care,
Server paths pass them everywhere.
Tests now hop in typed delight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change from raw HTTP status values to typed HTTP status codes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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