Configuration

Endpoints

By default, SDKs connect to the cloud instance at s2.dev, and only require an access token to get started, which can be generated from the dashboard. Users who elect to use Private Networking can provide the relevant endpoints as an override when configuring the client. SDKs can also connect to any S2-compatible endpoint, such as s2-lite for local development:

TypeScript
Go
Rust

const client = new S2({
	accessToken: "local-token",
	endpoints: {
		account: "http://localhost:8080",
		basin: "http://localhost:8080",
	},
});

client := s2.New("local-token", &s2.ClientOptions{
	BaseURL: "http://localhost:8080",
	MakeBasinBaseURL: func(basin string) string {
		return "http://localhost:8080"
	},
})

let endpoints = S2Endpoints::new(
    AccountEndpoint::new("http://localhost:8080")?,
    BasinEndpoint::new("http://localhost:8080")?,
)?;

let client = S2::new(S2Config::new(token).with_endpoints(endpoints))?;

Environment Variables

SDKs can read some common configuration keys from environment variables:

Variable	Description
`S2_ACCOUNT_ENDPOINT`	Account-level API endpoint
`S2_BASIN_ENDPOINT`	Basin-level API endpoint (may include `{basin}` placeholder for DNS-based routing)

Timeouts

SDKs support configuring connection and request timeouts:

TypeScript
Go
Rust

const client = new S2({
	accessToken: token,
	connectionTimeoutMillis: 3000,
	requestTimeoutMillis: 5000,
});

client := s2.New(token, &s2.ClientOptions{
	ConnectionTimeout: 5 * time.Second,
	RequestTimeout:    30 * time.Second,
})

let client = S2::new(
    S2Config::new(token)
        .with_connection_timeout(Duration::from_secs(5))
        .with_request_timeout(Duration::from_secs(10)),
)?;

Connection timeout: Maximum time to wait for a TCP connection to be established. This is a “fail fast” timeout that aborts slow connections early.
Request timeout: Maximum time to wait for a unary (non-streaming) request to complete. For append sessions, this value is also used to determine the SDK-enforced timeout for an individual batch append to be acknowledged.

Retry Behavior

SDKs automatically retry transient failures using exponential backoff with jitter.

TypeScript
Go
Rust

const client = new S2({
	accessToken: token,
	retry: {
		maxAttempts: 5,
		minBaseDelayMillis: 100,
		maxBaseDelayMillis: 2000,
	},
});

client := s2.New(token, &s2.ClientOptions{
	RetryConfig: &s2.RetryConfig{
		MaxAttempts:  5,
		MinBaseDelay: 100 * time.Millisecond,
		MaxBaseDelay: 2 * time.Second,
	},
})

let client = S2::new(
    S2Config::new(token).with_retry(
        RetryConfig::new()
            .with_max_attempts(NonZeroU32::new(5).unwrap())
            .with_min_base_delay(Duration::from_millis(100))
            .with_max_base_delay(Duration::from_secs(2)),
    ),
)?;

Append Retry Policy

Retrying appends requires care: if an append succeeds but the acknowledgement is lost, retrying would create duplicate records in a stream. The appendRetryPolicy setting controls how to react in this situation, by treating append retries as a special case.

Policy	Behavior
`all` (default)	Retry all appends. Duplicates are possible on transient failures.
`noSideEffects`	Only retry appends that include `matchSeqNum`, which makes them idempotent.

Using noSideEffects means that, in the event of a failure, the caller will manually need to verify whether or not the append succeeded (e.g., by reading or otherwise inspecting the state of the stream).

To achieve “exactly-once” semantics in single-writer setups, a matchSeqNum precondition can be used when appending. See concurrency control in the API docs.

Configuration Reference

Timeout Settings

Setting	Default	Description
Connection timeout	3 seconds	Max time to establish TCP connection
Request timeout	5 seconds	Max time for request completion

Retry Settings

Setting	Default	Description
Max attempts	3	Maximum retry attempts
Min base delay	100 ms	Minimum base delay for exponential backoff
Max base delay	1 second	Maximum base delay (actual delay with jitter can be up to 2x)
Append retry policy	`all`	How to handle append retries when duplication is possible

SDKs

​Endpoints

​Environment Variables

​Timeouts

​Retry Behavior

​Append Retry Policy

​Configuration Reference

​Timeout Settings

​Retry Settings

Endpoints

Environment Variables

Timeouts

Retry Behavior

Append Retry Policy

Configuration Reference

Timeout Settings

Retry Settings