JEP-xxxx: Address Lists

This document specifies extension to Extended Stanza Addressing to create and reuse lists of addresses.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the Jabber Software Foundation, and this document must not be referred to as a Jabber Enhancement Proposal (JEP). If this document is accepted as a JEP by the Jabber Council, it will be published at <http://www.jabber.org/jeps/> and announced on the <standards-jig@jabber.org> mailing list.


JEP Information

Status: ProtoJEP
Type: Standards Track
Number: xxxx
Version: 0.0.1
Last Updated: 2006-06-01
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, JEP-0030, JEP-0033
Supersedes: None
Superseded By: None
Short Name: Not yet assigned

Author Information

Michal Vaner

Email: michal.vaner@kdemail.net
JID: michal.vaner@njs.netlab.cz

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy (http://jabber.org/jsf/ipr-policy.php). This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this JEP has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.


Table of Contents

1. Introduction
2. Requirements
3. Discovering server support
3.1. Disco request for server
3.2. Multicast service
3.3. Caching
4. Saving a list
5. Using a list
6. Removing addresses from a list
7. Deleting a list
7.1. Requested delete
7.2. Deletion of all lists
7.3. Automatic deletion
8. Owner of the list
9. Automatic lists
9.1. Discovering automatic lists
9.2. Using an automatic list
10. Errors
11. Implementation Notes
11.1. Relay
11.2. Error handling
11.3. Prefixes
12. Security Considerations
13. IANA Considerations
14. Jabber Registrar Considerations
15. XML Schema
Notes
Revision History


1. Introduction

Extended Stanza Addressing allows sending of stanzas to more recipients. However, all the addresses must be sent with each stanza. There are many cases, where this list of addresses is same or simillar. This document specifies how to create such lists on remote server and reuse them to optimize the amount of sent data.

It leaves a way to introduce automatic lists, which can be used without prior creation. These automatic lists are out of scope of this document.

2. Requirements

As this is extension to Extended Stanza Addressing, conforming server MUST have full support for this, either as a service or as the server itself.

3. Discovering server support

To determine if a server or service supports Extended Stanza Addressing, the requesting entity SHOULD send a disco#info request to it.

3.1 Disco request for server

Example 1. Disco request for address header support

<iq type='get'
    from='romeo@montague.net/orchard'
    to='multicast.montague.net'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
           

If the server supports Extended Stanza Addressing, it MUST include both "http://jabber.org/protocol/address" and "http://jabber.org/protocols/address/list" features in the response.

Example 2. Disco response for server supporting address headers

<iq type='result'
    from='multicast.montague.net'
    to='romeo@montague.net/orchard'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://jabber.org/protocol/address'/>
    <feature var='http://jabber.org/protocol/address/list'/>
    ...
  </query>
</iq>
           

3.2 Multicast service

The IM service MAY implement multicast directly, or it MAY delegate that chore to a separate service. A client can use the following approach to find a multicast-capable service hosted by its domain:

  1. Send a disco#info request to the IM server; if its reply includes the 'http://jabber.org/protocol/address/list' feature, then it is a service supporting address lists.
  2. If the IM server is not supporting address lists, send a disco#items request to the IM server; the IM server will then return a list of associated services.
  3. Send a disco#info request to each of the services associated with the IM server; if one of the replies includes the 'http://jabber.org/protocol/address/list' feature, then that service is a multicast-capable service.

The multicast service MAY choose to limit which local users can use the service. The server MAY choose to limit whether non-local servers can send address headers that require the local server to send to third parties (relaying). In either case, if the server chooses to disallow the request, the server MUST return a Forbidden error (see the Error Conditions section below). In the relaying case, the server SHOULD NOT deliver to any of the addresses (even the local ones) if the sender is disallowed.

3.3 Caching

Implementations MAY choose to cache the disco response. Positive responses MAY be cached differently than negative responses. The result SHOULD NOT be cached for more than 24 hours, unless some sort of time-to-live information is added to the Service Discovery protocol in the future.

4. Saving a list

Any addresses provided in a stanza can be saved for future use. This means, first time the list is used, the addresses are sent in usual way according to jep-0033 and <save> element quilified by the "http://jabber.org/protocol/address/list" is added to specify this list should be saved.

The <save> element MUST possess a 'name' attribute. The value specifies desired name of the list.

Example 3. List creation example

<presence to='multicast.montague.net' from='conference.montague.net/romeo'>
    <addresses xmlns='http://jabber.org/protocols/address'>
        <address type='bcc' jid='romeo@montague.net/orchard'/>
	<address type='bcc' jid='juliet@capulet.com/balcony'/>
	<save xmlns='http://jabber.org' name='private MUC'/>
    </addresses>
    <show>away</show>
</presence>
	
	

5. Using a list

Existing list can be used instead of the actual addresses. These addresses are expanded before any processing of the addresses, including the <save> command. As there is no limit to number of lists used in one stanza, any duplicit addresses are removed. If these duplicit addresses are of more than one type, the 'to' is preferred above others and 'cc' above 'bcc'.

The list is specified by <list> element qualified by the "http://jabber.org/protocol/address/list" namespace.

Every <list> element MUST possess 'name' attribute, specifying the name of desired list. It SHOULD possess 'hash' attribute, which is used to check if the list is in sync on the servers. The hash is MD5 hash of coma separated list of the addresses in the list, in the form type:jid/url:the-address.

Example 4. Hash computation example

The hash of the list in above example would be MD5 hash of this string:
"bcc:jid:romeo@montague.net/orchard,bcc:jid:juliet@capulet.com/balcony", 
which means it would be 624678c1ce4f0cf6497b79cd9bc5822e.
	

Example 5. Use of existing list

<message to='multicast.montague.net' from='conference.montague.net/romeo'>
     <addresses xmlns='http://jabber.org/protocols/address'>
          <list xmlns='http://jabber.org/protocols/address/list'
	       name='private MUC'
	       hash='624678c1ce4f0cf6497b79cd9bc5822e'/>
     </addresses>
     <body>Julie, I love you</body>
</message>
	
	

The <addresses> element can contain any number of <address> and <list> subelements

A new list can be created by updating another one. Because the <list> element is expanded to the addresses before the <save> command is executed, it is just the same as creating a brand new list. This allows even merging and branching of lists.

Since the new list will have a different hash, it does not necesary need to have a different name. More than one list with a same name can exist, if they have different hash. If a name specifying more than one list is used, and no 'hash' attribute is present, the latest created list is used.

Example 6.

<presence to='multicast.montague.net' from='conference.montague.net/rogue'>
    <addresses xmlns='http://jabber.org/protocols/address'>
        <list xmlns='http://jabber.org/protocols/address/list'
	       name='private MUC'
	       hash='624678c1ce4f0cf6497b79cd9bc5822e'/>
        <address type='bcc' jid='rogue@nowhere.org/street'>
	<save xmlns='http://jabber.org/protocols/address/list' name='private MUC'/>
    </addresses>
</presence>
	
	

6. Removing addresses from a list

The <addresses> element can contain a <remove> subelement qualified by the "http://jabber.org/protocols/address/list" namespace. This sublement MUST contain either 'jid' or 'url' attribute, which efectively removes any <address> element with this jid or url. They are processed directly after expansion of <list> elements.

Of course, the <addresses> element can contain all 3 kinds of subelements (<list>, <address;>, <remove>), in any number.

This way modified list can be saved as any other list.

Example 7. Removing address example

<message to='multicast.montague.net' from='conference.montague.net/juliet'>
    <addresses xmlns='http://jabber.org/protocols/address/list'
        <list xmlns='http://jabber.org/protocols/address/list'
	       name='private MUC'
	       hash='0ea29eb12ceff84d6300d66170eeebc0'/>
	<remove xmlns='http://jabber.org/protocols/address/list' jid='rogue@nowhere.org/street'/>
	<save xmlns='http://jabber.org/protocols/address/list' name='private MUC'/>
    </addresses>
    <body>Uff, he left.</body>
</message>
	
	

7. Deleting a list

7.1 Requested delete

Owner of the list (see below) can even delete the whole list. List is deleted, when it possess attribude 'delete' of value "this".

If the hash is not specified, only the lates created list is deleted.

If deletion of all lists of the name is needed, the value for 'delete' attribute is "all".

Another possible value for 'delete' attribute is "others", which will delete all lists of specified name except this actual list.

No matter which delete way is specified, the specified list is used as if there was no 'delete' attribute and the deletion is processed after expansion.

Attribute 'no-expand' of empty value can be used to specify the list should not be expanded. It is useful when there is need to delete a list without

7.2 Deletion of all lists

Owner can delete all its lists by sending an <iq> stanza containing <delete-all> element qualified by "http://jabber.org/protocols/address/list" namespace.

7.3 Automatic deletion

Multicast service MAY delete any list at any time, wihthout notifying the owner. This is to ensure that forgotten lists will get deleted sometime and the multicast service won't eat too much resources.

If the list was not forgotten and is used, propper error MUST be specified to ensure the sender recreates the list and resends the stanza.

8. Owner of the list

Ususally, the lists belongs to the bare JID. This is usefull for things like MUC or sending outbound presence. However, for client usage, it would be better if the owner would be only the one resource. This can be achieved by including attribute 'owner' of value "resource" to each <list>, <save> and <delete-all> elements.

Lists owned by a resource SHOULD be deleted when the resource disconnects.

9. Automatic lists

Automatic lists are very similar to usual lists. They can have hash, multiple versions with the same name and so on. The only difference is they can created, modified or deleted. They exist and change without prior creation.

9.1 Discovering automatic lists

To dicover, what lists are supported, asking side sends an iq request like this: <iq to='multicast.montague.net' type='get' from='romeo@montague.net'> <auto-lists xmlns='jabber.org/protocols/address/list'/> </iq>

The service MUST respond with a list of supported automatic lists: <iq to='romeo@montague.net' from='multicast.montague.net' type='result'> <auto-lists xmlns='jabber.org/protocols/address/list'> <auto-list name='some fancy list'/> <auto-list name='all montagues'/> </auto-lists> </iq>

9.2 Using an automatic list

Automatic lists are used in a similar way to usual lists. Instead of <list> element, <auto-list> is used. Furthemore, 'delete' attribute MUST NOT be specified. An automatic list MAY have 'hash' attribute specified.

Example 8. Using an automatic list

<message to='multicast.montague.net' from='cook@montague.net'>
    <addresses xmlns='jabber.org/protocols/address'>
        <auto-list xmlns='jabber.org/protocols/address/list' name='all montagues'/>
    </addresses>
    <body>The dinner is ready</body>
</message>
		

10. Errors

If it is imposible to create a list (for example, not enough memory), the multicast service retuns an error of type 'continue' with <internal-server-error>. This means the stanza was delivered to all the recipients, but the list is not saved. In this case, the original stanza MAY be omited.

If a non-existing list is requested, an error of type 'modify' is returned. The condition is <undefined-condition>. The error contains <list-unavailable> element, qualified by the 'http://jabber.org/protocols/address/list' namespace. This element will contain all the unavailable lists and automatic lists as specified in <addresses> element. The service MUST include the original stanza inside the error.

If the sent stanza was a <presence> stanza, the error is returned as <message> stanza, since <presence> stanzas can not hold errors. To recognize that the original stanza was presence, <presence> element qualified by 'http://jabber.org/protocols/address/list' is added to the <message> stanza.

11. Implementation Notes

11.1 Relay

It is possible that one multicast service uses another. It is possible to use the lists for them as well. Sometimes, an update for a list does not necessary need to be send to all remote services.

It is possible to relay more local lists using one remote, if they are the same (if, for example, there are two montagues in two capulet chatrooms.)

11.2 Error handling

To handle the situation, when there is a problem with remote list (it is out of sync, does not exist..), the sender needs to remember what the desired list looks like, so it is possible to resent the stanza and recreate the list. However, there is no need to remember the stanza, since it is returned with the error.

11.3 Prefixes

It ie recommended for implementators to use XML namespace prefixes, since they are less verbose then including the namespace in each element.

12. Security Considerations

Author is not aware of any security problems or features in addition to JEP-0033.

13. IANA Considerations

This JEP requires no interaction with the the Internet Assigned Numbers Authority (IANA) [1].

14. Jabber Registrar Considerations

The Jabber Registrar [2] shall include 'http://jabber.org/protocols/adress/list' in its registry of protocols.

The Jabber Registrar [3] shall create new registry for names of automatic lists.

15. XML Schema

TODO


Notes

1. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

2. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.

3. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.


Revision History

Version 0.0.1 (2006-06-01)

First draft.

(mv)


END