//! High-level async client API for Meow v2. //! //! [`MeowClient`] owns one identity store ([`meow_store`]) and exposes servers, //! contacts, invitations, messaging and synchronisation. It is the API mirrored by the //! CLI and, later, by the Flutter FFI layer (`meow-ffi`). //! //! **Spaces.** The main password opens the main space (nickname, servers, visible //! contacts). [`MeowClient::unlock`] opens hidden spaces, each holding one or several //! contacts; their contacts then behave like the others (listed, polled, usable) until //! the client is dropped. Only spaces that changed are written back, so an unused //! hidden space is never touched on disk. //! //! Invariant: any ratchet/contact state change is **persisted before** the //! resulting bytes leave the device (or the server is told to delete a message), so //! a crash can never make us reuse a key or lose a message. #![forbid(unsafe_code)] #![cfg_attr(not(test), warn(clippy::unwrap_used, clippy::expect_used))] pub mod transport; use std::collections::BTreeMap; use std::path::Path; use std::time::{Duration, SystemTime, UNIX_EPOCH}; use futures_util::future::join_all; use meow_core::contact::{Contact, ContactState}; use meow_core::invitation::{self, OfferInfo}; use meow_core::server::{canonical_url, ServerInfo}; use meow_core::{messaging, rpc}; use meow_crypto::password::KdfParams; use meow_crypto::{SignPublic, SigningKeyPair}; use meow_proto::v2::{self, request::Body as Req, response::Body as Resp}; use meow_proto::Message; use meow_store::{Batch, RetiredMailbox, SpaceId, State as SpaceState, Store}; pub use meow_core::contact::ContactState as State; pub use meow_store::{Content, HistoryEntry, HistoryPage, PendingAck}; /// Maximum file size sent in a single message (chunking: roadmap 5.7). pub const MAX_FILE_BYTES: usize = 4 * 1024 * 1024; /// Default invitation lifetime. pub const DEFAULT_INVITATION_TTL: u64 = 7 * 86_400; #[derive(Debug, thiserror::Error)] pub enum Error { #[error("wrong password")] BadPassword, #[error("identity {0} is in use by another process")] Locked(String), #[error("storage: {0}")] Store(meow_store::Error), #[error("i/o: {0}")] Io(#[from] std::io::Error), #[error("network: {0}")] Network(String), #[error(transparent)] Protocol(#[from] meow_core::Error), #[error("crypto: {0}")] Crypto(#[from] meow_crypto::CryptoError), #[error("unknown server: {0}")] UnknownServer(String), #[error("server {0} changed its keys: refusing (remove and re-add it if this is expected)")] ServerKeyChanged(String), #[error("unknown contact: {0}")] UnknownContact(String), #[error("a contact named {0:?} already exists")] NameTaken(String), #[error("{0}")] Invalid(String), } impl From for Error { fn from(e: meow_store::Error) -> Self { match e { meow_store::Error::BadPassword => Error::BadPassword, meow_store::Error::Locked(p) => Error::Locked(p), meow_store::Error::Exists(p) => Error::Invalid(format!("{p} already exists (use --force)")), meow_store::Error::Io(e) => Error::Io(e), other => Error::Store(other), } } } pub type Result = std::result::Result; pub(crate) fn now() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_secs()) .unwrap_or(0) } fn now_ms() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_millis() as u64) .unwrap_or(0) } /// Something that happened during [`MeowClient::sync`]. #[derive(Debug, Clone, PartialEq, Eq)] pub enum Event { /// Initiator side: the invitee answered a server-published invitation; the /// confirmation has been sent automatically. InvitationAccepted { contact: String }, /// The handshake is complete on this side. ContactActivated { contact: String }, Message { contact: String, id: Vec, text: String, sent_at_ms: u64, }, /// A file was received (its content is also kept: [`MeowClient::file`]). File { contact: String, id: Vec, name: String, data: Vec, }, } /// Outcome of a send. #[derive(Debug, Clone, PartialEq, Eq)] pub struct SendReport { pub message_id: Vec, /// Number of servers that accepted the deposit. pub delivered_to: usize, } /// Acknowledged ids sent per mailbox and pull (server limit: 1024). const MAX_ACKS_PER_MAILBOX: usize = 512; #[derive(Default)] struct PullRound { /// Messages to process, with the index of the space owning their mailbox. new: Vec<(usize, v2::StoredMessage)>, /// A server held messages back. more: bool, } /// One unlocked space, in memory. struct Space { id: SpaceId, state: SpaceState, /// History and files waiting for the next save of this space. batch: Batch, /// Changed since the last save. dirty: bool, } /// One identity: its store and unlocked spaces. Index 0 is always the main space. pub struct MeowClient { /// Behind a mutex only to make the client `Sync` (SQLite connections are not); /// never held across an `.await`. store: std::sync::Mutex, spaces: Vec, transport: transport::Transport, } type Mailboxes = Vec<(SigningKeyPair, Vec)>; fn lock(store: &std::sync::Mutex) -> Result> { store.lock().map_err(|_| Error::Invalid("store lock poisoned".into())) } impl MeowClient { // ───────────────────────── lifecycle ───────────────────────── /// Create a new identity. Fails if `path` exists, unless `overwrite`. pub async fn create(path: &Path, nickname: &str, password: &str, kdf: KdfParams, overwrite: bool) -> Result { let store = Store::create(path, nickname, password, kdf, overwrite)?; Self::with_store(store) } /// Open an existing identity with its main password. pub async fn open(path: &Path, password: &str) -> Result { Self::with_store(Store::open(path, password)?) } fn with_store(mut store: Store) -> Result { let state = store.load(SpaceId::MAIN)?; Ok(Self { store: std::sync::Mutex::new(store), spaces: vec![Space { id: SpaceId::MAIN, state, batch: Batch::default(), dirty: false, }], transport: transport::Transport::new()?, }) } /// Write every changed space. pub async fn save(&mut self) -> Result<()> { for i in 0..self.spaces.len() { if self.spaces[i].dirty { self.save_space(i)?; } } Ok(()) } fn save_space(&mut self, i: usize) -> Result<()> { let sp = &mut self.spaces[i]; let batch = std::mem::take(&mut sp.batch); lock(&self.store)?.save(sp.id, &sp.state, batch)?; sp.dirty = false; Ok(()) } /// Change the main password (instantaneous: only the space root moves). pub async fn change_password(&mut self, new_password: &str) -> Result<()> { Ok(lock(&self.store)?.change_password(SpaceId::MAIN, new_password)?) } pub fn nickname(&self) -> &str { &self.main().nickname } fn main(&self) -> &SpaceState { &self.spaces[0].state } // ───────────────────────── hidden spaces ───────────────────────── /// Try a hidden-space password; `true` if it opened one (its contacts are now /// available). Same cost whether or not such a space exists. pub async fn unlock(&mut self, password: &str) -> Result { let found = lock(&self.store)?.unlock(password)?; match found { Some(id) => { self.space_index(id)?; Ok(true) } None => Ok(false), } } /// Index of an unlocked space in `self.spaces`, loading it if needed. fn space_index(&mut self, id: SpaceId) -> Result { if let Some(i) = self.spaces.iter().position(|s| s.id == id) { return Ok(i); } let state = lock(&self.store)?.load(id)?; self.spaces.push(Space { id, state, batch: Batch::default(), dirty: false, }); Ok(self.spaces.len() - 1) } /// Move a contact, with its history and files, into the hidden space opened by /// `password` (created if none). Several contacts may share a space. pub async fn hide_contact(&mut self, name: &str, password: &str) -> Result<()> { let found = lock(&self.store)?.unlock(password)?; let id = match found { Some(id) => id, None => lock(&self.store)?.create_space(password)?, }; if id == SpaceId::MAIN { return Err(Error::Invalid("this is the main password".into())); } let target = self.space_index(id)?; self.move_contact(name, target) } /// Move a hidden contact back to the main space. pub async fn reveal_contact(&mut self, name: &str) -> Result<()> { self.move_contact(name, 0) } /// Whether a contact lives in a hidden space. pub fn is_hidden(&self, name: &str) -> Result { Ok(self.locate(name)?.0 != 0) } fn move_contact(&mut self, name: &str, target: usize) -> Result<()> { let (si, ci) = self.locate(name)?; if si == target { return Ok(()); } let contact = self.spaces[si].state.contacts[ci].clone(); let src = self.spaces[si].id; let history = lock(&self.store)?.full_history(src, &contact.id)?; let mut files = Vec::new(); for h in history.iter().filter(|h| !h.outbound) { if matches!(h.content, Content::File { .. }) { if let Some(data) = lock(&self.store)?.file(src, &contact.id, &h.id)? { files.push((contact.id.clone(), h.id.clone(), data)); } } } let mailboxes: Vec> = contact .mailboxes() .iter() .map(|(kp, _)| kp.public().as_bytes().to_vec()) .collect(); let acks: Vec = self.spaces[si] .state .pending_acks .iter() .filter(|a| mailboxes.contains(&a.mailbox)) .cloned() .collect(); // Write the destination first: a crash in between leaves a copy, never a loss. let t = &mut self.spaces[target]; t.state.contacts.push(contact); t.state.pending_acks.extend(acks); t.batch.history.extend(history); t.batch.files.extend(files); self.save_space(target)?; let s = &mut self.spaces[si]; s.state.contacts.remove(ci); s.state.pending_acks.retain(|a| !mailboxes.contains(&a.mailbox)); self.save_space(si) } // ───────────────────────── servers ───────────────────────── /// Add a server: fetch its card, verify it and pin its keys (TOFU). pub async fn add_server(&mut self, url: &str) -> Result { let info = self.transport.fetch_card(url).await?; if canonical_url(url) != info.url { tracing::warn!("server announces {} (contacted as {url})", info.url); } if let Some(known) = self .main() .servers .iter() .find(|s| s.url == info.url || s.sign_key == info.sign_key) { if !known.same_keys(&info) { return Err(Error::ServerKeyChanged(info.url)); } return Ok(known.clone()); } self.spaces[0].state.servers.push(info.clone()); self.save_space(0)?; Ok(info) } pub fn servers(&self) -> &[ServerInfo] { &self.main().servers } pub async fn remove_server(&mut self, url_or_name: &str) -> Result<()> { let u = canonical_url(url_or_name); let servers = &mut self.spaces[0].state.servers; let before = servers.len(); servers.retain(|s| s.url != u && s.name != url_or_name); if servers.len() == before { return Err(Error::UnknownServer(url_or_name.to_string())); } self.save_space(0) } /// Resolve URLs to known servers; an empty list means "all my servers". fn resolve_servers(&self, urls: &[String]) -> Result> { let servers = &self.main().servers; if urls.is_empty() { if servers.is_empty() { return Err(Error::Invalid("no server configured: add one first".into())); } return Ok(servers.clone()); } urls.iter() .map(|u| { let cu = canonical_url(u); servers .iter() .find(|s| s.url == cu || s.name == *u) .cloned() .ok_or_else(|| Error::UnknownServer(u.clone())) }) .collect() } // ───────────────────────── contacts ───────────────────────── /// Contacts of every unlocked space (main space first). pub fn contacts(&self) -> Vec<&Contact> { self.spaces.iter().flat_map(|s| s.state.contacts.iter()).collect() } pub fn contact(&self, name: &str) -> Result<&Contact> { let (si, ci) = self.locate(name)?; Ok(&self.spaces[si].state.contacts[ci]) } /// (space index, contact index) of a contact. fn locate(&self, name: &str) -> Result<(usize, usize)> { self.find(|c| c.name == name) .ok_or_else(|| Error::UnknownContact(name.to_string())) } fn find(&self, pred: impl Fn(&Contact) -> bool) -> Option<(usize, usize)> { self.spaces .iter() .enumerate() .find_map(|(si, s)| s.state.contacts.iter().position(&pred).map(|ci| (si, ci))) } fn ensure_free_name(&self, name: &str) -> Result<()> { if self.find(|c| c.name == name).is_some() { return Err(Error::NameTaken(name.to_string())); } Ok(()) } /// Delete a contact with its history and files. pub async fn remove_contact(&mut self, name: &str) -> Result<()> { let (si, ci) = self.locate(name)?; let before = self.space_mailboxes(si); self.spaces[si].state.contacts.remove(ci); self.retire_mailboxes(si, before); self.save_space(si) } /// Whole conversation with a contact, oldest first. pub fn history(&self, name: &str) -> Result> { let (si, ci) = self.locate(name)?; let sp = &self.spaces[si]; Ok(lock(&self.store)?.full_history(sp.id, &sp.state.contacts[ci].id)?) } /// One segment of a conversation (`None`: the latest), oldest first. pub fn history_page(&self, name: &str, page: Option) -> Result { let (si, ci) = self.locate(name)?; let sp = &self.spaces[si]; Ok(lock(&self.store)?.history(sp.id, &sp.state.contacts[ci].id, page)?) } /// Content of a received file. pub fn file(&self, name: &str, message_id: &[u8]) -> Result>> { let (si, ci) = self.locate(name)?; let sp = &self.spaces[si]; Ok(lock(&self.store)?.file(sp.id, &sp.state.contacts[ci].id, message_id)?) } // ───────────────────────── invitations ───────────────────────── // New contacts are created in the main space; hide them afterwards if needed. /// Step 1: create an invitation for `contact_name`. Returns the encoded offer. pub async fn create_invitation( &mut self, contact_name: &str, server_urls: &[String], message: &str, ttl: u64, ) -> Result> { self.ensure_free_name(contact_name)?; let servers = self.resolve_servers(server_urls)?; let offer = invitation::create_offer(contact_name, self.nickname(), servers, message, now(), ttl)?; self.spaces[0].state.contacts.push(offer.contact); self.save_space(0)?; Ok(offer.offer_bytes) } pub fn inspect_invitation(&self, offer_bytes: &[u8]) -> Result { Ok(invitation::inspect_offer(offer_bytes, now())?) } /// Step 2: answer an offer. Returns the encoded answer (file flow). pub async fn answer_invitation( &mut self, offer_bytes: &[u8], contact_name: Option<&str>, server_urls: &[String], ) -> Result> { let info = self.inspect_invitation(offer_bytes)?; let name = contact_name.unwrap_or(&info.initiator_name).to_string(); self.ensure_free_name(&name)?; if self.find(|c| c.invitation_id == info.invitation_id).is_some() { return Err(Error::Invalid("this invitation was already answered".into())); } let servers = self.resolve_servers(server_urls)?; let (contact, answer) = invitation::answer(offer_bytes, &name, self.nickname(), servers, now())?; self.spaces[0].state.contacts.push(contact); self.save_space(0)?; Ok(answer.encode_to_vec()) } fn by_invitation(&self, id: &[u8]) -> Result<(usize, usize)> { self.find(|c| c.invitation_id.as_slice() == id) .ok_or_else(|| Error::Invalid("no pending invitation matches".into())) } /// Step 3 (file flow): process an answer, returns the encoded confirmation. pub async fn accept_answer(&mut self, answer_bytes: &[u8]) -> Result> { let msg = v2::InvitationMessage::decode(answer_bytes).map_err(meow_core::Error::from)?; let (si, ci) = self.by_invitation(&msg.invitation_id)?; let confirm = invitation::accept(&mut self.spaces[si].state.contacts[ci], &msg, now())?; self.save_space(si)?; Ok(confirm.encode_to_vec()) } /// Step 4 (file flow): process a confirmation and send the ack through the network. pub async fn finalize_invitation(&mut self, confirm_bytes: &[u8]) -> Result { let msg = v2::InvitationMessage::decode(confirm_bytes).map_err(meow_core::Error::from)?; let (si, ci) = self.by_invitation(&msg.invitation_id)?; let contact = &mut self.spaces[si].state.contacts[ci]; let ack = invitation::finalize(contact, &msg)?; let deposit = messaging::deposit_for(contact, &ack)?; let servers = peer_servers(contact); let name = contact.name.clone(); self.save_space(si)?; self.deliver(&servers, vec![deposit]).await?; Ok(name) } /// Step 1 through a server: publish the offer and return its URL /// (`/inv/`). pub async fn publish_invitation( &mut self, contact_name: &str, server_urls: &[String], message: &str, password: &str, ttl: u64, ) -> Result { let offer = self.create_invitation(contact_name, server_urls, message, ttl).await?; let server = self.resolve_servers(server_urls)?.remove(0); let resp = self .transport .call( &server, Req::InvPublish(v2::InvitationPublish { payload: offer, ttl_seconds: ttl.min(u32::MAX as u64) as u32, shortcode_len: 10, password: password.to_string(), }), Duration::ZERO, ) .await?; match resp { Resp::InvPublished(p) => Ok(format!("{}/inv/{}", server.url, p.shortcode)), _ => Err(Error::Network("unexpected response".into())), } } /// Step 2 through a server: fetch an offer by URL, answer it and post the answer /// in the initiator's answer mailbox. Returns the initiator's name. pub async fn accept_published_invitation( &mut self, url: &str, password: &str, contact_name: Option<&str>, server_urls: &[String], ) -> Result { let (base, code) = url .rsplit_once("/inv/") .ok_or_else(|| Error::Invalid("invitation URL must look like /inv/".into()))?; let server = self.transport.fetch_card(base).await?; let resp = self .transport .call( &server, Req::InvFetch(v2::InvitationFetch { shortcode: code.to_string(), password: password.to_string(), }), Duration::ZERO, ) .await?; let Resp::InvFetched(f) = resp else { return Err(Error::Network("unexpected response".into())); }; let info = self.inspect_invitation(&f.payload)?; let answer_bytes = self.answer_invitation(&f.payload, contact_name, server_urls).await?; let answer = v2::InvitationMessage::decode(answer_bytes.as_slice()).map_err(meow_core::Error::from)?; self.deliver(&info.answer_servers, vec![invitation::answer_deposit(&info, &answer)]) .await?; Ok(info.initiator_name) } // ───────────────────────── messaging ───────────────────────── pub async fn send_text(&mut self, contact_name: &str, text: &str) -> Result { let msg = messaging::text(text, now_ms()); self.send(contact_name, msg, Content::Text(text.to_string())).await } pub async fn send_file(&mut self, contact_name: &str, path: &Path) -> Result { let data = tokio::fs::read(path).await?; if data.len() > MAX_FILE_BYTES { return Err(Error::Invalid(format!("file larger than {MAX_FILE_BYTES} bytes"))); } let name = path .file_name() .map(|n| n.to_string_lossy().to_string()) .ok_or_else(|| Error::Invalid("bad file name".into()))?; let size = data.len() as u64; let body = v2::user_message::Body::File(v2::FileBody { filename: name.clone(), size, chunk: 0, chunks: 1, data, mime: String::new(), }); self.send( contact_name, messaging::new_message(body, now_ms()), Content::File { name, size }, ) .await } async fn send(&mut self, contact_name: &str, msg: v2::UserMessage, content: Content) -> Result { let (si, ci) = self.locate(contact_name)?; let sp = &mut self.spaces[si]; let contact = &mut sp.state.contacts[ci]; let env = messaging::encrypt(contact, &msg)?; let deposit = messaging::deposit_for(contact, &env)?; let servers = peer_servers(contact); sp.batch.history.push(HistoryEntry { id: msg.id.clone(), contact: contact.id.clone(), outbound: true, sent_at_ms: msg.sent_at_ms, received_at: now(), content, }); self.save_space(si)?; let delivered_to = self.deliver(&servers, vec![deposit]).await?; Ok(SendReport { message_id: msg.id, delivered_to, }) } /// Post deposits to every server; succeeds if at least one accepted them. async fn deliver(&self, servers: &[ServerInfo], deposits: Vec) -> Result { if servers.is_empty() { return Err(Error::Invalid("contact has no server".into())); } let calls = servers.iter().map(|s| { self.transport.call( s, Req::Post(v2::Post { deposits: deposits.clone(), }), Duration::ZERO, ) }); let mut ok = 0; let mut last_err = None; for (s, r) in servers.iter().zip(join_all(calls).await) { match r { Ok(Resp::PostAck(_)) => ok += 1, Ok(_) => last_err = Some(Error::Network(format!("{}: unexpected response", s.url))), Err(e) => { tracing::warn!("deposit on {} failed: {e}", s.url); last_err = Some(e); } } } match (ok, last_err) { (0, Some(e)) => Err(e), (n, _) => Ok(n), } } // ───────────────────────── sync ───────────────────────── /// Pull every mailbox of every unlocked space on every server (one request per /// server), process what arrived and return the resulting events. With `wait > 0` /// the servers hold the request until something arrives or the delay expires /// (long-poll). /// /// Delivery is at-least-once: servers keep messages until they are acknowledged, /// and a message is acknowledged (in the next pull) only once its effects are saved. /// After a round that brought messages, `sync` pulls again without waiting, which /// sends the acknowledgements and fetches what the servers held back. pub async fn sync(&mut self, wait: Duration) -> Result> { const MAX_ROUNDS: usize = 16; let mut events = Vec::new(); let mut wait = wait; for round in 0..MAX_ROUNDS { let r = match self.pull_round(wait).await { Ok(r) => r, // A later round only flushes acks and backlog: keep what we already got. Err(e) if round > 0 => { tracing::warn!("follow-up pull failed: {e}"); break; } Err(e) => return Err(e), }; let got_new = !r.new.is_empty(); if got_new { events.extend(self.process(r.new).await?); } // Pull again (without waiting) only to acknowledge what just arrived and to // fetch what servers held back. Redeliveries alone do not loop. if !got_new && !r.more { break; } wait = Duration::ZERO; } Ok(events) } /// One pull per server, carrying the pending acks. New (not yet processed) messages /// are returned and recorded as pending acks of the space owning their mailbox; /// they are saved by [`Self::process`]. async fn pull_round(&mut self, wait: Duration) -> Result { // server (by signing key) → (server, [(space index, mailbox key)]) let mut jobs: BTreeMap)> = BTreeMap::new(); for si in 0..self.spaces.len() { let st = &mut self.spaces[si].state; let pending = &st.pending_acks; st.retired_mailboxes.retain(|r| { pending .iter() .any(|a| a.mailbox.as_slice() == r.key.public().as_bytes().as_slice()) }); let retired: Mailboxes = self.spaces[si] .state .retired_mailboxes .iter() .map(|r| (r.key.clone(), r.servers.clone())) .collect(); for (kp, servers) in self.space_mailboxes(si).into_iter().chain(retired) { for s in servers { jobs.entry(s.sign_key) .or_insert_with(|| (s.clone(), Vec::new())) .1 .push((si, kp.clone())); } } } // Drop acks nobody can send any more (contact or server removed). for (si, sp) in self.spaces.iter_mut().enumerate() { sp.state.pending_acks.retain(|a| { jobs.get(&a.server).is_some_and(|(_, kps)| { kps.iter() .any(|(s, kp)| *s == si && kp.public().as_bytes().as_slice() == a.mailbox.as_slice()) }) }); } let mut round = PullRound::default(); if jobs.is_empty() { return Ok(round); } let wait_s = wait.as_secs().min(u32::MAX as u64) as u32; let mut sent_acks: Vec> = Vec::with_capacity(jobs.len()); let mut requests = Vec::with_capacity(jobs.len()); for (server, kps) in jobs.values() { let rid = meow_crypto::random_bytes::<16>().to_vec(); let ts = now(); let mut sent = Vec::new(); let auths = kps .iter() .map(|(si, kp)| { let mb = kp.public(); let acks: Vec> = self.spaces[*si] .state .pending_acks .iter() .filter(|a| a.server == server.sign_key && a.mailbox.as_slice() == mb.as_bytes().as_slice()) .take(MAX_ACKS_PER_MAILBOX) .inspect(|a| sent.push((*si, (*a).clone()))) .map(|a| a.id.clone()) .collect(); rpc::mailbox_auth(kp, server, &rid, acks, ts) }) .collect(); sent_acks.push(sent); requests.push(v2::Request { request_id: rid, timestamp: ts, body: Some(Req::Pull(v2::Pull { auths, wait_seconds: wait_s, })), }); } let calls = jobs .values() .zip(requests) .map(|((server, _), req)| self.transport.call_request(server, req, wait)); let results = join_all(calls).await; let mut failures = 0; let mut last_err = None; for (((server, kps), r), sent) in jobs.values().zip(results).zip(sent_acks) { match r { Ok(Resp::PullResult(p)) => { // The server applied our acks before answering. Forgetting them // needs no save: at worst they are sent again (acks are idempotent). for (si, a) in &sent { self.spaces[*si].state.pending_acks.retain(|x| x != a); } round.more |= p.more; for m in p.messages { let Some((si, _)) = kps .iter() .find(|(_, kp)| kp.public().as_bytes().as_slice() == m.mailbox.as_slice()) else { tracing::debug!("server sent a message for a mailbox we did not pull"); continue; }; let ack = PendingAck { server: server.sign_key, mailbox: m.mailbox.clone(), id: m.id.clone(), }; let sp = &mut self.spaces[*si]; // Already processed (its ack was lost): only re-acknowledge. if !sp.state.pending_acks.contains(&ack) { sp.state.pending_acks.push(ack); sp.dirty = true; round.new.push((*si, m)); } } } Ok(_) => failures += 1, Err(e) => { tracing::warn!("pull on {} failed: {e}", server.url); failures += 1; last_err = Some(e); } } } if failures == jobs.len() { return Err(last_err.unwrap_or_else(|| Error::Network("all servers failed".into()))); } Ok(round) } /// Every mailbox currently used by a contact of a space, with its pull servers. fn space_mailboxes(&self, si: usize) -> Mailboxes { self.spaces[si] .state .contacts .iter() .flat_map(|c| c.mailboxes()) .map(|(kp, servers)| (kp.clone(), servers.to_vec())) .collect() } /// Keep the keys of mailboxes that disappeared from a space (`before` → now) while /// they still have pending acks, so the next pull can acknowledge their last messages. fn retire_mailboxes(&mut self, si: usize, before: Mailboxes) { let current: Vec = self.space_mailboxes(si).iter().map(|(kp, _)| kp.public()).collect(); let st = &mut self.spaces[si].state; for (key, servers) in before { let pk = key.public(); let has_acks = st .pending_acks .iter() .any(|a| a.mailbox.as_slice() == pk.as_bytes().as_slice()); let known = st.retired_mailboxes.iter().any(|r| r.key.public() == pk); if has_acks && !known && !current.contains(&pk) { st.retired_mailboxes.push(RetiredMailbox { key, servers }); } } } async fn process(&mut self, stored: Vec<(usize, v2::StoredMessage)>) -> Result> { let mailboxes_before: Vec = (0..self.spaces.len()).map(|si| self.space_mailboxes(si)).collect(); // Handshake messages first (step 2 before step 3), then ratchet messages by arrival. let mut envs: Vec<(u32, u64, usize, Vec, v2::PeerEnvelope)> = stored .into_iter() .filter_map(|(si, m)| { let env = v2::PeerEnvelope::decode(m.payload.as_slice()).ok()?; let rank = match &env.body { Some(v2::peer_envelope::Body::Invitation(i)) => i.step, _ => 10, }; Some((rank, m.received_at, si, m.mailbox, env)) }) .collect(); envs.sort_by_key(|(rank, at, _, _, _)| (*rank, *at)); let mut events = Vec::new(); let mut outgoing: Vec<(Vec, v2::Deposit)> = Vec::new(); for (_, received_at, si, mailbox, env) in envs { let sp = &mut self.spaces[si]; let Some(ci) = sp.state.contacts.iter().position(|c| { c.mailboxes() .iter() .any(|(kp, _)| kp.public().as_bytes().as_slice() == mailbox.as_slice()) }) else { tracing::debug!("message for a retired mailbox"); continue; }; let contact = &mut sp.state.contacts[ci]; match env.body { Some(v2::peer_envelope::Body::Invitation(inv)) if inv.step == 2 => { match invitation::accept(contact, &inv, now()) { Ok(confirm) => { outgoing.push((peer_servers(contact), invitation::confirm_deposit(contact, &confirm)?)); events.push(Event::InvitationAccepted { contact: contact.name.clone(), }); } Err(e) => tracing::debug!("ignoring answer: {e}"), } } Some(v2::peer_envelope::Body::Invitation(inv)) if inv.step == 3 => { match invitation::finalize(contact, &inv) { Ok(ack) => { outgoing.push((peer_servers(contact), messaging::deposit_for(contact, &ack)?)); events.push(Event::ContactActivated { contact: contact.name.clone(), }); } Err(e) => tracing::debug!("ignoring confirmation: {e}"), } } Some(v2::peer_envelope::Body::Ratchet(rm)) => { let was = contact.state; let msg = match messaging::decrypt(contact, &rm) { Ok(m) => m, // Typically the same deposit received from a second server. Err(e) => { tracing::debug!("dropping undecryptable message: {e}"); continue; } }; let name = contact.name.clone(); let cid = contact.id.clone(); if was != ContactState::Active && contact.state == ContactState::Active { events.push(Event::ContactActivated { contact: name.clone() }); } let entry = |content| HistoryEntry { id: msg.id.clone(), contact: cid.clone(), outbound: false, sent_at_ms: msg.sent_at_ms, received_at, content, }; match &msg.body { Some(v2::user_message::Body::Text(t)) => { sp.batch.history.push(entry(Content::Text(t.text.clone()))); events.push(Event::Message { contact: name, id: msg.id.clone(), text: t.text.clone(), sent_at_ms: msg.sent_at_ms, }); } Some(v2::user_message::Body::File(f)) => { sp.batch.history.push(entry(Content::File { name: f.filename.clone(), size: f.size, })); sp.batch.files.push((cid.clone(), msg.id.clone(), f.data.clone())); events.push(Event::File { contact: name, id: msg.id.clone(), name: f.filename.clone(), data: f.data.clone(), }); } _ => {} } } _ => tracing::debug!("ignoring unsupported envelope"), } sp.dirty = true; } for (si, before) in mailboxes_before.into_iter().enumerate() { if self.spaces[si].dirty { self.retire_mailboxes(si, before); } } // Persist before anything leaves the device. self.save().await?; for (servers, deposit) in outgoing { if let Err(e) = self.deliver(&servers, vec![deposit]).await { tracing::warn!("could not deliver handshake message: {e}"); } } Ok(events) } } fn peer_servers(contact: &Contact) -> Vec { contact .peer .as_ref() .map(|p| p.pull_servers.clone()) .unwrap_or_default() }