toptl 0.1.0

Official Rust SDK for the TOP.TL Telegram directory API — post stats, check votes, manage vote webhooks.
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

use std::sync::Arc;
use tokio::sync::Mutex;
use tokio::task::JoinHandle;
use tokio::time::{self, Duration};

use crate::client::TopTL;
use crate::types::StatsPayload;

/// Callback that produces the current stats to post. Invoked on every
/// autoposter tick.
pub type StatsCallback = Arc<dyn Fn() -> StatsPayload + Send + Sync>;

/// Background task that calls [`TopTL::post_stats`] on an interval.
///
/// # Example
///
/// ```no_run
/// use std::sync::Arc;
/// use std::time::Duration;
/// use toptl::{StatsPayload, TopTL};
/// use toptl::autoposter::Autoposter;
///
/// #[tokio::main]
/// async fn main() {
///     let client = TopTL::new("toptl_xxx");
///
///     let autoposter = Autoposter::new(client, "mybot")
///         .interval(Duration::from_secs(30 * 60))
///         .callback(Arc::new(|| StatsPayload {
///             member_count: Some(5_000),
///             group_count: Some(1_200),
///             channel_count: Some(300),
///             bot_serves: None,
///         }))
///         .start();
///
///     // autoposter.stop().await;
/// }
/// ```
pub struct Autoposter {
    client: TopTL,
    username: String,
    interval: Duration,
    callback: Option<StatsCallback>,
    handle: Option<JoinHandle<()>>,
    running: Arc<Mutex<bool>>,
}

impl Autoposter {
    pub fn new(client: TopTL, username: impl Into<String>) -> Self {
        Self {
            client,
            username: username.into(),
            interval: Duration::from_secs(1800), // 30 min
            callback: None,
            handle: None,
            running: Arc::new(Mutex::new(false)),
        }
    }

    pub fn interval(mut self, interval: Duration) -> Self {
        self.interval = interval;
        self
    }

    pub fn callback(mut self, cb: StatsCallback) -> Self {
        self.callback = Some(cb);
        self
    }

    /// Start the background task. Panics if no callback is set.
    pub fn start(mut self) -> Self {
        let callback = self
            .callback
            .clone()
            .expect("A stats callback must be set before starting the autoposter");

        let client = self.client.clone();
        let username = self.username.clone();
        let interval = self.interval;
        let running = self.running.clone();

        let handle = tokio::spawn(async move {
            *running.lock().await = true;
            let mut ticker = time::interval(interval);
            loop {
                ticker.tick().await;
                if !*running.lock().await {
                    break;
                }
                let stats = (callback)();
                if let Err(e) = client.post_stats(&username, &stats).await {
                    // Keep going — transient errors (network, 5xx) shouldn't
                    // kill the loop. Consumers can log their own way via the
                    // `log` / `tracing` crate by wrapping post_stats themselves.
                    eprintln!("[toptl::autoposter] post_stats failed: {e}");
                }
            }
        });

        self.handle = Some(handle);
        self
    }

    pub async fn stop(self) {
        *self.running.lock().await = false;
        if let Some(handle) = self.handle {
            handle.abort();
            let _ = handle.await;
        }
    }
}