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#[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 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 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 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 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 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 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 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 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 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
598pub 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 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}