Skip to main content

resident_fat/
error.rs

1//! What can go wrong, and enough detail to act on it.
2//!
3//! Every variant carries the value that caused it. A filesystem refusing a
4//! volume is nearly always something a person has to diagnose from a log
5//! line on a device with no debugger, so "bad geometry" without the field
6//! and the number is a wasted message.
7//!
8//! For the same reason [`enum@Error`] implements [`Display`](core::fmt::Display)
9//! — and so [`core::error::Error`] — for *every* device error the
10//! [`BlockDevice`](crate::blockdev::BlockDevice) trait admits, rather than
11//! only for those that are themselves `Display`. See [`Error::Device`].
12
13use thiserror::Error;
14
15/// A FAT format this crate does not implement.
16///
17/// Reported by name rather than folded into a generic "unsupported": the
18/// volume was understood well enough to classify, which is a materially
19/// different situation from a corrupt or unrecognisable one, and the
20/// difference decides whether reformatting is the answer.
21#[non_exhaustive]
22#[derive(Error, Debug, Clone, Copy, PartialEq, Eq)]
23pub enum Format {
24    /// A FAT12 volume.
25    #[error("FAT12")]
26    Fat12,
27    /// A FAT16 volume.
28    #[error("FAT16")]
29    Fat16,
30}
31
32/// A boot sector field this crate refuses, and the value it held.
33///
34/// The list is deliberately short, because a check that rejects a volume
35/// working everywhere else is worse than no check at all. Both the media
36/// descriptor and the disk geometry fields are wrong on enough real devices
37/// that Linux removed its own checks on them, so nothing here looks at
38/// either. What is left is the arithmetic the rest of the crate depends on:
39/// a field whose value would make a later calculation meaningless, rather
40/// than one that merely looks unusual.
41#[non_exhaustive]
42#[derive(Error, Debug, Clone, Copy, PartialEq, Eq)]
43pub enum Geometry {
44    /// The volume's sector size is not the 512 bytes this crate supports.
45    ///
46    /// FAT allows 1024, 2048 and 4096 as well, and this crate refuses all
47    /// three rather than translating them: a sector number and a device
48    /// block number are the same number only at 512, and every offset the
49    /// rest of the crate computes is a sector number handed to a block
50    /// device. Effectively every SD card, and every volume `mkfs.vfat`
51    /// produces without being told otherwise, uses 512 — see
52    /// [`BLOCK_SIZE`](crate::BLOCK_SIZE).
53    #[error("sector size {0} is not the 512 bytes this crate supports")]
54    SectorSize(u16),
55
56    /// Sectors per cluster was zero or not a power of two.
57    #[error("sectors per cluster {0} is not a power of two")]
58    SectorsPerCluster(u8),
59
60    /// The reserved region was empty, so the boot sector is not inside it.
61    #[error("reserved sector count is {0}")]
62    ReservedSectors(u16),
63
64    /// The volume claims no file allocation tables.
65    #[error("file allocation table count is {0}")]
66    FatCount(u8),
67
68    /// The table has no length.
69    #[error("file allocation table length is {0}")]
70    FatLength(u32),
71
72    /// The volume claims no sectors at all.
73    #[error("total sector count is {0}")]
74    TotalSectors(u32),
75
76    /// The data area begins past the end of the volume.
77    #[error("data area starts at sector {data_start}, past the volume's {total_sectors} sectors")]
78    DataBeyondVolume {
79        /// First sector of the data area.
80        data_start: u32,
81        /// Sectors the volume claims to have.
82        total_sectors: u32,
83    },
84
85    /// More clusters than the format can address.
86    #[error("{0} clusters is more than the format can address")]
87    ClusterCount(u32),
88
89    /// The volume claims more space than whatever contains it.
90    ///
91    /// The container is the device, or the partition the volume sits in when
92    /// it was reached through a partition table — whichever is tighter, and
93    /// neither when the device declines to report its size and no partition
94    /// was named.
95    ///
96    /// Distinct from [`DataBeyondVolume`](Self::DataBeyondVolume), which is
97    /// the boot sector's fields disagreeing with *each other*. Here they are
98    /// internally consistent and the volume simply does not fit where it was
99    /// found, so the numbers worth printing are different ones.
100    #[error("volume needs blocks {first_block}..{end}, but only {bound} are available")]
101    VolumeTooLarge {
102        /// First block of the volume.
103        first_block: u64,
104        /// One past the last block the volume claims.
105        end: u64,
106        /// One past the last block the container makes available.
107        bound: u64,
108    },
109}
110
111/// What can go wrong inside the allocation table.
112///
113/// Separate from [`enum@Error`] because **none of it involves a device**. The
114/// table is resident, so walking a chain, finding room and freeing clusters
115/// are memory operations that either succeed or find the table inconsistent
116/// — there is no transfer to fail.
117///
118/// That is worth a type rather than five more variants on [`enum@Error`]: it lets
119/// [`Fat`](crate::Fat)'s methods say what they can actually return instead of
120/// being generic over a device error they can never produce. Before this
121/// existed, every one of them carried an unconstrained type parameter that
122/// the caller had to name — `fat.runs::<D::Error>(cluster)` — for the sole
123/// purpose of building an error variant that never arrived.
124///
125/// Converts into [`enum@Error`] with `?`, so a caller mixing table and device
126/// work writes neither a turbofish nor a `map_err`.
127#[non_exhaustive]
128#[derive(Error, Debug, Clone, Copy, PartialEq, Eq)]
129pub enum FatError {
130    /// A cluster number outside the addressable range.
131    ///
132    /// Cluster numbering starts at 2, and the upper bound is what the table
133    /// can actually address rather than what the volume claims — the two
134    /// disagree on corrupt media, and the table is the one that bounds
135    /// memory.
136    #[error("cluster {cluster} is outside the volume")]
137    BadCluster {
138        /// The offending cluster number.
139        cluster: u32,
140    },
141
142    /// A cluster chain longer than the volume has clusters, which means it
143    /// loops.
144    ///
145    /// Worth bounding even though a loop is corruption rather than a normal
146    /// state: with the table resident, walking a chain is a memory loop with
147    /// no I/O to slow it down, so an unbounded walk spins instantly rather
148    /// than slowly.
149    #[error("cluster chain from {start} loops")]
150    ChainLoop {
151        /// Cluster the walk started from.
152        start: u32,
153    },
154
155    /// A chain ran into a free cluster.
156    ///
157    /// Corruption, not the end of the file: a chain ends with an
158    /// end-of-chain marker, and a free entry in the middle of one means the
159    /// table and the directory disagree about what is allocated.
160    #[error("cluster chain from {start} runs into free cluster {cluster}")]
161    FreeClusterInChain {
162        /// Cluster the walk started from.
163        start: u32,
164        /// The free cluster it reached.
165        cluster: u32,
166    },
167
168    /// The volume has no room for what was asked.
169    #[error("no room: {wanted} clusters wanted, {free} free")]
170    DiskFull {
171        /// Clusters the operation needed.
172        wanted: u32,
173        /// Clusters actually available.
174        free: u32,
175    },
176
177    /// A file's cluster chain holds less data than its recorded length.
178    ///
179    /// The directory entry and the allocation table disagree, which is
180    /// corruption rather than a short file: the bytes the entry promises are
181    /// not anywhere on the volume.
182    #[error("the chain from {start} is shorter than the {size} bytes the entry claims")]
183    ChainShorterThanFile {
184        /// First cluster of the file.
185        start: u32,
186        /// Length the directory entry recorded.
187        size: u32,
188    },
189}
190
191/// What can go wrong reading a boot sector.
192///
193/// Separate from [`enum@Error`] for the same reason as [`FatError`], and it
194/// is the same reason: **none of it involves a device**.
195/// [`BootSector::parse`](crate::BootSector::parse) is handed a block that has
196/// already been read, so it either understands those 512 bytes or it does
197/// not — there is no transfer left to fail.
198///
199/// Being its own type is what lets `parse` say so. Reported through
200/// [`enum@Error`] it would have had to be generic over a device error it
201/// could never produce, and a caller parsing a block it had read itself
202/// would have needed a turbofish naming a type that never appeared —
203/// `BootSector::parse::<()>(&block)`.
204///
205/// Converts into [`enum@Error`] with `?`, so mounting, which does touch a
206/// device, needs neither turbofish nor `map_err`.
207#[non_exhaustive]
208#[derive(Error, Debug, Clone, Copy, PartialEq, Eq)]
209pub enum BootError {
210    /// No boot signature — this is not a FAT volume, or not the right
211    /// sector.
212    ///
213    /// The usual cause is a partitioned card: the partition table sits
214    /// where the boot sector was looked for, so the volume has to be
215    /// mounted at the partition's first block rather than at block 0.
216    #[error("no FAT boot signature")]
217    NotFat,
218
219    /// A FAT12 or FAT16 volume, recognised and declined.
220    #[error("{0} is not supported")]
221    UnsupportedFormat(Format),
222
223    /// A boot sector field this crate will not accept.
224    #[error("invalid boot sector: {0}")]
225    BadGeometry(Geometry),
226
227    /// The block handed in was shorter than a sector.
228    ///
229    /// A caller's mistake rather than anything about a volume: every field a
230    /// boot sector holds lives in its first 512 bytes, so a shorter slice has
231    /// nothing to parse.
232    ///
233    /// Reported rather than asserted, for the reason given on
234    /// [`Error::BufferLength`] — indexing past the end would panic, and a
235    /// bare-metal target has no unwinder to catch it. The two are the same
236    /// kind of mistake and get the same treatment.
237    #[error(
238        "boot sector block is {len} bytes, but {} are needed",
239        crate::BLOCK_SIZE
240    )]
241    ShortBlock {
242        /// Bytes the caller supplied.
243        len: usize,
244    },
245}
246
247/// Anything that can stop a filesystem operation.
248///
249/// `#[non_exhaustive]`, and that is a decision rather than a habit: a
250/// filesystem accumulates error kinds for years, and whether this enum can
251/// grow one without a breaking release is unchangeable once published. The
252/// cost is a wildcard arm in every downstream `match`; the alternative is a
253/// major version for each newly distinguished failure.
254#[non_exhaustive]
255#[derive(Error, Debug, Clone, PartialEq, Eq)]
256pub enum Error<E> {
257    /// The block device failed. Carries whatever it reported.
258    ///
259    /// Rendered with `{:?}` rather than `{}`, which is what makes this whole
260    /// type printable. [`BlockDevice::Error`](crate::blockdev::BlockDevice::Error)
261    /// is bounded `Debug` and nothing more, so formatting the payload with
262    /// `Display` would give `Error<E>` a `Display` impl that a conforming
263    /// device error need not satisfy — and an error type that cannot be
264    /// printed is no use on a board whose only diagnostic is a log line.
265    ///
266    /// Bounding the trait on `Display` instead would cost more than it
267    /// bought: `embedded_sdmmc::BlockDevice::Error` is itself only `Debug`,
268    /// so the `bridge` module would stop accepting the drivers it exists to
269    /// accept. A `#[derive(Debug)]` enum, which is what a device error nearly
270    /// always is, prints the same either way.
271    #[error("block device error: {0:?}")]
272    Device(E),
273
274    /// The boot sector was not one this crate can use.
275    ///
276    /// Nested rather than flattened because these are the failures that
277    /// involve no device — see [`BootError`], which is what
278    /// [`BootSector::parse`](crate::BootSector::parse) itself returns. `?`
279    /// converts.
280    #[error("{0}")]
281    Boot(#[from] BootError),
282
283    /// A partition was asked for on a device whose block 0 is not a
284    /// partition table.
285    ///
286    /// Usually means the device is formatted as one bare volume, which
287    /// [`FileSystem::mount`](crate::FileSystem::mount) handles. Also
288    /// reported for the placeholder table a GPT disk carries, which is a
289    /// table this crate deliberately will not mount through.
290    #[error("no partition table")]
291    NoPartitionTable,
292
293    /// The partition table has nothing in that slot.
294    ///
295    /// The slot is the raw table position, 0 to 3, so an empty slot before a
296    /// used one is a normal arrangement rather than a corrupt table.
297    #[error("partition {index} is not in use")]
298    NoSuchPartition {
299        /// The slot that was asked for.
300        index: usize,
301    },
302
303    /// The device has a partition table and no FAT partition in it.
304    ///
305    /// Its own case rather than [`Error::NoPartitionTable`], which would be
306    /// the wrong diagnosis: there *is* a table, and the fix is a different
307    /// one — the card was imaged with some other layout, or its FAT
308    /// partition was given another type.
309    #[error("no FAT partition in the partition table")]
310    NoFatPartition,
311
312    /// The allocation table was inconsistent, or had no room.
313    ///
314    /// Nested rather than flattened because these are exactly the failures
315    /// that involve no device — see [`FatError`], which is what
316    /// [`Fat`](crate::Fat)'s own methods return. `?` converts.
317    #[error("{0}")]
318    Fat(#[from] FatError),
319
320    /// An allocated entry sits after the end-of-directory marker.
321    ///
322    /// Those entries are files that exist on the volume and that no
323    /// implementation will list, since every reader stops at the marker.
324    /// Reporting it rather than stopping quietly is deliberate: silently
325    /// ignoring files that are really there is how data goes missing
326    /// without anyone being told.
327    #[error("directory has an allocated entry at index {index}, after its end marker")]
328    EntryAfterEnd {
329        /// Which 32-byte slot the stray entry occupies.
330        index: usize,
331    },
332
333    /// Nothing in the directory goes by that name.
334    #[error("{name} not found")]
335    NotFound {
336        /// The name that was looked for.
337        name: alloc::string::String,
338    },
339
340    /// A path component named a file where a directory was needed.
341    #[error("{name} is not a directory")]
342    NotADirectory {
343        /// The name that turned out to be a file.
344        name: alloc::string::String,
345    },
346
347    /// A directory was named where a file was needed.
348    #[error("{name} is a directory")]
349    IsADirectory {
350        /// The name that turned out to be a directory.
351        name: alloc::string::String,
352    },
353
354    /// A directory has no room for another entry and cannot grow.
355    #[error("directory is full")]
356    DirectoryFull,
357
358    /// A name no FAT volume can store.
359    ///
360    /// Names too long for 8.3 are not refused — they get a long name and a
361    /// generated alias. What is refused is a name that has no storable form
362    /// at all: empty, longer than 255 characters, containing one of the
363    /// characters the format reserves, or relying on the leading and
364    /// trailing spaces and trailing periods Windows silently strips.
365    /// Stripping them here would mean handing a file back under a different
366    /// name than the one asked for.
367    #[error("{name} cannot be stored as a FAT name")]
368    BadName {
369        /// The name that was refused.
370        name: alloc::string::String,
371    },
372
373    /// Every 8.3 alias this name could be given was already taken.
374    ///
375    /// Reachable only in theory: aliases are probed up to `~999999`, and an
376    /// aliased name costs at least two of a directory's 65536 slots, so no
377    /// directory can hold enough names to exhaust them. It is reported
378    /// rather than asserted because the alternative is an unbounded search
379    /// on a corrupt directory.
380    #[error("no free 8.3 alias is left for {name}")]
381    NoAliasAvailable {
382        /// The name that could not be given an alias.
383        name: alloc::string::String,
384    },
385
386    /// A directory was removed that still holds entries.
387    ///
388    /// Removing it would leave everything inside unreachable but still
389    /// marked as allocated — space no `fsck` run reclaims, because the
390    /// clusters really are referenced by directory entries nothing can
391    /// find.
392    #[error("{name} is not empty")]
393    DirectoryNotEmpty {
394        /// The directory that still has contents.
395        name: alloc::string::String,
396    },
397
398    /// A file or directory of that name already exists.
399    #[error("{name} already exists")]
400    AlreadyExists {
401        /// The name that was already taken.
402        name: alloc::string::String,
403    },
404
405    /// A directory was asked to move inside itself, or inside something
406    /// it contains.
407    ///
408    /// Carried out, that would unhook the directory from the tree it is
409    /// part of: its new parent would be reachable only through the
410    /// directory itself, so the whole subtree would be allocated and found
411    /// by nothing.
412    #[error("{name} cannot be moved inside itself")]
413    MoveIntoItself {
414        /// The directory that was to be moved.
415        name: alloc::string::String,
416    },
417
418    /// A [`File`](crate::File) was used after its directory slot stopped
419    /// being its own.
420    ///
421    /// A handle records where its entry lives so that changing a length is a
422    /// rewrite of one known slot rather than a fresh search. Deleting the
423    /// file frees that slot, and the next file created in the directory may
424    /// take it — at which point the old handle names an entry belonging to
425    /// something else. Writing through it would silently truncate a file the
426    /// caller never opened, so it is refused.
427    ///
428    /// Nothing on the volume is wrong when this is reported: the handle is
429    /// stale, not the card. Open the path again.
430    ///
431    /// # When a handle goes stale
432    ///
433    /// Any deletion from its directory, which includes the deletion
434    /// [`write_file`](crate::FileSystem::write_file) performs when it
435    /// replaces an existing file. Same-name replacement has to count,
436    /// because the slot is genuinely a different file afterwards and the
437    /// eleven name bytes are identical — FAT stores no inode, no generation
438    /// and no creation cookie for a check to find a difference in, so the
439    /// only thing left to notice is that a deletion happened at all.
440    ///
441    /// That makes deleting a *sibling* invalidate the handle too. The false
442    /// positive is deliberate: the cost is reopening a path in a resident
443    /// directory, and the alternative is a write landing on whichever file
444    /// was handed the slot — verified to leave a volume `fsck.vfat` reports
445    /// as having a file whose size does not account for its chain.
446    #[error("the handle for {name} no longer matches the entry it was opened from")]
447    StaleFile {
448        /// The 8.3 name the handle expected to find in its slot.
449        name: alloc::string::String,
450    },
451
452    /// A buffer whose length is not the one the operation needs.
453    ///
454    /// Reported rather than asserted. This is a caller's mistake and a
455    /// `debug_assert!` would be the usual answer to one, but a panic on a
456    /// bare-metal target has no unwinder to catch it — a filesystem
457    /// aborting the machine because a buffer was sized wrong is a worse
458    /// outcome than the caller being told.
459    #[error("buffer is {actual} bytes, but {expected} were needed")]
460    BufferLength {
461        /// Bytes the operation required.
462        expected: u64,
463        /// Bytes the caller supplied.
464        actual: usize,
465    },
466
467    /// A buffer the operation needed would not fit in memory.
468    ///
469    /// Not necessarily a bug in either the caller or the volume. This crate
470    /// trades memory for transfers by design, and the sizes it asks for are
471    /// set by *the volume* rather than by anything a program chooses — the
472    /// allocation table is four bytes per cluster, and reading a file or a
473    /// directory whole means a buffer as large as it is. A host that cannot
474    /// spare that much is a legitimate outcome, and the honest answer is to
475    /// say which allocation failed rather than to succeed at a smaller one
476    /// the caller did not ask for.
477    ///
478    /// Reported rather than left to the allocator, which is the whole point
479    /// of the variant. Rust's infallible allocation calls the `alloc` error
480    /// handler on failure, and on a bare-metal target that aborts the
481    /// machine — a filesystem is in no position to decide that a card too
482    /// big for this board should stop the program. So every allocation
483    /// whose size comes off the volume goes through `try_reserve` and
484    /// arrives here instead.
485    ///
486    /// `bytes` is what was being asked for, not what was available. On a
487    /// 32-bit target this also covers a request too large for `usize` at
488    /// all, which is why the field is a `u64` rather than a `usize`.
489    #[error("could not allocate {bytes} bytes")]
490    OutOfMemory {
491        /// Bytes the operation tried to allocate.
492        bytes: u64,
493    },
494}
495
496/// A `Vec` of `count` copies of `value`, or [`Error::OutOfMemory`].
497///
498/// Lives beside the error rather than beside its callers because producing
499/// that error is the only reason it exists: `vec![value; count]` is shorter
500/// and does the same thing right up until the allocation fails, at which
501/// point it aborts instead of returning. Every allocation this crate sizes
502/// from the volume goes through here, so there is one place to look for how
503/// that case is handled.
504///
505/// `count` is a `u64` rather than a `usize` on purpose. The counts reaching
506/// this come from 32-bit on-disk fields and from sums over a cluster chain,
507/// so on a 32-bit target they can exceed what `usize` holds — and silently
508/// truncating one yields a buffer that is too short rather than an
509/// allocation that fails, which is a panic further along instead of an
510/// error here.
511pub(crate) fn try_filled<T: Clone, E>(value: T, count: u64) -> Result<alloc::vec::Vec<T>, E> {
512    let bytes = count.saturating_mul(core::mem::size_of::<T>() as u64);
513    let too_big = || Error::OutOfMemory { bytes };
514
515    let count = usize::try_from(count).map_err(|_| too_big())?;
516    let mut buffer = alloc::vec::Vec::new();
517    buffer.try_reserve_exact(count).map_err(|_| too_big())?;
518    // Cannot reallocate: the reservation above is exact and already made.
519    buffer.resize(count, value);
520    Ok(buffer)
521}
522
523impl<E> Error<E> {
524    /// Wraps a block device's own error.
525    pub fn device(error: E) -> Self {
526        Error::Device(error)
527    }
528}
529
530/// The result of anything that touches a volume.
531pub type Result<T, E> = core::result::Result<T, Error<E>>;
532
533#[cfg(test)]
534mod tests {
535    use super::*;
536
537    /// A device error carrying exactly what the trait demands and nothing
538    /// more, which is the shape a `#[derive(Debug)]` enum in a driver has.
539    #[derive(Debug)]
540    struct DebugOnly;
541
542    /// A conforming device error is enough to print this crate's errors.
543    ///
544    /// The bound on [`BlockDevice::Error`](crate::blockdev::BlockDevice::Error)
545    /// is `Debug` alone, so a driver is under no obligation to implement
546    /// `Display`. If `Error<E>`'s own `Display` asked for one anyway — which
547    /// it would the moment the `Device` variant formatted its payload with
548    /// `{}` instead of `{:?}` — then the errors this crate returns could not
549    /// be printed by the consumers it was written for, and the failure would
550    /// land in their build rather than in this one.
551    #[test]
552    fn errors_print_for_any_conforming_device_error() {
553        fn printable<T: core::fmt::Display + core::error::Error>(_: &T) {}
554
555        let error: Error<DebugOnly> = Error::device(DebugOnly);
556        printable(&error);
557        assert_eq!(
558            alloc::format!("{error}"),
559            "block device error: DebugOnly",
560            "the device error should reach the message"
561        );
562
563        // And the variants that carry no device error at all stay legible
564        // whatever `E` is.
565        let full: Error<DebugOnly> = FatError::DiskFull { wanted: 4, free: 1 }.into();
566        assert_eq!(
567            alloc::format!("{full}"),
568            "no room: 4 clusters wanted, 1 free"
569        );
570    }
571
572    /// An allocation that cannot succeed is reported, not attempted.
573    ///
574    /// What makes this worth pinning is where the sizes come from. A file's
575    /// length and a table's sector count are fields on the volume, so an
576    /// infallible `vec![value; n]` hands a corrupt card the power to call
577    /// the `alloc` error handler — which aborts, with no unwinder on a
578    /// bare-metal target to catch it. Rejecting the card is the filesystem's
579    /// business; halting the board is not.
580    ///
581    /// `u64::MAX` is the request used because it fails the same way on every
582    /// target and allocates nothing on any of them: on a 32-bit target it
583    /// exceeds `usize` and is refused by the conversion, and on a 64-bit one
584    /// it exceeds the largest possible allocation and is refused by
585    /// `try_reserve_exact` before a byte is asked for.
586    #[test]
587    fn an_impossible_allocation_is_reported_rather_than_attempted() {
588        let refused: Result<alloc::vec::Vec<u8>, DebugOnly> = try_filled(0u8, u64::MAX);
589        match refused {
590            Err(Error::OutOfMemory { bytes }) => assert_eq!(bytes, u64::MAX),
591            other => panic!("expected OutOfMemory, got {other:?}"),
592        }
593
594        // The reported size saturates rather than wrapping. A count that
595        // overflows when scaled by the element size must not come back as a
596        // small number, which would read as a trivial allocation failing.
597        let wide: Result<alloc::vec::Vec<u32>, DebugOnly> = try_filled(0u32, u64::MAX / 2);
598        match wide {
599            Err(Error::OutOfMemory { bytes }) => assert_eq!(bytes, u64::MAX),
600            other => panic!("expected OutOfMemory, got {other:?}"),
601        }
602    }
603
604    /// And an allocation that can succeed still does, at the exact length.
605    #[test]
606    fn a_possible_allocation_still_happens() {
607        let buffer: Result<alloc::vec::Vec<u8>, DebugOnly> = try_filled(7u8, 4);
608        assert_eq!(buffer.expect("4 bytes should be available"), [7, 7, 7, 7]);
609
610        let empty: Result<alloc::vec::Vec<u8>, DebugOnly> = try_filled(0u8, 0);
611        assert!(
612            empty.expect("an empty buffer is not a failure").is_empty(),
613            "a zero-length chain asks for nothing and must not be an error"
614        );
615    }
616}