Purpose

• A high level light weight document to explain client reaction to the various server headers and status codes
• This document is not intended as guide for planning or development. It is also not intended to detail programming code.
• This page is a 'Living Document.' It will change. It is intended to reflect functionality of production Sync servers and Sync client on mozilla-central. As such, it will need to be maintained to keep up with functional changes as they occur.

Questions and Comments

• Please feel free to add information requests inline (or fill gaps yourself)
• If you have questions or comments regarding this document, contact:

 Tracy Walker
 twalker@mozilla.com
 irc: tracy

Headers and status codes

The servers send headers and/or status codes in conditional response to various Sync client requests. The Sync client responds to those codes in a variety of ways depending on its state.

• Headers - http://docs.services.mozilla.com/storage/apis-1.1.html#headers
• HTTP status codes - http://docs.services.mozilla.com/storage/apis-1.1.html#http-status-codes

Client response to server communications

All 200 codes

Indicates success in processing a request. Sync should proceed normally.

401 code

Indicates username or password are invalid on this node. There are two possible sources and client reaction to them

• If the user's node has change, the current sync should abort and retry against the new node. This should be silent to the user.
• If the node hasn’t changed, the user’s password was changed. The client should present the error bar indicating the need for the user to update their password on that client. Preferences button takes the user to appropriate update password link.

404 code

Indicates a resource could not be found.

• How should the client react? (rnewman?)

All other 4XX codes

Will abort sync immediately. Error bar will be presented. User is on their own to resolve the problem. Note: this is a place where Syncorro could be immensely helpful.

503 code

Indicates server under maintenance. 99.9% of errors sent to the client are 503's.

Client Scenarios for handling 503 + Retry-After

• 1) When a "Sync Now" is performed by the user and a 503 + Retry-After is received.
  • The sync will fail
  • The client will present the error bar indicating the server is under maintenance and will try again later.
• 2) When an instant sync or a scheduled sync is triggered and a 503 + Retry-After is received.
  • The sync will fail
  • The client will not present an error bar
• In both cases:
  • Logs will indicate a fuzzed syncInterval
  • about:config services.sync.nextSync will be set to current time + syncInterval
  • No previously scheduled syncs will occur
  • No instant sync actions will trigger a sync during the back-off interval
  • Another Sync will be tried again at the set nextSync time
  • Subsequent failures and retries will be handled as above until a successful sync occurs or
  • If a successful sync does not occur within 7 days, an error bar will be presented.

Retry-After

The Retry-After header is used so that older clients (pre Fx10) will obey the back-off request. The response header sends a time (usually 300-900 seconds). This is the minimum time the client must wait until the next sync attempt. However, the client checks on its own state and calculates a "fuzzed" next sync interval that is always at least what the server requests. In most cases, the back off length of time will be notably longer.

X-Weave-Backoff

This request will only be respected by Fx10 or newer. The response header sends a time (usually 300-900 seconds). This is the minimum time the client must wait until the next sync attempt. However, the client checks on its own state and calculates a "fuzzed" next sync interval that is always at least what the server requests. In most cases, the back off length of time will be notably longer.

The client will react to X-Weave-Backoff the same as if it had been sent a 503 + Retry-After noted in the scenarios above.

X-If-Unmodified-Since

client response detail needed

X-Weave-Alert

client response detail needed

X-Weave-Timestamp

client response detail needed

X-Weave-Records

client response detail needed