rsrs_core/

header.rs

use derive_more::Display;
use recode::RawDecoder;

/// An enum to represent supported frame types.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Display)]
#[from_to_repr::from_to_other(base_type = u8)]
pub enum FrameType {
    /// Setup: Sent by client to initiate protocol processing.
    Setup           = 0x01,

    /// Lease: Sent by Responder to grant the ability to send requests.
    Lease           = 0x02,

    /// Keepalive: Connection keepalive.
    Keepalive       = 0x03,

    /// Request Response: Request single response.
    RequestResponse = 0x04,

    /// Fire And Forget: A single one-way message.
    RequestFNF      = 0x05,

    /// Request Stream: Request a completable stream.
    RequestStream   = 0x06,

    /// Request Channel: Request a completable stream in both directions.
    RequestChannel  = 0x07,

    /// Request N: Request N more items with Reactive Streams semantics.
    RequestN        = 0x08,

    /// Cancel Request: Cancel outstanding request.
    Cancel          = 0x09,

    /// Payload: Payload on a stream. For example, response to a request, or
    /// message on a channel.
    Payload         = 0x0A,

    /// Error: Error at connection or application level.
    Error           = 0x0B,

    /// Metadata: Asynchronous Metadata frame
    MetadataPush    = 0x0C,

    /// Resume: Replaces SETUP for Resuming Operation (optional)
    Resume          = 0x0D,

    /// Resume OK : Sent in response to a RESUME if resuming operation possible
    /// (optional)
    ResumeOk        = 0x0E,

    /// Extension Header: Used To Extend more frame types as well as
    /// extensions.
    Ext             = 0x3F,

    /// Unknown frame type.
    Unknown(u8),
}

bitflags::bitflags! {
    /// A flags structure to represent possible frams flags.
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Display)]
    pub struct FrameFlags: u16 {
        /// (N)ext: bit to indicate Next (Payload Data and/or Metadata present).
        ///
        /// If set, onNext(Payload) or equivalent will be invoked on
        /// Subscriber/Observer.
        const NEXT = 1 << 5;

        /// (C)omplete: bit to indicate stream completion.
        ///
        /// If set, `onComplete()` or equivalent will be invoked on
        /// Subscriber/Observer.
        const COMPLETE = 1 << 6;

        /// (F)ollows: More fragments follow this fragment.
        const FOLLOW = 1 << 7;

        /// (M)etadata: Metadata present.
        const METADATA = 1 << 8;

        /// (I)gnore: Ignore invalid frames.
        const IGNORE = 1 << 9;

        /// (L)ease: Will honor LEASE (or not).
        const LEASE = Self::COMPLETE.bits();

        /// (R)esume Enable: Client requests resume capability if possible.
        /// Resume Identification Token present.
        const RESUME = Self::FOLLOW.bits();

        /// (R)espond with KEEPALIVE or not.
        const RESPOND = Self::FOLLOW.bits();
    }
}

/// A type to represent an rsocket frame header.
#[derive(Debug, Clone, Copy, recode::Recode)]
#[recode(error = "crate::Error")]
pub struct FrameHeader {
    inner: u16,
}

impl FrameHeader {
    const FLAGS_MASK: u16 = 0x03FF;
    const FRAME_TYPE_OFFSET: u16 = 10;

    /// Creates a new frame header.
    ///
    /// # Parameters
    /// * `frame_type` - A frame type.
    /// * `flags` - Frame flags.
    ///
    /// # Returns
    /// A new frame header.
    pub(crate) const fn new(frame_type: FrameType, flags: FrameFlags) -> Self {
        let frame_type =
            (frame_type.to_base_type() as u16) << Self::FRAME_TYPE_OFFSET;

        Self {
            inner: frame_type | flags.bits(),
        }
    }

    /// Gets frame type.
    pub const fn frame_type(&self) -> FrameType {
        FrameType::from_base_type((self.inner >> Self::FRAME_TYPE_OFFSET) as u8)
    }

    /// Gets frame flags.
    pub const fn flags(&self) -> FrameFlags {
        FrameFlags::from_bits_truncate(self.inner & Self::FLAGS_MASK)
    }

    /// A shorthand for `self.flags().contains(flag)`.
    #[inline]
    pub const fn has(&self, flag: FrameFlags) -> bool {
        self.flags().contains(flag)
    }

    #[inline]
    pub(crate) fn set(&mut self, flag: FrameFlags, value: bool) {
        let mut flags = FrameFlags::from_bits_truncate(self.inner);

        flags.set(flag, value);

        self.inner = (self.inner & !Self::FLAGS_MASK) | flags.bits();
    }
}

impl RawDecoder for FrameHeader {
    type Error = crate::Error;

    #[inline]
    fn raw_decode<'a>(buf: &'a [u8]) -> Result<(Self, usize), Self::Error>
    where
        Self: 'a,
    {
        let (inner, rx): (u16, usize) = u16::raw_decode(buf)?;

        Ok((Self { inner }, rx))
    }
}

/// Creates a value of type [`FrameFlags`] at compile time.
///
/// This macro removes the boilerplate required to create constant
/// [`FrameFlags`] values at compile time.
///
/// # Example
/// ```rust
/// #[macro_use]
/// use rsocket_proto::frame::Flags;
/// use rsocket_proto::const_flags;
///
/// struct MyType;
///
/// impl MyType {
///     const FLAGS_MASK: Flags = const_flags![METADATA | RESUME | LEASE];
/// }
/// ```
#[macro_export]
macro_rules! const_flags {
    ($($expr:tt)*) => {
        $crate::process_flags_expr!(@entry: [ $($expr)* ] [] )
    };
}

/// Recursively Converts an expression that uses [`FrameFlags`] constants into
/// an expression that uses the backing value of [`FrameFlags`] ([`u16`]).
#[macro_export]
macro_rules! process_flags_expr {
    (@entry: [ ] [ ]) => {
        $crate::FrameFlags::empty()
    };

    (@entry: [ $($lhs:tt)+ ] [ ]) => {
        $crate::process_flags_expr! {
            @process:
                [ $($lhs)+ ]
                []
        }
    };

    (@process: [ $flag:ident $($lhs:tt)* ] [ $($rhs:tt)* ]) => {
        $crate::process_flags_expr! {
            @process:
                [ $($lhs)* ]
                [ $($rhs)* $crate::FrameFlags::$flag.bits() ]
        }
    };

    (@process: [ ( $($expr:tt)+ ) $($lhs:tt)* ] [ $($rhs:tt)* ]) => {
        $crate::process_flags_expr! {
            @process:
                [ $($lhs)* ]
                [ $($rhs)* $crate::const_flags!($($expr)+).bits() ]
        }
    };

    (@process: [ $other:tt $($lhs:tt)* ] [ $($rhs:tt)* ]) => {
        $crate::process_flags_expr! {
            @process:
                [ $($lhs)* ]
                [ $($rhs)* $other ]
        }
    };

    (@process: [ ] [ $($lhs:tt)+ ]) => {
        $crate::FrameFlags::from_bits_truncate($($lhs)+)
    };
}

#[doc(inline)]
pub use const_flags;