fprint_fp3/error.rs
1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! Errors surfaced by the FP3 codec.
6//!
7//! `Display` and the `Error` impl come from `thiserror`. The failure modes are the ways a byte
8//! stream can fail to be a well-formed FP3 template: the `"FP3"` magic, the fixed GVariant tuple
9//! framing, the three `FpiPrintType` payload kinds, the per-sample "three equal-length arrays"
10//! rule, and the Julian day's range.
11
12use fprint_core::EnrollDate;
13
14/// Crate result alias.
15pub type Result<T> = core::result::Result<T, Fp3Error>;
16
17/// Everything that can go wrong turning bytes into a [`Print`](fprint_core::Print) or back.
18///
19/// The variants map one-to-one to the invariants of the FP3 container documented in
20/// `docs/fp3-format.md`.
21#[derive(Debug, thiserror::Error)]
22#[non_exhaustive]
23pub enum Fp3Error {
24 /// The first three bytes were not the ASCII magic `"FP3"`.
25 #[error("not an FP3 blob: bad magic")]
26 BadMagic,
27 /// The buffer is too short to even carry the magic.
28 #[error("truncated FP3 blob: shorter than the magic")]
29 Truncated,
30 /// The GVariant framing was malformed: an offset, length, or terminator did not fit the
31 /// bytes on hand. The static string names the specific check that failed.
32 #[error("malformed GVariant framing: {0}")]
33 Malformed(&'static str),
34 /// The tuple's `type` field was not a known `FpiPrintType` (or was `UNDEFINED`, which
35 /// is never serialized).
36 #[error("unknown FpiPrintType: {0}")]
37 UnknownType(i32),
38 /// Asked to serialize a [`Template::Undefined`](fprint_core::Template::Undefined) print —
39 /// a fresh, un-enrolled print has no on-disk representation.
40 #[error("cannot serialize an undefined template")]
41 UndefinedTemplate,
42 /// The `v` payload did not hold the type the `type` field promised.
43 #[error("payload variant did not match the print type")]
44 PayloadType,
45 /// An NBIS sample's `x`/`y`/`theta` arrays were not all the same length.
46 #[error("NBIS sample x/y/theta arrays have unequal lengths")]
47 UnevenSampleArrays,
48 /// The `finger` byte was outside the `FpFinger` range (`0..=10`).
49 #[error("invalid finger byte: {0}")]
50 BadFinger(u8),
51 /// The [`EnrollDate`](fprint_core::EnrollDate) has no FP3 Julian day: an `i32` year spans
52 /// further than an `i32` count of days, so dates outside
53 /// `-5879610-06-23 ..= 5879611-07-11` are unrepresentable, as is the single date whose
54 /// Julian day would collide with the `G_MININT32` "unset" sentinel.
55 #[error("enroll date {}-{}-{} has no FP3 Julian day", .0.year, .0.month, .0.day)]
56 DateOutOfRange(EnrollDate),
57}