State Machine Architecture
The connection process is split across two primary crates:ironrdp-connector: Handles connection establishment up to the “Connected” stateironrdp-session: Manages the active RDP session after connection
Why State Machines?
IronRDP’s state machine design enforces several architectural invariants:- No hidden I/O: Core tier crates never perform network operations
- Explicit state transitions: Each step is visible and controllable
- Testability: States can be tested in isolation
- Async-agnostic: Works with blocking, async, or custom I/O strategies
ironrdp-connector/src/lib.rs:327-337.
Connection States
TheClientConnector state machine progresses through these states:
State Diagram
Step-by-Step Connection Flow
Active Session Management
After connection, useironrdp-session::ActiveStage to handle the active session:
ironrdp-session/src/active_stage.rs for the complete ActiveStageOutput enum.
Adding Static Virtual Channels
Register static channels before stepping through the connector:SvcClientProcessor:
Error Handling
The connector returnsConnectorResult<T> for all operations:
ironrdp-connector/src/lib.rs:35-82 for NegotiationFailure definitions.
Best Practices
Do:
- Check
connector.state().is_terminal()to know when connection is complete - Use
connector.next_pdu_hint()to determine expected PDU size for buffer allocation - Clear
WriteBufbetween steps to avoid accumulating data - Handle all
ConnectorErrorvariants appropriately
- Call
step()when in a terminal state - Reuse the same input buffer without clearing between reads
- Assume specific byte sizes — always check
Writtenresult - Skip security upgrade or CredSSP steps when indicated by state
Example: Complete Connection Loop
References
- State Machine Trait:
ironrdp-connector/src/lib.rs:327-337 - Connector Implementation:
ironrdp-connector/src/connection.rs - Channel Connection:
ironrdp-connector/src/channel_connection.rs - License Exchange:
ironrdp-connector/src/license_exchange.rs - Connection Activation:
ironrdp-connector/src/connection_activation.rs - Active Session:
ironrdp-session/src/active_stage.rs

