moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 02:02:16 -05:00
Code Issues Releases Wiki Activity

XEP-0322: Formatting and XML fixes

Browse Source
This commit is contained in:
Sam Whited 2016-11-02 15:10:35 -05:00
parent 34580b792f
commit 80883baece
1 changed files with 173 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
xep-0322.xml
View File

@ -13,8 +13,7 @@
<abstract>This specification describes how EXI compression can be used in XMPP networks.</abstract>
&LEGALNOTICE;
<number>0322</number>
<status>Proposed</status>
<lastcall>2014-10-21</lastcall>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
@ -34,6 +33,14 @@
<jid>yusuke.doi@gmail.com</jid>
<uri>http://www.linkedin.com/in/yusukedoi</uri>
</author>
<revision>
<version>0.5.1</version>
<date>2016-11-02</date>
<initials>ssw</initials>
<remark>
<p>Formatting and XML fixes.</p>
</remark>
</revision>
<revision>
<version>0.5</version>
<date>2015-11-09</date>
@ -185,8 +192,7 @@
The following sections assume the client connects through the normal XMPP port, and starts communicating with the server using uncompressed XML fragments.
When the client connects to the XMPP Server, it will receive a list of features supported by the server:
</p>
<example caption='Search Features'>
<![CDATA[
<example caption='Search Features'><![CDATA[
<stream:features>
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
<compression xmlns='http://jabber.org/features/compress'>
@ -195,8 +201,7 @@
<method>exi</method>
<method>exi:54321</method>
</compression>
</stream:features>]]>
</example>
</stream:features>]]></example>
<p>
Support for EXI compression through the normal XMPP port is detected by the existence of the <strong>exi</strong> compression method in the <strong>features</strong> stanza.
If a port (static or dynamic) is available for a dedicated binary EXI/XMPP binding, this can be detected by the existence of the <strong>exi:PORT</strong> compression method,
@ -214,23 +219,20 @@
If the client attempts to activate an EXI stream at this point, before the negotiation of EXI properties has been performed, the server must respond with a
<strong>setup-failed</strong> response.
</p>
<example caption='Invalid setup'>
<![CDATA[
<example caption='Invalid setup'><![CDATA[
<compress xmlns='http://jabber.org/protocol/compress'>
<method>exi</method>
</compress>
<failure xmlns='http://jabber.org/protocol/compress'>
<setup-failed/>
</failure>]]>
</example>
</failure>]]></example>
</section3>
<section3 topic='Proposing compression parameters' anchor='setup'>
<p>
When the client decides to activate EXI compression, it sends a <strong>setup</strong> stanza containing parameter proposals to the server as follows:
</p>
<example caption='Proposing compression parameters'>
<![CDATA[
<example caption='Proposing compression parameters'><![CDATA[
<setup xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true' blockSize='1024'
valueMaxLength='32' valuePartitionCapacity='100'>
<schema ns='http://www.w3.org/XML/1998/namespace' bytes='4726' md5Hash='2e2cf9072dc058dcda41b7ee77a5cb54'/>
@ -247,8 +249,7 @@
<schema ns='urn:xmpp:iot:sensordata' bytes='8092' md5Hash='49b101e7deea39ccc31340a3c7871c43'/>
<schema ns='urn:xmpp:iot:interoperability' bytes='1275' md5Hash='5d39845a0082715ff8807691698353bb'/>
<schema ns='urn:xmpp:iot:provisioning' bytes='6303' md5Hash='3ed5360bc17eadb2a8949498c9af3f0c'/>
</setup>]]>
</example>
</setup>]]></example>
<p>
<strong>Note:</strong> Schema files are identified using three properties: Its <strong>target namespace</strong>, its <strong>byte size</strong> and its
<strong>MD5 hash</strong>. The <strong>MD5 hash</strong> provides a way to detect small changes in the file, even if the byte size and namespace are the same.
@ -267,8 +268,7 @@
After receiving the request, the server responds with a <strong>setupResponse</strong> stanza containing the parameters it can accept, based
on the initial values provided by the client. Any buffer sizes, etc., may have been changed, but only lowered, never raised.
</p>
<example caption='Unable to accommodate parameters'>
<![CDATA[
<example caption='Unable to accommodate parameters'><![CDATA[
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true'
blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100'>
<schema ns='http://www.w3.org/XML/1998/namespace' bytes='4726' md5Hash='2e2cf9072dc058dcda41b7ee77a5cb54'/>
@ -285,8 +285,7 @@
<schema ns='urn:xmpp:iot:sensordata' bytes='8092' md5Hash='49b101e7deea39ccc31340a3c7871c43'/>
<schema ns='urn:xmpp:iot:interoperability' bytes='1275' md5Hash='5d39845a0082715ff8807691698353bb'/>
<missingSchema ns='urn:xmpp:iot:provisioning' bytes='6303' md5Hash='3ed5360bc17eadb2a8949498c9af3f0c'/>
</setupResponse>]]>
</example>
</setupResponse>]]></example>
<p>
Schema files that the server does not have (based on namespace, byte size and MD5 hash) are marked with the <strong>missingSchema</strong> element instead of the
normal <strong>schema</strong> element.
@ -306,19 +305,17 @@
<p>
To upload a schema file, the client simply sends the schema file using an <strong>uploadSchema</strong> element, as follows:
</p>
<example caption='Uploading schema file'>
<![CDATA[
<example caption='Uploading schema file'><![CDATA[
<uploadSchema xmlns='http://jabber.org/protocol/compress/exi' contentType='Text'>
PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4NCjx4czpzY2hlbWENCiAgICB4
bWxuczp4cz0naHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEnDQogICAgdGFyZ2V0TmFt
ZXNwYWNlPSd1cm46eG1wcDpzbjpwcm92aXNpb25pbmcnDQogICAgeG1sbnM9J3Vybjp4bXBwOnNu
...
…
dmlsZWdlJz4NCgkJPHhzOmF0dHJpYnV0ZSBuYW1lPSdpZCcgdHlwZT0nUHJpdmlsZWdlSWQnIHVz
ZT0ncmVxdWlyZWQnLz4NCgk8L3hzOmNvbXBsZXhUeXBlPg0KIA0KPC94czpzY2hlbWE+DQo=
</uploadSchema>]]>
</example>
</uploadSchema>]]></example>
<p>
The schema itself is sent using base64 encoding to the server. This is to make sure a binary exact copy is transferred, maintaining encoding, processing instructions, etc. The
server then computes the <strong>target namespace</strong>, <strong>byte size</strong> and <strong>MD5 Hash</strong> from the sent schema file.
@ -327,8 +324,7 @@
If the client desires, it can test the EXI setup again. This is optional, but can be used to test that uploading the schema files, and any new property values
are accepted by the server.
</p>
<example caption='Testing newly uploaded schema files'>
<![CDATA[
<example caption='Testing newly uploaded schema files'><![CDATA[
<setup xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true' blockSize='1024'
valueMaxLength='32' valuePartitionCapacity='100'>
<schema ns='http://www.w3.org/XML/1998/namespace' bytes='4726' md5Hash='2e2cf9072dc058dcda41b7ee77a5cb54'/>
@ -345,13 +341,11 @@
<schema ns='urn:xmpp:iot:sensordata' bytes='8092' md5Hash='49b101e7deea39ccc31340a3c7871c43'/>
<schema ns='urn:xmpp:iot:interoperability' bytes='1275' md5Hash='5d39845a0082715ff8807691698353bb'/>
<schema ns='urn:xmpp:iot:provisioning' bytes='6303' md5Hash='3ed5360bc17eadb2a8949498c9af3f0c'/>
</setup>]]>
</example>
</setup>]]></example>
<p>
And the server should then respond:
</p>
<example caption='Agreement between client and server'>
<![CDATA[
<example caption='Agreement between client and server'><![CDATA[
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true'
blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100' agreement='true'
configurationId='c76ab4ec-4993-4285-8c7a-098060581bb8'>
@ -369,8 +363,7 @@
<schema ns='urn:xmpp:iot:sensordata' bytes='8092' md5Hash='49b101e7deea39ccc31340a3c7871c43'/>
<schema ns='urn:xmpp:iot:interoperability' bytes='1275' md5Hash='5d39845a0082715ff8807691698353bb'/>
<missingSchema ns='urn:xmpp:iot:provisioning' bytes='6303' md5Hash='3ed5360bc17eadb2a8949498c9af3f0c'/>
</setupResponse>]]>
</example>
</setupResponse>]]></example>
<p>
Note the <strong>agreement</strong> attribute in the response this time. The server must set this attribute to true if it agrees with the proposal from the client.
The client in turn can check this attribute as a quick way to check if agreement exists. When the server is in agreement it must also return a Configuration ID
@ -475,10 +468,9 @@
As an alternative to uploading a schema file to the server, the client can ask the server to download a schema file by itself. This is done using the <strong>downloadSchema</strong>
command, as follows:
</p>
<example caption='Downloading a new XML schema file on server'>
<![CDATA[
<downloadSchema xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd'/>]]>
</example>
<example caption='Downloading a new XML schema file on server'><![CDATA[
<downloadSchema xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd'/>
]]></example>
<p>
The server tries to download the schema by itself, and then computes the <strong>target namespace</strong>, <strong>byte size</strong> and <strong>MD5 Hash</strong>
from the downloaded schema.
@ -486,55 +478,44 @@
<p>
When the schema has been downloaded, the following successful download response is returned:
</p>
<example caption='Schema successfully downloaded'>
<![CDATA[
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd' result='true'/>]]>
</example>
<example caption='Schema successfully downloaded'><![CDATA[
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd' result='true'/>
]]></example>
<p>
If an HTTP error occurred while trying to download the schema, a response as follows is returned:
</p>
<example caption='HTTP Error'>
<![CDATA[
<example caption='HTTP Error'><![CDATA[
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd' result='false'>
<httpError code='404' message='NotFound'/>
</downloadSchemaResponse>]]>
</example>
</downloadSchemaResponse>]]></example>
<p>
If the URL could not be resolved, the following response is returned:
</p>
<example caption='Invalid URL'>
<![CDATA[
<example caption='Invalid URL'><![CDATA[
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='urk://example.org/schema.xsd' result='false'>
<invalidUrl message='Unrecognized schema.'/>
</downloadSchemaResponse>]]>
</example>
</downloadSchemaResponse>]]></example>
<p>
If a timeout occurred during the download attempt, the following response is returned:
</p>
<example caption='Timeout'>
<![CDATA[
<example caption='Timeout'><![CDATA[
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd' result='false'>
<timeout message='No response returned.'/>
</downloadSchemaResponse>]]>
</example>
</downloadSchemaResponse>]]></example>
<p>
If the url points to something that is not a schema, the following response is returned:
</p>
<example caption='Invalid Content Type'>
<![CDATA[
<example caption='Invalid Content Type'><![CDATA[
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd' result='false'>
<invalidContentType contentTypeReturned='text/html'/>
</downloadSchemaResponse>]]>
</example>
</downloadSchemaResponse>]]></example>
<p>
If an error occurs that is unforeseen by this specification, the server can simply respond with a generic error message, as follows:
</p>
<example caption='Other types of errors'>
<![CDATA[
<example caption='Other types of errors'><![CDATA[
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.example.org/compress/sn/provisioning.xsd' result='false'>
<error message='No free space left.'/>
</downloadSchemaResponse>]]>
</example>
</downloadSchemaResponse>]]></example>
<p>
<strong>Note:</strong> Downloading a schema, might download a version which does not correspond to the desired version
of the schema. It might for instance have been updated. This means the <strong>bytes</strong> and <strong>md5Hash</strong> values
@ -549,10 +530,9 @@
through the <strong>configurationId</strong> attribute. This Configuration ID can be used by the client during successive connections to the server,
to skip the larger part of the handshake, as is shown in the following example:
</p>
<example caption='Accessing quick configurations'>
<![CDATA[
<setup xmlns='http://jabber.org/protocol/compress/exi' configurationId='c76ab4ec-4993-4285-8c7a-098060581bb8'/>]]>
</example>
<example caption='Accessing quick configurations'><![CDATA[
<setup xmlns='http://jabber.org/protocol/compress/exi' configurationId='c76ab4ec-4993-4285-8c7a-098060581bb8'/>
]]></example>
<p>
<strong>Note:</strong> the quick configuration includes all accepted schemas and all EXI options agreed upon during the
session when the configuration ID was returned. The <strong>configurationId</strong> attribute MUST NOT be used together
@ -561,10 +541,9 @@
<p>
If the configuration is still available on the server, the server responds:
</p>
<example caption='Quick configuration accepted'>
<![CDATA[
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' agreement='true' configurationId='c76ab4ec-4993-4285-8c7a-098060581bb8'/>]]>
</example>
<example caption='Quick configuration accepted'><![CDATA[
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' agreement='true' configurationId='c76ab4ec-4993-4285-8c7a-098060581bb8'/>
]]></example>
<p>
Note that schemas or options are not mentioned explicitly when using this quick setup approach.
</p>
@ -574,10 +553,9 @@
If the server for some reason does not remember the specific configuration requested by the client (the client might have been disconnected for
a long time), it responds in the following manner:
</p>
<example caption='Quick configuration failure'>
<![CDATA[
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' agreement='false' configurationId='c76ab4ec-4993-4285-8c7a-098060581bb8'/>]]>
</example>
<example caption='Quick configuration failure'><![CDATA[
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' agreement='false' configurationId='c76ab4ec-4993-4285-8c7a-098060581bb8'/>
]]></example>
<p>
The agreement attribute is optional, with a default value of false. So, if the attribute is omitted, the client must consider the
agreement to be nonexistent. When no agreement is reached using the quick configuration approach, the client must restart the handshake
@ -589,19 +567,16 @@
When EXI option negotiation has been completed, the client can tell the server that it is ready to start compression. It does this using the normal <strong>compress</strong>
stanza, as follows:
</p>
<example>
<![CDATA[
<example><![CDATA[
<compress xmlns='http://jabber.org/protocol/compress'>
<method>exi</method>
</compress>]]>
</example>
</compress>]]></example>
<p>
The server now has the necessary knowledge on how the EXI engine should be configured for the current session and it responds as follows:
</p>
<example caption='Compression accepted'>
<![CDATA[
<compressed xmlns='http://jabber.org/protocol/compress'/>]]>
</example>
<example caption='Compression accepted'><![CDATA[
<compressed xmlns='http://jabber.org/protocol/compress'/>
]]></example>
<p>
When the client receives acknowledgement that the compression method has been accepted, it restarts the stream, as explained in
<link url='http://xmpp.org/extensions/xep-0138.html#usecase'>XEP 0138</link>, except that it <strong>must not</strong> resend the <strong>&lt;stream&gt;</strong>
@ -756,7 +731,7 @@
If client needs to use different encoding option or schema than the default encoding options or <link url="#defaultSchema">the default schema</link>, then the client shall start <link url="#schemaHandling">schema negotiation</link>. The streams with alternate options/schemas SHOULD NOT have an EXI Options document to indicate the parameter is negotiated via previous XMPP stream.
</p>
<p>
For example, the client want to use MUC option (<link href="http://xmpp.org/extensions/xep-0045.html">XEP-0045</link>)), the following communication will occur. First, client try to renegotiate XML schema used in the communication.
For example, the client want to use MUC option (<link url="http://xmpp.org/extensions/xep-0045.html">XEP-0045</link>), the following communication will occur. First, client try to renegotiate XML schema used in the communication.
</p>
<example caption="XML equivalent of setup element (Client to Server)">
<!-- samples/C2S/002-base-setup.xml -->
@ -1063,7 +1038,7 @@ FIXME
-->
<p>
In addition, local value learning mechanism is disabled by
default as described in section 4 of <link href="http://www.w3.org/TR/exi-profile/">EXI Profile</link>.
default as described in section 4 of <link url="https://www.w3.org/TR/exi-profile/">EXI Profile</link>.
<!-- FIXME: [YD] add reference to available implementations -->
</p>
<ul>
@ -1106,7 +1081,6 @@ FIXME
| +----+ | | +----+ |
+-------------------------+ +-----------------------+
]]>
</example>
<p>
In the example, the box XMPP is conventional XMPP process. [EXI] represents EXI processor (encoder and decoder). [Proc] means preprocessor and postprocessor.
@ -1366,7 +1340,7 @@ FIXME
The format for these opton documents or locations is beyond the scope of this specification.
</p>
<section3 topic="Shortcut Setup for Alternative Transport Binding" anchor="shortcutAltBind">
With alternative transport bind, following rule for shortcut may be used, assuming a server and a client have common shared configuration with configurationId="01234" as an example.
<p>With alternative transport bind, following rule for shortcut may be used, assuming a server and a client have common shared configuration with configurationId="01234" as an example.</p>
<ul>
<li>
Client can start configured stream with a <strong>exi:streamStart</strong> element encoded in the configuration given in configurationId="01234". To indicate configurationId, a schemaId corresponds to the configurationId prefixed by "c:" SHALL be used. In this example, schemaId is "c:01234". EXI option in EXI option header other than the schemaId SHOULD NOT be specified.
@ -2395,7 +2369,7 @@ FIXME
new byte sizes and hash values must be computed for the changed schema correspondingly.
</p>
<p>
Patched version of XML schemas may be placed in the <link href="#wellknown">snapshot repository for well-known schemas</link> to avoid wild patches (and too many derived schema for the same model).
Patched version of XML schemas may be placed in the <link url="#wellknown">snapshot repository for well-known schemas</link> to avoid wild patches (and too many derived schema for the same model).
</p>
<section3 topic="Patch to avoid UPA for streams.xsd" anchor="patch">
<!-- [YD] -->
@ -2478,16 +2452,16 @@ FIXME
]]>
</code>
<p>
The ${snapshot-url} corresponds to yet-to-be-specified schema snapshot repository described in <link href="#wellknown">snapshot repository for well-known schemas</link> section.
The ${snapshot-url} corresponds to yet-to-be-specified schema snapshot repository described in <link url="#wellknown">snapshot repository for well-known schemas</link> section.
The schemaId of this schema will is 'urn:xmpp:exi:default'. SchemaId is ID for this instance and not a namespace identifier and intentionally different from the target namespace of the schema.
</p>
</section2>
<section2 topic="Reserved Schema IDs" anchor="reservedSchemaID">
<!-- [YD] required for alternative bindings -->
Following schema Ids are reserved.
<p>Following schema Ids are reserved.</p>
<ul>
<li>
Schema IDs starts with "c:". This is used as <link href="#shortcutaltBind">shortcut setup for alternative transport binding</link>.
Schema IDs starts with "c:". This is used as <link url="#shortcutaltBind">shortcut setup for alternative transport binding</link>.
</li>
<li>Schema IDs starts with "urn:xmpp". This may be used to describe XEP-based schemas.</li>
</ul>