connection.md

title	Connection
sidebar_position	2

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 — enough for public operations like catalog browsing.
• Login performs the DAP auth handshake over an attached transport and returns a ConnectResult carrying your full identity (user, organizations, apps, teams).

connect() does both in one call; disconnect() logs out and detaches. The state probes mirror the layers: is_attached() (socket open) and is_authenticated() (auth handshake succeeded). is_connected() is a backward-compatible alias with the same meaning as is_attached() — it does not imply authentication.

result = await client.connect()  # attach + login
print(result['displayName'])

await client.logout()  # drop auth, keep the socket
await client.login('other-credential')  # re-auth on the same connection
await client.detach()  # tear down the socket

Calling login() with a different credential logs out first (best-effort); with the same credential it is a no-op. attach() to a different URI detaches and re-attaches.

Context manager (recommended)

async with guarantees the connection closes even on exception — entering calls connect(), exiting calls disconnect():

async with RocketRideClient(uri='wss://api.rocketride.ai', auth=os.environ['ROCKETRIDE_APIKEY']) as client:
    result = await client.use(filepath='pipeline.pipe')
    await client.send(result['token'], 'Hello, pipeline!')

TypeScript's counterparts to the context manager are withConnection() and await using.

URI scheme

The scheme selects the transport. The client normalizes the uri to a WebSocket address before connecting: https:// and wss:// both 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 the equivalent 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: it reconnects with linear backoff (+0.25 s per failure, 15 s cap) and never gives up, except on auth failure. Wire the lifecycle callbacks to observe it:

async def on_connected(info):
    print('Connected:', info)


async def on_disconnected(reason, has_error):
    # Fires only after a successful connection drops.
    # Do NOT call disconnect() here if you want auto-reconnect.
    print('Disconnected:', reason, has_error)


async def on_connect_error(message):
    # Fires on each failed RECONNECT attempt; an initial connect() failure
    # raises to the caller instead.
    print('Connect error:', message)


client = RocketRideClient(
    uri='https://api.rocketride.ai',
    auth='my-key',
    persist=True,
    on_connected=on_connected,
    on_disconnected=on_disconnected,
    on_connect_error=on_connect_error,
)
await client.connect()

Use on_disconnected for "we were connected and then dropped"; use on_connect_error for "failed to connect".

Inspecting state

get_connection_info() returns {'connected': bool, 'transport': str, 'uri': str} — useful for a "Connected to …" display. get_apikey() returns the key in use (debugging only; avoid logging it). set_env() replaces the client's environment map used for ${ROCKETRIDE_*} substitution and credential lookup.