Module uri 

Available on crate feature net only.

First-class URI support for rama.

This module hosts the rama-native URI type. It works for any RFC 3986 URI — http(s), ws(s), ftp, mailto:, urn:, file:, custom schemes — not just HTTP. HTTP-specific shapes (e.g. asterisk-form * from RFC 9112 §3.2.4) are supported but called out as such.

Graceful by default, lossless on parse (no silent normalization), preserves fragments, and lets you cheaply mutate components without the into_parts → from_parts dance.

HTTP request-target forms (RFC 9112 §3.2)

All four shapes are reachable, but not through a single auto-detecting entry point — the grammar is ambiguous (host:port parses validly as both authority-form and scheme:opaque-path), and the RFC 3986 tie-break prefers the scheme reading. Callers handling HTTP request- targets pick the entry point that matches their context:

• origin-form (/path?query) — Uri::parse
• absolute-form (scheme://...) — Uri::parse
• authority-form (host:port, for CONNECT) — Uri::parse_authority_form
• asterisk-form (*, for OPTIONS) — Uri::parse

Migrating from http::Uri

Notable behavioural differences for code switching from http::Uri:

• CONNECT request-targets must use Uri::parse_authority_form. http::Uri::from_str("example.com:443") silently misparsed the target; rama’s parse follows RFC 3986 and reads it as scheme=example.com / path=443. Proxies handling CONNECT must route through the dedicated entry point or the tie-break will quietly route wrong.
• Out-of-range port → Err. http::Uri silently discards ports outside u16; rama returns ParseError::InvalidComponent tagged with Component::Port.
• Empty host with port (http://:8080/) → Err. http::Uri accepted; rama doesn’t.
• Control bytes anywhere → Err. Browsers strip CR/LF/Tab; rama refuses (smuggling defense).
• Non-special schemes (urn:, data:, mailto:) parse correctly. http::Uri either rejected them or misparsed mailto:user@… as authority-bearing. rama follows RFC 3986 opaque-path semantics.

What lives where

• Uri (this file) — the opaque public type
• URI-component borrowed views: PathRef, QueryRef, FragmentRef
• URI-component owned mutable types: Query, Fragment
• Errors: ParseError, UriError

Host-related borrowed views live with their owned counterparts in crate::address (HostRef, DomainRef).

Scheme is Protocol; authority is Authority; host is Host — Uri doesn’t re-export these.

Modules

util

Preserved utility submodule (re-exports the percent_encoding crate).

Structs

Fragment

Owned fragment component (the part after #, sans the # itself).

FragmentRef

Borrowed view of a URI fragment component (no leading #).

PathMut

Mutable view of a Uri’s path component.

PathRef

Borrowed view of a URI path.

PathSegment

One segment in a URI path — the bytes between two / separators (or between a / and the end of the path).

PathSegments

Iterator over the segments of a URI path. Created by PathRef::segments.

Query

Owned query component. Cheaply mutable in-place via the QueryMut RAII guard.

QueryDeserializeError

Returned by QueryRef::deserialize / Query::deserialize when the query string cannot be converted into the target type — type mismatch, missing required field, malformed encoding, or an escaped value being fed into a non-owning &str field.

QueryDrain

Iterator yielding owned QueryPairs drained from a QueryMut. Created by QueryMut::drain.

QueryMut

Mutable view of a Uri’s query component.

QueryPair

One owned name[=value] pair, cheap to clone. Produced by QueryMut::pop and QueryMut::drain — popping a pair off a query doesn’t copy the byte content (the buffer is refcount-shared with the source).

QueryPairRef

Borrowed name[=value] pair view. Yielded by QueryRef::pairs / Query::pairs.

QueryPairs

Iterator over the name[=value] pairs of a URI query string. Created by QueryRef::pairs / Query::pairs.

QueryRef

Borrowed view of a URI query component (no leading ?).

Uri

First-class URI value.

UriRef

Borrowed snapshot of a Uri’s components.

Enums

Component

Which URI component a ParseError or UriError refers to.

ParseError

Reasons parsing a byte string into a Uri can fail.

ResolveError

Errors from Uri::resolve / Uri::resolve_strict.

UriError

Reasons an operation on an already-parsed Uri can fail.

WireError

Error returned when a wire-form contract can’t be honoured.

Traits

IntoUriComponent

Sealed marker — types accepted by URI component setters.

IntoUriInput

Marker trait for inputs accepted by Uri::parse and Uri::parse_strict.