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

grammers_session/
session.rs
