agent-uri-dht 0.12.0

Capability-based DHT discovery for agent:// URI scheme
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! Lookup queries.

use agent_uri::{CapabilityPath, TrustRoot};

/// How a capability path is matched during lookup.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum MatchMode {
    /// Return only agents registered at exactly this path.
    Exact,
    /// Return agents at this path and every descendant path.
    Prefix,
}

/// A capability lookup.
///
/// Every query is scoped to one trust root, because every DHT key is derived
/// from one. There is deliberately no cross-trust-root query.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Query {
    trust_root: TrustRoot,
    capability_path: CapabilityPath,
    match_mode: MatchMode,
}

impl Query {
    /// Creates a query for agents at exactly this capability path.
    #[must_use]
    pub const fn exact(trust_root: TrustRoot, capability_path: CapabilityPath) -> Self {
        Self {
            trust_root,
            capability_path,
            match_mode: MatchMode::Exact,
        }
    }

    /// Creates a query for agents at this capability path and its descendants.
    #[must_use]
    pub const fn prefix(trust_root: TrustRoot, capability_path: CapabilityPath) -> Self {
        Self {
            trust_root,
            capability_path,
            match_mode: MatchMode::Prefix,
        }
    }

    /// Returns the trust root this query is scoped to.
    #[must_use]
    pub const fn trust_root(&self) -> &TrustRoot {
        &self.trust_root
    }

    /// Returns the capability path being queried.
    #[must_use]
    pub const fn capability_path(&self) -> &CapabilityPath {
        &self.capability_path
    }

    /// Returns the match mode.
    #[must_use]
    pub const fn match_mode(&self) -> MatchMode {
        self.match_mode
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn parts() -> (TrustRoot, CapabilityPath) {
        (
            TrustRoot::parse("anthropic.com").unwrap(),
            CapabilityPath::parse("assistant/chat").unwrap(),
        )
    }

    #[test]
    fn exact_query_records_its_mode() {
        let (tr, path) = parts();
        let q = Query::exact(tr, path);
        assert_eq!(q.match_mode(), MatchMode::Exact);
        assert_eq!(q.trust_root().as_str(), "anthropic.com");
        assert_eq!(q.capability_path().as_str(), "assistant/chat");
    }

    #[test]
    fn prefix_query_records_its_mode() {
        let (tr, path) = parts();
        let q = Query::prefix(tr, path);
        assert_eq!(q.match_mode(), MatchMode::Prefix);
    }

    #[test]
    fn queries_differing_only_in_mode_are_not_equal() {
        let (tr, path) = parts();
        assert_ne!(
            Query::exact(tr.clone(), path.clone()),
            Query::prefix(tr, path)
        );
    }
}