Skip to main content

codync_network/node/
mod.rs

1//! One computer on the network: its iroh endpoint, its roster and the agents it offers.
2
3mod conns;
4mod directory;
5mod endpoint;
6mod hello;
7mod inbound;
8mod outbox;
9
10use crate::guard::{self, Guard};
11use crate::reach::{Held, Reach};
12use crate::roster::{self, Change, Role, Roster};
13use crate::rules::{self, Rule};
14use crate::types::{Address, Connector, Letter, Message, Peer, Sent};
15use crate::wire::{self, ALPN, Agent, Request, Response, Ticket};
16use anyhow::{Context, Result, anyhow, bail};
17use iroh::endpoint::Connection;
18use iroh::protocol::Router;
19use iroh::{Endpoint, EndpointId};
20use std::collections::{HashMap, VecDeque};
21use std::path::{Path, PathBuf};
22use std::sync::atomic::{AtomicBool, Ordering};
23use std::sync::{Arc, Mutex, MutexGuard};
24use std::time::{Duration, Instant};
25use tokio::sync::{mpsc, watch};
26
27/// How long an invite stays good.
28pub const INVITE_FOR: Duration = Duration::from_hours(1);
29const INBOX_SIZE: usize = 256;
30/// Letters whose handoff count a reply may need, and requests an answer may come back to, newest kept.
31const HEARD_MAX: usize = 1000;
32
33pub struct Node {
34    inner: Arc<Inner>,
35    router: Router,
36}
37
38struct Inner {
39    endpoint: Endpoint,
40    dir: PathBuf,
41    roster: Mutex<Option<Roster>>,
42    agents: Mutex<Vec<(Agent, Reach)>>,
43    /// Names the app also sends as without offering them (`set_senders`).
44    senders: Mutex<Vec<String>>,
45    /// The app offered its agents since the node started: until then, letters wait at the sender.
46    ready: AtomicBool,
47    /// The handoff count of letters taken here, by id, so a reply carries the chain on.
48    heard: Mutex<VecDeque<(String, u8)>>,
49    /// What each other computer offered when it last answered or wrote.
50    seen: Mutex<HashMap<EndpointId, directory::Seen>>,
51    invites: Mutex<HashMap<String, Instant>>,
52    guard: Mutex<Guard>,
53    held: Mutex<Held>,
54    /// Letters already taken, so a sender's retry isn't delivered twice.
55    taken: Mutex<VecDeque<String>>,
56    /// Who may write to this computer's agents (`rules`).
57    rules: Mutex<Vec<Rule>>,
58    /// What a sender no rule matches gets ([`Node::set_default_access`]).
59    default_access: Mutex<rules::Access>,
60    /// Requests this computer sent, newest kept: the letter's id, the computer it went to and
61    /// the agent here that sent it. That computer's answer to that agent passes the rules.
62    asked: Mutex<VecDeque<(String, EndpointId, String)>>,
63    outbox: Mutex<Vec<outbox::Queued>>,
64    inbox: mpsc::Sender<Message>,
65    /// The open connection to each other computer, whichever side opened it ([`conns`]).
66    conns: Mutex<HashMap<EndpointId, Connection>>,
67    /// One connection attempt at a time per computer.
68    dialing: Mutex<HashMap<EndpointId, Arc<tokio::sync::Mutex<()>>>>,
69    /// The command an agent the network knocks on runs to answer.
70    reply_command: Mutex<String>,
71    /// What the app calls this network; invites carry it (`set_network_name`).
72    network_name: Mutex<Option<String>>,
73    /// Ticks when the members, their roles or names, or what the others offer or whether they
74    /// answer, change.
75    changed: watch::Sender<()>,
76}
77
78fn locked<T>(m: &Mutex<T>) -> MutexGuard<'_, T> {
79    m.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
80}
81
82impl Node {
83    /// Starts this computer's node. State (its key and the roster) lives in `dir`. Messages for
84    /// agents the app delivers to ([`Reach::App`]) come out of the returned inbox.
85    pub async fn start(dir: &Path, connector: &Connector) -> Result<(Self, mpsc::Receiver<Message>)> {
86        std::fs::create_dir_all(dir)?;
87        let key = endpoint::load_key(dir)?;
88        let endpoint = endpoint::bind(dir, key, connector).await?;
89        let (tx, rx) = mpsc::channel(INBOX_SIZE);
90        let inner = Arc::new(Inner {
91            endpoint: endpoint.clone(),
92            dir: dir.to_path_buf(),
93            roster: Mutex::new(Roster::load(dir)?),
94            agents: Mutex::default(),
95            senders: Mutex::default(),
96            ready: AtomicBool::new(false),
97            heard: Mutex::default(),
98            seen: Mutex::default(),
99            invites: Mutex::default(),
100            guard: Mutex::default(),
101            held: Mutex::default(),
102            taken: Mutex::default(),
103            rules: Mutex::default(),
104            default_access: Mutex::new(rules::Access::Allow),
105            asked: Mutex::default(),
106            outbox: Mutex::default(),
107            inbox: tx,
108            conns: Mutex::default(),
109            dialing: Mutex::default(),
110            reply_command: Mutex::new("codync-network".into()),
111            network_name: Mutex::default(),
112            changed: watch::Sender::new(()),
113        });
114        let router = Router::builder(endpoint).accept(ALPN, inbound::Handler(inner.clone())).spawn();
115        endpoint::settle(&inner.endpoint, connector).await;
116        inner.locate(inner.endpoint.addr())?;
117        tokio::spawn(outbox::retry_loop(Arc::downgrade(&inner)));
118        tokio::spawn(endpoint::follow_addr(Arc::downgrade(&inner), inner.endpoint.watch_addr()));
119        Ok((Self { inner, router }, rx))
120    }
121
122    pub fn id(&self) -> EndpointId {
123        self.inner.endpoint.id()
124    }
125
126    /// This computer's name, once it is in a network.
127    pub fn name(&self) -> Option<String> {
128        locked(&self.inner.roster).as_ref().map(|r| r.name(&self.id()))
129    }
130
131    /// The network's id (its root key), once this computer is in one.
132    pub fn network_id(&self) -> Option<String> {
133        locked(&self.inner.roster).as_ref().map(|r| r.network.to_string())
134    }
135
136    pub fn role(&self) -> Option<Role> {
137        locked(&self.inner.roster).as_ref().and_then(|r| r.role(&self.id()))
138    }
139
140    /// Starts a new network with this computer as its owner. Returns the recovery code: show it
141    /// once; it is kept nowhere.
142    pub fn create(&self, name: &str) -> Result<String> {
143        let mut roster = locked(&self.inner.roster);
144        if roster.is_some() {
145            bail!("this computer is already in a network");
146        }
147        let key = self.inner.endpoint.secret_key();
148        let (new, root) = Roster::create(key, check_name(name)?, self.inner.endpoint.addr(), wire::now_ms());
149        self.inner.save(&new)?;
150        *roster = Some(new);
151        Ok(roster::recovery_code(&root))
152    }
153
154    /// A one-time invite for another computer, good for an hour while this one stays on.
155    pub fn invite(&self) -> Result<String> {
156        let roster = self.inner.roster()?;
157        if !roster.role(&self.id()).is_some_and(Role::invites) {
158            bail!("only the owner and admins can invite computers");
159        }
160        let secret = wire::random_hex(16);
161        locked(&self.inner.invites).insert(secret.clone(), Instant::now() + INVITE_FOR);
162        let name = locked(&self.inner.network_name).clone();
163        Ticket { network: roster.network, secret, addr: self.inner.endpoint.addr(), name }.encode()
164    }
165
166    pub async fn join(&self, ticket: &str, name: &str) -> Result<()> {
167        if locked(&self.inner.roster).is_some() {
168            bail!("this computer is already in a network");
169        }
170        let ticket = Ticket::decode(ticket)?;
171        let request = Request::Join { network: ticket.network, secret: ticket.secret, name: check_name(name)? };
172        let conn = conns::dial(&self.inner.endpoint, ticket.addr)
173            .await
174            .context("the inviting computer didn't answer; is it on?")?;
175        let answer = conns::ask(&conn, &request).await;
176        conn.close(0u32.into(), b"done");
177        match answer? {
178            Response::Welcome { roster } if roster.network == ticket.network => {
179                let mut roster = roster.verified();
180                if !roster.is_member(&self.id()) {
181                    bail!("the inviting computer gave an unexpected answer");
182                }
183                // Where this computer is; nothing to add when it knows no address yet.
184                let addr = self.inner.endpoint.addr();
185                let _ = roster.sign(
186                    self.inner.endpoint.secret_key(),
187                    wire::now_ms(),
188                    Change::Locate { addr: roster::bounded_addr(addr) },
189                );
190                // Held across saving and keeping it, so whoever `changes` wakes sees it.
191                let mut guard = locked(&self.inner.roster);
192                self.inner.save(&roster)?;
193                *guard = Some(roster);
194                drop(guard);
195                // Before the app offers its agents, a hello would tell the others it offers none
196                // (and could land after the one that does): the first `set_agents` says it.
197                if self.inner.ready.load(Ordering::Acquire) {
198                    self.inner.clone().hello_all();
199                }
200                Ok(())
201            }
202            Response::Refused { reason } => bail!("{reason}"),
203            _ => bail!("the inviting computer gave an unexpected answer"),
204        }
205    }
206
207    /// Takes a computer out of the network for good. `cascade` also voids every computer it
208    /// admitted: for one that was stolen.
209    pub fn remove(&self, computer: &str, cascade: bool) -> Result<()> {
210        let id = self.inner.member(computer)?;
211        if id == self.id() {
212            bail!("a computer can't remove itself; remove it from another one");
213        }
214        self.inner.change(Change::Remove { id, cascade }, "only the owner removes admins; admins remove members")
215    }
216
217    /// The owner makes a computer an admin: it can invite and remove members.
218    pub fn promote(&self, computer: &str) -> Result<()> {
219        let id = self.inner.member(computer)?;
220        self.inner.change(Change::Promote { id }, "only the owner promotes computers")
221    }
222
223    /// Makes this computer the owner with the network's recovery code, for when the owner was
224    /// lost. Remove the old one afterwards.
225    pub fn recover(&self, code: &str) -> Result<()> {
226        let root = roster::root_from_code(code)?;
227        let mut guard = locked(&self.inner.roster);
228        let roster = guard.as_mut().ok_or_else(|| anyhow!("this computer isn't in a network"))?;
229        if root.public() != roster.network {
230            bail!("that recovery code is for another network");
231        }
232        let name = roster.name(&self.id());
233        roster.sign(&root, wire::now_ms(), Change::Owner { id: self.id(), name })?;
234        self.inner.save(roster)?;
235        drop(guard);
236        self.inner.clone().hello_all();
237        Ok(())
238    }
239
240    /// What this computer offers. The first call opens it to letters, and the others hear at once
241    /// (the hello that catches up with them, which a computer that was off may need for a removal it
242    /// missed), so what waited for it while it started comes now.
243    pub fn set_agents(&self, agents: impl IntoIterator<Item = (Agent, Reach)>) {
244        let before = self.inner.offered();
245        // A session the network knocks on is the kind its harness is, whatever the app said.
246        let agents = agents.into_iter().map(|(mut agent, reach)| {
247            if let Some(kind) = reach.kind() {
248                agent.kind = kind;
249            }
250            (agent, reach)
251        });
252        *locked(&self.inner.agents) = agents.collect();
253        if self.inner.offered() != before {
254            self.inner.changed.send_replace(());
255        }
256        if !self.inner.ready.swap(true, Ordering::AcqRel) {
257            self.inner.clone().hello_all();
258        }
259    }
260
261    /// Names the app sends letters as without offering them to the network: a hosted assistant that
262    /// asks agents elsewhere but can't be asked itself. Answers to its letters still come back.
263    pub fn set_senders(&self, senders: impl IntoIterator<Item = String>) {
264        *locked(&self.inner.senders) = senders.into_iter().collect();
265    }
266
267    /// Who on the other computers may write to this computer's agents, the first match deciding.
268    /// Answers to this computer's own letters always pass, so a rule added while a request runs
269    /// doesn't strand it.
270    pub fn set_rules(&self, rules: Vec<Rule>) -> Result<()> {
271        rules::check_all(&rules)?;
272        *locked(&self.inner.rules) = rules;
273        Ok(())
274    }
275
276    pub fn rules(&self) -> Vec<Rule> {
277        locked(&self.inner.rules).clone()
278    }
279
280    /// What a sender no rule matches gets: `Allow` unless the app sets another (a Codync host sets `Auto`). Only an
281    /// app that holds its agents to a ceiling should set `Auto` or `Ask`: a letter under one to a session the network
282    /// knocks on is refused.
283    pub fn set_default_access(&self, access: rules::Access) {
284        *locked(&self.inner.default_access) = access;
285    }
286
287    pub fn default_access(&self) -> rules::Access {
288        *locked(&self.inner.default_access)
289    }
290
291    /// What the app calls this network (`home`, `work`) when a computer is in several: the invites
292    /// it makes carry the name, so the computer that joins can call it the same ([`crate::read_invite`]).
293    pub fn set_network_name(&self, name: Option<String>) {
294        *locked(&self.inner.network_name) = name;
295    }
296
297    /// The command agents the network knocks on run to reply (default `codync-network`).
298    pub fn set_reply_command(&self, command: impl Into<String>) {
299        *locked(&self.inner.reply_command) = command.into();
300    }
301
302    /// Every computer in the network, asked now for what it offers.
303    pub async fn peers(&self) -> Result<Vec<Peer>> {
304        self.inner.roster()?;
305        self.inner.hello_each(self.inner.others()).await;
306        Ok(self.directory())
307    }
308
309    /// Every computer in the network, as last heard, without asking anyone.
310    pub fn directory(&self) -> Vec<Peer> {
311        self.inner.directory()
312    }
313
314    /// Changes whenever what [`Node::directory`] shows does: a computer joins or leaves, a role
315    /// or name changes, another computer offers different agents, or it starts or stops
316    /// answering. Ticks only; read the directory for what changed.
317    pub fn changes(&self) -> watch::Receiver<()> {
318        self.inner.changed.subscribe()
319    }
320
321    /// Where a bare agent name or a full `agent@computer` points: this computer first, then the
322    /// directory. Refuses a name more than one computer has, naming them.
323    pub fn resolve(&self, name: &str) -> Result<Address> {
324        self.inner.resolve(name)
325    }
326
327    /// Sends a letter from one of the agents this computer offers. An answer (`reply_to`) may also
328    /// come from one it no longer offers: renamed or gone while it worked, it still says how it ended.
329    pub async fn send(&self, letter: Letter) -> Result<Sent> {
330        let sender = |from: &str| {
331            self.inner.offered().iter().any(|a| a.id == from) || locked(&self.inner.senders).iter().any(|s| s == from)
332        };
333        if letter.reply_to.is_none() && !sender(&letter.from) {
334            bail!("{} isn't one of this computer's agents", letter.from);
335        }
336        // A reply carries on the chain of the letter it answers (one more handoff).
337        let mut letter = letter;
338        if letter.hops == 0
339            && let Some(hops) = letter.reply_to.as_deref().and_then(|id| self.inner.hops_of(id))
340        {
341            letter.hops = hops.saturating_add(1);
342        }
343        guard::check_hops(letter.hops).map_err(anyhow::Error::msg)?;
344        let roster = locked(&self.inner.roster).clone();
345        let id = match &roster {
346            None => self.id(),
347            Some(r) => {
348                r.find(&letter.to.computer).ok_or_else(|| anyhow!("no computer called {}", letter.to.computer))?
349            }
350        };
351        let local = id == self.id();
352        let envelope = letter.seal(wire::now_ms());
353        wire::check(&envelope)?;
354        // A request, which an answer may come back to past the other computer's rules.
355        if !local && envelope.wake && envelope.reply_to.is_none() {
356            remember(&mut locked(&self.inner.asked), (envelope.id.clone(), id, envelope.from.clone()), HEARD_MAX);
357        }
358        let name = |id: &EndpointId| roster.as_ref().map_or_else(|| "this computer".into(), |r| r.name(id));
359        let answer = if local {
360            Ok(self.inner.take(id, envelope.clone()).await)
361        } else {
362            self.inner.call(id, &Request::Deliver { envelope: envelope.clone() }).await
363        };
364        match answer {
365            Ok(Response::Stored) => Ok(Sent::Delivered),
366            Ok(Response::Refused { reason }) => bail!("{} refused it: {reason}", name(&id)),
367            Ok(Response::Later { reason }) if local => bail!("{reason}"),
368            Ok(Response::Later { reason }) => {
369                tracing::info!(to = %name(&id), reason, "queued for a computer that is starting");
370                self.inner.queue(id, envelope)?;
371                Ok(Sent::Queued)
372            }
373            Ok(_) => bail!("{} gave an unexpected answer", name(&id)),
374            Err(e) => {
375                tracing::info!(to = %name(&id), error = format!("{e:#}"), "queued for a computer that is away");
376                self.inner.queue(id, envelope)?;
377                Ok(Sent::Queued)
378            }
379        }
380    }
381
382    /// Stops answering and closes the endpoint (leaving a network, or quitting).
383    pub async fn shutdown(&self) {
384        let _ = self.router.shutdown().await;
385    }
386}
387
388impl Inner {
389    fn roster(&self) -> Result<Roster> {
390        locked(&self.roster).clone().ok_or_else(|| anyhow!("this computer isn't in a network yet"))
391    }
392
393    fn me(&self) -> EndpointId {
394        self.endpoint.id()
395    }
396
397    /// Whether a letter from `peer` answers a request this computer sent there, from the agent
398    /// the letter is for.
399    pub(super) fn answers(&self, peer: EndpointId, envelope: &wire::Envelope) -> bool {
400        let Some(id) = envelope.reply_to.as_deref() else { return false };
401        locked(&self.asked).iter().any(|(sent, to, by)| sent == id && *to == peer && *by == envelope.to)
402    }
403
404    fn hops_of(&self, letter: &str) -> Option<u8> {
405        locked(&self.heard).iter().rev().find(|(id, _)| id == letter).map(|(_, hops)| *hops)
406    }
407
408    fn heard(&self, letter: &str, hops: u8) {
409        remember(&mut locked(&self.heard), (letter.to_owned(), hops), HEARD_MAX);
410    }
411
412    fn offered(&self) -> Vec<Agent> {
413        locked(&self.agents).iter().map(|(agent, _)| agent.clone()).collect()
414    }
415
416    fn member(&self, computer: &str) -> Result<EndpointId> {
417        self.roster()?.find(computer).ok_or_else(|| anyhow!("no computer called {computer}"))
418    }
419
420    /// Signs `change` as this computer, saves it and tells the others.
421    fn change(self: &Arc<Self>, change: Change, refused: &str) -> Result<()> {
422        let mut guard = locked(&self.roster);
423        let roster = guard.as_mut().ok_or_else(|| anyhow!("this computer isn't in a network"))?;
424        roster.sign(self.endpoint.secret_key(), wire::now_ms(), change).map_err(|_| anyhow!("{refused}"))?;
425        self.save(roster)?;
426        drop(guard);
427        self.clone().hello_all();
428        Ok(())
429    }
430
431    /// Keeps `roster` on disk and tells whoever watches [`Node::changes`]. Callers hold the roster
432    /// lock until `roster` is the one kept in memory, so a watcher woken here reads it.
433    fn save(&self, roster: &Roster) -> Result<()> {
434        roster.save(&self.dir)?;
435        self.close_outsiders(roster);
436        self.changed.send_replace(());
437        Ok(())
438    }
439}
440
441fn check_name(name: &str) -> Result<String> {
442    let name = name.trim();
443    if name.is_empty() || name.len() > 40 || name.contains(roster::NOT_IN_NAMES) {
444        bail!("a computer's name is 1–40 characters, without spaces, /, @ or .");
445    }
446    Ok(name.into())
447}
448
449/// Keeps `item` in a list of the newest `max`.
450fn remember<T>(list: &mut VecDeque<T>, item: T, max: usize) {
451    if list.len() >= max {
452        list.pop_front();
453    }
454    list.push_back(item);
455}
456
457#[cfg(test)]
458mod testing {
459    use crate::reach::Reach;
460    use crate::wire::{Agent, AgentKind};
461    use std::time::Duration;
462
463    /// An agent the app takes letters for.
464    pub(super) fn agent(id: &str) -> (Agent, Reach) {
465        (Agent { id: id.into(), name: id.into(), about: String::new(), kind: AgentKind::Codync }, Reach::App)
466    }
467
468    /// Waits up to 10 s until `done`.
469    pub(super) async fn until(what: &str, done: impl Fn() -> bool) {
470        tokio::time::timeout(Duration::from_secs(10), async {
471            while !done() {
472                tokio::time::sleep(Duration::from_millis(50)).await;
473            }
474        })
475        .await
476        .unwrap_or_else(|_| panic!("timed out waiting until {what}"));
477    }
478}