Multi-home peers

A standard OCapN locator names one transport and one designator. A program that listens on two transports therefore looks like two separate peers. A saved reference, or sturdyref, written for one of them works only over that path.

glowcap’s id locator names the peer by its durable public key and lists its routes as hints. A sturdyref using that locator can reach the same peer through any of its authenticated routes.

This is a glowcap-next extension. OCapN does not define these wire names. Wire format describes how they are negotiated.

One peer, several routes

An id locator puts the peer’s durable public key in the designator and bundles routes over actual transports. Dialing tries those routes in order. The channel must prove that the peer holds the key named by the locator.

Dialing one multi-home peer: the first route is down, so the dial moves on, and the next route’s channel proves the key. The peer is whoever proves the key. The weak fallback can carry a signed gift, never the identity.

The routes are written into two hints on a single ocapn:// URI. Each route is itself a locator, percent-encoded inside the hint and separated by |. Decoded for reading, the shape is:

ocapn://<durable key>.id?via=<route>|<route>&alt-locators=<route>

The via hint lists the strong routes, the ones where something besides the address vouches for the durable key:

  • iroh authenticates its node id in the QUIC handshake.
  • The Noise paths prove the dialed key while sealing the stream.
  • WebRTC relies on its signaling service to vouch for the peer, so it is as strong as your trust in that service.

A cleartext keyed route is not strong, because its key is only an address to dial and nothing proves it.

The alt-locators hint lists weak fallbacks, such as a plain socket or an onion address. Tor proves an onion service only to the side that dials it, so an onion route cannot prove a peer in both directions. A weak route can complete one handoff that a signed gift already authorized, and nothing more. It never establishes the peer’s identity, it never enters the identity cache, and a sturdyref never dials it.

Each list is capped in length, and the two together have a small size limit. Every via route must name the same key as the designator, so an untrusted locator cannot cause unbounded work or slip in a second identity.

What the other peer sees

Peers offer multi_location in the signed location hints of op:start-session, the message that opens a session. Both must offer it and agree on glowcap-next before using id locators. The first hello uses one concrete transport address because the peer’s support is not yet known.

The decision is made per session. One process can use routes with another glowcap host while its session with a Spritely Goblins vat stays on the standard version and sees the same wire whether or not multi-homing is in use.

A negotiated partner receives the id bundle intact. A baseline partner gets one concrete route it can dial, with the private vocabulary stripped, and when no such route exists the give is refused before anything is sent.

A handoff can cross between those two kinds of session, because a signed give travels from the session with the object’s host to the recipient’s. The give keeps its routes only when both sessions negotiated multi_location. Otherwise glowcap gives the recipient one concrete route on a transport that recipient is known to use, with the private fields removed. If no such route exists, glowcap refuses the give before sending anything.

Sturdyrefs that survive a transport change

A sturdyref written against an id locator names the peer’s key. It can use any reachable strong route listed in that locator. On a Host that has opted into multi_location, redemption works like this:

  1. If a session already exists whose channel proved that key, on any transport, the Host reuses it.
  2. Otherwise it tries the strong via routes, a few at a time, in the order the publisher listed them. When one attempt fails, it starts the next route on the list. The first channel that proves the key carries the fetch, and the other dials are cancelled.
  3. If every strong route fails, redemption fails. Weak fallbacks are reserved for a signed gift handoff and cannot redeem a sturdyref.

The multi-home route diagrams show route selection, handoffs, and redemption.

Rooms uses it

Directory peering in Rooms uses multi-homing. A Rooms server started with --capabilities=peering can list one of its durable rooms in another Rooms server’s directory, the list of rooms people find there, under a single id locator. Its iroh and Noise listeners, which prove the key, go under via. Its onion and plain socket listeners go under alt-locators as weak fallbacks.

Each reader then joins the room over whichever path that reader can open, so the listing does not pick one transport for everyone. The listing belongs to the publisher’s session with that directory. Revoking or disconnecting it removes the room from the directory, but a room already handed to a reader stays live.

Wire format

The multi-home wire format is a glowcap-next extension. Peers that do not negotiate it never see these route hints.