Struct Uri 

pub struct Uri { /* private fields */ }

Available on crate feature net only.

First-class URI value.

Represents any RFC 3986 URI-reference — an absolute URI (http://example.com/path), a network-path (//host/path), an origin-form path (/path?query), a relative reference (../foo, ?y, #frag), or the HTTP asterisk-form (*). Use is_absolute to check for the scheme-bearing case.

Opaque — fields are private. Construct via Uri::parse (strict shapes only) or Uri::parse_reference (all URI-references including relatives); inspect via typed accessors (scheme, path, query, fragment, host, port, userinfo, authority); mutate via the set_* / clear_* methods.

Clone is cheap: Asterisk is zero-cost, Lazy / Owned clone is one atomic refcount bump on the inner Arc.

Logging safety

The Debug impl redacts the userinfo password portion (anything after the first : inside user:pass@host), rendering it as "***". This is the safe default for tracing spans and log lines — a raw Debug-print would otherwise leak credentials into observability sinks. The username portion is rendered as-is. Display deliberately does not redact (it is the wire-faithful form); use a dedicated wire writer such as write_http_origin_form when serializing for HTTP — those drop the userinfo entirely per RFC 9110 §4.2.4.

Implementations

impl Uri

pub fn write_http_origin_form( &self, buf: &mut BytesMut, ) -> Result<(), WireError>

HTTP/1.1 origin-form request-target: /path[?query].

Used for normal requests to an origin server (the common case). Empty path is normalised to /. Scheme, authority, and fragment are stripped — origin-form carries only the path-and-query.

Errors with WireError::AsteriskMismatch if the URI is * — asterisk-form is its own request-target form (write * directly, it’s a one-byte literal).

pub fn write_http_absolute_form( &self, buf: &mut BytesMut, ) -> Result<(), WireError>

HTTP/1.1 absolute-form request-target: scheme:[//authority]path[?query].

Used by clients sending through a forward proxy. Userinfo and fragment are stripped (RFC 9110 §§4.2.4, 7.1).

pub fn write_http_authority_form( &self, buf: &mut BytesMut, ) -> Result<(), WireError>

HTTP/1.1 authority-form request-target: host[:port].

Only used for CONNECT. Userinfo, scheme, path, query, and fragment are all stripped.

Wire fidelity: an OptPort::Empty port emits a bare trailing : (e.g. example.com:), mirroring the parser. RFC 3986 §3.2.3 grammar permits this; some peers may reject. Call Uri::canonicalize first if you want the empty marker normalized away.

pub fn write_h2_path(&self, buf: &mut BytesMut)

HTTP/2 / HTTP/3 :path pseudo-header content.

Same shape as origin-form (empty path → /), with one exception: asterisk-form requests carry * in :path per RFC 9113 §8.3.1, so this method writes * for an asterisk URI rather than erroring.

pub fn write_h2_authority(&self, buf: &mut BytesMut) -> Result<(), WireError>

HTTP/2 / HTTP/3 :authority pseudo-header content: host[:port].

Userinfo is omitted per RFC 9113 §8.3.1.

Wire fidelity: see write_http_authority_form for the OptPort::Empty round-trip behavior.

pub fn write_h2_scheme(&self, buf: &mut BytesMut) -> Result<(), WireError>

HTTP/2 / HTTP/3 :scheme pseudo-header content (e.g. https).

impl Uri

pub const MAX_LEN: usize = parser::MAX_URI_LEN

Maximum input length accepted by any of the Uri::parse* entry points. Inputs longer than this fail with ParseError::TooLong. Capped at u16::MAX - 1 (component offsets are u16).

pub fn parse<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Parse a URI. Graceful: accepts what browsers and curl accept (e.g. unreserved chars outside RFC 3986’s pchar, raw UTF-8 in path/query/fragment). Rejects: ASCII control bytes anywhere, empty input, and inputs longer than the internal cap.

pub fn parse_strict<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Parse a URI in RFC 3986 strict mode. Inputs that would parse under Uri::parse but violate the strict grammar return ParseError::StrictViolation.

pub fn parse_reference<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Parse any RFC 3986 URI-reference — absolute URI or relative-ref.

Accepts everything parse accepts, plus the relative-ref grammar from §4.2:

• empty input (same-document reference)
• //host/path (network-path reference)
• g, g/h, ../g (path-noscheme)
• ?y (query-only)
• #s (fragment-only)

Use this when parsing a reference to feed into resolve.

pub fn parse_reference_strict<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Strict variant of parse_reference.

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

Parse a &'static str URI, panicking on invalid input. Convenient for compile-time-known URIs (constants, defaults, tests, examples) where the failure mode is “this binary contains a typo” rather than runtime input handling.

Uses the graceful parser — same shape as parse, just without the Result. Use parse for any runtime / user-supplied input.

Panics

Panics with the underlying ParseError if s is not a valid URI.

pub fn parse_authority_form<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Parse the HTTP authority-form request-target used by CONNECT (RFC 9112 §3.2.3).

Dedicated entry point because parse cannot disambiguate authority-form from scheme:opaque-path — example.com:443 is grammatically both authority(example.com:443) and scheme(example.com) + opaque-path(443), and RFC 3986 prefers the scheme reading. HTTP proxies and clients handling CONNECT must route those targets through this function instead.

Graceful grammar (this method): [userinfo@]host[:port]

Userinfo and a missing port are accepted as graceful conveniences for HTTP tooling — userinfo is preserved on the value but stripped by write_http_authority_form before serialization, and the missing port is treated as “fill in from the scheme” by the HTTP layer. Wire output remains RFC 9112-compliant.

For a parser that rejects everything outside host:port, use parse_authority_form_strict.

The returned Uri has no scheme, no path, no query, and no fragment — only the authority components (host, port, userinfo).

Returns ParseError::InvalidComponent for inputs that contain any of /, ?, or # — those bytes indicate a non-authority shape and the caller should use parse instead.

pub fn parse_authority_form_strict<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Strict-mode variant of parse_authority_form: enforces RFC 9112 §3.2.3 exactly.

Grammar: host ":" port. Userinfo and a missing port both return ParseError::StrictViolation; everything else matches parse_authority_form.

pub fn is_asterisk(&self) -> bool

Returns true if this is the OPTIONS-* request-target.

pub fn is_absolute(&self) -> bool

Returns true if this is an absolute URI — has a scheme. Inverse case is a URI-reference without a scheme (relative reference, origin-form path, or the asterisk).

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

Returns the scheme component, or None if the URI has none (origin-form URIs and the asterisk-form).

pub fn path(&self) -> Option<PathRef<'_>>

Returns the path component, or None for the asterisk-form (which has no path — the request-target is *).

For every other form (origin, absolute with or without authority) a path is always present per RFC 3986 §3.3 — possibly empty (e.g. http://example.com has an empty path-abempty).

pub fn query(&self) -> Option<QueryRef<'_>>

Returns the query component, or None if the URI has no ? delimiter on the wire.

Some(empty) vs None matters — ? followed by nothing is distinct from no ? at all (load-bearing for SigV4 / cache keys / proxy fidelity).

pub fn fragment(&self) -> Option<FragmentRef<'_>>

Returns the fragment component, or None if the URI has no # delimiter on the wire. Same Some(empty) vs None distinction as query.

Note: the wire writer for HTTP request-targets strips the fragment per RFC 9110 §7.1. This accessor returns it for inspection / logging / preservation purposes.

pub fn host(&self) -> Option<HostRef<'_>>

Returns the authority’s host, or None if the URI has no authority (origin-form /foo, asterisk-form *, opaque-path urn:isbn:0, etc.).

This is a shortcut for accessing just the host component; Uri::authority gives the full bundle (host + port + userinfo).

pub fn port(&self) -> OptPort

Returns the port as an OptPort — Unset / Empty / Set(u16).

Most callers want port_u16 instead — it returns Option<u16> and collapses the wire-only Empty distinction. Use port() only when you need to preserve the difference between host (no colon) and host: (colon with no digits) on the wire.

Scheme default ports are NOT substituted — that’s a canonicalization policy decision the caller makes (e.g. Protocol::default_port() if the URI’s scheme is known).

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

Relaxed view of the port — Set(n) → Some(n), Unset / Empty both → None. Use when the wire distinction between “no colon” and “empty colon” doesn’t matter (e.g. dialing).

pub fn userinfo(&self) -> Option<UserInfoRef<'_>>

Returns the userinfo component, or None if the URI has no authority OR the authority has no @.

Some("") (the @host form — empty userinfo before @) is distinct from None (no @ at all). Wire fidelity preserved.

pub fn authority(&self) -> Option<AuthorityRef<'_>>

Returns the full authority component (host + port + userinfo) as a borrowed view, or None if the URI has no authority (origin-form, asterisk-form, opaque-path schemes).

For just the host or just the port, Uri::host and Uri::port are slightly cheaper shortcuts (no extra struct).

pub fn with_path(self, path: impl IntoUriComponent) -> Uri

Replace the path. Bytes outside RFC 3986 pchar ∪ {'/'} are percent-encoded — pass raw (decoded) values, the library serializes them correctly. Already-legal owned inputs move without allocating.

pub fn set_path(&mut self, path: impl IntoUriComponent) -> &mut Uri

Replace the path. Bytes outside RFC 3986 pchar ∪ {'/'} are percent-encoded — pass raw (decoded) values, the library serializes them correctly. Already-legal owned inputs move without allocating.

pub fn unset_path(&mut self) -> &mut Uri

Clear the path (empty bytes — no leading /). Path is never absent in the URI grammar, so this is the canonical “no path” state, not a removal.

pub fn without_path(self) -> Uri

Consuming form of unset_path.

pub fn path_mut(&mut self) -> PathMut<'_>

Returns a PathMut guard for incremental path mutation — push_segment, pop_segment, clear.

pub fn maybe_with_query(self, query: Option<Query>) -> Uri

Set, clear, or assign the query. Bytes taken as-is — no re-encoding. Pair with set_query_from_bytes when you have raw bytes that need pct-encoding.

pub fn maybe_set_query(&mut self, query: Option<Query>) -> &mut Uri

Set, clear, or assign the query. Bytes taken as-is — no re-encoding. Pair with set_query_from_bytes when you have raw bytes that need pct-encoding.

pub fn with_query(self, query: Query) -> Uri

Set, clear, or assign the query. Bytes taken as-is — no re-encoding. Pair with set_query_from_bytes when you have raw bytes that need pct-encoding.

pub fn set_query(&mut self, query: Query) -> &mut Uri

Set, clear, or assign the query. Bytes taken as-is — no re-encoding. Pair with set_query_from_bytes when you have raw bytes that need pct-encoding.

pub fn without_query(self) -> Uri

Set, clear, or assign the query. Bytes taken as-is — no re-encoding. Pair with set_query_from_bytes when you have raw bytes that need pct-encoding.

pub fn unset_query(&mut self) -> &mut Uri

Set, clear, or assign the query. Bytes taken as-is — no re-encoding. Pair with set_query_from_bytes when you have raw bytes that need pct-encoding.

pub fn set_query_from_bytes(&mut self, query: impl IntoUriComponent) -> &mut Uri

Encode raw bytes into a Query and assign. Bytes outside pchar ∪ {'/', '?'} are percent-encoded (including #).

pub fn with_query_from_bytes(self, query: impl IntoUriComponent) -> Uri

Consuming form of set_query_from_bytes.

pub fn query_mut(&mut self) -> QueryMut<'_>

Returns a QueryMut guard for incremental query mutation — push_pair, push_key, pop, drain.

pub fn set_scheme(&mut self, scheme: impl Into<Protocol>) -> &mut Uri

Set the scheme. Accepts any Into<Protocol> — most usefully Protocol itself, but also &str / String (via the existing Protocol::From<&str> chain that’s used throughout rama’s HTTP / SOCKS5 / TLS plumbing).

The scheme is a presentation-only component for the parsed URI — canonicalize lowercases custom schemes per RFC 3986 §6.2.2.1, known schemes (http, https, ws, wss, socks5, socks5h) are already case-normalised at construction.

pub fn with_scheme(self, scheme: impl Into<Protocol>) -> Uri

Consuming form of set_scheme.

pub fn unset_scheme(&mut self) -> &mut Uri

Clear the scheme — turns an absolute-form URI into a relative-reference. Shortcut for the None arm of maybe_set_scheme.

pub fn without_scheme(self) -> Uri

Consuming form of unset_scheme.

pub fn maybe_set_scheme( &mut self, scheme: impl Into<Option<Protocol>>, ) -> &mut Uri

Set or clear the scheme in one call. Some(scheme) is equivalent to set_scheme; None is equivalent to unset_scheme.

pub fn maybe_with_scheme(self, scheme: impl Into<Option<Protocol>>) -> Uri

Consuming form of maybe_set_scheme.

pub fn canonicalize(self) -> Uri

Apply RFC 3986 §6.2.2 syntax-based normalization. Returns a new Uri with:

• Host promoted from Host::Uninterpreted to typed Domain / IpAddr when the bytes decode to one (%6D → m; pct-encoded UTF-8 → IDN→ACE under the idna feature). Sub-delim reg-name and IPvFuture stay Uninterpreted — no canonical typed form exists.
• Pct-encoded octets that map to unreserved characters (%41 → A, %7E → ~) decoded in path / query / fragment. Reserved / sub-delim octets stay encoded; their hex digits are uppercased per §6.2.2.1.
• Default port dropped (http://example.com:80/ → http://example.com/).
• Empty path replaced with / when an authority is present.
• Dot-segments (., ..) removed from the path per §6.2.2.3.

Wire-fidelity is lost. Use this when you specifically want a canonical form — typically client-side, building HTTP requests from user input. Server / proxy / forwarding code that needs to preserve received bytes should leave the URI unmodified.

pub fn parse_canonical<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Parse input and immediately apply canonicalize. One-shot convenience for client-side URI construction from user input.

pub fn parse_canonical_strict<T>(input: T) -> Result<Uri, ParseError>

where T: IntoUriInput,

Strict variant of parse_canonical — rejects RFC 3986 grammar violations before canonicalizing.

pub fn resolve(&self, reference: &Uri) -> Result<Uri, ResolveError>

Resolve reference against self (the base URI).

Graceful — matches browser / curl behaviour:

• If the reference shares the base’s scheme, the scheme is treated as inherited (RFC 3986 §5.2.2 non-strict loophole).
• Excess .. segments past the path root are silently clamped.

Use resolve_strict to reject both.

Errors when the base has no scheme, the base or reference is the asterisk-form, or the resolved URI exceeds the internal cap.

pub fn resolve_strict(&self, reference: &Uri) -> Result<Uri, ResolveError>

Resolve reference against self in strict mode (RFC 3986 §5.2.2):

• No scheme-matching loophole — a reference with a scheme stays absolute even if its scheme matches the base’s.
• A .. segment that would traverse past the path root is an error (ResolveError::DotSegmentTraversalPastRoot).

pub fn with_fragment(self, fragment: impl IntoUriComponent) -> Uri

Set the fragment. Leading # is implicit. Bytes outside pchar ∪ {'/', '?'} are percent-encoded.

pub fn set_fragment(&mut self, fragment: impl IntoUriComponent) -> &mut Uri

Set the fragment. Leading # is implicit. Bytes outside pchar ∪ {'/', '?'} are percent-encoded.

pub fn unset_fragment(&mut self) -> &mut Uri

Remove the fragment entirely (no # on the wire — distinct from an empty-fragment # per §3.5).

pub fn without_fragment(self) -> Uri

Consuming form of unset_fragment.

pub fn maybe_with_authority(self, authority: Option<Authority>) -> Uri

Set or remove the authority (userinfo + host + port).

pub fn maybe_set_authority(&mut self, authority: Option<Authority>) -> &mut Uri

Set or remove the authority (userinfo + host + port).

pub fn with_authority(self, authority: Authority) -> Uri

Set or remove the authority (userinfo + host + port).

pub fn set_authority(&mut self, authority: Authority) -> &mut Uri

Set or remove the authority (userinfo + host + port).

pub fn without_authority(self) -> Uri

Set or remove the authority (userinfo + host + port).

pub fn unset_authority(&mut self) -> &mut Uri

Set or remove the authority (userinfo + host + port).

pub fn set_host(&mut self, host: impl Into<Host>) -> &mut Uri

Set just the host, preserving any existing userinfo and port.

Accepts any Into<Host> — Host, Domain, IpAddr, Ipv4Addr, or Ipv6Addr. For inputs that need parsing (&str / String), use try_set_host instead.

If the URI has no authority yet, one is created with the given host and no userinfo / port. Existing authority parts are preserved otherwise.

pub fn with_host(self, host: impl Into<Host>) -> Uri

Consuming form of set_host.

pub fn try_set_host<H>(&mut self, host: H) -> Result<&mut Uri, UriError>

where H: TryInto<Host>, <H as TryInto<Host>>::Error: Into<Box<dyn Error + Send + Sync>>,

Fallible host setter. Accepts any TryInto<Host> — typically &str / String / &[u8] / Vec<u8>.

Routes through Host::try_from which does IP-first, then Domain::try_from (IDN-normalising non-ASCII to ACE under the idna feature). So try_set_host("münchen.de") ends up with a canonical Host::Name(Domain("xn--mnchen-3ya.de")) — exactly what client-side code building URIs from user input expects.

Returns UriError::ComponentConversion tagged with Component::Host when the upstream conversion fails — the inner boxed cause carries the original error.

pub fn try_with_host<H>(self, host: H) -> Result<Uri, UriError>

where H: TryInto<Host>, <H as TryInto<Host>>::Error: Into<Box<dyn Error + Send + Sync>>,

Consuming form of try_set_host.

pub fn set_port(&mut self, port: impl Into<OptPort>) -> &mut Uri

Set just the port, preserving the rest of the authority.

Some(port) sets the explicit port; None clears any existing :port suffix (scheme default ports are not substituted — they remain implicit). If the URI has no authority yet, one is created with the loopback IPv4 host as a placeholder — callers building a URI from scratch should set the host before the port for clarity.

pub fn with_port(self, port: impl Into<OptPort>) -> Uri

Consuming form of set_port.

pub fn set_user_info( &mut self, user_info: impl Into<Option<UserInfo>>, ) -> &mut Uri

Set just the user-info, preserving the rest of the authority.

Some(user_info) sets the user[:pass]@ prefix; None clears any existing user-info. If the URI has no authority yet, one is created with the loopback IPv4 host as a placeholder — see set_port for the same caveat.

pub fn with_user_info(self, user_info: impl Into<Option<UserInfo>>) -> Uri

Consuming form of set_user_info.

pub fn unset_user_info(&mut self) -> &mut Uri

Clear the user-info. Shortcut for set_user_info(None).

pub fn without_user_info(self) -> Uri

Consuming form of unset_user_info.

pub fn try_set_user_info<U>( &mut self, user_info: U, ) -> Result<&mut Uri, UriError>

where U: TryInto<UserInfo>, <U as TryInto<UserInfo>>::Error: Into<Box<dyn Error + Send + Sync>>,

Fallible user-info setter. Accepts any TryInto<UserInfo> — typically &str / String. Routes through UserInfo::try_from which enforces the RFC 3986 §3.2.1 userinfo grammar.

pub fn try_with_user_info<U>(self, user_info: U) -> Result<Uri, UriError>

where U: TryInto<UserInfo>, <U as TryInto<UserInfo>>::Error: Into<Box<dyn Error + Send + Sync>>,

Consuming form of try_set_user_info.

impl Uri

pub fn view(&self) -> UriRef<'_>

Borrow this URI as a UriRef — a single match-once snapshot of every component accessor.

Most useful for code that inspects three-or-more components in a row: each Uri::scheme() / host() / path() etc. re-walks the internal match &self.inner { … } per call; view() does the walk once and exposes the results as struct fields.

Trait Implementations

impl Clone for Uri

fn clone(&self) -> Uri

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Uri

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

Uri("…") rendering of the canonical URI form, with the password portion of any userinfo redacted as ***. See the type-level “Logging safety” docs.

impl Display for Uri

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

Writes the canonical URI string: [scheme:][//authority][path][?query][#fragment]. Lazy URIs round-trip byte-for-byte through their source buffer; Owned URIs reassemble from components.

Not the HTTP wire form. This includes userinfo and fragment and preserves the original port — none of which belong on an HTTP request line or in HTTP/2 pseudo-headers. Use the dedicated write_*_form helpers (landing with the relative-resolution work) when serializing for HTTP. Logging a Uri via Display may leak userinfo — use Debug (password-redacted) if the destination is a tracing sink, or strip the userinfo explicitly.

impl FromStr for Uri

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Uri, <Uri as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for Uri

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

where H: Hasher,

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 Uri

fn cmp(&self, other: &Uri) -> 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,

Restrict a value to a certain interval.

impl PartialEq for Uri

fn eq(&self, other: &Uri) -> 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 Uri

fn partial_cmp(&self, other: &Uri) -> 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 TryFrom<&[u8]> for Uri

type Error = ParseError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<&str> for Uri

type Error = ParseError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Bytes> for Uri

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(input: Bytes) -> Result<Uri, <Uri as TryFrom<Bytes>>::Error>

Performs the conversion.

impl TryFrom<String> for Uri

type Error = ParseError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Vec<u8>> for Uri

type Error = ParseError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Eq for Uri