Borrow opaque C++ messages in Rust

Summary: Add `BorrowedMessageAdapter` so synchronous Rust handlers can inspect callback-scoped views of opaque inline C++ messages without taking them out of `TypeErasedBox`. The original box remains intact and can be forwarded unchanged.

Reviewed By: robertroeser

Differential Revision: D116714816

fbshipit-source-id: fea6937a4d3d2f3822b6fc7b66a4003848c28814

Author: pranavtbhat

thrift/lib/rust/channel_pipeline/README.md

@@ -46,6 +46,12 @@ impl RustHandler for CountingHandler {
 }
 ```
 
+Opaque inline C++ messages can be inspected without taking them out of the
+pipeline box. Implement `BorrowedMessageAdapter`, borrow the callback-scoped
+view with `msg.borrow::<Adapter>()`, drop the view, and call
+`ctx.forward_read(msg)` or `ctx.forward_write(msg)` to forward the original box
+unchanged. This path performs no message allocation or copy.
+
 Expose a factory from the handler's own CXX bridge:
 
 ```rust

thrift/lib/rust/channel_pipeline/src/erased.rs

@@ -45,6 +45,32 @@ use crate::adapter::RustMessageAdapter;
 use crate::ffi::ffi;
 use crate::ffi::ffi::TypeErasedBox;
 
+/// Adapter for inspecting a C++ pipeline message without taking it out of its
+/// [`TypeErasedBox`].
+///
+/// This is the zero-allocation path for opaque inline C++ messages. The view is
+/// tied to the callback-scoped box borrow and must not be retained. After the
+/// view is dropped, the handler can forward the original box unchanged.
+///
+/// # Safety
+///
+/// Implementations must return a view of the exact C++ type checked by
+/// `holds`, and the view must not outlive or move the value in `message`.
+pub unsafe trait BorrowedMessageAdapter {
+    type View<'a>
+    where
+        Self: 'a;
+
+    fn holds(message: &TypeErasedBox) -> bool;
+
+    /// # Safety
+    ///
+    /// `message` must currently contain the exact C++ type recognized by
+    /// [`Self::holds`]. The contained value must not be moved, replaced, or
+    /// otherwise invalidated for the lifetime of the returned view.
+    unsafe fn borrow<'a>(message: Pin<&'a mut TypeErasedBox>) -> Self::View<'a>;
+}
+
 /// Provides the dev-mode type check used by [`RustTypeErasedBox::take`].
 /// Implemented once per message type via a tiny per-type C++ thunk that compares
 /// `typeid` — exactly like the per-type C++ `RustMessageAdapter<T>`. In release
@@ -121,6 +147,23 @@ impl<'a> RustTypeErasedBox<'a> {
         M::from_cpp(cpp)
     }
 
+    /// Borrow a typed view of the message while leaving the box intact.
+    ///
+    /// Drop the returned view before forwarding `self` with
+    /// [`CallbackContext::forward_read`](crate::CallbackContext::forward_read)
+    /// or [`CallbackContext::forward_write`](crate::CallbackContext::forward_write).
+    pub fn borrow<M: BorrowedMessageAdapter>(&mut self) -> M::View<'_> {
+        assert!(
+            M::holds(self.inner.as_ref().get_ref()),
+            "RustTypeErasedBox::borrow: box does not hold the requested type"
+        );
+        // SAFETY: the unconditional `M::holds` check establishes that the box
+        // contains the adapter's exact C++ type. The returned view is tied to
+        // this exclusive pinned borrow, so the value cannot be moved or
+        // replaced while the view is live.
+        unsafe { M::borrow(self.inner.as_mut()) }
+    }
+
     /// True if the box currently holds no value.
     pub fn is_empty(&self) -> bool {
         ffi::rust_teb_is_empty(&self.inner)

thrift/lib/rust/channel_pipeline/src/ffi.rs

@@ -246,6 +246,8 @@ pub(crate) mod ffi {
     }
 }
 
+pub use ffi::TypeErasedBox as FfiTypeErasedBox;
+
 use crate::context::CallbackContext;
 use crate::erased::RustTypeErasedBox;
 use crate::ffi::ffi::TypeErasedBox;

thrift/lib/rust/channel_pipeline/src/lib.rs

@@ -148,6 +148,7 @@
 //! | [`PipelineError`] | Owned Rust error converted to `folly::exception_wrapper` |
 //! | [`HandlerResult`] | FFI-stable return value (`Success`, `Backpressure`, `Error`) |
 //! | [`RustMessageAdapter`] | Trait describing how a message type crosses the FFI boundary |
+//! | [`BorrowedMessageAdapter`] | Callback-scoped view of an opaque inline C++ message without taking it from the box |
 //! | [`CoroReadHandle`] / [`CoroWriteHandle`] / [`CoroExceptionHandle`] | Adapters from a pipeline callback to an `async` handler body |
 //! | [`ContextReadMessage`] / [`ContextWriteMessage`] | Message traits describing how to resume a captured continuation |
 //! | [`ErasedCheck`] | Dev-build type check for erased message recovery |
@@ -217,9 +218,11 @@
 //!
 //! # Message adapter extension
 //!
-//! Any type implementing [`RustMessageAdapter`] can flow through a Rust
-//! handler; the message type itself is the identity, so there is no numeric
-//! type id and no central registry. A future Rust handler at the framing layer
+//! An owned type implementing [`RustMessageAdapter`] can flow through a Rust
+//! handler. An opaque inline C++ type can instead implement
+//! [`BorrowedMessageAdapter`] and forward the original box unchanged after the
+//! view is dropped. The message type itself is the identity, so there is no
+//! numeric type id and no central registry. A future Rust handler at the framing layer
 //! that needs `ParsedFrame`/`ComposedFrame` should use an opaque
 //! `UniquePtr<ParsedFrame>` boxed via CXX methods (never mirror the C++ layout)
 //! or serialize via `cxx-thrift-utils`. The single-message-type-per-layer
@@ -259,8 +262,10 @@ pub use coro_handler::ContextWriteMessage;
 pub use coro_handler::CoroExceptionHandle;
 pub use coro_handler::CoroReadHandle;
 pub use coro_handler::CoroWriteHandle;
+pub use erased::BorrowedMessageAdapter;
 pub use erased::ErasedCheck;
 pub use erased::RustTypeErasedBox;
+pub use ffi::FfiTypeErasedBox;
 pub use ffi::RustHandlerOpaque;
 pub use ffi::box_handler;
 pub use handler::HandlerResult;