mirror of
https://github.com/teloxide/teloxide.git
synced 2024-10-24 09:57:18 +02:00
Deprecate polling()
, expose Polling{,Builder}
and fix docs
This commit is contained in:
parent
db417caa52
commit
e0e5da30ba
2 changed files with 84 additions and 83 deletions
|
@ -42,8 +42,9 @@ use crate::{
|
||||||
mod polling;
|
mod polling;
|
||||||
mod stateful_listener;
|
mod stateful_listener;
|
||||||
|
|
||||||
|
#[allow(deprecated)]
|
||||||
pub use self::{
|
pub use self::{
|
||||||
polling::{polling, polling_builder, polling_default, PollingBuilder},
|
polling::{polling, polling_builder, polling_default, Polling, PollingBuilder, PollingStream},
|
||||||
stateful_listener::StatefulListener,
|
stateful_listener::StatefulListener,
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
|
@ -34,12 +34,20 @@ where
|
||||||
R: Requester + Send + 'static,
|
R: Requester + Send + 'static,
|
||||||
<R as Requester>::GetUpdates: Send,
|
<R as Requester>::GetUpdates: Send,
|
||||||
{
|
{
|
||||||
/// Set timeout.
|
/// A timeout in seconds for polling.
|
||||||
|
///
|
||||||
|
/// ## Note
|
||||||
|
///
|
||||||
|
/// `timeout` should not be bigger than http client timeout, see
|
||||||
|
/// [`default_reqwest_settings`] for default http client settings.
|
||||||
|
///
|
||||||
|
/// [`default_reqwest_settings`]: crate::net::default_reqwest_settings
|
||||||
pub fn timeout(self, timeout: Duration) -> Self {
|
pub fn timeout(self, timeout: Duration) -> Self {
|
||||||
Self { timeout: Some(timeout), ..self }
|
Self { timeout: Some(timeout), ..self }
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Set limit.
|
/// Limit the number of updates to be retrieved at once. Values between
|
||||||
|
/// 1—100 are accepted.
|
||||||
///
|
///
|
||||||
/// ## Panics
|
/// ## Panics
|
||||||
///
|
///
|
||||||
|
@ -51,14 +59,17 @@ where
|
||||||
Self { limit: Some(limit), ..self }
|
Self { limit: Some(limit), ..self }
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Set allowed updates.
|
/// A list of the types of updates you want to receive.
|
||||||
///
|
///
|
||||||
/// ## Note
|
/// ## Note
|
||||||
///
|
///
|
||||||
/// Teloxide normally (when using [`Dispatcher`] or repls) sets this
|
/// Teloxide normally (when using [`Dispatcher`] or [`repl`]s) sets this
|
||||||
/// automatically.
|
/// automatically via [`hint_allowed_updates`], so you rarely need to use
|
||||||
|
/// `allowed_updates` explicitly.
|
||||||
///
|
///
|
||||||
/// [`Dispatcher`]: crate::dispatching::Dispatcher
|
/// [`Dispatcher`]: crate::dispatching::Dispatcher
|
||||||
|
/// [`repl`]: fn@crate::repl
|
||||||
|
/// [`hint_allowed_updates`]: crate::dispatching::update_listeners::UpdateListener::hint_allowed_updates
|
||||||
pub fn allowed_updates(self, allowed_updates: Vec<AllowedUpdate>) -> Self {
|
pub fn allowed_updates(self, allowed_updates: Vec<AllowedUpdate>) -> Self {
|
||||||
Self { allowed_updates: Some(allowed_updates), ..self }
|
Self { allowed_updates: Some(allowed_updates), ..self }
|
||||||
}
|
}
|
||||||
|
@ -70,10 +81,14 @@ where
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Creates a polling update listener.
|
/// Returns a long polling update listener with configuration from the
|
||||||
|
/// builder.
|
||||||
|
///
|
||||||
|
/// See also: [`polling_default`], [`Polling`].
|
||||||
pub fn build(self) -> Polling<R> {
|
pub fn build(self) -> Polling<R> {
|
||||||
let Self { bot, timeout, limit, allowed_updates } = self;
|
let Self { bot, timeout, limit, allowed_updates } = self;
|
||||||
polling(bot, timeout, limit, allowed_updates)
|
let (token, flag) = AsyncStopToken::new_pair();
|
||||||
|
Polling { bot, timeout, limit, allowed_updates, flag, token }
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -101,59 +116,77 @@ where
|
||||||
polling_builder(bot).timeout(Duration::from_secs(10)).delete_webhook().await.build()
|
polling_builder(bot).timeout(Duration::from_secs(10)).delete_webhook().await.build()
|
||||||
}
|
}
|
||||||
|
|
||||||
#[cfg_attr(doc, aquamarine::aquamarine)]
|
|
||||||
/// Returns a long polling update listener with some additional options.
|
/// Returns a long polling update listener with some additional options.
|
||||||
///
|
#[deprecated(since = "0.7.0", note = "use `polling_builder` instead")]
|
||||||
/// - `bot`: Using this bot, the returned update listener will receive updates.
|
pub fn polling<R>(
|
||||||
/// - `timeout`: A timeout in seconds for polling.
|
bot: R,
|
||||||
/// - `limit`: Limits the number of updates to be retrieved at once. Values
|
timeout: Option<Duration>,
|
||||||
/// between 1—100 are accepted.
|
limit: Option<u8>,
|
||||||
/// - `allowed_updates`: A list the types of updates you want to receive.
|
allowed_updates: Option<Vec<AllowedUpdate>>,
|
||||||
///
|
) -> Polling<R>
|
||||||
/// See [`GetUpdates`] for defaults.
|
where
|
||||||
///
|
R: Requester + Send + 'static,
|
||||||
/// See also: [`polling_default`](polling_default).
|
<R as Requester>::GetUpdates: Send,
|
||||||
///
|
{
|
||||||
/// ## Notes
|
let mut builder = polling_builder(bot);
|
||||||
///
|
builder.timeout = timeout;
|
||||||
/// - `timeout` should not be bigger than http client timeout, see
|
builder.limit = limit;
|
||||||
/// [`default_reqwest_settings`] for default http client settings.
|
builder.allowed_updates = allowed_updates;
|
||||||
/// - [`repl`]s and [`Dispatcher`] use [`hint_allowed_updates`] to set
|
builder.build()
|
||||||
/// `allowed_updates`, so you rarely need to pass `allowed_updates`
|
}
|
||||||
/// explicitly.
|
|
||||||
///
|
async fn delete_webhook_if_setup<R>(requester: &R)
|
||||||
/// [`default_reqwest_settings`]: teloxide::net::default_reqwest_settings
|
where
|
||||||
/// [`repl`]: fn@crate::repl
|
R: Requester,
|
||||||
/// [`Dispatcher`]: crate::dispatching::Dispatcher
|
{
|
||||||
/// [`hint_allowed_updates`]:
|
let webhook_info = match requester.get_webhook_info().send().await {
|
||||||
/// crate::dispatching::update_listeners::UpdateListener::hint_allowed_updates
|
Ok(ok) => ok,
|
||||||
|
Err(e) => {
|
||||||
|
log::error!("Failed to get webhook info: {:?}", e);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
let is_webhook_setup = webhook_info.url.is_some();
|
||||||
|
|
||||||
|
if is_webhook_setup {
|
||||||
|
if let Err(e) = requester.delete_webhook().send().await {
|
||||||
|
log::error!("Failed to delete a webhook: {:?}", e);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg_attr(doc, aquamarine::aquamarine)]
|
||||||
|
/// A polling update listener.
|
||||||
///
|
///
|
||||||
/// ## How it works
|
/// ## How it works
|
||||||
///
|
///
|
||||||
/// Long polling works by repeatedly calling [`Bot::get_updates`][get_updates].
|
/// Long polling works by repeatedly calling
|
||||||
/// If telegram has any updates, it returns them immediately, otherwise it waits
|
/// [`Bot::get_updates`][get_updates]. If telegram has any updates, it
|
||||||
/// until either it has any updates or `timeout` expires.
|
/// returns them immediately, otherwise it waits until either it has any
|
||||||
|
/// updates or `timeout` expires.
|
||||||
///
|
///
|
||||||
/// Each [`get_updates`][get_updates] call includes an `offset` parameter equal
|
/// Each [`get_updates`][get_updates] call includes an `offset` parameter
|
||||||
/// to the latest update id + one, that allows to only receive updates that has
|
/// equal to the latest update id + one, that allows to only receive
|
||||||
/// not been received before.
|
/// updates that has not been received before.
|
||||||
///
|
///
|
||||||
/// When telegram receives a [`get_updates`][get_updates] request with `offset =
|
/// When telegram receives a [`get_updates`][get_updates] request with
|
||||||
/// N` it forgets any updates with id < `N`. When `polling` listener is stopped,
|
/// `offset = N` it forgets any updates with id < `N`. When `polling`
|
||||||
/// it sends [`get_updates`][get_updates] with `timeout = 0, limit = 1` and
|
/// listener is stopped, it sends [`get_updates`][get_updates] with
|
||||||
/// appropriate `offset`, so future bot restarts won't see updates that were
|
/// `timeout = 0, limit = 1` and appropriate `offset`, so future bot
|
||||||
/// already seen.
|
/// restarts won't see updates that were already seen.
|
||||||
///
|
///
|
||||||
/// Consumers of a `polling` update listener then need to repeatedly call
|
/// Consumers of a [`Polling`] update listener then need to repeatedly call
|
||||||
/// [`futures::StreamExt::next`] to get the updates.
|
/// [`futures::StreamExt::next`] to get the updates.
|
||||||
///
|
///
|
||||||
/// Here is an example diagram that shows these interactions between consumers
|
/// Here is an example diagram that shows these interactions between
|
||||||
/// like [`Dispatcher`], `polling` update listener and telegram.
|
/// consumers like [`Dispatcher`], [`Polling`] update listener and
|
||||||
|
/// telegram.
|
||||||
///
|
///
|
||||||
/// ```mermaid
|
/// ```mermaid
|
||||||
/// sequenceDiagram
|
/// sequenceDiagram
|
||||||
/// participant C as Consumer
|
/// participant C as Consumer
|
||||||
/// participant P as polling
|
/// participant P as Polling
|
||||||
/// participant T as Telegram
|
/// participant T as Telegram
|
||||||
///
|
///
|
||||||
/// link C: Dispatcher @ ../struct.Dispatcher.html
|
/// link C: Dispatcher @ ../struct.Dispatcher.html
|
||||||
|
@ -193,41 +226,7 @@ where
|
||||||
/// ```
|
/// ```
|
||||||
///
|
///
|
||||||
/// [get_updates]: crate::requests::Requester::get_updates
|
/// [get_updates]: crate::requests::Requester::get_updates
|
||||||
pub fn polling<R>(
|
/// [`Dispatcher`]: crate::dispatching::Dispatcher
|
||||||
bot: R,
|
|
||||||
timeout: Option<Duration>,
|
|
||||||
limit: Option<u8>,
|
|
||||||
allowed_updates: Option<Vec<AllowedUpdate>>,
|
|
||||||
) -> Polling<R>
|
|
||||||
where
|
|
||||||
R: Requester + Send + 'static,
|
|
||||||
<R as Requester>::GetUpdates: Send,
|
|
||||||
{
|
|
||||||
let (token, flag) = AsyncStopToken::new_pair();
|
|
||||||
Polling { bot, timeout, limit, allowed_updates, flag, token }
|
|
||||||
}
|
|
||||||
|
|
||||||
async fn delete_webhook_if_setup<R>(requester: &R)
|
|
||||||
where
|
|
||||||
R: Requester,
|
|
||||||
{
|
|
||||||
let webhook_info = match requester.get_webhook_info().send().await {
|
|
||||||
Ok(ok) => ok,
|
|
||||||
Err(e) => {
|
|
||||||
log::error!("Failed to get webhook info: {:?}", e);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
let is_webhook_setup = webhook_info.url.is_some();
|
|
||||||
|
|
||||||
if is_webhook_setup {
|
|
||||||
if let Err(e) = requester.delete_webhook().send().await {
|
|
||||||
log::error!("Failed to delete a webhook: {:?}", e);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
pub struct Polling<B: Requester> {
|
pub struct Polling<B: Requester> {
|
||||||
bot: B,
|
bot: B,
|
||||||
timeout: Option<Duration>,
|
timeout: Option<Duration>,
|
||||||
|
@ -370,6 +369,7 @@ fn polling_is_send() {
|
||||||
use crate::dispatching::update_listeners::AsUpdateStream;
|
use crate::dispatching::update_listeners::AsUpdateStream;
|
||||||
|
|
||||||
let bot = crate::Bot::new("TOKEN");
|
let bot = crate::Bot::new("TOKEN");
|
||||||
|
#[allow(deprecated)]
|
||||||
let mut polling = polling(bot, None, None, None);
|
let mut polling = polling(bot, None, None, None);
|
||||||
|
|
||||||
assert_send(&polling);
|
assert_send(&polling);
|
||||||
|
|
Loading…
Reference in a new issue