//! 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 chrono::Utc;
use serde::{Deserialize, Serialize};
use serde_json::json;

use crate::protocol::{ClientWsCommand, ServerWsEvent};

/// Inbound JSON envelope for HTTP-mirrored gateway actions over `/wss/gateway`.
///
/// Carries the same routing fields as the HTTP gateway (`action`, `client_name`, `path`, etc.)
/// documented in [`openapi-wss.yaml`](../../../../openapi-wss.yaml).
#[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,
}

/// Represents the response sent by the WebSocket gateway.
///
/// # Fields
/// - `request_id`: The ID of the request, if provided.
/// - `status`: The status of the response.
/// - `message`: The message of the response.
/// - `data`: The data of the response.
#[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": [
                "Durable chat writes stay on HTTP /chat routes; websocket is transport plus ephemeral control only.",
                "Requests mirror the HTTP gateway by carrying action, client_name, path, optional method, headers, query, and body.",
                "Realtime chat commands include subscribe, resume, typing, presence heartbeat, and read-cursor convenience signals."
            ],
            "actions": [
                "gateway.fetch",
                "gateway.insert",
                "gateway.update",
                "gateway.delete",
                "gateway.query",
                "chat.subscribe",
                "chat.resume",
                "chat.typing.start",
                "chat.typing.stop",
                "chat.presence.heartbeat",
                "chat.read.up_to"
            ],
            "server_time": Utc::now(),
            "contracts": {
                "client_command_type": std::any::type_name::<ClientWsCommand>(),
                "server_event_type": std::any::type_name::<ServerWsEvent>()
            }
        }
    }))
}
