Next: Prelay Utils, Previous: WebSocket, Up: Netlayers [Contents][Index]
The purpose of the prelay netlayer is to permit connections between two parties which cannot feasibly directly connect. For instance, some users may be able to feasibly connect unidirectionally via the TCP + TLS netlayer to a “public” peer, but may not be themselves reachable over a consistent IP address. For this reason, the Prelay netlayer exists.
The surprising thing about the Prelay netlayer is that it is a netlayer which runs *over another netlayer* by passing messages through an intermediate object, which itself speaks to other intermediate objects routing to other likely isolated users, bridging those users with the illusion of being direct peers. (The users need not use relays on the same peer; “federation” is achieved automatically through the underlying OCapN netlayer’s connectivity properties.)
The primary limitation of the prelay netlayer at present is that messages are delivered in cleartext through the chosen relay, unauthenticated, which means the relay has the power to both snoop on and modify messages. A fully end-to-end-encrypted Relay netlayer is on schedule to replace the present unencrypted, unauthenticated design. At present the prelay netlayer has characteristics similar to IRC, vanilla ActivityPub, and many multiplayer game systems which also tend to rely on trusting a provider, but we would like to (and will!) do better in the future.
Some simpler APIs for the prelay netlayer are coming, particularly a convenient daemon for managing prelay peers for users.
In the meanwhile, there are two essential APIs. The first is run on relay peers, which act as the routers:
Spawn a pair of prelay objects: the endpoint (public) and controller (private). The endpoint permits other peers to send messages, and the controller permits sending messages to other peers.
enliven is a object which when provided the 'enliven method and a
sturdyref, returns a promise to the object. This is likely created by using
the See Facet library with the MyCapN object.
Returns two values to its continuation, the endpoint and controller respectively.
In order for the endpoint to be useful as a public identity, a sturdyref must be made for it and then converted with the following procedure:
This transforms prelay-endpoint-sref into an OCapN prelay peer
identifier and returns that object and identifies this peer on the
network. (This is done by transforming and serializing relevant
information about the sturdyref into a data structure that is then
packed into the ocapn-peer-designator object, but this detail
is not particularly important for most users.)
This transformation can be reversed with the following procedure:
Do the reverse of prelay-sturdyref->prelay-peer, which is to say, transform the peer back into a sturdyref which represents the endpoint which handles routing messages for this peer.
Whew, that’s a lot! The above procedures are essential for setting up prelay-as-relay-host infrastructure, but setting up a prelay-using netlayer is much simpler:
Constructs the prelay netlayer which lives on the client.
Takes three arguments. Two of these arguments are sturdyrefs to objects which
likely live on the prelay server and their refrs were created by the
spawn-prelay-pair procedure defined above.
The three arguments are:
'enliven message with a
sturdyref, returns a promise to a remote object. This is likely created by
using the See Facet library with the MyCapN object.
Next: Prelay Utils, Previous: WebSocket, Up: Netlayers [Contents][Index]