Struct gix_url::Url

pub struct Url {
    pub scheme: Scheme,
    pub port: Option<u16>,
    pub path: BString,
    /* private fields */
}

A URL with support for specialized git related capabilities.

Additionally there is support for deserialization and serialization.

Security Warning

URLs may contain passwords and using standard formatting will redact such password, whereas lossless serialization will contain all parts of the URL. Beware that some URls still print secrets if they use them outside of the designated password fields.

Also note that URLs that fail to parse are typically stored in the resulting error type and printed in full using its display implementation.

Fields

scheme: Scheme

The URL scheme.

port: Option<u16>

The port to use when connecting to a host. If None, standard ports depending on scheme will be used.

path: BString

The path portion of the URL, usually the location of the git repository.

Security Warning

URLs allow paths to start with - which makes it possible to mask command-line arguments as path which then leads to the invocation of programs from an attacker controlled URL. See https://secure.phabricator.com/T12961 for details.

If this value is ever going to be passed to a command-line application, call Self::path_argument_safe() instead.

Implementations

impl Url

Instantiation

pub fn from_parts( scheme: Scheme, user: Option<String>, password: Option<String>, host: Option<String>, port: Option<u16>, path: BString, serialize_alternative_form: bool, ) -> Result<Self, Error>

Create a new instance from the given parts, including a password, which will be validated by parsing them back.

impl Url

Modification

pub fn set_user(&mut self, user: Option<String>) -> Option<String>

Set the given user, or unset it with None. Return the previous value.

pub fn set_password(&mut self, password: Option<String>) -> Option<String>

Set the given password, or unset it with None. Return the previous value.

impl Url

Builder

pub fn serialize_alternate_form(self, use_alternate_form: bool) -> Self

Enable alternate serialization for this url, e.g. file:///path becomes /path.

This is automatically set correctly for parsed URLs, but can be set here for urls created by constructor.

pub fn canonicalize(&mut self, current_dir: &Path) -> Result<(), Error>

Turn a file url like file://relative into file:///root/relative, hence it assures the url’s path component is absolute, using current_dir if needed to achieve that.

impl Url

Access

pub fn user(&self) -> Option<&str>

Return the username mentioned in the URL, if present.

Security Warning

URLs allow usernames to start with - which makes it possible to mask command-line arguments as username which then leads to the invocation of programs from an attacker controlled URL. See https://secure.phabricator.com/T12961 for details.

If this value is ever going to be passed to a command-line application, call Self::user_argument_safe() instead.

pub fn user_as_argument(&self) -> ArgumentSafety<'_>

Classify the username of this URL by whether it is safe to pass as a command-line argument.

Use this method instead of Self::user() if the host is going to be passed to a command-line application. If the unsafe and absent cases need not be distinguished, Self::user_argument_safe() may also be used.

pub fn user_argument_safe(&self) -> Option<&str>

Return the username of this URL if present and if it can’t be mistaken for a command-line argument.

Use this method or Self::user_as_argument() instead of Self::user() if the host is going to be passed to a command-line application. Prefer Self::user_as_argument() unless the unsafe and absent cases need not be distinguished from each other.

pub fn password(&self) -> Option<&str>

Return the password mentioned in the url, if present.

pub fn host(&self) -> Option<&str>

Return the host mentioned in the URL, if present.

Security Warning

URLs allow hosts to start with - which makes it possible to mask command-line arguments as host which then leads to the invocation of programs from an attacker controlled URL. See https://secure.phabricator.com/T12961 for details.

If this value is ever going to be passed to a command-line application, call Self::host_as_argument() or Self::host_argument_safe() instead.

pub fn host_as_argument(&self) -> ArgumentSafety<'_>

Classify the host of this URL by whether it is safe to pass as a command-line argument.

Use this method instead of Self::host() if the host is going to be passed to a command-line application. If the unsafe and absent cases need not be distinguished, Self::host_argument_safe() may also be used.

pub fn host_argument_safe(&self) -> Option<&str>

Return the host of this URL if present and if it can’t be mistaken for a command-line argument.

Use this method or Self::host_as_argument() instead of Self::host() if the host is going to be passed to a command-line application. Prefer Self::host_as_argument() unless the unsafe and absent cases need not be distinguished from each other.

pub fn path_argument_safe(&self) -> Option<&BStr>

Return the path of this URL if it can’t be mistaken for a command-line argument. Note that it always begins with a slash, which is ignored for this comparison.

Use this method instead of accessing Self::path directly if the path is going to be passed to a command-line application, unless it is certain that the leading / will always be included.

pub fn path_is_root(&self) -> bool

Return true if the path portion of the URL is /.

pub fn port_or_default(&self) -> Option<u16>

Return the actual or default port for use according to the URL scheme. Note that there may be no default port either.

impl Url

Transformation

pub fn canonicalized(&self, current_dir: &Path) -> Result<Self, Error>

Turn a file URL like file://relative into file:///root/relative, hence it assures the URL’s path component is absolute, using current_dir if necessary.

impl Url

Serialization

pub fn write_to(&self, out: &mut dyn Write) -> Result<()>

Write this URL losslessly to out, ready to be parsed again.

pub fn to_bstring(&self) -> BString

Transform ourselves into a binary string, losslessly, or fail if the URL is malformed due to host or user parts being incorrect.

impl Url

Deserialization

pub fn from_bytes(bytes: &BStr) -> Result<Self, Error>

Parse a URL from bytes.

Trait Implementations

impl Clone for Url

fn clone(&self) -> Url

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Url

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

Formats the value using the given formatter.

impl Default for Url

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Url

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Url

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

Formats the value using the given formatter.

impl Hash for Url

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Url

fn cmp(&self, other: &Url) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Url

fn eq(&self, other: &Url) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Url

fn partial_cmp(&self, other: &Url) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Url

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&BStr> for Url

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &BStr) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&OsStr> for Url

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &OsStr) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&Path> for Url

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Path) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&str> for Url

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> TryFrom<Cow<'a, BStr>> for Url

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Cow<'a, BStr>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<PathBuf> for Url

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: PathBuf) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<String> for Url

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for Url

impl StructuralPartialEq for Url