rapace_core/
transport.rs

1//! Transport traits.
2
3use std::future::Future;
4use std::pin::Pin;
5
6use crate::{EncodeCtx, Frame, FrameView, TransportError};
7
8/// A transport moves frames between two peers.
9///
10/// Transports are responsible for:
11/// - Frame serialization/deserialization
12/// - Flow control at the transport level
13/// - Delivering frames reliably (within a session)
14///
15/// Transports are NOT responsible for:
16/// - RPC semantics (channels, methods, deadlines)
17/// - Service dispatch
18/// - Schema management
19///
20/// Invariant: A transport may buffer internally, but must not reorder frames
21/// within a channel, and must uphold the lifetime guarantees implied by FrameView.
22pub trait Transport: Send + Sync {
23    /// Send a frame to the peer.
24    ///
25    /// The frame is borrowed for the duration of the call. The transport
26    /// may copy it (stream), reference it (in-proc), or encode it into
27    /// SHM slots depending on implementation.
28    fn send_frame(&self, frame: &Frame) -> impl Future<Output = Result<(), TransportError>> + Send;
29
30    /// Receive the next frame from the peer.
31    ///
32    /// Returns a FrameView with lifetime tied to internal buffers.
33    /// Caller must process or copy before calling recv_frame again.
34    fn recv_frame(&self) -> impl Future<Output = Result<FrameView<'_>, TransportError>> + Send;
35
36    /// Create an encoder context for building outbound frames.
37    ///
38    /// The encoder is transport-specific: SHM encoders can reference
39    /// existing SHM data; stream encoders always copy.
40    fn encoder(&self) -> Box<dyn EncodeCtx + '_>;
41
42    /// Graceful shutdown.
43    fn close(&self) -> impl Future<Output = Result<(), TransportError>> + Send;
44}
45
46/// Boxed future type for object-safe transport.
47pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
48
49/// Object-safe version of Transport for dynamic dispatch.
50///
51/// Use this when you need to store transports in a collection or
52/// pass them through trait objects.
53pub trait DynTransport: Send + Sync {
54    /// Send a frame (boxed future version).
55    fn send_frame_boxed(&self, frame: &Frame) -> BoxFuture<'_, Result<(), TransportError>>;
56
57    /// Receive a frame (returns owned Frame, not FrameView).
58    fn recv_frame_boxed(&self) -> BoxFuture<'_, Result<Frame, TransportError>>;
59
60    /// Create an encoder context.
61    fn encoder_boxed(&self) -> Box<dyn EncodeCtx + '_>;
62
63    /// Graceful shutdown (boxed future version).
64    fn close_boxed(&self) -> BoxFuture<'_, Result<(), TransportError>>;
65}
66
67// Note: Blanket impl for DynTransport requires concrete types due to
68// lifetime issues with FrameView. Transports implement DynTransport directly
69// when needed.
rapace_core/transport.rs

rapace_core/
transport.rs
