fix(deploy): CORS and proxy-headers for HF Spaces (#35)

* feat(docs): add comprehensive specifications for NiiVue integration and JavaScript loading issues

- Introduced multiple new documentation files detailing the proposed Gradio Custom Component for NiiVue, addressing the "Loading..." issue on HuggingFace Spaces, and providing a root cause analysis of JavaScript loading failures.
- Included a detailed audit of JavaScript loading issues, diagnostic steps for the "Loading..." bug, and an analysis of Gradio's compatibility with WebGL.
- Documented the decision-making process and next steps for implementing the custom component approach, emphasizing the need for a structured solution to integrate NiiVue effectively.

These additions aim to enhance understanding and provide a clear path forward for developers working with Gradio and NiiVue.

* fix(docs): update technical debt documentation and add root cause analysis for NiiVue loading issue

- Revised the TECHNICAL_DEBT.md to reflect the current status of the NiiVue/WebGL integration, marking it as a P0 BLOCKER due to issues on HuggingFace Spaces.
- Added detailed sections outlining the critical issue with NiiVue not loading, including root causes and proposed solutions.
- Introduced new specifications for the Gradio Custom Component approach to resolve the loading issue, emphasizing the need for a structured solution.
- Documented the findings from the recent audits and analyses, providing a clear path forward for developers addressing the integration challenges.

These updates aim to enhance clarity and provide actionable insights for future development efforts.

* fix(cors): correct regex pattern for HF Spaces URLs

The CORS allow_origin_regex expected double hyphens (--) but
HuggingFace Spaces direct URLs use single hyphens:

Before: https://.*--stroke-viewer-frontend(--.*)?\.hf\.space
After: https://.*stroke-viewer-frontend.*\.hf\.space

This was causing "Failed to fetch" errors when NiiVue tried to
load NIfTI files from the backend - the static file requests
were being blocked by CORS.

* fix(deploy): add proxy-headers and document HF Spaces bugs

- Add --proxy-headers to uvicorn CMD in Dockerfile
This ensures request.base_url returns https:// on HF Spaces
(fixes potential mixed-content issues with NIfTI file URLs)

- Add docs/bugs/ directory with comprehensive documentation:
- 001: CORS regex pattern mismatch (fixed)
- 002: HTTP vs HTTPS behind proxy (fixed)
- README: Common HF Spaces pitfalls and prevention

Sources:
- https://github.com/fastapi/fastapi/discussions/6670
- https://medium.com/@na.mazaheri/deploying-a-fastapi-app-on-hugging-face-spaces

Dockerfile

@@ -76,4 +76,5 @@ EXPOSE 7860
 ENTRYPOINT []
 
 # Run FastAPI with uvicorn (module path: stroke_deepisles_demo.api.main:app)
-CMD ["uvicorn", "stroke_deepisles_demo.api.main:app", "--host", "0.0.0.0", "--port", "7860"]
+# --proxy-headers: Trust X-Forwarded-Proto from HF Spaces proxy (ensures https:// in request.base_url)
+CMD ["uvicorn", "stroke_deepisles_demo.api.main:app", "--host", "0.0.0.0", "--port", "7860", "--proxy-headers"]

docs/bugs/001-cors-static-files-hf-spaces.md

@@ -0,0 +1,72 @@
+# Bug 001: CORS Blocking Static File Requests on HuggingFace Spaces
+
+**Status**: FIXED
+**Date Found**: 2025-12-11
+**Severity**: Critical (blocks core functionality)
+
+---
+
+## Symptoms
+
+1. Frontend loads successfully, case dropdown populates
+2. Segmentation API call succeeds (200 OK, ~34s processing time)
+3. Results panel shows metrics (Dice Score, Volume, Time)
+4. NiiVue viewer shows "loading..." then error: **"Failed to load volume: Failed to fetch"**
+
+## Root Cause
+
+The CORS `allow_origin_regex` pattern in `src/stroke_deepisles_demo/api/main.py` was incorrect:
+
+```python
+# WRONG - expects double hyphens
+allow_origin_regex=r"https://.*--stroke-viewer-frontend(--.*)?\.hf\.space"
+
+# Actual frontend URL uses single hyphen:
+# https://vibecodermcswaggins-stroke-viewer-frontend.hf.space
+#                           ^ single hyphen
+```
+
+The regex expected `--` (double hyphen) between username and space name, but HuggingFace Spaces direct URLs use single hyphens.
+
+## HuggingFace Spaces URL Formats
+
+| Format | Pattern | Example |
+|--------|---------|---------|
+| **Direct** | `{username}-{spacename}.hf.space` | `vibecodermcswaggins-stroke-viewer-frontend.hf.space` |
+| **Proxy/Embed** | `{username}--{spacename}--{hash}.hf.space` | `vibecodermcswaggins--stroke-viewer-frontend--abc123.hf.space` |
+
+The original regex only matched the proxy format, not the direct format.
+
+## Fix
+
+```python
+# CORRECT - matches both formats
+allow_origin_regex=r"https://.*stroke-viewer-frontend.*\.hf\.space"
+```
+
+## Logs Evidence
+
+```
+INFO: 10.16.13.79:42834 - "POST /api/segment HTTP/1.1" 200 OK
+```
+
+The API call succeeded, but subsequent static file fetches for NIfTI volumes were blocked by CORS (browser silently blocks and shows "Failed to fetch").
+
+## Files Changed
+
+- `src/stroke_deepisles_demo/api/main.py` - Fixed regex
+- `docs/specs/frontend/36-frontend-without-gradio-hf-spaces.md` - Updated spec
+
+## Verification
+
+After fix:
+1. Redeploy backend to HF Spaces
+2. Refresh frontend
+3. Run segmentation
+4. NiiVue should load and display the DWI + prediction overlay
+
+## Prevention
+
+- Test CORS configuration with actual production URLs before deployment
+- Add integration test that verifies static file CORS headers
+- Document HF Spaces URL formats in spec

docs/bugs/002-http-vs-https-proxy-headers.md

@@ -0,0 +1,82 @@
+# Bug 002: HTTP vs HTTPS URL Mismatch Behind HF Spaces Proxy
+
+**Status**: FIXED
+**Date Found**: 2025-12-11
+**Severity**: High (may cause mixed content errors or fetch failures)
+
+---
+
+## Symptoms
+
+NiiVue viewer fails to load NIfTI files with "Failed to fetch" even after CORS is fixed.
+Browser console may show mixed content warnings (HTTPS page loading HTTP resources).
+
+## Root Cause
+
+HuggingFace Spaces runs containers behind a reverse proxy that handles SSL termination.
+When the app constructs URLs using `request.base_url`, it may return `http://` instead of `https://`
+because uvicorn doesn't trust the proxy's `X-Forwarded-Proto` header by default.
+
+**Reference**: [FastAPI Static Files over HTTPS Discussion](https://github.com/fastapi/fastapi/discussions/6670)
+
+> "Starlette (FastAPI) returns http instead of https only inside containers"
+
+## The Code Path
+
+```python
+# routes.py
+def get_backend_base_url(request: Request) -> str:
+    env_url = os.environ.get("BACKEND_PUBLIC_URL", "").rstrip("/")
+    if env_url:
+        return env_url
+    return str(request.base_url).rstrip("/")  # May return http:// behind proxy!
+```
+
+## Fix
+
+Add `--proxy-headers` flag to uvicorn in Dockerfile:
+
+```dockerfile
+# BEFORE (broken)
+CMD ["uvicorn", "...:app", "--host", "0.0.0.0", "--port", "7860"]
+
+# AFTER (fixed)
+CMD ["uvicorn", "...:app", "--host", "0.0.0.0", "--port", "7860", "--proxy-headers"]
+```
+
+This tells uvicorn to trust headers like:
+- `X-Forwarded-Proto: https`
+- `X-Forwarded-For: client-ip`
+
+## Alternative Fixes
+
+1. **Set BACKEND_PUBLIC_URL**: Explicitly set the public URL in HF Space settings
+   ```
+   BACKEND_PUBLIC_URL=https://vibecodermcswaggins-stroke-deepisles-demo.hf.space
+   ```
+
+2. **Force HTTPS in code**: Override scheme detection
+   ```python
+   def get_backend_base_url(request: Request) -> str:
+       base = str(request.base_url).rstrip("/")
+       # Force HTTPS in production
+       if os.environ.get("HF_SPACES"):
+           base = base.replace("http://", "https://")
+       return base
+   ```
+
+## Files Changed
+
+- `Dockerfile` - Added `--proxy-headers` to uvicorn CMD
+
+## Verification
+
+1. Deploy to HF Spaces
+2. Run segmentation
+3. Check Network tab - file URLs should be `https://`
+4. NiiVue should load volumes successfully
+
+## Sources
+
+- [FastAPI/Starlette HTTPS Discussion](https://github.com/fastapi/fastapi/discussions/6670)
+- [Deploying FastAPI on HuggingFace Spaces](https://medium.com/@na.mazaheri/deploying-a-fastapi-app-on-hugging-face-spaces-and-handling-all-its-restrictions-d494d97a78fa)

docs/bugs/README.md

@@ -0,0 +1,51 @@
+# Bug Tracker: HuggingFace Spaces Deployment
+
+This directory tracks bugs found during deployment to HuggingFace Spaces.
+
+## Active Bugs
+
+None currently.
+
+## Fixed Bugs
+
+| ID | Title | Severity | Status |
+|----|-------|----------|--------|
+| [001](./001-cors-static-files-hf-spaces.md) | CORS regex blocking static file requests | Critical | FIXED |
+| [002](./002-http-vs-https-proxy-headers.md) | HTTP vs HTTPS URL mismatch behind proxy | High | FIXED |
+
+## Common HuggingFace Spaces Pitfalls
+
+Based on research and experience, here are common issues to watch for:
+
+### 1. CORS Configuration
+- HF Spaces URLs use single hyphens: `{username}-{spacename}.hf.space`
+- Proxy/embed URLs may use double hyphens: `{username}--{spacename}--{hash}.hf.space`
+- Always use a permissive regex that matches both formats
+
+### 2. HTTPS Behind Proxy
+- HF Spaces terminates SSL at their proxy
+- Uvicorn sees HTTP internally
+- Add `--proxy-headers` to trust `X-Forwarded-Proto`
+- Or explicitly set `BACKEND_PUBLIC_URL` environment variable
+
+### 3. File System Restrictions
+- Only `/tmp` is writable
+- Use `/tmp/stroke-results` for output files
+- Ensure directories are created with proper permissions
+
+### 4. Static Files
+- Mount static files AFTER directory exists
+- Ensure CORS allows file fetches from frontend origin
+- Files served from `/files/...` must be accessible
+
+### 5. Environment Variables
+- `HF_SPACES=1` indicates running on HF Spaces
+- `SPACE_ID` contains the space identifier
+- Use these to detect production environment
+
+## Sources
+
+- [Deploying FastAPI on HuggingFace Spaces](https://huggingface.co/blog/HemanthSai7/deploy-applications-on-huggingface-spaces)
+- [HF Spaces Restrictions](https://medium.com/@na.mazaheri/deploying-a-fastapi-app-on-hugging-face-spaces-and-handling-all-its-restrictions-d494d97a78fa)
+- [FastAPI HTTPS Discussion](https://github.com/fastapi/fastapi/discussions/6670)
+- [HF Docker Spaces Docs](https://huggingface.co/docs/hub/en/spaces-sdks-docker)

docs/specs/frontend/36-frontend-without-gradio-hf-spaces.md

@@ -804,7 +804,8 @@ if FRONTEND_ORIGIN:
 app.add_middleware(
     CORSMiddleware,
     allow_origins=CORS_ORIGINS,
-    allow_origin_regex=r"https://.*--stroke-viewer-frontend(--.*)?\\.hf\\.space",
+    # Match HF Spaces URLs in both formats (direct and proxy)
+    allow_origin_regex=r"https://.*stroke-viewer-frontend.*\\.hf\\.space",
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],

src/stroke_deepisles_demo/api/main.py

@@ -28,7 +28,10 @@ if FRONTEND_ORIGIN:
 app.add_middleware(
     CORSMiddleware,
     allow_origins=CORS_ORIGINS,
-    allow_origin_regex=r"https://.*--stroke-viewer-frontend(--.*)?\.hf\.space",
+    # Match HF Spaces URLs in both formats:
+    # - Direct: https://username-spacename.hf.space
+    # - Proxy:  https://username--spacename--hash.hf.space
+    allow_origin_regex=r"https://.*stroke-viewer-frontend.*\.hf\.space",
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],