postcard: support trailing opaque fields via #[facet(trailing)] (facet-rs#2109)

## Summary
Adds trailing opaque field support for postcard using a generic
`#[facet(trailing)]` field attribute. Trailing opaque payloads are
emitted and consumed as remaining bytes, without an outer postcard
byte-sequence length frame.

## Changes
- Add parser capability hint `hint_remaining_byte_sequence()` and use it
from generic opaque deserialization when the field is
`#[facet(trailing)]`.
- Remove format-specific branching from `facet-format` deserialization
(no `format_namespace()=="postcard"` gating).
- Add `Partial::nearest_field()` and use it for robust field lookup
through nested wrapper frames.
- Add field-aware opaque serialization dispatch in `facet-format`.
- Implement postcard trailing opaque serialization path that writes
mapped payload directly (no outer length prefix).
- Keep default opaque behavior unchanged for non-trailing fields.
- Add built-in `#[facet(trailing)]` attribute and compile-time
validation for usage constraints in macros.
- Deduplicate trailing validation logic across struct/enum macro
processing.
- Add integration tests for:
  - no outer framing for trailing opaque,
  - trailing deserialization consumes remainder,
  - scatter-gather reference preservation.

## Testing
- `cargo nextest run -p facet-postcard`
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`

Closes facet-rs#2108

Author: fasterthanlime

facet-format/src/deserializer/entry.rs

@@ -239,11 +239,27 @@ impl<'parser, 'input, const BORROW: bool> FormatDeserializer<'parser, 'input, BO
 
             Some(DeserStrategy::Opaque) => {
                 if let Some(adapter) = shape.opaque_adapter {
-                    if self.is_non_self_describing() && !self.parser.hint_byte_sequence() {
-                        self.parser.hint_scalar_type(ScalarTypeHint::Bytes);
+                    let trailing_opaque = wip
+                        .nearest_field()
+                        .is_some_and(|f| f.has_builtin_attr("trailing"));
+
+                    if self.is_non_self_describing() {
+                        let handled = if trailing_opaque {
+                            self.parser.hint_remaining_byte_sequence()
+                        } else {
+                            self.parser.hint_byte_sequence()
+                        };
+                        if !handled {
+                            self.parser.hint_scalar_type(ScalarTypeHint::Bytes);
+                        }
                     }
 
-                    let event = self.expect_event("bytes for opaque adapter")?;
+                    let expected = if trailing_opaque {
+                        "remaining bytes for trailing opaque adapter"
+                    } else {
+                        "bytes for opaque adapter"
+                    };
+                    let event = self.expect_event(expected)?;
                     let input = match event.kind {
                         ParseEventKind::Scalar(ScalarValue::Bytes(bytes)) => {
                             if BORROW {
@@ -259,7 +275,7 @@ impl<'parser, 'input, const BORROW: bool> FormatDeserializer<'parser, 'input, BO
                             return Err(self.mk_err(
                                 &wip,
                                 DeserializeErrorKind::UnexpectedToken {
-                                    expected: "bytes for opaque adapter",
+                                    expected,
                                     got: event.kind_name().into(),
                                 },
                             ));

facet-format/src/parser.rs

@@ -179,6 +179,17 @@ pub trait FormatParser<'de> {
         false
     }
 
+    /// Hint to the parser that all remaining input bytes should be consumed as a byte slice.
+    ///
+    /// This is used by formats like postcard for trailing opaque payloads where the
+    /// field boundary is "until end of input" rather than a length prefix.
+    ///
+    /// If handled, the parser should emit `Scalar(Bytes(...))` and advance to EOF.
+    /// Returns `true` if handled, `false` to use normal deserialization behavior.
+    fn hint_remaining_byte_sequence(&mut self) -> bool {
+        false
+    }
+
     /// Hint to the parser that a fixed-size array is expected.
     ///
     /// For non-self-describing formats, this tells the parser the array length

facet-format/src/serializer.rs

@@ -1,7 +1,7 @@
 use super::*;
 use crate::process_struct::{
-    TraitSources, gen_field_from_pfield, gen_trait_bounds, gen_type_ops, gen_vtable,
-    phantom_attr_use,
+    TraitSources, collect_trailing_shape_checks, gen_field_from_pfield, gen_trait_bounds,
+    gen_type_ops, gen_vtable, phantom_attr_use,
 };
 use proc_macro2::Literal;
 use quote::{format_ident, quote, quote_spanned};
@@ -132,6 +132,7 @@ pub(crate) fn process_enum(parsed: Enum) -> TokenStream {
     // Collect phantom use statements for IDE hover support on attribute names.
     // These link attribute spans to their facet::builtin::Attr variants.
     let mut phantom_attr_uses: Vec<TokenStream> = Vec::new();
+    let mut trailing_shape_checks: Vec<TokenStream> = Vec::new();
     // Container-level attributes
     for attr in &pe.container.attrs.facet {
         if let Some(phantom) = phantom_attr_use(attr, &facet_crate) {
@@ -151,6 +152,10 @@ pub(crate) fn process_enum(parsed: Enum) -> TokenStream {
             PVariantKind::Tuple { fields } => fields,
             PVariantKind::Struct { fields } => fields,
         };
+        match collect_trailing_shape_checks(fields, &facet_crate) {
+            Ok(checks) => trailing_shape_checks.extend(checks),
+            Err(err) => return err,
+        }
         for field in fields {
             if let Some(attr) = field
                 .attrs
@@ -1361,6 +1366,7 @@ pub(crate) fn process_enum(parsed: Enum) -> TokenStream {
         unsafe impl #bgp_def #facet_crate::Facet<'ʄ> for #enum_name #bgp_without_bounds #where_clauses {
             const SHAPE: &'static #facet_crate::Shape = &const {
                 use #facet_crate::𝟋::*;
+                #(#trailing_shape_checks)*
                 #(#shadow_struct_defs)*
                 #fields
                 𝟋ShpB::for_sized::<Self>(#enum_name_str)

facet-macros-impl/src/process_enum.rs

@@ -142,6 +142,50 @@ pub(crate) fn phantom_attr_use(
     Some(quote! { { use #facet_crate::builtin::Attr::#variant_ident as _; } })
 }
 
+pub(crate) fn collect_trailing_shape_checks(
+    fields: &[PStructField],
+    facet_crate: &TokenStream,
+) -> std::result::Result<Vec<TokenStream>, TokenStream> {
+    let mut trailing_shape_checks = Vec::new();
+
+    for (idx, field) in fields.iter().enumerate() {
+        for attr in &field.attrs.facet {
+            if !attr.is_builtin() || attr.key != "trailing" {
+                continue;
+            }
+            if !attr.args.is_empty() {
+                let span = attr.key.span();
+                return Err(quote_spanned! { span =>
+                    compile_error!("`#[facet(trailing)]` does not accept arguments");
+                });
+            }
+            if field.attrs.has_builtin("flatten") {
+                let span = attr.key.span();
+                return Err(quote_spanned! { span =>
+                    compile_error!("`#[facet(trailing)]` is not supported on flattened fields");
+                });
+            }
+            if idx + 1 != fields.len() {
+                let span = attr.key.span();
+                return Err(quote_spanned! { span =>
+                    compile_error!("`#[facet(trailing)]` requires this field to be the last field in its container");
+                });
+            }
+            if !field.attrs.has_builtin("opaque") {
+                let span = attr.key.span();
+                let field_type = &field.ty;
+                trailing_shape_checks.push(quote_spanned! { span =>
+                    if !<#field_type as #facet_crate::Facet<'ʄ>>::SHAPE.has_opaque_adapter() {
+                        panic!("`#[facet(trailing)]` requires an opaque field (`#[facet(opaque)]`) or a field type with `#[facet(opaque = ...)]`");
+                    }
+                });
+            }
+        }
+    }
+
+    Ok(trailing_shape_checks)
+}
+
 /// Generates the vtable for a type based on trait sources.
 ///
 /// Uses a layered approach for each trait:
@@ -1471,6 +1515,11 @@ pub(crate) fn process_struct(parsed: Struct) -> TokenStream {
         PStructKind::UnitStruct => &[],
     };
 
+    let trailing_shape_checks = match collect_trailing_shape_checks(fields, &facet_crate) {
+        Ok(checks) => checks,
+        Err(err) => return err,
+    };
+
     // MVP validation: adapter form is container-only for now.
     for field in fields {
         if let Some(attr) = field
@@ -2436,6 +2485,8 @@ pub(crate) fn process_struct(parsed: Struct) -> TokenStream {
             const __SHAPE_DATA: #facet_crate::Shape = {
                 use #facet_crate::𝟋::*;
 
+                #(#trailing_shape_checks)*
+
                 𝟋ShpB::for_sized::<Self>(#struct_name_str)
                     .module_path(::core::module_path!())
                     #decl_id_call

facet-macros-impl/src/process_struct.rs

@@ -98,6 +98,8 @@ pub struct PostcardParser<'de> {
     pending_sequence: bool,
     /// Pending byte sequence flag from `hint_byte_sequence`.
     pending_byte_sequence: bool,
+    /// Pending remaining-bytes flag from `hint_remaining_byte_sequence`.
+    pending_remaining_bytes: bool,
     /// Pending fixed-size array length from `hint_array`.
     pending_array: Option<usize>,
     /// Pending option flag from `hint_option`.
@@ -138,6 +140,7 @@ impl<'de> PostcardParser<'de> {
             pending_scalar_type: None,
             pending_sequence: false,
             pending_byte_sequence: false,
+            pending_remaining_bytes: false,
             pending_array: None,
             pending_option: false,
             pending_enum: None,
@@ -322,6 +325,18 @@ impl<'de> PostcardParser<'de> {
             return self.parse_opaque_scalar(opaque);
         }
 
+        // Check if we have a pending trailing bytes hint (consume rest of input as bytes)
+        if self.pending_remaining_bytes {
+            self.pending_remaining_bytes = false;
+            let bytes = &self.input[self.pos..];
+            self.pos = self.input.len();
+            return Ok(
+                self.event(ParseEventKind::Scalar(ScalarValue::Bytes(Cow::Borrowed(
+                    bytes,
+                )))),
+            );
+        }
+
         // Check if we have a pending scalar type hint
         if let Some(hint) = self.pending_scalar_type.take() {
             return self.parse_scalar_with_hint(hint);
@@ -986,6 +1001,10 @@ impl<'de> FormatParser<'de> for PostcardParser<'de> {
         Some(Span::new(self.pos, 1))
     }
 
+    fn format_namespace(&self) -> Option<&'static str> {
+        Some("postcard")
+    }
+
     fn save(&mut self) -> SavePoint {
         // Postcard doesn't support save/restore (non-self-describing format)
         // The solver can't work with positional formats anyway
@@ -1050,6 +1069,18 @@ impl<'de> FormatParser<'de> for PostcardParser<'de> {
         true // Postcard supports bulk byte reading
     }
 
+    fn hint_remaining_byte_sequence(&mut self) -> bool {
+        self.pending_remaining_bytes = true;
+        if self
+            .peeked
+            .as_ref()
+            .is_some_and(|e| matches!(e.kind, ParseEventKind::OrderedField))
+        {
+            self.peeked = None;
+        }
+        true
+    }
+
     fn hint_array(&mut self, len: usize) {
         self.pending_array = Some(len);
         // Clear any peeked OrderedField placeholder

facet-postcard/src/parser.rs

@@ -457,6 +457,10 @@ fn map_format_error(error: FormatSerializeError<SerializeError>) -> SerializeErr
     }
 }
 
+fn has_trailing_attr(field: Option<&facet_core::Field>) -> bool {
+    field.is_some_and(|f| f.has_builtin_attr("trailing"))
+}
+
 struct PostcardSerializer<'a, W> {
     writer: W,
     _marker: PhantomData<&'a ()>,
@@ -798,6 +802,15 @@ impl<'a, W: PostcardWriter<'a>> FormatSerializer for PostcardSerializer<'a, W> {
         &mut self,
         shape: &'static facet_core::Shape,
         value: Peek<'_, '_>,
+    ) -> Result<bool, Self::Error> {
+        self.serialize_opaque_scalar_with_field(None, shape, value)
+    }
+
+    fn serialize_opaque_scalar_with_field(
+        &mut self,
+        field: Option<&facet_core::Field>,
+        shape: &'static facet_core::Shape,
+        value: Peek<'_, '_>,
     ) -> Result<bool, Self::Error> {
         if value.scalar_type().is_some() {
             return Ok(false);
@@ -806,10 +819,16 @@ impl<'a, W: PostcardWriter<'a>> FormatSerializer for PostcardSerializer<'a, W> {
         if let Some(adapter) = shape.opaque_adapter {
             let mapped = unsafe { (adapter.serialize)(value.data()) };
             let mapped_peek = unsafe { Peek::unchecked_new(mapped.ptr, mapped.shape) };
-            let mut bytes = Vec::new();
-            let mut mapped_serializer = PostcardSerializer::new(CopyWriter::new(&mut bytes));
-            serialize_root(&mut mapped_serializer, mapped_peek).map_err(map_format_error)?;
-            self.write_bytes(&bytes)?;
+            if has_trailing_attr(field) {
+                // Trailing opaque fields stream mapped payload directly (no outer length framing),
+                // preserving scatter-gather references for borrowed bytes.
+                serialize_root(self, mapped_peek).map_err(map_format_error)?;
+            } else {
+                let mut bytes = Vec::new();
+                let mut mapped_serializer = PostcardSerializer::new(CopyWriter::new(&mut bytes));
+                serialize_root(&mut mapped_serializer, mapped_peek).map_err(map_format_error)?;
+                self.write_bytes(&bytes)?;
+            }
             return Ok(true);
         }
 

facet-postcard/src/serialize.rs

@@ -0,0 +1,111 @@
+use facet::{Facet, FacetOpaqueAdapter, OpaqueDeserialize, OpaqueSerialize, PtrConst};
+use facet_postcard::{Segment, from_slice, from_slice_borrowed, to_scatter_plan, to_vec};
+
+#[derive(Debug, Facet)]
+#[repr(u8)]
+#[facet(opaque = PayloadAdapter, traits(Debug))]
+enum Payload<'a> {
+    Borrowed(&'a [u8]),
+    RawBorrowed(&'a [u8]),
+    RawOwned(Vec<u8>),
+}
+
+struct PayloadAdapter;
+
+impl FacetOpaqueAdapter for PayloadAdapter {
+    type Error = String;
+    type SendValue<'a> = Payload<'a>;
+    type RecvValue<'de> = Payload<'de>;
+
+    fn serialize_map(value: &Self::SendValue<'_>) -> OpaqueSerialize {
+        match value {
+            Payload::Borrowed(bytes) => OpaqueSerialize {
+                ptr: PtrConst::new(bytes as *const &[u8]),
+                shape: <&[u8] as Facet>::SHAPE,
+            },
+            _ => unreachable!("serialize_map is only used for outgoing payload values"),
+        }
+    }
+
+    fn deserialize_build<'de>(
+        input: OpaqueDeserialize<'de>,
+    ) -> Result<Self::RecvValue<'de>, Self::Error> {
+        Ok(match input {
+            OpaqueDeserialize::Borrowed(bytes) => Payload::RawBorrowed(bytes),
+            OpaqueDeserialize::Owned(bytes) => Payload::RawOwned(bytes),
+        })
+    }
+}
+
+#[derive(Debug, Facet)]
+struct FramedTrailing<'a> {
+    id: u8,
+    #[facet(trailing)]
+    payload: Payload<'a>,
+}
+
+fn flatten(plan: &facet_postcard::ScatterPlan<'_>) -> Vec<u8> {
+    let mut out = vec![0u8; plan.total_size()];
+    plan.write_into(&mut out)
+        .expect("scatter plan should flatten");
+    out
+}
+
+#[test]
+fn issue_2108_trailing_opaque_omits_outer_length_framing() {
+    let value = FramedTrailing {
+        id: 7,
+        payload: Payload::Borrowed(&[0x10, 0x20]),
+    };
+
+    let bytes = to_vec(&value).expect("serialization should succeed");
+    assert_eq!(bytes, vec![7, 2, 0x10, 0x20]);
+}
+
+#[test]
+fn issue_2108_trailing_opaque_deserialize_consumes_remaining_bytes() {
+    let bytes = vec![7, 2, 0xAB, 0xCD];
+
+    let decoded_borrowed: FramedTrailing<'_> =
+        from_slice_borrowed(&bytes).expect("borrowed deserialization should succeed");
+    match decoded_borrowed.payload {
+        Payload::RawBorrowed(slice) => {
+            assert_eq!(slice, &[2, 0xAB, 0xCD]);
+            assert_eq!(slice.as_ptr(), bytes[1..].as_ptr());
+        }
+        other => panic!("expected RawBorrowed, got {other:?}"),
+    }
+
+    let decoded_owned: FramedTrailing<'static> =
+        from_slice(&bytes).expect("owned deserialization should succeed");
+    match decoded_owned.payload {
+        Payload::RawOwned(buf) => assert_eq!(buf, vec![2, 0xAB, 0xCD]),
+        other => panic!("expected RawOwned, got {other:?}"),
+    }
+}
+
+#[test]
+fn issue_2108_trailing_opaque_preserves_scatter_gather_references() {
+    let payload = [0x44, 0x55, 0x66];
+    let value = FramedTrailing {
+        id: 9,
+        payload: Payload::Borrowed(&payload),
+    };
+
+    let plan = to_scatter_plan(&value).expect("scatter plan should serialize");
+    let expected = to_vec(&value).expect("regular serialization should succeed");
+
+    assert_eq!(plan.total_size(), expected.len());
+    assert_eq!(flatten(&plan), expected);
+
+    let has_payload_ref = plan.segments().iter().any(|segment| match segment {
+        Segment::Reference { bytes } => {
+            bytes.len() == payload.len() && bytes.as_ptr() == payload.as_ptr()
+        }
+        Segment::Staged { .. } => false,
+    });
+    assert!(
+        has_payload_ref,
+        "expected a scatter-gather reference segment for borrowed payload bytes"
+    );
+}