grammers_session/
session.rs

1// Copyright 2020 - developers of the `grammers` project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9use crate::BoxFuture;
10use crate::peer::PeerRef;
11use crate::types::{DcOption, PeerId, PeerInfo, UpdateState, UpdatesState};
12
13pub type ErasedSession = dyn Session<Error = Box<dyn std::error::Error + Send + Sync + 'static>>;
14
15/// The main interface to interact with the different [`crate::storages`].
16///
17/// All methods are synchronous and currently infallible because clients
18/// are not equipped to deal with the arbitrary errors that a dynamic
19/// `Session` could produce. This may change in the future.
20///
21/// A newly-created storage should return the same values that
22/// [crate::SessionData::default] would produce.
23pub trait Session: Send + Sync + 'static {
24    type Error;
25
26    /// Datacenter that is "home" to the user authorized by this session.
27    ///
28    /// If not known, the ID of the closest datacenter should be returned instead.
29    /// Note that incorrect guesses are allowed, and the user may need to migrate.
30    ///
31    /// Note that it is used on every request and thus should be cheap to call.
32    fn home_dc_id(&self) -> Result<i32, Self::Error>;
33
34    /// Changes the [`Session::home_dc_id`] after finding out the actual datacenter
35    /// to which main queries should be executed against.
36    ///
37    /// This must update the value in the cache layer used by `home_dc_id`.
38    fn set_home_dc_id(&self, dc_id: i32) -> BoxFuture<'_, Result<(), Self::Error>>;
39
40    /// Query a single datacenter option.
41    ///
42    /// If no up-to-date option has been [`Session::set_dc_option`] yet,
43    /// a statically-known option must be returned.
44    ///
45    /// `None` may only be returned on invalid DC IDs or DCs that are not yet known.
46    ///
47    /// Note that it is used on every request and thus should be cheap to call.
48    fn dc_option(&self, dc_id: i32) -> Result<Option<DcOption>, Self::Error>;
49
50    /// Update the previously-known [`Session::dc_option`] with new values.
51    ///
52    /// Should also be used after generating permanent authentication keys to a datacenter.
53    ///
54    /// This must update the value in the cache layer used by `dc_option`.
55    fn set_dc_option(&self, dc_option: &DcOption) -> BoxFuture<'_, Result<(), Self::Error>>;
56
57    /// Query a peer by its identity.
58    ///
59    /// Querying for [`PeerId::self_user`] can be used as a way to determine
60    /// whether the authentication key has a logged-in user bound (i.e. signed in).
61    fn peer(&self, peer: PeerId) -> BoxFuture<'_, Result<Option<PeerInfo>, Self::Error>>;
62
63    /// Query the full peer reference from its identity.
64    ///
65    /// By default, this uses [`Session::peer`] to retrieve the [`PeerAuth`](crate::types::PeerAuth).
66    ///
67    /// If you want to obtain a `PeerRef` from a `PeerId` regardless of whether it is cached
68    /// in the session or not, you can pair this method with [`PeerId::to_ambient_ref`].
69    fn peer_ref(&self, peer: PeerId) -> BoxFuture<'_, Result<Option<PeerRef>, Self::Error>> {
70        Box::pin(async move {
71            Ok(self
72                .peer(peer)
73                .await?
74                .and_then(|info| info.auth())
75                .map(|auth| PeerRef { id: peer, auth }))
76        })
77    }
78
79    /// Cache a peer's basic information for [`Session::peer`] to be able to query them later.
80    ///
81    /// This method may not necessarily remember the peers forever,
82    /// except for users where [`PeerInfo::User::is_self`] is `Some(true)`.
83    fn cache_peer(&self, peer: &PeerInfo) -> BoxFuture<'_, Result<(), Self::Error>>;
84
85    /// Loads the entire updates state.
86    fn updates_state(&self) -> BoxFuture<'_, Result<UpdatesState, Self::Error>>;
87
88    /// Update the state for one or all updates.
89    fn set_update_state(&self, update: UpdateState) -> BoxFuture<'_, Result<(), Self::Error>>;
90}
grammers_session/session.rs

grammers_session/
session.rs
