Module peer_channels

Peer channels for realtime communication in webxdcs.

We use Iroh as an ephemeral peer channels provider to create direct communication channels between webxdcs. See here for the webxdc specs.

Ephemeral channels should be established lazily, to avoid bootstrapping p2p connectivity when it’s not required. Only when a webxdc subscribes to realtime data or when a reatlime message is sent, the p2p machinery should be started.

Adding peer channels to webxdc needs upfront negotiation of a topic and sharing of public keys so that nodes can connect to each other. The explicit approach is as follows:

1. We introduce a new IrohGossipTopic message header with a random 32-byte TopicId, securely generated on the initial webxdc sender’s device. This message header is encrypted and sent in the same message as the webxdc application.
2. Whenever joinRealtimeChannel().setListener() or joinRealtimeChannel().send() is called by the webxdc application, we start a routine to establish p2p connectivity and join the gossip swarm with Iroh.
3. The first step of this routine is to introduce yourself with a regular message containing the IrohNodeAddr. This message contains the users relay-server and public key. Direct IP address is not included as this information can be persisted by email providers.
4. After the announcement, the sending peer joins the gossip swarm with an empty list of peer IDs (as they don’t know anyone yet).
5. Upon receiving an announcement message, other peers store the sender’s [NodeAddr] in the database (scoped per WebXDC app instance/message-id). The other peers can then join the gossip with joinRealtimeChannel().setListener() and joinRealtimeChannel().send() just like the other peers.

Structs

ChannelState 🔒

Single gossip channel state.

Iroh

Store iroh peer channels for the context.

Constants

PUBLIC_KEY_LENGTH 🔒

The length of an ed25519 PublicKey, in bytes.

PUBLIC_KEY_STUB 🔒

Functions

add_gossip_peer_from_header

Add gossip peer from Iroh-Node-Addr header to WebXDC message identified by instance_id.

create_iroh_header 🔒

Creates Iroh-Gossip-Header with a new random topic and stores the topic for the message.

create_random_topic 🔒

Creates a new random gossip topic.

get_iroh_gossip_peers 🔒

Get a list of [NodeAddr]s for one webxdc.

get_iroh_topic_for_msg 🔒

Get the topic for a given MsgId.

insert_topic_stub 🔒

Insert topicId into the database so that we can use it to retrieve the topic.

iroh_add_peer_for_topic 🔒

Cache a peers [NodeId] for one topic.

leave_webxdc_realtime

Leave the gossip of the webxdc with given MsgId.

send_webxdc_realtime_advertisement

Send a gossip advertisement to the chat that MsgId belongs to. This method should be called from the frontend when joinRealtimeChannel is called.

send_webxdc_realtime_data

Send realtime data to other peers using iroh.

subscribe_loop 🔒