ringdrop 0.7.0

P2P streamed file transfer with ring-based access control, built on iroh and bao protocols
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

use anyhow::{Context, Result};
use data_encoding::BASE32_NOPAD;
use iroh::{EndpointAddr, EndpointId};
use iroh_blobs::{BlobFormat, Hash};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct TicketWire {
    addr: EndpointAddr,
    hash: Hash,
    format: BlobFormat,
    name: Option<String>,
}

/// An out-of-band transfer ticket that encodes everything a receiver needs.
///
/// Tickets are serialised to a `rdrop://` URI (base32-encoded JSON) for easy
/// copy-paste. Pass one to [`Node::download`] to fetch the blob.
///
/// [`Node::download`]: crate::core::Node::download
#[derive(Debug, Clone)]
pub struct ShareTicket {
    addr: EndpointAddr,
    hash: Hash,
    format: BlobFormat,
    pub name: Option<String>,
}

impl ShareTicket {
    /// Create a ticket for a single raw blob (`BlobFormat::Raw`).
    pub fn new(addr: EndpointAddr, hash: Hash, name: Option<String>) -> Self {
        ShareTicket {
            addr,
            hash,
            format: BlobFormat::Raw,
            name,
        }
    }

    /// Create a ticket for a directory / collection (`BlobFormat::HashSeq`).
    pub fn new_collection(addr: EndpointAddr, hash: Hash, name: Option<String>) -> Self {
        ShareTicket {
            addr,
            hash,
            format: BlobFormat::HashSeq,
            name,
        }
    }

    /// Returns the BLAKE3 root hash of the blob or collection.
    pub fn hash(&self) -> Hash {
        self.hash
    }

    /// Returns the blob format (`Raw` for files, `HashSeq` for directories).
    pub fn format(&self) -> BlobFormat {
        self.format
    }

    /// Returns the network address of the node that issued this ticket.
    pub fn node_addr(&self) -> &EndpointAddr {
        &self.addr
    }

    /// Returns the [`EndpointId`] (Ed25519 public key) of the issuing node.
    ///
    /// [`EndpointId`]: iroh::EndpointId
    pub fn peer_id(&self) -> EndpointId {
        self.addr.id
    }

    /// Encode the ticket as a `rdrop://` URI.
    ///
    /// The URI is base32-encoded JSON and can be decoded with [`ShareTicket::from_uri`].
    ///
    /// # Errors
    ///
    /// Returns an error if the ticket cannot be serialised to JSON.
    pub fn to_uri(&self) -> Result<String> {
        let wire = TicketWire {
            addr: self.addr.clone(),
            hash: self.hash,
            format: self.format,
            name: self.name.clone(),
        };
        let json = serde_json::to_string(&wire).context("serializing ticket")?;
        let encoded = BASE32_NOPAD.encode(json.as_bytes()).to_lowercase();
        Ok(format!("rdrop://{encoded}"))
    }

    /// Decode a `rdrop://` URI produced by [`ShareTicket::to_uri`].
    ///
    /// # Errors
    ///
    /// Returns an error if the URI is missing the `rdrop://` prefix, the
    /// base32 payload cannot be decoded, or the inner JSON is malformed.
    pub fn from_uri(s: &str) -> Result<Self> {
        let encoded = s
            .strip_prefix("rdrop://")
            .context("invalid ticket: expected 'rdrop://' prefix")?;
        let bytes = BASE32_NOPAD
            .decode(encoded.to_uppercase().as_bytes())
            .context("invalid ticket: base32 decode failed")?;
        let wire: TicketWire =
            serde_json::from_slice(&bytes).context("invalid ticket: json parse failed")?;
        Ok(ShareTicket {
            addr: wire.addr,
            hash: wire.hash,
            format: wire.format,
            name: wire.name,
        })
    }
}