Connect with Automatic Reconnection

Problem

Your application loses its WebSocket connection due to network instability, server restarts, or mobile network switches. You need it to automatically reconnect with exponential backoff.

Solution

Configure ReconnectOptions when creating your client. Starfish handles retry logic with exponential backoff and jitter automatically.

Code

TypeScript

import { StarfishClient } from "@starfish/sdk";

const client = new StarfishClient({
  server: "ws://localhost:4000",
  reconnect: {
    enabled: true,
    maxRetries: 10,
    baseDelayMs: 1000,   // start at 1 second
    maxDelayMs: 30_000,  // cap at 30 seconds
  },
});

// Monitor connection state to react to reconnections
client.connectionState$.subscribe((state) => {
  console.log("Connection:", state);
  // "connecting" | "connected" | "reconnecting" | "disconnected"
});

await client.connect();
await client.join("my-session");

Python

from starfish import StarfishClient, StarfishClientOptions, ReconnectOptions

client = StarfishClient(StarfishClientOptions(
    server="ws://localhost:4000",
    reconnect=ReconnectOptions(
        enabled=True,
        max_retries=10,
        base_delay=1000,   # start at 1 second
        max_delay=30_000,  # cap at 30 seconds
    ),
))

# Monitor connection state
client.connection_state.subscribe(lambda state: print(f"Connection: {state}"))

await client.connect()
await client.join("my-session")

Swift

import StarfishClient

let client = StarfishClient(options: StarfishClientOptions(
    server: URL(string: "ws://localhost:4000")!,
    reconnect: ReconnectOptions(
        enabled: true,
        maxRetries: 10,
        baseDelay: 1.0,   // start at 1 second
        maxDelay: 30.0     // cap at 30 seconds
    )
))

// Monitor connection state
Task {
    for await state in client.connectionState {
        print("Connection: \(state)")
    }
}

try await client.connect()
try await client.join(session: "my-session")

Explanation

The reconnection system uses exponential backoff with jitter:

• enabled — turn automatic reconnection on or off (default: true)
• maxRetries — maximum number of reconnection attempts before giving up
• baseDelayMs — initial delay between retries in milliseconds (baseDelay in seconds in Swift)
• maxDelayMs — upper bound on the delay between retries (maxDelay in Swift)

When the connection drops, the client transitions to reconnecting state and begins retrying. After a successful reconnect it automatically rejoins any previously joined session and resubscribes to topics.

Variations

Infinite retries (default behavior)

Omit maxRetries to retry indefinitely — useful for always-on installations:

TypeScript

const client = new StarfishClient({
  server: "ws://localhost:4000",
  reconnect: { enabled: true },
});

Python

client = StarfishClient(StarfishClientOptions(
    server="ws://localhost:4000",
    reconnect=ReconnectOptions(enabled=True),
))

Swift

let client = StarfishClient(options: StarfishClientOptions(
    server: URL(string: "ws://localhost:4000")!,
    reconnect: .defaults
))

Disable reconnection

For short-lived scripts or tests where you want a clean failure:

TypeScript

const client = new StarfishClient({
  server: "ws://localhost:4000",
  reconnect: { enabled: false },
});

Python

client = StarfishClient(StarfishClientOptions(
    server="ws://localhost:4000",
    reconnect=ReconnectOptions(enabled=False),
))

Swift

let client = StarfishClient(options: StarfishClientOptions(
    server: URL(string: "ws://localhost:4000")!,
    reconnect: ReconnectOptions(enabled: false)
))