-
Notifications
You must be signed in to change notification settings - Fork 122
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
XEP-0491: Clarifications based on feedback
- Loading branch information
1 parent
283598c
commit aa1cc24
Showing
1 changed file
with
45 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,9 @@ | ||
| <?xml version='1.0' encoding='UTF-8'?> | ||
| <!DOCTYPE xep SYSTEM 'xep.dtd' [ | ||
| <!ENTITY xep-number "0491"> | ||
| <!ENTITY webxdc "<span class='ref'><link url='https://webxdc.org'>WebXDC</link></span>"> | ||
| <!ENTITY webxdc "<span class='ref'><link url='https://webxdc.org'>WebXDC</link></span> <note>WebXDC docs: <link url='https://webxdc.org/docs/'>https://webxdc.org/docs/</link></note>"> | ||
| <!ENTITY webxdcSendUpdate "<span class='ref'><link url='https://webxdc.org/docs/spec/sendUpdate.html'>WebXDC</link></span> <note>WebXDC sendUpdate: <link url='https://webxdc.org/docs/spec/sendUpdate.html'>https://webxdc.org/docs/spec/sendUpdate.html</link></note>"> | ||
| <!ENTITY webxdcaddrname "<span class='ref'><link url='https://webxdc.org/docs/spec/selfAddr_and_selfName.html'>WebXDC</link></span> <note>WebXDC selfAddr and selfName: <link url='https://webxdc.org/docs/spec/selfAddr_and_selfName.html'>https://webxdc.org/docs/spec/selfAddr_and_selfName.html</link></note>"> | ||
| <!ENTITY % ents SYSTEM 'xep.ent'> | ||
| %ents; | ||
| ]> | ||
|
|
@@ -19,11 +21,25 @@ | |
| <dependencies> | ||
| <spec>XMPP Core</spec> | ||
| <spec>XMPP IM</spec> | ||
| <spec>XEP-0335</spec> | ||
| <spec>XEP-0421</spec> | ||
| <spec>WebXDC</spec> | ||
| </dependencies> | ||
| <supersedes/> | ||
| <supersededby/> | ||
| <shortname>webxdc</shortname> | ||
| &singpolyma; | ||
| <revision> | ||
| <version>0.1.3</version> | ||
| <date>2024-10-17</date> | ||
| <initials>spw</initials> | ||
| <remark> | ||
| <ul> | ||
| <li>Clarifications and wording</li> | ||
| <li>Better references for WebXDC spec</li> | ||
| </ul> | ||
| </remark> | ||
| </revision> | ||
| <revision> | ||
| <version>0.1.2</version> | ||
| <date>2024-07-03</date> | ||
|
|
@@ -53,16 +69,25 @@ | |
| </revision> | ||
| </header> | ||
| <section1 topic='Introduction' anchor='intro'> | ||
| <p>&webxdc; is a specification for sharing interactive embeddable widgets built with web-like technologies (HTML, JavaScript) via a chat platform, and sharing state between participants in the chat without allowing external network connections. In order to use these, the host protocol must define a way to transmit the widgets and the associated state updates.</p> | ||
| <p>&webxdc; is a specification for sharing interactive embeddable widgets built with web-like technologies (HTML, JavaScript) via a chat platform, and sharing state between participants in the chat without allowing external network connections for the sandboxed web content. In order to provide support for &webxdc; widgets, the host protocol (XMPP in our case) must define a way to transmit these widgets and the associated state updates.</p> | ||
| </section1> | ||
| <section1 topic='Glossary' anchor='glossary'> | ||
| <p>This specification uses some terminology defined below:</p> | ||
| <ul> | ||
| <li>widget: the WebXDC widget delivered in a zip container as defined by &webxdc;</li> | ||
| <li>host application: the XMPP client embedding the widget</li> | ||
| <li>peer: the chat partner in a 1:1 chat or one of the participants of a &xep0045; or other group chat</li> | ||
| <li>host protocol: the protocol used by the peers to communicate (XMPP in our case)</li> | ||
| </ul> | ||
| </section1> | ||
| <section1 topic='Sending a Widget in a Message' anchor='send'> | ||
| <p>A widget may be attached to a message using any file-transfer mechanism supported by the client, such as &xep0066; or &xep0385;. The message MUST contain a <tt><thread/></tt> element with a new, unique id.</p> | ||
| <p>A widget may be attached to a message using any file-transfer mechanism supported by the client, such as &xep0066; or &xep0385;. The message MUST contain a <tt><thread/></tt> element with a new, unique id. Note: including multiple file-transfer mechanisms in the same message may be beneficial for broader compatibility.</p> | ||
| <example caption='An example of sending a widget'><![CDATA[ | ||
| <message to='[email protected]' type='chat'> | ||
| <thread>018fe972-ea89-7f4b-90f8-729b85b7f32d</thread> | ||
| <media-sharing xmlns='urn:xmpp:sims:1'> | ||
| <file xmlns='urn:xmpp:jingle:apps:file-transfer:5'> | ||
| <media-type>application/xdc+zip</media-type> | ||
| <media-type>application/webxdc+zip</media-type> | ||
| <name>Calendar</name> | ||
| <size>3032449</size> | ||
| <hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash> | ||
|
|
@@ -72,10 +97,13 @@ | |
| <reference xmlns='urn:xmpp:reference:0' type='data' uri='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/calendar.xdc /> | ||
| </sources> | ||
| </media-sharing> | ||
| <x xmlns='jabber:x:oob'> | ||
| <url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/calendar.xdc</url> | ||
| </x> | ||
| </message>]]></example> | ||
| </section1> | ||
| <section1 topic='Sending a State Update' anchor='state'> | ||
| <p>When a widget needs to communicate an update to other participants, this update may contain the following information:</p> | ||
| <p>When a widget needs to communicate an update to peers in a chat, this update may contain one or more of the following items as defined in &webxdcSendUpdate;.</p> | ||
| <table caption='Data transmitted with a WebXDC update'> | ||
| <tr> | ||
| <th>Item</th> | ||
|
|
@@ -98,7 +126,7 @@ | |
| <td>Arbitrary JSON serializable value</td> | ||
| </tr> | ||
| </table> | ||
| <p>These items, except for the info item, are delivered in a message which MUST have the same <tt><thread></tt> as the message which originally delivered the widget itself, as children of an element <tt><x xmlns="urn:xmpp:webxdc:0"></tt> as defined below.</p> | ||
| <p>These items are delivered in a message which MUST have the same <tt><thread></tt> as the message which originally <link url="#send">delivered the widget itself</link>. The stanza SHOULD contain a <tt>x</tt> child having the <tt>urn:xmpp:webxdc:0</tt> namespace, with these items (except for <tt>info</tt>) as children, as defined below.</p> | ||
| <section2 topic='The Info Item' anchor='info'> | ||
| <p>The info item is human-readable and is not needed by the widget itself, thus it is appropriate to transmit it anywhere that it might be visible to all participants, such as in a message body. If this is the only item present, an empty <tt><x></tt> element SHOULD still be included in the message to signal this update came from the widget.</p> | ||
| <example caption='An example of sending just info'><![CDATA[ | ||
|
|
@@ -131,13 +159,22 @@ | |
| </section2> | ||
| </section1> | ||
| <section1 topic='selfAddr' anchor='selfAddr'> | ||
| <p>WebXDC widgets get various data injected into them by the host application. One of these worth mentioning is the <tt>selfAddr</tt> property. When the chat is a 1:1 chat this property SHOULD be set to the XMPP URI for the local party's bare Jabber ID. When the chat supports &xep0421; this property SHOULD be set to the local party's occupant id.</p> | ||
| <p>&webxdcaddrname; widgets get various data injected into them by the host application. One of these worth mentioning is the <tt>selfAddr</tt> property.</p> | ||
| <ul> | ||
| <li>When the chat is a 1:1 chat this property SHOULD be set to the XMPP URI for the local party's bare Jabber ID e.g. <tt>xmpp:[email protected]</tt></li> | ||
| <li>When the chat supports &xep0421; this property SHOULD be set to the local party's <tt>occupant-id</tt>.</li> | ||
| <li>Note that no other type of chat is specified here, and especially that a &xep0045; chat without support for &xep0421; SHOULD NOT use full Jabber ID or room nickname for the property, as it may case inconsistent behaviour in some widgets when the user changes their nickname.</li> | ||
| </ul> | ||
| </section1> | ||
| <section1 topic='selfName' anchor='selfName'> | ||
| <p>The <tt>selfName</tt> property defined by &webxdcaddrname; is human readable and may be set to anything useful per that specification. It MAY be set to the local &xep0045; nickname or &xep0172; where relevant.</p> | ||
| </section1> | ||
| <section1 topic='Accessibility Considerations' anchor='access'> | ||
| <p>None</p> | ||
| </section1> | ||
| <section1 topic='Security Considerations' anchor='security'> | ||
| <p>This XEP does not have any specific security considerations, however it is assumed that it will be paired with an implementation of &webxdc; which requires very careful sandboxing.</p> | ||
| <p>It is assumed that an implementation of this XEP will be paired with an implementation of &webxdc;. Please see &webxdc; for sandboxing and security considerations for your WebXDC implementation.</p> | ||
| <p>This XEP does not introduce any specific security considerations besides those present in any &webxdc; implementation.</p> | ||
| </section1> | ||
| <section1 topic='Privacy Considerations' anchor='privacy'> | ||
| <p>It should be clear to users that their actions inside an embedded widget may be transmitted to other participants.</p> | ||
|
|
||