Repository navigation
Releases
v0.3.0
vaegram 0.3.0 makes a bot's large uploads and downloads faster and harder to kill, fixes downloads from data centers that serve files on a media-only address, fixes the bugs an audit found in the session, transport, parser and dispatcher code, stops updates being lost silently, adds widgets and the rest of Bot API 10.4, adds what a bot built on vaegram was working around (rich ephemeral and guest messages, replacing the message a button is on, handler error context, run_until_signal, stream_rich_message), and adds PostgreSQL session storage.
Breaking
-
get_usersreturns one slot per requested id, in request order, withNonefor an id Telegram has no user for. It returned only the users found, and failed withPeerNotFoundwhen one was missing.let users: Vec<User> = app.get_users([a, b]).await?; // 0.2 let users: Vec<Option<User>> = app.get_users([a, b]).await?; // 0.3
-
Markdown parsing gives different text or spans for some input:
- A
[inside link text starts a link of its own, and the outer[stays text.[a [b](v) 0.2: link "a [b" to v 0.3: text "[a b", link on "b" - In a URL,
\escapes the next character, so\)no longer ends the URL.[a](x\)y) 0.2: link to "x\", then text "y)" 0.3: link to "x)y" - An escaped
\], or a]inside a code span, no longer closes link text.[a\](u) [b](v) 0.2: the "[" is lost and no later link is read 0.3: text "[a](u) b", link on "b" - No two spans cross. A span that crosses a quote is cut at the quote's edge and leaves out the line break beside it; a span that crosses a link's edge is cut there; a custom emoji or date that would be cut by a quote is dropped.
**a\n> b** c 0.2: one bold over "a\nb", across the quote's start 0.3: bold "a" and bold "b" - A
**>quote is expandable only when its last line ends in a||that closes no spoiler.**>||s||\nt 0.2: expandable quote 0.3: plain quote - Empty spans (
****) are dropped. Custom emoji ids and times may be negative.
- A
-
HTML parsing: a self-closing tag opens no span.
<b/>x 0.2: "x" bold 0.3: "x" plain -
Text::to_markdownwrites some text differently:)and\in a URL are written\)and\\, not%29. Markdown that already holds%29parses as before.Text::new().link("l", "https://x.y/(a)").to_markdown() // 0.2: "[l](https://x.y/(a%29)" 0.3: "[l](https://x.y/(a\\))"
]in the text of a link, mention, custom emoji or date is written\]; 0.2 dropped the span.Text::new().link("a]b", "u").to_markdown() // 0.2: "a\\]b" 0.3: "[a\\]b](u)"
- A quote right after another quote starts with
**>; 0.2 dropped the second quote.Text::new().blockquote("a", false).plain("\n").blockquote("b", false).to_markdown() // 0.2: "> a\nb" 0.3: "> a\n**> b"
- A span with exactly the range of a code span or block is written around it (
**abc**); 0.2 dropped the bold. A quote inside or across another quote is dropped.
-
Client::send_ephemeral_message,Message::reply_ephemeralandEphemeralMessage::replytakeimpl Into<MessageText>instead ofimpl Into<Text>. A&str,String,&StringorTextargument still compiles; code generic overT: Into<Text>must convert first.msg.reply_ephemeral(t) // 0.2, t: impl Into<Text> msg.reply_ephemeral(Into::<Text>::into(t)) // 0.3
Message::reply_ephemeralon a message in a forum topic now sends into that topic, asMessage::replydoes. -
verify_chat(..).custom_descriptiontakesimpl Into<Text>instead ofimpl Into<String>, and reads the description in the client's parse mode, as message text is read. With the default parse mode (Disabled) nothing changes. With another one, setDisabledon the request to send the text as typed.app.verify_chat(chat).custom_description(desc).await? // 0.2: sent as typed app.verify_chat(chat).custom_description(desc).parse_mode(ParseMode::Disabled).await? // 0.3: the same
-
A message carrying a widget has
Media::WidgetandMediaKind::Widget; 0.2 gaveMedia::Unknown. Both enums are#[non_exhaustive], so matches still compile, but a widget no longer reaches anUnknownarm.Some(Media::Unknown { .. }) // 0.2, for a widget Some(Media::Widget(w)) // 0.3
-
Dchas a new public fieldmedia, andDc::wire_idis negative when it is set.Dcis#[non_exhaustive], so code written for 0.2 still compiles; aDcwithmediaset is not equal to the sameDcwithout it.Dc::new(2, addr).wire_id() // 2 in 0.2 and 0.3 Dc::new(2, addr).media(true).wire_id() // -2, new in 0.3
-
Deprecated, not removed:
StoryAreaPositionis renamedAreaPosition, the Bot API 10.4 name, which TON wallet cards use too. The old name is a deprecated alias.StoryAreaPosition::new(50.0, 50.0, 10.0, 10.0) // 0.2, warns in 0.3 AreaPosition::new(50.0, 50.0, 10.0, 10.0) // 0.3
-
A bot's upload or download of 8 MiB or more whose size is known behaves differently by default: 8 connections (4 before) and a pace of 20 MiB/s down and 19.5 MiB/s up. A download by file id, whose size vaegram does not know, goes as in 0.2. Nothing in the API changes; pass
Nonetomax_download_bytes_per_sec/max_upload_bytes_per_secto remove the pace. A large bot upload holds 8 MiB of parts in memory at a time (4 MiB before), a large bot download 4 MiB (2 MiB before). -
RetryContexthas new public fieldsfile_partandflood_count, andClientEventa new variantConnectFailed { dc, error }. Both types are#[non_exhaustive].
Added
- Widgets (MTProto layer 233):
send_widget,send_shared_widget,Message::answer_widget/reply_widget/answer_shared_widget/reply_shared_widget,answer_widget_query,request_widget_query_answer,edit_message_widget_data,edit_inline_widget_data,edit_shared_widget_data,get_widget_public_data, the handlerson_widget_query,on_shared_widget_queryandon_widget_data_updated,filters::widget(),Message::widget()andInputMessageContent::Widget.copy_messagecopies a shared widget by its id. Only bots can send widgets; vaegram does not render HTML. - TON wallet cards:
ChatFullInfo::ton_wallet_card(TonWalletCard) andset_ton_wallet_card_stickers. ReplyParameters::quote_rich_texts: quote part of the replied message as rich text.verify_chat(..).custom_descriptiontakes formatted text, with.html(),.markdown()and.parse_mode(..).CallbackQuery::answer_ephemeral(text): an ephemeral message to the user who pressed the button. A button on an inline message givesError::InvalidArgument.- Bot API 10.4 names for calls that already existed:
get_unique_gift(name)(asget_upgraded_gift) anddelete_business_account_gift(business_connection_id, owned_gift_id)(asdelete_gift(..).business_connection_id(..)). - Ephemeral messages take a rich message as well as text:
send_ephemeral_message,Message::reply_ephemeral,EphemeralMessage::replyandCallbackQuery::answer_ephemeral. A rich message with media is refused withInvalidArgumentbefore anything is sent.SendEphemeralMessage::message_thread_id(id)without a reply is sent as a reply to the topic's root message; together withreply_to_ephemeralit is refused.impl From<&String> for MessageText. - Guest messages:
GuestMessage::reference_messages(service and empty messages left out),GuestMessage::answer_textandanswer_rich(an article with no title), andInputMessageContent::link_preview_options, which changes text content and returns other content unchanged. HandlerError::message_id,user_idandquery_id, filled from the update the failed handler was given.Error::Other,Error::other(e)andError::downcast_ref::<T>(): a handler can return its own error type throughvaegram::Resultand read it back inon_error. A string is boxed as std's string error; read it withto_string.Client::run_until_signal(): likerun_until_ctrl_c, and also stops on SIGTERM on Unix. SIGTERM is watched before the run starts.Client::stream_rich_message(chat_id): pushed chunks append Markdown (or HTML with.html()) source, each draft carries all of it, andfinishsends one rich message. A draft Telegram refuses is skipped; onlyfinishcan fail. No local length limit. A dropped stream sends no final message.ClientEvent::PacketDroppedhas a new reason,"msg_container holds a newer msg_id", and a packet dropped by the replay check is reported too.SendEphemeralMessage::replace_callback_query_message(): the ephemeral message replaces the message the pressed button is on. The press is the one named bycallback_query_id(..), whichCallbackQuery::answer_ephemeralsets; without one, awaiting fails withInvalidArgument. Refused locally together withreply_toor a topic id other than 1; Telegram's own error comes back unchanged when the tap is too old.SkipReason::NoPts: anupdateChannelTooLongfor a channel the client has noptsfor and that carries none.- Transfer options on the builder:
download_connections(n),upload_connections(n)(1 to 8),max_download_bytes_per_sec(rate)andmax_upload_bytes_per_sec(rate)(Noneremoves the pace, a value paces any account kind, 0 is refused). They apply to transfers of 8 MiB or more whose size is known. RetryPolicy::retries_file_parts(): whether a policy's "no retries" also means none for the parts of a file.NoRetriessends each part once.ClientEvent::ConnectFailed { dc, error }: a transfer connection that could not be opened; the transfer goes on with the ones that did.
Fixed
- Session:
- When Telegram...
v0.2.0
vaegram 0.2.0 turns the 0.1 proof of concept into a full Telegram client for bots and user accounts, written from scratch in Rust over MTProto.
Highlights
- Bots and user accounts: bot tokens, phone login with 2FA, QR login, business connections.
- 45 typed
on_*handlers and hooks, composable filters, and conversations (ask,listen, next-step handlers). - Friendly methods across chats, messages, media, stories, payments, gifts and business accounts; every function of layer 233 through
invoke. - Sessions that survive restarts, with gap recovery; storage engines for SQLite, redb, Redis, MongoDB, S3 and Vault behind features.
- Request observers with caller tags and credential-safe JSON, error events, and recorded traffic replay for offline tests.
Upgrading from 0.1
- Sessions: 0.1 session strings and
.sessionfiles are refused; delete the old file and log in once.storage::loadandstorage::saveare gone: the client keeps<name>.sessionitself (.workdir,.storage_engine,.in_memory). - Updates:
next_update()is removed. Registeron_message(filter, f)oron_raw_update(f), thenapp.run().await. - Login:
start()logs in when nothing is stored, asking on stdin for what the builder wasn't given. For a signed-out client, useconnect(), thensend_codeandsign_in.sign_in_bottakes&selfand returnstypes::User. get_me()returnstypes::User(is_bot,phone_number,is_premium).send_message(chat, text)takes any chat reference (i64,"@username","me",&Chat, ..) and returns a builder; awaiting it gives the senttypes::Message.- Errors:
RpcError,raw::ErrorandError's struct variants are#[non_exhaustive]: match with..and a_arm; buildRpcError::new(code, name, value). - Raw layer: layer 233;
RemoteCallhas a requiredNAME;cryptois private;ConnectionandSessionneed the experimentalunstable-rawfeature.
Install
vaegram = "0.2" # or vae = "0.2", the same crate under a shorter nameRequires Rust 1.85+. Documentation: https://docs.rs/vaegram
v0.1.0
The first release: a Telegram MTProto client library for Rust, written from scratch, for bots and user accounts.
[dependencies]
vaegram = "0.1"Or the short name: vae = "0.1".
What works
- MTProto 2.0: TCP transport, the auth key handshake with every check from the
security guidelines, and an encrypted
session that handles salts, acks, containers, gzip, pings and clock fixes - Bot login:
Client::builder(...).bot_token(...).start(), with automatic data center migration - Methods:
send_message,get_me,resolve_peer, plus rawinvokefor all 868 functions of layer 232 - Sessions: saved to
<name>.session, or exported as oneVAE_...session string - Named errors:
Error::Rpc(e)withe.name == "FLOOD_WAIT"ande.value == Some(30) - Crypto by WarpCrypto
- Minimum Rust version: 1.85
Next
Update handlers and filters, friendly types, user login, auto-reconnect, and file transfers.
Full Changelog: https://github.com/rjriajul/vaegram/commits/v0.1.0