feat: ephemeral peer channel

src-docs/SUMMARY.md

@@ -4,14 +4,16 @@
 
 - [Webxdc Specification](./spec/README.md)
   - [Container file format (`.xdc`)](./spec/format.md)
+  - [Ephemeral side channels](./spec/ephemeralSideChannels.md)
   - [Javascript API](./spec/api.md)
-      - [sendUpdate](./spec/sendUpdate.md)
-      - [setUpdateListener](./spec/setUpdateListener.md)
-      - [sendToChat](./spec/sendToChat.md)
-      - [importFiles](./spec/importFiles.md)
-      - [selfAddr & selfName](./spec/selfAddr_and_selfName.md)
+    - [sendUpdate](./spec/sendUpdate.md)
+    - [sendEphemeralUpdate](./spec/sendEphemeralUpdate.md)
+    - [setUpdateListener](./spec/setUpdateListener.md)
+    - [setEphemeralUpdateListener](./spec/setEphemeralUpdateListener.md)
+    - [sendToChat](./spec/sendToChat.md)
+    - [importFiles](./spec/importFiles.md)
+    - [selfAddr & selfName](./spec/selfAddr_and_selfName.md)
   - [Messenger implementations](./spec/messenger.md)
-
 - [Shared Web Application state](./shared_state/README.md)
   - [Detecting conflicts](./shared_state/conflicts.md)
   - [Theory of Conflict-free Replicated Data Types (CRDTs)](./shared_state/crdts.md)

src-docs/spec/ephemeralSideChannels.md

@@ -0,0 +1,10 @@
+# Ephemeral side channels
+
+### WebXDC Ephemeral Channels API
+
+The WebXDC ephemeral API has two methods `sendEphemeralUpdate<T>(payload: T)` and `setEphemeralUpdateListener<T>((payload: T) => void)` which allow one to explicitly send and receive data over an "ephemeral" channel. This data only has to be serializable by js. 
+
+Ephemeral channels provide a fast transport layer, ideally directly between machines collaborating on the same WebXDC app, improving performance significantly. The purpose of this is application state syncing for real time games or collaborative applications. It could for example be used to sync to display the cursor of all peers in an collaborative editor. The gossip layer should be much faster than normal messages but has the downside that messages are _not_ persist like regular WebXDC messages. WebXDC application developers need to explicitly handle persistence if desired (for example by sending regular messages), but ideally only use ephemeral channels for non-critical data.
+
+### Iroh
+DeltaChat uses the ephemeral-channel provider [Iroh](https://iroh.computer/), which attempts to establish direct p2p connections between peers (QUIC), using PlumTree as a gossiping protocol for efficient peer sampling. Iroh falls back to relay nodes when a direct connection can not be established. Even a relayed connection is faster than sending single WebXDC messages via mail. 

src-docs/spec/sendEphemeralUpdate.md

@@ -0,0 +1,9 @@
+# sendEphemeralUpdate
+
+```js
+window.webxdc.sendUpdate(payload);
+```
+
+Send an ephemeral update to all peers. [setEphemeralUpdateListener](./setEphemeralUpdateListener.md) has to be called first in order to join the gossip swarm and make it operational. Only after the promisle from [setEphemeralUpdateListener](./setEphemeralUpdateListener.md) resolves, the sent updates are able to reache a peer.
+
+- `payload` any js object that can be given to `JSON.stringify`

src-docs/spec/setEphemeralUpdateListener.md

@@ -0,0 +1,15 @@
+# setEphemeralUpdateListener
+
+```js
+window.webxdc.setEphemeralUpdateListener((payload) => {});
+```
+
+With `setEphemeralUpdateListener()` you define a callback that receives the _ephemeral_ updates
+sent by [`sendEphemeralUpdate()`](./setEphemeralUpdateListener.md). The callback is _only_ called for updates sent by other peers.
+The returned promise resolves as soon as at least one peer connection is established, making the swarm operational. Sending updates before this will not result in a hard error, but these messages will never arrive anywhere.
+
+- `payload`:
+
+Calling `setEphemeralUpdateListener()` multiple times is undefined behavior: in current implementations the callback is simply replaced.
+
+[`sendEphemeralUpdate()`]: ./sendEphemeralUpdate.html