Connect and Configure

The entry point for the SDK is client.Dial(ctx, client.Config{...}).

This page focuses on the real configuration model the Go client exposes today, based on the current public API and the demo harnesses in this repo.

Minimal Dial Flow

ctx := context.Background()

cli, err := client.Dial(ctx, client.Config{
	Endpoints: []string{"127.0.0.1:9123"},
})
if err != nil {
	log.Fatal(err)
}
defer cli.Close()

What Config Controls

The most important fields in client.Config today are:

• Endpoints
  • required bootstrap addresses
• DialTimeout and RequestTimeout
  • connection and request deadlines
• MetadataRefreshTimeout and MetadataRefreshInterval
  • metadata refresh behavior for long-lived clients
• PreferredListenerName
  • listener selection when Fluss advertises multiple endpoints
• Authenticator
  • extension point for secured clusters, though the broader auth story is still incomplete
• SnapshotStorage and SnapshotFetcher
  • used for the current snapshot scan path

Bootstrap Model

The Go SDK only requires bootstrap endpoint(s), but real operation depends on more than successful initial dial.

After bootstrap, Fluss metadata advertises coordinator and tablet leader addresses. Those advertised endpoints must also be reachable from the client network. In containerized deployments, listener and advertised-listener configuration still matters.

Snapshot Storage Configuration

The current snapshot path is most relevant for the canonical Fluss + Paimon demo and the current primary-key snapshot scan implementation.

The E2E harness configures snapshot access like this:

cli, err := client.Dial(ctx, client.Config{
	Endpoints: []string{"coordinator-server:9123"},
	SnapshotStorage: client.SnapshotStorageConfig{
		S3Endpoint:  "http://rustfs:9000",
		S3AccessKey: "flussadmin",
		S3SecretKey: "flussadmin",
		S3Region:    "us-east-1",
		S3UseSSL:    false,
		S3PathStyle: true,
	},
})

This should be treated as a validated current pattern, not a claim that every snapshot storage layout is already broadly documented or hardened.

Current Caveats

• At least one endpoint is required.
• Metadata-driven routing is part of normal operation, not an optional extra.
• Snapshot storage settings are relevant only if you use the current snapshot-scan path.
• Secured-cluster auth hooks exist, but broader auth workflows are still incomplete.