The Oda Remote API

The Oda client drives a running DataMind Oda through its Remote layer: unary calls, long-lived streams and forwarded events travel between the interface you see and the runtime behind it. This page documents the message shapes and rules, so you can read a trace, debug a connection or build a client of your own.

For the different surface that lets a program of your own drive Oda from outside the app, start at the Oda SDK overview.

Calls and streams

Calls are addressed. A call names a namespace and a method and carries its arguments as one plain object. The runtime checks those arguments before the method runs, so a call with the wrong shape fails instead of reaching the method.
Answers are result envelopes. An answer reports success with a value or failure with an error. A call the caller aborts settles as a cancelled failure, not as a failure from the method.
Streams are logical. They share the one WebSocket connection the client keeps open, each under its own stream id, and carry frames in both directions over it.
Reconnects start fresh. When the connection drops, the client reconnects and each stream reopens on the new connection; nothing from the old connection is replayed, so a consumer re-reads the state it needs.
A mismatch fails early. A method that is a stream must be opened as a stream, and a plain call must not be opened as one; the mismatch fails before the method runs.
Only admitted callers connect. Before any stream opens, the connection must come from a caller the runtime trusts and can authenticate: a caller it does not trust gets 403, and one it cannot authenticate gets 401.

On a stream, each side sends a small set of frames:

From	Frame	What it does
Client	`open`	Opens a logical stream, naming the method it calls and its arguments.
Client	`item`	Sends one uplink item; its value may be omitted.
Client	`end`	Half-closes the uplink: no further items follow.
Client	`cancel`	The consumer has left; the stream is torn down.
Runtime	`item`	Delivers one downlink value.
Runtime	`error`	Ends the stream with a failure: a code, a message and details.
Runtime	`end`	Ends the stream normally.

Items wait for the reader. An item that arrives before the method reads its uplink waits in the stream's inbox instead of being lost.
Late items fail only their stream. An uplink item sent after end fails that stream with a protocol failure; the connection stays open for its other streams.
Stray frames are dropped. A frame that names a stream the connection does not know, or has already finished, is ignored. The one violation that closes the whole connection is a second open for a stream id that is already open.

Forwarded events

A fixed list. The client subscribes to events from a list fixed at build time, twenty-five entries in the current set; a name outside the list is never forwarded.
What the list carries. Session changes (a session added or removed, its status, its activity, its branches and its errors), preset selection, goal activation changes, model adapter updates, permission catalogue changes, scheduled-task changes, settings updates, and the client's own components (commands, credentials and plugins).
Two entries answer back. An approval request and a user question arrive as requests: the first client to answer settles the request, the other clients are told it was cancelled, and a client that does not answer can hand the request to the next handler. When every client hands it on, the runtime's own fallback answers.
The events stream opens with a readiness frame. Its first item confirms readiness and carries the runtime's home folder, which the client uses to shorten displayed paths.
Only requests are replayed. A one-way event missed while disconnected is gone; a request still waiting for an answer is sent again to the replacement connection.

Limits

Lossless JSON only. Every uplink item and every forwarded-event payload must be plain JSON data: objects with enumerable fields, dense arrays and ordinary JSON values. An item may omit its value; anything present must not use undefined fields, big integers, NaN, infinities, negative zero, cycles, class instances, functions, accessor or hidden fields, or symbol keys.
A bounded uplink. A stream's uplink buffers at most 262,144 bytes of frames by default. A client that overruns this fails its own stream with gateway/uplink-overflow, and later items are dropped; uplink items are never replayed.
One consumer per stream. A logical stream serves exactly one consumer, and opening a second one fails.
The heartbeat is also the deadline. The connection is pinged every two seconds by default, and that interval is both the ping cadence and the answer deadline: a peer that misses two intervals in a row has its connection terminated.
Text messages only. A binary message closes the connection.

Close codes

A connection ends with a close code and, usually, a reason:

Code	Reason	What it means
`1000`	`disposed`	The client was disposed; the connection is closed for good.
`1001`	`peer left`	The peer's session ended, and its streams close with it.
`1003`	`text messages required`	A binary message arrived; the connection carries text only.
`1008`	`invalid Remote stream request`	A malformed message, an unknown message type, or a duplicate `open`.
`1011`	`Remote stream failure could not be delivered`	A stream failed and its failure could not be written, so the connection closed.
`4000`	`reconnect requested`	The client is making a fresh connection attempt.
`4002`	an invalid frame	A frame did not parse; every active stream fails and the connection closes.

When a call or stream fails

A failure carries a code, the endpoint it belongs to, and, when one field is at fault, that field's name.
The layer's own failures use a fixed vocabulary. For example: gateway/cancelled when the caller aborted, with the message Remote invocation "<endpoint>" was aborted; gateway/uplink-overflow when an uplink overran its bound; gateway/protocol for an uplink item after the stream had ended; and gateway/internal for a failure the layer could not classify, with empty details.
The rest of the vocabulary covers dispatch problems: an endpoint that cannot be found or is ambiguous, a service that is not available, and arguments or results that fail validation.
A failure from the method itself passes through unchanged; the layer marks only its own problems.

Questions, answered

What happens to my frames when the connection drops?

Nothing is replayed. When the client reconnects, each stream reopens on the new connection and re-reads the state it needs; uplink items and notifications from the old connection are never sent again.

Why did the connection close with code `1008`?

The reason invalid Remote stream request covers a malformed message, an unknown message type, or a second open for a stream id that is already open. Check the frames against the shapes on this page; a duplicate open is the one violation that closes the whole connection.

Why was my uplink item not lossless JSON?

The value used something the JSON subset does not admit, such as an undefined field, a big integer, NaN, an infinity, negative zero, a cycle, a class instance, or an accessor, hidden or symbol field. Send plain objects, dense arrays and ordinary JSON values instead.

Can two consumers watch the same stream?

No. A logical stream serves exactly one consumer, and opening a second one fails. When several parts of the interface need the same data, the client shares one stream between them instead of opening another.

How long may the connection stay silent?

It is pinged every two seconds by default, and that interval is also the deadline for the answer. A peer that misses two intervals in a row loses the connection; the interval is a deployment setting, so it can be raised where the default is too quick for the machines involved.

How much can a stream's uplink hold?

262,144 bytes of frames by default. Over that, the stream fails with gateway/uplink-overflow and later items are dropped. Uplink items are never replayed, so anything that did not get through is lost.

Are forwarded events replayed after a reconnect?

One-way events are not: a notification missed while disconnected is gone. A request that is still waiting for an answer is different; it is sent again to the replacement connection so it can still be answered.

Which events can the client subscribe to?

A fixed list, twenty-five entries in the current set: session changes (added, removed, status, activity, branches and errors), preset selection, goal activation changes, model adapter updates, permission catalogue changes, scheduled-task changes, settings updates, and the client's own components (commands, credentials and plugins). An approval request and a user question are on the list as requests. A name outside the list is never forwarded.

What error does an aborted call settle as?

A cancelled failure, not a failure from the method: the message reads Remote invocation "<endpoint>" was aborted, and nothing further is kept for the answer.

How is the Remote API different from the Oda SDK?

They are different surfaces. The Remote layer connects the Oda client's own interface to the runtime it drives, as this page describes. The SDK is for a program of your own: a client process talks to a runtime over standard input and output, with the messages in the SDK wire protocol. Start from the Oda SDK overview, or read Automation clients for the serving profiles.