Struct pavex::http::Uri

pub struct Uri { /* private fields */ }
Expand description

The URI component of a request.

For HTTP 1, this is included as part of the request line. From Section 5.3, Request Target:

Once an inbound connection is obtained, the client sends an HTTP request message (Section 3) with a request-target derived from the target URI. There are four distinct formats for the request-target, depending on both the method being requested and whether the request is to a proxy.

request-target = origin-form
               / absolute-form
               / authority-form
               / asterisk-form

The URI is structured as follows:

abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1
|-|   |-------------------------------||--------| |-------------------| |-----|
 |                  |                       |               |              |
scheme          authority                 path            query         fragment

For HTTP 2.0, the URI is encoded using pseudoheaders.

§Examples

use http::Uri;

let uri = "/foo/bar?baz".parse::<Uri>().unwrap();
assert_eq!(uri.path(), "/foo/bar");
assert_eq!(uri.query(), Some("baz"));
assert_eq!(uri.host(), None);

let uri = "https://www.rust-lang.org/install.html".parse::<Uri>().unwrap();
assert_eq!(uri.scheme_str(), Some("https"));
assert_eq!(uri.host(), Some("www.rust-lang.org"));
assert_eq!(uri.path(), "/install.html");

Implementations§

§

impl Uri

pub fn builder() -> Builder

Creates a new builder-style object to manufacture a Uri.

This method returns an instance of Builder which can be usd to create a Uri.

§Examples
use http::Uri;

let uri = Uri::builder()
    .scheme("https")
    .authority("hyper.rs")
    .path_and_query("/")
    .build()
    .unwrap();

pub fn from_parts(src: Parts) -> Result<Uri, InvalidUriParts>

Attempt to convert a Parts into a Uri.

§Examples

Relative URI

let mut parts = Parts::default();
parts.path_and_query = Some("/foo".parse().unwrap());

let uri = Uri::from_parts(parts).unwrap();

assert_eq!(uri.path(), "/foo");

assert!(uri.scheme().is_none());
assert!(uri.authority().is_none());

Absolute URI

let mut parts = Parts::default();
parts.scheme = Some("http".parse().unwrap());
parts.authority = Some("foo.com".parse().unwrap());
parts.path_and_query = Some("/foo".parse().unwrap());

let uri = Uri::from_parts(parts).unwrap();

assert_eq!(uri.scheme().unwrap().as_str(), "http");
assert_eq!(uri.authority().unwrap(), "foo.com");
assert_eq!(uri.path(), "/foo");

pub fn from_maybe_shared<T>(src: T) -> Result<Uri, InvalidUri>
where T: AsRef<[u8]> + 'static,

Attempt to convert a Bytes buffer to a Uri.

This will try to prevent a copy if the type passed is the type used internally, and will copy the data if it is not.

pub fn from_static(src: &'static str) -> Uri

Convert a Uri from a static string.

This function will not perform any copying, however the string is checked to ensure that it is valid.

§Panics

This function panics if the argument is an invalid URI.

§Examples
let uri = Uri::from_static("http://example.com/foo");

assert_eq!(uri.host().unwrap(), "example.com");
assert_eq!(uri.path(), "/foo");

pub fn into_parts(self) -> Parts

Convert a Uri into Parts.

§Note

This is just an inherent method providing the same functionality as let parts: Parts = uri.into()

§Examples
let uri: Uri = "/foo".parse().unwrap();

let parts = uri.into_parts();

assert_eq!(parts.path_and_query.unwrap(), "/foo");

assert!(parts.scheme.is_none());
assert!(parts.authority.is_none());

pub fn path_and_query(&self) -> Option<&PathAndQuery>

Returns the path & query components of the Uri

pub fn path(&self) -> &str

Get the path of this Uri.

Both relative and absolute URIs contain a path component, though it might be the empty string. The path component is case sensitive.

abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1
                                       |--------|
                                            |
                                          path

If the URI is * then the path component is equal to *.

§Examples

A relative URI


let uri: Uri = "/hello/world".parse().unwrap();

assert_eq!(uri.path(), "/hello/world");

An absolute URI

let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert_eq!(uri.path(), "/hello/world");

pub fn scheme(&self) -> Option<&Scheme>

Get the scheme of this Uri.

The URI scheme refers to a specification for assigning identifiers within that scheme. Only absolute URIs contain a scheme component, but not all absolute URIs will contain a scheme component. Although scheme names are case-insensitive, the canonical form is lowercase.

abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1
|-|
 |
scheme
§Examples

Absolute URI

use http::uri::{Scheme, Uri};

let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert_eq!(uri.scheme(), Some(&Scheme::HTTP));

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.scheme().is_none());

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

Get the scheme of this Uri as a &str.

§Example
let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert_eq!(uri.scheme_str(), Some("http"));

pub fn authority(&self) -> Option<&Authority>

Get the authority of this Uri.

The authority is a hierarchical element for naming authority such that the remainder of the URI is delegated to that authority. For HTTP, the authority consists of the host and port. The host portion of the authority is case-insensitive.

The authority also includes a username:password component, however the use of this is deprecated and should be avoided.

abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1
      |-------------------------------|
                    |
                authority
§Examples

Absolute URI

let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

assert_eq!(uri.authority().map(|a| a.as_str()), Some("example.org:80"));

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.authority().is_none());

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

Get the host of this Uri.

The host subcomponent of authority is identified by an IP literal encapsulated within square brackets, an IPv4 address in dotted- decimal form, or a registered name. The host subcomponent is case-insensitive.

abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1
                        |---------|
                             |
                            host
§Examples

Absolute URI

let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

assert_eq!(uri.host(), Some("example.org"));

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.host().is_none());

pub fn port(&self) -> Option<Port<&str>>

Get the port part of this Uri.

The port subcomponent of authority is designated by an optional port number following the host and delimited from it by a single colon (“:”) character. It can be turned into a decimal port number with the as_u16 method or as a str with the as_str method.

abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1
                                    |-|
                                     |
                                    port
§Examples

Absolute URI with port

let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

let port = uri.port().unwrap();
assert_eq!(port.as_u16(), 80);

Absolute URI without port

let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert!(uri.port().is_none());

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.port().is_none());

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

Get the port of this Uri as a u16.

§Example
let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

assert_eq!(uri.port_u16(), Some(80));

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

Get the query string of this Uri, starting after the ?.

The query component contains non-hierarchical data that, along with data in the path component, serves to identify a resource within the scope of the URI’s scheme and naming authority (if any). The query component is indicated by the first question mark (“?”) character and terminated by a number sign (“#”) character or by the end of the URI.

abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1
                                                  |-------------------|
                                                            |
                                                          query
§Examples

Absolute URI

let uri: Uri = "http://example.org/hello/world?key=value".parse().unwrap();

assert_eq!(uri.query(), Some("key=value"));

Relative URI with a query string component

let uri: Uri = "/hello/world?key=value&foo=bar".parse().unwrap();

assert_eq!(uri.query(), Some("key=value&foo=bar"));

Relative URI without a query string component

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.query().is_none());

Trait Implementations§

§

impl Clone for Uri

§

fn clone(&self) -> Uri

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
§

impl Debug for Uri

§

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

Formats the value using the given formatter. Read more
§

impl Default for Uri

Returns a Uri representing /

§

fn default() -> Uri

Returns the “default value” for a type. Read more
§

impl Display for Uri

§

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

Formats the value using the given formatter. Read more
§

impl From<Authority> for Uri

Convert an Authority into a Uri.

§

fn from(authority: Authority) -> Uri

Converts to this type from the input type.
§

impl From<PathAndQuery> for Uri

Convert a PathAndQuery into a Uri.

§

fn from(path_and_query: PathAndQuery) -> Uri

Converts to this type from the input type.
§

impl From<Uri> for Builder

§

fn from(uri: Uri) -> Builder

Converts to this type from the input type.
§

impl From<Uri> for Parts

Convert a Uri into Parts

§

fn from(src: Uri) -> Parts

Converts to this type from the input type.
§

impl FromStr for Uri

§

type Err = InvalidUri

The associated error which can be returned from parsing.
§

fn from_str(s: &str) -> Result<Uri, InvalidUri>

Parses a string s to return a value of this type. Read more
§

impl Hash for Uri

§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
§

impl<'a> PartialEq<&'a str> for Uri

§

fn eq(&self, other: &&'a str) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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<'a> PartialEq<Uri> for &'a str

§

fn eq(&self, uri: &Uri) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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 PartialEq<Uri> for str

§

fn eq(&self, uri: &Uri) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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 PartialEq<str> for Uri

§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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 PartialEq for Uri

§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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<'a> TryFrom<&'a [u8]> for Uri

§

type Error = InvalidUri

The type returned in the event of a conversion error.
§

fn try_from(t: &'a [u8]) -> Result<Uri, <Uri as TryFrom<&'a [u8]>>::Error>

Performs the conversion.
§

impl<'a> TryFrom<&'a String> for Uri

§

type Error = InvalidUri

The type returned in the event of a conversion error.
§

fn try_from(t: &'a String) -> Result<Uri, <Uri as TryFrom<&'a String>>::Error>

Performs the conversion.
§

impl<'a> TryFrom<&'a Uri> for Uri

§

type Error = Error

The type returned in the event of a conversion error.
§

fn try_from(src: &'a Uri) -> Result<Uri, <Uri as TryFrom<&'a Uri>>::Error>

Performs the conversion.
§

impl<'a> TryFrom<&'a str> for Uri

§

type Error = InvalidUri

The type returned in the event of a conversion error.
§

fn try_from(t: &'a str) -> Result<Uri, <Uri as TryFrom<&'a str>>::Error>

Performs the conversion.
§

impl TryFrom<Parts> for Uri

§

type Error = InvalidUriParts

The type returned in the event of a conversion error.
§

fn try_from(src: Parts) -> Result<Uri, <Uri as TryFrom<Parts>>::Error>

Performs the conversion.
§

impl TryFrom<String> for Uri

§

type Error = InvalidUri

The type returned in the event of a conversion error.
§

fn try_from(t: String) -> Result<Uri, <Uri as TryFrom<String>>::Error>

Performs the conversion.
§

impl TryFrom<Vec<u8>> for Uri

§

type Error = InvalidUri

The type returned in the event of a conversion error.
§

fn try_from(vec: Vec<u8>) -> Result<Uri, <Uri as TryFrom<Vec<u8>>>::Error>

Performs the conversion.
§

impl Eq for Uri

Auto Trait Implementations§

§

impl !Freeze for Uri

§

impl RefUnwindSafe for Uri

§

impl Send for Uri

§

impl Sync for Uri

§

impl Unpin for Uri

§

impl UnwindSafe for Uri

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more