Device Detection and IP Intelligence for the 51Degrees Pipeline, in Rust

data_paths.rs File Reference

Classes

struct  Host
 What the download command depends on besides the file. More...
struct  DownloadCommand
 The command that runs the data repository's download script for one file. More...

Enumerations

enum  IpiTier
 Which tier of IP Intelligence data file to resolve. More...

Functions

pub enum IpiTier dd_data_path () -> Option< PathBuf >
 Resolve the path to an on-premise Device Detection data file.
pub fn ipi_data_path (tier:IpiTier) -> Option< PathBuf >
 Resolve the path to an on-premise IP Intelligence data file at the requested tier.
pub fn find_data_file (relative_path:&str) -> Option< PathBuf >
 Find a data file the data repository links to, downloading it when it is missing.
pub fn find_data_file_from (relative_path:&str, start:&Path) -> Option< PathBuf >
 Find a data file the data repository links to by walking up from start instead of the current working directory, downloading it when it is missing.
fn find_data_file_for (relative_path:&str, start:&Path, host:Host) -> Option< PathBuf >
 [find_data_file_from] with the download command chosen for host.
struct Host current () -> Self
 The host this process runs on.
fn on_path (program:&str) -> bool
 Whether program, or program.exe, is in a folder on the PATH.
struct DownloadCommand for_host (data_repository:&Path, name:&str, host:Host) -> Self
 The command that downloads name into the data repository at data_repository on host.
command args self stdout (std::io::stderr())

Variables

pub const DD_PATH_ENV_VAR
 The environment variable giving an explicit Device Detection data-file path.
pub const IPI_PATH_ENV_VAR
 The environment variable giving an explicit IP Intelligence data-file path.
pub const DD_LITE_RELATIVE_PATH
 The Lite Device Detection data file in the data repository.
pub const IPI_ASN_RELATIVE_PATH
 The ASN IP Intelligence data file in the data repository, giving Asn and AsnName.
pub const IPI_LITE_RELATIVE_PATH
 The Lite IP Intelligence data file in the data repository, giving RegisteredName, RegisteredOwner and RegisteredCountry.
pub const IPI_ENTERPRISE_FILE_NAME
 The Enterprise IP Intelligence data-file name on the Enterprise share.
pub const IPI_ENTERPRISE_SHARE_ENV_VAR
 The environment variable giving the root of the dated Enterprise IP Intelligence share, which holds the latest data file under a YYYY/MM/DD subdirectory.
 EnterpriseOrLite
 The Enterprise file if the share is reachable, otherwise the Lite file from the data repository.
 EnterpriseOrAsn
 The Enterprise file if the share is reachable, otherwise the ASN file from the data repository.
 Asn
 Force the ASN file ([IPI_ASN_RELATIVE_PATH]).
 Lite
 Force the Lite file ([IPI_LITE_RELATIVE_PATH]), free from the data repository and much larger than the ASN file.
 Enterprise
 Force the Enterprise file from the Enterprise share.
pub const DATA_DOWNLOAD_SOURCE
 The source the examples send with each download, so that downloads can be counted by where they come from.
const GITHUB_ACTIONS_ENV_VAR
 The environment variable GitHub Actions sets to true in every step.
const POWERSHELL_MODULE_PATH_ENV_VAR
 The module path Windows PowerShell must not inherit from PowerShell 7.
static DOWNLOADS_TRIED
 The links this process has already run the download script for.
windows __pad0__
 Whether this is Windows, where the PowerShell script is run.
windows has_pwsh
 Whether PowerShell 7, pwsh, is on the PATH.
windows in_github_actions
 Whether this runs in GitHub Actions, where no source is sent.
program arguments
program removed
 Variables removed from the environment the command runs in.
fn run self bool
 Run the command, returning whether it succeeded.

Enumeration Type Documentation

◆ IpiTier

enum IpiTier

Which tier of IP Intelligence data file to resolve.

With no file set, an example that shows location or registration properties reads the Lite file, and one whose properties do not matter to what it shows, such as a performance or update example, reads the much smaller ASN file. Either reads the Enterprise file instead when the configured share is reachable. A caller can also force a specific tier, for example to exercise the Enterprise-only properties.

Function Documentation

◆ current()

struct Host current ( ) -> Self

The host this process runs on.

◆ dd_data_path()

pub enum IpiTier dd_data_path ( ) -> Option< PathBuf >

Resolve the path to an on-premise Device Detection data file.

Checks [DD_PATH_ENV_VAR] first and returns its value when set to a non-blank path. Otherwise finds [DD_LITE_RELATIVE_PATH] with [find_data_file], which downloads it when it is missing. Returns None if neither is available.

◆ find_data_file()

pub fn find_data_file ( relative_path:& str) -> Option< PathBuf >

Find a data file the data repository links to, downloading it when it is missing.

relative_path is looked for as [crate::find_file] looks for it. The data repository lists each data file as <file>.link in the folder where the file goes, so when the file is missing and its link is there, the data repository is the folder above, and its script is run for that one file, saying so. The file is then looked for again. When it still cannot be found, a message naming the command that gets it is printed and None is returned.

◆ find_data_file_for()

fn find_data_file_for ( relative_path:& str,
start:& Path,
host:Host  ) -> Option< PathBuf >

[find_data_file_from] with the download command chosen for host.

◆ find_data_file_from()

pub fn find_data_file_from ( relative_path:& str,
start:& Path ) -> Option< PathBuf >

Find a data file the data repository links to by walking up from start instead of the current working directory, downloading it when it is missing.

See [find_data_file].

◆ for_host()

struct DownloadCommand for_host ( data_repository:& Path,
name:& str,
host:Host  ) -> Self

The command that downloads name into the data repository at data_repository on host.

Outside GitHub Actions it sends [DATA_DOWNLOAD_SOURCE] as the source.

◆ ipi_data_path()

pub fn ipi_data_path ( tier:IpiTier ) -> Option< PathBuf >

Resolve the path to an on-premise IP Intelligence data file at the requested tier.

[IPI_PATH_ENV_VAR] always wins when set to a non-blank path, regardless of tier, so a caller can point every example at one explicit file. Otherwise the tier decides:

  • [IpiTier::EnterpriseOrLite] and [IpiTier::EnterpriseOrAsn] return the latest Enterprise file from the configured share if it is reachable, and otherwise that free file.
  • [IpiTier::Enterprise] returns the latest Enterprise file, or None when the share is unreachable.
  • [IpiTier::Asn] and [IpiTier::Lite] return that free file, found with [find_data_file], which downloads it when it is missing.

Returns None when no file for the requested tier can be located.

◆ on_path()

fn on_path ( program:& str) -> bool

Whether program, or program.exe, is in a folder on the PATH.

◆ stdout()

command args self stdout ( std::io::stderr() )

Variable Documentation

◆ __pad0__

program __pad0__

Whether this is Windows, where the PowerShell script is run.

◆ arguments

program arguments

◆ Asn

Asn

Force the ASN file ([IPI_ASN_RELATIVE_PATH]).

Small, current and free from the data repository, so it suits most quick tests.

◆ bool

fn run self bool
Initial value:
{
let mut command = Command::new(self.program)
pub fn set_star_sign mut
Set the computed star sign.
Definition star_sign.rs:193

Run the command, returning whether it succeeded.

The script's progress goes to standard error, as this module's own messages do, so the example's standard output carries only its results.

◆ DATA_DOWNLOAD_SOURCE

pub const DATA_DOWNLOAD_SOURCE

The source the examples send with each download, so that downloads can be counted by where they come from.

In GitHub Actions they send none, and the data repository's scripts send ci-<repository> instead, so CI is not counted as use of the examples.

◆ DD_LITE_RELATIVE_PATH

pub const DD_LITE_RELATIVE_PATH

The Lite Device Detection data file in the data repository.

◆ DD_PATH_ENV_VAR

pub const DD_PATH_ENV_VAR

The environment variable giving an explicit Device Detection data-file path.

◆ DOWNLOADS_TRIED

DOWNLOADS_TRIED
static

The links this process has already run the download script for.

Each file is tried once, and the lock means two threads never download one together.

◆ Enterprise

Enterprise

Force the Enterprise file from the Enterprise share.

Resolves to None when the share is not reachable.

◆ EnterpriseOrAsn

EnterpriseOrAsn

The Enterprise file if the share is reachable, otherwise the ASN file from the data repository.

For the performance and update examples, whose properties do not matter to what they show.

◆ EnterpriseOrLite

EnterpriseOrLite

The Enterprise file if the share is reachable, otherwise the Lite file from the data repository.

For the examples that show location or registration properties.

◆ GITHUB_ACTIONS_ENV_VAR

const GITHUB_ACTIONS_ENV_VAR

The environment variable GitHub Actions sets to true in every step.

◆ has_pwsh

windows has_pwsh

Whether PowerShell 7, pwsh, is on the PATH.

◆ in_github_actions

windows in_github_actions

Whether this runs in GitHub Actions, where no source is sent.

◆ IPI_ASN_RELATIVE_PATH

pub const IPI_ASN_RELATIVE_PATH

The ASN IP Intelligence data file in the data repository, giving Asn and AsnName.

It is a download of a few megabytes, so the examples whose properties do not matter to what they show read it, as do the examples' tests.

◆ IPI_ENTERPRISE_FILE_NAME

pub const IPI_ENTERPRISE_FILE_NAME

The Enterprise IP Intelligence data-file name on the Enterprise share.

◆ IPI_ENTERPRISE_SHARE_ENV_VAR

pub const IPI_ENTERPRISE_SHARE_ENV_VAR

The environment variable giving the root of the dated Enterprise IP Intelligence share, which holds the latest data file under a YYYY/MM/DD subdirectory.

Unset by default, so the Enterprise tier is skipped unless a deployment points this at a reachable share.

◆ IPI_LITE_RELATIVE_PATH

pub const IPI_LITE_RELATIVE_PATH

The Lite IP Intelligence data file in the data repository, giving RegisteredName, RegisteredOwner and RegisteredCountry.

It is a download of a few hundred megabytes. The examples that show location or registration properties read it when no other file is set.

◆ IPI_PATH_ENV_VAR

pub const IPI_PATH_ENV_VAR

The environment variable giving an explicit IP Intelligence data-file path.

◆ Lite

Lite

Force the Lite file ([IPI_LITE_RELATIVE_PATH]), free from the data repository and much larger than the ASN file.

◆ POWERSHELL_MODULE_PATH_ENV_VAR

const POWERSHELL_MODULE_PATH_ENV_VAR

The module path Windows PowerShell must not inherit from PowerShell 7.

With PowerShell 7's module folders it cannot load its own modules, and the data repository's script stops because Get-FileHash is not recognised.

◆ removed

for name in &self removed
Initial value:
{
command.env_remove(name)

Variables removed from the environment the command runs in.