grammers_client/client/
client.rs

1// Copyright 2020 - developers of the `grammers` project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8use std::sync::Arc;
9
10use grammers_mtsender::SenderPoolHandle;
11use grammers_session::Session;
12
13/// Configuration that controls the [`Client`] behaviour when making requests.
14///
15/// [`Client`]: struct.Client.html
16pub struct ClientConfiguration {
17    /// The threshold below which the library should automatically sleep on flood-wait and slow
18    /// mode wait errors (inclusive). For instance, if an
19    /// `RpcError { name: "FLOOD_WAIT", value: Some(17) }` (flood, must wait 17 seconds) occurs
20    /// and `flood_sleep_threshold` is 20 (seconds), the library will `sleep` automatically for
21    /// 17 seconds. If the error was for 21s, it would propagate the error instead.
22    ///
23    /// By default, the library will sleep on flood-waits below or equal to one minute (60
24    /// seconds), but this can be disabled by passing `0` (since all flood errors would be
25    /// higher and exceed the threshold).
26    ///
27    /// On flood, the library will retry *once*. If the flood error occurs a second time after
28    /// sleeping, the error will be returned.
29    pub flood_sleep_threshold: u32,
30}
31
32pub struct UpdatesConfiguration {
33    /// Should the client catch-up on updates sent to it while it was offline?
34    ///
35    /// By default, updates sent while the client was offline are ignored.
36    pub catch_up: bool,
37
38    /// How many updates may be buffered by the client at any given time.
39    ///
40    /// Telegram passively sends updates to the client through the open connection, so they must
41    /// be buffered until the application has the capacity to consume them.
42    ///
43    /// Upon reaching this limit, updates will be dropped, and a warning log message will be
44    /// emitted (but not too often, to avoid spamming the log), in order to let the developer
45    /// know that they should either change how they handle updates or increase the limit.
46    ///
47    /// A limit of zero (`0`) indicates that updates should not be buffered. They will be
48    /// immediately dropped, and no warning will ever be emitted.
49    ///
50    /// A limit of `None` disables the upper bound for the buffer. This is not recommended, as it
51    /// could eventually lead to memory exhaustion. This option will also not emit any warnings.
52    ///
53    /// The default limit, which may change at any time, should be enough for user accounts,
54    /// although bot accounts may need to increase the limit depending on their capacity.
55    ///
56    /// When the limit is `Some`, a buffer to hold that many updates will be pre-allocated.
57    pub update_queue_limit: Option<usize>,
58}
59
60pub(crate) struct ClientInner {
61    pub(crate) session: Arc<dyn Session>,
62    pub(crate) api_id: i32,
63    pub(crate) handle: SenderPoolHandle,
64    pub(crate) configuration: ClientConfiguration,
65    pub(crate) auth_copied_to_dcs: tokio::sync::Mutex<Vec<i32>>,
66}
67
68/// A client capable of connecting to Telegram and invoking requests.
69///
70/// This structure is the "entry point" of the library, from which you can start using the rest.
71///
72/// This structure owns all the necessary connections to Telegram, and has implementations for the
73/// most basic methods, such as connecting, signing in, or processing network events.
74///
75/// On drop, all state is synchronized to the session. The [`Session`] must be explicitly saved
76/// to disk with its corresponding save method for persistence.
77///
78/// [`Session`]: grammers_session::Session
79#[derive(Clone)]
80pub struct Client(pub(crate) Arc<ClientInner>);
81
82impl Default for ClientConfiguration {
83    fn default() -> Self {
84        Self {
85            flood_sleep_threshold: 60,
86        }
87    }
88}
89
90impl Default for UpdatesConfiguration {
91    fn default() -> Self {
92        Self {
93            catch_up: false,
94            update_queue_limit: Some(100),
95        }
96    }
97}
grammers_client/client/client.rs

grammers_client/client/
client.rs
