-
Notifications
You must be signed in to change notification settings - Fork 121
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
XEP-0478: Add the XML Schema, and make both children optional
- Loading branch information
Showing
1 changed file
with
60 additions
and
18 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 |
|---|---|---|
|
|
@@ -27,6 +27,18 @@ | |
| <jid>[email protected]</jid> | ||
| </author> | ||
| &mwild; | ||
| <revision> | ||
| <version>0.2.0</version> | ||
| <date>2024-08-02</date> | ||
| <initials>egp</initials> | ||
| <remark> | ||
| <ul> | ||
| <li>Add the XML Schema.</li> | ||
| <li>Clarify that both children can be optional.</li> | ||
| <li>Fix indentation and one typo.</li> | ||
| </ul> | ||
| </remark> | ||
| </revision> | ||
| <revision> | ||
| <version>0.1.0</version> | ||
| <date>2023-05-04</date> | ||
|
|
@@ -46,7 +58,7 @@ | |
| <p>This documents describes a mechanism for communicating limits, such as stanza size limits that is in effect on a particular stream, in order to allow the sending party to avoid reaching those limits.</p> | ||
| <section2 topic='Problem statement' anchor='intro-problem'> | ||
| <p>Where stanza size limits have been deployed, very often this leads to problems with large stanzas causing connection outages, most often &xep0084; and &xep0053; result stanzas, which can be very large due to embedded images.</p> | ||
| <p>If stanza size limit violations are met with stream errors then this may lead to temporary connection outage, which may a few seconds to recover from.</p> | ||
| <p>If stanza size limit violations are met with stream errors then this may lead to temporary connection outage, which may take a few seconds to recover from.</p> | ||
| </section2> | ||
| </section1> | ||
| <section1 topic='Requirements' anchor='reqs'> | ||
|
|
@@ -58,19 +70,19 @@ | |
| </section1> | ||
| <section1 topic='Use Cases' anchor='usecases'> | ||
| <section2 topic='Server advertises limits to connecting entity' anchor='advertise'> | ||
| <p>For any XMPP stream, there is an "initiating entity" (a client or server) and a "responding entity" that they are connecting to. The responding entity advertises its limits in the <stream:features/> element that it sends at the start of the stream.</p> | ||
| <p>The limits are enclosed in a <limits/> element qualified by the 'urn:xmpp:stream-limits:0' namespace. This element SHOULD contain the following child elements:</p> | ||
| <dl> | ||
| <di> | ||
| <dt><max-bytes/></dt> | ||
| <dd>Contains an integer representing the maximum size of any first-level stream elements (including stanzas), in bytes the announcing entity is willing to accept. Guidance on acceptable limits is provided in &rfc6120; section 13.12.</dd> | ||
| </di> | ||
| <di> | ||
| <dt><idle-seconds/></dt> | ||
| <dd>Contains an integer representing the number of seconds without any traffic from the iniating entity after which the server may consider the stream idle, and either perform liveness checks (using e.g. &xep0198; or &xep0199;) or terminate the stream. Guidance on handling idle connections is provided in &rfc6120; section 4.6.</dd> | ||
| </di> | ||
| </dl> | ||
| <example caption='Advertising limits to connecting entity'><![CDATA[ | ||
| <p>For any XMPP stream, there is an "initiating entity" (a client or server) and a "responding entity" that they are connecting to. The responding entity advertises its limits in the <stream:features/> element that it sends at the start of the stream.</p> | ||
| <p>The limits are enclosed in a <limits/> element qualified by the 'urn:xmpp:stream-limits:0' namespace. This element MAY contain the following child elements:</p> | ||
| <dl> | ||
| <di> | ||
| <dt><max-bytes/></dt> | ||
| <dd>Contains an integer representing the maximum size of any first-level stream elements (including stanzas), in bytes the announcing entity is willing to accept. Guidance on acceptable limits is provided in &rfc6120; section 13.12. If the responding entity is unable to determine its limits, this child can be absent.</dd> | ||
| </di> | ||
| <di> | ||
| <dt><idle-seconds/></dt> | ||
| <dd>Contains an integer representing the number of seconds without any traffic from the iniating entity after which the server may consider the stream idle, and either perform liveness checks (using e.g. &xep0198; or &xep0199;) or terminate the stream. Guidance on handling idle connections is provided in &rfc6120; section 4.6. If the responding entity is unable to determine its limits, this child can be absent.</dd> | ||
| </di> | ||
| </dl> | ||
| <example caption='Advertising limits to connecting entity'><![CDATA[ | ||
| <stream:features> | ||
| <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> | ||
| <mechanism>SCRAM-SHA-1</mechanism> | ||
|
|
@@ -81,18 +93,18 @@ | |
| <idle-seconds>1800</idle-seconds> | ||
| </limits> | ||
| </stream:features> | ||
| ]]></example> | ||
| ]]></example> | ||
| </section2> | ||
| <section2 topic='Connecting server announces limits on bidirectional stream' anchor='advertise-bidi'> | ||
| <p>Servers using &xep0288; to establish a bidirectional stream with another server do not get an opportunity to send <stream:features/> to the responding entity. For a server to advertise the limits about what it is willing to accept on such a stream, the <limits/> element can be included in the <bidi/> element.</p> | ||
| <example caption='Advertising limits to responding entity over bidirectional stream'><![CDATA[ | ||
| <example caption='Advertising limits to responding entity over bidirectional stream'><![CDATA[ | ||
| <bidi xmlns='urn:xmpp:bidi'> | ||
| <limits xmlns="urn:xmpp:stream-limits:0"> | ||
| <max-bytes>10000</max-bytes> | ||
| <idle-seconds>1800</idle-seconds> | ||
| </limits> | ||
| </bidi> | ||
| ]]></example> | ||
| ]]></example> | ||
| </section2> | ||
| </section1> | ||
| <section1 topic='Business Rules' anchor='rules'> | ||
|
|
@@ -129,6 +141,36 @@ | |
| <p>The ability for a client to announce limits on what it will receive on a client-to-server stream is deliberately not provided by this specification. This vastly simplifies discovery of the maximum limits between any two JIDs, and it avoids situations where the server is unable to deliver incoming stanzas to some or all of an account's connected clients. Clients will already be protected from denial-of-service through excessive stanza sizes due to the server's own limits.</p> | ||
| </section1> | ||
| <section1 topic='XML Schema' anchor='schema'> | ||
| <p>TBD.</p> | ||
| <code><![CDATA[ | ||
| <?xml version='1.0' encoding='UTF-8'?> | ||
| <xs:schema | ||
| xmlns:xs='http://www.w3.org/2001/XMLSchema' | ||
| xmlns='urn:xmpp:stream-limits:0' | ||
| targetNamespace='urn:xmpp:stream-limits:0' | ||
| elementFormDefault='qualified'> | ||
| <xs:annotation> | ||
| <xs:documentation> | ||
| The protocol documented by this schema is defined in | ||
| XEP-0478: https://xmpp.org/extensions/xep-0478.html | ||
| </xs:documentation> | ||
| </xs:annotation> | ||
| <xs:element name='limits'> | ||
| <xs:complexType> | ||
| <xs:sequence> | ||
| <xs:element ref='max-bytes' minOccurs='0'/> | ||
| <xs:element ref='idle-seconds' minOccurs='0'/> | ||
| </xs:sequence> | ||
| </xs:complexType> | ||
| </xs:element> | ||
| <xs:element name='max-bytes' type='xs:unsignedInt'/> | ||
| <xs:element name='idle-seconds' type='xs:unsignedInt'/> | ||
| </xs:schema> | ||
| ]]></code> | ||
| </section1> | ||
| </xep> | ||