Struct Tracker

pub struct Tracker { /* private fields */ }

The domain layer tracker service.

Its main responsibility is to handle the announce and scrape requests. But it’s also a container for the Tracker configuration, persistence, authentication and other services.

NOTICE: the Tracker is not responsible for handling the network layer. Typically, the Tracker is used by a higher application service that handles the network layer.

Implementations

impl Tracker

pub fn new( config: &Core, stats_event_sender: Option<Box<dyn EventSender>>, stats_repository: Repo, ) -> Result<Tracker, Error>

Tracker constructor.

Errors

Will return a databases::error::Error if unable to connect to database. The Tracker is responsible for the persistence.

pub fn is_public(&self) -> bool

Returns true is the tracker is in public mode.

pub fn is_private(&self) -> bool

Returns true is the tracker is in private mode.

pub fn is_listed(&self) -> bool

Returns true is the tracker is in whitelisted mode.

pub fn requires_authentication(&self) -> bool

Returns true if the tracker requires authentication.

pub fn is_behind_reverse_proxy(&self) -> bool

Returns true is the tracker is in whitelisted mode.

pub fn get_announce_policy(&self) -> AnnouncePolicy

pub fn get_maybe_external_ip(&self) -> Option<IpAddr>

pub fn announce( &self, info_hash: &InfoHash, peer: &mut Peer, remote_client_ip: &IpAddr, peers_wanted: &PeersWanted, ) -> AnnounceData

It handles an announce request.

Context: Tracker

BEP 03: The BitTorrent Protocol Specification.

pub async fn scrape(&self, info_hashes: &Vec<InfoHash>) -> ScrapeData

It handles a scrape request.

Context: Tracker

BEP 48: Tracker Protocol Extension: Scrape.

pub fn load_torrents_from_database(&self) -> Result<(), Error>

It loads the torrents from database into memory. It only loads the torrent entry list with the number of seeders for each torrent. Peers data is not persisted.

Context: Tracker

Errors

Will return a database::Error if unable to load the list of persistent_torrents from the database.

pub fn get_torrent_peers(&self, info_hash: &InfoHash) -> Vec<Arc<Peer>>

Context: Tracker

Get torrent peers for a given torrent.

pub fn upsert_peer_and_get_stats( &self, info_hash: &InfoHash, peer: &Peer, ) -> SwarmMetadata

It updates the torrent entry in memory, it also stores in the database the torrent info data which is persistent, and finally return the data needed for a announce request response.

Context: Tracker

pub fn get_torrents_metrics(&self) -> TorrentsMetrics

It calculates and returns the general Tracker TorrentsMetrics

Context: Tracker

Panics

Panics if unable to get the torrent metrics.

pub fn cleanup_torrents(&self)

Remove inactive peers and (optionally) peerless torrents.

Context: Tracker

pub async fn authenticate(&self, key: &Key) -> Result<(), Error>

It authenticates the peer key against the Tracker authentication key list.

Errors

Will return an error if the the authentication key cannot be verified.

Context: Authentication

pub async fn add_peer_key( &self, add_key_req: AddKeyRequest, ) -> Result<PeerKey, PeerKeyError>

Adds new peer keys to the tracker.

Keys can be pre-generated or randomly created. They can also be permanent or expire.

Errors

Will return an error if:

• The key duration overflows the duration type maximum value.
• The provided pre-generated key is invalid.
• The key could not been persisted due to database issues.

pub async fn generate_permanent_auth_key(&self) -> Result<PeerKey, Error>

It generates a new permanent authentication key.

Authentication keys are used by HTTP trackers.

Context: Authentication

Errors

Will return a database::Error if unable to add the auth_key to the database.

pub async fn generate_auth_key( &self, lifetime: Option<Duration>, ) -> Result<PeerKey, Error>

It generates a new expiring authentication key.

Authentication keys are used by HTTP trackers.

Context: Authentication

Errors

Will return a database::Error if unable to add the auth_key to the database.

Arguments

• lifetime - The duration in seconds for the new key. The key will be no longer valid after lifetime seconds.

pub async fn add_permanent_auth_key(&self, key: Key) -> Result<PeerKey, Error>

It adds a pre-generated permanent authentication key.

Authentication keys are used by HTTP trackers.

Context: Authentication

Errors

Will return a database::Error if unable to add the auth_key to the database. For example, if the key already exist.

Arguments

• key - The pre-generated key.

pub async fn add_auth_key( &self, key: Key, valid_until: Option<DurationSinceUnixEpoch>, ) -> Result<PeerKey, Error>

It adds a pre-generated authentication key.

Authentication keys are used by HTTP trackers.

Context: Authentication

Errors

Will return a database::Error if unable to add the auth_key to the database. For example, if the key already exist.

Arguments

• key - The pre-generated key.
• lifetime - The duration in seconds for the new key. The key will be no longer valid after lifetime seconds.

pub async fn remove_auth_key(&self, key: &Key) -> Result<(), Error>

It removes an authentication key.

Context: Authentication

Errors

Will return a database::Error if unable to remove the key to the database.

pub async fn load_keys_from_database(&self) -> Result<(), Error>

The Tracker stores the authentication keys in memory and in the database. In case you need to restart the Tracker you can load the keys from the database into memory with this function. Keys are automatically stored in the database when they are generated.

Context: Authentication

Errors

Will return a database::Error if unable to load_keys from the database.

pub async fn authorize(&self, info_hash: &InfoHash) -> Result<(), Error>

Right now, there is only authorization when the Tracker runs in listed or private_listed modes.

Context: Authorization

Errors

Will return an error if the tracker is running in listed mode and the infohash is not whitelisted.

pub async fn add_torrent_to_whitelist( &self, info_hash: &InfoHash, ) -> Result<(), Error>

It adds a torrent to the whitelist. Adding torrents is not relevant to public trackers.

Context: Whitelist

Errors

Will return a database::Error if unable to add the info_hash into the whitelist database.

pub async fn add_torrent_to_memory_whitelist( &self, info_hash: &InfoHash, ) -> bool

pub async fn remove_torrent_from_whitelist( &self, info_hash: &InfoHash, ) -> Result<(), Error>

It removes a torrent from the whitelist. Removing torrents is not relevant to public trackers.

Context: Whitelist

Errors

Will return a database::Error if unable to remove the info_hash from the whitelist database.

pub fn remove_torrent_from_database_whitelist( &self, info_hash: &InfoHash, ) -> Result<(), Error>

It removes a torrent from the whitelist in the database.

Context: Whitelist

Errors

Will return a database::Error if unable to remove the info_hash from the whitelist database.

pub async fn remove_torrent_from_memory_whitelist( &self, info_hash: &InfoHash, ) -> bool

It removes a torrent from the whitelist in memory.

Context: Whitelist

pub async fn is_info_hash_whitelisted(&self, info_hash: &InfoHash) -> bool

It checks if a torrent is whitelisted.

Context: Whitelist

pub async fn load_whitelist_from_database(&self) -> Result<(), Error>

It loads the whitelist from the database.

Context: Whitelist

Errors

Will return a database::Error if unable to load the list whitelisted info_hashs from the database.

pub async fn get_stats(&self) -> RwLockReadGuard<'_, Metrics>

It return the Tracker statistics::Metrics.

Context: Statistics

pub async fn send_stats_event( &self, event: Event, ) -> Option<Result<(), SendError<Event>>>

It allows to send a statistic events which eventually will be used to update statistics::Metrics.

Context: Statistics

pub fn drop_database_tables(&self) -> Result<(), Error>

It drops the database tables.

Errors

Will return Err if unable to drop tables.