Remote methods and streams

An extension package can expose methods that code on the other side of the boundary between the host and its clients calls directly. Mark the method as Remote, bind its owner to a service, and the runtime carries calls, streams and cancellation between the two sides. This page is the reference for that model: the authoring walkthrough is on Remote calls for extension authors, the wire messages are on The Oda Remote API, and what a build generates for such a package is on Plugin artifacts and the catalog.

Mark a method as Remote

Four markers exist, written on the method itself in TypeScript:

• Public instance methods only. 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.
• One marker per method. Two markers that disagree on one method fail with Remote method "<method>" has conflicting invocation markers.
• 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". Use the plain or named marker for a method that does not stream.
• Parameters are plain bindings. Rest parameters, default values and destructured bindings are 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 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.
• The descriptor. The markers record one descriptor on the class: frozen, non-enumerable, and carrying a version, currently 1. Markers read back in declaration order, and a descriptor under another version is refused.
• The binding is frozen. Binding validates the service key and the namespace first, and the record it produces (the service, its key and its namespace) is frozen.

What a call carries

• The invocation context. Inside a Remote method, ctx.invocation describes the call in progress: the request it belongs to (its namespace, its method and the arguments as received), the service it reached, the peer that made it and the signal. Outside a Remote call the same property reads as undefined.
• Cancellation is injected. Declare a final signal: AbortSignal parameter to cooperate with cancellation; the runtime provides the signal, and it never travels as a call argument. React to it to stop your work when the caller goes away.

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 yielded item travels on the logical stream as the method produces it, so a caller sees items while the method still runs.
• 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 cancels the stream and ends the caller's iteration.
• Items wait for the open. An item the caller sends before the stream has opened is queued and sent once the stream opens.
• 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. When the caller breaks out of the item loop early, the stream is cancelled, and items that were never read are dropped rather than delivered later.
• One handle, one connection. A handle stands for one connection generation: when the connection is lost, iteration fails with the connection error and the handle is finished; start the call again for a new stream.

Results and failures

• The result envelope. A call answers with { ok: true, value } on success or { ok: false, error } on failure.
• One failure class. Failures come as one RemoteError class carrying a stable code of the form <domain>/<reason>.
• The universal codes. gateway/bad-request when the request 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 class. Tell failures apart by their code, never by an instance check on the error's class.
• Binary only in a unary result. Binary data (Uint8Array) may cross only as a single result of a unary call, directly or nested inside it; parameters and stream items stay JSON only.
• One value rule set everywhere. The same lossless checks cover clients, gateways and mocks, so a value that cannot round-trip unchanged is refused wherever it crosses. The accepted and refused value sets are listed on Remote calls for extension authors.

How things are named

• Endpoint. A call is addressed by its endpoint, <namespace>/<method>; a registered invocation carries the full id <package>#<namespace>/<method>.
• Schema key. A generated schema is addressed as <package>#<name>.
• Package key. The generated contribution of one package is keyed per side as <package>#<side>, where the side 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 a # is refused inside a name because # separates the package part of an identity; a name outside the set is refused with must contain only RPC endpoint segment characters.

Questions, answered

What do the different key formats mean?

Each key points at a different thing. An endpoint addresses one callable as <namespace>/<method>, and a registered invocation carries the full id <package>#<namespace>/<method>. A generated schema is addressed as <package>#<name>, and one package's contribution per side as <package>#<side>; the # marks where the package part ends.

Is a marker stored on the class or on each instance?

On the class. The markers record one descriptor on the class, frozen and non-enumerable, and instances read it from there; the class declares its callable surface once, and the markers read back in declaration order.

What does the invocation context carry?

Inside a method, ctx.invocation carries the request the call made (its namespace, its method and the arguments as received), the service it reached, the peer that made the call and the cancellation signal. Outside a Remote call the property reads as undefined.

Do stream items arrive as they are produced?

Yes. Each item travels on the stream as the method produces it, so the caller sees items while the method still runs. There is no wait for the method to finish.

What happens to an open stream when the connection drops?

A handle stands for one connection generation. When the connection is lost, iteration fails with the connection error and the handle is finished; start the call again for a new stream.

What does a refused request's failure tell me?

When a call does not satisfy the endpoint, it fails with gateway/bad-request. That failure can carry an issues list describing what was wrong, so read it before you retry.

Why did my second marker fail?

A method takes one marker. A second marker that disagrees with the first fails with Remote method "<method>" has conflicting invocation markers; keep the single marker that says how the method is called and remove the other.

Why did my send() call throw?

send throws when the item is not a lossless JSON value, when the uplink has already been ended, or when the stream has terminated. Nothing is delivered when it throws, so fix the value or stop sending to an ended or finished stream.