fix: prevent startup failure when INTERNAL_RAG_TOKEN is unset

[Namraa310806]

Summary

This PR fixes a deployment availability issue where the RAG service could fail to start when INTERNAL_RAG_TOKEN was not configured.

Previously, the service performed token validation during module initialization, causing application startup to fail with a runtime exception if the environment variable was missing. This resulted in a complete service outage rather than a controlled failure for protected endpoints.

Changes Made

• Updated require_internal_rag_token_configured() to return configuration status instead of raising an exception.
• Replaced import-time startup failure with a warning log.
• Added runtime protection that returns HTTP 503 for protected endpoints when INTERNAL_RAG_TOKEN is not configured.
• Preserved security by ensuring protected routes remain inaccessible until a valid token is configured.
• Added tests covering configured and unconfigured token scenarios.

Related issue

Fixes: #354

Testing

• I ran the relevant checks locally
• I verified the app still starts
• I tested the affected flow end-to-end

Verified Scenarios

• Service starts successfully when INTERNAL_RAG_TOKEN is configured.
• Service starts successfully when INTERNAL_RAG_TOKEN is missing.
• Protected endpoints return HTTP 503 when the token is not configured.
• Protected endpoints continue functioning normally when the token is configured.
• Existing authentication behavior remains unchanged.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas

Screenshots / recordings

N/A – Backend-only change.

Notes

This change improves deployment resilience by preventing full application startup failures caused by missing configuration while maintaining secure behavior for protected endpoints.

No database migrations or deployment changes are required.

Security

• No sensitive data included

Summary by CodeRabbit

• Bug Fixes

  • Protected RAG endpoints no longer crash the app at startup when the internal auth token is missing; startup logs a warning and affected endpoints return HTTP 503 with a clear "INTERNAL_RAG_TOKEN is not configured" message (including path/IP logging).

• Tests

  • Tests updated to cover graceful 503 behavior across all protected endpoints.

[vercel]

@Namraa310806 is attempting to deploy a commit to the firefistisdead's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

Startup no longer raises when INTERNAL_RAG_TOKEN is unset; require_internal_rag_token_configured() returns a boolean and logs a warning. internal_auth_middleware now returns 503 with "INTERNAL_RAG_TOKEN is not configured" (and logs path + client IP) for protected endpoints when the token is missing.

Changes

RAG Service Token Configuration and Request-Time Protection

Layer / File(s)	Summary
Token Configuration Check Returns Boolean rag-service/main.py, rag-service/test_main.py	require_internal_rag_token_configured() now returns bool and logs a startup warning when INTERNAL_RAG_TOKEN is unset instead of raising RuntimeError. Tests updated to assert False for empty and True for set token.
Middleware Request-Time Protection rag-service/main.py, rag-service/test_main.py	internal_auth_middleware performs an early check for token configuration on protected paths and returns HTTP 503 with detail "INTERNAL_RAG_TOKEN is not configured" (and logs request path + client IP) when unset. Parametrized tests assert 503 and the exact message for /process-pdf, /ask, and /summarize.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• FireFistisDead/pdf-qa-bot#205: Related fail-closed internal RAG authentication changes touching rag-service/main.py.
• FireFistisDead/pdf-qa-bot#161: Prior edits to internal-token/middleware logic in rag-service/main.py.
• FireFistisDead/pdf-qa-bot#250: Overlaps on protected-path handling including /ask/stream and middleware behavior.

Suggested reviewers

• FireFistisDead

Poem

🐰 I once choked the app with a missing key,
Now I whisper warnings, let the routes be.
Middleware watches, returns three-oh-three,
Logs the path and IP — safe as can be.
Hooray for gentle failures, says this rabbit with glee.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% 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
Title check	✅ Passed	The title clearly and specifically describes the main change: preventing startup failure when INTERNAL_RAG_TOKEN is unset, which is the core objective of this PR.
Description check	✅ Passed	The description is comprehensive, covering all required template sections including summary, related issue, testing verification, checklist items, and security confirmation.
Linked Issues check	✅ Passed	The PR successfully addresses all coding requirements from issue #354: prevents import-time startup failure, allows service to start without token, logs warning on startup, returns HTTP 503 for protected endpoints when token is missing, and maintains security.
Out of Scope Changes check	✅ Passed	All changes directly support the stated objective of preventing startup failure and protecting endpoints at runtime. No out-of-scope modifications detected.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (1)

rag-service/test_main.py (1)

697-715: ⚡ Quick win

Consider expanding test coverage to all protected endpoints.

The parametrized test currently covers 3 endpoints (/process-pdf, /ask, /summarize), but PROTECTED_RAG_PATHS includes 7 endpoint paths plus 2 prefix patterns. While the middleware logic is shared, testing all protected endpoints provides defense in depth and catches configuration errors (e.g., if an endpoint is accidentally removed from the protection sets).

🧪 Suggested test expansion

-@pytest.mark.parametrize("path", ["/process-pdf", "/ask", "/summarize"])
+@pytest.mark.parametrize("path", [
+    "/process-pdf", 
+    "/ask", 
+    "/ask/stream",
+    "/summarize",
+    "/knowledge-gaps",
+    "/validate-session-write",
+    "/sessions/lookup",
+])
 def test_protected_endpoints_rejected_when_token_is_cleared_after_startup(path):

You may also want to add a test case for prefix-based protection (e.g., /ask/v2/future-endpoint to verify the /ask/ prefix guard).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rag-service/test_main.py` around lines 697 - 715, Update the
test_protected_endpoints_rejected_when_token_is_cleared_after_startup to iterate
over the full set of protected paths instead of the hard-coded three: import
PROTECTED_RAG_PATHS from main (or grab main_module.PROTECTED_RAG_PATHS) and
parametrize the test over that collection, and add at least one path that
exercises prefix-based protection (e.g., "/ask/v2/future-endpoint") to verify
prefix guards; keep the same token-clear setup using
main_module.INTERNAL_RAG_TOKEN, TestClient(app, ...), and the same assertions
for 503 and the "INTERNAL_RAG_TOKEN is not configured" detail.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@rag-service/test_main.py`:
- Around line 697-715: Update the
test_protected_endpoints_rejected_when_token_is_cleared_after_startup to iterate
over the full set of protected paths instead of the hard-coded three: import
PROTECTED_RAG_PATHS from main (or grab main_module.PROTECTED_RAG_PATHS) and
parametrize the test over that collection, and add at least one path that
exercises prefix-based protection (e.g., "/ask/v2/future-endpoint") to verify
prefix guards; keep the same token-clear setup using
main_module.INTERNAL_RAG_TOKEN, TestClient(app, ...), and the same assertions
for 503 and the "INTERNAL_RAG_TOKEN is not configured" detail.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fb9be230-1ce4-4cf0-ae7d-33acd5bafcff

📥 Commits

Reviewing files that changed from the base of the PR and between 04e78f5 and b0b722b.

📒 Files selected for processing (2)

• rag-service/main.py
• rag-service/test_main.py

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.