dravr-browser 0.1.0

Headless-Chrome automation primitives: launch, persistent profiles, stealth, CDP input, and streaming network capture
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

// ABOUTME: Error type for headless-browser automation: launch, navigation, interaction, auth, config
// ABOUTME: Consumers convert BrowserError into their own domain error (RunnerError, ScraperError, etc.)
//
// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (c) 2026 dravr.ai

/// Result alias for browser operations.
pub type BrowserResult<T> = Result<T, BrowserError>;

/// Errors arising from headless-browser automation.
#[derive(Debug, thiserror::Error)]
pub enum BrowserError {
    /// Browser launch, connection, or low-level CDP failure.
    #[error("browser error: {reason}")]
    Browser {
        /// Detailed failure reason.
        reason: String,
    },

    /// Page navigation failure.
    #[error("navigation error: {reason}")]
    Navigation {
        /// Detailed failure reason.
        reason: String,
    },

    /// DOM interaction failure (element not found, click/fill failed).
    #[error("interaction error: {reason}")]
    Interaction {
        /// Detailed failure reason.
        reason: String,
    },

    /// Authentication / session failure (no cookies captured, expired session).
    #[error("auth error: {reason}")]
    Auth {
        /// Detailed failure reason.
        reason: String,
    },

    /// Configuration error (invalid launch config, missing values).
    #[error("config error: {reason}")]
    Config {
        /// Detailed failure reason.
        reason: String,
    },

    /// Operation exceeded its deadline.
    #[error("timeout: {reason}")]
    Timeout {
        /// Detailed failure reason.
        reason: String,
    },
}

impl BrowserError {
    /// Construct a [`BrowserError::Browser`].
    pub fn browser(reason: impl Into<String>) -> Self {
        Self::Browser {
            reason: reason.into(),
        }
    }

    /// Construct a [`BrowserError::Navigation`].
    pub fn navigation(reason: impl Into<String>) -> Self {
        Self::Navigation {
            reason: reason.into(),
        }
    }

    /// Construct a [`BrowserError::Interaction`].
    pub fn interaction(reason: impl Into<String>) -> Self {
        Self::Interaction {
            reason: reason.into(),
        }
    }

    /// Construct a [`BrowserError::Auth`].
    pub fn auth(reason: impl Into<String>) -> Self {
        Self::Auth {
            reason: reason.into(),
        }
    }

    /// Construct a [`BrowserError::Config`].
    pub fn config(reason: impl Into<String>) -> Self {
        Self::Config {
            reason: reason.into(),
        }
    }

    /// Construct a [`BrowserError::Timeout`].
    pub fn timeout(reason: impl Into<String>) -> Self {
        Self::Timeout {
            reason: reason.into(),
        }
    }

    /// Whether this error is transient and may succeed on retry.
    #[must_use]
    pub const fn is_transient(&self) -> bool {
        matches!(
            self,
            Self::Browser { .. } | Self::Navigation { .. } | Self::Timeout { .. }
        )
    }
}

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

    #[test]
    fn transient_classification() {
        assert!(BrowserError::browser("x").is_transient());
        assert!(BrowserError::timeout("x").is_transient());
        assert!(!BrowserError::auth("x").is_transient());
        assert!(!BrowserError::config("x").is_transient());
    }

    #[test]
    fn display_includes_reason() {
        assert_eq!(
            BrowserError::interaction("no element").to_string(),
            "interaction error: no element"
        );
    }
}