Connections

Everything in osra happens over connections.
A connection is what a pair of expose() calls establish over a transport: each side sends its value across, each side gets the other’s back, and every call, stream and promise between them rides on that connection afterwards.

expose() gives you back its connections in two ways.
Awaiting the result gives you the first one, and iterating it gives you every one as it arrives:

const remote = await expose<Api>({}, { transport: worker })

for await (const remote of expose<Api>({}, { transport: worker })) {
  remote.ping()
}

By default, what you get is the peer’s exposed value, which is what expose() has always resolved to.
The connection option lets you change that.

How a connection is made

A connection starts with a handshake, and the handshake needs traffic in both directions.
This means that the transport must be able to both emit and receive: if you pass half a transport, only the emit side of a custom pair for example, expose() rejects immediately with an error telling you so.

Every expose() call generates a random uuid for itself.
Until it has its first connection, it announces that uuid on the transport, retrying with a backoff that starts at 50ms and doubles up to once per second.
This is what lets you expose() toward an iframe that hasn’t finished loading, or a worker that starts late: whoever comes up first just keeps knocking until the other side answers.

A side that hears an announce answers with an announce of its own, addressed to that uuid.
Once the two sides know each other’s uuid, each one sends a single init message carrying its exposed value.
Your expose() promise resolves when the peer’s init arrives and its value has been revived, so what you get is ready to call.

If nobody ever answers, the promise stays pending.
Errors and lifecycle covers the cases where it rejects instead, and how to put a deadline on it.

One thing to note is that your own value is built and serialized as part of that init message.
This is why a context() factory runs before anything reaches the peer.

Osra never reconnects on its own.
Once your side has a connection it stops announcing, but it keeps listening, so a new peer that announces later on the same channel still connects to you.
And if a connection goes away, calling expose() on the same transport again starts a fresh handshake, a teardown does not poison the transport, see errors and lifecycle.
This matters mostly for WebExtension MV3 service workers, which the platform unloads on its own schedule, the transports page covers reconnecting there.

Keep in mind that a transport is a channel, not a connection.
Several independent expose() calls can share one channel under different keys, and a single expose() can hold several peers at once, see multiple peers.

Choosing what a connection is

The connection option receives { value, context } and returns whatever a connection should mean in your code:

const { value, context } = await expose({}, {
  transport: worker,
  connection: ({ value, context }) => ({ value, context })
})

Since it is a plain function, it can return anything you like, for example just the one field you care about:

for await (const origin of expose({}, {
  transport: child,
  connection: ({ context }) => context.origin
})) {
  origin // string | undefined
}

It runs on your side, once per connection, after the handshake finishes.
It cannot change what you send, and nothing it returns ever crosses the wire.

What is in the context

The context only contains what the transport actually observed about the peer, plus an abort() for that one connection.
Each field is only there when the browser actually set it:

Transport	Context
Window, iframe	abort, origin, source
WebExtension	abort, port, sender
WebSocket	abort, origin
MessagePort, Worker, SharedWorker	abort

One thing to remember is that a port or a worker observes nothing about its peer: their messages arrive with an empty origin and a null source, so neither field survives.
This is fine in practice, a server handing out ports created each port in response to something that did know who was asking, so the identity is already in scope where you call expose().

Also keep in mind that a WebSocket’s origin is the origin of the socket’s URL, not the peer’s.
Every peer on the same relay reports the same one, so identify relay peers with key, name, or something in your own payload instead.

Nothing in the context is ever sent anywhere, and nothing the peer sends can reach it.
It is built purely from what the browser told your side about the delivery.

A different value per peer

Wrap your value in context() and it is built once per connection, from that connection’s context, instead of being one object shared by everyone:

expose(context(({ origin }) => ({ read: readFor(origin) })), { transport: child })

The factory runs before your value is boxed and sent, which is what makes it useful: a page embedded by several iframes can answer each one differently, rather than exposing one object to all of them.

One thing to note is that this is a wrapper rather than “just pass a function”, because osra exposes functions as endpoints.
A bare function is a value you are exposing, not a factory:

expose(async (n: number) => n * 2, { transport: worker }) // an endpoint, called by the peer

The factory and connection receive the same context object, so anything your connection function needs, it can derive by itself.

Dropping one peer

Calling context.abort() closes that one connection and leaves every other peer alone.
unregisterSignal is still the way to tear down your whole side, see errors and lifecycle.

for await (const peer of expose({}, {
  transport: child,
  connection: ({ value, context }) => ({ value, context })
})) {
  if (!allowed(peer.context.origin)) peer.context.abort?.()
}

If you call it from inside a context() factory instead, the peer is refused before your value is ever sent, and the peer’s own expose() rejects:

expose(
  context(ctx => {
    if (!allowed(ctx.origin)) ctx.abort?.()
    return resolvers
  }),
  { transport: child }
)

Every loop sees every peer

Several for await loops over one expose() result each get every connection.
They are independent readers rather than a shared queue, so one loop cannot consume a peer another loop was waiting for.

Peers that connect before anything iterates are buffered, up to the 32 most recent, and that buffer is replayed to every loop that starts afterwards.
This also bounds what a side that only ever awaits holds on to: at most those 32, no matter how many peers show up.

One thing to note is that the replay only covers peers that arrived while nothing was iterating.
A loop that starts while another one is already running gets that buffer plus every peer from the moment it starts, not what the first loop already received.

Typing it

With no connection option, expose<Api>() types the result as Remote<Api>.
With one, the result type is inferred from whatever your function returns.

One thing to remember is that those two cannot be combined, because TypeScript has no partial type argument inference: passing <Api> explicitly makes every later type parameter fall back to its default, so the inferred result type is lost.
If you want both, type the peer on the function’s parameter instead, using the Connected and Remote types osra exports:

const { value, context } = await expose({}, {
  transport: worker,
  connection: ({ value, context }: Connected<Remote<Api>>) => ({ value, context })
})

await value.ping()