Merge pull request #306 from bg-playground/copilot/bgstm-300-implement-session-endpoints

Implement External Results session endpoints (BGSTM#300)

Author: bg-playground

backend/alembic/env.py

@@ -24,6 +24,7 @@
 
 # Import Base.metadata for autogenerate support.
 # All models must be imported so their tables are registered on Base.metadata.
+import app.models.external_results  # noqa: E402, F401
 import app.models.link  # noqa: E402, F401
 import app.models.requirement  # noqa: E402, F401
 import app.models.suggestion  # noqa: E402, F401

backend/alembic/versions/h7i8j9k0l1m2_add_external_run_sessions.py

@@ -0,0 +1,62 @@
+"""add external_run_sessions table
+
+Revision ID: h7i8j9k0l1m2
+Revises: g6h7i8j9k0l1
+Create Date: 2026-05-06 22:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "h7i8j9k0l1m2"
+down_revision: Union[str, None] = "g6h7i8j9k0l1"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "external_run_sessions",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("runner", sa.String(255), nullable=False),
+        sa.Column(
+            "status",
+            sa.Enum("started", "passed", "failed", "skipped", "aborted", name="runstatus"),
+            nullable=False,
+            server_default="started",
+        ),
+        sa.Column("git_sha", sa.String(255), nullable=True),
+        sa.Column("git_branch", sa.String(255), nullable=True),
+        sa.Column("ci_url", sa.String(2048), nullable=True),
+        sa.Column("run_metadata", sa.JSON(), nullable=True),
+        sa.Column("started_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.Column("finished_at", sa.DateTime(), nullable=True),
+        sa.Column("summary", sa.JSON(), nullable=True),
+        sa.Column(
+            "created_by_runner_token_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("runner_tokens.id"),
+            nullable=False,
+        ),
+    )
+    op.create_index("idx_external_run_sessions_project_id", "external_run_sessions", ["project_id"])
+    op.create_index(
+        "idx_external_run_sessions_runner_token_id",
+        "external_run_sessions",
+        ["created_by_runner_token_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_external_run_sessions_runner_token_id", table_name="external_run_sessions")
+    op.drop_index("idx_external_run_sessions_project_id", table_name="external_run_sessions")
+    op.drop_table("external_run_sessions")
+    # Drop the enum type on PostgreSQL (no-op on other dialects).
+    op.execute("DROP TYPE IF EXISTS runstatus")

backend/app/api/external_results.py

@@ -0,0 +1,178 @@
+"""API router for External Results — session endpoints (BGSTM#300).
+
+Implements:
+  POST   /external-results/session          – start a run (201 Created)
+  PATCH  /external-results/session/{id}     – finish a run
+  GET    /external-results/session/{id}     – read a session (runner OR user JWT)
+
+Case-result endpoints  → BGSTM#303
+Artifact endpoints     → BGSTM#298
+Audit-log integration  → BGSTM#297
+"""
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Header, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.dependencies import (
+    get_current_runner_token,  # noqa: F401 — used inside _get_session_auth
+    require_runner_scope,
+)
+from app.crud.external_results import create_session, finish_session_db, get_session
+from app.db.session import get_db
+from app.models.runner_token import RunnerToken
+from app.schemas.external_results import SessionCreate, SessionFinish, SessionResponse
+
+router = APIRouter()
+
+_WRITE_SCOPE = "external_results:write"
+_READ_SCOPE = "external_results:read"
+
+
+def _session_to_response(session) -> SessionResponse:
+    """Map an ExternalRunSession ORM row to a SessionResponse.
+
+    The ci_url column stores a plain string; SessionResponse expects an
+    HttpUrl-compatible value.  We pass it through as-is — Pydantic will
+    validate and coerce it when constructing the model.
+    """
+    return SessionResponse(
+        id=session.id,
+        status=session.status,
+        started_at=session.started_at,
+        finished_at=session.finished_at,
+        runner=session.runner,
+        project_id=session.project_id,
+        git_sha=session.git_sha,
+        git_branch=session.git_branch,
+        ci_url=session.ci_url,
+        metadata=session.run_metadata or {},
+    )
+
+
+# ---------------------------------------------------------------------------
+# POST /external-results/session — start a run
+# ---------------------------------------------------------------------------
+
+
+@router.post(
+    "/external-results/session",
+    response_model=SessionResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_external_session(
+    payload: SessionCreate,
+    db: AsyncSession = Depends(get_db),
+    token: RunnerToken = Depends(require_runner_scope(_WRITE_SCOPE)),
+) -> SessionResponse:
+    """Start a new external test-run session.
+
+    Returns the existing session if an identical session was created within the
+    last 60 seconds (idempotency window).
+    """
+    session = await create_session(db, payload=payload, runner_token_id=token.id)
+    return _session_to_response(session)
+
+
+# ---------------------------------------------------------------------------
+# PATCH /external-results/session/{session_id} — finish a run
+# ---------------------------------------------------------------------------
+
+
+@router.patch(
+    "/external-results/session/{session_id}",
+    response_model=SessionResponse,
+)
+async def finish_external_session(
+    session_id: UUID,
+    payload: SessionFinish,
+    db: AsyncSession = Depends(get_db),
+    token: RunnerToken = Depends(require_runner_scope(_WRITE_SCOPE)),  # noqa: ARG001
+) -> SessionResponse:
+    """Set the terminal status of a session.
+
+    Returns 404 if the session does not exist.
+    Returns 409 if the status transition is not allowed (e.g. already finished).
+    """
+    try:
+        session = await finish_session_db(db, session_id=session_id, payload=payload)
+    except ValueError as exc:
+        detail = exc.args[0]
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=detail) from exc
+
+    if session is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"code": "session.not_found", "message": f"Session {session_id} does not exist.", "details": None},
+        )
+
+    return _session_to_response(session)
+
+
+# ---------------------------------------------------------------------------
+# GET /external-results/session/{session_id} — read a session
+# ---------------------------------------------------------------------------
+
+
+async def _get_session_auth(
+    authorization: str | None = Header(None),
+    db: AsyncSession = Depends(get_db),
+):
+    """Accept either a runner token or a user JWT for read access.
+
+    We attempt runner-token resolution first; on failure we fall back to user
+    JWT.  A 401 is raised only when both paths fail.
+    """
+    # Try runner-token path
+    if authorization and authorization.lower().startswith("bearer bgstm_runner_"):
+        from app.auth.dependencies import get_current_runner_token as _get_runner
+
+        try:
+            return await _get_runner(authorization=authorization, db=db)
+        except HTTPException:
+            pass
+
+    # Fall back to user-JWT path via the bearer scheme
+
+    from app.auth.security import decode_access_token
+    from app.crud.user import get_user
+
+    if authorization and authorization.lower().startswith("bearer "):
+        raw_token = authorization.split(" ", 1)[1]
+        payload = decode_access_token(raw_token)
+        if payload is not None:
+            user_id = payload.get("sub")
+            if user_id:
+                user = await get_user(db, user_id)
+                if user and user.is_active:
+                    return user
+
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail={"code": "runner_token.invalid", "message": "Missing or invalid credentials.", "details": None},
+    )
+
+
+@router.get(
+    "/external-results/session/{session_id}",
+    response_model=SessionResponse,
+)
+async def get_external_session(
+    session_id: UUID,
+    db: AsyncSession = Depends(get_db),
+    _auth=Depends(_get_session_auth),
+) -> SessionResponse:
+    """Return a single session by ID.
+
+    Accepts either a runner token (any scope) or a standard user JWT.
+    Returns 404 if the session does not exist.
+    """
+    session = await get_session(db, session_id)
+    if session is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"code": "session.not_found", "message": f"Session {session_id} does not exist.", "details": None},
+        )
+
+    return _session_to_response(session)

backend/app/crud/external_results.py

@@ -0,0 +1,129 @@
+"""CRUD operations for External Run Sessions (BGSTM#300)."""
+
+from datetime import datetime, timedelta, timezone
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.external_results import ExternalRunSession, RunStatus
+from app.schemas.external_results import SessionCreate, SessionFinish
+
+# Terminal statuses — no further transitions allowed once reached.
+_TERMINAL_STATUSES = {RunStatus.passed, RunStatus.failed, RunStatus.aborted}
+
+# Idempotency window in seconds: duplicate session creates within this window
+# (same project_id, runner, ci_url, git_sha) return the existing session.
+_IDEMPOTENCY_WINDOW_SECONDS = 60
+
+
+async def create_session(
+    db: AsyncSession,
+    *,
+    payload: SessionCreate,
+    runner_token_id: UUID,
+) -> ExternalRunSession:
+    """Create a new ExternalRunSession, honouring the idempotency window.
+
+    If an active (started) session with the same (project_id, runner, ci_url,
+    git_sha) was created within the last ``_IDEMPOTENCY_WINDOW_SECONDS``
+    seconds by the same runner token, the existing session is returned instead
+    of creating a duplicate.
+
+    # TODO(#297): Write audit entry ``external_results.session.start`` here.
+    """
+    cutoff = datetime.now(tz=timezone.utc).replace(tzinfo=None) - timedelta(seconds=_IDEMPOTENCY_WINDOW_SECONDS)
+
+    # Normalise ci_url to a plain string so we can compare it.
+    ci_url_str = str(payload.ci_url) if payload.ci_url is not None else None
+
+    stmt = (
+        select(ExternalRunSession)
+        .where(ExternalRunSession.project_id == payload.project_id)
+        .where(ExternalRunSession.runner == payload.runner)
+        .where(ExternalRunSession.created_by_runner_token_id == runner_token_id)
+        .where(ExternalRunSession.status == RunStatus.started)
+        .where(ExternalRunSession.started_at >= cutoff)
+    )
+    if ci_url_str is not None:
+        stmt = stmt.where(ExternalRunSession.ci_url == ci_url_str)
+    else:
+        stmt = stmt.where(ExternalRunSession.ci_url.is_(None))
+
+    if payload.git_sha is not None:
+        stmt = stmt.where(ExternalRunSession.git_sha == payload.git_sha)
+    else:
+        stmt = stmt.where(ExternalRunSession.git_sha.is_(None))
+
+    result = await db.execute(stmt)
+    existing = result.scalar_one_or_none()
+    if existing is not None:
+        return existing
+
+    session = ExternalRunSession(
+        project_id=payload.project_id,
+        runner=payload.runner,
+        status=RunStatus.started,
+        git_sha=payload.git_sha,
+        git_branch=payload.git_branch,
+        ci_url=ci_url_str,
+        run_metadata=payload.metadata,
+        started_at=datetime.now(tz=timezone.utc).replace(tzinfo=None),
+        created_by_runner_token_id=runner_token_id,
+    )
+    db.add(session)
+    await db.commit()
+    await db.refresh(session)
+    return session
+
+
+async def finish_session_db(
+    db: AsyncSession,
+    *,
+    session_id: UUID,
+    payload: SessionFinish,
+) -> ExternalRunSession | None:
+    """Apply the finish payload to the session and return the updated model.
+
+    Returns ``None`` if the session does not exist.
+
+    Raises ``ValueError`` with a structured dict payload on transition
+    violations so the API layer can return the appropriate 409.
+
+    # TODO(#297): Write audit entry ``external_results.session.finish`` here.
+    """
+    result = await db.execute(select(ExternalRunSession).where(ExternalRunSession.id == session_id))
+    session = result.scalar_one_or_none()
+    if session is None:
+        return None
+
+    current = RunStatus(session.status)
+
+    # All terminal statuses block further transitions.
+    if current in _TERMINAL_STATUSES:
+        raise ValueError(
+            {
+                "code": "session.transition.invalid",
+                "message": (
+                    f"Cannot transition session from '{current.value}' to '{payload.status.value}': "
+                    f"session is already in a terminal state."
+                ),
+                "details": {"current_status": current.value, "requested_status": payload.status.value},
+            }
+        )
+
+    session.status = payload.status
+    session.summary = payload.summary
+    session.finished_at = datetime.now(tz=timezone.utc).replace(tzinfo=None)
+    await db.commit()
+    await db.refresh(session)
+    return session
+
+
+async def get_session(
+    db: AsyncSession,
+    session_id: UUID,
+) -> ExternalRunSession | None:
+    """Return a single ExternalRunSession by primary key, or None."""
+    result = await db.execute(select(ExternalRunSession).where(ExternalRunSession.id == session_id))
+    return result.scalar_one_or_none()

backend/app/main.py

@@ -7,6 +7,7 @@
     analytics,
     audit_log,
     auth,
+    external_results,
     links,
     notifications,
     requirements,
@@ -40,6 +41,7 @@
 app.include_router(audit_log.router, prefix=settings.API_V1_PREFIX, tags=["audit_log"])
 app.include_router(users.router, prefix=settings.API_V1_PREFIX, tags=["users"])
 app.include_router(notifications.router, prefix=settings.API_V1_PREFIX, tags=["notifications"])
+app.include_router(external_results.router, prefix=settings.API_V1_PREFIX, tags=["external_results"])
 
 
 @app.on_event("startup")