Skip to main content

openreadout_core/
reader.rs

1//! The traits every format crate implements, and the registry that dispatches on them.
2
3use std::io::Read;
4use std::path::Path;
5
6use crate::error::{Error, Result};
7use crate::model::{
8    AttachmentInfo, CheckReport, DetectConfidence, FileInfo, FormatDescriptor, LsEntry, Spectrum,
9    Table, Trace,
10};
11use crate::pixel::Plane;
12use crate::provenance::ProvenanceMap;
13use crate::source::Input;
14
15/// Result of sniffing a file's first bytes.
16#[derive(Debug, Clone)]
17pub struct Detection {
18    /// Format id of the reader that matched.
19    pub format_id: &'static str,
20    /// How sure the match is.
21    pub confidence: DetectConfidence,
22    /// Why the match is less than definite, if it is.
23    pub note: Option<String>,
24}
25
26/// Which representation `read_spectrum_view` returns when a scan stores more than one
27/// (Fourier-transform instruments typically keep a profile *and* the instrument's centroid list).
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
29#[non_exhaustive]
30pub enum SpectrumView {
31    /// The scan's primary data: the profile when one was recorded, otherwise the centroids.
32    #[default]
33    Primary,
34    /// The centroid list stored by the instrument software, when the scan has one; otherwise
35    /// the same as `Primary`.
36    Centroid,
37}
38
39/// Which plane of an image to read. All zero-based.
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
41pub struct PlaneIndex {
42    /// Channel index.
43    pub c: u32,
44    /// Z index (focal plane).
45    pub z: u32,
46    /// Time index.
47    pub t: u32,
48}
49
50/// An open file. Implementations must keep `info` cheap: read headers, never pixels.
51pub trait Dataset: Send {
52    /// Header-only summary.
53    fn info(&self) -> Result<FileInfo>;
54    /// The vendor's metadata tree as JSON, names untouched.
55    fn vendor_metadata(&self) -> Result<serde_json::Value>;
56    /// Provenance of the normalized fields this reader fills.
57    fn provenance(&self) -> ProvenanceMap;
58    /// Structural listing for `info --view structure`.
59    fn entries(&self) -> Result<Vec<LsEntry>>;
60    /// Read one full-resolution plane. Mosaics are stitched; pyramids are ignored.
61    fn read_plane(&mut self, image: u32, index: PlaneIndex) -> Result<Plane>;
62    /// Integrity validation for `check`.
63    fn check(&mut self) -> Result<CheckReport>;
64    /// Integrity validation that reads headers and structure only (`check --headers-only`, and
65    /// the `index` crawl): offsets, declared sizes and counts against the file length, missing
66    /// parts; no decompression, no decoding of samples and no checksums over the data. Readers
67    /// whose `check` decodes data override it; the default is `check`, which for most formats
68    /// already reads only headers and structure.
69    fn check_headers(&mut self) -> Result<CheckReport> {
70        self.check()
71    }
72    /// Other files on disk that belong to this dataset (multi-file OME-TIFF members, CZI file
73    /// parts, OIR continuation files, a SpikeGLX `.meta`/`.bin` pair, an imzML `.ibd`, VSI
74    /// `.ets` stacks, ...), excluding the path that was opened. Only files that exist are
75    /// listed. `index` records them as members of this dataset instead of separate records.
76    /// Directory datasets (a Bruker `.d`, a ChemStation `.D`) keep the default: the directory
77    /// itself is the dataset.
78    fn member_files(&self) -> Vec<std::path::PathBuf> {
79        Vec::new()
80    }
81    /// Evidence that the file is not finished: the structures its software writes last that
82    /// are absent and the planes already complete ([`crate::live::WriteState`]). `None` for
83    /// finished files and for formats that do not know their write order (the default).
84    /// [`crate::live::assess`] turns it into `acquisition: in_progress | interrupted`.
85    fn write_state(&self) -> Option<crate::live::WriteState> {
86        None
87    }
88    /// Rows `[first_row, first_row + max_rows)` of table `index`. Formats without tables keep the default.
89    fn read_table(&mut self, index: u32, first_row: u64, max_rows: u64) -> Result<Table> {
90        let _ = (index, first_row, max_rows);
91        Err(Error::unsupported(
92            "core",
93            "tabular data",
94            "This format exposes images, not tables.",
95        ))
96    }
97    /// Samples `[first_sample, first_sample + max_samples)` of sweep `sweep` of trace `index`.
98    fn read_trace(
99        &mut self,
100        index: u32,
101        sweep: u32,
102        first_sample: u64,
103        max_samples: u64,
104    ) -> Result<Trace> {
105        let _ = (index, sweep, first_sample, max_samples);
106        Err(Error::unsupported(
107            "core",
108            "sampled signals",
109            "This format does not expose traces.",
110        ))
111    }
112    /// Spectrum `spectrum` of run `index`. Formats without spectra keep the default.
113    fn read_spectrum(&mut self, index: u32, spectrum: u64) -> Result<Spectrum> {
114        let _ = (index, spectrum);
115        Err(Error::unsupported(
116            "core",
117            "mass spectra",
118            "This format exposes images, not spectra.",
119        ))
120    }
121    /// MS level of every spectrum of run `run`, in spectrum-index order, when the reader knows
122    /// them without decoding peaks (a scan index, per-scan events, header summaries). `None`
123    /// (the default) means unknown: [`spectrum_by_level`] then reads the spectra one by one.
124    fn spectrum_ms_levels(&mut self, run: u32) -> Result<Option<Vec<u32>>> {
125        let _ = run;
126        Ok(None)
127    }
128    /// Zero-based index of the spectrum with instrument scan number `scan_number` in run `run`.
129    /// `Ok(None)` means the reader keeps no scan-number map; callers then assume scan numbers
130    /// are contiguous from the first spectrum's (see [`spectrum_by_scan`]).
131    fn find_spectrum(&mut self, run: u32, scan_number: u64) -> Result<Option<u64>> {
132        let _ = (run, scan_number);
133        Ok(None)
134    }
135    /// Visit the headers of run `run`'s spectra from spectrum `first` on, in index order,
136    /// without decoding any peaks (scan number, MS level, RT, polarity, precursor, isolation,
137    /// activation, filter, the file's stored TIC/base peak: [`crate::scans::ScanHeader`]).
138    /// `visit` returns false to stop. `Ok(false)` (the default) means the reader has no
139    /// header-only path; [`crate::scans::visit_scans`] then decodes the spectra.
140    fn visit_scan_headers(
141        &mut self,
142        run: u32,
143        first: u64,
144        visit: &mut dyn FnMut(crate::scans::ScanHeader) -> bool,
145    ) -> Result<bool> {
146        let _ = (run, first, visit);
147        Ok(false)
148    }
149    /// Like `read_spectrum`, choosing between stored representations. Formats that store only one
150    /// keep the default, which ignores `view`.
151    fn read_spectrum_view(
152        &mut self,
153        index: u32,
154        spectrum: u64,
155        view: SpectrumView,
156    ) -> Result<Spectrum> {
157        let _ = view;
158        self.read_spectrum(index, spectrum)
159    }
160    /// Read one plane of pyramid level `level` (0 = full resolution, larger = more downsampled;
161    /// `ImageInfo::pyramid_levels` says how many exist). Formats without pyramids keep the
162    /// default, which serves level 0 and rejects the rest.
163    fn read_plane_level(&mut self, image: u32, index: PlaneIndex, level: u32) -> Result<Plane> {
164        if level == 0 {
165            return self.read_plane(image, index);
166        }
167        Err(Error::unsupported(
168            "core",
169            "pyramid level reads",
170            "This format does not expose downsampled pyramid levels; read level 0.",
171        ))
172    }
173    /// Read the rectangle `region` of one plane of pyramid level `level`, in that level's pixel
174    /// coordinates (see [`crate::region`]). A region outside the level is a usage error (exit
175    /// 2). Readers that store pixels in tiles, subblocks or chunks override it to decode only
176    /// the tiles the region touches, which also makes regions of planes too large to assemble
177    /// whole ([`crate::pixel::MAX_PLANE_BYTES`]) readable. The default reads the whole plane at
178    /// the level and crops it.
179    fn read_region(
180        &mut self,
181        image: u32,
182        index: PlaneIndex,
183        level: u32,
184        region: crate::region::Region,
185    ) -> Result<Plane> {
186        let plane = self.read_plane_level(image, index, level)?;
187        crate::region::crop(plane, region, &format!("image {image} level {level}"))
188    }
189    /// Which parts of one plane of level `level` (or of `region` of it) hold stored tiles, as
190    /// rectangles in the coordinates of the plane [`Dataset::read_region`] returns (the
191    /// region's top-left corner is 0, 0). Mosaic scans leave areas where nothing was
192    /// acquired, and readers return 0 there. Previews use this to draw those areas as
193    /// background instead of as black data. `None` (the default) means the reader stores the
194    /// whole plane or does not know.
195    fn stored_areas(
196        &mut self,
197        image: u32,
198        index: PlaneIndex,
199        level: u32,
200        region: Option<crate::region::Region>,
201    ) -> Result<Option<Vec<crate::region::Region>>> {
202        let _ = (image, index, level, region);
203        Ok(None)
204    }
205    /// Whether [`Dataset::read_strips`] decodes each stored tile of `image` at `level` once for
206    /// all the strips of a plane. A reader whose tiles are not on a grid (overlapping CZI
207    /// mosaic tiles) returns `true`, because separate strip reads would decode the tiles that
208    /// cross a strip edge once per strip. `stats` then reads the plane through
209    /// [`Dataset::read_strips`] instead of as separate regions.
210    fn reads_strips(&self, image: u32, level: u32) -> bool {
211        let _ = (image, level);
212        false
213    }
214    /// Read the `strips` of one plane of level `level` (regions of the level, top to bottom)
215    /// and hand each to `sink` in order. The default reads each strip with
216    /// [`Dataset::read_region`].
217    fn read_strips(
218        &mut self,
219        image: u32,
220        index: PlaneIndex,
221        level: u32,
222        strips: &[crate::region::Region],
223        sink: &mut dyn FnMut(Plane) -> Result<()>,
224    ) -> Result<()> {
225        for &r in strips {
226            let p = self.read_region(image, index, level, r)?;
227            sink(p)?;
228        }
229        Ok(())
230    }
231    /// How many consecutive z planes of `image` at `level` share one stored chunk, so that
232    /// reading them on one handle decodes each chunk once (HDF5 and Zarr chunks deeper than
233    /// one plane). Parallel reads give such runs to one worker. 1 (the default) means planes
234    /// are stored apart.
235    fn z_planes_per_chunk(&self, image: u32, level: u32) -> u32 {
236        let _ = (image, level);
237        1
238    }
239    /// Why the reader refuses every plane of `image` (exit 6), when it knows that without
240    /// reading: raw data it recognises but does not decode, such as Leica FALCON photon
241    /// histograms. `None` (the default) means the planes are read. Whole-file `stats` and
242    /// `export` leave such images out and list them; asking for one by `--image` still
243    /// fails with the reader's error.
244    fn pixels_refused(&self, image: u32) -> Option<String> {
245        let _ = image;
246        None
247    }
248    /// Files embedded in the container (thumbnails, label images, time stamps, ...).
249    fn attachments(&self) -> Result<Vec<AttachmentInfo>> {
250        Ok(Vec::new())
251    }
252    /// Raw bytes of attachment `index` (see `attachments`).
253    fn read_attachment(&mut self, index: u32) -> Result<Vec<u8>> {
254        let _ = index;
255        Err(Error::unsupported(
256            "core",
257            "attachments",
258            "This format has no embedded attachments; `info --view structure` lists what the file contains.",
259        ))
260    }
261    /// The sum of the time points `ts` of image `image` at channel `c` and plane `z`, as 32-bit
262    /// float samples (a movie's frames added up: its dose image). The default reads and adds
263    /// every plane; readers whose frames are sparse (electron-event movies) add their events
264    /// directly.
265    fn sum_planes(&mut self, image: u32, c: u32, z: u32, ts: &[u32]) -> Result<Plane> {
266        sum_planes_by_reading(self, image, c, z, ts)
267    }
268    /// Per-frame acquisition records of image `image` (acquisition time, stage position,
269    /// detector state, ...), too numerous for `info`. Each record is a JSON object in the
270    /// reader's documented vocabulary. At most `limit` records are returned (`None` = all);
271    /// the first value is the total number of records. `info --view full` stores them under
272    /// `images[i].extra.frames` (see [`attach_frames`]). Formats without per-frame records keep
273    /// the default (no records).
274    fn frames(&self, image: u32, limit: Option<usize>) -> Result<(u64, Vec<serde_json::Value>)> {
275        let _ = (image, limit);
276        Ok((0, Vec::new()))
277    }
278    /// Experiment facts this reader knows that the normalized model cannot carry (a Bruker NMR
279    /// `title` file, an mzML `sampleList`), each value with its origin in `provenance`. They are
280    /// laid over the experiment derived from `info` ([`crate::experiment::of_dataset`]). Most
281    /// readers keep the default: everything they know is already in `info`.
282    fn experiment(&self) -> Option<crate::experiment::Experiment> {
283        None
284    }
285    /// The layout of a multi-well plate (high-content screening): imaged wells, the images of
286    /// each, and how complete the copy on disk is. `info` reports it under `plate`. Readers
287    /// of other files keep the default (none).
288    fn plate(&self) -> Option<crate::plate::PlateSummary> {
289        None
290    }
291    /// What the reader itself knows about this file's variant beyond `info` (structures met
292    /// but not decoded, values assumed, calibrations, block types), laid over its assurance
293    /// profile's observations ([`crate::assurance::assess`]). Most readers keep the default:
294    /// their profile reads everything it needs from `info`. Wrappers forward it.
295    fn assurance_observations(&self) -> crate::assurance::Observations {
296        crate::assurance::Observations::default()
297    }
298    /// This file's assurance ([`crate::assurance::assess_dataset`] over `info`); `None` when
299    /// `info` cannot be read. The strict-mode wrapper returns the assessment it gates on, so
300    /// `check` reports it even when strict mode refuses `info`.
301    fn file_assurance(&self) -> Option<crate::assurance::Assurance> {
302        let info = self.info().ok()?;
303        Some(crate::assurance::assess(
304            &info,
305            self.assurance_observations(),
306            &self.provenance(),
307        ))
308    }
309    /// Leave the peaks the instrument flags as reference or background ions out of the spectra
310    /// read from now on (Thermo `.raw`: what ThermoRawFileParser and ProteoWizard before
311    /// 3.0.20286 write). Returns false when the format flags no peaks (nothing changes).
312    fn exclude_flagged_peaks(&mut self, exclude: bool) -> bool {
313        let _ = exclude;
314        false
315    }
316    /// Correct the m/z of the spectra read from now on with the file's lock-spray (lock-mass)
317    /// reference scans, `reference_mz` being the lock compound's true m/z (`None`: the one the
318    /// file records). Returns `Ok(false)` when the format has no lock-mass reference (nothing
319    /// changes); an error when the file names no reference m/z and none is given, or no
320    /// reference scan holds the lock peak.
321    fn set_lock_mass(&mut self, reference_mz: Option<f64>) -> crate::Result<bool> {
322        let _ = reference_mz;
323        Ok(false)
324    }
325    /// True for the `--strict` wrapper ([`crate::strict::StrictDataset`]): outputs built from
326    /// it withhold the fields its assurance does not validate (`Assurance::strict_withholds`).
327    fn is_strict(&self) -> bool {
328        false
329    }
330}
331
332/// [`Dataset::sum_planes`] by reading every plane and adding its samples.
333pub fn sum_planes_by_reading<D: Dataset + ?Sized>(
334    ds: &mut D,
335    image: u32,
336    channel: u32,
337    plane_z: u32,
338    ts: &[u32],
339) -> Result<Plane> {
340    let mut acc: Vec<f32> = Vec::new();
341    let (mut width, mut height) = (0u32, 0u32);
342    for &t in ts {
343        let p = ds.read_plane(
344            image,
345            PlaneIndex {
346                c: channel,
347                z: plane_z,
348                t,
349            },
350        )?;
351        if p.samples_per_pixel != 1 {
352            return Err(Error::Usage(
353                "frames with several samples per pixel (RGB) are not summed".into(),
354            ));
355        }
356        let bps = p.pixel_type.bytes_per_sample();
357        let n = p.width as usize * p.height as usize;
358        if acc.is_empty() {
359            (width, height) = (p.width, p.height);
360            acc = vec![0f32; n];
361        } else if (p.width, p.height) != (width, height) {
362            return Err(Error::Other(format!(
363                "frame t={t} is {}x{}, the first {width}x{height}: frames of different sizes are not summed",
364                p.width, p.height
365            )));
366        }
367        for (a, sample) in acc.iter_mut().zip(p.data.chunks_exact(bps)) {
368            *a += p.pixel_type.sample_f64(sample) as f32;
369        }
370    }
371    if ts.is_empty() {
372        return Err(Error::Usage("no frames to sum".into()));
373    }
374    Ok(Plane {
375        width,
376        height,
377        pixel_type: crate::PixelType::Float,
378        samples_per_pixel: 1,
379        data: acc.iter().flat_map(|v| v.to_le_bytes()).collect(),
380    })
381}
382
383/// Read the spectrum with instrument scan number `scan` of run `run`: through
384/// [`Dataset::find_spectrum`] when the reader has a scan-number map, otherwise assuming scan
385/// numbers are contiguous from the first spectrum's.
386pub fn spectrum_by_scan(
387    ds: &mut dyn Dataset,
388    run: u32,
389    scan: u64,
390    view: SpectrumView,
391) -> Result<Spectrum> {
392    if let Some(i) = ds.find_spectrum(run, scan)? {
393        return ds.read_spectrum_view(run, i, view);
394    }
395    let first = ds.read_spectrum_view(run, 0, view)?;
396    let i = scan.checked_sub(first.scan_number).ok_or_else(|| {
397        Error::Usage(format!(
398            "scan {scan} precedes the first scan ({})",
399            first.scan_number
400        ))
401    })?;
402    let sp = if i == 0 {
403        first
404    } else {
405        ds.read_spectrum_view(run, i, view)?
406    };
407    if sp.scan_number != scan {
408        return Err(Error::Usage(format!(
409            "scan numbers are not contiguous; spectrum {i} is scan {}. Use --spectrum (the zero-based index)",
410            sp.scan_number
411        )));
412    }
413    Ok(sp)
414}
415
416/// Read the spectrum at zero-based `index` among the spectra of MS level `ms_level` in run `run`
417/// (`index` 0 is the first MS/MS scan when `ms_level` is 2). MS1 and MS/MS scans are interleaved
418/// in most runs, so the first MS2 scan cannot be found by assuming the MS1 scans come first: the
419/// reader's per-spectrum MS levels ([`Dataset::spectrum_ms_levels`]) locate it and only that
420/// spectrum is decoded. A reader without them is walked from its first spectrum, with
421/// `scan_count` (from `info` → `spectra[run].scan_count`) bounding the walk.
422pub fn spectrum_by_level(
423    ds: &mut dyn Dataset,
424    run: u32,
425    ms_level: u32,
426    index: u64,
427    scan_count: u64,
428    view: SpectrumView,
429) -> Result<Spectrum> {
430    let mut seen = 0u64;
431    let too_few = |seen: u64| {
432        Error::Usage(format!(
433            "run {run} has {seen} MS{ms_level} spectra, so the zero-based index {index} is out of range; `info` → spectra[].extra.ms_level_counts lists the counts"
434        ))
435    };
436    if let Some(levels) = ds.spectrum_ms_levels(run)? {
437        for (i, l) in levels.iter().enumerate() {
438            if *l == ms_level {
439                if seen == index {
440                    return ds.read_spectrum_view(run, i as u64, view);
441                }
442                seen += 1;
443            }
444        }
445        return Err(too_few(seen));
446    }
447    for i in 0..scan_count {
448        let sp = ds.read_spectrum_view(run, i, view)?;
449        if sp.ms_level == ms_level {
450            if seen == index {
451                return Ok(sp);
452            }
453            seen += 1;
454        }
455    }
456    Err(too_few(seen))
457}
458
459/// Default number of per-frame records `info --view full` embeds per image (`--max-frames -1` lifts
460/// it).
461pub const DEFAULT_FRAME_RECORDS: usize = 100;
462
463/// Store each image's per-frame records under `extra.frames` (plus `extra.frame_records_total`
464/// and, when capped, `extra.frames_truncated: true`). Images without records are left untouched.
465pub fn attach_frames(ds: &dyn Dataset, info: &mut FileInfo, limit: Option<usize>) -> Result<()> {
466    for img in &mut info.images {
467        let (total, records) = ds.frames(img.index, limit)?;
468        if records.is_empty() {
469            continue;
470        }
471        let truncated = (records.len() as u64) < total;
472        img.extra
473            .insert("frames".into(), serde_json::Value::Array(records));
474        img.extra
475            .insert("frame_records_total".into(), serde_json::Value::from(total));
476        if truncated {
477            img.extra
478                .insert("frames_truncated".into(), serde_json::Value::Bool(true));
479        }
480    }
481    Ok(())
482}
483
484/// A format implementation.
485pub trait FormatReader: Send + Sync {
486    /// Static description of the format (id, name, extensions, known gaps).
487    fn descriptor(&self) -> FormatDescriptor;
488    /// Inspect the first bytes (up to 64 KiB) and the path; return `None` if this is not ours.
489    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection>;
490    /// Open for reading.
491    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>>;
492    /// Like [`sniff`](FormatReader::sniff), for an [`Input`] that may not be on the local file
493    /// system. Readers whose detection looks at other files (a directory's contents, a
494    /// sibling) override it to look through [`Input::fs`]; the default calls `sniff` with the
495    /// input's path.
496    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
497        self.sniff(head, input.path())
498    }
499    /// Open an [`Input`]: a local path, a buffer in memory, or a source the host provides.
500    /// Readers that read through [`Input::fs`] override it (and make `open` a thin wrapper);
501    /// the default opens local inputs by path and reports every other source as unsupported
502    /// (exit 6), so a reader that does not read through byte sources never touches the local disk
503    /// for a buffer that merely has the same name.
504    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
505        if input.is_local() {
506            return self.open(input.path());
507        }
508        let d = self.descriptor();
509        Err(Error::Unsupported {
510            format: "input",
511            feature: format!(
512                "reading {} ({}) from an in-memory or host-provided source",
513                d.name, d.id
514            ),
515            hint: Some(
516                "This reader opens local files only so far: save the data to a file and open its path."
517                    .into(),
518            ),
519        })
520    }
521    /// True when [`open_input`](FormatReader::open_input) reads any [`Input`] (memory, host
522    /// callbacks), not only local paths.
523    fn reads_any_source(&self) -> bool {
524        false
525    }
526    /// The reader's assurance profile (its crate's `src/assurance.rs`): how to fingerprint a
527    /// file's variant and which variants the development corpus validates. `None` (the
528    /// default) makes every file of the format `unvalidated`.
529    fn assurance(&self) -> Option<&'static crate::assurance::AssuranceProfile> {
530        None
531    }
532}
533
534/// Number of leading bytes handed to `sniff`.
535pub const SNIFF_LEN: usize = 64 * 1024;
536
537/// Ordered collection of readers. First definite match wins; otherwise best confidence.
538pub struct Registry {
539    readers: Vec<Box<dyn FormatReader>>,
540    /// `--strict`: datasets opened through this registry refuse outputs their file's
541    /// assurance does not validate ([`crate::strict`]).
542    strict: bool,
543}
544
545impl std::fmt::Debug for Registry {
546    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
547        let ids: Vec<String> = self.readers.iter().map(|r| r.descriptor().id).collect();
548        f.debug_struct("Registry")
549            .field("readers", &ids)
550            .field("strict", &self.strict)
551            .finish()
552    }
553}
554
555impl Default for Registry {
556    /// An empty registry, strict when the process-wide default says so
557    /// ([`crate::assurance::default_strict`]: `--strict`, `OPENREADOUT_STRICT=1`).
558    fn default() -> Self {
559        Registry {
560            readers: Vec::new(),
561            strict: crate::assurance::default_strict(),
562        }
563    }
564}
565
566impl Registry {
567    /// An empty registry. Readers are consulted in the order they are added.
568    pub fn new() -> Self {
569        Self::default()
570    }
571
572    /// Add a reader at the end of the detection order (and make its assurance profile known).
573    pub fn register(&mut self, reader: Box<dyn FormatReader>) {
574        if let Some(p) = reader.assurance() {
575            crate::assurance::register_profile(p);
576        }
577        self.readers.push(reader);
578    }
579
580    /// Strict mode (`--strict`, MCP `strict: true`): every dataset this registry opens refuses,
581    /// with exit 6 and a hint, to return outputs its file's assurance does not validate
582    /// (`assurance.strict_refuses`: an unvalidated variant, an undecoded structure or an unapplied
583    /// calibration affecting them). `check` and `info --view structure` are never refused.
584    #[must_use]
585    pub fn strict(mut self, on: bool) -> Self {
586        self.strict = on;
587        self
588    }
589
590    /// True in strict mode.
591    pub fn is_strict(&self) -> bool {
592        self.strict
593    }
594
595    /// Builder form of [`Registry::register`].
596    pub fn with(mut self, reader: Box<dyn FormatReader>) -> Self {
597        self.register(reader);
598        self
599    }
600
601    /// Descriptors of every registered reader, in detection order.
602    pub fn descriptors(&self) -> Vec<FormatDescriptor> {
603        self.readers.iter().map(|r| r.descriptor()).collect()
604    }
605
606    /// The reader with this format id, if registered.
607    pub fn by_id(&self, id: &str) -> Option<&dyn FormatReader> {
608        self.readers
609            .iter()
610            .find(|r| r.descriptor().id == id)
611            .map(AsRef::as_ref)
612    }
613
614    /// Read the head of the file and ask every reader. A directory (a vendor "folder format"
615    /// such as a Bruker `.d`) is offered to every reader with an empty head; readers that accept
616    /// directories recognise them by their path and contents.
617    pub fn detect(&self, path: &Path) -> Result<(&dyn FormatReader, Detection)> {
618        self.detect_input(&Input::local(path))
619    }
620
621    /// Like [`detect`](Registry::detect), for any [`Input`] (a local path, a buffer, a host
622    /// source).
623    pub fn detect_input(&self, input: &Input) -> Result<(&dyn FormatReader, Detection)> {
624        let path = input.path();
625        let meta = input.metadata()?;
626        let mut head = Vec::new();
627        if !meta.is_dir() {
628            let mut file = input.open()?;
629            head = vec![0u8; SNIFF_LEN];
630            let mut filled = 0;
631            while filled < head.len() {
632                let n = file
633                    .read(&mut head[filled..])
634                    .map_err(|e| Error::io(path, e))?;
635                if n == 0 {
636                    break;
637                }
638                filled += n;
639            }
640            head.truncate(filled);
641            if filled == 0 {
642                // An empty file is a truncated file (interrupted copy or acquisition), not an
643                // unknown format: report it as corrupt so agents do not go looking for a reader.
644                return Err(Error::Corrupt {
645                    format: "input",
646                    detail: "the file is empty (0 bytes)".into(),
647                    offset: Some(0),
648                });
649            }
650        }
651        if is_apple_double(&head) {
652            return Err(Error::UnknownFormat {
653                path: path.to_path_buf(),
654            });
655        }
656        let mut best: Option<(&dyn FormatReader, Detection)> = None;
657        for r in &self.readers {
658            if let Some(d) = r.sniff_input(&head, input) {
659                let better = match &best {
660                    None => true,
661                    Some((_, b)) => rank(d.confidence) > rank(b.confidence),
662                };
663                if better {
664                    let definite = d.confidence == DetectConfidence::Definite;
665                    best = Some((r.as_ref(), d));
666                    if definite {
667                        break;
668                    }
669                }
670            }
671        }
672        best.ok_or_else(|| Error::UnknownFormat {
673            path: path.to_path_buf(),
674        })
675    }
676
677    /// Detect and open.
678    pub fn open(&self, path: &Path) -> Result<(Detection, Box<dyn Dataset>)> {
679        let (reader, det) = self.detect(path)?;
680        let ds = reader
681            .open(path)
682            .map_err(|e| extension_only_context(e, &det))?;
683        Ok((det, self.guard(ds)?))
684    }
685
686    /// In strict mode, wrap `ds` so it refuses unvalidated outputs; otherwise return it as is.
687    pub fn guard(&self, ds: Box<dyn Dataset>) -> Result<Box<dyn Dataset>> {
688        if self.strict {
689            crate::strict::StrictDataset::wrap(ds)
690        } else {
691            Ok(ds)
692        }
693    }
694
695    /// Detect and open any [`Input`]. Readers that only read local files report other inputs
696    /// as unsupported (exit 6).
697    pub fn open_input(&self, input: &Input) -> Result<(Detection, Box<dyn Dataset>)> {
698        let (reader, det) = self.detect_input(input)?;
699        let ds = reader
700            .open_input(input)
701            .map_err(|e| extension_only_context(e, &det))?;
702        Ok((det, self.guard(ds)?))
703    }
704
705    /// Detect from bytes already in memory (the first up to [`SNIFF_LEN`] bytes of a stream,
706    /// e.g. standard input). `name` stands in for the path readers may consult for an extension.
707    pub fn detect_bytes(&self, head: &[u8], name: &Path) -> Result<(&dyn FormatReader, Detection)> {
708        let head = &head[..head.len().min(SNIFF_LEN)];
709        if is_apple_double(head) {
710            return Err(Error::UnknownFormat {
711                path: name.to_path_buf(),
712            });
713        }
714        let mut best: Option<(&dyn FormatReader, Detection)> = None;
715        for r in &self.readers {
716            if let Some(d) = r.sniff(head, name)
717                && best
718                    .as_ref()
719                    .is_none_or(|(_, b)| rank(d.confidence) > rank(b.confidence))
720            {
721                let definite = d.confidence == DetectConfidence::Definite;
722                best = Some((r.as_ref(), d));
723                if definite {
724                    break;
725                }
726            }
727        }
728        best.ok_or_else(|| Error::UnknownFormat {
729            path: name.to_path_buf(),
730        })
731    }
732}
733
734/// A reader chosen only for the file's extension that then fails to open it says so: the file
735/// may be another kind of file with that extension (a JSON model named `.emd`, a Java object
736/// stream named `.ser`, a library catalogue named `.mrc`), not a damaged one.
737fn extension_only_context(e: Error, det: &Detection) -> Error {
738    if det.confidence != DetectConfidence::ExtensionOnly {
739        return e;
740    }
741    match e {
742        Error::Corrupt {
743            format,
744            detail,
745            offset,
746        } => Error::Corrupt {
747            format,
748            detail: format!("{detail} ({})", crate::error::EXTENSION_ONLY),
749            offset,
750        },
751        Error::Unsupported {
752            format,
753            feature,
754            hint,
755        } => Error::Unsupported {
756            format,
757            feature: format!("{feature} ({})", crate::error::EXTENSION_ONLY),
758            hint: Some(match hint {
759                Some(h) => format!("{} {h}", crate::error::EXTENSION_ONLY_HINT),
760                None => crate::error::EXTENSION_ONLY_HINT.into(),
761            }),
762        },
763        other => other,
764    }
765}
766
767/// A macOS AppleDouble or AppleSingle file (`._name`: Finder metadata that macOS writes next to
768/// `name` on disks without its own file attributes, and into zip archives). It holds no data,
769/// whatever its extension says.
770fn is_apple_double(head: &[u8]) -> bool {
771    head.starts_with(&[0x00, 0x05, 0x16, 0x07]) || head.starts_with(&[0x00, 0x05, 0x16, 0x00])
772}
773
774fn rank(c: DetectConfidence) -> u8 {
775    match c {
776        DetectConfidence::Definite => 3,
777        DetectConfidence::Likely => 2,
778        DetectConfidence::ExtensionOnly => 1,
779    }
780}
781
782/// Helper for readers: does the path have one of these extensions (case-insensitive)?
783pub fn has_extension(path: &Path, exts: &[&str]) -> bool {
784    path.extension()
785        .and_then(|e| e.to_str())
786        .is_some_and(|e| exts.iter().any(|x| x.eq_ignore_ascii_case(e)))
787}
788
789#[cfg(test)]
790mod tests {
791    use super::*;
792    use crate::provenance::Confidence;
793
794    #[derive(Debug)]
795    struct PathOnly;
796
797    impl FormatReader for PathOnly {
798        fn descriptor(&self) -> FormatDescriptor {
799            FormatDescriptor {
800                id: "path-only".into(),
801                name: "Path-only test format".into(),
802                vendor: String::new(),
803                extensions: vec!["po".into()],
804                family: "test".into(),
805                can_read: true,
806                can_write: false,
807                confidence: Confidence::Low,
808                known_gaps: Vec::new(),
809            }
810        }
811        fn sniff(&self, head: &[u8], _path: &Path) -> Option<Detection> {
812            head.starts_with(b"PO").then_some(Detection {
813                format_id: "path-only",
814                confidence: DetectConfidence::Definite,
815                note: None,
816            })
817        }
818        fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
819            Err(Error::Other(format!("opened {}", path.display())))
820        }
821    }
822
823    #[test]
824    fn unmigrated_readers_refuse_non_file_inputs() {
825        let reg = Registry::new().with(Box::new(PathOnly));
826        let input = Input::from_bytes("x.po", b"PO data".to_vec());
827        let (r, det) = reg.detect_input(&input).unwrap();
828        assert_eq!(det.format_id, "path-only");
829        assert!(!r.reads_any_source());
830        let err = reg.open_input(&input).map(|_| ()).unwrap_err();
831        assert_eq!(err.exit_code(), 6, "{err}");
832        assert!(err.hint().is_some());
833        // Local paths still reach `open`.
834        let dir = tempfile::tempdir().unwrap();
835        let path = dir.path().join("x.po");
836        std::fs::write(&path, b"PO data").unwrap();
837        let err = reg
838            .open_input(&Input::local(&path))
839            .map(|_| ())
840            .unwrap_err();
841        assert!(err.to_string().starts_with("opened "), "{err}");
842        // Empty inputs are corrupt, missing ones are I/O errors, like `detect`.
843        let empty = Input::from_bytes("e.po", Vec::new());
844        let code = |i: &Input| reg.detect_input(i).map(|_| ()).unwrap_err().exit_code();
845        assert_eq!(code(&empty), 4);
846        assert_eq!(code(&empty.with_path("other.po")), 5);
847    }
848
849    /// Matches `.ext` files by name only and finds them corrupt.
850    #[derive(Debug)]
851    struct ByName;
852
853    impl FormatReader for ByName {
854        fn descriptor(&self) -> FormatDescriptor {
855            FormatDescriptor {
856                extensions: vec!["ext".into()],
857                ..PathOnly.descriptor()
858            }
859        }
860        fn sniff(&self, _head: &[u8], path: &Path) -> Option<Detection> {
861            (path.extension()? == "ext").then_some(Detection {
862                format_id: "by-name",
863                confidence: DetectConfidence::ExtensionOnly,
864                note: None,
865            })
866        }
867        fn open(&self, _path: &Path) -> Result<Box<dyn Dataset>> {
868            Err(Error::corrupt("by-name", "no signature"))
869        }
870    }
871
872    #[test]
873    fn apple_double_files_are_not_data() {
874        let reg = Registry::new().with(Box::new(ByName));
875        let dir = tempfile::tempdir().unwrap();
876        let path = dir.path().join("._spectrum.ext");
877        let mut b = vec![0x00, 0x05, 0x16, 0x07, 0x00, 0x02, 0x00, 0x00];
878        b.extend_from_slice(b"Mac OS X        ");
879        std::fs::write(&path, &b).unwrap();
880        let err = reg.open(&path).map(|_| ()).unwrap_err();
881        assert_eq!(err.exit_code(), 3, "{err}");
882        assert!(err.hint().unwrap().contains("AppleDouble"));
883        let err = reg.detect_bytes(&b, &path).map(|_| ()).unwrap_err();
884        assert_eq!(err.exit_code(), 3, "{err}");
885    }
886
887    #[test]
888    fn extension_only_failures_say_only_the_extension_matched() {
889        let reg = Registry::new().with(Box::new(ByName));
890        let dir = tempfile::tempdir().unwrap();
891        let path = dir.path().join("model.ext");
892        std::fs::write(&path, b"{\"json\": true}").unwrap();
893        let err = reg.open(&path).map(|_| ()).unwrap_err();
894        assert_eq!(err.exit_code(), 4);
895        assert!(
896            err.to_string().contains("only the file extension matched"),
897            "{err}"
898        );
899        assert!(err.hint().unwrap().contains("another kind of file"));
900    }
901}
902
903#[cfg(test)]
904mod level_tests {
905    use super::*;
906    use crate::model::{CheckReport, FileInfo, LsEntry, Spectrum};
907
908    /// A run with the given MS levels; counts the spectra decoded.
909    struct Run {
910        levels: Vec<u32>,
911        indexed: bool,
912        reads: u64,
913    }
914    impl Dataset for Run {
915        fn info(&self) -> Result<FileInfo> {
916            Err(Error::Other("unused".into()))
917        }
918        fn vendor_metadata(&self) -> Result<serde_json::Value> {
919            Ok(serde_json::Value::Null)
920        }
921        fn provenance(&self) -> ProvenanceMap {
922            ProvenanceMap::new()
923        }
924        fn entries(&self) -> Result<Vec<LsEntry>> {
925            Ok(vec![])
926        }
927        fn read_plane(&mut self, _: u32, _: PlaneIndex) -> Result<Plane> {
928            Err(Error::Other("unused".into()))
929        }
930        fn check(&mut self) -> Result<CheckReport> {
931            Ok(CheckReport::new("fake", "fake"))
932        }
933        fn read_spectrum(&mut self, _: u32, i: u64) -> Result<Spectrum> {
934            self.reads += 1;
935            Ok(Spectrum {
936                index: i,
937                ms_level: self.levels[i as usize],
938                ..Spectrum::default()
939            })
940        }
941        fn spectrum_ms_levels(&mut self, _: u32) -> Result<Option<Vec<u32>>> {
942            Ok(self.indexed.then(|| self.levels.clone()))
943        }
944    }
945
946    #[test]
947    fn spectrum_of_level_uses_the_index_when_there_is_one() {
948        for indexed in [true, false] {
949            let mut r = Run {
950                levels: vec![1, 2, 2, 1, 2],
951                indexed,
952                reads: 0,
953            };
954            let sp = spectrum_by_level(&mut r, 0, 2, 2, 5, SpectrumView::Primary).unwrap();
955            assert_eq!(sp.index, 4);
956            assert_eq!(r.reads, if indexed { 1 } else { 5 });
957            let err = spectrum_by_level(&mut r, 0, 2, 3, 5, SpectrumView::Primary).unwrap_err();
958            assert!(err.to_string().contains("has 3 MS2 spectra"), "{err}");
959        }
960    }
961}