ReconnectionConfig

Configure WebSocket reconnection behavior

The ReconnectionConfig type controls how the III SDK reconnects to the engine when the WebSocket connection is lost.

Type Definition

TypeScript

interface ReconnectionConfig {
  initialDelayMs: number
  maxDelayMs: number
  backoffMultiplier: number
  jitterFactor: number
  maxRetries: number
}

Python

@dataclass
class ReconnectionConfig:
    initial_delay_ms: int = 1000
    max_delay_ms: int = 30000
    backoff_multiplier: float = 2.0
    jitter_factor: float = 0.3
    max_retries: int = -1

Rust

pub struct ReconnectionConfig {
    pub initial_delay_ms: u64,
    pub max_delay_ms: u64,
    pub backoff_multiplier: f64,
    pub jitter_factor: f64,
    pub max_retries: Option<u64>,  // None for infinite
    pub max_pending_messages: usize,
}

Fields

Default Configuration

TypeScript

const DEFAULT_RECONNECTION_CONFIG: ReconnectionConfig = {
  initialDelayMs: 1000,
  maxDelayMs: 30000,
  backoffMultiplier: 2,
  jitterFactor: 0.3,
  maxRetries: -1  // infinite
}

Python

DEFAULT_RECONNECTION_CONFIG = ReconnectionConfig(
    initial_delay_ms=1000,
    max_delay_ms=30000,
    backoff_multiplier=2.0,
    jitter_factor=0.3,
    max_retries=-1  # infinite
)

Rust

impl Default for ReconnectionConfig {
    fn default() -> Self {
        Self {
            initial_delay_ms: 1000,
            max_delay_ms: 30000,
            backoff_multiplier: 2.0,
            jitter_factor: 0.3,
            max_retries: None,  // infinite
            max_pending_messages: 1000,
        }
    }
}

Usage Examples

Fast Reconnection

For local development or low-latency requirements:

TypeScript

const iii = init('ws://localhost:49134', {
  reconnectionConfig: {
    initialDelayMs: 100,
    maxDelayMs: 5000,
    backoffMultiplier: 1.5,
    jitterFactor: 0.2,
    maxRetries: -1
  }
})

Python

iii = III('ws://localhost:49134', InitOptions(
    reconnection_config=ReconnectionConfig(
        initial_delay_ms=100,
        max_delay_ms=5000,
        backoff_multiplier=1.5,
        jitter_factor=0.2,
        max_retries=-1
    )
))

Rust

let reconnection = ReconnectionConfig {
    initial_delay_ms: 100,
    max_delay_ms: 5000,
    backoff_multiplier: 1.5,
    jitter_factor: 0.2,
    max_retries: None,
    max_pending_messages: 1000,
};

let config = OtelConfig {
    reconnection_config: Some(reconnection),
    ..Default::default()
};

let iii = III::new("ws://localhost:49134");
iii.set_otel_config(config);

Limited Retries

For batch jobs or scripts that should fail fast:

TypeScript

const iii = init('ws://localhost:49134', {
  reconnectionConfig: {
    initialDelayMs: 1000,
    maxDelayMs: 10000,
    backoffMultiplier: 2,
    jitterFactor: 0.3,
    maxRetries: 5  // Give up after 5 attempts
  }
})

Python

iii = III('ws://localhost:49134', InitOptions(
    reconnection_config=ReconnectionConfig(
        initial_delay_ms=1000,
        max_delay_ms=10000,
        backoff_multiplier=2.0,
        jitter_factor=0.3,
        max_retries=5  # Give up after 5 attempts
    )
))

Rust

let reconnection = ReconnectionConfig {
    initial_delay_ms: 1000,
    max_delay_ms: 10000,
    backoff_multiplier: 2.0,
    jitter_factor: 0.3,
    max_retries: Some(5),  // Give up after 5 attempts
    max_pending_messages: 1000,
};

No Automatic Reconnection

For testing or manual connection management:

TypeScript

const iii = init('ws://localhost:49134', {
  reconnectionConfig: {
    initialDelayMs: 1000,
    maxDelayMs: 1000,
    backoffMultiplier: 1,
    jitterFactor: 0,
    maxRetries: 0  // Never retry
  }
})

Python

iii = III('ws://localhost:49134', InitOptions(
    reconnection_config=ReconnectionConfig(
        initial_delay_ms=1000,
        max_delay_ms=1000,
        backoff_multiplier=1.0,
        jitter_factor=0.0,
        max_retries=0  # Never retry
    )
))

Rust

let reconnection = ReconnectionConfig {
    initial_delay_ms: 1000,
    max_delay_ms: 1000,
    backoff_multiplier: 1.0,
    jitter_factor: 0.0,
    max_retries: Some(0),  // Never retry
    max_pending_messages: 1000,
};

Connection State Monitoring

You can monitor connection state changes to react to reconnection events:

TypeScript

// Connection states: 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'

iii.onConnectionStateChange((state) => {
  console.log('Connection state:', state)
  
  if (state === 'reconnecting') {
    console.log('Attempting to reconnect...')
  } else if (state === 'connected') {
    console.log('Reconnected successfully!')
  } else if (state === 'failed') {
    console.error('Max retries exceeded, connection failed')
  }
})

Python

def on_state_change(state: str):
    print(f'Connection state: {state}')
    
    if state == 'reconnecting':
        print('Attempting to reconnect...')
    elif state == 'connected':
        print('Reconnected successfully!')
    elif state == 'failed':
        print('Max retries exceeded, connection failed')

iii.on_connection_state_change(on_state_change)

Rust

// Connection state is tracked internally
// Monitor via logs with the tracing crate

Behavior During Reconnection

Message Queueing

When the connection is lost:

1. Outgoing messages are queued in memory
2. On reconnect, all registrations (functions, triggers, services) are re-sent
3. Queued invocations are sent after reconnection
4. Duplicate registrations are automatically deduplicated

Pending Invocations

Active function invocations during disconnect:

• TypeScript/Python: Remain pending, will timeout if not completed within invocationTimeoutMs
• Rust: Subject to max_pending_messages limit, excess messages are dropped

State Preservation

• ✅ Function registrations
• ✅ Trigger registrations
• ✅ Service registrations
• ✅ Trigger type handlers
• ❌ Active WebSocket connections (channels)
• ❌ In-flight HTTP streaming responses

Best Practices

1. Production environments: Use default config with infinite retries
2. Development: Reduce delays for faster feedback
3. Batch jobs: Limit retries to fail fast
4. High-traffic: Increase jitterFactor to prevent thundering herd
5. Monitoring: Always monitor connection state in production

Related

• InitOptions
• Reconnection Guide
• Error Handling