随笔- 1  评论- 21  文章- 16 

XMPP翻译:RFC 3920[7](Chapter9)

本篇翻译了XMPP核心协议RFC 3920的第九章。

内容提要

XML Stanzas //XML节

    1. Common Attributes //共同的属性
    2. Basic Semantics //基本的语义
    3. Stanza Errors //节错误

在TLS协商后(假定希望TLS协商),如果需要SASL协商和资源绑定,可以通过流发送XML节。我们定义为'jabber:client' 和'jabber:server' 命名空间定义了三种类型的XMl节:<message/>、<presence/>、<iq/>。另外,这些节有五个通用的属性。这里定义了这些通用属性以及这些节类型的基本语义;[XMPP-IM]中提供有关(涉及到XMPP应用程序的)XML节的更多详细的信息。


9.1. 共同的属性

下面的五个属性通用于message、presence和IQ节:

9.1.1.  to

‘to’属性指定了节所要的接收者的JID

在‘jabber:client’命名空间里,节应该(SHOULD)要持有一个‘to’属性,虽然从客户端发送到服务器,让服务器处理的节(例如,为了广播到其它实体而发送的presence)不应该(SHOULD NOT)有‘to’属性。

在‘jabber:server’命名空间里,节(MUST)持有一个‘to’属性;如果服务器接收到了一个不符合该规定的节,他必须(MUST)生成一个<improper-addressing/>流错误信息,并且终止与出错服务器的XML流和TCP连接。

如果‘to’属性值无效或无法连接,意识到这个错误的实体()必须(MUST)返回一个适当的错误报告给发送者,将报告(一个节)的‘from’属性设置成出错节的‘to’属性值。

9.1.2.  from

‘from’属性指定了发送者的JID。

当服务器接收到在‘jabber:client’命名空间下的已认证的流的上下文中的XML节,它做下列事件之一:

  1. 确认客户端提供的‘from’属性值是已关联实体的已连接的资源
  2. add a 'from' address to the stanza whose value is the bare JID (<node@domain>) or the full JID (<node@domain/resource>) determined by the server for the connected resource that generated the stanza (see Determination of Addresses)

如果客户端尝试发送一个XML节,而该节的‘from’属性值与实体的连接资源不符,服务器应该(SHOULD)返回流错误到客户端。如果客户端尝试通过还未认证的流发送XML节,服务器应该(SHOULD)返回一个<not-authorized/>流错误到客户端。如果发生了,这些情形中,都必须(MUST)关闭流并终止underlyingTCP连接;这有助于在流氓客户端发起的攻击时预先拒绝服务。 

当服务器自身产生一个节发送到已连接的客户端(例如,服务器代表提供的数据存储服务的上下文中),该节必须(MUST)要么不包含‘from’属性,要么所包含的‘from’的属性值是the account's bare JID (<node@domain>) or client's full JID (node@domain/resource)。当节是由服务器自身产生的,服务器则禁止(MUST NOT)给客户端发送不带有‘from’属性的此类节。当客户端接收到不包含‘from’属性的节,它必须(MUST)假设该节是从它所连接的服务器发来的。

在‘jabber:server’命名空间里,节必须(MUST)持有‘from’属性;如果服务器接收到不满足这个约束的节时,它必须(MUST)产生一个<improper-addressing/>流错误报告。另外,‘from’属性中包含的JID的域标识符部分必须(MUST)与发送该JID的服务器(或者在其中的任何有效域,如发送服务器主机名的一个有效的子域或发送服务器掌控的的其它有效的域)的主机名相匹配,与SASL协商或回拨协商时一样;如果服务器接收到了不满足这个条件的节时,它必须(MUST)产生一个<invalid-from/>流错误报告。这些情形中,都必须(MUST)关闭流并终止underlyingTCP连接;这有助于在流氓服务器发起的攻击时预先拒绝服务。

9.1.3.  id

可选的‘id’属性可以被发送实体用于内在的跟踪(internal tracking)它所发送和接收的节(尤其用于跟踪IQ节的内在语义中的请求/响应交互)。在一个域中或是一个流中,把‘id’属性值设为全球唯一也是可选的。IQ节的语义强加了额外的限制;参见IQ语义。

9.1.4.  type

‘type’属性定义了与message、presence或IQ节的意图或上下文有关的详细信息。‘type’属性允许的特定值因是messge或是presence,或是IQ而变化;message和presence节的这些值特定于即时信息和即时出席,所以定义在[XMPP-IM]中,而IQ节的值指定了在结构化的请求/响应“会话”中的IQ节的作用,因此被定义在[IQ语义]中。与这三种节有共同点的唯一的‘type’值是‘error’;参见节错误。

9.1.5.  xml:lang

若节包含了XML字符数据,这数据是要呈现给用户的,那么这节应该(SHOULD)要有个‘xml:lang’属性(RFC 2277[CHARSET]中有说明,“为用户国际化”)。‘xml:lang’属性值定义了这些用户可读的XML字符数据的缺省语言,它可以(MAY)被特定子元素的‘xml:lang’属性值覆盖。倘若节没有‘xml:lang’属性,针对这个数据的实现(implementation)必须(MUST)假设缺省语言是流属性中定义的缺省语言(在前面的“流属性”中有详细说明)。‘xml:lang’属性值必须(MUST)是NMTOKEN,而且必须(MUST)符合RFC 3066[LANGTAGS]中的规定。

 

9.2.  基本的语义

9.2.1.  Message的语义

<message/>节类型可以看做事一个“push”机制,实体通过它将信息push给其它实体,这类似于发生在email系统中的通信。所有的message节应该(SHOULD)要有‘to’属性,用于指定message目标容器;在接收到这样一个节后,服务器应该(SHOULD)将其路由或递送到目标容器(参见Server Rules for Handling XML Stanzas for general routing and delivery rules related to XML stanzas)。

9.2.2.  Presence的语义

<presence/>元素可以看成是一个基础的广播或“publish-subscribe”机制,其它众多的实体通过此机制得到它们订阅的实体的信息(即,网络的可用性信息)。一般来说,发布者(实体)应该(SHOULD)发送一个不带‘to’属性的presence节,此时,与此实体连接的服务器应该(SHOULD)广播或多元化该节给所有的订阅者(实体)。然而发布者也可以(MAY)发送带有‘to’属性的节,此时,服务器则应该(SHOULD)路由或递送此节到目标容器。参见Server Rules for Handling XML Stanzas for general routing and delivery rules related to XML stanzas和[XMPP‑IM] for presence-specific rules in the context of an instant messaging and presence application。

9.2.3.  IQ的语义

Info/Query或IQ,使一个请求/响应机制 ,某些方面类似于HTTP。IQ的语义让实体能够向其它实体发送请求,以及从其它实体接收响应。请求/响应数据的内容定义在IQ节的一个直接子元素的命名空间声明里,请求实体通过使用‘id’属性跟踪这个请求/响应交互。因此,IQ节的交互遵循结构化数据交互的通用模式,像get/result或set/result(尽管也可能会返回适当的错误):

Requesting                 Responding
Entity                     Entity
----------                 ----------
|                           |
| <iq type='get' id='1'>    |
| ------------------------> |
|                           |
| <iq type='result' id='1'> |
| <------------------------ |
|                           |
| <iq type='set' id='2'>    |
| ------------------------> |
|                           |
| <iq type='error' id='2'>  |
| <------------------------ |
|                           |

为了增强这些语义,应用以下规则:

  1. IQ节的‘id’ 属性是必需的(REQUIRED) 。
  2. IQ节的‘type’ 属性是必需的(REQUIRED)。其值必须(MUST)是以下之一:
    • get -- The stanza is a request for information or requirements.
    • set -- The stanza provides required data, sets new values, or replaces existing values.
    • result -- The stanza is a response to a successful get or set request.
    • error -- An error has occurred regarding processing or delivery of a previously-sent get or set (see Stanza Errors).
  3. 接收到‘type’为“get”或“set”的IQ节的实体必须(MUST)回复type为“result”或“error”的IQ响应(响应必须保持请求的‘ID’属性)。
  4. 接收到‘type’为“result”或“error”的IQ节的实体必须(MUST)回复type为“result”或“error”的更深一层次的IQ响应;然而,正如前面所说的,发送请求的实体可以(MAY)发送其它请求(例如,一个type为“set”的节,用来提供那些通过get/result对所发现的被需要的信息)。
  5. type为“get”或“set”的IQ节,必须(MUST)包含一个且仅有一个指定特定的request或response语义的子元素。
  6. type为“result”必须(MUST)是包含0/1个子元素。
  7. type为“error”应该(SHOULD)包含一个与“get”或“set”相关的节中的子元素,且必须(MUST)包含一个<error/>子元素; 详见Stanza Errors.

 

9.3.  节错误

节有关的错误(stanza-related errors)以类似于处理流错误的方式处理。可是,与流错误不同的是,节错误是可恢复的;因此节错误包含了与初始实体为了挽回错误而携带的动作(actions)相关的信息。

9.3.1.  规则

下列规则应用于stanza-related errors:

  • The receiving or processing entity that detects an error condition in relation to a stanza MUST return to the sending entity a stanza of the same kind (message, presence, or IQ), whose 'type' attribute is set to a value of "error" (such a stanza is called an "error stanza" herein).
  • The entity that generates an error stanza SHOULD include the original XML sent so that the sender can inspect and, if necessary, correct the XML before attempting to resend.
  • An error stanza MUST contain an <error/> child element.
  • An <error/> child MUST NOT be included if the 'type' attribute has a value other than "error" (or if there is no 'type' attribute).
  • An entity that receives an error stanza MUST NOT respond to the stanza with a further error stanza; this helps to prevent looping.

9.3.2.  语法

与节相关的错误的语法如下:

<stanza-kind to='sender' type='error'>
[RECOMMENDED to include sender XML here]
<error type='error-type'>
<defined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'
xml:lang='langcode'>
OPTIONAL descriptive text
</text>
[OPTIONAL application-specific condition element]
</error>
</stanza-kind>

节类型是message、presence或iq中的一种。

<error/>元素的‘type’属性值必须(MUST)是以下之一:

  • cancel -- 不要再尝试(the error is unrecoverable)
  • continue -- 继续进行 (the condition was only a warning)
  • modify -- 改变发送的数据后再试
  • auth -- 提供凭证后再试
  • wait -- 等待一段时间后在试(the error is temporary)

<error/>元素:

  • 必须包含一个 与下面定义的节错误情形之一相应的子元素;且该元素必须有‘urn:ietf:params:xml:ns:xmpp-stanzas’命名空间限定。
  • 可以包含一个<text/>子元素,含有用于描述详细的错误信息的XML字符数据; 该元素必须(MUST)由‘urn:ietf:params:xml:ns:xmpp-stanzas’命名空间限定修饰,且应该(SHOULD)要有一个‘xml:lang’属性。
  • 可以包含一个子元素用于application-specific的错误情形;该元素必须(MUST)由一个application-defined命名空间限定修饰,而且它的结构也由此命名空间定义。

<text/>元素是可选的。若是包含了,它应该仅用于提供描述性的或诊断性的信息,来补充定义的情形或application-specific 的情形的信息。应用程序不应该(SHOULD NOT)自动的解释它。它也不应该(SHOULD NOT)被用做呈现给用户的错误信息 ,但是可以指示除与已包括的元素相关的错误信息之外的信息。

最后,我了保持向后的兼容性,该模式(定义在[XMPP‑IM]中)允许在<error/>元素中包含一个可选的‘code’属性 。

9.3.3.  定义的情形

以下是为节错误定义的情形。

  • <bad-request/> -- the sender has sent XML that is malformed or that cannot be processed (e.g., an IQ stanza that includes an unrecognized value of the 'type' attribute); the associated error type SHOULD be "modify".
  • <conflict/> -- access cannot be granted because an existing resource or session exists with the same name or address; the associated error type SHOULD be "cancel".
  • <feature-not-implemented/> -- the feature requested is not implemented by the recipient or server and therefore cannot be processed; the associated error type SHOULD be "cancel".
  • <forbidden/> -- the requesting entity does not possess the required permissions to perform the action; the associated error type SHOULD be "auth".
  • <gone/> -- the recipient or server can no longer be contacted at this address (the error stanza MAY contain a new address in the XML character data of the <gone/> element); the associated error type SHOULD be "modify".
  • <internal-server-error/> -- the server could not process the stanza because of a misconfiguration or an otherwise-undefined internal server error; the associated error type SHOULD be "wait".
  • <item-not-found/> -- the addressed JID or item requested cannot be found; the associated error type SHOULD be "cancel".
  • <jid-malformed/> -- the sending entity has provided or communicated an XMPP address (e.g., a value of the 'to' attribute) or aspect thereof (e.g., a resource identifier) that does not adhere to the syntax defined in Addressing Scheme; the associated error type SHOULD be "modify".
  • <not-acceptable/> -- the recipient or server understands the request but is refusing to process it because it does not meet criteria defined by the recipient or server (e.g., a local policy regarding acceptable words in messages); the associated error type SHOULD be "modify".
  • <not-allowed/> -- the recipient or server does not allow any entity to perform the action; the associated error type SHOULD be "cancel".
  • <not-authorized/> -- the sender must provide proper credentials before being allowed to perform the action, or has provided improper credentials; the associated error type SHOULD be "auth".
  • <payment-required/> -- the requesting entity is not authorized to access the requested service because payment is required; the associated error type SHOULD be "auth".
  • <recipient-unavailable/> -- the intended recipient is temporarily unavailable; the associated error type SHOULD be "wait" (note: an application MUST NOT return this error if doing so would provide information about the intended recipient's network availability to an entity that is not authorized to know such information).
  • <redirect/> -- the recipient or server is redirecting requests for this information to another entity, usually temporarily (the error stanza SHOULD contain the alternate address, which MUST be a valid JID, in the XML character data of the <redirect/> element); the associated error type SHOULD be "modify".
  • <registration-required/> -- the requesting entity is not authorized to access the requested service because registration is required; the associated error type SHOULD be "auth".
  • <remote-server-not-found/> -- a remote server or service specified as part or all of the JID of the intended recipient does not exist; the associated error type SHOULD be "cancel".
  • <remote-server-timeout/> -- a remote server or service specified as part or all of the JID of the intended recipient (or required to fulfill a request) could not be contacted within a reasonable amount of time; the associated error type SHOULD be "wait".
  • <resource-constraint/> -- the server or recipient lacks the system resources necessary to service the request; the associated error type SHOULD be "wait".
  • <service-unavailable/> -- the server or recipient does not currently provide the requested service; the associated error type SHOULD be "cancel".
  • <subscription-required/> -- the requesting entity is not authorized to access the requested service because a subscription is required; the associated error type SHOULD be "auth".
  • <undefined-condition/> -- the error condition is not one of those defined by the other conditions in this list; any error type may be associated with this condition, and it SHOULD be used only in conjunction with an application-specific condition.
  • <unexpected-request/> -- the recipient or server understood the request but was not expecting it at this time (e.g., the request was out of order); the associated error type SHOULD be "wait".

9.3.4.  特定应用的情形

如我们说知道的,应用程序可以(MAY)通过在错误元素中包含一个由适当的命名空间限定的子元素,提供特定应用(application-specific)的节错误信息。这个application-specific元素应该(SHOULD)补充或更进一步的限定一个定义的元素。因此,元素将会包含2、3个子元素:

<iq type='error' id='some-id'>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<too-many-parameters xmlns='application-ns'/>
</error>
</iq>
<message type='error' id='another-id'>
<error type='modify'>
<undefined-condition
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xml:lang='en'
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
Some special application diagnostic information...
</text>
<special-application-condition xmlns='application-ns'/>
</error>
</message>
 

XMPP翻译:RFC 3920[7]到此结束,请继续关注 XMPP翻译:RFC 3920[8]

posted on 2006-11-17 23:37 Hunts.C 阅读(...) 评论(...) 编辑 收藏