XEP-0051: Redirect and Connection Transfer

Abstract:This document describes redirection of Jabber queries, and a method to replace the current (non standard) use of 302 to redirect connections.
Authors:Klaus Wolf, Richard Dobson
Copyright:© 1999 - 2009 XMPP Standards Foundation. SEE LEGAL NOTICES.
Type:Standards Track
Last Updated:2002-10-08

WARNING: Consideration of this document has been Deferred by the XMPP Standards Foundation. Implementation of the protocol described herein is not recommended.

Table of Contents

1. Introduction
2. IQ Redirect
    2.1. Introduction
    2.2. Scenario
    2.3. Redirection Message
    2.4. Examples
    2.5. Scope and Validity
    2.6. Repeated Redirections
    2.7. Implementation Note
3. Server Transfer
    3.1. Introduction
    3.2. Scenarios
       3.2.1. Scenario 1
       3.2.2. Scenario 2
       3.2.3. Scenario 3
    3.3. Server Transfer Packet
    3.4. Examples

    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History

1. Introduction

To be written.

2. IQ Redirect

2.1 Introduction

This document describes a general request redirection mechanism for Jabber queries.

There are cases where only the receiver of a query, e.g. the receiver of <iq type='get'/> requests, knows the real location of the targeted data object. Reasons might be load balancing, changes in the protocol and/or usage patterns, or an additional level of indirection for improved flexibility. The possible reasons are very similar to reasons for (temporary) HTTP redirection.

Redirection adds an additional feature to the protocol. But it also adds also a small amount of complexity to implementations. The mechanism has been designed in a way such that it affects implementations only minimally while providing maximum flexibility.

For security reasons the redirection mechanism is only valid for <iq type='get'/> packets.

2.2 Scenario

A client sends a query to a server. The server may well be an other client acting as a server for this transaction. The server decides that it can not serve the original request. It redirects the request to an other server. In order to do so, it sends a redirection query to the client. The redirection query informs the client about the modified query including the new destination. The client then repeats the request by sending the redirected query to other server.

2.3 Redirection Message

The meaning of <iq/> queries is specified by multiple parameters, i.e. JID, <query/> namespace, and namespace specific tags and attributes. Many of these parameters may change during the redirection. To allow for maximum flexibility, the redirection query contains the complete redirected query.

The redirection query is identified by the "type" attribute and by the code of an embedded <error/> tag. The code is "302". The redirection is meant to be temporary, not permanent.

The original query is returned as a child of the <iq type='error'/>.

The redirected query sent from the server back to the client is embedded into the <error/> tag.

The envelope of the redirected query must preserve all attributes of the initial query except for the destination JID ("to" attribute). In particular, it must preserve the "id" attribute.

The must not redirect any query other than <iq type='get'/>.

The redirected query may target a different entity than the original query and it may have different parameters. But the redirected query must be manufactured in such a way that the result returned from the redirected query is compatible with the original query.

2.4 Examples

Example 1. The original query which will be redirected

    <iq type='get' from='jid-A' to='jid-B'>
      original query

Example 2. Redirection response to original query

    <iq type='error' from='jid-B' to='jid-A'>
      original query
      <error code='302'>redirection message</error> 

Example 3. Redirected query

    <iq type='get' from='jid-A' to='jid-C'>
      redirected query

Example 4. A simple redirection which changes the destination JID

A: <iq id='5' type='get' from='user@server-A' to='user@server-B> 
A:   <query xmlns='jabber:iq:browse'/> 
A: </iq> 

B: <iq type='error' from='user@server-B' to='user@server-A'>
B:   <query xmlns='jabber:iq:browse'/>
B:   <error code='302'>
B:     <iq id='5' type='get' to='user@server-C'> 
B:       <query xmlns='jabber:iq:browse'/> 
B:     </iq> 
B:   </error>
B: </iq> 

A: <iq id='5' type='get' from='user@server-A' to='user@server-C'> 
A:   <query xmlns='jabber:iq:browse'/> 
A: </iq> 

Example 5. A redirection which changes a client-client data request to client-storage

A: <iq id='5' type='get' from='user@server-A' to='user@server-B/work'> 
A:   <query xmlns='jabber:iq:app-specific'/> 
A: </iq> 

B: <iq type='error' from='user@server-B/work' to='user@server-A'> 
B:   <query xmlns='jabber:iq:app-specific'/>
B:   <error code='302'>
B:     <iq id='5' type='get' to='user@server-B'> 
B:       <query xmlns='storage:client:app-specific'/> 
B:     </iq> 
B:   </error>
B: </iq> 

A: <iq id='5' type='get' from='user@server-A' to='user@server-B'> 
A:   <query xmlns='storage:client:app-specific'/> 
A: </iq> 

2.5 Scope and Validity

The client must check the redirected query. The redirected query is valid only if all three of the following conditions are met:

  1. the original query is <iq type='get'/>
  2. the redirected query is <iq type='get'/>
  3. the <iq/> envelope of the redirected query has all attributes of the original query except for the "to" attribute

2.6 Repeated Redirections

If redirections are cascaded then the client should stop the sequence after a reasonable number of redirections. Three consecutive redirects, which make a total of four trials, should be enough.

Applications must not rely on more than three consecutive redirections for a single query.

2.7 Implementation Note

The redirection mechanism can be implemented transparently for the protocol engine. The client should unwrap the redirected query, check for validity, and send the data to the connection.

Protocol implementations do not have to create a new request context. The request context of the original query will still be valid since the redirector must preserve the query id.

The query id is often used by the protocol engine to relate queries sent and queries received in order to form request-response pairs. Using the query id the client can find the related original query when the result of the redirected query returns.

However, the client must check the validity before re-sending the redirected query.

3. Server Transfer

3.1 Introduction

This document describes a connection transfer mechanism for telling clients (or others) to reconnect to a different address.

This is useful for transfering people to a different server in a cluster if it is going down for maintenance or during login to transfer the person to a certain server in a cluster.

3.2 Scenarios

3.2.1 Scenario 1

A server needs to be shutdown for maintenance by an administrator but there are other servers available in the cluster and the administrator wants to cause the least disruption possible by having the users automatically reconnect to one of the other available servers.

3.2.2 Scenario 2

Users of a Jabber cluster are hosted on particular servers, the server the user has connected to is not their server in the cluster, so the server redirects the user to connect to the correct server.

3.2.3 Scenario 3

A new server is brought online in the cluster. To reduce the load on the other servers and to balance out the load, the other servers direct some of their users to connect to the new server.

3.3 Server Transfer Packet

The transfer packet is addressed to the user from the domain they are logged into, it contains the server address to connect to which can be domain name or ip address, it can also contain an optional port number. There is also the domain specified just in case they have to use a different domain name when they log in or to maintain the original domain.

3.4 Examples

Example 6. Server tells client to connect to a different server in the cluster (by ip address)

<iq type='set' from='jabber.org' to='user@jabber.org'> 
  <query xmlns='jabber:iq:srvxfr'>

Example 7. Server tells client to connect to a different server in the cluster (by domain name)

<iq type='set' from='jabber.org' to='user@jabber.org'> 
  <query xmlns='jabber:iq:srvxfr'>

Example 8. Server tells client to connect to a different server in the cluster (using a different port number)

<iq type='set' from='jabber.org' to='user@jabber.org'> 
  <query xmlns='jabber:iq:srvxfr'>

Example 9. Server tells client to simply reconnect

<iq type='set' from='jabber.org' to='user@jabber.org'> 
  <query xmlns='jabber:iq:srvxfr'>


Appendix A: Document Information

Series: XEP
Number: 0051
Publisher: XMPP Standards Foundation
Status: Deferred
Type: Standards Track
Version: 0.1
Last Updated: 2002-10-08
Approving Body: XMPP Council
Dependencies: None
Supersedes: None
Superseded By: None
Short Name:
Source Control: HTML  RSS

Appendix B: Author Information

Klaus Wolf

Email: wolf@bluehands.de
JabberID: klaus@jabber.bluehands.de

Richard Dobson

Email: richard@dobson-i.net
JabberID: richard@dobson-i.net

Appendix C: Legal Notices



Disclaimer of Warranty

Limitation of Liability

IPR Conformance

Appendix D: 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 XMPP Standards 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 document 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.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata may be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

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

Appendix G: Notes

Appendix H: Revision History

Version 0.1 (2002-10-08)

Initial version. (psa)

Version 0.0.2 (2002-09-14)

Added the server transfer section. (rd)

Version 0.0.1 (2002-07-31)

Initial version. (hw)