Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

9.4 KB
Raw Blame
import threading
import traceback

from loguru import logger

from ..__version__ import __version__
from ..utilities.log_utils import config_logger
from .server_config import load_server_config


def _install_thread_excepthook() -> None:
    """Install a global hook that loudly logs uncaught exceptions on any
    thread — including daemon threads — so silent crashes in the queue
    processor, APScheduler jobs, or the post-login background thread
    surface in logs instead of leaving the app wedged with no signal.

    Respects a previously-installed hook if any (chains to it).
    """
    previous = threading.excepthook

    def _hook(args: threading.ExceptHookArgs) -> None:
        # Don't try to log for SystemExit-in-thread; that is intentional.
        if issubclass(args.exc_type, SystemExit):
            return
        try:
            tb = "".join(
                traceback.format_exception(
                    args.exc_type, args.exc_value, args.exc_traceback
                )
            )
            thread_name = (
                args.thread.name if args.thread is not None else "unknown"
            )
            logger.error(
                f"Uncaught exception on thread {thread_name!r}: "
                f"{args.exc_type.__name__}: {args.exc_value}\n{tb}"
            )
        except Exception:
            pass  # noqa: silent-exception — last-ditch; the excepthook itself must never crash the interpreter
        finally:
            # Chain to the previous hook (usually threading's default).
            try:
                previous(args)
            except Exception:
                pass  # noqa: silent-exception — previous hook failing must not turn our hook into a crash vector

    threading.excepthook = _hook


# reraise=True is load-bearing: without it a fatal startup error is logged and
# then SWALLOWED, main() returns None, and the console script exits 0 — so
# systemd `Restart=on-failure` and Kubernetes `restartPolicy: OnFailure` read a
# dead server as a clean shutdown and never restart it. uvicorn loads the app
# eagerly on the workers==1 path, so app-import failures land inside main()
# rather than before it. This PR widened the exposure: _load_secret_key() now
# hard-raises where the Flask app fell back to an ephemeral key. SystemExit
# already propagated (a port conflict correctly exits 3); this makes real
# exceptions behave the same way while keeping loguru's formatted traceback.
@logger.catch(reraise=True)
def main():
    """
    Entry point for the web application (ldr-web command).

    Launches uvicorn with the FastAPI app.
    """
    # Install the excepthook before any other threads are spawned so
    # uncaught exceptions in daemon threads (queue processor, APScheduler
    # jobs, post-login background thread) surface in logs instead of
    # dying silently.
    _install_thread_excepthook()

    config = load_server_config()
    config_logger("ldr_web", debug=config["debug"])
    from ..security.process_dump_policy import enforce_process_dump_policy

    enforce_process_dump_policy()
    logger.info(f"Starting Local Deep Research v{__version__}")

    # One-time removal of plaintext legacy RAG docstores (phase 1 of the
    # vector-store cutover -- see vector_stores/legacy_cleanup.py). Pure
    # filesystem, no DB/login required, so it belongs here at the real
    # server-start entrypoint (not in the app factory / lifespan, which the
    # test suite exercises without LDR_DATA_DIR isolation -- wiring it there
    # would delete a developer's real .pkl files on every test run). Wrapped
    # so a cleanup issue never blocks boot; the function logs its own errors
    # and is idempotent. Ports #5143.
    try:
        from ..vector_stores.legacy_cleanup import migrate_legacy_docstores

        migrate_legacy_docstores()
    except Exception:
        logger.exception("Legacy RAG docstore migration failed at startup")

    # Ported from main: `web.use_https` never actually served TLS on either
    # framework -- main only logged that it is unsupported and told the
    # operator to front the app with a reverse proxy. Without this, someone
    # who sets LDR_WEB_USE_HTTPS=true gets total silence and reasonably
    # assumes TLS is on. Say so plainly instead.
    if config.get("use_https"):
        logger.warning(
            "web.use_https is set, but HTTPS is not served directly. "
            "Terminate TLS at a reverse proxy (nginx, Caddy, Traefik) in "
            "front of this server; it is listening on plain HTTP."
        )

    _run_with_uvicorn(config["host"], config["port"], config["debug"])


def _normalise_forwarded_allow_ips(raw: str) -> str:
    """The allow-list string uvicorn is handed for ``raw``.

    TWIN of ``web/dependencies/rate_limit.py``'s
    ``_normalise_forwarded_allow_ips`` -- duplicated rather than
    imported because importing that module here would run its
    import-time startup guard and freeze its view of the allow-list
    before uvicorn has started, and would pull slowapi/limits and the
    server config into this launcher. The two are pinned together by
    tests/security/test_middleware_and_proxy_trust_fastapi.py::
    TestTrustProxyHeadersUvicornWiring::
    test_app_and_rate_limit_normalise_identically.
    """
    return (
        ",".join(item.strip() for item in raw.split(",") if item.strip()) or "*"
    )


def _run_with_uvicorn(host: str, port: int, debug: bool) -> None:
    """Launch the FastAPI app via uvicorn.

    Lifespan-managed startup/shutdown lives in `fastapi_app.py`; this
    function only deals with launching the ASGI server. Logging,
    log-queue processor lifecycle, scheduler shutdown, and DB
    teardown are all handled inside the FastAPI lifespan.
    """
    import os

    import uvicorn

    # When TRUST_PROXY_HEADERS is set (operator is behind nginx/caddy/traefik),
    # honor X-Forwarded-Proto / X-Forwarded-For so request.url.scheme reflects
    # TLS termination and HSTS + Secure-cookie logic work correctly. Without
    # this, the app always sees http:// behind a TLS proxy.
    trust_proxy = os.environ.get("TRUST_PROXY_HEADERS", "").lower() in (
        "true",
        "1",
        "yes",
    )

    # Which direct peers uvicorn's ProxyHeadersMiddleware will trust forwarded
    # headers from -- passed straight through to uvicorn's own
    # `--forwarded-allow-ips`. Defaults to "*" (any peer) for backward
    # compatibility with every deployment that has only ever set
    # TRUST_PROXY_HEADERS=true.
    #
    # This default is exactly what makes TRUST_PROXY_HEADERS=true UNSAFE to
    # combine with `web/dependencies/rate_limit.py`'s
    # LDR_SERVER_TRUSTED_PROXY_COUNT hop-count mode: with "*", the middleware
    # rewrites `scope["client"]` to the client-forgeable left-most
    # X-Forwarded-For entry for ANY direct connection, not just ones from the
    # real proxy -- poisoning the hop-count logic's fallback-to-direct-peer
    # safety net before it ever runs (see rate_limit.py's import-time check).
    # Restricting this to the actual reverse-proxy IP(s) closes that hole:
    # uvicorn then only rewrites `scope["client"]` for connections whose
    # DIRECT peer is one of these addresses, so an attacker connecting
    # straight to LDR keeps their real socket peer and the rate limiter's
    # trust boundary stays intact. See "Combining TRUST_PROXY_HEADERS with
    # LDR_SERVER_TRUSTED_PROXY_COUNT" in docs/deployment/reverse-proxy.md
    # for the recommended value here.
    #
    # Normalised per entry, not as one string: `web/dependencies/
    # rate_limit.py` classifies the SAME value and names it in the
    # RuntimeError, the startup warning and the info line it logs, so a
    # value the two read differently would make every one of those
    # messages describe an allow-list uvicorn was never handed. `","`
    # used to arrive here as the literal `","` (one entry matching
    # nothing, every client in one bucket) while rate_limit.py read it
    # as unset.
    forwarded_allow_ips = _normalise_forwarded_allow_ips(
        os.environ.get("LDR_SERVER_FORWARDED_ALLOW_IPS", "")
    )

    uvicorn.run(
        "local_deep_research.web.fastapi_app:app",
        host=host,
        port=port,
        workers=1,  # Required for Socket.IO without Redis message queue
        log_level="warning",  # uvicorn's own log level; app uses loguru
        # No per-request access log. main justified this with an app-level
        # request-logging middleware; nothing in the FastAPI app logs a
        # request line today, so only explicit app events reach loguru.
        access_log=False,
        # Don't advertise the server stack. Flask/werkzeug's Server header
        # was suppressed on main; uvicorn sends "server: uvicorn" by default,
        # which re-introduces the fingerprinting main deliberately removed.
        server_header=False,
        timeout_keep_alive=5,
        # Bound how long we wait for in-flight requests to drain on
        # SIGTERM/SIGINT. Without this, uvicorn waits forever for
        # long-running streams (research SSE) and the process never exits.
        timeout_graceful_shutdown=10,
        proxy_headers=trust_proxy,
        forwarded_allow_ips=forwarded_allow_ips if trust_proxy else None,
        # Cap inbound WebSocket messages at the transport (uvicorn's default
        # is 16 MiB). Must equal socketio_asgi.MAX_INBOUND_MESSAGE_BYTES;
        # kept as a literal so this launcher does not import the app module
        # before uvicorn starts.
        ws_max_size=65536,
    )


if __name__ == "__main__":
    main()