Struct UrlContext 

pub struct UrlContext {
    pub base_urls: Arc<[Arc<UrlRef>]>,
    pub url_overrides: Arc<Mutex<HashMap<String, String>>>,
    pub cache: Arc<UrlCache>,
    pub internal_url_registry: Arc<InternalUrlRegistry>,
    pub http_client: Arc<LazyLock<Client>>,
}

Context for URL.

Fields

base_urls: Arc<[Arc<UrlRef>]>

Base URLs.

url_overrides: Arc<Mutex<HashMap<String, String>>>

URL overrides.

cache: Arc<UrlCache>

Cache.

internal_url_registry: Arc<InternalUrlRegistry>

Internal URL registry.

http_client: Arc<LazyLock<Client>>

Available on crate feature http only.

Common HTTP client.

Note that we are using the async version of reqwest::Client rather than the blocking version because 1) the blocking version is not supported in WASM, and 2) we can just use a straightforward blocking wrapper on top of the async client.

Implementations

impl UrlContext

pub fn absolute_url( self: &UrlContextRef, url_representation: &str, ) -> Result<UrlRef, UrlError>

Parses the argument as an absolute URL.

Make sure to call URL::conform or URL::conform_async before calling URL::open or URL::open_async.

To support relative URLs, see url.

If you are expecting either a URL or a file path, consider absolute_url_or_file_path.

pub fn absolute_url_or_file_path( self: &UrlContextRef, url_or_file_path_representation: &str, ) -> Result<UrlRef, UrlError>

Available on crate feature file only.

Parses the argument as either an absolute URL or an absolute file path.

Make sure to call URL::conform or URL::conform_async before calling URL::open or URL::open_async.

Internally, attempts to parse the URL via absolute_url and if that fails treats the URL as an absolute file path and returns a FileUrl.

To support relative URLs and relative file paths, see url_or_file_path.

On Windows note a rare edge case: If there happens to be a drive that has the same name as a supported URL scheme (e.g. “http”) then callers would have to provide a full file URL, e.g. instead of “http:\Dir\file” provide “file:///http:/Dir/file”. Otherwise it would be parsed as a URL of that scheme. rather than a file path.

impl UrlContext

pub async fn url_async( self: &UrlContextRef, url_representation: &str, ) -> Result<UrlRef, UrlError>

Available on crate feature async only.

Parses the argument as either an absolute URL or a path relative to one of the context’s base URls. Relative paths support “..” and “.”.

The returned URL will always have had URL::conform_async called on it, so there is no need to call it again.

Relative paths are tested against the base URLs argument in order. The first valid URL will be returned and the remaining bases will be ignored. Note that bases can be any of any URL type.

If you are expecting either a URL or a file path, consider url_or_file_path_async.

pub async fn url_or_file_path_async( self: &UrlContextRef, url_or_file_path_representation: &str, ) -> Result<UrlRef, UrlError>

Available on crate features async and file only.

Parses the argument as an absolute URL, or an absolute file path, or a path relative to one of the context’s base URLs. Relative paths support “..” and “.”.

The returned URL will always have had URL::conform_async called on it, so there is no need to call it again.

Relative paths are tested against the base URLs argument in order. The first valid URL will be returned and the remaining bases will be ignored. Note that bases can be any of any URL type.

On Windows note a rare edge case: If there happens to be a drive that has the same name as a supported URL scheme (e.g. “http”) then callers would have to provide a full file URL, e.g. instead of “http:\Dir\file” provide “file:///http:/Dir/file”. Otherwise it would be parsed as a URL of that scheme. rather than a file path.

impl UrlContext

pub fn url( self: &UrlContextRef, url_representation: &str, ) -> Result<UrlRef, UrlError>

Available on crate feature blocking only.

Parses the argument as either an absolute URL or a path relative to one of the context’s base URls. Relative paths support “..” and “.”.

The returned URL will always have had URL::conform called on it, so there is no need to call it again.

Relative paths are tested against the base URLs argument in order. The first valid URL will be returned and the remaining bases will be ignored. Note that bases can be any of any URL type.

If you are expecting either a URL or a file path, consider url_or_file_path.

pub fn url_or_file_path( self: &UrlContextRef, url_or_file_path_representation: &str, ) -> Result<UrlRef, UrlError>

Available on crate features blocking and file only.

Parses the argument as an absolute URL, or an absolute file path, or a path relative to one of the context’s base URLs. Relative paths support “..” and “.”.

The returned URL will always have had URL::conform called on it, so there is no need to call it again.

Relative paths are tested against the base URLs argument in order. The first valid URL will be returned and the remaining bases will be ignored. Note that bases can be any of any URL type.

On Windows note a rare edge case: If there happens to be a drive that has the same name as a supported URL scheme (e.g. “http”) then callers would have to provide a full file URL, e.g. instead of “http:\Dir\file” provide “file:///http:/Dir/file”. Otherwise it would be parsed as a URL of that scheme. rather than a file path.

impl UrlContext

pub fn new() -> UrlContextRef

Constructor.

pub fn new_for(cache_base_directory: Option<PathBuf>) -> UrlContextRef

Constructor.

pub fn with_base_urls<UrlRefT>( self: &UrlContextRef, base_urls: Vec<UrlRefT>, ) -> UrlContextRef

where UrlRefT: Into<Arc<UrlRef>>,

Return a child context with different base URLs.

The child context shares everything else with the parent.

pub fn with_cache( self: &UrlContextRef, cache_base_directory: Option<PathBuf>, ) -> UrlContextRef

Return a child context with a different cache.

The child context shares everything else with the parent.

pub fn clone_base_urls(&self) -> Vec<Arc<UrlRef>>

Clone base URLs.

impl UrlContext

pub fn override_url( self: &UrlContextRef, from_url: String, to_url: String, ) -> Result<Option<String>, UrlError>

Override a URL.

pub fn remove_url_override( self: &UrlContextRef, from_url: &String, ) -> Result<Option<String>, UrlError>

Remove a URL override.

pub fn override_global_url( from_url: String, to_url: String, ) -> Result<Option<String>, UrlError>

Override a global URL.

pub fn remove_global_url_override( from_url: &String, ) -> Result<Option<String>, UrlError>

Remove a global URL override.

pub fn get_url_override( self: &UrlContextRef, from_url: &String, ) -> Result<Option<String>, UrlError>

Get a URL override.

Tries the context’s overrides first, the global overrides next.

pub fn get_url_or_override( self: &UrlContextRef, from_url: String, ) -> Result<String, UrlError>

Get a URL’s override or itself.

Tries the context’s overrides first, the global overrides next.

impl UrlContext

pub fn file_url( self: &UrlContextRef, path: PathBuf, host: Option<String>, query: Option<UrlQuery>, fragment: Option<String>, ) -> UrlRef

Available on crate feature file only.

Construct a FileUrl.

pub fn working_dir_url(self: &UrlContextRef) -> Result<UrlRef, UrlError>

Available on crate features file and blocking only.

A valid FileUrl for the current working directory.

pub async fn working_dir_url_async( self: &UrlContextRef, ) -> Result<UrlRef, UrlError>

Available on crate features file and async only.

Async version of working_dir_url.

Note that the blocking version would also work in async. However, we are providing an async version, too, in case the blocking feature is disabled.

pub fn working_dir_url_vec( self: &UrlContextRef, ) -> Result<Vec<UrlRef>, UrlError>

Available on crate features file and blocking only.

A valid FileUrl for the current working directory as a vector.

Useful as the “base_urls” argument of UrlContext::url.

pub async fn working_dir_url_vec_async( self: &UrlContextRef, ) -> Result<Vec<UrlRef>, UrlError>

Available on crate features file and async only.

Async version of working_dir_url_vec.

Note that the blocking version would also work in async. However, we are providing an async version, too, in case the blocking feature is disabled.

impl UrlContext

pub fn git_url( self: &UrlContextRef, conformed_repository_url: UrlRef, path: RelativePathBuf, ) -> Result<UrlRef, UrlError>

Available on crate feature git only.

Construct a GitUrl.

impl UrlContext

pub fn http_url(self: &UrlContextRef, url: Url) -> UrlRef

Available on crate feature http only.

Construct a HttpUrl.

impl UrlContext

pub fn internal_url( self: &UrlContextRef, path: String, host: Option<String>, query: Option<UrlQuery>, fragment: Option<String>, ) -> UrlRef

Construct an InternalUrl.

pub fn register_internal_url( self: &UrlContextRef, path: String, slashable: bool, base_path: Option<String>, format: Option<String>, content: &[u8], ) -> Result<(), UrlError>

Register an InternalUrl.

pub fn deregister_internal_url( self: &UrlContextRef, path: &String, ) -> Result<(), UrlError>

Deregister an InternalUrl.

pub fn update_internal_url( self: &UrlContextRef, path: &String, content: &[u8], ) -> Result<bool, UrlError>

Update the content of an InternalUrl.

pub fn register_global_internal_url( path: String, slashable: bool, base_path: Option<String>, format: Option<String>, content: &[u8], ) -> Result<(), UrlError>

Register a global InternalUrl.

pub fn deregister_global_internal_url(path: &String) -> Result<(), UrlError>

Deregister a global InternalUrl.

pub fn update_global_internal_url( path: &String, content: &[u8], ) -> Result<bool, UrlError>

Update the content of a global InternalUrl.

pub fn read_internal_url( self: &UrlContextRef, path: &String, ) -> Result<Option<ReadableBufferReader>, UrlError>

Read an InternalUrl’s content.

Tries the context’s registry first, the global registry next.

pub fn internal_url_metadata( self: &UrlContextRef, path: &String, ) -> Result<Option<InternalUrlMetadata>, UrlError>

Access an InternalUrl’s metadata.

Tries the context’s registry first, the global registry next.

impl UrlContext

pub fn mock_url( self: &UrlContextRef, url_representation: String, slashable: bool, base_url_representation: Option<String>, query: Option<UrlQuery>, fragment: Option<String>, format: Option<String>, content: Option<&[u8]>, ) -> UrlRef

Construct a MockUrl.

impl UrlContext

pub fn tar_url( self: &UrlContextRef, conformed_archive_url: UrlRef, path: RelativePathBuf, compression: Option<TarCompression>, ) -> UrlRef

Available on crate feature tar only.

Construct a TarUrl.

impl UrlContext

pub fn zip_url( self: &UrlContextRef, conformed_archive_url: UrlRef, path: RelativePathBuf, ) -> UrlRef

Available on crate feature zip only.

Construct a ZipUrl.

Trait Implementations

impl Clone for UrlContext

fn clone(&self) -> UrlContext

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UrlContext

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

Formats the value using the given formatter.