ironrdp-core

Common traits and types for the IronRDP project

Version: 0.1.5
Docs.rs: ironrdp-core

Overview

The ironrdp-core crate provides foundational traits and types used throughout IronRDP. It defines the core encoding/decoding infrastructure, cursor utilities, and error types that form the basis of all PDU operations.

Key Design Principles

• no_std compatible: Core functionality works without the standard library
• Object-safe traits: Enables dynamic dispatch for protocol PDUs
• Zero-copy parsing: Uses cursors instead of allocating intermediate buffers
• Type-safe encoding: Size is computed before writing to prevent buffer overruns

Core Traits

Encode

pub trait Encode {
    fn encode(&self, dst: &mut WriteCursor<'_>) -> EncodeResult<()>;
    fn name(&self) -> &'static str;
    fn size(&self) -> usize;
}

Trait for types that can be encoded into binary form. All RDP PDUs implement this trait.

Key Methods:

• encode() - Writes the PDU to a WriteCursor
• name() - Returns a static name for debugging/logging
• size() - Computes the exact size in bytes before encoding

Helper Functions:

// Encode to a fixed-size buffer
pub fn encode<T: Encode>(pdu: &T, dst: &mut [u8]) -> EncodeResult<usize>

// Encode using a WriteCursor
pub fn encode_cursor<T: Encode>(pdu: &T, dst: &mut WriteCursor<'_>) -> EncodeResult<()>

// Encode to a growable buffer (requires alloc feature)
pub fn encode_buf<T: Encode>(pdu: &T, buf: &mut WriteBuf) -> EncodeResult<usize>

// Encode to a new Vec (convenience function)
pub fn encode_vec<T: Encode>(pdu: &T) -> EncodeResult<Vec<u8>>

Decode

pub trait Decode<'de>: Sized {
    fn decode(src: &mut ReadCursor<'de>) -> DecodeResult<Self>;
}

Trait for types that can be decoded from a byte stream. The lifetime parameter 'de allows zero-copy parsing.

Helper Functions:

// Decode from a byte slice
pub fn decode<'de, T: Decode<'de>>(src: &'de [u8]) -> DecodeResult<T>

// Decode using a ReadCursor
pub fn decode_cursor<'de, T: Decode<'de>>(src: &mut ReadCursor<'de>) -> DecodeResult<T>

DecodeOwned

pub trait DecodeOwned: Sized {
    fn decode_owned(src: &mut ReadCursor<'_>) -> DecodeResult<Self>;
}

Similar to Decode but unconditionally returns an owned type (no lifetime parameter). Use when you need to own the decoded data.

Cursor Types

ReadCursor

pub struct ReadCursor<'a> { /* private fields */ }

Zero-copy cursor for reading bytes from a buffer. Tracks position and provides typed read methods.

Common Methods:

new · fn(bytes: &'a [u8]) -> Self

Create a new cursor from a byte slice

read_u8 · fn(&mut self) -> u8

Read a single byte

read_u16 · fn(&mut self) -> u16

Read a little-endian u16

read_u16_be · fn(&mut self) -> u16

Read a big-endian u16

read_u32 · fn(&mut self) -> u32

Read a little-endian u32

read_slice · fn(&mut self, n: usize) -> &'a [u8]

Read a slice of n bytes

remaining · fn(&self) -> &'a [u8]

Get the remaining unread bytes

len · fn(&self) -> usize

Number of bytes remaining

pos · fn(&self) -> usize

Current position in the buffer

Example:

use ironrdp_core::ReadCursor;

let data = &[0x01, 0x02, 0x03, 0x04];
let mut cursor = ReadCursor::new(data);

let first = cursor.read_u8();  // 0x01
let second = cursor.read_u16(); // 0x0302 (little-endian)
assert_eq!(cursor.len(), 1); // 1 byte remaining

WriteCursor

pub struct WriteCursor<'a> { /* private fields */ }

Cursor for writing bytes to a mutable buffer. Provides type-safe write methods and tracks position.

Common Methods:

new · fn(bytes: &'a mut [u8]) -> Self

Create a new cursor from a mutable byte slice

write_u8 · fn(&mut self, value: u8)

Write a single byte

write_u16 · fn(&mut self, value: u16)

Write a little-endian u16

write_u16_be · fn(&mut self, value: u16)

Write a big-endian u16

write_u32 · fn(&mut self, value: u32)

Write a little-endian u32

write_slice · fn(&mut self, slice: &[u8])

Write a slice of bytes

pos · fn(&self) -> usize

Current position (number of bytes written)

Example:

use ironrdp_core::WriteCursor;

let mut buffer = [0u8; 8];
let mut cursor = WriteCursor::new(&mut buffer);

cursor.write_u8(0x01);
cursor.write_u16(0x0302); // little-endian
cursor.write_u32(0x07060504); // little-endian

assert_eq!(cursor.pos(), 7);

WriteBuf

pub struct WriteBuf { /* private fields */ }

Growable write buffer that manages a Vec<u8> internally. Maintains separate “filled” and “unfilled” regions.

Requires the alloc feature. Use WriteBuf when the output size is not known in advance.

Common Methods:

new · fn() -> Self

Create a new empty buffer

unfilled_to · fn(&mut self, size: usize) -> &mut [u8]

Get a mutable slice of at least size bytes, growing if necessary

advance · fn(&mut self, n: usize)

Mark n bytes as filled after writing to unfilled_to()

filled · fn(&self) -> &[u8]

Get the filled portion of the buffer

clear · fn(&mut self)

Reset the filled region without deallocating

Example:

use ironrdp_core::{WriteBuf, WriteCursor, encode_buf};

let mut buf = WriteBuf::new();

// Write multiple PDUs
for pdu in pdus {
    encode_buf(&pdu, &mut buf)?;
}

// Get all encoded data
let data = buf.filled();

// Reuse buffer for next batch
buf.clear();

Error Types

EncodeError & DecodeError

pub type EncodeResult<T> = Result<T, EncodeError>;
pub type DecodeResult<T> = Result<T, DecodeError>;

pub enum EncodeErrorKind {
    NotEnoughBytes { received: usize, expected: usize },
    InvalidField { field: &'static str, reason: &'static str },
    UnexpectedMessageType { got: u8 },
    UnsupportedVersion { got: u8 },
    UnsupportedValue { name: &'static str, value: String },
    Other { description: &'static str },
}

Both encode and decode operations return structured errors with context.

Example Error Handling:

use ironrdp_core::{decode, DecodeError};

match decode::<MyPdu>(&bytes) {
    Ok(pdu) => { /* process pdu */ },
    Err(e) => {
        eprintln!("Failed to decode: {}", e);
        // Error includes context and source chain
    }
}

Features

std · feature

Enables standard library support (includes alloc)

alloc · feature

Enables heap allocations (WriteBuf, Vec support)

Usage Notes

WriteCursor vs WriteBuf:

• Use WriteCursor when you know the exact size and want syscall-free, infallible writes
• Use WriteBuf when size is unknown and you need the buffer to grow automatically
• WriteCursor wraps &mut [u8] for stack/static buffers
• WriteBuf manages Vec<u8> internally and can resize

Object Safety:
The Encode trait is intentionally object-safe to enable dynamic dispatch:

let pdus: Vec<Box<dyn Encode>> = vec![Box::new(pdu1), Box::new(pdu2)];

See Also

• ironrdp-pdu - PDU definitions that use these traits
• ironrdp-svc - Static virtual channel traits
• ARCHITECTURE.md - Crate architecture