gun/
error.rs

1//! Error types for Gun.rs
2//! 
3//! All errors that can occur in Gun operations are represented by the `GunError` enum.
4//! This module provides comprehensive error handling for the entire library.
5
6use thiserror::Error;
7
8/// Main error type for all Gun operations
9/// 
10/// All operations in Gun return `GunResult<T>` which is `Result<T, GunError>`.
11/// This enum covers all possible error conditions that can occur.
12/// 
13/// # Error Variants
14/// 
15/// - `InvalidData(String)`: Data format is invalid or doesn't match expected structure
16/// - `Storage(#[from] sled::Error)`: Storage operation failed (disk full, corruption, etc.)
17/// - `Serialization(#[from] serde_json::Error)`: JSON serialization/deserialization failed
18/// - `Network(String)`: Network operation failed (connection lost, timeout, etc.)
19/// - `InvalidSoul(String)`: Soul (node ID) format is invalid
20/// - `NodeNotFound`: Requested node doesn't exist in the graph
21/// - `Io(#[from] std::io::Error)`: I/O operation failed (file read/write, etc.)
22/// - `UrlParseError(#[from] url::ParseError)`: URL parsing failed (invalid peer URL)
23/// - `WebRTC(String)`: WebRTC operation failed (connection, signaling, etc.)
24/// - `Crypto(String)`: Cryptographic operation failed (encryption, signing, etc.)
25/// 
26/// # Error Handling
27/// 
28/// All errors implement `std::error::Error` and can be:
29/// - Converted to strings with `to_string()` or `Display` trait
30/// - Used with `?` operator for error propagation
31/// - Matched with pattern matching
32/// 
33/// # Example
34/// 
35/// ```rust,no_run
36/// use gun::{Gun, GunError};
37/// use serde_json::json;
38/// 
39/// # async fn example() -> Result<(), GunError> {
40/// let gun = Gun::new();
41/// 
42/// // Operations return GunResult
43/// let result = gun.get("test").put(json!({"data": 42})).await;
44/// 
45/// match result {
46///     Ok(chain) => println!("Success: {:?}", chain),
47///     Err(GunError::Storage(e)) => eprintln!("Storage error: {}", e),
48///     Err(GunError::Network(msg)) => eprintln!("Network error: {}", msg),
49///     Err(e) => eprintln!("Other error: {}", e),
50/// }
51/// # Ok(())
52/// # }
53/// ```
54#[derive(Error, Debug)]
55pub enum GunError {
56    /// Invalid data format or structure
57    #[error("Invalid data: {0}")]
58    InvalidData(String),
59
60    /// Storage operation failed (from sled database)
61    #[error("Storage error: {0}")]
62    Storage(#[from] sled::Error),
63
64    /// JSON serialization/deserialization failed
65    #[error("Serialization error: {0}")]
66    Serialization(#[from] serde_json::Error),
67
68    /// Network operation failed (connection, timeout, etc.)
69    #[error("Network error: {0}")]
70    Network(String),
71
72    /// Invalid soul (node ID) format
73    #[error("Invalid soul: {0}")]
74    InvalidSoul(String),
75
76    /// Requested node not found in graph
77    #[error("Node not found")]
78    NodeNotFound,
79
80    /// I/O operation failed (file operations, etc.)
81    #[error("IO error: {0}")]
82    Io(#[from] std::io::Error),
83
84    /// URL parsing failed (invalid peer URL format)
85    #[error("URL parse error: {0}")]
86    UrlParseError(#[from] url::ParseError),
87
88    /// WebRTC operation failed (connection, signaling, etc.)
89    #[error("WebRTC error: {0}")]
90    WebRTC(String),
91
92    /// Cryptographic operation failed (encryption, signing, etc.)
93    #[error("Crypto error: {0}")]
94    Crypto(String),
95}
96
97/// Result type alias for Gun operations
98/// 
99/// All Gun operations return `GunResult<T>` which is `Result<T, GunError>`.
100/// This provides consistent error handling across the entire library.
101/// 
102/// # Example
103/// 
104/// ```rust,no_run
105/// use gun::{Gun, GunResult};
106/// use serde_json::json;
107/// 
108/// async fn put_data() -> GunResult<()> {
109///     let gun = Gun::new();
110///     gun.get("test").put(json!({"value": 42})).await?;
111///     Ok(())
112/// }
113/// ```
114pub type GunResult<T> = Result<T, GunError>;
gun/error.rs

gun/
error.rs
