fix(startup): validate before serving (BUG-025)

[fvadicamo]

Summary

BUG-025: the ARCH-057 startup validation ran inside the ASGI lifespan, so a failed step's raise SystemExit(1) propagated into uvicorn, which logged a raw Python traceback next to the structured [STARTUP ERROR]. NFR-009 asks for the remediable message instead of the stack dump, and this affected all 11 steps, not just config validation.

Root cause

The container ran uvicorn vektra_app.main:app, so the 11-step sequence necessarily ran as ASGI startup. Any abort had to travel through uvicorn, which logs a lifespan exception as a traceback before Application startup failed. Exiting.

Fix

• Extract the sequence into a loop-agnostic _run_startup() that raises StartupValidationError (no SystemExit inside it) and a matching _run_shutdown().
• Add a main() container entrypoint (python -m vektra_app.main, wired in docker/entrypoint.sh) that runs validation in the very loop that will serve, then calls uvicorn with lifespan="off". A failed step logs its [STARTUP ERROR] and exits non-zero with no ASGI and no traceback. Startup and serving share one event loop, so async resources built during validation (DB engine, HTTP clients) stay bound to the loop that serves requests; uvloop is preserved via config.get_loop_factory().
• The ASGI lifespan keeps validating (and raising SystemExit) for the in-process / TestClient path, so test_missing_llm_provider_aborts_startup is unchanged.

Testing

make lint and make test green (771 passed). Removed the now-passing xfail(strict=True) on tests/test_startup.py::test_no_raw_traceback_on_startup_failure.

Proven on the container (rebuilt image, throwaway docker compose run, dev stack left untouched):

Scenario	Result
Empty VEKTRA_LLM_PROVIDER (config_validation)	[STARTUP ERROR] Step: config_validation, exit 1, no traceback
Unreachable DB (database_connectivity)	step 1 completes, then [STARTUP ERROR] Step: database_connectivity, exit 1, no traceback
Valid .env	all 11 steps logged, startup_complete, Uvicorn running on http://0.0.0.0:8000, no traceback

Acceptance criteria (BUG-025)

• A misconfiguration produces the structured [STARTUP ERROR] and no Traceback (most recent call last)
• Holds for a step other than config validation (database_connectivity shown)
• The container still exits non-zero
• The xfail(strict=True) is removed

Notes

• No workflow files touched, so the branch-protection check names (Integration tests + NFR gates, CI gate) are unchanged. The integration job runs the container and test_startup.py, which now exercises the fix end-to-end.

Backlog: BUG-025. Traceability: REQ-011, NFR-009, ARCH-057, DEBT-031 (found by), BUG-024 (same surface).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved application startup validation and error handling.
  • Configuration problems now produce a clear [STARTUP ERROR] message and exit cleanly without an ASGI traceback.
  • Container startup now validates configuration before launching the API server.

• Documentation

  • Added production/container startup instructions.
  • Clarified local development commands with live reload.

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 18 minutes

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?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: acdbca85-d21b-4a54-8667-982474bcbce5

📥 Commits

Reviewing files that changed from the base of the PR and between adb19c2 and 12ba845.

⛔ Files ignored due to path filters (1)

• .s2s/BACKLOG.md is excluded by !.s2s/**

📒 Files selected for processing (1)

• CHANGELOG.md

📝 Walkthrough

Walkthrough

Startup validation is centralized for ASGI and container execution. The container now runs the module entrypoint, which validates before starting uvicorn. Lifespan teardown is shared, startup failures return non-zero without an ASGI traceback, and tests and documentation reflect the new behavior.

Changes

Startup validation and serving

Layer / File(s)	Summary
Shared startup and shutdown lifecycle vektra-app/src/vektra_app/main.py	Startup validation and shutdown teardown are centralized in _run_startup and _run_shutdown; ASGI lifespan delegates to them and converts validation failures to SystemExit(1).
Module-based container serving vektra-app/src/vektra_app/main.py	main() configures uvicorn with lifespan disabled, while _serve validates before serving and returns exit code 1 on validation failure.
Entrypoint, test, and usage updates docker/entrypoint.sh, tests/test_startup.py, vektra-app/README.md	The server dispatch uses python -m vektra_app.main, the startup failure test is enabled, and documentation distinguishes container execution from local reload usage.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Docker as docker/entrypoint.sh
  participant Main as vektra_app.main
  participant Startup as _run_startup
  participant Uvicorn as uvicorn Server
  Docker->>Main: execute python -m vektra_app.main
  Main->>Startup: validate configuration and initialize services
  Startup-->>Main: success or StartupValidationError
  Main->>Uvicorn: start server after successful validation

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: moving startup validation before serving and fixing BUG-025.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/bug-025-startup-traceback

---

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.}

[gemini-code-assist]

Code Review

This pull request refactors the application startup process to run the 11-step validation (ARCH-057) before starting the Uvicorn server, preventing Python tracebacks on startup failures (BUG-025). The container entrypoint now executes the module directly via python -m vektra_app.main instead of running Uvicorn directly. Review feedback suggests safely accessing app.state.registry during shutdown to avoid potential AttributeErrors if startup fails early, and allowing the host and port to be configured via environment variables rather than being hardcoded.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[fvadicamo]

Addressed the two automated review comments (gemini). Both are declined as by-design, with rationale posted in the inline threads and threads resolved:

• _run_shutdown direct app.state.registry access: teardown is only reachable after _run_startup succeeds (finally-after-yield in lifespan, finally-after-serve in _serve), so the attribute is always set; a getattr fallback would mask a broken invariant without actually making a never-started app's teardown safe.
• Hardcoded 0.0.0.0:8000 in main(): preserves the prior entrypoint exactly; the container's internal bind port is intentionally fixed at 8000 (Dockerfile healthcheck, compose :8000 mapping, CI probe all depend on it). VEKTRA_PORT is the host-side published port, not the bind port.

CodeRabbit reported no actionable comments. Both integration jobs (pgvector, qdrant) pass, exercising the fix on a real container.