scientific_workflow/configuration/parameters/
resolved_configuration.rs

1//! Cheap resolved combinations with lazy nested-document materialization.
2
3use std::fmt;
4use std::iter::FusedIterator;
5use std::sync::{Arc, OnceLock};
6
7use serde::de::DeserializeOwned;
8use serde_json::Value;
9
10use super::super::error::ConfigurationError;
11use super::super::parameter_key_tuple::ParameterKeyTuple;
12use super::super::parameter_path::ParameterPath;
13use super::super::parameter_tree::{lookup_path, reconstruct};
14use super::ConfigurationSpaceInner;
15use super::reconstruction;
16
17pub struct ResolvedConfiguration {
18    inner: Arc<ConfigurationSpaceInner>,
19    ordinal: u64,
20    resolved: OnceLock<Value>,
21}
22
23impl Clone for ResolvedConfiguration {
24    fn clone(&self) -> Self {
25        Self {
26            inner: Arc::clone(&self.inner),
27            ordinal: self.ordinal,
28            resolved: OnceLock::new(),
29        }
30    }
31}
32
33impl ResolvedConfiguration {
34    pub(super) fn new(inner: Arc<ConfigurationSpaceInner>, ordinal: u64) -> Self {
35        Self {
36            inner,
37            ordinal,
38            resolved: OnceLock::new(),
39        }
40    }
41
42    pub fn ordinal(&self) -> u64 {
43        self.ordinal
44    }
45
46    /// Borrows an exact leaf or lazily reconstructed nested subtree.
47    pub fn value(&self, key: &str) -> Option<&Value> {
48        let path = ParameterPath::parse(key)?;
49        if let Some(&position) = self.inner.fixed_by_path.get(&path) {
50            return Some(&self.inner.fixed[position].value);
51        }
52        if let Some(leaf) = self.inner.sweep.selected_leaf(self.ordinal, &path) {
53            return Some(&leaf.value);
54        }
55        if !self
56            .inner
57            .sweep
58            .selected_leaves(self.ordinal)
59            .any(|leaf| path.is_ancestor_of(&leaf.path))
60        {
61            return lookup_path(&self.inner.fixed_document, &path);
62        }
63        lookup_path(self.resolved_document(), &path)
64    }
65
66    pub fn require_value(&self, key: &str) -> Result<&Value, ConfigurationError> {
67        self.value(key)
68            .ok_or_else(|| ConfigurationError::UnknownConfigurationValue {
69                ordinal: self.ordinal,
70                key: key.to_owned(),
71            })
72    }
73
74    pub fn decode_value<T>(&self, key: &str) -> Result<T, ConfigurationError>
75    where
76        T: DeserializeOwned,
77    {
78        let Some(path) = ParameterPath::parse(key) else {
79            return Err(ConfigurationError::UnknownConfigurationValue {
80                ordinal: self.ordinal,
81                key: key.to_owned(),
82            });
83        };
84        if let Some(value) = self.exact_leaf(&path) {
85            return T::deserialize(value).map_err(|source| {
86                ConfigurationError::DecodeConfigurationValue {
87                    ordinal: self.ordinal,
88                    key: key.to_owned(),
89                    source,
90                }
91            });
92        }
93        let has_selected_sweep_descendant = self
94            .inner
95            .sweep
96            .selected_leaves(self.ordinal)
97            .any(|leaf| path.is_ancestor_of(&leaf.path));
98        if !has_selected_sweep_descendant
99            && let Some(value) = lookup_path(&self.inner.fixed_document, &path)
100        {
101            return T::deserialize(value).map_err(|source| {
102                ConfigurationError::DecodeConfigurationValue {
103                    ordinal: self.ordinal,
104                    key: key.to_owned(),
105                    source,
106                }
107            });
108        }
109        let subtree = reconstruct(
110            self.inner
111                .fixed
112                .iter()
113                .chain(self.inner.sweep.selected_leaves(self.ordinal))
114                .filter(|leaf| path.is_ancestor_of(&leaf.path)),
115        );
116        let Some(value) = lookup_path(&subtree, &path) else {
117            return Err(ConfigurationError::UnknownConfigurationValue {
118                ordinal: self.ordinal,
119                key: key.to_owned(),
120            });
121        };
122        T::deserialize(value).map_err(|source| ConfigurationError::DecodeConfigurationValue {
123            ordinal: self.ordinal,
124            key: key.to_owned(),
125            source,
126        })
127    }
128
129    pub fn decode_values<Values, Keys>(&self, keys: Keys) -> Result<Values, ConfigurationError>
130    where
131        Keys: ParameterKeyTuple<Values>,
132    {
133        keys.decode(self)
134    }
135
136    pub fn contains(&self, key: &str) -> bool {
137        let Some(path) = ParameterPath::parse(key) else {
138            return false;
139        };
140        self.inner
141            .fixed
142            .iter()
143            .any(|leaf| leaf.path == path || path.is_ancestor_of(&leaf.path))
144            || self
145                .inner
146                .sweep
147                .selected_leaves(self.ordinal)
148                .any(|leaf| leaf.path == path || path.is_ancestor_of(&leaf.path))
149    }
150
151    pub fn len(&self) -> usize {
152        self.inner.fixed.len() + self.inner.sweep.selected_leaf_count(self.ordinal)
153    }
154
155    pub fn is_empty(&self) -> bool {
156        self.len() == 0
157    }
158
159    /// Iterates canonical terminal parameter identifiers.
160    pub fn keys(&self) -> impl Iterator<Item = &str> {
161        self.inner
162            .fixed
163            .iter()
164            .map(|leaf| leaf.path.identifier())
165            .chain(
166                self.inner
167                    .sweep
168                    .selected_leaves(self.ordinal)
169                    .map(|leaf| leaf.path.identifier()),
170            )
171    }
172
173    pub fn iter(&self) -> impl Iterator<Item = (&str, &Value)> {
174        self.inner
175            .fixed
176            .iter()
177            .map(|leaf| (leaf.path.identifier(), &leaf.value))
178            .chain(
179                self.inner
180                    .sweep
181                    .selected_leaves(self.ordinal)
182                    .map(|leaf| (leaf.path.identifier(), &leaf.value)),
183            )
184    }
185
186    /// Serializes the complete rehydrated nested configuration document.
187    pub fn to_json(&self) -> Result<String, ConfigurationError> {
188        serde_json::to_string(self.resolved_document()).map_err(|source| {
189            ConfigurationError::SerializeResolvedConfiguration {
190                ordinal: self.ordinal,
191                source,
192            }
193        })
194    }
195
196    fn resolved_document(&self) -> &Value {
197        self.resolved
198            .get_or_init(|| reconstruction::document(&self.inner, self.ordinal))
199    }
200
201    pub(crate) fn resolved_object(&self) -> &serde_json::Map<String, Value> {
202        self.resolved_document()
203            .as_object()
204            .expect("resolved configurations always form a JSON object")
205    }
206
207    fn exact_leaf(&self, path: &ParameterPath) -> Option<&Value> {
208        if let Some(&position) = self.inner.fixed_by_path.get(path) {
209            return Some(&self.inner.fixed[position].value);
210        }
211        self.inner
212            .sweep
213            .selected_leaf(self.ordinal, path)
214            .map(|leaf| &leaf.value)
215    }
216}
217
218impl fmt::Debug for ResolvedConfiguration {
219    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
220        formatter
221            .debug_struct("ResolvedConfiguration")
222            .field("ordinal", &self.ordinal)
223            .field("values", &self.len())
224            .finish_non_exhaustive()
225    }
226}
227
228#[derive(Clone)]
229pub struct ConfigurationIter {
230    inner: Arc<ConfigurationSpaceInner>,
231    next: u64,
232    end: u64,
233}
234
235impl ConfigurationIter {
236    pub(super) fn new(inner: Arc<ConfigurationSpaceInner>, end: u64) -> Self {
237        Self {
238            inner,
239            next: 0,
240            end,
241        }
242    }
243}
244
245impl Iterator for ConfigurationIter {
246    type Item = ResolvedConfiguration;
247
248    fn next(&mut self) -> Option<Self::Item> {
249        if self.next == self.end {
250            return None;
251        }
252        let ordinal = self.next;
253        self.next += 1;
254        Some(ResolvedConfiguration::new(Arc::clone(&self.inner), ordinal))
255    }
256
257    fn size_hint(&self) -> (usize, Option<usize>) {
258        let remaining = self.end - self.next;
259        match usize::try_from(remaining) {
260            Ok(remaining) => (remaining, Some(remaining)),
261            Err(_) => (usize::MAX, None),
262        }
263    }
264}
265
266impl FusedIterator for ConfigurationIter {}
267
268impl fmt::Debug for ConfigurationIter {
269    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
270        formatter
271            .debug_struct("ConfigurationIter")
272            .field("next", &self.next)
273            .field("end", &self.end)
274            .finish_non_exhaustive()
275    }
276}
scientific_workflow/configuration/parameters/resolved_configuration.rs

scientific_workflow/configuration/parameters/
resolved_configuration.rs
