Skip to content

Releases

v0.3.0

Choose a tag to compare

@z7vian z7vian released this 14 Nov 11:45
v0.3.0
b8ba274

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_users returns one slot per requested id, in request order, with None for an id Telegram has no user for. It returned only the users found, and failed with PeerNotFound when 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.
  • HTML parsing: a self-closing tag opens no span.

    <b/>x   0.2: "x" bold      0.3: "x" plain
    
  • Text::to_markdown writes some text differently:

    • ) and \ in a URL are written \) and \\, not %29. Markdown that already holds %29 parses 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_ephemeral and EphemeralMessage::reply take impl Into<MessageText> instead of impl Into<Text>. A &str, String, &String or Text argument still compiles; code generic over T: 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_ephemeral on a message in a forum topic now sends into that topic, as Message::reply does.

  • verify_chat(..).custom_description takes impl Into<Text> instead of impl 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, set Disabled on 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::Widget and MediaKind::Widget; 0.2 gave Media::Unknown. Both enums are #[non_exhaustive], so matches still compile, but a widget no longer reaches an Unknown arm.

    Some(Media::Unknown { .. }) // 0.2, for a widget
    Some(Media::Widget(w))      // 0.3
  • Dc has a new public field media, and Dc::wire_id is negative when it is set. Dc is #[non_exhaustive], so code written for 0.2 still compiles; a Dc with media set is not equal to the same Dc without 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: StoryAreaPosition is renamed AreaPosition, 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 None to max_download_bytes_per_sec / max_upload_bytes_per_sec to 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).

  • RetryContext has new public fields file_part and flood_count, and ClientEvent a new variant ConnectFailed { 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 handlers on_widget_query, on_shared_widget_query and on_widget_data_updated, filters::widget(), Message::widget() and InputMessageContent::Widget. copy_message copies a shared widget by its id. Only bots can send widgets; vaegram does not render HTML.
  • TON wallet cards: ChatFullInfo::ton_wallet_card (TonWalletCard) and set_ton_wallet_card_stickers.
  • ReplyParameters::quote_rich_texts: quote part of the replied message as rich text.
  • verify_chat(..).custom_description takes 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 gives Error::InvalidArgument.
  • Bot API 10.4 names for calls that already existed: get_unique_gift(name) (as get_upgraded_gift) and delete_business_account_gift(business_connection_id, owned_gift_id) (as delete_gift(..).business_connection_id(..)).
  • Ephemeral messages take a rich message as well as text: send_ephemeral_message, Message::reply_ephemeral, EphemeralMessage::reply and CallbackQuery::answer_ephemeral. A rich message with media is refused with InvalidArgument before anything is sent. SendEphemeralMessage::message_thread_id(id) without a reply is sent as a reply to the topic's root message; together with reply_to_ephemeral it is refused. impl From<&String> for MessageText.
  • Guest messages: GuestMessage::reference_messages (service and empty messages left out), GuestMessage::answer_text and answer_rich (an article with no title), and InputMessageContent::link_preview_options, which changes text content and returns other content unchanged.
  • HandlerError::message_id, user_id and query_id, filled from the update the failed handler was given.
  • Error::Other, Error::other(e) and Error::downcast_ref::<T>(): a handler can return its own error type through vaegram::Result and read it back in on_error. A string is boxed as std's string error; read it with to_string.
  • Client::run_until_signal(): like run_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, and finish sends one rich message. A draft Telegram refuses is skipped; only finish can fail. No local length limit. A dropped stream sends no final message.
  • ClientEvent::PacketDropped has 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 by callback_query_id(..), which CallbackQuery::answer_ephemeral sets; without one, awaiting fails with InvalidArgument. Refused locally together with reply_to or a topic id other than 1; Telegram's own error comes back unchanged when the tap is too old.
  • SkipReason::NoPts: an updateChannelTooLong for a channel the client has no pts for and that carries none.
  • Transfer options on the builder: download_connections(n), upload_connections(n) (1 to 8), max_download_bytes_per_sec(rate) and max_upload_bytes_per_sec(rate) (None removes 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. NoRetries sends 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...
Read more

v0.2.0

Choose a tag to compare

@z7vian z7vian released this 07 Nov 19:53
v0.2.0
1148719

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 .session files are refused; delete the old file and log in once. storage::load and storage::save are gone: the client keeps <name>.session itself (.workdir, .storage_engine, .in_memory).
  • Updates: next_update() is removed. Register on_message(filter, f) or on_raw_update(f), then app.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, use connect(), then send_code and sign_in. sign_in_bot takes &self and returns types::User.
  • get_me() returns types::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 sent types::Message.
  • Errors: RpcError, raw::Error and Error's struct variants are #[non_exhaustive]: match with .. and a _ arm; build RpcError::new(code, name, value).
  • Raw layer: layer 233; RemoteCall has a required NAME; crypto is private; Connection and Session need the experimental unstable-raw feature.

Install

vaegram = "0.2"   # or vae = "0.2", the same crate under a shorter name

Requires Rust 1.85+. Documentation: https://docs.rs/vaegram

v0.1.0

Choose a tag to compare

@github-actions github-actions released this 27 Oct 08:27
v0.1.0
6fecbea

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 raw invoke for all 868 functions of layer 232
  • Sessions: saved to <name>.session, or exported as one VAE_... session string
  • Named errors: Error::Rpc(e) with e.name == "FLOOD_WAIT" and e.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