Function index_url

agent/src/opentrace_agent/cli/serve.py:491–547

POST /api/index-url Body: ``{repoUrl, repoId?, token?, ref?, zipball?, reindex?}``. Spawns a background thread that clones the repo, runs the indexing pipeline, and reopens the live store after the atomic swap. Returns the job id immediately; the UI polls ``

(request: Request)

            _trim_index_jobs()

    async def index_url(request: Request) -> JSONResponse:
        """POST /api/index-url

        Body: ``{repoUrl, repoId?, token?, ref?, zipball?, reindex?}``.

        Spawns a background thread that clones the repo, runs the
        indexing pipeline, and reopens the live store after the atomic
        swap. Returns the job id immediately; the UI polls
        ``GET /api/index-progress/{jobId}`` for progress.

        Refuses with 409 Conflict when another index is already
        running — the underlying pipeline holds an exclusive flock on
        the DB, so a concurrent submission would fail anyway, but
        only several stages in. Failing fast at the HTTP boundary
        lets the UI surface a friendly message (Fix #12).
        """
        if db_path is None:
            return _error(503, "Server was started without --db; indexing is unavailable")
        body = await _read_json(request)
        if not body or not body.get("repoUrl"):
            return _error(400, "Missing required field: repoUrl")
        if not isinstance(body.get("repoUrl"), str):
            return _error(400, "Invalid field: repoUrl must be a string")

        # Atomic check-and-insert: hold the lock across both the active-job
        # guard and the new job's insertion. Releasing between the two would
        # let two concurrent requests both observe no active job and each
        # spawn an indexing thread (TOCTOU), wasting clone/parse work.
        job_id = uuid.uuid4().hex
        with index_jobs_lock:
            active = [jid for jid, st in index_jobs.items() if not st.get("done")]
            if active:
                return _error(
                    409,
                    "Another index is already running on this agent. Wait for it to finish before starting a new one.",
                )

            index_jobs[job_id] = {
                "jobId": job_id,
                "phase": "queued",
                "message": "Queued",
                "done": False,
                "error": None,
                "result": None,
                "startedAt": time.time(),
            }

        # daemon=True so the thread doesn't keep the process alive past
        # uvicorn shutdown (matters for cleanup; not for correctness).
        thread = threading.Thread(
            target=_run_index_url_job,
            args=(job_id, body, db_path),
            daemon=True,
            name=f"index-url-{job_id[:8]}",
        )
        thread.start()
        return JSONResponse({"jobId": job_id, "status": "queued"}, status_code=202)