From b66a9f1b797552590a4a4c9d2a5eeaf4c67f8000 Mon Sep 17 00:00:00 2001 From: Septias Date: Mon, 1 Apr 2024 17:43:50 +0200 Subject: [PATCH 1/4] add page --- src-docs/SUMMARY.md | 13 ++++++++----- src-docs/spec/sendEphemeralUpdate.md | 1 + 2 files changed, 9 insertions(+), 5 deletions(-) create mode 100644 src-docs/spec/sendEphemeralUpdate.md diff --git a/src-docs/SUMMARY.md b/src-docs/SUMMARY.md index a945103..ff7b8e9 100644 --- a/src-docs/SUMMARY.md +++ b/src-docs/SUMMARY.md @@ -3,16 +3,19 @@ - [Get Started](./get_started.md) - [Webxdc Specification](./spec/README.md) + - [Container file format (`.xdc`)](./spec/format.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) + - [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) - [Practical CRDT usage](./shared_state/practical.md) diff --git a/src-docs/spec/sendEphemeralUpdate.md b/src-docs/spec/sendEphemeralUpdate.md new file mode 100644 index 0000000..f756b02 --- /dev/null +++ b/src-docs/spec/sendEphemeralUpdate.md @@ -0,0 +1 @@ +hiiiiii \ No newline at end of file From e72ac9961984112a78e2254c15fff63ad230df0d Mon Sep 17 00:00:00 2001 From: Septias Date: Tue, 2 Apr 2024 10:08:30 +0200 Subject: [PATCH 2/4] more docs --- src-docs/SUMMARY.md | 5 ++--- src-docs/spec/ephemeralSideChannels.md | 10 ++++++++++ src-docs/spec/sendEphemeralUpdate.md | 10 +++++++++- src-docs/spec/setEphemeralUpdateListener.md | 14 ++++++++++++++ 4 files changed, 35 insertions(+), 4 deletions(-) create mode 100644 src-docs/spec/ephemeralSideChannels.md create mode 100644 src-docs/spec/setEphemeralUpdateListener.md diff --git a/src-docs/SUMMARY.md b/src-docs/SUMMARY.md index ff7b8e9..d9c8f4d 100644 --- a/src-docs/SUMMARY.md +++ b/src-docs/SUMMARY.md @@ -3,19 +3,18 @@ - [Get Started](./get_started.md) - [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) - [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) - [Practical CRDT usage](./shared_state/practical.md) diff --git a/src-docs/spec/ephemeralSideChannels.md b/src-docs/spec/ephemeralSideChannels.md new file mode 100644 index 0000000..b145426 --- /dev/null +++ b/src-docs/spec/ephemeralSideChannels.md @@ -0,0 +1,10 @@ +# Ephemeral side channels + +### WebXDC Ephemeral Channels API + +The WebXDC ephemeral API has two methods `sendEphemeralUpdate(payload: T)` and `setEphemeralUpdateListener((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. \ No newline at end of file diff --git a/src-docs/spec/sendEphemeralUpdate.md b/src-docs/spec/sendEphemeralUpdate.md index f756b02..f57de3b 100644 --- a/src-docs/spec/sendEphemeralUpdate.md +++ b/src-docs/spec/sendEphemeralUpdate.md @@ -1 +1,9 @@ -hiiiiii \ No newline at end of file +# 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. + +- `payload` any js object that can be given to `JSON.stringify` diff --git a/src-docs/spec/setEphemeralUpdateListener.md b/src-docs/spec/setEphemeralUpdateListener.md new file mode 100644 index 0000000..d65d2f5 --- /dev/null +++ b/src-docs/spec/setEphemeralUpdateListener.md @@ -0,0 +1,14 @@ +# 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 called for updates sent _only_ by other peers. + +- `payload`: + +Calling `setEphemeralUpdateListener()` multiple times is undefined behavior: in current implementations the callback is simply replaced. + +[`sendEphemeralUpdate()`]: ./sendEphemeralUpdate.html From 863632445e1b84bb192f83d08ca1a15fa011bd9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Kl=C3=A4hn?= Date: Tue, 9 Apr 2024 11:57:43 +0200 Subject: [PATCH 3/4] improve docs --- src-docs/spec/sendEphemeralUpdate.md | 2 +- src-docs/spec/setEphemeralUpdateListener.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src-docs/spec/sendEphemeralUpdate.md b/src-docs/spec/sendEphemeralUpdate.md index f57de3b..7fc9422 100644 --- a/src-docs/spec/sendEphemeralUpdate.md +++ b/src-docs/spec/sendEphemeralUpdate.md @@ -4,6 +4,6 @@ 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. +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` diff --git a/src-docs/spec/setEphemeralUpdateListener.md b/src-docs/spec/setEphemeralUpdateListener.md index d65d2f5..8a77512 100644 --- a/src-docs/spec/setEphemeralUpdateListener.md +++ b/src-docs/spec/setEphemeralUpdateListener.md @@ -5,7 +5,8 @@ window.webxdc.setEphemeralUpdateListener((payload) => {}); ``` With `setEphemeralUpdateListener()` you define a callback that receives the _ephemeral_ updates -sent by [`sendEphemeralUpdate()`](./setEphemeralUpdateListener.md). The callback is called for updates sent _only_ by other peers. +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`: From 18c9bf4992bc2f8282de0d67d559ee18e2e0c036 Mon Sep 17 00:00:00 2001 From: Septias Date: Wed, 10 Apr 2024 14:57:34 +0200 Subject: [PATCH 4/4] restructuring --- src-docs/SUMMARY.md | 5 ++-- src-docs/spec/ephemeralSideChannels.md | 10 ------- src-docs/spec/sendEphemeral.md | 9 ++++++ src-docs/spec/sendEphemeralUpdate.md | 9 ------ src-docs/spec/setEphemeralListener.md | 31 +++++++++++++++++++++ src-docs/spec/setEphemeralUpdateListener.md | 15 ---------- 6 files changed, 42 insertions(+), 37 deletions(-) delete mode 100644 src-docs/spec/ephemeralSideChannels.md create mode 100644 src-docs/spec/sendEphemeral.md delete mode 100644 src-docs/spec/sendEphemeralUpdate.md create mode 100644 src-docs/spec/setEphemeralListener.md delete mode 100644 src-docs/spec/setEphemeralUpdateListener.md diff --git a/src-docs/SUMMARY.md b/src-docs/SUMMARY.md index d9c8f4d..d165d8a 100644 --- a/src-docs/SUMMARY.md +++ b/src-docs/SUMMARY.md @@ -4,12 +4,11 @@ - [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) - - [sendEphemeralUpdate](./spec/sendEphemeralUpdate.md) - [setUpdateListener](./spec/setUpdateListener.md) - - [setEphemeralUpdateListener](./spec/setEphemeralUpdateListener.md) + - [sendEphemeral](./spec/sendEphemeral.md) + - [setEphemeralListener](./spec/setEphemeralListener.md) - [sendToChat](./spec/sendToChat.md) - [importFiles](./spec/importFiles.md) - [selfAddr & selfName](./spec/selfAddr_and_selfName.md) diff --git a/src-docs/spec/ephemeralSideChannels.md b/src-docs/spec/ephemeralSideChannels.md deleted file mode 100644 index b145426..0000000 --- a/src-docs/spec/ephemeralSideChannels.md +++ /dev/null @@ -1,10 +0,0 @@ -# Ephemeral side channels - -### WebXDC Ephemeral Channels API - -The WebXDC ephemeral API has two methods `sendEphemeralUpdate(payload: T)` and `setEphemeralUpdateListener((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. \ No newline at end of file diff --git a/src-docs/spec/sendEphemeral.md b/src-docs/spec/sendEphemeral.md new file mode 100644 index 0000000..8200b8c --- /dev/null +++ b/src-docs/spec/sendEphemeral.md @@ -0,0 +1,9 @@ +# sendEphemeral + +```js +window.webxdc.sendEphemeral(payload); +``` + +Send an ephemeral message to all peers. [setEphemeralListener](./setEphemeralListener.md) has to be called first to create a connection to at least on peer. See the documentation for [setEphemeralListener](./setEphemeralListener.md) to find out more. + +- `payload` any javascript object that can be given to `JSON.stringify` diff --git a/src-docs/spec/sendEphemeralUpdate.md b/src-docs/spec/sendEphemeralUpdate.md deleted file mode 100644 index 7fc9422..0000000 --- a/src-docs/spec/sendEphemeralUpdate.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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` diff --git a/src-docs/spec/setEphemeralListener.md b/src-docs/spec/setEphemeralListener.md new file mode 100644 index 0000000..c30144b --- /dev/null +++ b/src-docs/spec/setEphemeralListener.md @@ -0,0 +1,31 @@ +# setEphemeralListener + +```js +window.webxdc.setEphemeralListener((payload) => {}); +``` + +`setEphemeralListener` can be used to set a callback that receives the _ephemeral_ messages +sent by [`sendEphemeral`](./sendEphemeral.md). Ephemeral messages are messages that are delivered only to peers that are currently connected with a direct connection to the sender. These messages are not persisted and should thus only be used for unimportant synchronization like cursor positions and live game data. Members of a chat that are not currently connected will never receive these messages. +The `setEphemeralListener` function returnes a promise that resolves as soon as at least one peer is online. The completion of the promise thus signales that the connection is usable for message delivery. Messages that are send with [`sendEphemeral`](./sendEphemeral.md) before this promise resolves are discarded and will never reach any peer. + +- `payload`: Any json object deserialized by `JSON.parse`. + +Calling `setEphemeralListener()` multiple times is undefined behavior: in current implementations the callback is simply replaced. + + +## Example +```js +// stub implementation until the channel is ready +let sendGossip = () => { console.error("transport not ready") } + +window.webxdc.setEphemeralListener(function (message) { + console.log("Received ephemeral message: ", message); + /* Application code */ +}).then(() => { + // Replace `sendGossip` with proper implementation + sendGossip = () => { + console.log("New ephemeral message: ", msg); + window.webxdc.sendEphemeral(msg); + } +}); +``` \ No newline at end of file diff --git a/src-docs/spec/setEphemeralUpdateListener.md b/src-docs/spec/setEphemeralUpdateListener.md deleted file mode 100644 index 8a77512..0000000 --- a/src-docs/spec/setEphemeralUpdateListener.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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