Skip to main content

muse_code_sdk/fold/
approvals.rs

1//! Approvals as the TS and Python folds hold them: a
2//! pending entry keeps its latest request and its latest update apart, and
3//! both sets list in the order their entries first arrived.
4//!
5//! Downstream code cannot build `PendingApproval` with a struct literal and
6//! must destructure it with `..`, so a later field stays additive.
7//!
8//! ```compile_fail,E0639
9//! use muse_code_sdk::fold::PendingApproval;
10//!
11//! fn rebuild(approval: PendingApproval) {
12//!     let _ = PendingApproval { ..approval };
13//! }
14//! ```
15//!
16//! ```no_run
17//! use muse_code_sdk::fold::PendingApproval;
18//!
19//! fn inspect(approval: PendingApproval) {
20//!     let PendingApproval { approval_id, .. } = approval;
21//!     println!("{approval_id}");
22//! }
23//! ```
24
25use std::collections::{HashMap, hash_map::Entry};
26
27use serde_json::{Map, Value};
28
29/// An approval awaiting its first durable terminal.
30///
31/// Callers only receive it, so it is `#[non_exhaustive]`: a later field
32/// breaks no caller (as for the received wire structs).
33#[derive(Clone, Debug, PartialEq)]
34#[non_exhaustive]
35pub struct PendingApproval {
36    /// The `approvalId` the host minted for this approval.
37    pub approval_id: String,
38    /// The latest `approval/requested` params, verbatim.
39    pub requested: Value,
40    /// The most recent `approval/updated` refresh since that request, if any.
41    pub latest_update: Option<Value>,
42}
43
44/// Each entry keeps the sequence at which it entered its set, so pending
45/// approvals list in first-request order and resolved ones in
46/// first-resolution order.
47#[derive(Debug, Default)]
48pub(super) struct Approvals {
49    observed: u64,
50    pending: HashMap<String, (u64, PendingApproval)>,
51    resolved: HashMap<String, (u64, Value)>,
52}
53
54impl Approvals {
55    /// A request for an approval that already has its terminal never re-opens
56    /// it. A re-request replaces the entry, update included: a re-issued
57    /// request already embodies the latest refresh.
58    pub(super) fn request(&mut self, id: &str, params: &Map<String, Value>) -> bool {
59        if self.resolved.contains_key(id) {
60            return false;
61        }
62        let entry = PendingApproval {
63            approval_id: id.to_owned(),
64            requested: Value::Object(params.clone()),
65            latest_update: None,
66        };
67        match self.pending.entry(id.to_owned()) {
68            Entry::Occupied(mut slot) => slot.get_mut().1 = entry,
69            Entry::Vacant(slot) => {
70                slot.insert((self.observed, entry));
71                self.observed += 1;
72            }
73        }
74        true
75    }
76
77    /// An update refreshes a pending entry; it never opens one.
78    pub(super) fn update(&mut self, id: &str, params: &Map<String, Value>) -> bool {
79        match self.pending.get_mut(id) {
80            Some((_, entry)) => {
81                entry.latest_update = Some(Value::Object(params.clone()));
82                true
83            }
84            None => false,
85        }
86    }
87
88    /// The first durable terminal stands; a later one is an echo, never an
89    /// overwrite.
90    pub(super) fn resolve(&mut self, id: &str, params: &Map<String, Value>) -> bool {
91        self.pending.remove(id);
92        match self.resolved.entry(id.to_owned()) {
93            Entry::Vacant(slot) => {
94                slot.insert((self.observed, Value::Object(params.clone())));
95                self.observed += 1;
96                true
97            }
98            Entry::Occupied(_) => false,
99        }
100    }
101
102    /// The latest params seen for a pending approval: its update if any, else
103    /// its request.
104    pub(super) fn latest(&self, id: &str) -> Option<&Value> {
105        self.pending
106            .get(id)
107            .map(|(_, entry)| entry.latest_update.as_ref().unwrap_or(&entry.requested))
108    }
109
110    pub(super) fn resolved(&self, id: &str) -> Option<&Value> {
111        super::params_of(self.resolved.get(id))
112    }
113
114    pub(super) fn pending_in_order(&self) -> Vec<&PendingApproval> {
115        let mut ordered: Vec<_> = self.pending.values().collect();
116        ordered.sort_unstable_by_key(|(observed, _)| *observed);
117        ordered.into_iter().map(|(_, entry)| entry).collect()
118    }
119
120    pub(super) fn resolved_in_order(&self) -> Vec<&Value> {
121        super::in_observed_order(&self.resolved)
122    }
123}