Skip to main content

powerio/collection/
manifest.rs

1use super::{
2    ArtifactPath, Collection, CollectionLimits, CollectionResult, CollectionSelection, Error,
3    ParseOptions, Result, codes, selection_error,
4};
5use serde::{Deserialize, Serialize};
6use std::{collections::BTreeSet, sync::Arc};
7
8/// Structured transport origin, separate from network values and display names.
9#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
10#[serde(deny_unknown_fields)]
11#[non_exhaustive]
12pub struct CollectionOrigin {
13    pub collection: String,
14    /// One relative member name per explicitly opened ZIP boundary.
15    pub containers: Vec<String>,
16}
17#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
18#[serde(deny_unknown_fields)]
19#[non_exhaustive]
20pub struct SelectionOrigin {
21    pub origin: CollectionOrigin,
22    pub selection: CollectionSelection,
23}
24
25/// Native options recorded with a selection, without host acquisition or code.
26#[derive(Clone, Debug, Default, Serialize, Deserialize)]
27#[serde(deny_unknown_fields)]
28#[non_exhaustive]
29pub struct CollectionReaderOptions {
30    pub variant: Option<i64>,
31    pub snapshot_hours: Option<f64>,
32    pub acquired_tables: Option<String>,
33    #[serde(default)]
34    pub assume_inactive_source_controls: bool,
35}
36#[derive(Clone, Debug, Serialize, Deserialize)]
37#[serde(deny_unknown_fields)]
38#[non_exhaustive]
39pub struct CollectionCase {
40    pub id: String,
41    #[serde(default)]
42    pub containers: Vec<String>,
43    pub selection: CollectionSelection,
44    /// Explicit associations only; attachments are not silently parsed/merged.
45    #[serde(default)]
46    pub attachments: Vec<String>,
47    pub reader_options: Option<CollectionReaderOptions>,
48}
49/// Optional untrusted selection catalog. It cannot change host limits or features.
50#[derive(Clone, Debug, Serialize, Deserialize)]
51#[serde(deny_unknown_fields)]
52#[non_exhaustive]
53pub struct CollectionManifest {
54    pub schema: String,
55    pub version: u32,
56    pub cases: Vec<CollectionCase>,
57}
58impl CollectionManifest {
59    pub fn new(cases: Vec<CollectionCase>) -> Self {
60        Self {
61            schema: "powerio-collection".into(),
62            version: 1,
63            cases,
64        }
65    }
66    fn validate(&self, limits: CollectionLimits) -> Result<()> {
67        if self.schema != "powerio-collection" || self.version != 1 {
68            return Err(selection_error(
69                "unsupported collection manifest identity/version",
70            ));
71        }
72        if self.cases.len() > limits.tree.max_files() {
73            return Err(selection_error("manifest case limit exceeded"));
74        }
75        let mut ids = BTreeSet::new();
76        for case in &self.cases {
77            if case.id.is_empty()
78                || case.id.len() > 128
79                || !case
80                    .id
81                    .bytes()
82                    .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.'))
83                || !case.id.as_bytes()[0].is_ascii_alphanumeric()
84                || !ids.insert(&case.id)
85            {
86                return Err(selection_error(
87                    "manifest IDs must be unique bounded portable identifiers",
88                ));
89            }
90            if case.containers.len() > limits.max_zip_layers as usize
91                || case.attachments.len() > limits.tree.max_files()
92            {
93                return Err(selection_error("manifest scope limit exceeded"));
94            }
95            for path in case
96                .containers
97                .iter()
98                .chain(case.attachments.iter())
99                .chain(case.selection.root.iter())
100                .chain(case.selection.primary.iter())
101                .chain(case.selection.members.iter().flatten())
102            {
103                ArtifactPath::new(path)?;
104            }
105            if case
106                .selection
107                .members
108                .as_ref()
109                .is_some_and(|m| m.len() > limits.tree.max_files())
110            {
111                return Err(selection_error("manifest member limit exceeded"));
112            }
113            case.options()?;
114        }
115        Ok(())
116    }
117    /// Deterministic metadata encoding. Case order remains user-controlled.
118    pub fn to_json(&self) -> Result<Vec<u8>> {
119        // This bound also applies to manually constructed catalogs.
120        struct Limited(Vec<u8>);
121        impl std::io::Write for Limited {
122            fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
123                if bytes.len() > (1 << 20) - self.0.len() {
124                    return Err(std::io::Error::other("manifest exceeds 1 MiB"));
125                }
126                self.0.extend_from_slice(bytes);
127                Ok(bytes.len())
128            }
129            fn flush(&mut self) -> std::io::Result<()> {
130                Ok(())
131            }
132        }
133        let mut writer = Limited(Vec::new());
134        serde_json::to_writer_pretty(&mut writer, self)
135            .map_err(|e| selection_error(e.to_string()))?;
136        let bytes = writer.0;
137        Ok(bytes)
138    }
139}
140impl CollectionCase {
141    /// A case with no containers, attachments, or reader options. The other
142    /// public fields can be set on the returned value.
143    #[must_use]
144    pub fn new(id: impl Into<String>, selection: CollectionSelection) -> Self {
145        Self {
146            id: id.into(),
147            containers: Vec::new(),
148            selection,
149            attachments: Vec::new(),
150            reader_options: None,
151        }
152    }
153    fn options(&self) -> Result<ParseOptions> {
154        #[cfg(feature = "sincal")]
155        let mut options = ParseOptions::default();
156        #[cfg(not(feature = "sincal"))]
157        let options = ParseOptions::default();
158        if let Some(reader) = &self.reader_options {
159            if reader
160                .snapshot_hours
161                .is_some_and(|v| !v.is_finite() || !(0.0..=24.0).contains(&v))
162            {
163                return Err(selection_error(
164                    "snapshot_hours must be finite and in [0,24]",
165                ));
166            }
167            if let Some(path) = &reader.acquired_tables {
168                ArtifactPath::new(path)?;
169            }
170            match self.selection.format_token() {
171                #[cfg(feature = "sincal")]
172                Some("sincal-balanced") => {
173                    if reader.assume_inactive_source_controls {
174                        return Err(selection_error(
175                            "inactive controls apply only to the multiconductor profile",
176                        ));
177                    }
178                    let mut selected =
179                        powerio_tnd::formats::sincal::SincalBalancedReadOptions::default();
180                    selected.variant = reader.variant;
181                    selected.snapshot_hours = reader.snapshot_hours;
182                    selected.acquired_tables.clone_from(&reader.acquired_tables);
183                    options.sincal_balanced = Some(selected);
184                }
185                #[cfg(feature = "sincal")]
186                Some("sincal-multiconductor") => {
187                    let mut selected = powerio_tnd::formats::sincal::SincalReadOptions::default();
188                    selected.variant = reader.variant;
189                    selected.snapshot_hours = reader.snapshot_hours;
190                    selected.acquired_tables.clone_from(&reader.acquired_tables);
191                    selected.assume_inactive_source_controls =
192                        reader.assume_inactive_source_controls;
193                    options.sincal_multiconductor = Some(selected);
194                }
195                _ => {
196                    return Err(selection_error(
197                        "reader_options require a supported explicit SINCAL profile",
198                    ));
199                }
200            }
201        }
202        Ok(options)
203    }
204}
205
206/// Explicit export policy. No policy infers editable-project completeness from
207/// dependency observations; use ExplicitMembers to export an observed subset.
208#[derive(Clone, Debug)]
209#[non_exhaustive]
210pub enum SourceBundleScope {
211    /// Only the primary or explicit group. Directory roots need another scope.
212    SelectedMembers,
213    /// All companions inside the selection's permitted root, including unused files.
214    Project,
215    /// Exactly these names relative to the selection's root. No implicit additions.
216    ExplicitMembers(Vec<String>),
217}
218#[derive(Clone, Debug)]
219pub struct SourceBundle {
220    pub origin: SelectionOrigin,
221    files: Vec<(ArtifactPath, Arc<[u8]>)>,
222}
223impl SourceBundle {
224    pub fn files(&self) -> &[(ArtifactPath, Arc<[u8]>)] {
225        &self.files
226    }
227    /// Package exact member bytes into a new deterministic ZIP. It is not an
228    /// original archive echo and does not rewrite names, references or encodings.
229    pub fn deterministic_zip(&self, limits: super::ArchiveLimits) -> Result<Vec<u8>> {
230        powerio_archive::package::deterministic_zip(&self.files, limits)
231    }
232}
233impl Collection {
234    pub fn origin(&self) -> CollectionOrigin {
235        CollectionOrigin {
236            collection: self.origin_name.clone(),
237            containers: self.containers.clone(),
238        }
239    }
240    pub fn selection_origin(&self, selection: &CollectionSelection) -> SelectionOrigin {
241        SelectionOrigin {
242            origin: self.origin(),
243            selection: selection.clone(),
244        }
245    }
246    /// Read bounded metadata only. Nested paths are validated syntactically;
247    /// opening them and validating selected members waits for explicit use.
248    pub fn read_manifest(&self, bytes: &[u8]) -> Result<CollectionManifest> {
249        self.cancel.check()?;
250        if bytes.len() > (1 << 20) || bytes.len() as u64 > self.limits.inspection_bytes {
251            return Err(Error::new(
252                &codes::LIMIT,
253                "manifest metadata limit exceeded",
254            ));
255        }
256        super::nested::Work::new(self.limits.work_bytes).charge(bytes.len() as u64)?;
257        let manifest: CollectionManifest =
258            serde_json::from_slice(bytes).map_err(|e| selection_error(e.to_string()))?;
259        manifest.validate(self.limits)?;
260        for case in &manifest.cases {
261            if case.containers.is_empty() {
262                self.validate_case_scope(case)?;
263            }
264        }
265        Ok(manifest)
266    }
267    fn validate_case_scope(&self, case: &CollectionCase) -> Result<()> {
268        self.source(&case.selection)?;
269        let root = case
270            .selection
271            .root
272            .as_ref()
273            .map(ArtifactPath::new)
274            .transpose()?;
275        let source = self.tree.source(root.as_ref(), None, self.limits.tree)?;
276        for attachment in &case.attachments {
277            source.root_buffer(attachment)?;
278        }
279        Ok(())
280    }
281    /// Execute one catalog case explicitly; siblings remain independent.
282    pub fn parse_manifest_case(
283        &self,
284        manifest: &CollectionManifest,
285        id: &str,
286    ) -> Result<CollectionResult> {
287        self.cancel.check()?;
288        let metadata = manifest.to_json()?;
289        if metadata.len() as u64 > self.limits.inspection_bytes {
290            return Err(Error::new(
291                &codes::LIMIT,
292                "manifest metadata limit exceeded",
293            ));
294        }
295        super::nested::Work::new(self.limits.work_bytes).charge(metadata.len() as u64)?;
296        manifest.validate(self.limits)?;
297        let case = manifest
298            .cases
299            .iter()
300            .find(|c| c.id == id)
301            .ok_or_else(|| selection_error("unknown manifest case ID"))?;
302        let mut collection = self.clone();
303        for member in &case.containers {
304            collection = collection.open_nested(member)?;
305        }
306        collection.validate_case_scope(case)?;
307        collection.parse(&case.selection, &case.options()?)
308    }
309    /// Export an explicitly requested source scope. Bytes are shared, and the
310    /// collection need not stay alive after the bundle has been returned.
311    pub fn source_bundle(
312        &self,
313        selection: &CollectionSelection,
314        scope: SourceBundleScope,
315    ) -> Result<SourceBundle> {
316        self.cancel.check()?;
317        self.source(selection)?;
318        let root = selection.root.as_ref().map(ArtifactPath::new).transpose()?;
319        let source = self.tree.source(root.as_ref(), None, self.limits.tree)?;
320        let names = match scope {
321            SourceBundleScope::SelectedMembers => selection
322                .primary
323                .as_ref()
324                .map(|p| vec![p.clone()])
325                .or_else(|| selection.members.clone())
326                .ok_or_else(|| {
327                    selection_error("dataset export requires explicit Project or member scope")
328                })?,
329            SourceBundleScope::Project => source
330                .entry_names()?
331                .into_iter()
332                .map(String::from)
333                .collect(),
334            SourceBundleScope::ExplicitMembers(names) => names,
335        };
336        if names.len() > self.limits.tree.max_files() {
337            return Err(selection_error("source bundle file limit exceeded"));
338        }
339        let mut unique = BTreeSet::new();
340        let mut files = Vec::new();
341        for name in names {
342            let path = ArtifactPath::new(&name)?;
343            if !unique.insert(path.clone()) {
344                return Err(selection_error("duplicate source bundle member"));
345            }
346            files.push((path, source.root_buffer(&name)?.shared_bytes()));
347        }
348        files.sort_by(|a, b| a.0.cmp(&b.0));
349        Ok(SourceBundle {
350            origin: self.selection_origin(selection),
351            files,
352        })
353    }
354}