Struct tor_dirmgr::DirMgr

pub struct DirMgr<R: Runtime> {

    pub(crate) config: MutCfg<DirMgrConfig>,
    pub(crate) store: Arc<Mutex<Box<dyn Store>>>,
    pub(crate) netdir: Arc<SharedMutArc<NetDir>>,
    pub(crate) default_parameters: Mutex<Arc<NetParameters>>,
    pub(crate) events: FlagPublisher<DirEvent>,
    pub(crate) send_status: Mutex<Sender<DirBootstrapStatus>>,
    pub(crate) receive_status: DirBootstrapEvents,
    pub(crate) circmgr: Option<Arc<CircMgr<R>>>,
    pub(crate) runtime: R,
    pub(crate) offline: bool,
    pub(crate) bootstrap_started: AtomicBool,
    pub(crate) filter: FilterConfig,
    pub(crate) task_schedule: Mutex<Option<TaskSchedule<R>>>,
    pub(crate) task_handle: TaskHandle,
}

A directory manager to download, fetch, and cache a Tor directory.

A DirMgr can operate in three modes:

• In offline mode, it only reads from the cache, and can only read once.
• In read-only mode, it reads from the cache, but checks whether it can acquire an associated lock file. If it can, then it enters read-write mode. If not, it checks the cache periodically for new information.
• In read-write mode, it knows that no other process will be writing to the cache, and it takes responsibility for fetching data from the network and updating the directory with new directory information.

Fields

config: MutCfg<DirMgrConfig>

Configuration information: where to find directories, how to validate them, and so on.

store: Arc<Mutex<Box<dyn Store>>>

Handle to our sqlite cache.

netdir: Arc<SharedMutArc<NetDir>>

Our latest sufficiently bootstrapped directory, if we have one.

We use the RwLock so that we can give this out to a bunch of other users, and replace it once a new directory is bootstrapped.

default_parameters: Mutex<Arc<NetParameters>>

A set of network parameters to hand out when we have no directory.

events: FlagPublisher<DirEvent>

A publisher handle that we notify whenever the consensus changes.

send_status: Mutex<Sender<DirBootstrapStatus>>

A publisher handle that we notify whenever our bootstrapping status changes.

receive_status: DirBootstrapEvents

A receiver handle that gets notified whenever our bootstrapping status changes.

We don’t need to keep this drained, since postage::watch already knows to discard unread events.

circmgr: Option<Arc<CircMgr<R>>>

A circuit manager, if this DirMgr supports downloading.

runtime: R

Our asynchronous runtime.

offline: bool

Whether or not we’re operating in offline mode.

bootstrap_started: AtomicBool

If we’re not in offline mode, stores whether or not the DirMgr has attempted to bootstrap yet or not.

This exists in order to prevent starting two concurrent bootstrap tasks.

(In offline mode, this does nothing.)

filter: FilterConfig

Available on crate feature dirfilter only.

A filter that gets applied to directory objects before we use them.

task_schedule: Mutex<Option<TaskSchedule<R>>>

A task schedule that can be used if we’re bootstrapping. If this is None, then there’s currently a scheduled task in progress.

task_handle: TaskHandle

A task handle that we return to anybody who needs to manage our download process.

Implementations

impl<R: Runtime> DirMgr<R>

pub async fn load_once(runtime: R, config: DirMgrConfig) -> Result<Arc<NetDir>>

Try to load the directory from disk, without launching any kind of update process.

This function runs in offline mode: it will give an error if the result is not up-to-date, or not fully downloaded.

In general, you shouldn’t use this function in a long-running program; it’s only suitable for command-line or batch tools.

pub async fn load_or_bootstrap_once( config: DirMgrConfig, runtime: R, store: DirMgrStore<R>, circmgr: Arc<CircMgr<R>> ) -> Result<Arc<NetDir>>

Return a current netdir, either loading it or bootstrapping it as needed.

Like load_once, but will try to bootstrap (or wait for another process to bootstrap) if we don’t have an up-to-date bootstrapped directory.

In general, you shouldn’t use this function in a long-running program; it’s only suitable for command-line or batch tools.

pub fn create_unbootstrapped( config: DirMgrConfig, runtime: R, store: DirMgrStore<R>, circmgr: Arc<CircMgr<R>> ) -> Result<Arc<Self>>

Create a new DirMgr in online mode, but don’t bootstrap it yet.

The DirMgr can be bootstrapped later with bootstrap.

pub async fn bootstrap(self: &Arc<Self>) -> Result<()>

Bootstrap a DirMgr created in online mode that hasn’t been bootstrapped yet.

This function will not return until the directory is bootstrapped enough to build circuits. It will also launch a background task that fetches any missing information, and that replaces the directory when a new one is available.

This function is intended to be used together with create_unbootstrapped. There is no need to call this function otherwise.

If bootstrapping has already successfully taken place, returns early with success.

Errors

Returns an error if bootstrapping fails. If the error is Error::CantAdvanceState, it may be possible to successfully bootstrap later on by calling this function again.

Panics

Panics if the DirMgr passed to this function was not created in online mode, such as via load_once.

pub fn bootstrap_started(&self) -> bool

Returns true if a bootstrap attempt is in progress, or successfully completed.

pub async fn bootstrap_from_config( config: DirMgrConfig, runtime: R, store: DirMgrStore<R>, circmgr: Arc<CircMgr<R>> ) -> Result<Arc<Self>>

Return a new directory manager from a given configuration, bootstrapping from the network as necessary.

pub(crate) async fn reload_until_owner( weak: &Weak<Self>, schedule: &mut TaskSchedule<R>, attempt_id: AttemptId, on_complete: &mut Option<Sender<()>> ) -> Result<()>

Try forever to either lock the storage (and thereby become the owner), or to reload the database.

If we have begin to have a bootstrapped directory, send a message using on_complete.

If we eventually become the owner, return Ok().

pub(crate) async fn download_forever( weak: Weak<Self>, schedule: &mut TaskSchedule<R>, attempt_id: AttemptId, on_complete: Option<Sender<()>> ) -> Result<()>

Try to fetch our directory info and keep it updated, indefinitely.

If we have begin to have a bootstrapped directory, send a message using on_complete.

pub(crate) fn circmgr(&self) -> Result<Arc<CircMgr<R>>>

Get a reference to the circuit manager, if we have one.

pub fn reconfigure( &self, new_config: &DirMgrConfig, how: Reconfigure ) -> Result<(), ReconfigureError>

Try to change our configuration to new_config.

Actual behavior will depend on the value of how.

pub fn bootstrap_events(&self) -> DirBootstrapEvents

Return a stream of DirBootstrapStatus events to tell us about changes in the latest directory’s bootstrap status.

Note that this stream can be lossy: the caller will not necessarily observe every event on the stream

pub(crate) fn update_progress( &self, attempt_id: AttemptId, progress: DirProgress )

Replace the latest status with progress and broadcast to anybody watching via a DirBootstrapEvents stream.

pub(crate) fn note_errors(&self, attempt_id: AttemptId, n_errors: usize)

Update our status tracker to note that some number of errors has occurred.

pub(crate) fn note_reset(&self, attempt_id: AttemptId)

Update our status tracker to note that we’ve needed to reset our download attempt.

pub(crate) fn try_upgrade_to_readwrite(&self) -> Result<bool>

Try to make this a directory manager with read-write access to its storage.

Return true if we got the lock, or if we already had it.

Return false if another process has the lock

pub(crate) fn from_config( config: DirMgrConfig, runtime: R, store: DirMgrStore<R>, circmgr: Option<Arc<CircMgr<R>>>, offline: bool ) -> Result<Self>

Construct a DirMgr from a DirMgrConfig.

If offline is set, opens the SQLite store read-only and sets the offline flag in the returned manager.

pub(crate) async fn load_directory( self: &Arc<Self>, attempt_id: AttemptId ) -> Result<bool>

Load the latest non-pending non-expired directory from the cache, if it is newer than the one we have.

Return false if there is no such consensus.

pub fn events(&self) -> impl Stream<Item = DirEvent>

Return a new asynchronous stream that will receive notification whenever the consensus has changed.

Multiple events may be batched up into a single item: each time this stream yields an event, all you can assume is that the event has occurred at least once.

pub fn text(&self, doc: &DocId) -> Result<Option<DocumentText>>

Try to load the text of a single document described by doc from storage.

pub fn texts<T>(&self, docs: T) -> Result<HashMap<DocId, DocumentText>>

where T: IntoIterator<Item = DocId>,

Load the text for a collection of documents.

If many of the documents have the same type, this can be more efficient than calling text.

pub(crate) fn expand_response_text( &self, req: &ClientRequest, text: String ) -> Result<String>

Given a request we sent and the response we got from a directory server, see whether we should expand that response into “something larger”.

Currently, this handles expanding consensus diffs, and nothing else. We do it at this stage of our downloading operation because it requires access to the store.

pub(crate) fn apply_netdir_changes( self: &Arc<Self>, state: &mut Box<dyn DirState>, store: &mut dyn Store ) -> Result<()>

If state has netdir changes to apply, apply them to our netdir.

Trait Implementations

impl<R: Runtime> NetDirProvider for DirMgr<R>

fn netdir(&self, timeliness: Timeliness) -> Result<Arc<NetDir>>

Return a network directory that’s live according to the provided timeliness.

fn events(&self) -> BoxStream<'static, DirEvent>

Return a new asynchronous stream that will receive notification whenever the consensus has changed.

fn params(&self) -> Arc<dyn AsRef<NetParameters>>

Return the latest network parameters.

fn timely_netdir(&self) -> Result<Arc<NetDir>, Error>

Return a reasonable netdir for general usage.