# Client Configuration

Stream's server-side SDKs ship with default HTTP settings designed for typical use. For high-traffic applications or specific network environments, you may need to tune these settings.

## Default Settings

| SDK    | Request Timeout | Connect Timeout | Connection Pool              | Idle Timeout | Keep-Alive | Retries        |
| ------ | --------------- | --------------- | ---------------------------- | ------------ | ---------- | -------------- |
| Node   | 3s              | -               | Default (fetch/Undici)       | -            | Enabled    | None           |
| Python | 6s              | -               | 10 per host (httpx)          | -            | Enabled    | None           |
| Go     | 6s              | -               | ~100 idle (http.Transport)   | 90s          | Enabled    | None           |
| Java   | 10s             | -               | 5 idle connections (OkHttp)  | 59s          | Enabled    | None           |
| PHP    | 30s             | 10s             | Default (Guzzle)             | -            | Enabled    | 3x on 429      |
| Ruby   | 30s             | -               | Default (Faraday)            | -            | Enabled    | 3x exponential |
| .NET   | 100s            | -               | Managed (SocketsHttpHandler) | -            | Enabled    | None           |

## Customizing Settings

### Node

<codetabs>

<codetabs-item value="js" label="Node">

```js
const { Agent } = require("undici");

const client = new StreamClient("YOUR_API_KEY", "YOUR_API_SECRET", {
  timeout: 10000, // Request timeout in milliseconds
  agent: new Agent({
    keepAliveTimeout: 30000, // Keep-alive timeout in ms
    keepAliveMaxTimeout: 60000, // Max keep-alive timeout in ms
    connections: 50, // Max concurrent connections per host
    pipelining: 1, // HTTP pipelining
  }),
});
```

</codetabs-item>

</codetabs>

| Option    | Type   | Default | Description                                                       |
| --------- | ------ | ------- | ----------------------------------------------------------------- |
| `timeout` | number | 3000    | Request timeout in milliseconds.                                  |
| `agent`   | Agent  | Default | Custom Undici agent for connection pooling and keep-alive tuning. |

### Python

<codetabs>

<codetabs-item value="py" label="Python">

```python
client = Stream(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    timeout=10.0,  # Request timeout in seconds
)
```

</codetabs-item>

</codetabs>

| Parameter | Type  | Default | Description                 |
| --------- | ----- | ------- | --------------------------- |
| `timeout` | float | 6.0     | Request timeout in seconds. |

The Python SDK uses `httpx.Client` internally with a pool of 10 connections per host. For advanced pooling, extend the base client with a custom `httpx.Client`.

### Go

<codetabs>

<codetabs-item value="go" label="Go">

```go
// Create HTTP client with persistent connections and tuned settings
transport := &http.Transport{
    DialContext: (&net.Dialer{
        Timeout:   30 * time.Second,
        KeepAlive: 30 * time.Second,
    }).DialContext,
    MaxIdleConns:        100,
    MaxIdleConnsPerHost: 100,
    IdleConnTimeout:     90 * time.Second,
    TLSHandshakeTimeout: 10 * time.Second,
}

httpClient := &http.Client{
    Transport: transport,
    Timeout:   30 * time.Second,
}

client := getstream.NewStream("YOUR_API_KEY", "YOUR_API_SECRET",
    getstream.WithTimeout(30 * time.Second),
    getstream.WithHTTPClient(httpClient),
)
```

</codetabs-item>

</codetabs>

| Option                   | Default             | Description                                     |
| ------------------------ | ------------------- | ----------------------------------------------- |
| `WithTimeout(duration)`  | 6s                  | Request timeout.                                |
| `WithHTTPClient(client)` | Default http.Client | Custom HTTP client with full transport control. |
| `WithLogger(logger)`     | Default logger      | Custom logger for debugging.                    |

**Transport settings:**

| Setting                 | Default | Recommended | Description                                                  |
| ----------------------- | ------- | ----------- | ------------------------------------------------------------ |
| `DialContext.Timeout`   | 30s     | 30s         | TCP connection establishment timeout.                        |
| `DialContext.KeepAlive` | 30s     | 30s         | TCP keep-alive probe interval.                               |
| `MaxIdleConns`          | 100     | 100-200     | Max idle connections across all hosts.                       |
| `MaxIdleConnsPerHost`   | 2       | 50-100      | Max idle connections per host. Increase for high throughput. |
| `IdleConnTimeout`       | 90s     | 90s         | How long idle connections stay in the pool.                  |
| `TLSHandshakeTimeout`   | 10s     | 10s         | TLS handshake timeout.                                       |

### Java

<codetabs>

<codetabs-item value="java" label="Java">

```java
// Via properties
Properties props = new Properties();
props.put("io.getstream.apiKey", "YOUR_API_KEY");
props.put("io.getstream.apiSecret", "YOUR_API_SECRET");
props.put("io.getstream.timeout", "15000");  // Request timeout in milliseconds

var client = new StreamSDKClient(props);
```

</codetabs-item>

</codetabs>

| Property               | Env Variable         | Default | Description                                             |
| ---------------------- | -------------------- | ------- | ------------------------------------------------------- |
| `io.getstream.timeout` | `STREAM_API_TIMEOUT` | 10000   | Request timeout in milliseconds (OkHttp `callTimeout`). |

The Java SDK uses OkHttp with a connection pool of 5 idle connections and 59-second idle timeout. For custom pooling, provide a configured `StreamHTTPClient` instance.

### PHP

<codetabs>

<codetabs-item value="php" label="PHP">

```php
use GuzzleHttp\Client as GuzzleClient;

// Custom Guzzle client with tuned settings
$httpClient = new GuzzleClient([
    'timeout' => 15,           // Request timeout in seconds
    'connect_timeout' => 5,    // Connection timeout in seconds
]);

$client = ClientBuilder::apiKey('YOUR_API_KEY')
    ->apiSecret('YOUR_API_SECRET')
    ->httpClient($httpClient)
    ->build();
```

</codetabs-item>

</codetabs>

| Setting           | Default    | Description                                                        |
| ----------------- | ---------- | ------------------------------------------------------------------ |
| `timeout`         | 30s        | Request timeout in seconds.                                        |
| `connect_timeout` | 10s        | TCP connection timeout in seconds.                                 |
| Retry on 429      | 3 attempts | Automatic exponential backoff with jitter on rate limit responses. |

### Ruby

<codetabs>

<codetabs-item value="ruby" label="Ruby">

```ruby
client = GetStream::Client.new(
  api_key: "YOUR_API_KEY",
  api_secret: "YOUR_API_SECRET",
  timeout: 15,  # Request timeout in seconds
)
```

</codetabs-item>

</codetabs>

| Parameter | Default    | Description                                                  |
| --------- | ---------- | ------------------------------------------------------------ |
| `timeout` | 30s        | Request timeout in seconds.                                  |
| Retry     | 3 attempts | Exponential backoff (0.05s base, 2x factor, 0.5 randomness). |

### .NET

<codetabs>

<codetabs-item value="dotnet" label=".NET">

```csharp
// The .NET SDK uses HttpClient with framework defaults.
// For production tuning, configure via IHttpClientFactory:
builder.Services.AddHttpClient("stream", client =>
{
    client.Timeout = TimeSpan.FromSeconds(15);
})
.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2),
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1),
    MaxConnectionsPerServer = 50,
});
```

</codetabs-item>

</codetabs>

| Setting                    | Default   | Description                                        |
| -------------------------- | --------- | -------------------------------------------------- |
| `Timeout`                  | 100s      | .NET HttpClient framework default.                 |
| `PooledConnectionLifetime` | Unlimited | How long a connection lives before being replaced. |
| `MaxConnectionsPerServer`  | Unlimited | Max connections per server.                        |

## Recommendations for High-Traffic Applications

- **Increase `MaxIdleConnsPerHost`** (Go) or equivalent — the default of 2 per host is too low for high-throughput moderation workloads.
- **Set explicit timeouts** — don't rely on framework defaults (especially .NET's 100s default). 10-30 seconds is a good range for moderation API calls.
- **Enable connection reuse** — all SDKs enable keep-alive by default. Avoid creating new client instances per request.
- **Monitor for connection exhaustion** — if you see connection errors under load, increase pool sizes.
- **Use a single client instance** — instantiate the Stream client once and reuse it across your application. All SDKs are thread-safe / goroutine-safe.


---

This page was last updated at 2026-04-16T18:29:40.211Z.

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/guides/client-configuration/](https://getstream.io/moderation/docs/node/guides/client-configuration/).