firefox-webdriver 0.2.1

//! Type-safe identifier wrappers for Firefox WebDriver.
//!
//! This module provides newtype wrappers around primitive types to prevent
//! accidentally mixing incompatible IDs at compile time.
//!
//! # ID System
//!
//! From ARCHITECTURE.md Section 1.4:
//!
//! | ID | Type | Source | Purpose |
//! |----|------|--------|---------|
//! | [`SessionId`] | `NonZeroU32` | Rust counter | Window identification |
//! | [`TabId`] | `NonZeroU32` | Firefox | Tab identification |
//! | [`FrameId`] | `u64` | Firefox | Frame identification (0 = main) |
//! | [`RequestId`] | UUID v4 | Rust | WebSocket correlation |
//! | [`ElementId`] | UUID v4 | Extension | DOM element reference |
//! | [`ScriptId`] | UUID v4 | Extension | Preload script reference |
//! | [`SubscriptionId`] | UUID v4 | Extension | Element observation |
//! | [`InterceptId`] | UUID v4 | Extension | Network interception |
//!
//! # Example
//!
//! ```ignore
//! use firefox_webdriver::{TabId, FrameId, ElementId};
//!
//! // Type safety prevents mixing IDs
//! let tab_id = TabId::new(1).expect("valid tab id");
//! let frame_id = FrameId::main();
//! let element_id = ElementId::new("uuid-string");
//!
//! // This would not compile:
//! // let wrong: TabId = frame_id; // Error: mismatched types
//! ```

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

use std::fmt;
use std::num::NonZeroU32;
use std::sync::Arc;
use std::sync::atomic::{AtomicU32, Ordering};

use serde::de::Error as DeError;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use uuid::Uuid;

// ============================================================================
// Constants
// ============================================================================

/// Starting value for session counter.
const SESSION_COUNTER_START: u32 = 1;

// ============================================================================
// Global State
// ============================================================================

/// Global atomic counter for generating unique session IDs.
static SESSION_COUNTER: AtomicU32 = AtomicU32::new(SESSION_COUNTER_START);

// ============================================================================
// SessionId
// ============================================================================

/// Identifier for a browser session (Firefox window/process).
///
/// Generated by an atomic counter starting at 1. Each call to [`SessionId::next()`]
/// returns a unique, incrementing ID. Thread-safe and lock-free.
///
/// # Example
///
/// ```ignore
/// let session1 = SessionId::next();
/// let session2 = SessionId::next();
/// assert!(session1.as_u32() < session2.as_u32());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct SessionId(NonZeroU32);

impl SessionId {
    /// Generates the next unique session ID.
    ///
    /// Uses an atomic counter that starts at 1 and increments.
    /// Thread-safe and lock-free. Wraps around on overflow, skipping 0.
    #[inline]
    #[must_use]
    pub fn next() -> Self {
        loop {
            let id = SESSION_COUNTER.fetch_add(1, Ordering::Relaxed);
            if let Some(non_zero) = NonZeroU32::new(id) {
                return Self(non_zero);
            }
            // id was 0, try again
        }
    }

    /// Creates a SessionId from a u32 value.
    ///
    /// Used for parsing session IDs from READY messages.
    ///
    /// # Returns
    ///
    /// `Some(SessionId)` if `id > 0`, `None` otherwise.
    #[inline]
    #[must_use]
    pub fn from_u32(id: u32) -> Option<Self> {
        NonZeroU32::new(id).map(Self)
    }

    /// Returns the underlying `u32` value.
    #[inline]
    #[must_use]
    pub const fn as_u32(&self) -> u32 {
        self.0.get()
    }
}

impl fmt::Display for SessionId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl Serialize for SessionId {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_u32(self.0.get())
    }
}

impl<'de> Deserialize<'de> for SessionId {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let id = u32::deserialize(deserializer)?;
        NonZeroU32::new(id)
            .map(Self)
            .ok_or_else(|| DeError::custom("session_id cannot be 0"))
    }
}

// ============================================================================
// TabId
// ============================================================================

/// Identifier for a browser tab.
///
/// Firefox assigns tab IDs starting from 1. A value of 0 is invalid.
///
/// # Example
///
/// ```ignore
/// let tab_id = TabId::new(1).expect("valid tab id");
/// assert_eq!(tab_id.as_u32(), 1);
///
/// // Zero is invalid
/// assert!(TabId::new(0).is_none());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct TabId(NonZeroU32);

impl TabId {
    /// Creates a new tab ID with validation.
    ///
    /// # Arguments
    ///
    /// * `id` - Tab ID value (must be > 0)
    ///
    /// # Returns
    ///
    /// `Some(TabId)` if `id > 0`, `None` otherwise.
    #[inline]
    #[must_use]
    pub fn new(id: u32) -> Option<Self> {
        NonZeroU32::new(id).map(Self)
    }

    /// Returns the underlying `u32` value.
    #[inline]
    #[must_use]
    pub const fn as_u32(&self) -> u32 {
        self.0.get()
    }
}

impl fmt::Display for TabId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl Serialize for TabId {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_u32(self.0.get())
    }
}

impl<'de> Deserialize<'de> for TabId {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let id = u32::deserialize(deserializer)?;
        NonZeroU32::new(id)
            .map(Self)
            .ok_or_else(|| DeError::custom("tab_id cannot be 0"))
    }
}

// ============================================================================
// FrameId
// ============================================================================

/// Identifier for a frame context.
///
/// Unlike [`TabId`] and [`SessionId`], `FrameId(0)` is valid and represents
/// the main (top-level) frame. Firefox frame IDs can be large 64-bit values
/// for iframes.
///
/// # Example
///
/// ```ignore
/// let main_frame = FrameId::main();
/// assert!(main_frame.is_main());
/// assert_eq!(main_frame.as_u64(), 0);
///
/// let iframe = FrameId::new(17179869185);
/// assert!(!iframe.is_main());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct FrameId(u64);

impl FrameId {
    /// Creates a new frame identifier.
    #[inline]
    #[must_use]
    pub const fn new(id: u64) -> Self {
        Self(id)
    }

    /// Returns the main frame identifier (0).
    #[inline]
    #[must_use]
    pub const fn main() -> Self {
        Self(0)
    }

    /// Returns `true` if this is the main frame.
    #[inline]
    #[must_use]
    pub const fn is_main(&self) -> bool {
        self.0 == 0
    }

    /// Returns the underlying `u64` value.
    #[inline]
    #[must_use]
    pub const fn as_u64(&self) -> u64 {
        self.0
    }
}

impl Default for FrameId {
    #[inline]
    fn default() -> Self {
        Self::main()
    }
}

impl fmt::Display for FrameId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<u64> for FrameId {
    #[inline]
    fn from(id: u64) -> Self {
        Self(id)
    }
}

// ============================================================================
// RequestId
// ============================================================================

/// Unique identifier for a WebSocket request.
///
/// Used to correlate requests with their responses in the async protocol.
/// Generated as UUID v4 by Rust side.
///
/// # Special Values
///
/// - [`RequestId::ready()`] returns the nil UUID, used for the READY handshake.
///
/// # Example
///
/// ```ignore
/// let request_id = RequestId::generate();
/// assert!(!request_id.is_ready());
///
/// let ready_id = RequestId::ready();
/// assert!(ready_id.is_ready());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct RequestId(Uuid);

impl RequestId {
    /// Generates a new random request ID.
    #[inline]
    #[must_use]
    pub fn generate() -> Self {
        Self(Uuid::new_v4())
    }

    /// Returns the special READY request ID (nil UUID).
    ///
    /// This ID is used for the initial handshake message from the extension.
    #[inline]
    #[must_use]
    pub const fn ready() -> Self {
        Self(Uuid::nil())
    }

    /// Returns `true` if this is the READY request ID.
    #[inline]
    #[must_use]
    pub fn is_ready(&self) -> bool {
        self.0.is_nil()
    }

    /// Returns a reference to the underlying UUID.
    #[inline]
    #[must_use]
    pub const fn as_uuid(&self) -> &Uuid {
        &self.0
    }
}

impl Default for RequestId {
    #[inline]
    fn default() -> Self {
        Self::generate()
    }
}

impl fmt::Display for RequestId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.0, f)
    }
}

impl From<Uuid> for RequestId {
    #[inline]
    fn from(uuid: Uuid) -> Self {
        Self(uuid)
    }
}

// ============================================================================
// ElementId
// ============================================================================

/// Identifier for a DOM element.
///
/// Generated by the extension as UUID v4. References an element stored
/// in content script's internal `Map<UUID, Element>`.
///
/// # Example
///
/// ```ignore
/// let element_id = ElementId::new("550e8400-e29b-41d4-a716-446655440000");
/// assert_eq!(element_id.as_str(), "550e8400-e29b-41d4-a716-446655440000");
/// ```
#[derive(Debug, Clone, Hash, PartialEq, Eq)]
pub struct ElementId(Arc<str>);

impl ElementId {
    /// Creates a new element identifier.
    #[inline]
    #[must_use]
    pub fn new(id: impl Into<Arc<str>>) -> Self {
        Self(id.into())
    }

    /// Returns the ID as a string slice.
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for ElementId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.0, f)
    }
}

impl AsRef<str> for ElementId {
    #[inline]
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl Serialize for ElementId {
    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(&self.0)
    }
}

impl<'de> Deserialize<'de> for ElementId {
    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        Ok(Self(Arc::from(s)))
    }
}

// ============================================================================
// ScriptId
// ============================================================================

/// Identifier for a preload script.
///
/// Generated by the extension as UUID v4. Used to track registered
/// content scripts that run before page load.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ScriptId(String);

impl ScriptId {
    /// Creates a new script identifier.
    #[inline]
    #[must_use]
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    /// Returns the ID as a string slice.
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for ScriptId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.0, f)
    }
}

impl AsRef<str> for ScriptId {
    #[inline]
    fn as_ref(&self) -> &str {
        &self.0
    }
}

// ============================================================================
// SubscriptionId
// ============================================================================

/// Identifier for an element observation subscription.
///
/// Generated by the extension as UUID v4. Used to track MutationObserver
/// subscriptions for `element.added` / `element.removed` events.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct SubscriptionId(String);

impl SubscriptionId {
    /// Creates a new subscription identifier.
    #[inline]
    #[must_use]
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    /// Returns the ID as a string slice.
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for SubscriptionId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.0, f)
    }
}

impl AsRef<str> for SubscriptionId {
    #[inline]
    fn as_ref(&self) -> &str {
        &self.0
    }
}

// ============================================================================
// InterceptId
// ============================================================================

/// Identifier for a network intercept.
///
/// Generated by the extension as UUID v4. Used to track network
/// interception configurations for request/response interception.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct InterceptId(String);

impl InterceptId {
    /// Creates a new intercept identifier.
    #[inline]
    #[must_use]
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    /// Returns the ID as a string slice.
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for InterceptId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.0, f)
    }
}

impl AsRef<str> for InterceptId {
    #[inline]
    fn as_ref(&self) -> &str {
        &self.0
    }
}

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

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

    #[test]
    fn test_session_id_increments() {
        let id1 = SessionId::next();
        let id2 = SessionId::next();
        assert!(id1.as_u32() < id2.as_u32());
    }

    #[test]
    fn test_session_id_display() {
        let id = SessionId::next();
        let display = id.to_string();
        assert!(!display.is_empty());
    }

    #[test]
    fn test_session_id_from_u32() {
        assert!(SessionId::from_u32(0).is_none());
        assert!(SessionId::from_u32(1).is_some());
        assert_eq!(SessionId::from_u32(42).unwrap().as_u32(), 42);
    }

    #[test]
    fn test_tab_id_rejects_zero() {
        assert!(TabId::new(0).is_none());
        assert!(TabId::new(1).is_some());
    }

    #[test]
    fn test_tab_id_value() {
        let tab = TabId::new(42).expect("valid tab id");
        assert_eq!(tab.as_u32(), 42);
    }

    #[test]
    fn test_frame_id_main() {
        let main = FrameId::main();
        assert!(main.is_main());
        assert_eq!(main.as_u64(), 0);
    }

    #[test]
    fn test_frame_id_iframe() {
        let iframe = FrameId::new(17179869185);
        assert!(!iframe.is_main());
        assert_eq!(iframe.as_u64(), 17179869185);
    }

    #[test]
    fn test_frame_id_default() {
        let default = FrameId::default();
        assert!(default.is_main());
    }

    #[test]
    fn test_frame_id_from_u64() {
        let frame: FrameId = 123u64.into();
        assert_eq!(frame.as_u64(), 123);
    }

    #[test]
    fn test_request_id_ready() {
        let ready = RequestId::ready();
        assert!(ready.is_ready());
        assert!(ready.as_uuid().is_nil());
    }

    #[test]
    fn test_request_id_generated() {
        let id = RequestId::generate();
        assert!(!id.is_ready());
        assert!(!id.as_uuid().is_nil());
    }

    #[test]
    fn test_request_id_uniqueness() {
        let id1 = RequestId::generate();
        let id2 = RequestId::generate();
        assert_ne!(id1, id2);
    }

    #[test]
    fn test_element_id() {
        let id = ElementId::new("test-uuid");
        assert_eq!(id.as_str(), "test-uuid");
        assert_eq!(id.as_ref(), "test-uuid");
        assert_eq!(id.to_string(), "test-uuid");
    }

    #[test]
    fn test_script_id() {
        let id = ScriptId::new("script-123");
        assert_eq!(id.as_str(), "script-123");
    }

    #[test]
    fn test_subscription_id() {
        let id = SubscriptionId::new("sub-456");
        assert_eq!(id.as_str(), "sub-456");
        assert_eq!(id.as_ref(), "sub-456");
    }

    #[test]
    fn test_intercept_id() {
        let id = InterceptId::new("intercept-789");
        assert_eq!(id.as_str(), "intercept-789");
        assert_eq!(id.as_ref(), "intercept-789");
    }

    #[test]
    fn test_serde_session_id() {
        let id = SessionId::next();
        let json = serde_json::to_string(&id).expect("serialize");
        let parsed: SessionId = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(id, parsed);
    }

    #[test]
    fn test_serde_tab_id() {
        let id = TabId::new(42).expect("valid");
        let json = serde_json::to_string(&id).expect("serialize");
        let parsed: TabId = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(id, parsed);
    }

    #[test]
    fn test_serde_frame_id() {
        let id = FrameId::new(12345);
        let json = serde_json::to_string(&id).expect("serialize");
        let parsed: FrameId = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(id, parsed);
    }

    #[test]
    fn test_serde_element_id() {
        let id = ElementId::new("elem-uuid");
        let json = serde_json::to_string(&id).expect("serialize");
        let parsed: ElementId = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(id, parsed);
    }
}