Skip to main content

Module uri

rama::net

Module uri 

Available on crate feature net only.
Expand description

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:

§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

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 #).
PathCaptures
Captured values from a successful PathPattern::captures match.
PathMatchOptions
Options controlling path prefix/suffix matching and stripping (PathRef::has_prefix_with_opts, super::PathMut::strip_prefix_with_opts, …).
PathMut
Mutable view of a Uri’s path component.
PathPattern
A compiled path pattern.
PathPatternSegmentSpecificity
Specificity metadata for one compiled PathPattern segment.
PathRef
Borrowed view of a URI path.
PathRouteCaptures
Decoded captures inserted by PathRouter’s Service implementation.
PathRouteMatch
Result of a successful PathRouter::match_prefix lookup.
PathRouter
A typed prefix router for URI paths.
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.
QueryDeserializeErrorstd
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.
PathPatternSegmentKind
Coarse classification of a compiled PathPattern segment, exposed via PathPattern::segment_kinds so callers (e.g. a router) can reason about route specificity without re-parsing the pattern syntax themselves.
PathRouterError
Error produced by PathRouter when used as a Service.
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.