Struct DirMirror 

#[non_exhaustive]
pub struct DirMirror { /* private fields */ }

Core data type of a directory mirror.

External Notes

This structure serves as the entrence point to the mirror API. It represents an instance that is launchable using DirMirror::serve. Calling this method consumes the instance, as this is the common behavior for objects representing server-like things, in order to not imply that this instance serves as a mere configuration template only.

Internal Notes

For now, this data structure only holds configuration options as an ad-hoc replacement for a yet missing hypothetical DirMirrorConfig structure.

I assume that in the future, regardless of the configuration, this might also hold other fields such as access to the database pool, etc. The question is whether this structure will be passed around with locking mechanisms or will just be used as a way to extract configuration options initially in the consuming function, which then applies further wrapping or not.

Implementations

impl DirMirror

pub fn new( path: PathBuf, authorities: AuthorityContacts, schedule: DownloadScheduleConfig, tolerance: DirTolerance, ) -> Self

Creates a new DirMirror with a given set of configuration options.

Parameters

• path: The PathBuf where the database is located.
• authorities: The AuthorityContacts data structure for contacting authorities.
• schedule: The DownloadScheduleConfig used for properly retrying downloads.
• tolerance: The DirTolerance to tolerate clock skews.

Notes

Beware of DirTolerance::default()!, as the default values are inteded for clients, not directory mirrors. Tolerances of several days are not recommened for directory mirrors. Consider using something in the minute range instead, such as 60s, which is what ctor uses.¹

TODO DIRMIRROR: This is unacceptable for the actual release. We NEED a proper way to configure this, such as with a DirMirrorConfig struct that can properly serialize from configuration files and such. However, this task is not a trivial one and maybe one of the hardest parts of this entire development, as it would involve a radical change to many higher level crates. The reason for this being, that we need a clean way to share “global” settings such as the list of authorities into various sub-configurations, such as the configuration for the directory mirror. We must not offer different configurations for the list of authorities for those different components, that would result in lots of boilerplate and potentially wrong execution given that those resources are affecting so many parts of the Tor protocol that a consistent view must be assumed in order to avoid surprising behavior.

---

1. https://gitlab.torproject.org/tpo/core/tor/-/blob/0b20710/src/feature/nodelist/networkstatus.c#L1890. ↩

pub async fn serve<S, T, E>(self, _listener: S) -> Result<(), Infallible>

where S: Stream<Item = Result<T, E>> + Unpin, T: AsyncRead + AsyncWrite + Unpin + Send + 'static, E: Error,

Consumes the DirMirror by running endlessly in the current task.

This method accepts a listener, which is a Stream yielding a Result in order to model a generic way of accepting incoming connections. Think of S as the file descriptor you would call accept(2) upon if you were in C. The idea behind this generic is, as outlined in the module documentation, that a DirMirror can handle incoming connections in multiple ways, such as by serving through an ordinary TCP socket or through a Tor circuit in combination with a RELAY_BEGIN_DIR cell. How this is concretely done, is outside the scope of this crate; instead we provide the primitives making such flexibility possible.

Trait Implementations

impl Debug for DirMirror

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.