Connect

Every SDK primitive starts from one connected client. This page covers connection strings, authentication, TLS, reconnection, and default streams.

Connection strings

The simplest form is a bare connection string passed to connect:

import { Laser } from "@laserdata/laser-sdk"

await using laser = await Laser.connect("iggy:[email protected]:8090")

use laser_sdk::prelude::*;

let laser = Laser::connect("iggy:[email protected]:8090").await?;

import laser_sdk as ls

laser = await ls.Laser.connect("iggy:[email protected]:8090")

A connection string is user:pwd@host or token@host. The port defaults to 8090.

# username and password
iggy:[email protected]:8090

# token in place of user:pwd
<token>@starter-123.us-west-1.aws.laserdata.cloud

Pass the bare target shown above. The SDK adds the Iggy TCP scheme internally and always creates a VSR client.

For the complete local surface, Laser Stack starts Iggy and laser-plane, then prints the exact export to use:

export LASER_CONNECTION_STRING='iggy:[email protected]:8090'

Rust's Laser::local() and TypeScript's Laser.local() connect to iggy:[email protected]:8090. Laser Stack uses iggy:laser by default. Python has no local shortcut. Use the connection string printed by Laser Stack for shared setup.

Environment variables

Rust's Laser::connect_env() and TypeScript's Laser.connectEnv() read the environment. Python uses Laser.connect:

await using laser = await Laser.connectEnv()

let laser = Laser::connect_env().await?;

import os
import laser_sdk as ls

laser = await ls.Laser.connect(
    os.environ["LASER_CONNECTION_STRING"],
    stream=os.environ.get("LASER_STREAM"),
)

LASER_CONNECTION_STRING='user:[email protected]'
# or with a token instead of user:pwd
LASER_CONNECTION_STRING='<token>@starter-123.us-west-1.aws.laserdata.cloud'

The SDK does not read LASER_SERVER, LASER_TOKEN, LASER_USERNAME, or LASER_PASSWORD. Some examples use them to build LASER_CONNECTION_STRING.

VSR transport

VSR (Viewstamped Replication Revisited) is the only transport supported by Laser SDK:

• Rust and Python build against Apache Iggy's VSR client.
• TypeScript always constructs a VSR client. A client passed through fromIggyClient is rejected before use when it is configured for another protocol.
• There is no Cargo protocol feature, Python option, TypeScript option, connection-string flag, or classic-framing fallback.

Streaming commands and managed operations share one connection. The server decides whether an operation uses replication.

Token vs. username/password

Both forms authenticate an Apache Iggy user:

• Token - use <token>@host. Tokens suit services and CI because they can be scoped and rotated.
• Username and password - use user:pwd@host. This form suits local development.

Iggy enforces stream and topic permissions for both forms. A denied operation returns a typed error such as is_permission_denied().

TLS

For *.laserdata.cloud and *.laserdata.com, the SDK enables TLS with its bundled LaserData root CA. Other hosts keep their connection-string TLS settings.

• LASER_TLS_CERT=<path> (or the connection string's tls_ca_file= parameter) overrides the bundled CA with your own.
• LASER_NO_TLS=1 disables TLS outright - local development only.
• A connection string that already sets tls_ca_file= is left untouched by the auto-attach logic.

Reconnection

TCP reconnection covers the initial handshake and later disconnects. The default is unlimited retries at one-second intervals. Change it with connection-string parameters:

user:pwd@host
  ?reconnection_retries=<count|unlimited>
  &reconnection_interval=<duration>

Durations accept values such as 250ms, 1s, and 1m. After reconnecting, the client authenticates again with the connection-string credentials.

The single-connection model

One connection can address every stream on the server. Use the full path when no default stream is set:

laser.stream(name).topic(name)

The default stream helper

Applications that mostly work with one stream can pin it once and drop it from every call after:

await using laser = await Laser.connectWithStream(
  "iggy:[email protected]:8090",
  "shop"
)

// shorthand for laser.stream("shop").topic("orders")
const orders = laser.topic("orders")

let laser = Laser::connect_with_stream(
    "iggy:[email protected]:8090",
    "shop",
)
.await?;

// shorthand for laser.stream("shop").topic("orders")
let orders = laser.topic("orders");

laser = await ls.Laser.connect(
    "iggy:[email protected]:8090",
    stream="shop",
)

# shorthand for laser.stream("shop").topic("orders")
orders = laser.topic("orders")

Rust's connect_with_stream, TypeScript's connectWithStream, and Python's connect(..., stream=...) set a default stream. This enables laser.topic(name). Other streams remain available through laser.stream(other).topic(name). Without a default, laser.topic(name) returns a configuration error.

Change the default with Rust's with_default_stream(name), TypeScript's withDefaultStream(name), or Python's with_stream(name). The returned client shares the existing connection.

Next