agent-workspace-contract 0.5.0

Transport-neutral contracts for Agent Infra workspace APIs
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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

use std::collections::BTreeSet;

use serde::{Deserialize, Serialize};

/// Resource owner identity. At least one owner is required on every Environment
/// resource; callers authenticate with runtime, agent, or user credentials.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum OwnerKind {
    Runtime,
    Agent,
    User,
}

#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub struct OwnerRef {
    pub kind: OwnerKind,
    pub id: String,
}

impl OwnerRef {
    pub fn runtime(id: impl Into<String>) -> Self {
        Self {
            kind: OwnerKind::Runtime,
            id: id.into(),
        }
    }

    pub fn agent(id: impl Into<String>) -> Self {
        Self {
            kind: OwnerKind::Agent,
            id: id.into(),
        }
    }

    pub fn user(id: impl Into<String>) -> Self {
        Self {
            kind: OwnerKind::User,
            id: id.into(),
        }
    }

    pub fn from_principal(principal: &crate::PrincipalRef) -> Self {
        match principal.kind {
            crate::PrincipalKind::User => Self::user(&principal.id),
            crate::PrincipalKind::Agent => Self::agent(&principal.id),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub struct PatchOwnersRequest {
    pub expected_version: u64,
    #[serde(default)]
    pub add: Vec<OwnerRef>,
    #[serde(default)]
    pub remove: Vec<OwnerRef>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OwnerValidationError {
    Empty,
    Duplicate,
    NotSubset,
}

/// Normalize owners: non-empty, deduplicated, stable order.
pub fn normalize_owners(owners: Vec<OwnerRef>) -> Result<Vec<OwnerRef>, OwnerValidationError> {
    if owners.is_empty() {
        return Err(OwnerValidationError::Empty);
    }
    let mut set = BTreeSet::new();
    for owner in owners {
        if !set.insert(owner.clone()) {
            return Err(OwnerValidationError::Duplicate);
        }
    }
    Ok(set.into_iter().collect())
}

/// True when `candidate` is a subset of `parent` (every element of candidate in parent).
pub fn owners_subset_of(candidate: &[OwnerRef], parent: &[OwnerRef]) -> bool {
    let parent_set: BTreeSet<_> = parent.iter().collect();
    candidate.iter().all(|owner| parent_set.contains(owner))
}

/// True when caller and resource owners share at least one identity.
pub fn owners_intersect(caller: &[OwnerRef], resource: &[OwnerRef]) -> bool {
    let resource_set: BTreeSet<_> = resource.iter().collect();
    caller.iter().any(|owner| resource_set.contains(owner))
}

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

    #[test]
    fn normalize_rejects_empty() {
        assert!(matches!(
            normalize_owners(vec![]),
            Err(OwnerValidationError::Empty)
        ));
    }

    #[test]
    fn normalize_rejects_duplicate() {
        assert!(matches!(
            normalize_owners(vec![OwnerRef::runtime("rt-1"), OwnerRef::runtime("rt-1"),]),
            Err(OwnerValidationError::Duplicate)
        ));
    }

    #[test]
    fn subset_and_intersect() {
        let parent = vec![OwnerRef::user("u1"), OwnerRef::agent("agt-1")];
        let child = vec![OwnerRef::agent("agt-1")];
        assert!(owners_subset_of(&child, &parent));
        assert!(!owners_subset_of(&parent, &child));
        assert!(owners_intersect(
            &[OwnerRef::runtime("rt-1")],
            &[OwnerRef::runtime("rt-1"), OwnerRef::user("u1")]
        ));
        assert!(!owners_intersect(
            &[OwnerRef::runtime("rt-2")],
            &[OwnerRef::runtime("rt-1")]
        ));
    }
}