XEP-0051: Redirect and Connection Transfer

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

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

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
    </iq> 
    

Example 2. Redirection response to original query

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

Example 3. Redirected query

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

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.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.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'>
    <domain>jabber.org</domain>
    <server>123.123.123.122</server>
  </query>
</iq>

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'>
    <domain>jabber.org</domain>
    <server>server2.jabber.org</server>
  </query>
</iq>

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'>
    <domain>jabber.org</domain>
    <server>server3.jabber.org:6222</server>
  </query>
</iq>

Example 9. Server tells client to simply reconnect

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

Klaus Wolf

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

Richard Dobson

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

Copyright

Permissions

Disclaimer of Warranty

Limitation of Liability

IPR Conformance

Version 0.1 (2002-10-08)

Version 0.0.2 (2002-09-14)

Version 0.0.1 (2002-07-31)