vaegram 0.2.0

Telegram MTProto client library for users and bots
Documentation
use std::collections::VecDeque;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, RwLock};

use tokio::sync::Notify;

use crate::enums::ClientEvent;
use crate::raw::{base, types};

type Listener = Arc<dyn Fn(ClientEvent) + Send + Sync>;
type LinkListener = Arc<dyn Fn(bool) + Send + Sync>;

/// Where sessions report what happens below the requests (reconnects, dropped packets or updates, failed storage
/// calls) for `Client::on_event`. The sessions of one client share one. A new one has no listener, so warnings go
/// to stderr as one line each until one is set.
///
/// Experimental (`unstable-raw`): may change or go away in any release.
#[derive(Default)]
pub struct Events {
    listener: RwLock<Option<Listener>>,
    // Told when the main connection goes down (false) or comes back (true).
    link: RwLock<Option<LinkListener>>,
    // Dropped batches in the low half, the unrecoverable ones among them in the high half.
    dropped: AtomicU64,
    reconnected: AtomicBool,
    affected: Mutex<Vec<Affected>>,
    nested: Mutex<VecDeque<base::Updates>>,
    pub(crate) wake: Notify,
}

// Past this many unread batches the oldest is dropped, which asks for a getDifference.
const NESTED_LIMIT: usize = 64;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct Affected {
    pub(crate) channel_id: Option<i64>,
    pub(crate) pts: i32,
    pub(crate) pts_count: i32,
}

impl Affected {
    pub(crate) fn into_updates(self) -> base::Updates {
        let (pts, pts_count, messages) = (self.pts, self.pts_count, Vec::new());
        let update = match self.channel_id {
            Some(channel_id) => {
                let u = types::UpdateDeleteChannelMessages { channel_id, messages, pts, pts_count };
                base::Update::UpdateDeleteChannelMessages(Box::new(u))
            }
            None => {
                base::Update::UpdateDeleteMessages(Box::new(types::UpdateDeleteMessages { messages, pts, pts_count }))
            }
        };
        base::Updates::UpdateShort(Box::new(types::UpdateShort { update, date: 0 }))
    }
}

impl Events {
    pub(crate) fn listen(&self, listener: Listener) {
        *self.listener.write().unwrap() = Some(listener);
    }

    pub(crate) fn emit(&self, event: ClientEvent) {
        let listener = self.listener.read().unwrap().clone();
        if let Some(listener) = listener {
            call(&listener, event);
        }
    }

    /// For what the client can only report, not act on: the listener gets it, and with none set it is one line on
    /// stderr, so an app that never listens still sees it. Apart from the interactive login, the only place the
    /// crate writes to the terminal.
    pub(crate) fn warn(&self, event: ClientEvent) {
        let listener = self.listener.read().unwrap().clone();
        match listener {
            Some(listener) => call(&listener, event),
            None => eprintln!("vaegram: {}", describe(&event)),
        }
    }

    /// A failed storage call, as `warn` reports it; `message` says what was being done and why it failed.
    pub(crate) fn storage_failed(&self, kind: std::io::ErrorKind, message: impl std::fmt::Display) {
        self.warn(ClientEvent::StorageFailed { error: Arc::new(std::io::Error::new(kind, message.to_string())) });
    }

    pub(crate) fn on_link(&self, listener: LinkListener) {
        *self.link.write().unwrap() = Some(listener);
    }

    pub(crate) fn link(&self, up: bool) {
        let listener = self.link.read().unwrap().clone();
        if let Some(listener) = listener {
            let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| listener(up)));
        }
    }

    pub(crate) fn drop_updates(&self, updates: &base::Updates) {
        self.dropped.fetch_add(1 | (u64::from(unrecoverable(updates)) << 32), Ordering::AcqRel);
    }

    /// Dropped batches, and how many of those held updates getDifference can't bring back.
    pub(crate) fn take_dropped(&self) -> (u32, u32) {
        let dropped = self.dropped.swap(0, Ordering::AcqRel);
        (dropped as u32, (dropped >> 32) as u32)
    }

    pub(crate) fn reconnected(&self) {
        self.reconnected.store(true, Ordering::Release);
    }

    pub(crate) fn take_reconnected(&self) -> bool {
        self.reconnected.swap(false, Ordering::AcqRel)
    }

    pub(crate) fn affected(&self, a: Affected) {
        if a.pts_count == 0 {
            return;
        }
        let mut affected = self.affected.lock().unwrap();
        match affected.iter_mut().find(|e| e.channel_id == a.channel_id) {
            Some(e) if e.pts == a.pts.wrapping_sub(a.pts_count) => {
                (e.pts, e.pts_count) = (a.pts, e.pts_count.wrapping_add(a.pts_count));
            }
            Some(e) => *e = a,
            None => affected.push(a),
        }
        drop(affected);
        // As for nested updates: a waiting dispatcher takes it now, not with the next update.
        self.wake.notify_one();
    }

    pub(crate) fn take_affected(&self) -> Option<Affected> {
        self.affected.lock().unwrap().pop()
    }

    /// Updates that came inside another reply, to go the way the ones on the update stream go.
    pub(crate) fn nested(&self, updates: base::Updates) {
        let mut nested = self.nested.lock().unwrap();
        if nested.len() == NESTED_LIMIT {
            let lost = nested.pop_front().expect("a full queue has a front");
            self.drop_updates(&lost);
        }
        nested.push_back(updates);
        drop(nested);
        self.wake.notify_one();
    }

    pub(crate) fn take_nested(&self) -> Option<base::Updates> {
        self.nested.lock().unwrap().pop_front()
    }

    #[cfg(test)]
    pub(crate) fn record(&self) -> std::sync::mpsc::Receiver<ClientEvent> {
        let (tx, rx) = std::sync::mpsc::channel();
        self.listen(Arc::new(move |e| {
            let _ = tx.send(e);
        }));
        rx
    }

    #[cfg(test)]
    pub(crate) fn record_link(&self) -> std::sync::mpsc::Receiver<bool> {
        let (tx, rx) = std::sync::mpsc::channel();
        self.on_link(Arc::new(move |up| {
            let _ = tx.send(up);
        }));
        rx
    }
}

// A panicking listener would otherwise take the connection down with it; the panic hook still reports it.
fn call(listener: &Listener, event: ClientEvent) {
    let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| listener(event)));
}

/// What `warn` writes when nobody listens.
fn describe(event: &ClientEvent) -> String {
    match event {
        ClientEvent::HandlerFailed { error } => match error.chat_id {
            Some(chat) => format!("{:?} handler failed in chat {chat}: {}", error.kind, error.error),
            None => format!("{:?} handler failed: {}", error.kind, error.error),
        },
        ClientEvent::StorageFailed { error } => error.to_string(),
        other => format!("{other:?}"),
    }
}

// getDifference replays only what moved pts or qts.
fn unrecoverable(updates: &base::Updates) -> bool {
    let lost = |u: &base::Update| u.pts().is_none() && u.qts().is_none();
    match updates {
        base::Updates::UpdateShort(u) => lost(&u.update),
        base::Updates::Updates(u) => u.updates.iter().any(lost),
        base::Updates::UpdatesCombined(u) => u.updates.iter().any(lost),
        _ => false,
    }
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use super::{Affected, Events, NESTED_LIMIT, describe};
    use crate::enums::ClientEvent;
    use crate::errors::Error;
    use crate::handlers::{HandlerError, UpdateKind};
    use crate::raw::base;

    #[test]
    fn affected_pts_merge_per_box() {
        let events = Events::default();
        let a = |channel_id, pts, pts_count| Affected { channel_id, pts, pts_count };
        for affected in [a(None, 11, 1), a(None, 13, 2), a(Some(7), 5, 1), a(None, 20, 1), a(None, 21, 0)] {
            events.affected(affected);
        }
        assert_eq!(*events.affected.lock().unwrap(), [a(None, 20, 1), a(Some(7), 5, 1)]);
    }

    #[test]
    fn unread_nested_updates_are_capped_and_the_overflow_asks_for_a_difference() {
        let events = Events::default();
        for _ in 0..NESTED_LIMIT + 2 {
            events.nested(base::Updates::UpdatesTooLong);
        }
        assert_eq!(events.nested.lock().unwrap().len(), NESTED_LIMIT);
        assert_eq!(events.take_dropped(), (2, 0));
    }

    #[test]
    fn warn_goes_to_the_listener() {
        let events = Events::default();
        let got = events.record();
        events.warn(ClientEvent::Reconnected { dc: 2, attempt: 1 });
        events.storage_failed(std::io::ErrorKind::PermissionDenied, "failed to save the update state: disk full");
        let got: Vec<ClientEvent> = got.try_iter().collect();
        assert!(matches!(got[0], ClientEvent::Reconnected { dc: 2, attempt: 1 }), "{got:?}");
        let ClientEvent::StorageFailed { error } = &got[1] else { panic!("{got:?}") };
        assert_eq!(error.kind(), std::io::ErrorKind::PermissionDenied);
        assert_eq!(error.to_string(), "failed to save the update state: disk full");
    }

    #[test]
    fn unheard_warnings_are_described_in_one_line() {
        let failed = |chat_id| ClientEvent::HandlerFailed {
            error: Arc::new(HandlerError { kind: UpdateKind::Message, chat_id, error: Error::Timeout }),
        };
        let timeout = Error::Timeout.to_string();
        assert_eq!(describe(&failed(Some(5))), format!("Message handler failed in chat 5: {timeout}"));
        assert_eq!(describe(&failed(None)), format!("Message handler failed: {timeout}"));
        let error = Arc::new(std::io::Error::other("failed to close the storage engine"));
        let storage = ClientEvent::StorageFailed { error };
        assert_eq!(describe(&storage), "failed to close the storage engine");
    }
}