RSPEED-2417: Add root_path support for reverse proxy deployments

[major]

Description

Add a configurable root_path setting to ServiceConfiguration so Lightspeed Stack can be deployed behind load balancers and reverse proxies that route traffic on a non-root path prefix (e.g. /api/lightspeed).

The root_path value is passed to uvicorn.run() at the ASGI server level, following FastAPI's recommended approach for proxy path prefix handling. This ensures OpenAPI docs, redirects, and all routing work correctly when the service sits behind a path-rewriting proxy.

Default is an empty string (no change in behavior for existing deployments).

Type of change

• New feature

Tools used to create PR

• Assisted-by: Claude (claude-opus-4-6)
• Generated by: N/A

Related Tickets & Documents

• Related Issue: RSPEED-2417
• Epic: RSPEED-2229

Checklist before requesting a review

• I have performed a self-review of my code.
• PR has passed all pre-merge test jobs.
• If it is a core feature, I have added thorough tests.

Testing

1. Unit tests: pytest tests/unit/models/config/test_service_configuration.py tests/unit/runners/test_uvicorn_runner.py — 9/9 passing
2. Linters: make verify passes clean (pylint 10/10, pyright 0 errors, ruff/docstyle/mypy clean)
3. Manual verification: Set root_path: /api/lightspeed in service config and confirm Swagger UI at /api/lightspeed/docs shows correct server URL

Summary by CodeRabbit

• New Features

  • Added a configurable ASGI root path option (default empty) with validation: if set it must start with "/" and must not end with "/". The setting is forwarded to server startup and included in serialized configuration.

• Tests

  • Added coverage for default and custom root path scenarios, validation rules, server startup propagation, and serialization output.

[coderabbitai]

Walkthrough

Adds a new ASGI root_path field to ServiceConfiguration (default ""), enforces simple validation, forwards it to uvicorn.run(), and updates tests and serialization expectations to include root_path.

Changes

Cohort / File(s)	Summary
Configuration Model src/models/config.py	Added root_path: str = Field("", title="Root path", description="ASGI root path for serving behind a reverse proxy on a subpath") and a @field_validator("root_path") to require a leading / if non-empty and disallow a trailing /.
Uvicorn Runner src/runners/uvicorn.py	Forwarded configuration.root_path to uvicorn.run(...); updated docstring parameter list to include root_path.
Configuration Tests tests/unit/models/config/test_service_configuration.py, tests/unit/models/config/test_dump_configuration.py	Added tests asserting default root_path == "", valid explicit value ("/api/lightspeed"), validation errors for missing leading / or trailing /, and updated dumped JSON expectations to include root_path.
Uvicorn Runner Tests tests/unit/runners/test_uvicorn_runner.py	Updated tests to include root_path="" by default and added test_start_uvicorn_with_root_path to assert root_path is passed through to uvicorn.run.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: adding root_path support for reverse proxy deployments, which aligns perfectly with the changeset across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[tisnik]

LGTM