Skip to main content

powerio_core/source/
tree.rs

1//! Shared immutable inputs and independently observed source selections.
2
3use std::collections::BTreeMap;
4use std::sync::{Arc, Mutex};
5
6use super::{Error, Source, SourceBuffer, SourceId, SourceProvider};
7use crate::ArtifactPath;
8
9/// Explicit admission limits for an in-memory tree or one selected view.
10///
11/// These limits do not read environment variables. They bound admitted files,
12/// their combined byte length, and path depth relative to the selected root.
13/// View limits apply to exposed files; a view keeps the shared tree owner alive,
14/// whose total storage is bounded by the limits used to construct the tree.
15/// Parser work and decoded model allocations have their own limits.
16/// Defaults are 4096 files, 1 GiB, and 64 path segments.
17#[derive(Clone, Copy, Debug, Eq, PartialEq)]
18pub struct SourceTreeLimits {
19    files: usize,
20    bytes: u64,
21    depth: usize,
22}
23
24impl Default for SourceTreeLimits {
25    fn default() -> Self {
26        Self {
27            files: super::MAX_REFERENCED_FILES,
28            bytes: super::DEFAULT_SOURCE_BYTES,
29            depth: super::MAX_REFERENCED_DEPTH,
30        }
31    }
32}
33
34impl SourceTreeLimits {
35    /// Set positive file, byte, and depth limits. Depth cannot exceed the
36    /// source resolver's 64-segment bound; bytes must fit this platform.
37    pub fn new(files: usize, bytes: u64, depth: usize) -> Result<Self, Error> {
38        if files == 0
39            || bytes == 0
40            || isize::try_from(bytes).is_err()
41            || depth == 0
42            || depth > super::MAX_REFERENCED_DEPTH
43        {
44            return Err(Error::new(
45                &crate::codes::REQUEST_SOURCE_INVALID_LIMIT,
46                "tree limits require positive file/byte counts, platform-sized bytes, and depth in 1..=64",
47            ));
48        }
49        Ok(Self {
50            files,
51            bytes,
52            depth,
53        })
54    }
55
56    #[must_use]
57    pub const fn max_files(self) -> usize {
58        self.files
59    }
60
61    #[must_use]
62    pub const fn max_bytes(self) -> u64 {
63        self.bytes
64    }
65
66    #[must_use]
67    pub const fn max_depth(self) -> usize {
68        self.depth
69    }
70
71    fn check(self, count: usize, bytes: u64, path: &str) -> Result<(), Error> {
72        if count > self.files || bytes > self.bytes || path.split('/').count() > self.depth {
73            return Err(Error::new(
74                &crate::codes::READ_IO_REFERENCE_BUDGET,
75                format!(
76                    "source tree exceeds {} files, {} bytes, or {} path segments",
77                    self.files, self.bytes, self.depth
78                ),
79            ));
80        }
81        Ok(())
82    }
83}
84
85/// Named immutable files shared by independently selectable sources.
86///
87/// Construct once, then call [`Self::source`] for each primary or directory.
88/// Views share the inventory and byte allocations. Each call creates a fresh
89/// dependency observation set; clones of that source share its observations.
90/// No view can acquire files outside its selected root or from the filesystem.
91///
92/// ```
93/// use std::sync::Arc;
94/// use powerio_core::{ArtifactPath, SourceTree, SourceTreeLimits};
95///
96/// let limits = SourceTreeLimits::new(100, 8 << 20, 16)?;
97/// let primary = ArtifactPath::new("masters/day.dss")?;
98/// let tree = SourceTree::new("study", [
99///     (primary.clone(), Arc::<[u8]>::from(&b"Redirect ../shared/lines.inc"[..])),
100///     (ArtifactPath::new("shared/lines.inc")?, Arc::<[u8]>::from(&b"line data"[..])),
101/// ], limits)?;
102/// let source = tree.source(None, Some(&primary), limits)?;
103/// let master = source.primary_buffer()?;
104/// source.referenced_buffer(&master, "../shared/lines.inc")?;
105/// assert_eq!(source.dependencies().len(), 1);
106/// assert!(tree.source(None, Some(&primary), limits)?.dependencies().is_empty());
107/// # Ok::<(), powerio_core::Error>(())
108/// ```
109#[derive(Clone, Debug)]
110pub struct SourceTree {
111    name: Arc<str>,
112    files: Arc<BTreeMap<String, SourceBuffer>>,
113}
114
115impl SourceTree {
116    /// Retain unique portable paths under explicit limits. File/directory
117    /// collisions are refused. Paths are case sensitive and never renamed.
118    pub fn new(
119        name: impl Into<String>,
120        files: impl IntoIterator<Item = (ArtifactPath, Arc<[u8]>)>,
121        limits: SourceTreeLimits,
122    ) -> Result<Self, Error> {
123        let name = name.into();
124        if !super::valid_nonempty_text(&name) {
125            return Err(Error::new(
126                &crate::codes::REQUEST_SOURCE_INVALID_NAME,
127                "a source tree requires a nonempty bounded name",
128            ));
129        }
130        let mut retained = BTreeMap::new();
131        let mut total = 0u64;
132        for (path, bytes) in files {
133            let segments = super::resolve_segments(&[], path.as_str())?;
134            total = total.saturating_add(bytes.len() as u64);
135            limits.check(retained.len().saturating_add(1), total, path.as_str())?;
136            let key = path.as_str().to_owned();
137            let buffer = SourceBuffer::new(
138                SourceId::new(&key)?,
139                &key,
140                bytes,
141                segments[..segments.len() - 1].to_vec(),
142            );
143            if retained.insert(key.clone(), buffer).is_some() {
144                return Err(invalid_path(format!("duplicate source tree file `{key}`")));
145            }
146        }
147        for name in retained.keys() {
148            let mut child = name.as_str();
149            while let Some((parent, _)) = child.rsplit_once('/') {
150                if retained.contains_key(parent) {
151                    return Err(invalid_path(format!(
152                        "source tree file `{parent}` is also a directory"
153                    )));
154                }
155                child = parent;
156            }
157        }
158        Ok(Self {
159            name: name.into(),
160            files: Arc::new(retained),
161        })
162    }
163
164    /// Select a directory root and optionally a primary relative to that root.
165    /// `None` selects the tree root or a directory source, respectively.
166    ///
167    /// All files below the root remain available as retained companions and
168    /// count against `limits`, including the primary. Names, source IDs, and
169    /// reference directories are rebased to that root; the primary has ID
170    /// `/input`. Selecting a file creates no dependency observation.
171    pub fn source(
172        &self,
173        root: Option<&ArtifactPath>,
174        primary: Option<&ArtifactPath>,
175        limits: SourceTreeLimits,
176    ) -> Result<Source, Error> {
177        let prefix = root.map_or_else(String::new, |path| format!("{}/", path.as_str()));
178        let mut count = 0usize;
179        let mut total = 0u64;
180        for (path, buffer) in self.files.range(prefix.clone()..) {
181            let Some(relative) = path.strip_prefix(&prefix) else {
182                break;
183            };
184            count += 1;
185            total = total.saturating_add(buffer.bytes().len() as u64);
186            limits.check(count, total, relative)?;
187        }
188        if root.is_some() && count == 0 {
189            return Err(invalid_path(
190                "selected source tree directory does not exist",
191            ));
192        }
193        let view = TreeView {
194            files: Arc::clone(&self.files),
195            prefix,
196            primary: primary.cloned(),
197            limits,
198            buffers: Mutex::new(BTreeMap::new()),
199        };
200        if let Some(primary) = primary {
201            view.buffer(primary.as_str(), u64::MAX)?;
202        }
203        let name = primary.map_or_else(
204            || {
205                root.map_or_else(
206                    || self.name.to_string(),
207                    |root| format!("{}/{}", self.name, root.as_str()),
208                )
209            },
210            |primary| primary.as_str().to_owned(),
211        );
212        Ok(Source {
213            name: name.into(),
214            provider: Arc::new(SourceProvider::Tree(view)),
215            declared_format: None,
216            dependencies: Arc::default(),
217        })
218    }
219}
220
221fn invalid_path(message: impl Into<String>) -> Error {
222    Error::new(&crate::codes::REQUEST_SOURCE_INVALID_PATH, message)
223}
224
225#[derive(Debug)]
226pub(super) struct TreeView {
227    files: Arc<BTreeMap<String, SourceBuffer>>,
228    prefix: String,
229    pub primary: Option<ArtifactPath>,
230    pub limits: SourceTreeLimits,
231    buffers: Mutex<BTreeMap<String, SourceBuffer>>,
232}
233
234impl TreeView {
235    pub fn retained_buffers(&self) -> Vec<SourceBuffer> {
236        let mut buffers: Vec<_> = self
237            .names()
238            .iter()
239            .map(|path| {
240                self.buffer(path.as_str(), u64::MAX)
241                    .expect("validated tree view")
242            })
243            .collect();
244        if let Some(index) = buffers
245            .iter()
246            .position(|buffer| buffer.id().as_str() == super::PRIMARY_SOURCE_ID)
247        {
248            let primary = buffers.remove(index);
249            buffers.insert(0, primary);
250        }
251        buffers
252    }
253
254    pub fn names(&self) -> Vec<ArtifactPath> {
255        self.files
256            .range(self.prefix.clone()..)
257            .take_while(|(path, _)| path.starts_with(&self.prefix))
258            .map(|(path, _)| {
259                ArtifactPath::new(&path[self.prefix.len()..]).expect("validated tree path")
260            })
261            .collect()
262    }
263
264    pub fn buffer(&self, name: &str, max_bytes: u64) -> Result<SourceBuffer, Error> {
265        let segments = super::resolve_segments(&[], name)?;
266        let key = segments.join("/");
267        let original = self
268            .files
269            .get(&format!("{}{key}", self.prefix))
270            .ok_or_else(|| {
271                Error::new(
272                    &crate::codes::REQUEST_SOURCE_UNKNOWN_BUFFER,
273                    format!("file `{key}` was not supplied beneath the selected tree root"),
274                )
275            })?;
276        if original.bytes().len() as u64 > max_bytes {
277            return Err(super::ReadBudget::ReferencedBuffer(max_bytes).exceeded(&key));
278        }
279        let mut buffers = self
280            .buffers
281            .lock()
282            .unwrap_or_else(std::sync::PoisonError::into_inner);
283        Ok(buffers
284            .entry(key.clone())
285            .or_insert_with(|| {
286                let id = if self.primary.as_ref().is_some_and(|p| p.as_str() == key) {
287                    super::PRIMARY_SOURCE_ID
288                } else {
289                    &key
290                };
291                SourceBuffer::new(
292                    SourceId::new(id).expect("validated tree source ID"),
293                    &key,
294                    original.shared_bytes(),
295                    segments[..segments.len() - 1].to_vec(),
296                )
297            })
298            .clone())
299    }
300}