Skip to main content

Connection

View as Markdown

Connection

How the client attaches, authenticates, stays connected, and shuts down. The full method tables live in the API reference.

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.

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.

Scoped disconnect​

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

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.

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 to observe it:

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.

Last updated on