Module builder 

Type-state builder pattern for OpenIGTLink clients

This module provides a flexible, type-safe way to construct OpenIGTLink clients with exactly the features you need. The builder uses Rust’s type system to prevent invalid configurations at compile time.

Design Philosophy

Instead of creating separate types for every feature combination (which would lead to exponential growth: TcpAsync, TcpAsyncTls, TcpAsyncReconnect, TcpAsyncTlsReconnect…), this builder creates a single UnifiedAsyncClient with optional features.

Benefits:

• ✅ Compile-time safety: Invalid combinations caught at compile time
• ✅ No variant explosion: Scales to any number of features
• ✅ Zero runtime cost: PhantomData markers are optimized away
• ✅ Ergonomic API: Method chaining with clear intent

Type-State Pattern

The builder uses type states to enforce valid construction:

ClientBuilder<Unspecified, Unspecified>
  ├─ .tcp(addr)  → ClientBuilder<TcpConfigured, Unspecified>
  │   ├─ .sync()       → ClientBuilder<TcpConfigured, SyncMode>
  │   │   └─ .build()  → Result<SyncIgtlClient>
  │   └─ .async_mode() → ClientBuilder<TcpConfigured, AsyncMode>
  │       ├─ .with_tls(config)      → self
  │       ├─ .with_reconnect(cfg)   → self
  │       ├─ .verify_crc(bool)      → self
  │       └─ .build()               → Result<UnifiedAsyncClient>
  └─ .udp(addr)  → ClientBuilder<UdpConfigured, Unspecified>
      └─ .build() → Result<UdpClient>

Invalid state transitions result in compile errors, not runtime errors!

Examples

Basic TCP Clients

use openigtlink_rust::io::builder::ClientBuilder;

// Synchronous TCP client (blocking I/O)
let client = ClientBuilder::new()
    .tcp("127.0.0.1:18944")
    .sync()
    .build()?;

// Asynchronous TCP client (Tokio)
let client = ClientBuilder::new()
    .tcp("127.0.0.1:18944")
    .async_mode()
    .build()
    .await?;

TLS-Encrypted Clients

use openigtlink_rust::io::builder::ClientBuilder;
use std::sync::Arc;

// TLS client for secure hospital networks
let tls_config = rustls::ClientConfig::builder()
    .with_root_certificates(rustls::RootCertStore::empty())
    .with_no_client_auth();

let client = ClientBuilder::new()
    .tcp("hospital-server.local:18944")
    .async_mode()
    .with_tls(Arc::new(tls_config))
    .build()
    .await?;

Auto-Reconnecting Clients

use openigtlink_rust::io::builder::ClientBuilder;
use openigtlink_rust::io::reconnect::ReconnectConfig;

// Client that auto-reconnects on network failures
let reconnect_config = ReconnectConfig::with_max_attempts(10);
let client = ClientBuilder::new()
    .tcp("127.0.0.1:18944")
    .async_mode()
    .with_reconnect(reconnect_config)
    .build()
    .await?;

Combined Features (TLS + Auto-Reconnect)

use openigtlink_rust::io::builder::ClientBuilder;
use openigtlink_rust::io::reconnect::ReconnectConfig;
use std::sync::Arc;

// Production-ready client with encryption AND auto-reconnect
let tls_config = rustls::ClientConfig::builder()
    .with_root_certificates(rustls::RootCertStore::empty())
    .with_no_client_auth();

let reconnect_config = ReconnectConfig::with_max_attempts(100);

let client = ClientBuilder::new()
    .tcp("production-server:18944")
    .async_mode()
    .with_tls(Arc::new(tls_config))
    .with_reconnect(reconnect_config)
    .verify_crc(true)
    .build()
    .await?;

UDP Client for Low-Latency Tracking

use openigtlink_rust::io::builder::ClientBuilder;

// UDP client for real-time surgical tool tracking (120+ Hz)
let client = ClientBuilder::new()
    .udp("127.0.0.1:18944")
    .build()?;

Compile-Time Error Prevention

The following code will not compile:

use openigtlink_rust::io::builder::ClientBuilder;

// ERROR: This library does not implement UDP + TLS (DTLS)
let client = ClientBuilder::new()
    .udp("127.0.0.1:18944")
    .with_tls(config)  // ← Compile error: method not found
    .build()?;

Note: While DTLS (Datagram TLS) exists in theory, this library focuses on TCP-based TLS as it’s the standard for OpenIGTLink secure communications.

Structs

AsyncMode

Asynchronous (non-blocking) mode state

ClientBuilder

Type-state builder for OpenIGTLink clients

SyncMode

Synchronous (blocking) mode state

TcpConfigured

TCP protocol configured state

UdpConfigured

UDP protocol configured state

Unspecified

Unspecified protocol or mode state