Struct QueryParams 

pub struct QueryParams { /* private fields */ }

Query parameters from an agent URI.

Stores key-value pairs from the query string, sorted lexicographically by key for consistent normalization. Percent escapes in values decode to octets, and the complete decoded sequence must be valid UTF-8. Invalid UTF-8 is rejected rather than replaced. Programmatically constructed values may contain any characters. fmt::Display re-encodes every value octet outside the ASCII alphanumeric, -, _, and . set using uppercase %XX, so its output parses to the same values.

Reserved Parameters

• version: Capability version constraint (semver)
• attestation: Inline PASETO attestation token
• resolver: Hint for resolution endpoint
• ttl: Cache TTL hint in seconds

Parameters are held sorted by name, so two queries that differ only in the order they were written are equal and hash equally.

Implementations

impl QueryParams

pub fn new() -> Self

Creates an empty query params instance.

pub fn parse(input: &str) -> Result<Self, QueryError>

Parses query parameters from a query string (without leading ‘?’).

Percent escapes decode to octets, and the complete decoded sequence must be valid UTF-8. Invalid sequences are rejected rather than replaced. Rendering with fmt::Display re-encodes every value octet outside the ASCII alphanumeric, -, _, and . set as uppercase %XX, preserving values across parse-display-parse round trips. This standalone entry point enforces the same total-URI byte limit that crate::AgentUri::parse applies.

Errors

Input longer than 512 bytes (crate::MAX_URI_LENGTH) is rejected with QueryError::TooLong. Other invalid parameters return their corresponding QueryError variant.

pub fn get(&self, name: &str) -> Option<&str>

Returns the value for a parameter, if present.

pub fn is_empty(&self) -> bool

Returns true if the query is empty.

pub fn len(&self) -> usize

Returns the number of parameters.

pub fn iter(&self) -> impl Iterator<Item = (&str, &str)>

Returns an iterator over the parameters.

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

Returns the version parameter, if present.

pub fn ttl(&self) -> Option<u64>

Returns the TTL parameter, if present.

pub fn with_param(&self, key: &str, value: &str) -> Result<Self, QueryError>

Returns a new query with the given parameter added or updated.

The value may contain any characters. fmt::Display percent-encodes every UTF-8 octet outside the ASCII alphanumeric, -, _, and . set.

Errors

Returns QueryError if the parameter name is invalid.

Examples

use agent_uri::QueryParams;

let query = QueryParams::new();
let updated = query.with_param("version", "2.0").unwrap();
assert_eq!(updated.get("version"), Some("2.0"));

let with_filter = updated.with_param("filter", "&b=c").unwrap();
assert_eq!(with_filter.get("filter"), Some("&b=c"));
let rendered = with_filter.to_string();
assert!(rendered.contains("filter=%26b%3Dc"));
assert_eq!(
    QueryParams::parse(&rendered).unwrap().get("filter"),
    Some("&b=c")
);

pub fn without_param(&self, key: &str) -> Self

Returns a new query without the given parameter.

Examples

use agent_uri::QueryParams;

let query = QueryParams::parse("version=2.0&ttl=300").unwrap();
let updated = query.without_param("ttl");
assert!(updated.get("ttl").is_none());
assert_eq!(updated.get("version"), Some("2.0"));

pub fn with_version(&self, v: &str) -> Result<Self, QueryError>

Returns a new query with the version parameter set.

Errors

The return type is retained for API stability. This helper currently cannot fail because its fixed parameter name is valid and values may contain any characters.

Examples

use agent_uri::QueryParams;

let query = QueryParams::new();
let updated = query.with_version("2.0").unwrap();
assert_eq!(updated.version(), Some("2.0"));

pub fn with_ttl(&self, ttl: u64) -> Result<Self, QueryError>

Returns a new query with the TTL parameter set.

Errors

The return type is retained for API stability. This helper currently cannot fail because its fixed parameter name and generated value are valid.

Examples

use agent_uri::QueryParams;

let query = QueryParams::new();
let updated = query.with_ttl(300).unwrap();
assert_eq!(updated.ttl(), Some(300));

Trait Implementations

impl Clone for QueryParams

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for QueryParams

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

Formats the value using the given formatter.

impl Default for QueryParams

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for QueryParams

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for QueryParams

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

Formats the value using the given formatter.

impl Eq for QueryParams

impl FromStr for QueryParams

type Err = QueryError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

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

impl Hash for QueryParams

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

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 QueryParams

Orders by the parameters themselves rather than by their rendering.

Rendering both sides to compare them allocated two Strings per comparison, and percent-encoded every value on the way to throwing it away. The map is already sorted by key, so comparing it directly is the same walk without the encoding: pairs in key order, first difference wins. Values that differ only in how they encode are the same value, and now sort as one.

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

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for QueryParams

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

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for QueryParams

fn partial_cmp(&self, other: &Self) -> 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 Serialize for QueryParams

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for QueryParams

impl TryFrom<&str> for QueryParams

type Error = QueryError

The type returned in the event of a conversion error.

fn try_from(s: &str) -> Result<Self, Self::Error>

Performs the conversion.