fraiseql_server/routes/api/

federation.rs

//! Federation API endpoints.
//!
//! Provides endpoints for:
//! - Listing subgraphs and their health status
//! - Exporting federation dependency graphs in multiple formats (JSON, DOT, Mermaid)

use axum::{
    Json,
    extract::{Query, State},
};
use fraiseql_core::db::traits::DatabaseAdapter;
use serde::{Deserialize, Serialize};

use crate::routes::{
    api::types::{ApiError, ApiResponse},
    graphql::AppState,
};

/// Response containing federation subgraph information.
#[derive(Debug, Serialize)]
pub struct SubgraphsResponse {
    /// List of federated subgraphs
    pub subgraphs: Vec<SubgraphInfo>,
}

/// Information about a single federated subgraph.
#[derive(Debug, Serialize, Clone)]
pub struct SubgraphInfo {
    /// Name of the subgraph
    pub name:     String,
    /// GraphQL endpoint URL for the subgraph
    pub url:      String,
    /// Entity types managed by this subgraph
    pub entities: Vec<String>,
    /// Health status of the subgraph
    pub healthy:  bool,
}

/// Federation graph in various formats.
#[derive(Debug, Serialize)]
pub struct GraphResponse {
    /// Format of the graph (json, dot, or mermaid)
    pub format:  String,
    /// Graph content in the specified format
    pub content: String,
}

/// Graph format query parameter for federation graph endpoint.
#[derive(Debug, Deserialize)]
pub struct GraphFormatQuery {
    /// Output format: json (default), dot, or mermaid
    #[serde(default = "default_format")]
    pub format: String,
}

fn default_format() -> String {
    "json".to_string()
}

/// Get list of federation subgraphs.
///
/// Returns information about all subgraphs in the federated schema,
/// including their URLs, managed entities, and health status.
pub async fn subgraphs_handler<A: DatabaseAdapter>(
    State(_state): State<AppState<A>>,
) -> Result<Json<ApiResponse<SubgraphsResponse>>, ApiError> {
    // In a real implementation, this would:
    // 1. Extract federation metadata from the schema
    // 2. Query each subgraph for health status
    // 3. Return actual subgraph information

    // Placeholder: Return empty list
    let response = SubgraphsResponse { subgraphs: vec![] };

    Ok(Json(ApiResponse {
        status: "success".to_string(),
        data:   response,
    }))
}

/// Get federation dependency graph.
///
/// Exports the federation structure showing:
/// - Subgraph relationships
/// - Entity resolution paths
/// - Dependencies between subgraphs
///
/// Supports multiple output formats:
/// - **json**: Machine-readable federation structure
/// - **dot**: Graphviz format for visualization
/// - **mermaid**: Markdown-compatible graph syntax
pub async fn graph_handler<A: DatabaseAdapter>(
    State(_state): State<AppState<A>>,
    Query(query): Query<GraphFormatQuery>,
) -> Result<Json<ApiResponse<GraphResponse>>, ApiError> {
    // Validate format parameter
    let format = match query.format.as_str() {
        "json" | "dot" | "mermaid" => query.format,
        _ => return Err(ApiError::validation_error("format must be 'json', 'dot', or 'mermaid'")),
    };

    // Generate graph in the requested format
    let content = generate_federation_graph(&format);

    let response = GraphResponse {
        format: format.clone(),
        content,
    };

    Ok(Json(ApiResponse {
        status: "success".to_string(),
        data:   response,
    }))
}

/// Generate federation graph in the specified format.
///
/// In a real implementation, this would:
/// 1. Extract subgraph information from schema
/// 2. Build graph structure from federation metadata
/// 3. Convert to requested format
fn generate_federation_graph(format: &str) -> String {
    match format {
        "json" => generate_json_graph(),
        "dot" => generate_dot_graph(),
        "mermaid" => generate_mermaid_graph(),
        _ => "{}".to_string(),
    }
}

/// Generate JSON representation of federation graph.
fn generate_json_graph() -> String {
    r#"{
  "subgraphs": [],
  "edges": []
}"#
    .to_string()
}

/// Generate Graphviz (DOT) representation of federation graph.
fn generate_dot_graph() -> String {
    r#"digraph federation {
  rankdir=LR;
  node [shape=box, style=rounded];

  // Subgraphs would be added here
  // Example:
  // users [label="users\n[User, Query]"];
  // posts [label="posts\n[Post]"];
  // users -> posts [label="User", style=dashed];
}"#
    .to_string()
}

/// Generate Mermaid diagram representation of federation graph.
fn generate_mermaid_graph() -> String {
    r#"graph LR
    %% Federation subgraphs
    %% Example:
    %% users["users<br/>[User, Query]"]
    %% posts["posts<br/>[Post]"]
    %% users -->|User| posts"#
        .to_string()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_generate_json_graph() {
        let json = generate_json_graph();
        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();

        assert!(parsed["subgraphs"].is_array());
        assert!(parsed["edges"].is_array());
    }

    #[test]
    fn test_generate_dot_graph() {
        let dot = generate_dot_graph();

        assert!(dot.contains("digraph"));
        assert!(dot.contains("rankdir"));
    }

    #[test]
    fn test_generate_mermaid_graph() {
        let mermaid = generate_mermaid_graph();

        assert!(mermaid.contains("graph LR"));
    }

    #[test]
    fn test_default_format() {
        assert_eq!(default_format(), "json");
    }

    #[test]
    fn test_subgraph_info_creation() {
        let info = SubgraphInfo {
            name:     "test".to_string(),
            url:      "http://test.local".to_string(),
            entities: vec!["Entity1".to_string()],
            healthy:  true,
        };

        assert_eq!(info.name, "test");
        assert!(info.healthy);
    }

    #[test]
    fn test_subgraphs_response_creation() {
        let response = SubgraphsResponse { subgraphs: vec![] };

        assert!(response.subgraphs.is_empty());
    }

    #[test]
    fn test_graph_response_creation() {
        let response = GraphResponse {
            format:  "json".to_string(),
            content: "{}".to_string(),
        };

        assert_eq!(response.format, "json");
    }
}