feat: initial hf-backend setup with generic router host and keep-alive

.github/workflows/keep_alive.yml

@@ -0,0 +1,19 @@
+name: Space Keep Alive
+
+on:
+  schedule:
+    - cron: "*/30 * * * *"
+  workflow_dispatch:
+
+jobs:
+  ping:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ping Health Endpoint
+        run: |
+          TARGET_URL="${{ secrets.HF_SPACE_URL }}"
+          if [ -z "$TARGET_URL" ]; then
+            TARGET_URL="https://rachit-mangawa-hf-backend.hf.space/health"
+          fi
+          echo "Pinging ${TARGET_URL}..."
+          curl --fail --show-error --silent --max-time 30 "$TARGET_URL" || exit 1

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/

Dockerfile

@@ -0,0 +1,37 @@
+FROM python:3.11-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PORT=7860
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR /app
+
+COPY --chown=user:user requirements.txt .
+
+RUN --mount=type=secret,id=GITHUB_TOKEN,required=false,uid=1000 \
+    if [ -f /run/secrets/GITHUB_TOKEN ]; then \
+        TOKEN=$(cat /run/secrets/GITHUB_TOKEN); \
+        if [ -n "$TOKEN" ]; then \
+            git config --global url."https://${TOKEN}@github.com/".insteadOf "https://github.com/"; \
+        fi; \
+    fi && \
+    pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt && \
+    git config --global --unset-all url."https://${TOKEN}@github.com/".insteadOf 2>/dev/null || true
+
+COPY --chown=user:user . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,8 @@
+---
+title: HF Backend Host
+emoji: ⚡
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 7860
+---

main.py

@@ -0,0 +1,110 @@
+import asyncio
+import importlib
+import logging
+import os
+from contextlib import asynccontextmanager
+from typing import Callable
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from registry import PROJECT_REGISTRY
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+logger = logging.getLogger("hf-backend")
+
+loaded_projects: dict[str, str] = {}
+failed_projects: dict[str, str] = {}
+
+max_body_size = int(os.getenv("MAX_BODY_SIZE_BYTES", str(10 * 1024 * 1024)))
+request_timeout = float(os.getenv("REQUEST_TIMEOUT_SECONDS", "60.0"))
+
+
+class RequestLimitMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, max_size: int, timeout: float):
+        super().__init__(app)
+        self.max_size = max_size
+        self.timeout = timeout
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        content_length = request.headers.get("content-length")
+        if content_length and int(content_length) > self.max_size:
+            return Response(content="Payload Too Large", status_code=413)
+
+        bytes_received = 0
+        original_receive = request._receive
+
+        async def limited_receive():
+            nonlocal bytes_received
+            message = await original_receive()
+            if message["type"] == "http.request":
+                bytes_received += len(message.get("body", b""))
+                if bytes_received > self.max_size:
+                    raise HTTPException(status_code=413, detail="Payload Too Large")
+            return message
+
+        request._receive = limited_receive
+
+        try:
+            return await asyncio.wait_for(call_next(request), timeout=self.timeout)
+        except asyncio.TimeoutError:
+            return Response(content="Request Timeout", status_code=504)
+
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+app.add_middleware(RequestLimitMiddleware, max_size=max_body_size, timeout=request_timeout)
+
+raw_origins = [o.strip() for o in os.getenv("CORS_ALLOWED_ORIGINS", "").split(",") if o.strip()]
+allowed_origins = [o for o in raw_origins if o != "*"]
+if allowed_origins:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=allowed_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+def load_routers():
+    disabled_raw = [p.strip().strip("/") for p in os.getenv("DISABLE_PROJECTS", "").split(",") if p.strip()]
+    disabled_set = {p for p in disabled_raw}
+
+    for prefix, target in PROJECT_REGISTRY.items():
+        clean_prefix = prefix.strip("/")
+        if clean_prefix in disabled_set:
+            logger.warning(f"[{prefix}] Skipped: disabled by DISABLE_PROJECTS")
+            continue
+
+        try:
+            logger.info(f"[{prefix}] Importing {target}")
+            module_name, attr_name = target.split(":")
+            module = importlib.import_module(module_name)
+            router = getattr(module, attr_name)
+            app.include_router(router, prefix=prefix)
+            loaded_projects[prefix] = target
+            logger.info(f"[{prefix}] Successfully mounted at {prefix}")
+        except Exception as e:
+            failed_projects[prefix] = f"{type(e).__name__}: {str(e)}"
+            logger.error(f"[{prefix}] Failed to mount router: {e}", exc_info=True)
+
+
+load_routers()
+
+
+@app.get("/health")
+def health():
+    if not failed_projects:
+        overall_status = "healthy"
+    elif loaded_projects:
+        overall_status = "degraded"
+    else:
+        overall_status = "unhealthy"
+
+    return {
+        "status": overall_status,
+        "loaded": loaded_projects,
+        "failed": failed_projects,
+    }

registry.py

@@ -0,0 +1,4 @@
+PROJECT_REGISTRY = {
+    "/project-1": "heartflow_backend.router:router",
+    "/project-2": "semantic_backend.router:router",
+}

requirements.txt

@@ -0,0 +1,54 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile requirements.in -o requirements.txt
+annotated-doc==0.0.5
+    # via fastapi
+annotated-types==0.8.0
+    # via pydantic
+anyio==4.15.1
+    # via
+    #   starlette
+    #   watchfiles
+click==8.5.0
+    # via uvicorn
+fastapi==0.162.0
+    # via -r requirements.in
+h11==0.16.0
+    # via uvicorn
+httptools==0.9.0
+    # via uvicorn
+idna==3.20
+    # via anyio
+opentelemetry-api==1.45.1
+    # via fastapi
+pydantic==2.14.1
+    # via
+    #   -r requirements.in
+    #   fastapi
+pydantic-core==2.50.1
+    # via pydantic
+python-dotenv==1.2.4
+    # via uvicorn
+pyyaml==6.0.3
+    # via uvicorn
+starlette==1.10.0
+    # via
+    #   -r requirements.in
+    #   fastapi
+typing-extensions==4.16.0
+    # via
+    #   anyio
+    #   fastapi
+    #   opentelemetry-api
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.4
+    # via
+    #   fastapi
+    #   pydantic
+uvicorn==0.54.0
+    # via -r requirements.in
+watchfiles==1.3.0
+    # via uvicorn
+websockets==17.3
+    # via uvicorn

tests/test_host.py

@@ -0,0 +1,163 @@
+import asyncio
+import os
+import sys
+
+root_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if root_dir not in sys.path:
+    sys.path.insert(0, root_dir)
+
+import logging
+import types
+import pytest
+from fastapi import APIRouter
+from fastapi.testclient import TestClient
+
+
+def create_mock_modules():
+    p1 = types.ModuleType("mock_p1")
+    p1_router_mod = types.ModuleType("mock_p1.router")
+    r1 = APIRouter()
+
+    @r1.get("/ping")
+    def ping_p1():
+        return {"project": "p1", "status": "ok"}
+
+    @r1.post("/echo")
+    def echo_p1(data: dict):
+        return {"project": "p1", "echo": data}
+
+    @r1.get("/slow")
+    async def slow_p1():
+        await asyncio.sleep(0.5)
+        return {"status": "finished"}
+
+    p1_router_mod.router = r1
+    p1.router = p1_router_mod
+    sys.modules["mock_p1"] = p1
+    sys.modules["mock_p1.router"] = p1_router_mod
+
+    p2 = types.ModuleType("mock_p2")
+    p2_router_mod = types.ModuleType("mock_p2.router")
+    r2 = APIRouter()
+
+    @r2.get("/ping")
+    def ping_p2():
+        return {"project": "p2", "status": "ok"}
+
+    p2_router_mod.router = r2
+    p2.router = p2_router_mod
+    sys.modules["mock_p2"] = p2
+    sys.modules["mock_p2.router"] = p2_router_mod
+
+
+def test_host_with_mocks(monkeypatch, caplog):
+    create_mock_modules()
+
+    monkeypatch.setenv("CORS_ALLOWED_ORIGINS", "https://allowed.com,https://example.com")
+    monkeypatch.setenv("MAX_BODY_SIZE_BYTES", "1024")
+    monkeypatch.setenv("REQUEST_TIMEOUT_SECONDS", "0.2")
+    monkeypatch.setenv("DISABLE_PROJECTS", "")
+
+    import registry
+    registry.PROJECT_REGISTRY = {
+        "/project-1": "mock_p1.router:router",
+        "/project-2": "mock_p2.router:router",
+        "/project-3": "nonexistent_module.router:router",
+    }
+
+    if "main" in sys.modules:
+        del sys.modules["main"]
+
+    with caplog.at_level(logging.INFO):
+        import main
+        client = TestClient(main.app)
+
+    assert "[/project-1] Successfully mounted at /project-1" in caplog.text
+    assert "[/project-2] Successfully mounted at /project-2" in caplog.text
+    assert "[/project-3] Failed to mount router" in caplog.text
+
+    res_health = client.get("/health")
+    assert res_health.status_code == 200
+    health_data = res_health.json()
+    assert health_data["status"] == "degraded"
+    assert "/project-1" in health_data["loaded"]
+    assert "/project-2" in health_data["loaded"]
+    assert "/project-3" in health_data["failed"]
+
+    res_p1 = client.get("/project-1/ping")
+    assert res_p1.status_code == 200
+    assert res_p1.json() == {"project": "p1", "status": "ok"}
+
+    res_p2 = client.get("/project-2/ping")
+    assert res_p2.status_code == 200
+    assert res_p2.json() == {"project": "p2", "status": "ok"}
+
+    for doc_url in ["/docs", "/redoc", "/openapi.json"]:
+        assert client.get(doc_url).status_code == 404
+
+    cors_allowed = client.get(
+        "/project-1/ping",
+        headers={"Origin": "https://allowed.com"}
+    )
+    assert cors_allowed.status_code == 200
+    assert cors_allowed.headers.get("access-control-allow-origin") == "https://allowed.com"
+
+    cors_rejected = client.get(
+        "/project-1/ping",
+        headers={"Origin": "https://disallowed.com"}
+    )
+    assert cors_rejected.headers.get("access-control-allow-origin") is None
+
+    oversized_data = {"text": "a" * 2000}
+    res_oversized = client.post("/project-1/echo", json=oversized_data)
+    assert res_oversized.status_code == 413
+
+    res_slow = client.get("/project-1/slow")
+    assert res_slow.status_code == 504
+
+
+def test_kill_switch(monkeypatch):
+    create_mock_modules()
+    monkeypatch.setenv("DISABLE_PROJECTS", "project-2")
+
+    import registry
+    registry.PROJECT_REGISTRY = {
+        "/project-1": "mock_p1.router:router",
+        "/project-2": "mock_p2.router:router",
+    }
+
+    if "main" in sys.modules:
+        del sys.modules["main"]
+
+    import main
+    client = TestClient(main.app)
+
+    res_health = client.get("/health")
+    health_data = res_health.json()
+    assert "/project-1" in health_data["loaded"]
+    assert "/project-2" not in health_data["loaded"]
+    assert "/project-2" not in health_data["failed"]
+
+    assert client.get("/project-1/ping").status_code == 200
+    assert client.get("/project-2/ping").status_code == 404
+
+
+def test_healthy_status_when_all_load(monkeypatch):
+    create_mock_modules()
+    monkeypatch.setenv("DISABLE_PROJECTS", "")
+
+    import registry
+    registry.PROJECT_REGISTRY = {
+        "/project-1": "mock_p1.router:router",
+        "/project-2": "mock_p2.router:router",
+    }
+
+    if "main" in sys.modules:
+        del sys.modules["main"]
+
+    import main
+    client = TestClient(main.app)
+
+    res_health = client.get("/health")
+    assert res_health.status_code == 200
+    assert res_health.json()["status"] == "healthy"