fetchkit 0.3.0

AI-friendly web content fetching and HTML-to-Markdown conversion library
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
129
130
131
132
133
134

//! Error types for FetchKit

use thiserror::Error;

/// Errors that can occur during fetch operations
///
/// # Examples
///
/// ```
/// use fetchkit::FetchError;
///
/// let err = FetchError::MissingUrl;
/// assert_eq!(err.to_string(), "Missing required parameter: url");
/// ```
#[derive(Debug, Error)]
pub enum FetchError {
    /// URL is missing
    #[error("Missing required parameter: url")]
    MissingUrl,

    /// URL has invalid scheme
    #[error("Invalid URL: must start with http:// or https://")]
    InvalidUrlScheme,

    /// Invalid HTTP method
    #[error("Invalid method: must be GET or HEAD")]
    InvalidMethod,

    /// URL is blocked by policy (prefix list or DNS policy)
    #[error("Blocked URL: not allowed by policy")]
    BlockedUrl,

    /// Failed to build HTTP client
    #[error("Failed to create HTTP client")]
    ClientBuildError(#[source] reqwest::Error),

    /// Request timed out waiting for first byte
    #[error("Request timed out: server did not respond within 1 second")]
    FirstByteTimeout,

    /// Failed to connect to server
    #[error("Failed to connect to server")]
    ConnectError(#[source] reqwest::Error),

    /// Other request error
    #[error("Request failed: {0}")]
    RequestError(String),

    /// Fetcher-specific error
    #[error("Fetcher error: {0}")]
    FetcherError(String),

    /// File save failed
    #[error("Failed to save file: {0}")]
    SaveError(String),

    /// No FileSaver provided but save_to_file was requested
    #[error("File saving not available")]
    SaverNotAvailable,
}

impl FetchError {
    /// Create an error from a reqwest error
    ///
    // THREAT[TM-LEAK-001]: Sanitize reqwest errors to avoid leaking internal hostnames/IPs
    pub fn from_reqwest(err: reqwest::Error) -> Self {
        if err.is_timeout() {
            FetchError::FirstByteTimeout
        } else if err.is_connect() {
            FetchError::ConnectError(err)
        } else if err.is_redirect() {
            FetchError::RequestError("redirect error".to_string())
        } else if err.is_body() {
            FetchError::RequestError("error reading response body".to_string())
        } else if err.is_decode() {
            FetchError::RequestError("error decoding response".to_string())
        } else {
            FetchError::RequestError("request failed".to_string())
        }
    }
}

/// Errors returned by the toolkit-library contract surface.
#[derive(Debug, Error)]
pub enum ToolError {
    /// Safe to surface to an LLM or end user.
    #[error("{0}")]
    UserFacing(String),
    /// Internal/operator-facing failure details.
    #[error("{0}")]
    Internal(String),
}

impl ToolError {
    /// Whether this error is safe to show to the LLM.
    pub fn is_user_facing(&self) -> bool {
        matches!(self, Self::UserFacing(_))
    }
}

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

    #[test]
    fn test_error_messages() {
        assert_eq!(
            FetchError::MissingUrl.to_string(),
            "Missing required parameter: url"
        );
        assert_eq!(
            FetchError::InvalidUrlScheme.to_string(),
            "Invalid URL: must start with http:// or https://"
        );
        assert_eq!(
            FetchError::InvalidMethod.to_string(),
            "Invalid method: must be GET or HEAD"
        );
        assert_eq!(
            FetchError::BlockedUrl.to_string(),
            "Blocked URL: not allowed by policy"
        );
        assert_eq!(
            FetchError::FirstByteTimeout.to_string(),
            "Request timed out: server did not respond within 1 second"
        );
    }

    #[test]
    fn test_tool_error_classification() {
        assert!(ToolError::UserFacing("url is required".to_string()).is_user_facing());
        assert!(!ToolError::Internal("serde failure".to_string()).is_user_facing());
    }
}