Configuration

View as Markdown

Configuration

Everything RocketRideClientConfig accepts, the environment variables the client reads, and how its timeouts, reconnection, and debug hooks behave.

Constructor

import { RocketRideClient } from 'rocketride';

const client = new RocketRideClient({
	auth: process.env.ROCKETRIDE_APIKEY!,
	uri: 'https://api.rocketride.ai',
	persist: true,
});

new RocketRideClient(config = {}) creates the instance; it does not open a connection until you call attach(), login(), or connect().

Property	Type	Default	Description
auth	string	—	Initial API key. Optional: omit and use env.ROCKETRIDE_APIKEY, or pass a credential directly to login()/connect().
uri	string	RocketRide Cloud	Initial server URI (e.g. https://api.rocketride.ai or ws://localhost:5565). Optional: omit and use env.ROCKETRIDE_URI or the built-in Cloud default; attach(), login(), and connect() accept URI overrides.
env	Record<string, string>	process.env strings	Environment override used for ${ROCKETRIDE_*} substitution and credential/URI defaults. In Node the SDK copies string values from process.env; it does not load .env files.
persist	boolean	false	Automatic reconnection with capped linear backoff. See Reconnection.
maxRetryTime	number	—	Accepted for backward compatibility but ignored. Reconnection has no time limit; stop it explicitly with detach() or disconnect() (logout() keeps the anonymous attachment reconnecting).
requestTimeout	number	—	Default timeout in ms per request; overridable per request() call.
module	string	CLIENT-0, CLIENT-1, …	Client name for logging.
wsPath	string	'/task/service'	WebSocket path override. Model-server clients pass '/models'.
clientName / clientVersion	string	SDK name/version	Display identity reported to the server.
public	boolean	false	Reserved: declared but not currently consumed by the client. For unauthenticated public calls, attach() without logging in.

Callbacks

Property	Signature	Description
onConnected	(info?: string) => Promise<void>	Called exactly once per accepted authenticated connection generation, after authentication and best-effort monitor restoration.
onDisconnected	(reason?: string, hasError?: boolean) => Promise<void>	Called at most once per generation, and only if that generation previously published onConnected. A failed or cancelled pre-authentication attempt does not call it. Do not call disconnect() here if you want persistent reconnection.
onConnectError	(error: ConnectionException) => void | Promise<void>	Called for automatic reconnect failures; the next retry waits for this callback. Foreground login()/connect() failures reject their promises directly. Authentication failure stops automatic retries.
onEvent	(event: DAPMessage) => Promise<void>	Called for each server event (upload progress, task status, …). Event type is event.event, payload in event.body. Subscribe per-task with addMonitor.
onTrace	(type: TraceType, message: DAPMessage) => void	Called around high-level SDK requests with a credential-redacted message copy — for logging or telemetry.
onProtocolMessage	(message: string) => void	Credential-redacted DAP messages, for protocol debugging.
onDebugMessage	(message: string) => void	Debug output.

const client = new RocketRideClient({
	auth: process.env.ROCKETRIDE_APIKEY!,
	uri: 'wss://api.rocketride.ai',
	persist: true,
	requestTimeout: 30000,
	onConnected: async () => setStatus('connected'),
	onDisconnected: async () => setStatus('disconnected'),
	onConnectError: (error) => setStatus('error', error.message),
	onEvent: async (e) => handleServerEvent(e),
});

Reconnection

With persist: true, an unexpected loss schedules a background reconnect using linear backoff: 250 ms, 500 ms, 750 ms, and so on to a 15-second cap — and it never gives up. A successful foreground login resets the delay. Foreground attach(), login(), or connect(), URI changes, logout(), detach(), and disconnect() invalidate stale timers, so stale callbacks cannot publish state. Authentication failures are not retried automatically — fix credentials and call login()/connect() again.

Environment variables

Variable	Description
ROCKETRIDE_URI	Server URI (e.g. wss://api.rocketride.ai or ws://localhost:5565)
ROCKETRIDE_APIKEY	API key, consulted by login() when no explicit credential is supplied
ROCKETRIDE_TOKEN	User token, accepted by the CLI as an alternative credential

The same map drives ${ROCKETRIDE_*} substitution inside pipeline configs passed to use() (validate() does not substitute). Replace it at runtime with setEnv().

Timeouts

requestTimeout (config) sets the default for every DAP request; request(..., timeout) overrides it per call. attach(), login(), and connect() accept a per-call { timeout } for the handshake. All timeouts are in milliseconds.