solace-agent-mesh 0.2.4__py3-none-any.whl → 1.0.2__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/routers/auth.py

@@ -0,0 +1,212 @@
+"""
+Router for handling authentication-related endpoints.
+"""
+
+from fastapi import (
+    APIRouter,
+    Request as FastAPIRequest,
+    Depends,
+    HTTPException,
+    Response,
+)
+from fastapi.responses import RedirectResponse
+import httpx
+import secrets
+from urllib.parse import urlencode
+
+from ...http_sse.dependencies import get_sac_component, get_api_config
+from solace_ai_connector.common.log import log
+
+router = APIRouter()
+
+
+@router.get("/auth/login")
+async def initiate_login(
+    request: FastAPIRequest, config: dict = Depends(get_api_config)
+):
+    """
+    Initiates the login flow by redirecting to the external authorization service.
+    """
+    external_auth_url = config.get("external_auth_service_url", "http://localhost:8080")
+    callback_url = config.get(
+        "external_auth_callback_uri", "http://localhost:8000/api/v1/auth/callback"
+    )
+
+    params = {
+        "provider": config.get("external_auth_provider", "azure"),
+        "redirect_uri": callback_url,
+    }
+
+    login_url = f"{external_auth_url}/login?{urlencode(params)}"
+    log.info(f"Redirecting to external authorization service: {login_url}")
+
+    return RedirectResponse(url=login_url)
+
+
+@router.get("/csrf-token")
+async def get_csrf_token(
+    response: Response, component: "WebUIBackendComponent" = Depends(get_sac_component)
+):
+    """
+    Generates and returns a CSRF token, setting it as a readable cookie and returning it in the response.
+    """
+    csrf_token = secrets.token_urlsafe(32)
+
+    response.set_cookie(
+        key="csrf_token",
+        value=csrf_token,
+        httponly=False,
+        secure=False,
+        samesite="lax",
+        max_age=3600,
+    )
+
+    return {"message": "CSRF token set", "csrf_token": csrf_token}
+
+
+@router.get("/auth/callback")
+async def auth_callback(
+    request: FastAPIRequest,
+    config: dict = Depends(get_api_config),
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+):
+    """
+    Handles the callback from the OIDC provider by calling an external exchange service.
+    """
+    code = request.query_params.get("code")
+
+    if not code:
+        raise HTTPException(status_code=400, detail="Missing authorization code")
+
+    external_auth_url = config.get("external_auth_service_url", "http://localhost:8080")
+    exchange_url = f"{external_auth_url}/exchange-code"
+    redirect_uri = config.get(
+        "external_auth_callback_uri", "http://localhost:8000/api/v1/auth/callback"
+    )
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.post(
+                exchange_url,
+                json={
+                    "code": code,
+                    "provider": config.get("external_auth_provider", "azure"),
+                    "redirect_uri": redirect_uri,
+                },
+                timeout=20.0,
+            )
+            response.raise_for_status()
+            token_data = response.json()
+        except httpx.HTTPStatusError as e:
+            log.error(f"Failed to exchange code: {e.response.text}")
+            raise HTTPException(
+                status_code=e.response.status_code,
+                detail=f"Failed to exchange code: {e.response.text}",
+            )
+        except Exception as e:
+            log.error(f"Error during code exchange: {e}")
+            raise HTTPException(status_code=500, detail="Error during code exchange")
+
+    access_token = token_data.get("access_token")
+    refresh_token = token_data.get("refresh_token")
+
+    if not access_token:
+        raise HTTPException(
+            status_code=400, detail="Access token not in response from exchange service"
+        )
+
+    request.session["access_token"] = access_token
+    if refresh_token:
+        request.session["refresh_token"] = refresh_token
+    log.debug("Tokens stored directly in session.")
+
+    try:
+        async with httpx.AsyncClient() as client:
+            user_info_response = await client.get(
+                f"{external_auth_url}/user_info",
+                params={"provider": config.get("external_auth_provider", "azure")},
+                headers={"Authorization": f"Bearer {access_token}"},
+            )
+            user_info_response.raise_for_status()
+            user_info = user_info_response.json()
+
+            user_id = user_info.get("email", "authenticated_user")
+            if user_id:
+                session_manager = component.get_session_manager()
+                session_manager.store_user_id(request, user_id)
+            else:
+                log.warning("Could not find 'email' in user info response.")
+
+    except httpx.HTTPStatusError as e:
+        log.error(f"Failed to get user info: {e.response.text}")
+
+    except Exception as e:
+        log.error(f"Error getting user info: {e}")
+
+    frontend_base_url = config.get("frontend_redirect_url", "http://localhost:3000")
+
+    hash_params = {"access_token": access_token}
+    if refresh_token:
+        hash_params["refresh_token"] = refresh_token
+
+    hash_fragment = urlencode(hash_params)
+
+    frontend_redirect_url = f"{frontend_base_url}/auth-callback.html#{hash_fragment}"
+    return RedirectResponse(url=frontend_redirect_url)
+
+
+@router.post("/auth/refresh")
+async def refresh_token(
+    request: FastAPIRequest,
+    config: dict = Depends(get_api_config),
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+):
+    """
+    Refreshes an access token using the external authorization service.
+    """
+    data = await request.json()
+    refresh_token = data.get("refresh_token")
+    if not refresh_token:
+        raise HTTPException(status_code=400, detail="Missing refresh_token")
+
+    external_auth_url = config.get("external_auth_service_url", "http://localhost:8080")
+    refresh_url = f"{external_auth_url}/refresh_token"
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.post(
+                refresh_url,
+                json={
+                    "refresh_token": refresh_token,
+                    "provider": config.get("external_auth_provider", "azure"),
+                },
+                timeout=20.0,
+            )
+            response.raise_for_status()
+            token_data = response.json()
+        except httpx.HTTPStatusError as e:
+            log.error(f"Failed to refresh token: {e.response.text}")
+            raise HTTPException(
+                status_code=e.response.status_code,
+                detail=f"Failed to refresh token: {e.response.text}",
+            )
+        except Exception as e:
+            log.error(f"Error during token refresh: {e}")
+            raise HTTPException(status_code=500, detail="Error during token refresh")
+
+    access_token = token_data.get("access_token")
+    new_refresh_token = token_data.get("refresh_token")
+
+    if not access_token:
+        raise HTTPException(
+            status_code=400, detail="Access token not in response from refresh service"
+        )
+
+    session_manager = component.get_session_manager()
+    session_manager.store_auth_tokens(request, access_token, new_refresh_token)
+    log.info("Successfully refreshed and updated tokens in session.")
+
+    return {
+        "access_token": access_token,
+        "refresh_token": new_refresh_token,
+    }

solace_agent_mesh/gateway/http_sse/routers/config.py

@@ -0,0 +1,55 @@
+"""
+API Router for providing frontend configuration.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from typing import Dict, Any
+
+from solace_ai_connector.common.log import log
+
+from ....gateway.http_sse.dependencies import get_sac_component
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gateway.http_sse.component import WebUIBackendComponent
+
+router = APIRouter()
+
+
+@router.get("/config", response_model=Dict[str, Any])
+async def get_app_config(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+):
+    """
+    Provides configuration settings needed by the frontend application.
+    """
+    log_prefix = "[GET /api/v1/config] "
+    log.info("%sRequest received.", log_prefix)
+    try:
+        config_data = {
+            "frontend_server_url": "",
+            "frontend_auth_login_url": component.get_config(
+                "frontend_auth_login_url", ""
+            ),
+            "frontend_use_authorization": component.get_config(
+                "frontend_use_authorization", False
+            ),
+            "frontend_welcome_message": component.get_config(
+                "frontend_welcome_message", ""
+            ),
+            "frontend_redirect_url": component.get_config("frontend_redirect_url", ""),
+            "frontend_collect_feedback": component.get_config(
+                "frontend_collect_feedback", False
+            ),
+            "frontend_bot_name": component.get_config("frontend_bot_name", "A2A Agent"),
+        }
+        log.info("%sReturning frontend configuration.", log_prefix)
+        return config_data
+    except Exception as e:
+        log.exception(
+            "%sError retrieving configuration for frontend: %s", log_prefix, e
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error retrieving configuration.",
+        )

solace_agent_mesh/gateway/http_sse/routers/people.py

@@ -0,0 +1,69 @@
+"""
+API endpoints for people-related features, such as user search for autocomplete.
+"""
+
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, Query
+from solace_ai_connector.common.log import log
+
+from ..dependencies import get_people_service
+from ..services.people_service import PeopleService
+
+router = APIRouter()
+
+
+@router.get("/people/search", response_model=List[Dict[str, Any]])
+async def search_people(
+    q: str = Query(
+        ...,
+        min_length=2,
+        max_length=50,
+        description="Search query for user name/email.",
+    ),
+    limit: int = Query(
+        10, ge=1, le=25, description="Maximum number of results to return."
+    ),
+    people_service: PeopleService = Depends(get_people_service),
+):
+    """
+    Searches for users to populate frontend autocomplete suggestions (e.g., for @mentions).
+    """
+    log.debug("Endpoint /people/search called with query: '%s'", q)
+    results = await people_service.search_for_users(query=q, limit=limit)
+    return results
+
+
+"""
+API endpoints for people-related features, such as user search for autocomplete.
+"""
+
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, Query
+from solace_ai_connector.common.log import log
+from ..dependencies import get_people_service
+from ..services.people_service import PeopleService
+
+router = APIRouter()
+
+
+@router.get("/people/search", response_model=List[Dict[str, Any]])
+async def search_people(
+    q: str = Query(
+        ...,
+        min_length=2,
+        max_length=50,
+        description="Search query for user name/email.",
+    ),
+    limit: int = Query(
+        10, ge=1, le=25, description="Maximum number of results to return."
+    ),
+    people_service: PeopleService = Depends(get_people_service),
+):
+    """
+    Searches for users to populate frontend autocomplete suggestions (e.g., for @mentions).
+    """
+    log.debug("Endpoint /people/search called with query: '%s'", q)
+    results = await people_service.search_for_users(query=q, limit=limit)
+    return results

solace_agent_mesh/gateway/http_sse/routers/routers_llm.txt

@@ -0,0 +1,37 @@
+Here is the DEVELOPER GUIDE for the `routers` directory.
+
+## Quick Summary
+The `routers` directory contains FastAPI `APIRouter` modules that define the REST API endpoints for the HTTP SSE Gateway. Each file groups endpoints by a specific domain of functionality, such as agent discovery, artifact management, user authentication, task submission, and real-time event streaming. These routers are the primary interface for frontend applications and other clients to interact with the gateway.
+
+## Files Overview
+- `__init__.py`: Marks the directory as a Python package.
+- `agents.py`: API endpoints for discovering available A2A agents.
+- `artifacts.py`: REST endpoints for managing session-specific artifacts (upload, download, list, delete).
+- `auth.py`: Endpoints for handling the user authentication flow (login, callback, refresh, CSRF).
+- `config.py`: API endpoint for providing configuration settings to the frontend application.
+- `people.py`: API endpoints for user search functionality, typically for autocomplete features.
+- `sessions.py`: API endpoints for managing user sessions (creating new sessions, getting current session info).
+- `sse.py`: The Server-Sent Events (SSE) endpoint for streaming real-time task updates to the client.
+- `tasks.py`: API endpoints for submitting tasks to agents and managing their lifecycle (e.g., cancellation).
+- `users.py`: API endpoint for retrieving information about the currently authenticated user.
+- `visualization.py`: API endpoints for managing A2A message visualization streams for monitoring and debugging.
+
+## Developer API Reference
+
+### agents.py
+**Purpose:** Provides REST endpoints for agent discovery.
+**Import:** `from src.solace_agent_mesh.gateway.http_sse.routers.agents import router`
+
+**Functions:**
+- `get_discovered_agents() -> List[AgentCard]`: Retrieves a list of all currently discovered and available A2A agents. The `AgentCard` type contains details about each agent.
+
+**Usage Examples:**
+```python
+# To include this router in a FastAPI application
+from fastapi import FastAPI
+from src.solace_agent_mesh.gateway.http_sse.routers.agents import router
+
+app = FastAPI()
+app.include_router(router, prefix="/api/v1")
+
+# A client would make a GET request to /api/v1/agents

solace_agent_mesh/gateway/http_sse/routers/sessions.py

@@ -0,0 +1,80 @@
+"""
+API Router for managing user sessions.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, Request as FastAPIRequest, status
+from typing import TYPE_CHECKING
+
+from solace_ai_connector.common.log import log
+from ....gateway.http_sse.session_manager import SessionManager
+from ....gateway.http_sse.dependencies import get_session_manager
+from ....common.types import JSONRPCResponse, InternalError
+
+if TYPE_CHECKING:
+    from ....gateway.http_sse.component import WebUIBackendComponent
+
+router = APIRouter()
+
+
+@router.post("/new", response_model=JSONRPCResponse)
+async def create_new_session(
+    request: FastAPIRequest,
+    session_manager: SessionManager = Depends(get_session_manager),
+):
+    """
+    Forces creation of a new A2A session, replacing any existing one.
+    Returns the new session ID.
+    """
+    log_prefix = "[POST /api/v1/sessions/new] "
+    log.info("%sReceived new session creation request", log_prefix)
+
+    try:
+        new_session_id = session_manager.start_new_a2a_session(request)
+
+        log.info("%sCreated new A2A session: %s", log_prefix, new_session_id)
+
+        return JSONRPCResponse(
+            result={
+                "sessionId": new_session_id,
+                "message": "New A2A session created successfully",
+            }
+        )
+
+    except Exception as e:
+        log.exception("%sError creating new session: %s", log_prefix, e)
+        error_resp = InternalError(message=f"Failed to create new session: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=error_resp.model_dump(exclude_none=True),
+        )
+
+
+@router.get("/current", response_model=JSONRPCResponse)
+async def get_current_session(
+    request: FastAPIRequest,
+    session_manager: SessionManager = Depends(get_session_manager),
+):
+    """
+    Returns information about the current session.
+    """
+    log_prefix = "[GET /api/v1/sessions/current] "
+
+    try:
+        client_id = session_manager.get_a2a_client_id(request)
+        session_id = session_manager.get_a2a_session_id(request)
+
+        return JSONRPCResponse(
+            result={
+                "clientId": client_id,
+                "sessionId": session_id,
+                "hasActiveSession": session_id is not None,
+            }
+        )
+
+    except Exception as e:
+        log.exception("%sError getting current session info: %s", log_prefix, e)
+        error_resp = InternalError(message=f"Failed to get session info: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=error_resp.model_dump(exclude_none=True),
+        )

solace_agent_mesh/gateway/http_sse/routers/sse.py

@@ -0,0 +1,138 @@
+"""
+API Router for Server-Sent Events (SSE) subscriptions.
+"""
+
+import asyncio
+import json
+from fastapi import APIRouter, Depends, Request as FastAPIRequest, HTTPException, status
+
+from solace_ai_connector.common.log import log
+
+from sse_starlette.sse import EventSourceResponse
+
+from ....gateway.http_sse.sse_manager import SSEManager
+from ....gateway.http_sse.dependencies import get_sse_manager
+
+router = APIRouter()
+
+
+@router.get("/subscribe/{task_id}")
+async def subscribe_to_task_events(
+    task_id: str,
+    request: FastAPIRequest,
+    sse_manager: SSEManager = Depends(get_sse_manager),
+):
+    """
+    Establishes an SSE connection to receive real-time updates for a specific task.
+    """
+    log_prefix = "[GET /api/v1/sse/subscribe/%s] " % task_id
+    log.info("%sClient requesting SSE subscription.", log_prefix)
+
+    connection_queue: asyncio.Queue = None
+    try:
+        connection_queue = await sse_manager.create_sse_connection(task_id)
+        log.info("%sSSE connection queue created.", log_prefix)
+
+        async def event_generator():
+            nonlocal connection_queue
+            log.debug("%sSSE event generator started.", log_prefix)
+            try:
+                yield {"comment": "SSE connection established"}
+                log.debug("%sSent initial SSE comment.", log_prefix)
+
+                loop_count = 0
+                while True:
+                    loop_count += 1
+                    log.debug(
+                        "%sEvent generator loop iteration: %d", log_prefix, loop_count
+                    )
+
+                    disconnected = await request.is_disconnected()
+                    log.debug(
+                        "%sRequest disconnected status: %s", log_prefix, disconnected
+                    )
+                    if disconnected:
+                        log.info("%sClient disconnected. Breaking loop.", log_prefix)
+                        break
+
+                    try:
+                        log.debug("%sWaiting for event from queue...", log_prefix)
+                        event_payload = await asyncio.wait_for(
+                            connection_queue.get(), timeout=120
+                        )
+                        log.debug(
+                            "%sReceived from queue: %s",
+                            log_prefix,
+                            event_payload is not None,
+                        )
+
+                        if event_payload is None:
+                            log.info(
+                                "%sReceived None sentinel. Closing connection. Breaking loop.",
+                                log_prefix,
+                            )
+                            break
+                        log.debug(
+                            "%sYielding event_payload: %s", log_prefix, event_payload
+                        )
+                        yield event_payload
+                        connection_queue.task_done()
+                        log.debug(
+                            "%sSent event: %s", log_prefix, event_payload.get("event")
+                        )
+
+                    except asyncio.TimeoutError:
+                        log.debug(
+                            "%sSSE queue wait timed out (iteration %d), checking disconnect status.",
+                            log_prefix,
+                            loop_count,
+                        )
+                        continue
+                    except asyncio.CancelledError:
+                        log.info(
+                            "%sSSE event generator cancelled. Breaking loop.",
+                            log_prefix,
+                        )
+                        break
+                    except Exception as q_err:
+                        log.error(
+                            "%sError getting event from queue: %s. Breaking loop.",
+                            log_prefix,
+                            q_err,
+                            exc_info=True,
+                        )
+                        yield {
+                            "event": "error",
+                            "data": json.dumps({"error": "Internal queue error"}),
+                        }
+                        break
+
+            except asyncio.CancelledError:
+                log.info(
+                    "%sSSE event generator explicitly cancelled. Breaking loop.",
+                    log_prefix,
+                )
+            except Exception as gen_err:
+                log.error(
+                    "%sError in SSE event generator: %s",
+                    log_prefix,
+                    gen_err,
+                    exc_info=True,
+                )
+            finally:
+                log.info("%sSSE event generator finished.", log_prefix)
+                if connection_queue:
+                    await sse_manager.remove_sse_connection(task_id, connection_queue)
+                    log.info("%sRemoved SSE connection queue from manager.", log_prefix)
+
+        return EventSourceResponse(event_generator())
+
+    except Exception as e:
+        log.exception("%sError establishing SSE connection: %s", log_prefix, e)
+
+        if connection_queue:
+            await sse_manager.remove_sse_connection(task_id, connection_queue)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to establish SSE connection: %s" % e,
+        )