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

grammers_session/
session.rs
