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}