content_scan 0.2.2

An extensible, plugin-based framework for identifying, analyzing, and recursively extracting structured content from arbitrary bytes.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
use crate::ContentPath;
use std::{
    fmt::Debug,
    io::{Read, Seek, SeekFrom},
    ops::{Deref, DerefMut},
};

/// Enumeration of content kinds understood by a scanner.
///
/// A `ContentType` is typically a user-defined `#[repr(u16)]` enum
/// derived with `#[derive(ContentType)]` (see
/// [`content_scan_proc_macro::ContentType`]). It maps each variant to a
/// stable `u16` identifier that the framework uses internally for fast
/// dispatch to identifiers, analyzers, and extractors.
///
/// # Contract
///
/// - [`as_u16`](Self::as_u16) must return a stable value that is unique
///   per variant and strictly less than [`COUNT`](Self::COUNT).
/// - [`from_u16`](Self::from_u16) must be the inverse of `as_u16` and
///   return `None` for values that do not correspond to a variant.
/// - [`COUNT`](Self::COUNT) is the number of possible variants and is
///   used to size internal fast-lookup tables.
///
/// # Example
///
/// ```ignore
/// #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, ContentType)]
/// #[repr(u16)]
/// enum MyTypes { Text, Binary }
/// ```
pub trait ContentType: Copy + Eq + PartialEq + Debug + Ord + PartialOrd {
    /// Total number of variants of this type.
    ///
    /// This must be strictly greater than the largest value ever
    /// returned by [`as_u16`](Self::as_u16). It is used to preallocate
    /// dispatch tables inside the scanner.
    const COUNT: u16;

    /// Returns the stable `u16` identifier for this variant.
    ///
    /// The value must be less than [`COUNT`](Self::COUNT) and unique
    /// among variants.
    fn as_u16(&self) -> u16;

    /// Reconstructs a variant from its `u16` identifier.
    ///
    /// Returns `None` if `value` does not correspond to any variant of
    /// this type.
    fn from_u16(value: u16) -> Option<Self>;
}

/// A byte-addressable piece of content the scanner can operate on.
///
/// Implementors expose a [`ContentPath`], a total size, and a way to
/// read arbitrary byte ranges. Analyzers and extractors receive a
/// `&mut dyn Content<T>` so they can request the exact windows they
/// need without requiring the whole payload to be buffered in memory
/// up front.
///
/// Ready-made implementations: [`crate::BufferContent`] (in-memory),
/// [`crate::FileContent`] (a file on disk), and [`crate::FolderContent`]
/// (a directory). You can also implement `Content` for your own types
/// (for example a memory-mapped region, a network stream wrapper, or
/// an entry inside an archive).
pub trait Content<T: ContentType> {
    /// Returns the content type if it is already known.
    ///
    /// When this returns `Some(ty)` the scanner will skip its own type
    /// detection (magic / extension / file name) and use `ty` directly.
    /// The default implementation returns `None`, meaning the scanner
    /// must identify the type itself.
    fn content_type(&self) -> Option<T> {
        None
    }
    /// Sets the content type of the content.
    fn set_content_type(&mut self, ty: T);

    /// Returns the path associated with this content.
    ///
    /// The path is a [`ContentPath`]: a UTF-8 printable view always
    /// exists, and a real OS path (including non-UTF-8 names) stays
    /// openable via [`ContentPath::as_path`]. It is used by
    /// [`Filter`](crate::Filter) rules, stored in the scan result tree,
    /// and available to analyzers and extractors. It does not need to
    /// correspond to a real filesystem path — archive members and
    /// in-memory buffers typically use a synthetic address built with
    /// [`ContentPath::from_str`].
    fn path(&self) -> &ContentPath;

    /// Returns the total size of the content in bytes.
    fn size(&self) -> u64;

    /// Reads up to `count` bytes starting at `offset`.
    ///
    /// - Returns `Some(&[])` if `offset` is exactly at the end of the
    ///   content.
    /// - Returns `None` if `offset` is past the end or the underlying
    ///   source cannot fulfill the request.
    /// - May return fewer bytes than requested at EOF **or** at an
    ///   implementation boundary (for example one cache page). A short
    ///   slice is not end of file; advance by its length and read again.
    ///
    /// The returned slice borrows from `self`, so the read cursor is
    /// implicit: successive calls with different `offset` values do not
    /// interact.
    fn read(&mut self, offset: u64, count: u32) -> Option<&[u8]>;
}

pub trait ContentReadExt<T: ContentType>: Content<T> {
    /// Reads exactly `count` bytes at `offset`, but only if they land in a
    /// single underlying read window. Returns `None` if the source can't
    /// deliver them contiguously — which may mean the bytes span a page
    /// boundary, NOT that they don't exist. Use `read_into` to cross boundaries.
    fn read_exact(&mut self, offset: u64, count: u32) -> Option<&[u8]> {
        if count == 0 {
            return Some(&[]);
        }
        let slice = self.read(offset, count)?;
        (slice.len() == count as usize).then_some(slice)
    }

    /// Reads up to `count` bytes starting at `offset` into `output_buf`,
    /// looping across short reads, and returns the number of bytes copied.
    ///
    /// The number of bytes read is the minimum of three limits: `count`,
    /// the bytes remaining in the content (`size - offset`), and the length
    /// of `output_buf`. Whichever is smallest wins, so the call never reads
    /// past the end of the content and never writes past the end of the
    /// buffer regardless of what the caller passes.
    ///
    /// Because [`read`](Content::read) may return a short slice at an
    /// implementation boundary, this method calls it repeatedly, advancing
    /// by the length of each slice, until the target count is reached or the
    /// content ends.
    ///
    /// # Returns
    ///
    /// - `Some(n)` where `n` is the number of bytes copied into
    ///   `output_buf[..n]`. `n` may be less than `count` when the content,
    ///   the buffer, or a mid-stream end of content is the limiting factor.
    /// - `Some(0)` if `offset` is exactly at the end of the content, if
    ///   `count` is `0`, or if `output_buf` is empty. Note that `Some(0)`
    ///   does not distinguish "at end of content" from "nothing was
    ///   requested"; a caller needing that distinction can compare `offset`
    ///   against [`size`](Content::size) itself.
    /// - `None` if `offset` is past the end of the content, or if the
    ///   underlying [`read`](Content::read) fails at any point — **even
    ///   after some bytes have already been copied**. A returned `None`
    ///   therefore discards any partial progress; only a `Some(n)` result
    ///   reports bytes read.
    fn read_into(&mut self, offset: u64, count: u32, output_buf: &mut [u8]) -> Option<usize> {
        let size = self.size();
        if offset > size {
            return None;
        }
        if offset == size {
            return Some(0);
        }
        let count = (size - offset).min(count as u64).min(output_buf.len() as u64) as usize;
        let mut filled = 0usize;
        while filled < count {
            let want = ((count - filled).min(u32::MAX as usize)) as u32;
            let src = self.read(offset + filled as u64, want)?;
            if src.is_empty() {
                break;
            }
            let n = src.len().min(count - filled);
            output_buf[filled..filled + n].copy_from_slice(&src[..n]);
            filled += n;
        }
        Some(filled)
    }

    /// Reads a `G` from `offset` by copying `size_of::<G>()` bytes out of the
    /// content.
    ///
    /// Intended for mapping an on-disk or in-buffer structure onto its Rust
    /// equivalent — for example a PE COFF header. The bytes are copied
    /// unaligned, so `offset` has no alignment requirement, and short reads
    /// from [`read`](Content::read) are looped internally.
    ///
    /// # Returns
    /// - `Some(g)` if `size_of::<G>()` bytes are available starting at `offset`.
    /// - `None` if the read would run past the end of the content, if the
    ///   underlying [`read`](Content::read) fails, or if `size_of::<G>()`
    ///   exceeds `u32::MAX`.
    ///
    /// A zero-sized `G` returns `Some` without touching the content.
    ///
    /// # Safety
    /// The caller must guarantee that **every** bit pattern of length
    /// `size_of::<G>()` is a valid value of `G`. This holds for `#[repr(C)]`
    /// plain-data structs composed of integers, floats, and arrays of those.
    /// It is undefined behavior to call this with a `G` that has validity
    /// invariants — e.g. one containing a `bool`, `char`, reference, `NonZero*`,
    /// or an enum with a restricted set of discriminants — because arbitrary
    /// file bytes may not be a valid instance.
    unsafe fn read_struct<S: Copy>(&mut self, offset: u64) -> Option<S> {
        let size = std::mem::size_of::<S>();
        if size == 0 {
            return Some(unsafe { std::mem::zeroed() });
        }
        if size > u32::MAX as usize {
            return None;
        }

        let mut buf = std::mem::MaybeUninit::<S>::uninit();
        let output_bytes: &mut [u8] = unsafe { std::slice::from_raw_parts_mut(buf.as_mut_ptr() as *mut u8, size) };
        match self.read_into(offset, size as u32, output_bytes) {
            Some(n) if n == size => Some(unsafe { buf.assume_init() }),
            _ => None,
        }
    }

    /// Reads a single byte at `offset`. Returns `None` if the content ends
    /// (or errors) before the byte is available.
    fn read_byte(&mut self, offset: u64) -> Option<u8> {
        self.read_exact(offset, 1).map(|b| b[0])
    }

    /// Reads a 16-bit unsigned integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in big-endian order.
    fn read_be_u16(&mut self, offset: u64) -> Option<u16> {
        self.read_exact(offset, 2).map(|b| u16::from_be_bytes([b[0], b[1]]))
    }
    /// Reads a 16-bit unsigned integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in little-endian order.
    fn read_le_u16(&mut self, offset: u64) -> Option<u16> {
        self.read_exact(offset, 2).map(|b| u16::from_le_bytes([b[0], b[1]]))
    }

    /// Reads a 32-bit unsigned integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in big-endian order.
    fn read_be_u32(&mut self, offset: u64) -> Option<u32> {
        self.read_exact(offset, 4).map(|b| u32::from_be_bytes([b[0], b[1], b[2], b[3]]))
    }
    /// Reads a 32-bit unsigned integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in little-endian order.
    fn read_le_u32(&mut self, offset: u64) -> Option<u32> {
        self.read_exact(offset, 4).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
    }
    /// Reads a 64-bit unsigned integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in big-endian order.
    fn read_be_u64(&mut self, offset: u64) -> Option<u64> {
        self.read_exact(offset, 8)
            .map(|b| u64::from_be_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]))
    }
    /// Reads a 64-bit unsigned integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in little-endian order.
    fn read_le_u64(&mut self, offset: u64) -> Option<u64> {
        self.read_exact(offset, 8)
            .map(|b| u64::from_le_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]))
    }
    /// Reads a 16-bit signed integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in big-endian order.
    fn read_be_i16(&mut self, offset: u64) -> Option<i16> {
        self.read_exact(offset, 2).map(|b| i16::from_be_bytes([b[0], b[1]]))
    }
    /// Reads a 16-bit signed integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in little-endian order.
    fn read_le_i16(&mut self, offset: u64) -> Option<i16> {
        self.read_exact(offset, 2).map(|b| i16::from_le_bytes([b[0], b[1]]))
    }
    /// Reads a 32-bit signed integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in big-endian order.
    fn read_be_i32(&mut self, offset: u64) -> Option<i32> {
        self.read_exact(offset, 4).map(|b| i32::from_be_bytes([b[0], b[1], b[2], b[3]]))
    }
    /// Reads a 32-bit signed integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in little-endian order.
    fn read_le_i32(&mut self, offset: u64) -> Option<i32> {
        self.read_exact(offset, 4).map(|b| i32::from_le_bytes([b[0], b[1], b[2], b[3]]))
    }
    /// Reads a 64-bit signed integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in big-endian order.
    fn read_be_i64(&mut self, offset: u64) -> Option<i64> {
        self.read_exact(offset, 8)
            .map(|b| i64::from_be_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]))
    }
    /// Reads a 64-bit signed integer at `offset`. Returns `None` if the content ends
    /// (or errors) before the integer is available. The integer is read in little-endian order.
    fn read_le_i64(&mut self, offset: u64) -> Option<i64> {
        self.read_exact(offset, 8)
            .map(|b| i64::from_le_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]))
    }
}

impl<T: ContentType, C: Content<T> + ?Sized> ContentReadExt<T> for C {}

/// Trivial [`ContentType`] implementation for `bool`.
///
/// This is convenient when a scanner only needs to distinguish between
/// two abstract kinds of content (`false` and `true`) or when writing
/// tests. `false` maps to `0`, `true` to `1`, and `COUNT` is `2`.
impl ContentType for bool {
    const COUNT: u16 = 2;
    fn as_u16(&self) -> u16 {
        *self as u16
    }
    fn from_u16(value: u16) -> Option<Self> {
        if value == 0 {
            Some(false)
        } else if value == 1 {
            Some(true)
        } else {
            None
        }
    }
}

#[derive(Debug, Copy, Clone)]
pub(crate) struct ContentPtr<T: ContentType> {
    content: *mut dyn Content<T>,
}
impl<T: ContentType> ContentPtr<T> {
    #[inline(always)]
    pub(crate) fn new(content: &mut dyn Content<T>) -> Self {
        Self {
            content: unsafe { std::mem::transmute::<*mut dyn Content<T>, *mut (dyn Content<T> + 'static)>(content as *mut _) },
        }
    }
    #[inline(always)]
    pub(crate) fn as_mut(&mut self) -> &mut dyn Content<T> {
        unsafe { &mut *self.content }
    }
    #[inline(always)]
    pub(crate) fn as_ref(&self) -> &dyn Content<T> {
        unsafe { &*self.content }
    }
}
/// Non-owning handle to the parent [`Content`] of an extraction session.
///
/// [`ContentExtractor::create_session`](crate::ContentExtractor::create_session)
/// receives this instead of a `&mut dyn Content<T>` so the session can
/// keep the parent across [`advance`](crate::ExtractionSession::advance)
/// / [`extract`](crate::ExtractionSession::extract) without fighting
/// the borrow checker. It [derefs](std::ops::Deref) to `dyn Content<T>`,
/// so a session can call [`path`](Content::path), [`size`](Content::size),
/// [`read`](Content::read), and [`content_type`](Content::content_type)
/// through it.
///
/// The handle is valid for the lifetime of the session that received
/// it. The scanner guarantees the parent outlives that session; do not
/// store the pointer after the session is dropped.
pub struct OwnedContentPtr<T: ContentType> {
    content: *mut dyn Content<T>,
}
impl<T: ContentType> OwnedContentPtr<T> {
    #[inline(always)]
    pub(crate) fn new(content: ContentPtr<T>) -> Self {
        Self { content: content.content }
    }
}
impl<T: ContentType> Deref for OwnedContentPtr<T> {
    type Target = dyn Content<T>;
    #[inline(always)]
    fn deref(&self) -> &Self::Target {
        unsafe { &*self.content }
    }
}
impl<T: ContentType> DerefMut for OwnedContentPtr<T> {
    #[inline(always)]
    fn deref_mut(&mut self) -> &mut Self::Target {
        unsafe { &mut *self.content }
    }
}

/// Sequential [`Read`] + [`Seek`] adapter over an [`OwnedContentPtr`].
///
/// [`Content::read`] is random-access and returns a borrowed slice.
/// Libraries that expect a `std::io::Read` / `Seek` stream (for
/// example the `zip` crate used by [`ZipExtractor`](crate::ZipExtractor))
/// need a cursor instead. `ContentReader` wraps the parent handle,
/// starts at offset `0`, and advances on each `read`.
///
/// A short slice from the underlying [`Content`] is not treated as
/// EOF: the adapter copies what it got, advances, and the next
/// `Read::read` continues from there. A `Content::read` that returns
/// `None` before the advertised [`size`](Content::size) becomes an
/// `UnexpectedEof` error. Seeking past the end is allowed (same as
/// [`std::io::Cursor`]); a later read then returns `Ok(0)`.
///
/// ```ignore
/// let mut reader = ContentReader::new(parent);
/// let mut archive = zip::ZipArchive::new(reader)?;
/// ```
pub struct ContentReader<T: ContentType> {
    content: OwnedContentPtr<T>,
    offset: u64,
}
impl<T: ContentType> ContentReader<T> {
    /// Wraps `content` with the read cursor at offset `0`.
    pub fn new(content: OwnedContentPtr<T>) -> Self {
        Self { content, offset: 0 }
    }
}
impl<T: ContentType> Read for ContentReader<T> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        if buf.is_empty() {
            return Ok(0);
        }
        let len = self.content.size();
        if self.offset >= len {
            return Ok(0); // at or past EOF: clean end of stream
        }

        let remaining = len - self.offset;
        let want = (buf.len() as u64).min(remaining).min(u32::MAX as u64) as u32;

        match self.content.read(self.offset, want) {
            Some(src) => {
                let n = src.len().min(buf.len());
                buf[..n].copy_from_slice(&src[..n]);
                self.offset += n as u64;
                Ok(n)
            }
            None => Err(std::io::Error::new(
                std::io::ErrorKind::UnexpectedEof,
                "Content::read failed before end of content",
            )),
        }
    }
}

impl<T: ContentType> Seek for ContentReader<T> {
    fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
        let (base, delta) = match pos {
            SeekFrom::Start(o) => {
                self.offset = o;
                return Ok(o);
            }
            SeekFrom::End(o) => (self.content.size(), o),
            SeekFrom::Current(o) => (self.offset, o),
        };

        let new = if delta >= 0 {
            base.checked_add(delta as u64)
        } else {
            base.checked_sub(delta.unsigned_abs())
        };

        match new {
            Some(p) => {
                self.offset = p;
                Ok(p)
            }
            None => Err(std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                "seek to a negative or overflowing position",
            )),
        }
    }
}