> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/iii-hq/sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# Client

> III struct and connection management

## Overview

The `III` struct is the main entry point for the SDK. It manages WebSocket connections to the III Engine, handles function registration, and provides methods for invoking remote functions.

## Creating a Client

### III::new

Create a new III client with default worker metadata.

```rust theme={null}
pub fn new(address: &str) -> Self
```

<ParamField path="address" type="&str" required>
  WebSocket address of the III Engine (e.g., `ws://localhost:49134`)
</ParamField>

<ResponseField name="III" type="III">
  A new III client instance
</ResponseField>

**Example:**

```rust theme={null}
use iii_sdk::III;

let iii = III::new("ws://localhost:49134");
```

### III::with\_metadata

Create a new III client with custom worker metadata.

```rust theme={null}
pub fn with_metadata(address: &str, metadata: WorkerMetadata) -> Self
```

<ParamField path="address" type="&str" required>
  WebSocket address of the III Engine
</ParamField>

<ParamField path="metadata" type="WorkerMetadata" required>
  Custom metadata describing this worker (runtime, version, name, OS)
</ParamField>

**Example:**

```rust theme={null}
use iii_sdk::{III, WorkerMetadata};

let metadata = WorkerMetadata {
    runtime: "rust".to_string(),
    version: "0.4.1".to_string(),
    name: "my-worker".to_string(),
    os: "linux x86_64".to_string(),
    telemetry: None,
};

let iii = III::with_metadata("ws://localhost:49134", metadata);
```

## Connection Management

### connect

Connect to the III Engine and start the message loop.

```rust theme={null}
pub async fn connect(&self) -> Result<(), IIIError>
```

<ResponseField name="Result" type="Result<(), IIIError>">
  Returns `Ok(())` on successful connection, or an error if connection fails
</ResponseField>

**Example:**

```rust theme={null}
let iii = III::new("ws://localhost:49134");
iii.connect().await?;
```

<Note>
  The `connect` method spawns a background task that maintains the WebSocket connection. If the connection is lost, it will automatically reconnect with exponential backoff.
</Note>

### shutdown\_async

Shutdown the client and flush all pending telemetry data.

```rust theme={null}
pub async fn shutdown_async(&self)
```

**Example:**

```rust theme={null}
iii.shutdown_async().await;
```

<Note>
  When the `otel` feature is enabled, this method waits for all spans, metrics, and logs to be exported before returning. Use this instead of the deprecated `shutdown()` method to ensure telemetry is not lost.
</Note>

## Configuration

### address

Get the WebSocket address this client connects to.

```rust theme={null}
pub fn address(&self) -> &str
```

**Example:**

```rust theme={null}
let addr = iii.address();
println!("Connected to: {}", addr);
```

### set\_metadata

Set custom worker metadata (must be called before `connect`).

```rust theme={null}
pub fn set_metadata(&self, metadata: WorkerMetadata)
```

<ParamField path="metadata" type="WorkerMetadata" required>
  Worker metadata to register with the engine
</ParamField>

### set\_otel\_config

Set OpenTelemetry configuration (requires `otel` feature, must be called before `connect`).

```rust theme={null}
#[cfg(feature = "otel")]
pub fn set_otel_config(&self, config: OtelConfig)
```

<ParamField path="config" type="OtelConfig" required>
  OpenTelemetry configuration including service name, metrics settings, etc.
</ParamField>

**Example:**

```rust theme={null}
#[cfg(feature = "otel")]
{
    use iii_sdk::{III, OtelConfig};
    
    let iii = III::new("ws://localhost:49134");
    
    let otel_config = OtelConfig {
        enabled: Some(true),
        service_name: Some("my-service".to_string()),
        metrics_enabled: Some(true),
        logs_enabled: Some(true),
        ..Default::default()
    };
    
    iii.set_otel_config(otel_config);
    iii.connect().await?;
}
```

## Types

### WorkerMetadata

Metadata about a worker that is registered with the engine.

```rust theme={null}
pub struct WorkerMetadata {
    pub runtime: String,
    pub version: String,
    pub name: String,
    pub os: String,
    pub telemetry: Option<WorkerTelemetryMeta>,
}
```

**Default Implementation:**

The default implementation auto-detects:

* Runtime: `"rust"`
* Version: SDK version from `Cargo.toml`
* Name: `"{hostname}:{pid}"`
* OS: System architecture and family
* Telemetry: Language locale from environment

### IIIError

Error types returned by SDK operations.

```rust theme={null}
pub enum IIIError {
    NotConnected,
    Timeout,
    Remote { code: String, message: String },
    Handler(String),
    Serde(String),
    WebSocket(String),
}
```

## See Also

* [Functions API](/rust/api/functions) - Register and handle function invocations
* [Invocation API](/rust/api/invocation) - Call remote functions
* [Telemetry API](/rust/api/telemetry) - Configure OpenTelemetry