irosh 0.2.0

SSH sessions over Iroh peer-to-peer transport
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

use iroh::EndpointAddr;
use iroh_tickets::endpoint::EndpointTicket;
use serde::{Deserialize, Serialize};
use std::fmt;
use std::str::FromStr;

/// Errors that can occur when parsing or manipulating connection tickets.
#[derive(Debug, thiserror::Error)]
pub enum TicketError {
    /// The ticket string format is invalid.
    #[error("invalid connection ticket format")]
    InvalidFormat,
}

/// A high-level representation of an irosh connection ticket.
///
/// `Ticket` wraps Iroh's official `EndpointTicket` format so the crate can
/// expose a library-owned ticket type while remaining compatible with the Iroh
/// ecosystem.
///
/// The string form of a `Ticket` is intended for out-of-band sharing between a
/// server and a client.
///
/// # Example
///
/// ```no_run
/// # use std::error::Error;
/// use irosh::Ticket;
///
/// # fn main() -> Result<(), Box<dyn Error>> {
/// let ticket: Ticket = "endpoint...".parse()?;
/// let serialized = ticket.to_string();
/// # let _ = serialized;
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Ticket {
    /// The wrapped Iroh addressing information.
    pub(crate) inner: EndpointTicket,
}

impl Serialize for Ticket {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(&self.to_string())
    }
}

impl<'de> Deserialize<'de> for Ticket {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        Self::from_str(&s).map_err(serde::de::Error::custom)
    }
}

impl Ticket {
    /// Creates a new ticket from an Iroh EndpointAddr.
    pub fn new(addr: EndpointAddr) -> Self {
        Self {
            inner: EndpointTicket::new(addr),
        }
    }

    /// Returns a cloned copy of the underlying endpoint address.
    pub fn to_addr(&self) -> EndpointAddr {
        self.inner.endpoint_addr().clone()
    }
}

impl From<Ticket> for String {
    fn from(ticket: Ticket) -> Self {
        ticket.to_string()
    }
}

impl fmt::Display for Ticket {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // Use Iroh's native EndpointTicket string representation.
        write!(f, "{}", self.inner)
    }
}

impl FromStr for Ticket {
    type Err = TicketError;

    /// Parses an irosh ticket from either the native endpoint ticket string
    /// format or a legacy JSON endpoint-address form.
    ///
    /// The JSON fallback exists for backward compatibility with older
    /// management flows and should not be treated as the preferred external
    /// representation.
    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
        let s = s.trim();

        // Try to parse using Iroh's native EndpointTicket format.
        if let Ok(endpoint_ticket) = s.parse::<EndpointTicket>() {
            return Ok(Self {
                inner: endpoint_ticket,
            });
        }

        // Fallback to JSON (legacy management - maybe remove later?)
        if s.starts_with('{') {
            if let Ok(addr) = serde_json::from_str::<EndpointAddr>(s) {
                return Ok(Self::new(addr));
            }
        }

        Err(TicketError::InvalidFormat)
    }
}

impl TryFrom<&str> for Ticket {
    type Error = TicketError;

    fn try_from(value: &str) -> Result<Self, Self::Error> {
        value.parse()
    }
}

impl TryFrom<String> for Ticket {
    type Error = TicketError;

    fn try_from(value: String) -> Result<Self, Self::Error> {
        value.parse()
    }
}