feat(error): record byte offset on decode and encode error variants

Reshapes the position-aware error approach per #1266 review feedback. Moves
position metadata out of the foundational `ironrdp-error` crate and onto the
decode and encode `*ErrorKind` enum variants where it actually applies.

Previously this PR added an optional `ErrorPosition { offset, field }` slot
to `Error<Kind>`'s `ErrorMeta`, paying a metadata slot on every error in the
workspace to serve only the decode and encode surfaces. The new shape places
a non-optional `offset: usize` on each variant that can know one:

- `DecodeErrorKind::{NotEnoughBytes, InvalidField, UnexpectedMessageType,
  UnsupportedVersion, UnsupportedValue}` gain `offset: usize`
- `EncodeErrorKind::*` mirrors the same shape for encode-side errors
- `*::Other` is unchanged; producers of `Other` typically lack stream-cursor
  access and the variant exists precisely for those cases

The `in_field` dotted-path use case is dropped from this PR per the same
review: `Error::set_context` already covers it. No parallel structured
field-tracking channel is introduced.

Trait and macro changes:

- `NotEnoughBytesErr`, `InvalidFieldErr`, `UnexpectedMessageTypeErr`,
  `UnsupportedVersionErr`, `UnsupportedValueErr` all take an additional
  `offset: usize` parameter
- The five corresponding `*_err!` macros gain `at:` and `in:` prefixes for
  explicit offset and cursor-extracted offset respectively
- `OtherErr` and `other_err!` are unchanged
- `cast_length!` and `cast_int!` macros pass `0` to the new offset slot
  (the macros do not have stream-cursor access)

Call-site migration:

- All 84 affected files updated to pass an explicit offset
- Most existing call sites pass `0` (the documented "offset unknown" sentinel)
  since the cursor is not always in lexical scope at the call site
- Cursor-aware sites can opt in via the new `in: cursor` macro syntax
- A workspace sweep upgrading `at: 0` to `in: cursor` where applicable is a
  follow-up

Display output includes the offset when known:
`invalid \`field\` at offset 47: reason`

Refs #1257, #1120. Supersedes the cross-cutting `ErrorPosition` approach
that was on this branch before today's review.

Author: Greg Lamberson

crates/ironrdp-ainput/src/lib.rs

@@ -159,8 +159,8 @@ impl<'de> Decode<'de> for ServerPdu {
     fn decode(src: &mut ReadCursor<'de>) -> DecodeResult<Self> {
         ensure_fixed_part_size!(in: src);
 
-        let pdu_type =
-            ServerPduType::from_u16(src.read_u16()).ok_or_else(|| invalid_field_err!("pduType", "invalid pdu type"))?;
+        let pdu_type = ServerPduType::from_u16(src.read_u16())
+            .ok_or_else(|| invalid_field_err!("pduType", "invalid pdu type", at: 0))?;
 
         let server_pdu = match pdu_type {
             ServerPduType::Version => ServerPdu::Version(VersionPdu::decode(src)?),
@@ -256,8 +256,8 @@ impl<'de> Decode<'de> for ClientPdu {
     fn decode(src: &mut ReadCursor<'de>) -> DecodeResult<Self> {
         ensure_fixed_part_size!(in: src);
 
-        let pdu_type =
-            ClientPduType::from_u16(src.read_u16()).ok_or_else(|| invalid_field_err!("pduType", "invalid pdu type"))?;
+        let pdu_type = ClientPduType::from_u16(src.read_u16())
+            .ok_or_else(|| invalid_field_err!("pduType", "invalid pdu type", at: 0))?;
 
         let client_pdu = match pdu_type {
             ClientPduType::Mouse => ClientPdu::Mouse(MousePdu::decode(src)?),

crates/ironrdp-cliprdr-format/src/bitmap.rs

@@ -243,19 +243,19 @@ impl BitmapInfoHeader {
 
         let width = src.read_i32();
         check_invariant(width != i32::MIN && width.abs() <= 10_000)
-            .ok_or_else(|| invalid_field_err!("biWidth", "width is too big"))?;
+            .ok_or_else(|| invalid_field_err!("biWidth", "width is too big", at: 0))?;
 
         let height = src.read_i32();
         check_invariant(height != i32::MIN && height.abs() <= 10_000)
-            .ok_or_else(|| invalid_field_err!("biHeight", "height is too big"))?;
+            .ok_or_else(|| invalid_field_err!("biHeight", "height is too big", at: 0))?;
 
         let planes = src.read_u16();
         if planes != 1 {
-            return Err(invalid_field_err!("biPlanes", "invalid planes count"));
+            return Err(invalid_field_err!("biPlanes", "invalid planes count", at: 0));
         }
 
         let bit_count = src.read_u16();
-        check_invariant(bit_count <= 32).ok_or_else(|| invalid_field_err!("biBitCount", "invalid bit count"))?;
+        check_invariant(bit_count <= 32).ok_or_else(|| invalid_field_err!("biBitCount", "invalid bit count", at: 0))?;
 
         let compression = BitmapCompression(src.read_u32());
         let size_image = src.read_u32();
@@ -320,7 +320,7 @@ impl<'a> Decode<'a> for BitmapInfoHeader {
         let size: usize = cast_int!("biSize", size)?;
 
         if size != Self::FIXED_PART_SIZE {
-            return Err(invalid_field_err!("biSize", "invalid V1 bitmap info header size"));
+            return Err(invalid_field_err!("biSize", "invalid V1 bitmap info header size", at: 0));
         }
 
         Ok(header)
@@ -406,7 +406,7 @@ impl<'a> Decode<'a> for BitmapV5Header {
         let size: usize = cast_int!("biSize", size)?;
 
         if size != Self::FIXED_PART_SIZE {
-            return Err(invalid_field_err!("biSize", "invalid V5 bitmap info header size"));
+            return Err(invalid_field_err!("biSize", "invalid V5 bitmap info header size", at: 0));
         }
 
         let red_mask = src.read_u32();

crates/ironrdp-cliprdr/src/pdu/capabilities.rs

@@ -170,10 +170,8 @@ impl<'de> Decode<'de> for CapabilitySet {
                 let general = GeneralCapabilitySet::decode(src)?;
                 Ok(Self::General(general))
             }
-            _ => Err(invalid_field_err!(
-                "capabilitySetType",
-                "invalid clipboard capability set type"
-            )),
+            _ => Err(invalid_field_err!( "capabilitySetType",
+                "invalid clipboard capability set type", at: 0)),
         }
     }
 }

crates/ironrdp-cliprdr/src/pdu/client_temporary_directory.rs

@@ -52,7 +52,7 @@ impl ClientTemporaryDirectory<'_> {
         let mut cursor = ReadCursor::new(&self.path_buffer);
 
         read_string_from_cursor(&mut cursor, CharacterSet::Unicode, true)
-            .map_err(|_| invalid_field_err!("wszTempDir", "failed to decode temp dir path"))
+            .map_err(|_| invalid_field_err!("wszTempDir", "failed to decode temp dir path", at: 0))
     }
 }
 

crates/ironrdp-cliprdr/src/pdu/file_contents.rs

@@ -129,18 +129,15 @@ impl<'a> FileContentsResponse<'a> {
     /// Should not panic - the try_into conversion is guaranteed to succeed after length validation.
     pub fn data_as_size(&self) -> DecodeResult<u64> {
         if self.data.len() != 8 {
-            return Err(invalid_field_err!(
-                "requestedFileContentsData",
-                "SIZE response must be exactly 8 bytes per MS-RDPECLIP 2.2.5.4"
-            ));
+            return Err(invalid_field_err!( "requestedFileContentsData",
+                "SIZE response must be exactly 8 bytes per MS-RDPECLIP 2.2.5.4", at: 0));
         }
 
         // Per length check above, this conversion is infallible.
-        let chunk: [u8; 8] = self
-            .data
-            .as_ref()
-            .try_into()
-            .map_err(|_| invalid_field_err!("requestedFileContentsData", "SIZE response data is not 8 bytes"))?;
+        let chunk: [u8; 8] =
+            self.data.as_ref().try_into().map_err(
+                |_| invalid_field_err!("requestedFileContentsData", "SIZE response data is not 8 bytes", at: 0),
+            )?;
         Ok(u64::from_le_bytes(chunk))
     }
 }
@@ -182,7 +179,7 @@ impl<'de> Decode<'de> for FileContentsResponse<'de> {
         ensure_size!(in: src, size: header.data_length());
 
         if header.data_length() < Self::FIXED_PART_SIZE {
-            return Err(invalid_field_err!("requestedFileContentsData", "invalid data size"));
+            return Err(invalid_field_err!("requestedFileContentsData", "invalid data size", at: 0));
         };
 
         let data_size = header.data_length() - Self::FIXED_PART_SIZE;
@@ -287,28 +284,22 @@ impl<'de> Decode<'de> for FileContentsRequest {
 
         // [MS-RDPECLIP] 2.2.5.3 - Validate lindex is non-negative
         if index < 0 {
-            return Err(invalid_field_err!(
-                "lindex",
-                "file index must be non-negative per MS-RDPECLIP 2.2.5.3"
-            ));
+            return Err(invalid_field_err!( "lindex",
+                "file index must be non-negative per MS-RDPECLIP 2.2.5.3", at: 0));
         }
 
         // [MS-RDPECLIP] 2.2.5.3 - Validate flags are spec-compliant
-        flags.validate().map_err(|e| invalid_field_err!("dwFlags", e))?;
+        flags.validate().map_err(|e| invalid_field_err!("dwFlags", e, at: 0))?;
 
         // [MS-RDPECLIP] 2.2.5.3 - Validate SIZE request constraints
         if flags.contains(FileContentsFlags::SIZE) {
             if requested_size != 8 {
-                return Err(invalid_field_err!(
-                    "cbRequested",
-                    "SIZE request must have cbRequested=8 per MS-RDPECLIP 2.2.5.3"
-                ));
+                return Err(invalid_field_err!( "cbRequested",
+                    "SIZE request must have cbRequested=8 per MS-RDPECLIP 2.2.5.3", at: 0));
             }
             if position != 0 {
-                return Err(invalid_field_err!(
-                    "position",
-                    "SIZE request must have position=0 per MS-RDPECLIP 2.2.5.3"
-                ));
+                return Err(invalid_field_err!( "position",
+                    "SIZE request must have position=0 per MS-RDPECLIP 2.2.5.3", at: 0));
             }
         }
 

crates/ironrdp-cliprdr/src/pdu/format_data/file_list.rs

@@ -184,10 +184,8 @@ impl Encode for FileDescriptor {
         // UTF-16 encoding: each code unit is 2 bytes, plus 2 bytes for null terminator.
         let encoded_len = wire_name.encode_utf16().count() * 2 + 2;
         if NAME_LENGTH < encoded_len {
-            return Err(ironrdp_core::invalid_field_err!(
-                "cFileName",
-                "encoded wire name exceeds NAME_LENGTH (520 bytes)"
-            ));
+            return Err(ironrdp_core::invalid_field_err!( "cFileName",
+                "encoded wire name exceeds NAME_LENGTH (520 bytes)", at: 0));
         }
 
         let written = encode_string(dst.remaining_mut(), &wire_name, CharacterSet::Unicode, true)?;
@@ -297,10 +295,8 @@ impl<'de> Decode<'de> for PackedFileList {
         let file_count: usize = cast_length!(Self::NAME, "cItems", src.read_u32())?;
 
         if MAX_FILE_COUNT < file_count {
-            return Err(ironrdp_core::invalid_field_err!(
-                "cItems",
-                "file count exceeds maximum of 100000"
-            ));
+            return Err(ironrdp_core::invalid_field_err!( "cItems",
+                "file count exceeds maximum of 100000", at: 0));
         }
 
         // Cap pre-allocation against remaining bytes to prevent OOM from

crates/ironrdp-cliprdr/src/pdu/format_list.rs

@@ -449,7 +449,7 @@ impl<'de> Decode<'de> for FormatListResponse {
         match header.message_flags {
             ClipboardPduFlags::RESPONSE_OK => Ok(FormatListResponse::Ok),
             ClipboardPduFlags::RESPONSE_FAIL => Ok(FormatListResponse::Fail),
-            _ => Err(invalid_field_err!("msgFlags", "invalid format list message flags")),
+            _ => Err(invalid_field_err!("msgFlags", "invalid format list message flags", at: 0)),
         }
     }
 }

crates/ironrdp-cliprdr/src/pdu/mod.rs

@@ -243,7 +243,7 @@ impl<'de> Decode<'de> for ClipboardPdu<'de> {
             MSG_TYPE_FILE_CONTENTS_RESPONSE => ClipboardPdu::FileContentsResponse(FileContentsResponse::decode(src)?),
             MSG_TYPE_LOCK_CLIPDATA => ClipboardPdu::LockData(LockDataId::decode(src)?),
             MSG_TYPE_UNLOCK_CLIPDATA => ClipboardPdu::UnlockData(LockDataId::decode(src)?),
-            _ => return Err(invalid_field_err!("msgType", "unknown clipboard PDU type")),
+            _ => return Err(invalid_field_err!("msgType", "unknown clipboard PDU type", at: 0)),
         };
 
         Ok(pdu)

crates/ironrdp-core/src/decode.rs

@@ -14,7 +14,16 @@ pub type DecodeResult<T> = Result<T, DecodeError>;
 /// An error type specifically for encoding operations, wrapping an [`DecodeErrorKind`].
 pub type DecodeError = ironrdp_error::Error<DecodeErrorKind>;
 
-/// Enum representing different kinds of decode errors.
+/// Structured decode errors carry the fields needed to describe the failure,
+/// including a byte `offset` when the error can be associated with
+/// a position in the input stream.
+///
+/// The `offset` is the cursor position at, or nearest to, where the error was
+/// detected. Producers without a stream cursor (a `try_from` on a primitive,
+/// a constructor, a validator) pass `0`.
+///
+/// [`DecodeErrorKind::Other`] is reserved for errors that do not fit one of the
+/// structured variants and therefore does not carry an offset.
 #[non_exhaustive]
 #[derive(Clone, Debug)]
 pub enum DecodeErrorKind {
@@ -24,23 +33,40 @@ pub enum DecodeErrorKind {
         received: usize,
         /// Number of bytes expected.
         expected: usize,
+        /// Byte offset in the input stream where the shortage was detected.
+        ///
+        /// `0` indicates that the producer had no stream cursor in scope
+        /// (a `try_from` on a primitive, a constructor, a validator).
+        offset: usize,
     },
     /// Error when a field is invalid.
     InvalidField {
         /// Name of the invalid field.
         field: &'static str,
         /// Reason for invalidity.
         reason: &'static str,
+        /// Byte offset in the input stream where the invalid field was decoded.
+        ///
+        /// `0` indicates that the producer had no stream cursor in scope.
+        offset: usize,
     },
     /// Error when an unexpected message type is encountered.
     UnexpectedMessageType {
         /// The unexpected message type received.
         got: u8,
+        /// Byte offset in the input stream where the unexpected type was read.
+        ///
+        /// `0` indicates that the producer had no stream cursor in scope.
+        offset: usize,
     },
     /// Error when an unsupported version is encountered.
     UnsupportedVersion {
         /// The unsupported version received.
         got: u8,
+        /// Byte offset in the input stream where the unsupported version was read.
+        ///
+        /// `0` indicates that the producer had no stream cursor in scope.
+        offset: usize,
     },
     /// Error when an unsupported value is encountered (with allocation feature).
     #[cfg(feature = "alloc")]
@@ -49,14 +75,26 @@ pub enum DecodeErrorKind {
         name: &'static str,
         /// The unsupported value.
         value: String,
+        /// Byte offset in the input stream where the unsupported value was read.
+        ///
+        /// `0` indicates that the producer had no stream cursor in scope.
+        offset: usize,
     },
     /// Error when an unsupported value is encountered (without allocation feature).
     #[cfg(not(feature = "alloc"))]
     UnsupportedValue {
         /// Name of the unsupported value.
         name: &'static str,
+        /// Byte offset in the input stream where the unsupported value was read.
+        ///
+        /// `0` indicates that the producer had no stream cursor in scope.
+        offset: usize,
     },
     /// Generic error for other cases.
+    ///
+    /// Does not carry an offset: producers of this variant typically do not
+    /// have stream-cursor access, and the variant exists precisely for those
+    /// cases.
     Other {
         /// Description of the error.
         description: &'static str,
@@ -69,26 +107,30 @@ impl core::error::Error for DecodeErrorKind {}
 impl fmt::Display for DecodeErrorKind {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            Self::NotEnoughBytes { received, expected } => write!(
+            Self::NotEnoughBytes {
+                received,
+                expected,
+                offset,
+            } => write!(
                 f,
-                "not enough bytes provided to decode: received {received} bytes, expected {expected} bytes"
+                "not enough bytes provided to decode at offset {offset}: received {received} bytes, expected {expected} bytes"
             ),
-            Self::InvalidField { field, reason } => {
-                write!(f, "invalid `{field}`: {reason}")
+            Self::InvalidField { field, reason, offset } => {
+                write!(f, "invalid `{field}` at offset {offset}: {reason}")
             }
-            Self::UnexpectedMessageType { got } => {
-                write!(f, "invalid message type ({got})")
+            Self::UnexpectedMessageType { got, offset } => {
+                write!(f, "invalid message type ({got}) at offset {offset}")
             }
-            Self::UnsupportedVersion { got } => {
-                write!(f, "unsupported version ({got})")
+            Self::UnsupportedVersion { got, offset } => {
+                write!(f, "unsupported version ({got}) at offset {offset}")
             }
             #[cfg(feature = "alloc")]
-            Self::UnsupportedValue { name, value } => {
-                write!(f, "unsupported {name} ({value})")
+            Self::UnsupportedValue { name, value, offset } => {
+                write!(f, "unsupported {name} ({value}) at offset {offset}")
             }
             #[cfg(not(feature = "alloc"))]
-            Self::UnsupportedValue { name } => {
-                write!(f, "unsupported {name}")
+            Self::UnsupportedValue { name, offset } => {
+                write!(f, "unsupported {name} at offset {offset}")
             }
             Self::Other { description } => {
                 write!(f, "other ({description})")
@@ -98,37 +140,44 @@ impl fmt::Display for DecodeErrorKind {
 }
 
 impl NotEnoughBytesErr for DecodeError {
-    fn not_enough_bytes(context: &'static str, received: usize, expected: usize) -> Self {
-        Self::new(context, DecodeErrorKind::NotEnoughBytes { received, expected })
+    fn not_enough_bytes(context: &'static str, received: usize, expected: usize, offset: usize) -> Self {
+        Self::new(
+            context,
+            DecodeErrorKind::NotEnoughBytes {
+                received,
+                expected,
+                offset,
+            },
+        )
     }
 }
 
 impl InvalidFieldErr for DecodeError {
-    fn invalid_field(context: &'static str, field: &'static str, reason: &'static str) -> Self {
-        Self::new(context, DecodeErrorKind::InvalidField { field, reason })
+    fn invalid_field(context: &'static str, field: &'static str, reason: &'static str, offset: usize) -> Self {
+        Self::new(context, DecodeErrorKind::InvalidField { field, reason, offset })
     }
 }
 
 impl UnexpectedMessageTypeErr for DecodeError {
-    fn unexpected_message_type(context: &'static str, got: u8) -> Self {
-        Self::new(context, DecodeErrorKind::UnexpectedMessageType { got })
+    fn unexpected_message_type(context: &'static str, got: u8, offset: usize) -> Self {
+        Self::new(context, DecodeErrorKind::UnexpectedMessageType { got, offset })
     }
 }
 
 impl UnsupportedVersionErr for DecodeError {
-    fn unsupported_version(context: &'static str, got: u8) -> Self {
-        Self::new(context, DecodeErrorKind::UnsupportedVersion { got })
+    fn unsupported_version(context: &'static str, got: u8, offset: usize) -> Self {
+        Self::new(context, DecodeErrorKind::UnsupportedVersion { got, offset })
     }
 }
 
 impl UnsupportedValueErr for DecodeError {
     #[cfg(feature = "alloc")]
-    fn unsupported_value(context: &'static str, name: &'static str, value: String) -> Self {
-        Self::new(context, DecodeErrorKind::UnsupportedValue { name, value })
+    fn unsupported_value(context: &'static str, name: &'static str, value: String, offset: usize) -> Self {
+        Self::new(context, DecodeErrorKind::UnsupportedValue { name, value, offset })
     }
     #[cfg(not(feature = "alloc"))]
-    fn unsupported_value(context: &'static str, name: &'static str) -> Self {
-        Self::new(context, DecodeErrorKind::UnsupportedValue { name })
+    fn unsupported_value(context: &'static str, name: &'static str, offset: usize) -> Self {
+        Self::new(context, DecodeErrorKind::UnsupportedValue { name, offset })
     }
 }