feat(error): record optional byte offset and field context on Error<Kind>

Adds two composable builder methods to ironrdp-error::Error<Kind> that
record optional positional metadata: Error::at_offset records a byte
offset in the input stream, and Error::in_field records a symbolic field
or sub-PDU name. Both are optional, both compose, and both are surfaced
in Display output when present. Position lives as a fourth field on
ErrorMeta (alongside context, location, source) so it carries zero size
cost on Result-Ok paths and is available only when the alloc feature is
enabled.

Refs #1257, #1120. Depends on #1269.

Author: Greg Lamberson

crates/ironrdp-error/src/lib.rs

@@ -13,6 +13,39 @@ pub trait Source: core::error::Error + Send + Sync + 'static {}
 
 impl<T> Source for T where T: core::error::Error + Send + Sync + 'static {}
 
+/// Optional positional metadata attached to an [`Error`] when the failure
+/// occurred at a known byte offset within a wire-format input stream, and/or
+/// while processing a known symbolic field.
+///
+/// Populated via [`Error::at_offset`] and [`Error::in_field`]. These builders
+/// compose: both may be set independently on the same error. When either is
+/// present, the position is rendered in [`Error`]'s `Display` output.
+///
+/// Intended primarily for decode and encode errors where the byte offset and
+/// the field being processed materially aid triage, particularly for
+/// fuzz-crash analysis where the variant kind alone does not narrow the
+/// failure point down enough.
+///
+/// Available only when the `alloc` feature is enabled, since it lives in
+/// [`Error`]'s heap-allocated metadata.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+#[non_exhaustive]
+pub struct ErrorPosition {
+    /// Byte offset in the input stream where the error was detected.
+    pub offset: Option<usize>,
+    /// Symbolic name of the field or sub-PDU being processed when the error
+    /// occurred. Dotted notation may be used for nested PDU navigation,
+    /// e.g. `"ServerSecurityData.serverRandom"`.
+    pub field: Option<&'static str>,
+}
+
+impl ErrorPosition {
+    /// Returns `true` if at least one of `offset` or `field` is set.
+    pub const fn is_set(&self) -> bool {
+        self.offset.is_some() || self.field.is_some()
+    }
+}
+
 /// Diagnostic metadata stored behind a [`Box`] so that `Error<Kind>` stays small.
 ///
 /// All fields here are purely for display and error-chain traversal; none are
@@ -24,6 +57,7 @@ struct ErrorMeta {
     context: &'static str,
     location: &'static core::panic::Location<'static>,
     source: Option<Box<dyn Source>>,
+    position: Option<ErrorPosition>,
 }
 
 /// A typed error wrapper carrying a `Kind` discriminant plus diagnostic metadata.
@@ -53,9 +87,14 @@ impl<Kind: fmt::Debug> fmt::Debug for Error<Kind> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let mut dbg = f.debug_struct("Error");
         #[cfg(feature = "alloc")]
-        dbg.field("context", &self.meta.context)
-            .field("kind", &self.kind)
-            .field("source", &self.meta.source);
+        {
+            dbg.field("context", &self.meta.context)
+                .field("kind", &self.kind)
+                .field("source", &self.meta.source);
+            if let Some(position) = &self.meta.position {
+                dbg.field("position", position);
+            }
+        }
         #[cfg(not(feature = "alloc"))]
         dbg.field("context", &self.context).field("kind", &self.kind);
         dbg.finish()
@@ -74,6 +113,7 @@ impl<Kind> Error<Kind> {
                 context,
                 location: core::panic::Location::caller(),
                 source: None,
+                position: None,
             }),
             #[cfg(not(feature = "alloc"))]
             context,
@@ -130,6 +170,60 @@ impl<Kind> Error<Kind> {
         self.meta.location
     }
 
+    /// Records the byte offset in the input stream where this error was detected.
+    ///
+    /// Composes with [`Error::in_field`]: both may be set independently and
+    /// are rendered together in `Display` output when present.
+    ///
+    /// Primarily intended for decode and encode errors on wire-format input,
+    /// where pointing at the offending byte materially aids triage and is
+    /// strictly more informative than the source code location alone.
+    ///
+    /// Available only when the `alloc` feature is enabled.
+    #[cfg(feature = "alloc")]
+    #[cold]
+    #[must_use]
+    pub fn at_offset(mut self, offset: usize) -> Self {
+        let field = self.meta.position.and_then(|p| p.field);
+        self.meta.position = Some(ErrorPosition {
+            offset: Some(offset),
+            field,
+        });
+        self
+    }
+
+    /// Records the symbolic field or sub-PDU name being processed when this
+    /// error occurred.
+    ///
+    /// Composes with [`Error::at_offset`]: both may be set independently and
+    /// are rendered together in `Display` output when present.
+    ///
+    /// Dotted notation may be used for nested PDU navigation,
+    /// e.g. `"ServerSecurityData.serverRandom"`.
+    ///
+    /// Available only when the `alloc` feature is enabled.
+    #[cfg(feature = "alloc")]
+    #[cold]
+    #[must_use]
+    pub fn in_field(mut self, field: &'static str) -> Self {
+        let offset = self.meta.position.and_then(|p| p.offset);
+        self.meta.position = Some(ErrorPosition {
+            offset,
+            field: Some(field),
+        });
+        self
+    }
+
+    /// Returns the byte offset and/or field-context position at which this
+    /// error was constructed, if either was recorded via [`Error::at_offset`]
+    /// or [`Error::in_field`].
+    ///
+    /// Available only when the `alloc` feature is enabled.
+    #[cfg(feature = "alloc")]
+    pub fn position(&self) -> Option<&ErrorPosition> {
+        self.meta.position.as_ref()
+    }
+
     pub fn set_context(&mut self, context: &'static str) {
         #[cfg(feature = "alloc")]
         {
@@ -160,7 +254,26 @@ where
                 self.meta.location.file(),
                 self.meta.location.line(),
                 self.kind
-            )
+            )?;
+            match self.meta.position {
+                Some(ErrorPosition {
+                    offset: Some(o),
+                    field: Some(name),
+                }) => write!(f, " (at offset {o} in {name:?})"),
+                Some(ErrorPosition {
+                    offset: Some(o),
+                    field: None,
+                }) => write!(f, " (at offset {o})"),
+                Some(ErrorPosition {
+                    offset: None,
+                    field: Some(name),
+                }) => write!(f, " (in {name:?})"),
+                Some(ErrorPosition {
+                    offset: None,
+                    field: None,
+                })
+                | None => Ok(()),
+            }
         }
         #[cfg(not(feature = "alloc"))]
         {