Struct RiFrame 

pub struct RiFrame {
    pub header: RiFrameHeader,
    pub payload: Vec<u8>,
}

Complete protocol frame combining header and payload data.

A RiFrame represents the fundamental unit of data transmission in the Ri protocol. Each frame consists of a fixed 32-byte header containing protocol metadata and a variable-length payload containing the actual application data. Frames are serialized for network transmission and deserialized upon receipt using CRC32 checksums for integrity verification.

Frame Structure

+------------------+-------------------+
|   Header (32B)   |  Payload (VAR)    |
+------------------+-------------------+
| magic | type | v | flags | len | seq |
|      timestamp     |    checksum     |
+------------------+-------------------+

Frame Lifecycle

1. Creation: Construct a frame using new() or one of the convenience constructors (data_frame(), control_frame(), etc.)
2. Serialization: Convert to bytes using to_bytes() for transmission
3. Transmission: Send bytes over the network connection
4. Reception: Receive bytes and add to frame parser buffer
5. Deserialization: Parse bytes back to frame using from_bytes()
6. Processing: Handle the frame based on its type

Frame Validity

A frame is considered valid when:

• The magic number matches the Ri protocol identifier
• The protocol version is supported
• The CRC32 checksum matches the computed checksum
• The payload length matches the actual payload size

Use the is_valid() method for quick validation checking.

Python Bindings

When compiled with the pyo3 feature, this struct provides Python bindings:

from ri import RiFrame, RiFrameType

# Create a data frame
frame = RiFrame.data_frame(
    data=b"Hello, Ri Protocol!",
    sequence_number=1
)

# Serialize for transmission
frame_bytes = frame.to_bytes()
print(f"Frame size: {len(frame_bytes)} bytes")

# Access frame properties
print(f"Frame type: {frame.frame_type()}")
print(f"Sequence: {frame.sequence_number()}")
print(f"Timestamp: {frame.timestamp()}")
print(f"Valid: {frame.is_valid()}")

# Deserialize received frame
received = RiFrame.from_bytes(frame_bytes)
assert received.payload == b"Hello, Ri Protocol!"

Examples

Creating and serializing a data frame:

use ri::protocol::frames::{RiFrame, RiFrameType};

let frame = RiFrame::data_frame(
    b"Hello, World!".to_vec(),
    42
).expect("Failed to create frame");

let bytes = frame.to_bytes().expect("Failed to serialize frame");
println!("Frame serialized to {} bytes", bytes.len());

assert!(frame.is_valid());
assert_eq!(frame.sequence_number(), 42);

Creating different frame types:

use ri::protocol::frames::{RiFrame, RiFrameType};

// Control frame with command data
let control = RiFrame::control_frame(
    vec![0x01, 0x02, 0x03],
    1
).expect("Failed to create control frame");

// Authentication frame with credentials
let auth = RiFrame::auth_frame(
    b"token=abc123".to_vec(),
    2
).expect("Failed to create auth frame");

// Keep-alive frame (no payload)
let keepalive = RiFrame::keepalive_frame(3)
    .expect("Failed to create keepalive frame");

// Error frame with code and message
let error = RiFrame::error_frame(
    0x0401,
    "Connection timeout".to_string(),
    4
).expect("Failed to create error frame");

Receiving and deserializing frames:

use ri::protocol::frames::{RiFrame, RiFrameType};

let original = RiFrame::data_frame(
    b"Received data".to_vec(),
    100
).expect("Failed to create frame");

let bytes = original.to_bytes().expect("Failed to serialize");

// Simulate network transmission
let received = RiFrame::from_bytes(&bytes)
    .expect("Failed to deserialize frame");

assert_eq!(received.sequence_number(), 100);
assert_eq!(received.payload, b"Received data");
assert!(received.is_valid());

Fields

header: RiFrameHeader

Frame header containing protocol metadata.

The header provides essential information for frame processing including the frame type, sequence number, timestamp, and integrity checksum. It is always exactly 32 bytes in size and uses big-endian byte ordering.

payload: Vec<u8>

Frame payload containing application data.

The payload contains the actual data being transmitted. Its meaning depends on the frame type:

• Control: Protocol management commands
• Data: Application-level message data
• Auth: Authentication credentials or tokens
• KeepAlive: Empty (no payload)
• Error: Error code + error message
• Encrypted: Pre-encrypted application data

Implementations

impl RiFrame

pub fn new( frame_type: RiFrameType, payload: Vec<u8>, sequence_number: u32, ) -> RiResult<Self>

Create a new frame

pub fn control_frame( control_data: Vec<u8>, sequence_number: u32, ) -> RiResult<Self>

Create a control frame

pub fn data_frame(data: Vec<u8>, sequence_number: u32) -> RiResult<Self>

Create a data frame

pub fn auth_frame(auth_data: Vec<u8>, sequence_number: u32) -> RiResult<Self>

Create an authentication frame

pub fn keepalive_frame(sequence_number: u32) -> RiResult<Self>

Create a keep-alive frame

pub fn error_frame( error_code: u32, error_message: String, sequence_number: u32, ) -> RiResult<Self>

Create an error frame

pub fn to_bytes(&self) -> RiResult<Vec<u8>>

Serialize frame to bytes

pub fn from_bytes(bytes: &[u8]) -> RiResult<Self>

Deserialize frame from bytes

pub fn frame_type(&self) -> Option<RiFrameType>

Get frame type

pub fn sequence_number(&self) -> u32

Get sequence number

pub fn timestamp(&self) -> u64

Get timestamp

pub fn is_valid(&self) -> bool

Check if frame is valid

Trait Implementations

impl Clone for RiFrame

fn clone(&self) -> RiFrame

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RiFrame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'py> IntoPyObject<'py> for RiFrame

type Target = RiFrame

The Python output type

type Output = Bound<'py, <RiFrame as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

impl PyClass for RiFrame

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for RiFrame

const IS_BASETYPE: bool = false

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

const IS_IMMUTABLE_TYPE: bool = false

#[pyclass(immutable_type)]

const RAW_DOC: &'static CStr = /// ```

Docstring for the class provided on the struct or enum.

const DOC: &'static CStr

Fully rendered class doc, including the text_signature if a constructor is defined.

type BaseType = PyAny

Base class

type ThreadChecker = SendablePyClass<RiFrame>

This handles following two situations:

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<isize>

fn weaklist_offset() -> Option<isize>

impl PyTypeInfo for RiFrame

const NAME: &'static str = "RiFrame"

Class name.

const MODULE: Option<&'static str> = ::core::option::Option::None

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

impl DerefToPyAny for RiFrame

impl ExtractPyClassWithClone for RiFrame