//! WebSocket gateway scaffolding for Athena.
//!
//! This module intentionally starts with protocol definitions and documentation
//! endpoints so the transport contract can stabilize before a dedicated
//! gateway WebSocket server is wired into production.

use actix_web::{HttpResponse, Responder, get};
use serde::{Deserialize, Serialize};
use serde_json::json;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GatewayWsRequest {
    pub action: String,
    pub request_id: Option<String>,
    pub client_name: String,
    pub path: String,
    #[serde(default)]
    pub method: Option<String>,
    #[serde(default)]
    pub headers: serde_json::Value,
    #[serde(default)]
    pub query: serde_json::Value,
    #[serde(default)]
    pub body: serde_json::Value,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GatewayWsResponse {
    pub request_id: Option<String>,
    pub status: String,
    pub message: String,
    #[serde(default)]
    pub data: serde_json::Value,
}

/// Returns the current WebSocket gateway contract and rollout note.
#[get("/wss/info")]
pub async fn gateway_wss_info() -> impl Responder {
    HttpResponse::Ok().json(json!({
        "status": "success",
        "message": "Athena WebSocket gateway scaffold",
        "data": {
            "transport": "wss",
            "path": "/wss/gateway",
            "state": "scaffolded",
            "notes": [
                "The initial implementation documents the message contract and serves a dedicated OpenAPI file.",
                "Requests mirror the HTTP gateway by carrying action, client_name, path, optional method, headers, query, and body.",
                "Responses return request_id, status, message, and data so clients can correlate multiplexed calls."
            ],
            "actions": [
                "gateway.fetch",
                "gateway.insert",
                "gateway.update",
                "gateway.delete",
                "gateway.query"
            ]
        }
    }))
}
