Remote APIs

A plugin package can expose methods that code on the other side calls directly across the boundary between the host and its clients: mark the method as Remote, bind its owner to a service, and the runtime carries the calls, the streams and the cancellation between the two sides. This page is the authoring reference for that layer: how methods are declared and bound, what a call carries and returns, and the value and naming rules every call is validated against.

The end-to-end walkthrough of the same model is on Remote calls for extension authors; the messages a running client exchanges with the host are on The Oda Remote API; and what a build generates for a Remote-capable package is on Plugin artifacts and the catalog.

Mark a method as Remote

Markers are written in TypeScript on the method itself:

• Method shape. A marker needs a public, non-static instance method with a string name and a concrete implementation; private or static methods, methods without an implementation and generic methods are refused, with Remote decorators require a public instance method with a string name.
• One marker per method. Two markers that disagree about one method fail with Remote method "<method>" has conflicting invocation markers; keep the single marker that says how the method is called.
• The stream option is exact. A stream marker's options object must be exactly { mode: 'stream' }; anything else fails with Remote options must contain exactly mode: "stream".
• Parameters are plain named bindings. A rest parameter, a destructured binding or a default value is refused, so a call carries exactly the arguments the method declares. A parameter written as T | undefined still counts as required; only an optional parameter may be left out of a call.

Bind the marked methods to a service

A marked method becomes callable once its owner is bound:

• A service base class. A class that extends the runtime's service base class binds its marked methods when it is constructed.
• A bind helper. An instance that does not extend the base class can be bound with a bind helper that takes the service key and, optionally, a namespace.
• One descriptor. The markers record one descriptor on the class: frozen, non-enumerable and carrying a version, currently 1. A descriptor under another version is refused, and the markers read back in declaration order.
• The binding is validated. Binding checks the service key and the namespace before it records them, and a second binding of the same service is refused.

What a call carries

• The invocation context. Inside a Remote method, ctx.invocation describes the call in progress: the service it reached, the peer that made it and the signal. Outside a Remote call the property reads as undefined.
• Cancellation arrives by injection. A method opts into cooperative cancellation by declaring signal: AbortSignal as its final parameter; the runtime injects the signal, and it never travels as a sent argument.

Streaming calls

• Declaration. A streaming method is declared with @Remote({ mode: 'stream' }) and returns an Iterable<Out>, an AsyncIterable<Out> or a RemoteStream<Out, In>; each item travels on the logical stream as the method produces it. Another return shape, a promise included, is refused with stream Remote methods must return Iterable<Out>, AsyncIterable<Out>, or RemoteStream<Out, In>.
• The caller's handle. On the calling side, a streaming call is a handle with send(item), end() and dispose(): send adds one item to the caller's side of the stream, end half-closes it so no further items follow, and dispose releases the handle when the caller is done.
• Items wait for the open. An item the caller sends before the stream has opened is queued, not lost.
• The uplink is read once. The method reads the caller's items through ctx.invocation.uplink(); it is available once per call, and asking for it a second time throws.
• Leaving early cancels. A caller that leaves the item loop early cancels the stream, and items that were never read are dropped rather than delivered later.

Results and failures

• The result envelope. A call answers with { ok: true, value } on success or { ok: false, error } on failure.
• One failure type. Failures come as one RemoteError carrying a stable code of the form <domain>/<reason>.
• The universal codes. gateway/bad-request when the call does not satisfy the endpoint, and that failure can carry an issues list describing what was wrong; gateway/cancelled when the call was cancelled; and gateway/internal for a failure the layer could not classify.
• By code, never by a class check. Failures are recognised structurally, not by their class, so one that arrived across a bundle boundary still reads correctly; branch on the code.

Values that cross

• Lossless JSON only. Every argument, result, event payload and stream item must round-trip unchanged: null, strings, booleans, finite numbers, plain objects with enumerable fields and dense arrays all cross.
• What is refused. NaN, infinities, -0, class instances and other non-plain objects, symbol keys, non-enumerable fields, sparse arrays and cycles are refused wherever they would cross.
• One exception for items. An uplink item may omit its value at the top level: an item sent as undefined crosses without one, while nested undefined, NaN and infinities stay refused.
• Bytes only in a unary result. Uint8Array data crosses only as the single result of a unary call, directly or nested inside it; parameters, events and stream items stay JSON-only, and another use is refused with Remote Uint8Array is only supported in unary results.
• Released exactly once. A value can cross as invocation-owned: the invocation releases it at most once, the release never throws, and repeating the release is harmless.

How calls and schemas are named

• Endpoint. A call is addressed by its endpoint, <namespace>/<method>; a registered invocation carries the full id <package>#<namespace>/<method>.
• Schema and package keys. A generated schema is addressed as <package>#<name>, and a package's contribution per side as <package>#<face>, where the face is host or client.
• The segment grammar. Every segment of a call name (a namespace, a method, an export name, a service key or a scope key) may contain only letters, digits, _, $, . and -. A lone . or .. is refused, and # is refused inside a name because it separates the package part of an identity; a name outside the set is refused with <subject> must contain only RPC endpoint segment characters.

Questions, answered

Can a private or static method be marked as Remote?

No. A marker needs a public, non-static instance method with a string name and a concrete implementation; private or static methods, methods without an implementation and generic methods are refused, with Remote decorators require a public instance method with a string name. Mark a public instance method instead.

How do I export a Remote method under a different name?

Write the name in the marker: @Remote('name') exports the call under name while the method keeps its own name on the class. A context-scoped marker takes an optional second name for the call the same way, as in @RemoteScope('context', 'name').

Why are rest parameters and default values refused?

The layer keeps a call to exactly what the method declares, and only plain named bindings can be declared: a rest parameter, a destructured binding or a default value is refused. Write the parameters out one by one, and make a parameter optional where a call may leave it out; a parameter written as T | undefined still counts as required.

Why must the signal parameter be last?

Because the signal is injected, not sent: the runtime provides it at call time, and the check requires the declaration to end with it, refusing anything else with cancellation signal must be the final parameter. Declare signal: AbortSignal as the method's last parameter and react to it when the caller goes away.

Can a stream method return a promise?

No. A streaming method must return an Iterable<Out>, an AsyncIterable<Out> or a RemoteStream<Out, In>; anything else, a promise included, is refused with stream Remote methods must return Iterable<Out>, AsyncIterable<Out>, or RemoteStream<Out, In>.

May an uplink item cross without a value?

Yes, at the top level only. An item sent as undefined crosses as an item with no value; nested undefined, NaN and infinities inside an item stay refused.

What is the difference between a direct call and a scoped call?

A direct call reaches the method on the bound service, under its own name or the name the marker gave it. A scoped call, declared with @RemoteScope('context'), takes its receiver from the named context instead, with an optional second name for the call; the same segment rules apply to the context key and the name.

Which values cannot cross the boundary?

The refused set is shared on every side: NaN, infinities, -0, class instances and other non-plain objects, symbol keys, non-enumerable fields, sparse arrays and cycles. What crosses is null, strings, booleans, finite numbers, plain objects with enumerable fields and dense arrays; bytes cross only as the single result of a unary call.

Why should I check the failure code instead of using instanceof?

Because an instance check does not survive a bundle boundary: a failure is recognised structurally, not by its class, and discrimination is always by the code. Read the stable <domain>/<reason> code and branch on that.

Which failure codes belong to the layer itself?

Three are universal: gateway/bad-request when a call does not satisfy the endpoint, and it can carry an issues list describing what was wrong; gateway/cancelled when the call was aborted; and gateway/internal for a failure the layer could not classify.