Skip to main content

aff4_image/
discovery.rs

1//! Metadata-based physical-image discovery without filename conventions.
2use super::*;
3use crate::DiskImageInfo;
4use std::io::{self, Read, Seek, SeekFrom};
5use std::path::PathBuf;
6use std::sync::Mutex;
7
8/// A container required by a discovered physical image.
9#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
10pub struct BackingVolume {
11    /// AFF4 volume identifier, checked again on reopen.
12    pub volume_id: String,
13    /// Container path supplied by the caller.
14    pub path: PathBuf,
15}
16
17/// Stable identity and backing files for one decoded physical disk.
18#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
19pub struct PhysicalDisk {
20    /// Physical image resource and geometry.
21    pub image: DiskImageInfo,
22    /// Metadata-connected containers, excluding unrelated discovery candidates.
23    pub volumes: Vec<BackingVolume>,
24}
25
26impl PhysicalDisk {
27    /// Reopens exactly the recorded files and checks their identities and geometry.
28    /// This does not hash the payload; backing files must remain unchanged.
29    pub fn reopen(&self) -> Result<PhysicalDiskReader> {
30        let paths: Vec<_> = self.volumes.iter().map(|v| v.path.clone()).collect();
31        let set = DiskImageSet::discover(&paths, &[])?;
32        set.into_readers()
33            .into_iter()
34            .find(|reader| reader.info() == self)
35            .ok_or_else(|| malformed("AFF4 image or backing volume identity changed"))
36    }
37}
38
39struct Inventory {
40    container: Container,
41    path: PathBuf,
42    owned: BTreeSet<String>,
43    needs: BTreeSet<String>,
44    disks: Vec<(DiskImageInfo, bool)>,
45}
46
47fn symbolic(id: &str) -> bool {
48    volume_set::is_symbolic(id)
49}
50
51fn dependencies(
52    container: &mut Container,
53    id: &str,
54    stack: &mut Vec<String>,
55    needs: &mut BTreeSet<String>,
56) -> Result<()> {
57    if symbolic(id) {
58        return Ok(());
59    }
60    if container.inline_data(id)?.is_some() {
61        return Ok(());
62    }
63    if stack.len() >= 32 || stack.iter().any(|previous| previous == id) {
64        return Err(malformed("cyclic or excessive disk dependency depth"));
65    }
66    stack.push(id.to_owned());
67    if let Some(target) = container.value(id, "dataStream")? {
68        dependencies(container, &target, stack, needs)?;
69    } else if container.has_type(id, "Map") {
70        container.load_map(id)?;
71        let map = container.maps[id].clone();
72        let mut targets: BTreeSet<_> = map
73            .ranges
74            .iter()
75            .map(|range| range.target.clone())
76            .collect();
77        targets.insert(map.gap.clone());
78        for target in targets {
79            dependencies(container, &target, stack, needs)?;
80        }
81    } else {
82        let path = container.path(id)?;
83        let local = container.archive.index_for_name(&path).is_some()
84            || container
85                .archive
86                .index_for_name(&format!("{path}/00000000"))
87                .is_some()
88            || (container.value(id, "stored")?.as_deref() == Some(&container.volume)
89                && container.number(id, "size").ok() == Some(0));
90        if !local {
91            needs.insert(id.to_owned());
92        }
93    }
94    stack.pop();
95    Ok(())
96}
97
98impl Inventory {
99    fn new(mut container: Container, path: PathBuf) -> Result<Self> {
100        let mut owned = BTreeSet::from([container.volume.clone()]);
101        let mut needs = BTreeSet::new();
102        for id in container.graph.keys() {
103            if container.has_type(id, "ImageStream") {
104                // ZipVolume::stored may be an original filename, and case
105                // metadata is not a disk dependency. Resolve storage owners.
106                if let Some(stored) = container.value(id, "stored")?
107                    && stored != container.volume
108                {
109                    needs.insert(stored);
110                }
111                let member = format!("{}/00000000", container.path(id)?);
112                if container.archive.index_for_name(&member).is_some()
113                    || (container.number(id, "size").ok() == Some(0)
114                        && container.value(id, "stored")?.as_deref() == Some(&container.volume))
115                {
116                    owned.insert(id.clone());
117                }
118            }
119        }
120        let mut disks = Vec::new();
121        for disk in container.disk_images()? {
122            let mut dependencies_found = BTreeSet::new();
123            dependencies(
124                &mut container,
125                &disk.resource_id,
126                &mut Vec::new(),
127                &mut dependencies_found,
128            )?;
129            let mapped = !dependencies_found.is_empty();
130            needs.extend(dependencies_found);
131            disks.push((disk, mapped));
132        }
133        container.maps.clear();
134        Ok(Self {
135            container,
136            path,
137            owned,
138            needs,
139            disks,
140        })
141    }
142}
143
144/// Physical disks discovered from explicit inputs and optional nearby containers.
145/// Membership follows volume identifiers and map references, never filenames.
146pub struct DiskImageSet {
147    readers: Vec<PhysicalDiskReader>,
148}
149
150impl DiskImageSet {
151    /// Discovers every physical disk connected to an input, including when the
152    /// input is a companion. Unrelated candidates are not returned as evidence.
153    /// Candidates must be local paths; this API never follows network references.
154    pub fn discover(inputs: &[PathBuf], candidates: &[PathBuf]) -> Result<Self> {
155        Self::discover_with_limits(inputs, candidates, Limits::default())
156    }
157
158    /// Discovery inspects at most 128 distinct paths, with aggregate metadata,
159    /// directory and triple budgets. Invalid optional candidates are ignored;
160    /// unresolved dependencies of selected evidence remain errors.
161    pub fn discover_with_limits(
162        inputs: &[PathBuf],
163        candidates: &[PathBuf],
164        limits: Limits,
165    ) -> Result<Self> {
166        if inputs.is_empty() {
167            return Err(malformed("no AFF4 inputs"));
168        }
169        let mut paths = Vec::new();
170        for path in inputs.iter().chain(candidates) {
171            if !paths.contains(path) {
172                paths.push(path.clone());
173            }
174        }
175        if paths.len() > 128 {
176            return Err(malformed("AFF4 discovery exceeds 128 container paths"));
177        }
178        let mut remaining = limits.clone();
179        let mut inventory = Vec::new();
180        let mut selected = BTreeSet::new();
181        for path in paths {
182            let explicit = inputs.contains(&path);
183            let mut container = match Container::open_with_limits(&path, remaining.clone()) {
184                Ok(container) => container,
185                Err(error) if explicit => return Err(error),
186                Err(_) => continue,
187            };
188            remaining.metadata_bytes -= container.usage.metadata_bytes;
189            remaining.triples -= container.usage.triples;
190            remaining.directory_bytes -= container.usage.directory_bytes;
191            remaining.archive_entries -= container.usage.entries;
192            container.limits = limits.clone();
193            match Inventory::new(container, path) {
194                Ok(item) => {
195                    if explicit {
196                        selected.insert(inventory.len());
197                    }
198                    inventory.push(item);
199                }
200                Err(error) if explicit => return Err(error),
201                Err(_) => continue,
202            }
203        }
204        let mut providers: BTreeMap<String, Vec<usize>> = BTreeMap::new();
205        for (index, item) in inventory.iter().enumerate() {
206            for id in &item.owned {
207                providers.entry(id.clone()).or_default().push(index);
208            }
209        }
210        let mut edges = vec![BTreeSet::new(); inventory.len()];
211        for (index, item) in inventory.iter().enumerate() {
212            for need in &item.needs {
213                for &owner in providers.get(need).into_iter().flatten() {
214                    edges[index].insert(owner);
215                    edges[owner].insert(index);
216                }
217            }
218        }
219        loop {
220            let previous = selected.len();
221            for index in selected.clone() {
222                selected.extend(&edges[index]);
223            }
224            if selected.len() == previous {
225                break;
226            }
227        }
228        for &index in &selected {
229            for owned in &inventory[index].owned {
230                if providers[owned].len() != 1 {
231                    return Err(malformed(format!("ambiguous AFF4 owner for {owned}")));
232                }
233            }
234            for need in &inventory[index].needs {
235                match providers.get(need).map(Vec::len).unwrap_or(0) {
236                    1 => (),
237                    0 => return Err(malformed(format!("missing AFF4 companion for {need}"))),
238                    _ => return Err(malformed(format!("ambiguous AFF4 companion for {need}"))),
239                }
240            }
241        }
242        let mut descriptions = Vec::new();
243        for (primary, &index) in selected.iter().enumerate() {
244            let mut component = BTreeSet::from([index]);
245            loop {
246                let previous = component.len();
247                for member in component.clone() {
248                    component.extend(&edges[member]);
249                }
250                if previous == component.len() {
251                    break;
252                }
253            }
254            if component
255                .iter()
256                .all(|&member| inventory[member].disks.is_empty())
257            {
258                return Err(Error::Unsupported(format!(
259                    "no physical DiskImage found for input {}",
260                    inventory[index].path.display()
261                )));
262            }
263            let mut volumes: Vec<_> = component
264                .iter()
265                .map(|&member| BackingVolume {
266                    volume_id: inventory[member].container.volume.clone(),
267                    path: inventory[member].path.clone(),
268                })
269                .collect();
270            volumes.sort_by(|left, right| left.volume_id.cmp(&right.volume_id));
271            for (image, mapped) in &inventory[index].disks {
272                if descriptions.len() >= 128 {
273                    return Err(malformed("more than 128 physical disk images"));
274                }
275                descriptions.push((
276                    primary,
277                    *mapped,
278                    PhysicalDisk {
279                        image: image.clone(),
280                        volumes: volumes.clone(),
281                    },
282                ));
283            }
284        }
285        if descriptions.is_empty() {
286            return Err(Error::Unsupported(
287                "no physical DiskImage resources found".into(),
288            ));
289        }
290        let mut containers = Vec::new();
291        let mut paths = Vec::new();
292        for (index, item) in inventory.into_iter().enumerate() {
293            if selected.contains(&index) {
294                containers.push(item.container);
295                paths.push(item.path);
296            }
297        }
298        let mut backing = VolumeSet::from_containers(containers, paths)?;
299        let mut unique: BTreeMap<String, (usize, bool, PhysicalDisk)> = BTreeMap::new();
300        for (primary, mapped, info) in descriptions {
301            if backing.disk_size(primary, mapped, &info.image.resource_id)?
302                != info.image.logical_size
303            {
304                return Err(malformed("physical image length changed during discovery"));
305            }
306            if let Some((previous, _, original)) = unique.get(&info.image.resource_id) {
307                if original.image.logical_size != info.image.logical_size
308                    || original.image.block_size != info.image.block_size
309                    || original.volumes != info.volumes
310                    || !backing.equivalent_disk_maps(*previous, primary, &info.image.resource_id)?
311                {
312                    return Err(malformed("conflicting definitions of physical image"));
313                }
314                // Producers may replicate a disk with differently split Maps.
315                // Choose a stable primary only after proving equivalent ranges.
316                if original.image.volume_id < info.image.volume_id {
317                    continue;
318                }
319            }
320            unique.insert(info.image.resource_id.clone(), (primary, mapped, info));
321        }
322        let backing = Arc::new(Mutex::new(backing));
323        Ok(Self {
324            readers: unique
325                .into_values()
326                .map(|(primary, mapped, info)| PhysicalDiskReader {
327                    backing: backing.clone(),
328                    primary,
329                    mapped,
330                    info,
331                    position: 0,
332                })
333                .collect(),
334        })
335    }
336
337    /// Transfers all discovered disks to independent cursors with shared caches.
338    pub fn into_readers(self) -> Vec<PhysicalDiskReader> {
339        self.readers
340    }
341}
342
343/// Seekable decoded disk, including data spread across companion containers.
344pub struct PhysicalDiskReader {
345    backing: Arc<Mutex<VolumeSet>>,
346    primary: usize,
347    mapped: bool,
348    info: PhysicalDisk,
349    position: u64,
350}
351
352impl PhysicalDiskReader {
353    /// Identity, geometry and exact backing container paths.
354    pub fn info(&self) -> &PhysicalDisk {
355        &self.info
356    }
357
358    /// Returns cumulative payload-reader counters shared by this volume set.
359    pub fn reader_statistics(&self) -> Result<ReaderStatistics> {
360        Ok(self
361            .backing
362            .lock()
363            .map_err(|_| malformed("AFF4 reader lock poisoned"))?
364            .reader_statistics())
365    }
366
367    /// Returns automatic decoded payload-cache usage shared by this volume set.
368    pub fn reader_cache_info(&self) -> Result<ReaderCacheInfo> {
369        Ok(self
370            .backing
371            .lock()
372            .map_err(|_| malformed("AFF4 reader lock poisoned"))?
373            .reader_cache_info())
374    }
375
376    /// Reads decoded bytes without moving the cursor.
377    pub fn read_at(&mut self, buffer: &mut [u8], offset: u64) -> Result<usize> {
378        self.backing
379            .lock()
380            .map_err(|_| malformed("AFF4 reader lock poisoned"))?
381            .read_disk_at(
382                self.primary,
383                self.mapped,
384                &self.info.image.resource_id,
385                buffer,
386                offset,
387            )
388    }
389}
390
391impl Read for PhysicalDiskReader {
392    fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
393        let count = self
394            .read_at(buffer, self.position)
395            .map_err(io::Error::other)?;
396        self.position += count as u64;
397        Ok(count)
398    }
399}
400
401impl Seek for PhysicalDiskReader {
402    fn seek(&mut self, from: SeekFrom) -> io::Result<u64> {
403        let position = match from {
404            SeekFrom::Start(offset) => Some(offset),
405            SeekFrom::End(offset) => self.info.image.logical_size.checked_add_signed(offset),
406            SeekFrom::Current(offset) => self.position.checked_add_signed(offset),
407        }
408        .ok_or_else(|| {
409            io::Error::new(io::ErrorKind::InvalidInput, "AFF4 seek outside u64 range")
410        })?;
411        self.position = position;
412        Ok(position)
413    }
414}