firefox-webdriver 0.2.1

//! Network interception types.
//!
//! Types for request/response interception callbacks.
//!
//! # Request Interception
//!
//! ```ignore
//! use firefox_webdriver::RequestAction;
//!
//! let intercept_id = tab.intercept_request(|req| {
//!     if req.url.contains("ads") {
//!         RequestAction::block()
//!     } else {
//!         RequestAction::allow()
//!     }
//! }).await?;
//! ```
//!
//! # Response Interception
//!
//! ```ignore
//! use firefox_webdriver::BodyAction;
//!
//! let intercept_id = tab.intercept_response_body(|res| {
//!     if res.url.contains("config.json") {
//!         BodyAction::modify_body(r#"{"modified": true}"#)
//!     } else {
//!         BodyAction::allow()
//!     }
//! }).await?;
//! ```

// ============================================================================
// Imports
// ============================================================================

use std::collections::HashMap;

// ============================================================================
// InterceptedRequest
// ============================================================================

/// Data about an intercepted network request.
#[derive(Debug, Clone)]
pub struct InterceptedRequest {
    /// Unique request ID.
    pub request_id: String,

    /// Request URL.
    pub url: String,

    /// HTTP method (GET, POST, etc.).
    pub method: String,

    /// Request headers.
    pub headers: HashMap<String, String>,

    /// Resource type (document, script, xhr, etc.).
    pub resource_type: String,

    /// Tab ID where request originated.
    pub tab_id: u32,

    /// Frame ID where request originated.
    pub frame_id: u64,

    /// Request body (if available).
    pub body: Option<RequestBody>,
}

// ============================================================================
// RequestBody
// ============================================================================

/// Request body data.
#[derive(Debug, Clone)]
pub enum RequestBody {
    /// Form data (application/x-www-form-urlencoded or multipart/form-data).
    FormData(HashMap<String, Vec<String>>),

    /// Raw bytes (base64 encoded).
    Raw(Vec<u8>),

    /// Error reading body.
    Error(String),
}

// ============================================================================
// RequestAction
// ============================================================================

/// Action to take for an intercepted request.
#[derive(Debug, Clone)]
pub enum RequestAction {
    /// Allow the request to proceed.
    Allow,

    /// Block/cancel the request.
    Block,

    /// Redirect to a different URL.
    Redirect(String),
}

// ============================================================================
// RequestAction - Constructors
// ============================================================================

impl RequestAction {
    /// Creates an Allow action.
    #[inline]
    #[must_use]
    pub fn allow() -> Self {
        Self::Allow
    }

    /// Creates a Block action.
    #[inline]
    #[must_use]
    pub fn block() -> Self {
        Self::Block
    }

    /// Creates a Redirect action.
    #[inline]
    #[must_use]
    pub fn redirect(url: impl Into<String>) -> Self {
        Self::Redirect(url.into())
    }
}

// ============================================================================
// InterceptedRequestBody
// ============================================================================

/// Data about an intercepted request body (read-only, cannot be modified).
///
/// Browser limitation: request body cannot be modified, only inspected.
#[derive(Debug, Clone)]
pub struct InterceptedRequestBody {
    /// Unique request ID.
    pub request_id: String,

    /// Request URL.
    pub url: String,

    /// HTTP method.
    pub method: String,

    /// Resource type (document, script, xhr, etc.).
    pub resource_type: String,

    /// Tab ID.
    pub tab_id: u32,

    /// Frame ID.
    pub frame_id: u64,

    /// Request body (if available).
    pub body: Option<RequestBody>,
}

// ============================================================================
// InterceptedRequestHeaders
// ============================================================================

/// Data about intercepted request headers.
#[derive(Debug, Clone)]
pub struct InterceptedRequestHeaders {
    /// Unique request ID.
    pub request_id: String,

    /// Request URL.
    pub url: String,

    /// HTTP method.
    pub method: String,

    /// Request headers.
    pub headers: HashMap<String, String>,

    /// Tab ID.
    pub tab_id: u32,

    /// Frame ID.
    pub frame_id: u64,
}

// ============================================================================
// HeadersAction
// ============================================================================

/// Action to take for intercepted headers.
#[derive(Debug, Clone)]
pub enum HeadersAction {
    /// Allow headers to proceed unchanged.
    Allow,

    /// Modify headers with optional status code override.
    Modify {
        /// Headers to set/replace.
        headers: HashMap<String, String>,
        /// Optional HTTP status code override.
        status_code: Option<u16>,
    },

    /// Block/cancel the request.
    Block,
}

// ============================================================================
// HeadersAction - Constructors
// ============================================================================

impl HeadersAction {
    /// Creates an Allow action.
    #[inline]
    #[must_use]
    pub fn allow() -> Self {
        Self::Allow
    }

    /// Creates a Block action.
    #[inline]
    #[must_use]
    pub fn block() -> Self {
        Self::Block
    }

    /// Creates a Modify action with headers only (no status code change).
    #[inline]
    #[must_use]
    pub fn modify_headers(headers: HashMap<String, String>) -> Self {
        Self::Modify {
            headers,
            status_code: None,
        }
    }

    /// Creates a Modify action with headers and status code override.
    #[inline]
    #[must_use]
    pub fn modify_headers_with_status(
        headers: HashMap<String, String>,
        status_code: u16,
    ) -> Self {
        Self::Modify {
            headers,
            status_code: Some(status_code),
        }
    }
}

// ============================================================================
// InterceptedResponse
// ============================================================================

/// Data about an intercepted network response.
#[derive(Debug, Clone)]
pub struct InterceptedResponse {
    /// Unique request ID.
    pub request_id: String,

    /// Request URL.
    pub url: String,

    /// HTTP status code.
    pub status: u16,

    /// HTTP status text.
    pub status_text: String,

    /// Response headers.
    pub headers: HashMap<String, String>,

    /// Tab ID where request originated.
    pub tab_id: u32,

    /// Frame ID where request originated.
    pub frame_id: u64,
}

// ============================================================================
// ResponseAction
// ============================================================================

/// Action to take for intercepted response headers.
#[derive(Debug, Clone)]
pub enum ResponseAction {
    /// Allow the response to proceed unchanged.
    Allow,

    /// Block/cancel the response.
    Block,

    /// Modify response body content.
    Modify {
        /// Replacement body content.
        body: String,
    },

    /// Fulfill the response with fully synthetic data (complete response mocking).
    Fulfill {
        /// HTTP status code.
        status: u16,
        /// Response headers.
        headers: HashMap<String, String>,
        /// Response body.
        body: String,
    },
}

// ============================================================================
// ResponseAction - Constructors
// ============================================================================

impl ResponseAction {
    /// Creates an Allow action.
    #[inline]
    #[must_use]
    pub fn allow() -> Self {
        Self::Allow
    }

    /// Creates a Block action.
    #[inline]
    #[must_use]
    pub fn block() -> Self {
        Self::Block
    }

    /// Creates a Modify action that replaces the response body.
    #[inline]
    #[must_use]
    pub fn modify(body: impl Into<String>) -> Self {
        Self::Modify { body: body.into() }
    }

    /// Creates a Fulfill action for complete response mocking.
    #[inline]
    #[must_use]
    pub fn fulfill(
        status: u16,
        headers: HashMap<String, String>,
        body: impl Into<String>,
    ) -> Self {
        Self::Fulfill {
            status,
            headers,
            body: body.into(),
        }
    }
}

// ============================================================================
// InterceptedResponseBody
// ============================================================================

/// Data about an intercepted response body.
#[derive(Debug, Clone)]
pub struct InterceptedResponseBody {
    /// Unique request ID.
    pub request_id: String,

    /// Request URL.
    pub url: String,

    /// HTTP status code.
    pub status: u16,

    /// Content-Type of the response.
    pub content_type: String,

    /// Response body data (text or binary).
    pub body: ResponseBodyData,

    /// Tab ID.
    pub tab_id: u32,

    /// Frame ID.
    pub frame_id: u64,

    /// Content length.
    pub content_length: usize,
}

// ============================================================================
// ResponseBodyData
// ============================================================================

/// Response body content, supporting both text and binary data.
#[derive(Debug, Clone)]
pub enum ResponseBodyData {
    /// Text body content (UTF-8 string).
    Text(String),

    /// Binary body content (base64-decoded from extension).
    Binary(Vec<u8>),
}

impl ResponseBodyData {
    /// Returns the body as a string reference if it is text.
    #[inline]
    #[must_use]
    pub fn as_text(&self) -> Option<&str> {
        match self {
            Self::Text(s) => Some(s),
            Self::Binary(_) => None,
        }
    }

    /// Returns the body as a byte slice if it is binary.
    #[inline]
    #[must_use]
    pub fn as_bytes(&self) -> Option<&[u8]> {
        match self {
            Self::Text(_) => None,
            Self::Binary(b) => Some(b),
        }
    }

    /// Returns true if the body is text.
    #[inline]
    #[must_use]
    pub fn is_text(&self) -> bool {
        matches!(self, Self::Text(_))
    }

    /// Returns true if the body is binary.
    #[inline]
    #[must_use]
    pub fn is_binary(&self) -> bool {
        matches!(self, Self::Binary(_))
    }
}

// ============================================================================
// BodyAction
// ============================================================================

/// Action to take for intercepted response body.
#[derive(Debug, Clone)]
pub enum BodyAction {
    /// Allow body to proceed unchanged.
    Allow,

    /// Modify body content.
    ModifyBody(String),
}

// ============================================================================
// BodyAction - Constructors
// ============================================================================

impl BodyAction {
    /// Creates an Allow action.
    #[inline]
    #[must_use]
    pub fn allow() -> Self {
        Self::Allow
    }

    /// Creates a ModifyBody action.
    #[inline]
    #[must_use]
    pub fn modify_body(body: impl Into<String>) -> Self {
        Self::ModifyBody(body.into())
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::{BodyAction, HeadersAction, RequestAction, ResponseAction, ResponseBodyData};

    use std::collections::HashMap;

    #[test]
    fn test_request_action_allow() {
        let action = RequestAction::allow();
        assert!(matches!(action, RequestAction::Allow));
    }

    #[test]
    fn test_request_action_block() {
        let action = RequestAction::block();
        assert!(matches!(action, RequestAction::Block));
    }

    #[test]
    fn test_request_action_redirect() {
        let action = RequestAction::redirect("https://example.com");
        if let RequestAction::Redirect(url) = action {
            assert_eq!(url, "https://example.com");
        } else {
            panic!("Expected Redirect action");
        }
    }

    #[test]
    fn test_headers_action_allow() {
        let action = HeadersAction::allow();
        assert!(matches!(action, HeadersAction::Allow));
    }

    #[test]
    fn test_headers_action_block() {
        let action = HeadersAction::block();
        assert!(matches!(action, HeadersAction::Block));
    }

    #[test]
    fn test_headers_action_modify() {
        let mut headers = HashMap::new();
        headers.insert("X-Custom".to_string(), "value".to_string());

        let action = HeadersAction::modify_headers(headers);
        if let HeadersAction::Modify {
            headers: h,
            status_code,
        } = action
        {
            assert_eq!(h.get("X-Custom"), Some(&"value".to_string()));
            assert!(status_code.is_none());
        } else {
            panic!("Expected Modify action");
        }
    }

    #[test]
    fn test_headers_action_modify_with_status() {
        let mut headers = HashMap::new();
        headers.insert("X-Custom".to_string(), "value".to_string());

        let action = HeadersAction::modify_headers_with_status(headers, 404);
        if let HeadersAction::Modify {
            headers: h,
            status_code,
        } = action
        {
            assert_eq!(h.get("X-Custom"), Some(&"value".to_string()));
            assert_eq!(status_code, Some(404));
        } else {
            panic!("Expected Modify action with status");
        }
    }

    #[test]
    fn test_response_action_allow() {
        let action = ResponseAction::allow();
        assert!(matches!(action, ResponseAction::Allow));
    }

    #[test]
    fn test_response_action_block() {
        let action = ResponseAction::block();
        assert!(matches!(action, ResponseAction::Block));
    }

    #[test]
    fn test_response_action_modify() {
        let action = ResponseAction::modify("new body");
        if let ResponseAction::Modify { body } = action {
            assert_eq!(body, "new body");
        } else {
            panic!("Expected Modify action");
        }
    }

    #[test]
    fn test_response_action_fulfill() {
        let mut headers = HashMap::new();
        headers.insert("Content-Type".to_string(), "application/json".to_string());

        let action = ResponseAction::fulfill(200, headers, r#"{"ok": true}"#);
        if let ResponseAction::Fulfill {
            status,
            headers: h,
            body,
        } = action
        {
            assert_eq!(status, 200);
            assert_eq!(
                h.get("Content-Type"),
                Some(&"application/json".to_string())
            );
            assert_eq!(body, r#"{"ok": true}"#);
        } else {
            panic!("Expected Fulfill action");
        }
    }

    #[test]
    fn test_body_action_allow() {
        let action = BodyAction::allow();
        assert!(matches!(action, BodyAction::Allow));
    }

    #[test]
    fn test_body_action_modify() {
        let action = BodyAction::modify_body("new body");
        if let BodyAction::ModifyBody(body) = action {
            assert_eq!(body, "new body");
        } else {
            panic!("Expected ModifyBody action");
        }
    }

    #[test]
    fn test_response_body_data_text() {
        let data = ResponseBodyData::Text("hello".to_string());
        assert!(data.is_text());
        assert!(!data.is_binary());
        assert_eq!(data.as_text(), Some("hello"));
        assert!(data.as_bytes().is_none());
    }

    #[test]
    fn test_response_body_data_binary() {
        let data = ResponseBodyData::Binary(vec![0x89, 0x50, 0x4E, 0x47]);
        assert!(!data.is_text());
        assert!(data.is_binary());
        assert!(data.as_text().is_none());
        assert_eq!(data.as_bytes(), Some(&[0x89, 0x50, 0x4E, 0x47][..]));
    }
}