Skip to main content
IronRDP implements the RDP connection and session lifecycle using explicit state machines that handle each protocol phase. This design provides precise control and testability without hidden I/O operations.

State Machine Architecture

The connection process is split across two primary crates:
  • ironrdp-connector: Handles connection establishment up to the “Connected” state
  • ironrdp-session: Manages the active RDP session after connection

Why State Machines?

IronRDP’s state machine design enforces several architectural invariants:
  1. No hidden I/O: Core tier crates never perform network operations
  2. Explicit state transitions: Each step is visible and controllable
  3. Testability: States can be tested in isolation
  4. Async-agnostic: Works with blocking, async, or custom I/O strategies
See ironrdp-connector/src/lib.rs:327-337.

Connection States

The ClientConnector state machine progresses through these states:

State Diagram

Step-by-Step Connection Flow

Active Session Management

After connection, use ironrdp-session::ActiveStage to handle the active session:
See ironrdp-session/src/active_stage.rs for the complete ActiveStageOutput enum.

Adding Static Virtual Channels

Register static channels before stepping through the connector:
Channels must implement SvcClientProcessor:
See Virtual Channels for details.

Error Handling

The connector returns ConnectorResult<T> for all operations:
Negotiation failures provide user-friendly messages:
See 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 WriteBuf between steps to avoid accumulating data
  • Handle all ConnectorError variants appropriately
Don’t:
  • Call step() when in a terminal state
  • Reuse the same input buffer without clearing between reads
  • Assume specific byte sizes — always check Written result
  • 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