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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
use std::sync::Arc;
use super::SkipReason;
use crate::errors::Error;
use crate::handlers::{HandlerError, UpdateKind};
/// Something the client noticed that no request returns: reconnects, dropped packets, updates it couldn't parse
/// or deliver, failed handlers and storage calls. Receive them with [`Client::on_event`](crate::Client::on_event).
///
/// Errors are behind an [`Arc`], so an event clones cheaply, for example to send it to several channels.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum ClientEvent {
/// A connection to `dc` came back after `attempt` tries. When it's the main connection, updates missed
/// meanwhile are being fetched.
#[non_exhaustive]
Reconnected {
/// Id of the data center whose connection came back; file-transfer connections report theirs too.
dc: i32,
/// How many connection attempts it took, counting the one that worked; 1 means the first try.
attempt: u32,
},
/// A file-transfer connection to `dc` couldn't be opened. The transfer goes on over the connections that did;
/// only when none did does it fail, with one of the errors.
#[non_exhaustive]
ConnectFailed {
/// Id of the data center the connection was for.
dc: i32,
/// Why it couldn't be opened.
error: Arc<Error>,
},
/// A packet from Telegram, or one message of a container, was thrown away unread, and the connection carries on.
#[non_exhaustive]
PacketDropped {
/// Why: `"failed decryption or the MTProto checks"`, `"msg_id seen before, even or outside the time window"`
/// (the replay check; Telegram can also send a message again that was already taken in),
/// `"bad msg_container"`, `"msg_container holds a newer msg_id"` or `"bad gzip_packed"`.
reason: &'static str,
},
/// An update Telegram pushed couldn't be deserialized and was skipped. An unknown constructor is reported as
/// [`UnknownConstructor`](Self::UnknownConstructor) instead.
#[non_exhaustive]
UpdateParseFailed {
/// TL constructor id at the start of the update, or 0 when it's shorter than 4 bytes.
constructor_id: u32,
/// Length of the update in bytes.
len: usize,
},
/// An update Telegram pushed holds a TL constructor this build's schema doesn't know, usually from a newer
/// layer, and was skipped.
#[non_exhaustive]
UnknownConstructor {
/// The unknown constructor id; it can sit anywhere inside the update, not only at its start.
id: u32,
},
/// A handler or lifecycle hook returned `Err` and no [`on_error`](crate::Client::on_error) handler is set.
#[non_exhaustive]
HandlerFailed {
/// The error, with the route it came from and the chat, message, user and query of the update.
error: Arc<HandlerError>,
},
/// A handler, its filter, a raw handler or a lifecycle hook panicked. The panic is caught where it happened, so
/// update delivery carries on: a panicking handler stops the later groups for its update as an `Err` does, a
/// panicking filter counts as not matching, an [`ordered`] chat moves on to its next update and the handler's
/// [`max_concurrent_handlers`] slot is given back. [`on_error`](crate::Client::on_error) doesn't receive
/// panics, and the process's panic hook has already printed the panic by the time this is sent.
///
/// [`ordered`]: crate::ClientBuilder::ordered
/// [`max_concurrent_handlers`]: crate::ClientBuilder::max_concurrent_handlers
#[non_exhaustive]
HandlerPanicked {
/// The route of the handler that panicked, as in [`HandlerError::kind`].
kind: UpdateKind,
/// Bot-API style id of the update's chat, as in [`HandlerError::chat_id`].
chat_id: Option<i64>,
/// The panic's message when it is a `&str` or a `String`, as `panic!`, `unwrap` and `expect` give.
message: Option<String>,
},
/// Fetching missed updates (`updates.getDifference` or `updates.getChannelDifference`) failed. Updates it gave
/// up on, if any, follow as [`UpdatesSkipped`](Self::UpdatesSkipped).
#[non_exhaustive]
DifferenceFailed {
/// The error the fetch returned.
error: Arc<Error>,
},
/// Writing to the file given to `ClientBuilder::record` failed; the message is missing from the recording.
#[non_exhaustive]
RecordingFailed {
/// The I/O error from the recording file.
error: Arc<std::io::Error>,
},
/// A call to the storage engine failed and `error` says which. The client carries on: a lookup falls back to
/// asking Telegram, and a save that failed is tried again with the next one. This can fire on the engine's own
/// thread.
#[non_exhaustive]
StorageFailed {
/// The engine's error; its message names the call that failed.
error: Arc<std::io::Error>,
},
/// The handlers fell behind and `count` batches of updates didn't fit in the queue. Updates that move pts or
/// qts are fetched again; `unrecoverable` of the batches also held others (callback queries, typing, ...) that
/// are gone. More `max_concurrent_handlers` or faster handlers keep it at 0.
#[non_exhaustive]
UpdatesDropped {
/// Batches dropped since the last report.
count: u32,
/// How many of those batches held updates a fetch can't bring back. Never more than `count`.
unrecoverable: u32,
},
/// The updates with pts `from..to` of a channel (`chat_id`) or of the account (`None`) will never be
/// delivered. `from == to` when the fetch stopped before Telegram said how many there were, or when there was
/// nothing to fetch from ([`SkipReason::NoPts`]: no fetch was made). A report for the account also stands for
/// its qts updates (participant changes, join requests, a bot being stopped, ...), whose own numbers it doesn't
/// give: `from..to` are pts. Of those, the ones held behind a missing one went out past it. The ones dropped
/// because too many were held stay ahead of the stored qts and come with the account's next fetch: a later gap,
/// the idle fetch, a reconnect, [`recover_gaps`](crate::Client::recover_gaps), or the next start with
/// [`catch_up`](crate::ClientBuilder::catch_up). Nothing schedules one for them.
#[non_exhaustive]
UpdatesSkipped {
/// Bot-API style id of the channel (`-100…`), or `None` for the account's own message box (private chats
/// and basic groups).
chat_id: Option<i64>,
/// Start of the gap: the last pts the client had, or 0 when it had none ([`SkipReason::NoPts`]).
from: i32,
/// End of the gap: the pts the next delivered update builds on. Equal to `from` when it isn't known.
to: i32,
/// Why the updates were given up on.
reason: SkipReason,
},
}