Skip to main content

aiogram/
bot.rs

1use std::collections::{BTreeMap, BTreeSet};
2use std::fmt;
3use std::hash::{Hash, Hasher};
4use std::sync::Arc;
5use std::time::Duration;
6
7use futures_util::StreamExt;
8use serde::Serialize;
9use serde::de::DeserializeOwned;
10use tokio::io::{AsyncWrite, AsyncWriteExt};
11use tokio::sync::OnceCell;
12use tokio_util::io::ReaderStream;
13
14use crate::client::{
15    BotRequest, DefaultBotProperties, RequestMiddleware, RequestNext, TelegramApiServer,
16};
17use crate::error::{Error, Result};
18use crate::methods::{
19    AnswerCallbackQuery, GetFile, GetMe, GetUpdates, SendCopyMethod, SendMessage, TelegramMethod,
20    TelegramResponse,
21};
22use crate::types::{
23    ChatId, Downloadable, File, InputFileContent, InputFileUpload, Message, Update, User,
24};
25
26const DEFAULT_PROPERTY_FIELDS: [&str; 6] = [
27    "parse_mode",
28    "disable_notification",
29    "protect_content",
30    "allow_sending_without_reply",
31    "link_preview_options",
32    "show_caption_above_media",
33];
34
35mod generated;
36pub use generated::GENERATED_BOT_SHORTCUT_COUNT;
37
38struct Inner {
39    token: String,
40    id: i64,
41    api_server: TelegramApiServer,
42    client: reqwest::Client,
43    defaults: DefaultBotProperties,
44    request_middlewares: Arc<Vec<Arc<dyn RequestMiddleware>>>,
45    me: OnceCell<User>,
46}
47
48/// Cloneable asynchronous Telegram Bot API client.
49#[derive(Clone)]
50pub struct Bot {
51    inner: Arc<Inner>,
52}
53
54impl PartialEq for Bot {
55    fn eq(&self, other: &Self) -> bool {
56        self.inner.token == other.inner.token
57    }
58}
59
60impl Eq for Bot {}
61
62impl Hash for Bot {
63    fn hash<H: Hasher>(&self, state: &mut H) {
64        self.inner.token.hash(state);
65    }
66}
67
68impl fmt::Debug for Bot {
69    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
70        formatter
71            .debug_struct("Bot")
72            .field("token", &"<redacted>")
73            .field("api_server", &self.inner.api_server)
74            .finish()
75    }
76}
77
78impl Bot {
79    pub fn new(token: impl Into<String>) -> Result<Self> {
80        Self::builder(token).build()
81    }
82
83    /// Creates a bot against a custom Bot API server or a local test server.
84    pub fn with_api_base(token: impl Into<String>, api_base: impl Into<String>) -> Result<Self> {
85        Self::builder(token).api_base(api_base).build()
86    }
87
88    pub fn with_api_server(token: impl Into<String>, server: TelegramApiServer) -> Result<Self> {
89        Self::builder(token).api_server(server).build()
90    }
91
92    pub fn builder(token: impl Into<String>) -> BotBuilder {
93        BotBuilder {
94            token: token.into(),
95            api_server: TelegramApiServer::production(),
96            defaults: DefaultBotProperties::default(),
97            client: None,
98            request_middlewares: Vec::new(),
99        }
100    }
101
102    pub fn default_properties(&self) -> &DefaultBotProperties {
103        &self.inner.defaults
104    }
105
106    pub fn id(&self) -> i64 {
107        self.inner.id
108    }
109
110    pub fn token(&self) -> &str {
111        &self.inner.token
112    }
113
114    pub fn api_server(&self) -> &TelegramApiServer {
115        &self.inner.api_server
116    }
117
118    pub async fn execute<M: TelegramMethod>(&self, method: &M) -> Result<M::Response> {
119        let request = self.prepare_request(method)?;
120        let response = self.dispatch_request(request).await?;
121        serde_json::from_value(response.clone()).map_err(|error| Error::ClientDecode {
122            method: M::NAME.to_owned(),
123            reason: error.to_string(),
124            data: response.to_string(),
125        })
126    }
127
128    /// Executes a method without applying any [`DefaultBotProperties`].
129    pub async fn execute_without_defaults<M: TelegramMethod>(
130        &self,
131        method: &M,
132    ) -> Result<M::Response> {
133        let request = self.prepare_request_suppressing_defaults(method, DEFAULT_PROPERTY_FIELDS)?;
134        let response = self.dispatch_request(request).await?;
135        serde_json::from_value(response.clone()).map_err(|error| Error::ClientDecode {
136            method: M::NAME.to_owned(),
137            reason: error.to_string(),
138            data: response.to_string(),
139        })
140    }
141
142    /// Suppresses selected client defaults only when the method did not set an
143    /// explicit value for the same field.
144    pub async fn execute_suppressing_defaults<M, I, S>(
145        &self,
146        method: &M,
147        fields: I,
148    ) -> Result<M::Response>
149    where
150        M: TelegramMethod,
151        I: IntoIterator<Item = S>,
152        S: AsRef<str>,
153    {
154        let request = self.prepare_request_suppressing_defaults(method, fields)?;
155        let response = self.dispatch_request(request).await?;
156        serde_json::from_value(response.clone()).map_err(|error| Error::ClientDecode {
157            method: M::NAME.to_owned(),
158            reason: error.to_string(),
159            data: response.to_string(),
160        })
161    }
162
163    pub async fn execute_with_timeout<M: TelegramMethod>(
164        &self,
165        method: &M,
166        timeout: Duration,
167    ) -> Result<M::Response> {
168        match tokio::time::timeout(timeout, self.execute(method)).await {
169            Ok(result) => result,
170            Err(_) => Err(Error::RequestTimeout {
171                method: M::NAME.to_owned(),
172                timeout,
173            }),
174        }
175    }
176
177    /// Serializes a typed method, applies this bot's defaults, discovers file
178    /// uploads and returns the exact request passed to client middleware.
179    pub fn prepare_request<M: TelegramMethod>(&self, method: &M) -> Result<BotRequest> {
180        let mut payload = serde_json::to_value(method)?;
181        self.inner
182            .defaults
183            .apply(M::DEFAULT_PROPERTIES, &mut payload)?;
184        Ok(BotRequest::new(
185            M::NAME,
186            payload,
187            deduplicate_files(method.files())?,
188        ))
189    }
190
191    fn prepare_request_suppressing_defaults<M, I, S>(
192        &self,
193        method: &M,
194        fields: I,
195    ) -> Result<BotRequest>
196    where
197        M: TelegramMethod,
198        I: IntoIterator<Item = S>,
199        S: AsRef<str>,
200    {
201        let mut payload = serde_json::to_value(method)?;
202        let object = payload.as_object_mut().ok_or_else(|| {
203            Error::InvalidPayload("Telegram method payload must be an object".to_owned())
204        })?;
205        let fields: BTreeSet<String> = fields
206            .into_iter()
207            .map(|field| field.as_ref().to_owned())
208            .collect();
209        for &(wire_field, property) in M::DEFAULT_PROPERTIES {
210            if (fields.contains(wire_field) || fields.contains(property))
211                && !object.contains_key(wire_field)
212            {
213                object.insert(wire_field.to_owned(), serde_json::Value::Null);
214            }
215        }
216        self.inner
217            .defaults
218            .apply(M::DEFAULT_PROPERTIES, &mut payload)?;
219        Ok(BotRequest::new(
220            M::NAME,
221            payload,
222            deduplicate_files(method.files())?,
223        ))
224    }
225
226    /// Executes any Telegram method with a serializable payload.
227    ///
228    /// This is the forward-compatibility escape hatch for Bot API methods that
229    /// are newer than the schema pinned by this crate.
230    pub async fn request<T, R>(&self, method_name: &str, payload: &T) -> Result<R>
231    where
232        T: Serialize + ?Sized,
233        R: DeserializeOwned,
234    {
235        let payload = serde_json::to_value(payload)?;
236        let response = self
237            .dispatch_request(BotRequest::new(method_name, payload, Vec::new()))
238            .await?;
239        serde_json::from_value(response.clone()).map_err(|error| Error::ClientDecode {
240            method: method_name.to_owned(),
241            reason: error.to_string(),
242            data: response.to_string(),
243        })
244    }
245
246    async fn dispatch_request(&self, request: BotRequest) -> Result<serde_json::Value> {
247        RequestNext::new(self.inner.request_middlewares.clone())
248            .run(self.clone(), request)
249            .await
250    }
251
252    pub(crate) async fn send_request(&self, request: BotRequest) -> Result<serde_json::Value> {
253        if request.files.is_empty() {
254            self.request_value(&request.method_name, &request.payload)
255                .await
256        } else {
257            self.request_multipart(&request.method_name, &request.payload, request.files)
258                .await
259        }
260    }
261
262    async fn request_value(
263        &self,
264        method_name: &str,
265        payload: &serde_json::Value,
266    ) -> Result<serde_json::Value> {
267        let url = self
268            .inner
269            .api_server
270            .api_url(&self.inner.token, method_name);
271        let response = self.inner.client.post(url).json(payload).send().await?;
272        self.decode_response(method_name, response).await
273    }
274
275    async fn request_multipart(
276        &self,
277        method_name: &str,
278        payload: &serde_json::Value,
279        files: Vec<InputFileUpload>,
280    ) -> Result<serde_json::Value> {
281        let object = payload.as_object().ok_or_else(|| {
282            Error::InvalidPayload("Telegram method payload must be an object".to_owned())
283        })?;
284        let mut form = reqwest::multipart::Form::new();
285        for (name, value) in object {
286            if value.is_null() {
287                continue;
288            }
289            let text = match value {
290                serde_json::Value::String(value) => value.clone(),
291                serde_json::Value::Bool(_) | serde_json::Value::Number(_) => value.to_string(),
292                _ => serde_json::to_string(value)?,
293            };
294            form = form.text(name.clone(), text);
295        }
296        for file in files {
297            let part = match file.content {
298                InputFileContent::Bytes(data) => {
299                    reqwest::multipart::Part::bytes(data.as_ref().to_vec())
300                }
301                InputFileContent::Path(path) => {
302                    let file = tokio::fs::File::open(&path).await?;
303                    let length = file.metadata().await?.len();
304                    reqwest::multipart::Part::stream_with_length(
305                        reqwest::Body::wrap_stream(ReaderStream::new(file)),
306                        length,
307                    )
308                }
309                InputFileContent::Url {
310                    url,
311                    headers,
312                    timeout,
313                } => {
314                    let mut request = self.inner.client.get(url).timeout(timeout);
315                    for (name, value) in headers {
316                        request = request.header(name, value);
317                    }
318                    let response = request.send().await?.error_for_status()?;
319                    match response.content_length() {
320                        Some(length) => reqwest::multipart::Part::stream_with_length(
321                            reqwest::Body::wrap_stream(response.bytes_stream()),
322                            length,
323                        ),
324                        None => reqwest::multipart::Part::stream(reqwest::Body::wrap_stream(
325                            response.bytes_stream(),
326                        )),
327                    }
328                }
329            }
330            .file_name(file.file_name);
331            form = form.part(file.attachment_name, part);
332        }
333
334        let url = self
335            .inner
336            .api_server
337            .api_url(&self.inner.token, method_name);
338        let response = self.inner.client.post(url).multipart(form).send().await?;
339        self.decode_response(method_name, response).await
340    }
341
342    pub(crate) async fn load_input_file(&self, content: InputFileContent) -> Result<Vec<u8>> {
343        match content {
344            InputFileContent::Bytes(data) => Ok(data.as_ref().to_vec()),
345            InputFileContent::Path(path) => Ok(tokio::fs::read(path).await?),
346            InputFileContent::Url {
347                url,
348                headers,
349                timeout,
350            } => {
351                let mut request = self.inner.client.get(url).timeout(timeout);
352                for (name, value) in headers {
353                    request = request.header(name, value);
354                }
355                Ok(request
356                    .send()
357                    .await?
358                    .error_for_status()?
359                    .bytes()
360                    .await?
361                    .to_vec())
362            }
363        }
364    }
365
366    async fn decode_response<R: DeserializeOwned>(
367        &self,
368        method_name: &str,
369        response: reqwest::Response,
370    ) -> Result<R> {
371        let status = response.status();
372        let content = response.text().await?;
373        let body: TelegramResponse<R> =
374            serde_json::from_str(&content).map_err(|error| Error::ClientDecode {
375                method: method_name.to_owned(),
376                reason: error.to_string(),
377                data: content,
378            })?;
379
380        if (200..=226).contains(&status.as_u16()) && body.ok {
381            return body.result.ok_or_else(|| Error::Telegram {
382                method: method_name.to_owned(),
383                error_code: status.as_u16(),
384                description: "successful Telegram response did not contain result".to_owned(),
385                parameters: body.parameters,
386            });
387        }
388
389        let description = body.description.unwrap_or_else(|| status.to_string());
390        if let Some(retry_after) = body.parameters.as_ref().and_then(|p| p.retry_after) {
391            return Err(Error::RetryAfter {
392                method: method_name.to_owned(),
393                retry_after: Duration::from_secs(retry_after),
394                description,
395            });
396        }
397        if let Some(migrate_to_chat_id) = body
398            .parameters
399            .as_ref()
400            .and_then(|parameters| parameters.migrate_to_chat_id)
401        {
402            return Err(Error::MigrateToChat {
403                method: method_name.to_owned(),
404                migrate_to_chat_id,
405                description,
406            });
407        }
408
409        let method = method_name.to_owned();
410        match status.as_u16() {
411            400 => {
412                return Err(Error::BadRequest {
413                    method,
414                    description,
415                });
416            }
417            401 => {
418                return Err(Error::Unauthorized {
419                    method,
420                    description,
421                });
422            }
423            403 => {
424                return Err(Error::Forbidden {
425                    method,
426                    description,
427                });
428            }
429            404 => {
430                return Err(Error::NotFound {
431                    method,
432                    description,
433                });
434            }
435            409 => {
436                return Err(Error::Conflict {
437                    method,
438                    description,
439                });
440            }
441            413 => {
442                return Err(Error::EntityTooLarge {
443                    method,
444                    description,
445                });
446            }
447            500..=599 if description.contains("restart") => {
448                return Err(Error::Restarting {
449                    method,
450                    description,
451                });
452            }
453            500..=599 => {
454                return Err(Error::Server {
455                    method,
456                    description,
457                });
458            }
459            _ => {}
460        }
461
462        Err(Error::Telegram {
463            method,
464            error_code: body.error_code.unwrap_or(status.as_u16()),
465            description,
466            parameters: body.parameters,
467        })
468    }
469
470    pub async fn get_me(&self) -> Result<User> {
471        self.inner
472            .me
473            .get_or_try_init(|| async { self.execute(&GetMe::default()).await })
474            .await
475            .cloned()
476    }
477
478    pub async fn get_updates(&self, method: GetUpdates) -> Result<Vec<Update>> {
479        self.execute(&method).await
480    }
481
482    pub async fn get_file(&self, file_id: impl Into<String>) -> Result<File> {
483        self.execute(&GetFile::new(file_id)).await
484    }
485
486    /// Downloads a file using a path returned by Telegram's `getFile` method.
487    pub async fn download_file(&self, file_path: &str) -> Result<Vec<u8>> {
488        if self.inner.api_server.is_local {
489            return Ok(tokio::fs::read(self.inner.api_server.to_local(file_path)?).await?);
490        }
491        let url = self.inner.api_server.file_url(&self.inner.token, file_path);
492        let response = self
493            .inner
494            .client
495            .get(url)
496            .send()
497            .await?
498            .error_for_status()?;
499        Ok(response.bytes().await?.to_vec())
500    }
501
502    /// Downloads any Telegram object with a `file_id`, resolving its current
503    /// file path through `getFile` first, like aiogram's `Bot.download`.
504    pub async fn download<D: Downloadable + ?Sized>(&self, file: &D) -> Result<Vec<u8>> {
505        self.download_by_id(file.file_id()).await
506    }
507
508    pub async fn download_by_id(&self, file_id: &str) -> Result<Vec<u8>> {
509        let file = self.get_file(file_id).await?;
510        self.download_descriptor(&file).await
511    }
512
513    /// Downloads a previously resolved Telegram `File` descriptor.
514    pub async fn download_descriptor(&self, file: &File) -> Result<Vec<u8>> {
515        let path = file.file_path.as_deref().ok_or_else(|| {
516            Error::InvalidPayload("Telegram File does not contain file_path".to_owned())
517        })?;
518        self.download_file(path).await
519    }
520
521    pub async fn download_to<D, W>(&self, file: &D, writer: &mut W) -> Result<u64>
522    where
523        D: Downloadable + ?Sized,
524        W: AsyncWrite + Unpin + Send,
525    {
526        let file = self.get_file(file.file_id()).await?;
527        let path = file.file_path.as_deref().ok_or_else(|| {
528            Error::InvalidPayload("Telegram File does not contain file_path".to_owned())
529        })?;
530        self.download_file_to(path, writer).await
531    }
532
533    pub async fn download_file_to<W>(&self, file_path: &str, writer: &mut W) -> Result<u64>
534    where
535        W: AsyncWrite + Unpin + Send,
536    {
537        if self.inner.api_server.is_local {
538            let mut file =
539                tokio::fs::File::open(self.inner.api_server.to_local(file_path)?).await?;
540            return Ok(tokio::io::copy(&mut file, writer).await?);
541        }
542        let url = self.inner.api_server.file_url(&self.inner.token, file_path);
543        let response = self
544            .inner
545            .client
546            .get(url)
547            .send()
548            .await?
549            .error_for_status()?;
550        let mut stream = response.bytes_stream();
551        let mut written = 0_u64;
552        while let Some(chunk) = stream.next().await {
553            let chunk = chunk?;
554            writer.write_all(&chunk).await?;
555            written += chunk.len() as u64;
556        }
557        Ok(written)
558    }
559
560    pub async fn send_message(
561        &self,
562        chat_id: impl Into<ChatId>,
563        text: impl Into<String>,
564    ) -> Result<Message> {
565        self.execute(&SendMessage::new(chat_id, text)).await
566    }
567
568    /// Executes the concrete request selected by [`Message::send_copy`](crate::types::Message::send_copy).
569    pub async fn execute_send_copy(&self, method: &SendCopyMethod) -> Result<Message> {
570        match method {
571            SendCopyMethod::ForwardMessage(method) => self.execute(method).await,
572            SendCopyMethod::SendAnimation(method) => self.execute(method).await,
573            SendCopyMethod::SendAudio(method) => self.execute(method).await,
574            SendCopyMethod::SendContact(method) => self.execute(method).await,
575            SendCopyMethod::SendDocument(method) => self.execute(method).await,
576            SendCopyMethod::SendLocation(method) => self.execute(method).await,
577            SendCopyMethod::SendMessage(method) => self.execute(method).await,
578            SendCopyMethod::SendPhoto(method) => self.execute(method).await,
579            SendCopyMethod::SendPoll(method) => self.execute(method).await,
580            SendCopyMethod::SendDice(method) => self.execute(method).await,
581            SendCopyMethod::SendSticker(method) => self.execute(method).await,
582            SendCopyMethod::SendVenue(method) => self.execute(method).await,
583            SendCopyMethod::SendVideo(method) => self.execute(method).await,
584            SendCopyMethod::SendVideoNote(method) => self.execute(method).await,
585            SendCopyMethod::SendVoice(method) => self.execute(method).await,
586        }
587    }
588
589    pub async fn answer_callback_query(
590        &self,
591        callback_query_id: impl Into<String>,
592    ) -> Result<bool> {
593        self.execute(&AnswerCallbackQuery::new(callback_query_id))
594            .await
595    }
596}
597
598/// Configures a [`Bot`] with a custom API base and aiogram-style defaults.
599pub struct BotBuilder {
600    token: String,
601    api_server: TelegramApiServer,
602    defaults: DefaultBotProperties,
603    client: Option<reqwest::Client>,
604    request_middlewares: Vec<Arc<dyn RequestMiddleware>>,
605}
606
607impl BotBuilder {
608    pub fn api_base(mut self, value: impl Into<String>) -> Self {
609        self.api_server = TelegramApiServer::from_base(value.into());
610        self
611    }
612
613    pub fn api_server(mut self, value: TelegramApiServer) -> Self {
614        self.api_server = value;
615        self
616    }
617
618    pub fn defaults(mut self, value: DefaultBotProperties) -> Self {
619        self.defaults = value;
620        self
621    }
622
623    /// Uses a preconfigured reqwest client (proxy, timeout, connector, etc.).
624    pub fn client(mut self, value: reqwest::Client) -> Self {
625        self.client = Some(value);
626        self
627    }
628
629    pub fn request_middleware(mut self, value: impl RequestMiddleware + 'static) -> Self {
630        self.request_middlewares.push(Arc::new(value));
631        self
632    }
633
634    pub fn build(self) -> Result<Bot> {
635        validate_token(&self.token)?;
636        let id = crate::utils::token::extract_bot_id(&self.token)?;
637        let client = match self.client {
638            Some(client) => client,
639            None => reqwest::Client::builder()
640                .user_agent(concat!("aiogram-rust/", env!("CARGO_PKG_VERSION")))
641                .build()?,
642        };
643        Ok(Bot {
644            inner: Arc::new(Inner {
645                token: self.token,
646                id,
647                api_server: self.api_server,
648                client,
649                defaults: self.defaults,
650                request_middlewares: Arc::new(self.request_middlewares),
651                me: OnceCell::new(),
652            }),
653        })
654    }
655}
656
657fn validate_token(token: &str) -> Result<()> {
658    crate::utils::token::validate(token)
659}
660
661fn deduplicate_files(files: Vec<InputFileUpload>) -> Result<Vec<InputFileUpload>> {
662    let mut unique = BTreeMap::<String, InputFileUpload>::new();
663    for file in files {
664        match unique.get(&file.attachment_name) {
665            Some(existing) if existing == &file => {}
666            Some(_) => {
667                return Err(Error::InvalidPayload(format!(
668                    "multipart attachment name {:?} refers to different files",
669                    file.attachment_name
670                )));
671            }
672            None => {
673                unique.insert(file.attachment_name.clone(), file);
674            }
675        }
676    }
677    Ok(unique.into_values().collect())
678}
679
680#[cfg(test)]
681mod tests {
682    use std::sync::atomic::{AtomicUsize, Ordering};
683
684    use super::*;
685    use crate::methods::{SendDocument, SendPhoto};
686    use crate::types::InputFile;
687    use tokio::io::{AsyncReadExt, AsyncWriteExt};
688    use tokio::net::TcpListener;
689
690    #[test]
691    fn rejects_invalid_token() {
692        assert!(matches!(
693            Bot::new("not-a-token"),
694            Err(Error::InvalidToken(_))
695        ));
696    }
697
698    #[test]
699    fn generated_shortcuts_cover_non_core_bot_api_methods() {
700        assert_eq!(GENERATED_BOT_SHORTCUT_COUNT, 180);
701    }
702
703    #[test]
704    fn rejects_conflicting_multipart_attachment_names() {
705        let bot = bot_for_tests();
706        let method = SendDocument::new(
707            3_i64,
708            InputFile::named_bytes("same", "document.txt", b"DOCUMENT".to_vec()),
709        )
710        .thumbnail(InputFile::named_bytes(
711            "same",
712            "thumbnail.jpg",
713            b"THUMBNAIL".to_vec(),
714        ));
715        assert!(matches!(
716            bot.prepare_request(&method),
717            Err(Error::InvalidPayload(message)) if message.contains("same")
718        ));
719    }
720
721    #[test]
722    fn debug_never_exposes_token() {
723        let token = "123456:abcdefghijklmnopqrstuvwxyzABCDE";
724        let bot = Bot::new(token).unwrap();
725        let output = format!("{bot:?}");
726        assert!(!output.contains(token));
727        assert!(output.contains("<redacted>"));
728    }
729
730    #[test]
731    fn equality_and_hash_follow_the_bot_token() {
732        use std::collections::hash_map::DefaultHasher;
733        use std::hash::{Hash, Hasher};
734
735        fn hash(bot: &Bot) -> u64 {
736            let mut hasher = DefaultHasher::new();
737            bot.hash(&mut hasher);
738            hasher.finish()
739        }
740
741        let production = Bot::new("42:secret").unwrap();
742        let custom_server = Bot::with_api_base("42:secret", "http://localhost:8081").unwrap();
743        let other = Bot::new("43:secret").unwrap();
744
745        assert_eq!(production, custom_server);
746        assert_ne!(production, other);
747        assert_eq!(hash(&production), hash(&custom_server));
748        assert_ne!(hash(&production), hash(&other));
749    }
750
751    #[test]
752    fn send_copy_explicit_none_suppresses_bot_defaults() {
753        let bot = Bot::builder("123456:abcdefghijklmnopqrstuvwxyzABCDE")
754            .defaults(
755                DefaultBotProperties::default()
756                    .parse_mode("HTML")
757                    .disable_notification(true)
758                    .allow_sending_without_reply(true)
759                    .link_preview_is_disabled(true),
760            )
761            .build()
762            .unwrap();
763        let message: Message = serde_json::from_value(serde_json::json!({
764            "message_id": 7,
765            "date": 1_700_000_000,
766            "chat": {"id": 10, "type": "private"},
767            "text": "already formatted",
768            "entities": [{"type":"bold","offset":0,"length":7}]
769        }))
770        .unwrap();
771        let method = message.send_copy(42_i64).unwrap();
772        let SendCopyMethod::SendMessage(method) = method else {
773            panic!("text copy must select SendMessage");
774        };
775        let payload = bot.prepare_request(&method).unwrap().payload;
776        assert!(payload.get("parse_mode").is_none());
777        assert!(payload.get("disable_notification").is_none());
778        assert!(payload.get("allow_sending_without_reply").is_none());
779        assert!(payload.get("link_preview_options").is_none());
780        assert_eq!(payload["entities"][0]["type"], "bold");
781    }
782
783    fn bot_for_tests() -> Bot {
784        Bot::new("123456:abcdefghijklmnopqrstuvwxyzABCDE").unwrap()
785    }
786
787    async fn mock_server(
788        response_status: &str,
789        response_json: &'static str,
790    ) -> (String, tokio::task::JoinHandle<String>) {
791        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
792        let address = listener.local_addr().unwrap();
793        let status = response_status.to_owned();
794        let task = tokio::spawn(async move {
795            let (mut socket, _) = listener.accept().await.unwrap();
796            let mut request = Vec::new();
797            let mut buffer = [0_u8; 8192];
798            let mut expected_len = None;
799            loop {
800                let read = socket.read(&mut buffer).await.unwrap();
801                if read == 0 {
802                    break;
803                }
804                request.extend_from_slice(&buffer[..read]);
805                if expected_len.is_none()
806                    && let Some(header_end) =
807                        request.windows(4).position(|part| part == b"\r\n\r\n")
808                {
809                    let headers = String::from_utf8_lossy(&request[..header_end]);
810                    let content_length = headers
811                        .lines()
812                        .find_map(|line| {
813                            let (name, value) = line.split_once(':')?;
814                            name.eq_ignore_ascii_case("content-length")
815                                .then(|| value.trim().parse::<usize>().ok())
816                                .flatten()
817                        })
818                        .unwrap_or(0);
819                    expected_len = Some(header_end + 4 + content_length);
820                }
821                if expected_len.is_some_and(|length| request.len() >= length) {
822                    break;
823                }
824            }
825            let response = format!(
826                "HTTP/1.1 {status}\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{response_json}",
827                response_json.len()
828            );
829            socket.write_all(response.as_bytes()).await.unwrap();
830            String::from_utf8_lossy(&request).into_owned()
831        });
832        (format!("http://{address}"), task)
833    }
834
835    async fn download_mock_server() -> (String, tokio::task::JoinHandle<Vec<String>>) {
836        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
837        let address = listener.local_addr().unwrap();
838        let task = tokio::spawn(async move {
839            let responses = [
840                (
841                    "application/json",
842                    r#"{"ok":true,"result":{"file_id":"file-id","file_unique_id":"unique-id","file_path":"photos/avatar.jpg"}}"#,
843                ),
844                ("application/octet-stream", "DOWNLOADABLE_BYTES"),
845            ];
846            let mut requests = Vec::new();
847            for (content_type, body) in responses {
848                let (mut socket, _) = listener.accept().await.unwrap();
849                let mut request = Vec::new();
850                let mut buffer = [0_u8; 8192];
851                let mut expected_len = None;
852                loop {
853                    let read = socket.read(&mut buffer).await.unwrap();
854                    if read == 0 {
855                        break;
856                    }
857                    request.extend_from_slice(&buffer[..read]);
858                    if expected_len.is_none()
859                        && let Some(header_end) =
860                            request.windows(4).position(|part| part == b"\r\n\r\n")
861                    {
862                        let headers = String::from_utf8_lossy(&request[..header_end]);
863                        let content_length = headers
864                            .lines()
865                            .find_map(|line| {
866                                let (name, value) = line.split_once(':')?;
867                                name.eq_ignore_ascii_case("content-length")
868                                    .then(|| value.trim().parse::<usize>().ok())
869                                    .flatten()
870                            })
871                            .unwrap_or(0);
872                        expected_len = Some(header_end + 4 + content_length);
873                    }
874                    if expected_len.is_some_and(|length| request.len() >= length) {
875                        break;
876                    }
877                }
878                let response = format!(
879                    "HTTP/1.1 200 OK\r\ncontent-type: {content_type}\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}",
880                    body.len()
881                );
882                socket.write_all(response.as_bytes()).await.unwrap();
883                requests.push(String::from_utf8_lossy(&request).into_owned());
884            }
885            requests
886        });
887        (format!("http://{address}"), task)
888    }
889
890    #[tokio::test]
891    async fn executes_json_method_and_deserializes_response() {
892        let (api_base, request) = mock_server(
893            "200 OK",
894            r#"{"ok":true,"result":{"id":123,"is_bot":true,"first_name":"Rust bot"}}"#,
895        )
896        .await;
897        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
898
899        let user = bot.get_me().await.unwrap();
900        assert_eq!(user.id, 123);
901        assert_eq!(bot.get_me().await.unwrap().id, 123);
902        let request = request.await.unwrap();
903        assert!(request.starts_with("POST /bot123456:abcdefghijklmnopqrstuvwxyzABCDE/getMe "));
904        assert!(
905            request
906                .to_ascii_lowercase()
907                .contains("content-type: application/json")
908        );
909    }
910
911    #[tokio::test]
912    async fn applies_defaults_only_to_supported_method_fields() {
913        let (api_base, request) = mock_server(
914            "200 OK",
915            r#"{"ok":true,"result":{"message_id":1,"date":2,"chat":{"id":3,"type":"private"}}}"#,
916        )
917        .await;
918        let bot = Bot::builder("123456:abcdefghijklmnopqrstuvwxyzABCDE")
919            .api_base(api_base)
920            .defaults(
921                DefaultBotProperties::default()
922                    .parse_mode("HTML")
923                    .protect_content(true)
924                    .link_preview_is_disabled(true),
925            )
926            .build()
927            .unwrap();
928
929        bot.send_message(3_i64, "hello").await.unwrap();
930        let request = request.await.unwrap();
931        let body = request.split("\r\n\r\n").nth(1).unwrap();
932        let payload: serde_json::Value = serde_json::from_str(body).unwrap();
933        assert_eq!(payload["parse_mode"], "HTML");
934        assert_eq!(payload["protect_content"], true);
935        assert_eq!(payload["link_preview_options"]["is_disabled"], true);
936        assert!(payload.get("disable_notification").is_none());
937    }
938
939    #[test]
940    fn generated_default_mappings_cover_aliases_and_exclude_plain_optional_fields() {
941        let bot = Bot::builder("123456:abcdefghijklmnopqrstuvwxyzABCDE")
942            .defaults(
943                DefaultBotProperties::default()
944                    .parse_mode("HTML")
945                    .protect_content(true),
946            )
947            .build()
948            .unwrap();
949        let poll = crate::methods::SendPoll::new(42_i64, "Question", Vec::new());
950        let payload = bot.prepare_request(&poll).unwrap().payload;
951        assert_eq!(payload["question_parse_mode"], "HTML");
952        assert_eq!(payload["explanation_parse_mode"], "HTML");
953        assert_eq!(payload["description_parse_mode"], "HTML");
954        assert_eq!(payload["protect_content"], true);
955
956        let ephemeral = crate::methods::EditEphemeralMessageText::new(42_i64, 7, 8, "Text");
957        let payload = bot.prepare_request(&ephemeral).unwrap().payload;
958        assert!(payload.get("parse_mode").is_none());
959        assert!(payload.get("protect_content").is_none());
960    }
961
962    #[tokio::test]
963    async fn call_can_suppress_selected_or_all_bot_defaults() {
964        let response =
965            r#"{"ok":true,"result":{"message_id":1,"date":2,"chat":{"id":3,"type":"private"}}}"#;
966        let (api_base, request) = mock_server("200 OK", response).await;
967        let bot = Bot::builder("123456:abcdefghijklmnopqrstuvwxyzABCDE")
968            .api_base(api_base)
969            .defaults(
970                DefaultBotProperties::default()
971                    .parse_mode("HTML")
972                    .protect_content(true),
973            )
974            .build()
975            .unwrap();
976        bot.execute_suppressing_defaults(&SendMessage::new(3_i64, "hello"), ["parse_mode"])
977            .await
978            .unwrap();
979        let request = request.await.unwrap();
980        let body: serde_json::Value =
981            serde_json::from_str(request.split("\r\n\r\n").nth(1).unwrap()).unwrap();
982        assert!(body.get("parse_mode").is_none());
983        assert_eq!(body["protect_content"], true);
984
985        let (api_base, request) = mock_server("200 OK", response).await;
986        let bot = Bot::builder("123456:abcdefghijklmnopqrstuvwxyzABCDE")
987            .api_base(api_base)
988            .defaults(
989                DefaultBotProperties::default()
990                    .parse_mode("HTML")
991                    .protect_content(true),
992            )
993            .build()
994            .unwrap();
995        bot.execute_without_defaults(&SendMessage::new(3_i64, "hello"))
996            .await
997            .unwrap();
998        let request = request.await.unwrap();
999        let body: serde_json::Value =
1000            serde_json::from_str(request.split("\r\n\r\n").nth(1).unwrap()).unwrap();
1001        assert!(body.get("parse_mode").is_none());
1002        assert!(body.get("protect_content").is_none());
1003        assert_eq!(body["text"], "hello");
1004    }
1005
1006    #[tokio::test]
1007    async fn per_call_timeout_cancels_a_stalled_request() {
1008        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
1009        let address = listener.local_addr().unwrap();
1010        let server = tokio::spawn(async move {
1011            let (_socket, _) = listener.accept().await.unwrap();
1012            tokio::time::sleep(Duration::from_secs(1)).await;
1013        });
1014        let bot = Bot::with_api_base(
1015            "123456:abcdefghijklmnopqrstuvwxyzABCDE",
1016            format!("http://{address}"),
1017        )
1018        .unwrap();
1019        assert!(matches!(
1020            bot.execute_with_timeout(&GetMe::default(), Duration::from_millis(10))
1021                .await
1022                .unwrap_err(),
1023            Error::RequestTimeout { method, .. } if method == "getMe"
1024        ));
1025        server.abort();
1026    }
1027
1028    #[tokio::test]
1029    async fn malformed_or_wrongly_typed_success_response_is_a_client_decode_error() {
1030        let (api_base, _request) = mock_server("200 OK", "not-json").await;
1031        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1032        assert!(matches!(
1033            bot.get_me().await.unwrap_err(),
1034            Error::ClientDecode { method, data, .. }
1035                if method == "getMe" && data == "not-json"
1036        ));
1037
1038        let (api_base, _request) = mock_server("200 OK", r#"{"ok":true,"result":true}"#).await;
1039        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1040        assert!(matches!(
1041            bot.get_me().await.unwrap_err(),
1042            Error::ClientDecode { method, .. } if method == "getMe"
1043        ));
1044    }
1045
1046    #[tokio::test]
1047    async fn ok_body_on_http_error_is_not_accepted_as_success() {
1048        let (api_base, _request) = mock_server(
1049            "500 Internal Server Error",
1050            r#"{"ok":true,"result":{"id":123,"is_bot":true,"first_name":"Bot"}}"#,
1051        )
1052        .await;
1053        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1054        assert!(matches!(
1055            bot.get_me().await.unwrap_err(),
1056            Error::Server { method, .. } if method == "getMe"
1057        ));
1058    }
1059
1060    #[tokio::test]
1061    async fn turns_retry_after_into_typed_error() {
1062        let (api_base, _request) = mock_server(
1063            "429 Too Many Requests",
1064            r#"{"ok":false,"error_code":429,"description":"flood control","parameters":{"retry_after":3}}"#,
1065        ).await;
1066        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1067
1068        let error = bot.get_me().await.unwrap_err();
1069        assert!(matches!(
1070            error,
1071            Error::RetryAfter { retry_after, .. } if retry_after == Duration::from_secs(3)
1072        ));
1073    }
1074
1075    #[tokio::test]
1076    async fn classifies_all_upstream_telegram_http_error_categories() {
1077        let cases = [
1078            ("400 Bad Request", "bad_request"),
1079            ("401 Unauthorized", "unauthorized"),
1080            ("403 Forbidden", "forbidden"),
1081            ("404 Not Found", "not_found"),
1082            ("409 Conflict", "conflict"),
1083            ("413 Payload Too Large", "entity_too_large"),
1084            ("500 Internal Server Error", "server"),
1085        ];
1086        for (status, expected) in cases {
1087            let (api_base, _request) = mock_server(
1088                status,
1089                r#"{"ok":false,"error_code":500,"description":"request failed"}"#,
1090            )
1091            .await;
1092            let bot =
1093                Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1094            let error = bot.get_me().await.unwrap_err();
1095            let (actual, method) = match error {
1096                Error::BadRequest { method, .. } => ("bad_request", method),
1097                Error::Unauthorized { method, .. } => ("unauthorized", method),
1098                Error::Forbidden { method, .. } => ("forbidden", method),
1099                Error::NotFound { method, .. } => ("not_found", method),
1100                Error::Conflict { method, .. } => ("conflict", method),
1101                Error::EntityTooLarge { method, .. } => ("entity_too_large", method),
1102                Error::Server { method, .. } => ("server", method),
1103                error => panic!("unexpected error classification: {error:?}"),
1104            };
1105            assert_eq!(actual, expected);
1106            assert_eq!(method, "getMe");
1107        }
1108
1109        let (api_base, _request) = mock_server(
1110            "503 Service Unavailable",
1111            r#"{"ok":false,"error_code":503,"description":"server restart in progress"}"#,
1112        )
1113        .await;
1114        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1115        assert!(matches!(
1116            bot.get_me().await.unwrap_err(),
1117            Error::Restarting { method, .. } if method == "getMe"
1118        ));
1119    }
1120
1121    #[tokio::test]
1122    async fn migrate_to_chat_parameter_takes_precedence_over_http_status() {
1123        let (api_base, _request) = mock_server(
1124            "400 Bad Request",
1125            r#"{"ok":false,"error_code":400,"description":"migrated","parameters":{"migrate_to_chat_id":-100123}}"#,
1126        )
1127        .await;
1128        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1129        assert!(matches!(
1130            bot.get_me().await.unwrap_err(),
1131            Error::MigrateToChat {
1132                method,
1133                migrate_to_chat_id: -100123,
1134                ..
1135            } if method == "getMe"
1136        ));
1137    }
1138
1139    #[tokio::test]
1140    async fn executes_file_method_as_multipart() {
1141        let (api_base, request) = mock_server(
1142            "200 OK",
1143            r#"{"ok":true,"result":{"message_id":1,"date":2,"chat":{"id":3,"type":"private"}}}"#,
1144        )
1145        .await;
1146        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1147        let message = bot
1148            .send_photo(
1149                ChatId::Id(3),
1150                InputFile::named_bytes("photo_upload", "avatar.jpg", b"IMAGE_BYTES".to_vec()),
1151            )
1152            .await
1153            .unwrap();
1154        assert_eq!(message.message_id, 1);
1155        let request = request.await.unwrap();
1156        assert!(
1157            request
1158                .to_ascii_lowercase()
1159                .contains("content-type: multipart/form-data")
1160        );
1161        assert!(request.contains("attach://photo_upload"));
1162        assert!(request.contains("filename=\"avatar.jpg\""));
1163        assert!(request.contains("IMAGE_BYTES"));
1164    }
1165
1166    #[tokio::test]
1167    async fn lazily_reads_filesystem_uploads() {
1168        let path = std::env::temp_dir().join(format!(
1169            "aiogram-rust-upload-test-{}.txt",
1170            std::process::id()
1171        ));
1172        std::fs::write(&path, b"FILESYSTEM_BYTES").unwrap();
1173        let (api_base, request) = mock_server(
1174            "200 OK",
1175            r#"{"ok":true,"result":{"message_id":1,"date":2,"chat":{"id":3,"type":"private"}}}"#,
1176        )
1177        .await;
1178        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1179        let method = SendPhoto::new(
1180            3_i64,
1181            InputFile::named_path("disk_upload", "document.txt", &path),
1182        );
1183
1184        bot.execute(&method).await.unwrap();
1185        let request = request.await.unwrap();
1186        std::fs::remove_file(&path).unwrap();
1187        assert!(request.contains("filename=\"document.txt\""));
1188        assert!(request.contains("FILESYSTEM_BYTES"));
1189    }
1190
1191    #[tokio::test]
1192    async fn downloads_url_input_file_with_bot_http_client() {
1193        let (file_url, file_request) = mock_server("200 OK", "REMOTE_FILE_BYTES").await;
1194        let (api_base, api_request) = mock_server(
1195            "200 OK",
1196            r#"{"ok":true,"result":{"message_id":1,"date":2,"chat":{"id":3,"type":"private"}}}"#,
1197        )
1198        .await;
1199        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1200
1201        bot.send_photo(3_i64, InputFile::url("remote.jpg", file_url))
1202            .await
1203            .unwrap();
1204
1205        assert!(file_request.await.unwrap().starts_with("GET / "));
1206        let request = api_request.await.unwrap();
1207        assert!(request.contains("filename=\"remote.jpg\""));
1208        assert!(request.contains("REMOTE_FILE_BYTES"));
1209    }
1210
1211    struct InjectRequestField(Arc<AtomicUsize>);
1212
1213    #[async_trait::async_trait]
1214    impl RequestMiddleware for InjectRequestField {
1215        async fn handle(
1216            &self,
1217            bot: Bot,
1218            mut request: BotRequest,
1219            next: RequestNext,
1220        ) -> Result<serde_json::Value> {
1221            self.0.fetch_add(1, Ordering::SeqCst);
1222            request.payload["middleware"] = serde_json::json!("visited");
1223            next.run(bot, request).await
1224        }
1225    }
1226
1227    #[tokio::test]
1228    async fn request_middleware_wraps_typed_execution() {
1229        let (api_base, request) = mock_server(
1230            "200 OK",
1231            r#"{"ok":true,"result":{"id":123,"is_bot":true,"first_name":"Rust bot"}}"#,
1232        )
1233        .await;
1234        let calls = Arc::new(AtomicUsize::new(0));
1235        let bot = Bot::builder("123456:abcdefghijklmnopqrstuvwxyzABCDE")
1236            .api_base(api_base)
1237            .request_middleware(InjectRequestField(calls.clone()))
1238            .build()
1239            .unwrap();
1240
1241        bot.get_me().await.unwrap();
1242        let request = request.await.unwrap();
1243        let body: serde_json::Value =
1244            serde_json::from_str(request.split("\r\n\r\n").nth(1).unwrap()).unwrap();
1245        assert_eq!(body["middleware"], "visited");
1246        assert_eq!(calls.load(Ordering::SeqCst), 1);
1247    }
1248
1249    #[tokio::test]
1250    async fn downloads_file_from_telegram_file_endpoint() {
1251        let (api_base, request) = mock_server("200 OK", "FILE_BYTES").await;
1252        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1253
1254        assert_eq!(
1255            bot.download_file("photos/avatar.jpg").await.unwrap(),
1256            b"FILE_BYTES"
1257        );
1258        assert!(
1259            request.await.unwrap().starts_with(
1260                "GET /file/bot123456:abcdefghijklmnopqrstuvwxyzABCDE/photos/avatar.jpg "
1261            )
1262        );
1263    }
1264
1265    #[tokio::test]
1266    async fn downloadable_resolves_get_file_then_downloads_the_current_path() {
1267        let (api_base, requests) = download_mock_server().await;
1268        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1269        let photo = crate::types::PhotoSize::new("file-id", "unique-id", 320, 240);
1270
1271        assert_eq!(bot.download(&photo).await.unwrap(), b"DOWNLOADABLE_BYTES");
1272        let requests = requests.await.unwrap();
1273        assert_eq!(requests.len(), 2);
1274        assert!(
1275            requests[0].starts_with("POST /bot123456:abcdefghijklmnopqrstuvwxyzABCDE/getFile ")
1276        );
1277        let body: serde_json::Value =
1278            serde_json::from_str(requests[0].split("\r\n\r\n").nth(1).unwrap()).unwrap();
1279        assert_eq!(body["file_id"], "file-id");
1280        assert!(
1281            requests[1].starts_with(
1282                "GET /file/bot123456:abcdefghijklmnopqrstuvwxyzABCDE/photos/avatar.jpg "
1283            )
1284        );
1285    }
1286
1287    #[tokio::test]
1288    async fn streams_download_into_async_writer() {
1289        let (api_base, request) = mock_server("200 OK", "STREAMED_FILE_BYTES").await;
1290        let bot = Bot::with_api_base("123456:abcdefghijklmnopqrstuvwxyzABCDE", api_base).unwrap();
1291        let (mut writer, mut reader) = tokio::io::duplex(64);
1292
1293        let written = bot
1294            .download_file_to("document.bin", &mut writer)
1295            .await
1296            .unwrap();
1297        drop(writer);
1298        let mut content = Vec::new();
1299        reader.read_to_end(&mut content).await.unwrap();
1300
1301        assert_eq!(written, 19);
1302        assert_eq!(content, b"STREAMED_FILE_BYTES");
1303        assert!(request.await.unwrap().contains("/document.bin "));
1304    }
1305
1306    #[tokio::test]
1307    async fn local_api_server_download_reads_mapped_file_without_http() {
1308        let directory = std::env::temp_dir().join(format!(
1309            "aiogram-rust-local-api-{}-{}",
1310            std::process::id(),
1311            std::time::SystemTime::now()
1312                .duration_since(std::time::UNIX_EPOCH)
1313                .unwrap()
1314                .as_nanos()
1315        ));
1316        let file = directory.join("photos/avatar.jpg");
1317        tokio::fs::create_dir_all(file.parent().unwrap())
1318            .await
1319            .unwrap();
1320        tokio::fs::write(&file, b"LOCAL_FILE").await.unwrap();
1321        let server = TelegramApiServer::from_base("http://127.0.0.1:1")
1322            .local_file_paths("/telegram", &directory);
1323        let bot = Bot::with_api_server("123456:abcdefghijklmnopqrstuvwxyzABCDE", server).unwrap();
1324        assert_eq!(
1325            bot.download_file("/telegram/photos/avatar.jpg")
1326                .await
1327                .unwrap(),
1328            b"LOCAL_FILE"
1329        );
1330        tokio::fs::remove_dir_all(directory).await.unwrap();
1331    }
1332}