> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# Connection

How the client attaches, authenticates, stays connected, and shuts down. The full
method tables live in the [API reference](/clients/typescript/reference#connection).

## The layered model

The connection has two layers you can drive together or separately:

- **Attach** opens the WebSocket without authenticating — public `rrext_public_*`
  requests are available on an anonymous attachment.
- **Login** authenticates over the attachment, restores monitor subscriptions, and
  returns a `ConnectResult` carrying your full identity (user, organizations, apps,
  teams).

`connect()` performs attach + login as one foreground operation; `disconnect()` does
a best-effort logout, cancels pending work, and detaches. The state probes mirror
the layers: `isAttached()` (socket open), `isAuthenticated()` (auth succeeded), and
`isConnected()` — a compatibility **alias for `isAttached()`**; it does not imply
authentication.

```typescript
const result = await client.connect();
console.log(result.displayName);

await client.logout(); // drop auth, keep an anonymous attachment
await client.login('other-credential'); // re-auth on the same connection
await client.detach(); // tear down the socket
```

For UIs that need anonymous public calls before sign-in: `attach()`, then
`login()`, and `logout()` to return to a fresh anonymous attachment. `login()` also
accepts an OAuth code exchange (`{ code, verifier, redirectUri }`) as the
credential.

## Concurrent logins

Concurrent foreground `login()`/`connect()` calls for the same endpoint and
credential **join** one operation: one attachment, one auth request, one result. A
different foreground login **supersedes** the earlier one, and foreground work
always supersedes background reconnects (never the reverse). Superseded waiters
reject with `LoginAttemptCancelledError('superseded')`; the error's `reason` is
exactly `'superseded'`, `'logout'`, or `'detached'`. An unsolicited transport loss
during login rejects with `ConnectionException` instead. See
[Error Handling](/clients/typescript/errors).

## Scoped disconnect

The client supports `await using` (`Symbol.asyncDispose`) for automatic disconnect
when leaving scope, and `RocketRideClient.withConnection()` for one-off scripts:

```typescript
const status = await RocketRideClient.withConnection({ auth: 'my-key', uri: 'wss://api.rocketride.ai' }, async (client) => {
	const { token } = await client.use({ pipeline: myPipelineConfig });
	await client.send(token, JSON.stringify({ data: 1 }));
	return await client.getTaskStatus(token);
});
```

> Python's counterpart to scoped disconnect is the
> [async context manager](/clients/python/connection#context-manager-recommended).

## URI scheme

The scheme selects the transport: `https://` and `wss://` resolve to a secure
`wss://` connection, while `http://`, `ws://`, and a bare `host:port` resolve to
plain `ws://`. For RocketRide Cloud use `https://api.rocketride.ai` (or
`wss://api.rocketride.ai`); for a local engine use `ws://localhost:5565`.

**Caution:** against a Cloud endpoint always use `https://` or `wss://` — an
`http://` or `ws://` URI (or a bare `host:port`) silently downgrades to an
unencrypted `ws://` connection.

## Staying connected

With `persist: true` the client survives drops — linear backoff (250 ms steps,
15 s cap), never gives up, auth failures excepted. Wire the
[lifecycle callbacks](/clients/typescript/configuration#callbacks) to observe it:

```typescript
const client = new RocketRideClient({
	auth: apiKey,
	uri: serverUri,
	persist: true,
	onConnected: async () => updateUI({ state: 'connected' }),
	onDisconnected: async (reason, hasError) => updateUI({ state: 'disconnected', reason, hasError }),
	onConnectError: (error) => updateUI({ state: 'error', message: error.message }),
});
await client.connect();
```

Use `onDisconnected` for "we were connected and then dropped"; use
`onConnectError` for "failed to connect". Only call `detach()` or `disconnect()`
when reconnection should stop.

## Inspecting state

`getConnectionInfo()` returns `{ connected, transport, uri }` — useful for a
"Connected to …" display. `getApiKey()` returns the key in use (debugging only;
avoid logging it). `setEnv()` replaces the environment map used for
`${ROCKETRIDE_*}` substitution and credential lookup.

## Optional signup attribution

PKCE credentials passed to `login()` or `connect()` may include `signupProperties` (type
`SignupProperties` or a synchronous `() => SignupProperties | null` resolver). The SDK evaluates
the resolver immediately before sending authentication, after transport readiness. Use a resolver
when consent can change during connection setup; return null to omit context. Resolver errors
also omit context without interrupting login. The SDK forwards only the bounded version 1 schema validated by
`normalizeSignupProperties`. Invalid or expired context is omitted; credentials without context
retain their existing wire encoding. Only the encoded `cd_` credential uses the snake_case
`signup_properties` key. No context is placed in an OAuth URL. This is analytics
metadata and never an authorization claim. The backend validates its active experiment separately.
Optional attribution does not change credential deduplication and is not retained in fallback
reconnect credentials after successful authentication.
