rapace-core 0.2.0

Core types and traits for rapace RPC
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

//! Transport traits.

use std::future::Future;
use std::pin::Pin;

use crate::{EncodeCtx, Frame, FrameView, TransportError};

/// A transport moves frames between two peers.
///
/// Transports are responsible for:
/// - Frame serialization/deserialization
/// - Flow control at the transport level
/// - Delivering frames reliably (within a session)
///
/// Transports are NOT responsible for:
/// - RPC semantics (channels, methods, deadlines)
/// - Service dispatch
/// - Schema management
///
/// Invariant: A transport may buffer internally, but must not reorder frames
/// within a channel, and must uphold the lifetime guarantees implied by FrameView.
pub trait Transport: Send + Sync {
    /// Send a frame to the peer.
    ///
    /// The frame is borrowed for the duration of the call. The transport
    /// may copy it (stream), reference it (in-proc), or encode it into
    /// SHM slots depending on implementation.
    fn send_frame(&self, frame: &Frame) -> impl Future<Output = Result<(), TransportError>> + Send;

    /// Receive the next frame from the peer.
    ///
    /// Returns a FrameView with lifetime tied to internal buffers.
    /// Caller must process or copy before calling recv_frame again.
    fn recv_frame(&self) -> impl Future<Output = Result<FrameView<'_>, TransportError>> + Send;

    /// Create an encoder context for building outbound frames.
    ///
    /// The encoder is transport-specific: SHM encoders can reference
    /// existing SHM data; stream encoders always copy.
    fn encoder(&self) -> Box<dyn EncodeCtx + '_>;

    /// Graceful shutdown.
    fn close(&self) -> impl Future<Output = Result<(), TransportError>> + Send;
}

/// Boxed future type for object-safe transport.
pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;

/// Object-safe version of Transport for dynamic dispatch.
///
/// Use this when you need to store transports in a collection or
/// pass them through trait objects.
pub trait DynTransport: Send + Sync {
    /// Send a frame (boxed future version).
    fn send_frame_boxed(&self, frame: &Frame) -> BoxFuture<'_, Result<(), TransportError>>;

    /// Receive a frame (returns owned Frame, not FrameView).
    fn recv_frame_boxed(&self) -> BoxFuture<'_, Result<Frame, TransportError>>;

    /// Create an encoder context.
    fn encoder_boxed(&self) -> Box<dyn EncodeCtx + '_>;

    /// Graceful shutdown (boxed future version).
    fn close_boxed(&self) -> BoxFuture<'_, Result<(), TransportError>>;
}

// Note: Blanket impl for DynTransport requires concrete types due to
// lifetime issues with FrameView. Transports implement DynTransport directly
// when needed.