lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

error.rs (7399B)


      1 //! Stable Nostr transport failures.
      2 
      3 use core::fmt;
      4 
      5 /// Error returned by the Nostr transport adapter.
      6 #[derive(Clone, Debug, Eq, PartialEq)]
      7 #[non_exhaustive]
      8 pub enum Error {
      9     /// The owner has permanently closed admission to this transport.
     10     TransportClosed,
     11     /// No relay was configured.
     12     EmptyRelaySet,
     13     /// The configured relay count exceeds the adapter bound.
     14     TooManyRelays { max: usize, actual: usize },
     15     /// A canonical relay URL occurs more than once.
     16     DuplicateRelayUrl,
     17     /// The URL is not a valid canonical Nostr relay target.
     18     InvalidRelayUrl,
     19     /// The URL scheme is not permitted by the selected policy.
     20     RelaySchemeDenied,
     21     /// The URL destination is not permitted by the selected policy.
     22     RelayDestinationDenied,
     23     /// DNS resolution produced no addresses.
     24     EmptyResolution,
     25     /// A resolved address violates the selected policy.
     26     ResolvedAddressDenied,
     27     /// An endpoint policy is incompatible with its host profile kind.
     28     RelayProfilePolicyMismatch,
     29     /// A connection or request timeout is outside its governed bounds.
     30     InvalidTimeout { field: &'static str, value_ms: u64 },
     31     /// The per-operation connection limit is outside its governed bounds.
     32     InvalidConnectionLimit { value: usize },
     33     /// The reconnect delay policy is empty, inverted, or exceeds its bound.
     34     InvalidReconnectBackoff {
     35         initial_delay_ms: u64,
     36         max_delay_ms: u64,
     37     },
     38     /// A transport-neutral target is not a Nostr target.
     39     UnexpectedTransport,
     40     /// A relay cursor contains a noncanonical event position.
     41     InvalidRelayCursor,
     42     /// The generic transport target rejected the relay URL.
     43     Target,
     44     /// The relay challenge is empty, malformed, or outside its time bounds.
     45     InvalidAuthChallenge,
     46     /// A different live challenge already exists for this relay.
     47     AuthChallengeConflict,
     48     /// No matching live challenge exists for this relay.
     49     AuthChallengeMissing,
     50     /// The matching challenge expired before response submission.
     51     AuthChallengeExpired,
     52     /// The host supplied no signed NIP-42 response.
     53     AuthSignerUnavailable,
     54     /// The signed response does not match the pending relay and challenge.
     55     AuthResponseMismatch,
     56     /// The signed response is malformed or cryptographically invalid.
     57     AuthResponseInvalid,
     58     /// The host explicitly rejected the pending challenge.
     59     AuthRejected,
     60     /// Internal authentication state could not be accessed safely.
     61     AuthStateUnavailable,
     62     /// The relay rejected or failed the explicit AUTH message.
     63     AuthTransport,
     64 }
     65 
     66 impl fmt::Display for Error {
     67     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
     68         match self {
     69             Self::TransportClosed => formatter.write_str("transport admission is closed"),
     70             Self::EmptyRelaySet => formatter.write_str("relay set must not be empty"),
     71             Self::TooManyRelays { max, actual } => {
     72                 write!(formatter, "relay count {actual} exceeds maximum {max}")
     73             }
     74             Self::DuplicateRelayUrl => formatter.write_str("duplicate relay URL"),
     75             Self::InvalidRelayUrl => formatter.write_str("invalid relay URL"),
     76             Self::RelaySchemeDenied => formatter.write_str("relay URL scheme is denied by policy"),
     77             Self::RelayDestinationDenied => {
     78                 formatter.write_str("relay URL destination is denied by policy")
     79             }
     80             Self::EmptyResolution => formatter.write_str("relay URL resolved to no addresses"),
     81             Self::ResolvedAddressDenied => {
     82                 formatter.write_str("relay URL resolved to a denied address")
     83             }
     84             Self::RelayProfilePolicyMismatch => {
     85                 formatter.write_str("relay endpoint policy does not match its profile kind")
     86             }
     87             Self::InvalidTimeout { field, value_ms } => {
     88                 write!(formatter, "invalid {field} timeout: {value_ms}ms")
     89             }
     90             Self::InvalidConnectionLimit { value } => {
     91                 write!(formatter, "invalid connection limit: {value}")
     92             }
     93             Self::InvalidReconnectBackoff {
     94                 initial_delay_ms,
     95                 max_delay_ms,
     96             } => write!(
     97                 formatter,
     98                 "invalid reconnect backoff: initial={initial_delay_ms}ms max={max_delay_ms}ms"
     99             ),
    100             Self::UnexpectedTransport => formatter.write_str("expected Nostr transport target"),
    101             Self::InvalidRelayCursor => formatter.write_str("invalid relay cursor"),
    102             Self::Target => formatter.write_str("transport target error"),
    103             Self::InvalidAuthChallenge => formatter.write_str("invalid NIP-42 challenge"),
    104             Self::AuthChallengeConflict => {
    105                 formatter.write_str("a different NIP-42 challenge is already pending")
    106             }
    107             Self::AuthChallengeMissing => {
    108                 formatter.write_str("matching NIP-42 challenge is not pending")
    109             }
    110             Self::AuthChallengeExpired => formatter.write_str("NIP-42 challenge expired"),
    111             Self::AuthSignerUnavailable => {
    112                 formatter.write_str("NIP-42 response signer is unavailable")
    113             }
    114             Self::AuthResponseMismatch => {
    115                 formatter.write_str("NIP-42 response does not match its challenge")
    116             }
    117             Self::AuthResponseInvalid => formatter.write_str("NIP-42 response is invalid"),
    118             Self::AuthRejected => formatter.write_str("NIP-42 challenge was rejected"),
    119             Self::AuthStateUnavailable => {
    120                 formatter.write_str("NIP-42 authentication state is unavailable")
    121             }
    122             Self::AuthTransport => formatter.write_str("NIP-42 relay submission failed"),
    123         }
    124     }
    125 }
    126 
    127 impl std::error::Error for Error {}
    128 
    129 #[cfg(test)]
    130 mod tests {
    131     use super::*;
    132     use std::error::Error as _;
    133 
    134     #[test]
    135     fn every_error_has_a_stable_nonempty_message() {
    136         let errors = [
    137             Error::TransportClosed,
    138             Error::EmptyRelaySet,
    139             Error::TooManyRelays { max: 1, actual: 2 },
    140             Error::DuplicateRelayUrl,
    141             Error::InvalidRelayUrl,
    142             Error::RelaySchemeDenied,
    143             Error::RelayDestinationDenied,
    144             Error::EmptyResolution,
    145             Error::ResolvedAddressDenied,
    146             Error::RelayProfilePolicyMismatch,
    147             Error::InvalidTimeout {
    148                 field: "request",
    149                 value_ms: 0,
    150             },
    151             Error::InvalidConnectionLimit { value: 0 },
    152             Error::InvalidReconnectBackoff {
    153                 initial_delay_ms: 0,
    154                 max_delay_ms: 1,
    155             },
    156             Error::UnexpectedTransport,
    157             Error::InvalidRelayCursor,
    158             Error::Target,
    159             Error::InvalidAuthChallenge,
    160             Error::AuthChallengeConflict,
    161             Error::AuthChallengeMissing,
    162             Error::AuthChallengeExpired,
    163             Error::AuthSignerUnavailable,
    164             Error::AuthResponseMismatch,
    165             Error::AuthResponseInvalid,
    166             Error::AuthRejected,
    167             Error::AuthStateUnavailable,
    168             Error::AuthTransport,
    169         ];
    170         for error in errors {
    171             assert!(!error.to_string().is_empty());
    172             assert!(error.source().is_none());
    173         }
    174     }
    175 }