From 20aad16919e882a7ffeb94cf31e2f2975223633a Mon Sep 17 00:00:00 2001 From: Ryan Kelly Date: Mon, 18 Nov 2013 15:44:32 +1100 Subject: [PATCH 1/3] Document basic backoff protocol. --- docs/api.md | 43 +++++++++++++++++++++++++++++++++++++++---- error.js | 6 ++++-- 2 files changed, 43 insertions(+), 6 deletions(-) diff --git a/docs/api.md b/docs/api.md index b1eec58aa..61b1cfc50 100644 --- a/docs/api.md +++ b/docs/api.md @@ -43,7 +43,7 @@ To simplify error handling for the client, the type of error is indicated both b ```js { "code": 400, // matches the HTTP status code - "errno": 107, // stable application level error number + "errno": 107, // stable application-level error number "error": "Bad Request", // string description of the error type "message": "the value of salt is not allowed to be undefined", "info": "https://docs.dev.lcip.og/errors/1234" // link to more info on the error @@ -68,13 +68,15 @@ The currently-defined error responses are: * status code 401, errno 115: invalid authentication nonce * status code 411, errno 112: content-length header was not provided * status code 413, errno 113: request body too large -* status code 429, errno 114: client has sent too many requests (see backoff protocol) -* status code 503, errno 201: service temporarily unavailable to due high load (see backoff protocol) +* status code 429, errno 114: client has sent too many requests (see [backoff protocol](#backoff-protocol)) +* status code 503, errno 201: service temporarily unavailable to due high load (see [backoff protocol](#backoff-protocol)) * any status code, errno 999: unknown error The follow error responses include additional parameters: * errno 111: a `serverTime` parameter giving the current server time in seconds. +* errno 114: a `retryAfter` parameter indicating how long the client should wait before re-trying. +* errno 201: a `retryAfter` parameter indicating how long the client should wait before re-trying. ## Responses from Intermediary Servers @@ -1312,7 +1314,40 @@ There are no standard failure modes for this endpoint. * GOTO "Attach a new device" -# Client Backoff Protocol +# Backoff Protocol + +During periods of heavy load, the auth server may request that clients enter a "backoff" state in which they avoid making further requests. + +If the server is under heavy load but is still able to satisfy the client's request, it will include a `Backoff` header in the HTTP response. The value is an integer number of seconds that the client should wait before issuing any further requests. For example, the following response would indicate that the server has successfully processed the request, but that the client should avoid sending additional requests for 20 seconds: + +``` +HTTP/1.1 200 OK +Backoff: 20 +Content-Type: application/json + +{} +``` + +If the server is under too much load to handle the client's request, it will return a `503 Service Unavailable` HTTP response. The response will include `Retry-After` header giving the number of seconds that the client should wait before issuing any further requests. It will also include a [JSON error response](#response-format) with `errno` of 201, and with a `retryAfter` field that matches the value in the `Retry-After` header. For example, the following response would indicate that the server could not process the request and the client should avoid sending additional requests for 30 seconds: + +``` +HTTP/1.1 503 Service Unavailable +Retry-After: 30 +Content-Type: application/json + +{ + "code": 503, + "errno": 201, + "error": "Service Unavailable", + "message": "The server is experiencing heavy load, please try again shortly", + "info": "https://github.com/mozilla/fxa-auth-server/blob/master/docs/api.md#response-format", + "retryAfter": 30 +} +``` + +The `Retry-After` value is included in both the headers and body so that clients can choose to handle it at the most appropriate level of abstraction for their environment. + +If an individual client is found to be issuing too many requests in quick succession, the server may return a `429 Too Many Requests` response. This is similar to the `503 Service Unavailable` response but indicates that the problem originates from the client's behavior, rather than the server. The response will include `Retry-After` header giving the number of seconds that the client should wait before issuing any further requests. It will also include a [JSON error response](#response-format) with `errno` of 114, and with a `retryAfter` field that matches the value in the `Retry-After` header. # Reference Client diff --git a/error.js b/error.js index 4ff17c6b2..addab80f3 100644 --- a/error.js +++ b/error.js @@ -199,7 +199,8 @@ Boom.tooManyRequests = function () { return Boom.wrap({ code: 429, errno: 114, - message: 'Client has sent too many requests' + message: 'Client has sent too many requests', + retryAfter: 30 }) } @@ -207,7 +208,8 @@ Boom.serviceUnavailable = function () { return Boom.wrap({ code: 503, errno: 201, - message: 'Service unavailable' + message: 'Service unavailable', + retryAfter: 30 }) } From 50076d9b9b8347a9ab87215e26ed7c8cf52c3334 Mon Sep 17 00:00:00 2001 From: Ryan Kelly Date: Tue, 19 Nov 2013 10:49:32 +1100 Subject: [PATCH 2/3] Add example "429 Too Many Requests" response to the docs. --- docs/api.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index 61b1cfc50..4f22d4f26 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1347,7 +1347,22 @@ Content-Type: application/json The `Retry-After` value is included in both the headers and body so that clients can choose to handle it at the most appropriate level of abstraction for their environment. -If an individual client is found to be issuing too many requests in quick succession, the server may return a `429 Too Many Requests` response. This is similar to the `503 Service Unavailable` response but indicates that the problem originates from the client's behavior, rather than the server. The response will include `Retry-After` header giving the number of seconds that the client should wait before issuing any further requests. It will also include a [JSON error response](#response-format) with `errno` of 114, and with a `retryAfter` field that matches the value in the `Retry-After` header. +If an individual client is found to be issuing too many requests in quick succession, the server may return a `429 Too Many Requests` response. This is similar to the `503 Service Unavailable` response but indicates that the problem originates from the client's behavior, rather than the server. The response will include `Retry-After` header giving the number of seconds that the client should wait before issuing any further requests. It will also include a [JSON error response](#response-format) with `errno` of 114, and with a `retryAfter` field that matches the value in the `Retry-After` header. For example: + +``` +HTTP/1.1 429 Too Many Requests +Retry-After: 30 +Content-Type: application/json + +{ + "code": 429, + "errno": 114, + "error": "Too Many Requests", + "message": "This client has sent too many requests", + "info": "https://github.com/mozilla/fxa-auth-server/blob/master/docs/api.md#response-format", + "retryAfter": 30 +} +``` # Reference Client From 358ba48e9d28cc7b3a1609c14f8ee7923a240792 Mon Sep 17 00:00:00 2001 From: Ryan Kelly Date: Tue, 19 Nov 2013 13:54:25 +1100 Subject: [PATCH 3/3] Remove Backoff header from protocol docs. --- docs/api.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/api.md b/docs/api.md index 4f22d4f26..3e9ef97a4 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1318,16 +1318,6 @@ There are no standard failure modes for this endpoint. During periods of heavy load, the auth server may request that clients enter a "backoff" state in which they avoid making further requests. -If the server is under heavy load but is still able to satisfy the client's request, it will include a `Backoff` header in the HTTP response. The value is an integer number of seconds that the client should wait before issuing any further requests. For example, the following response would indicate that the server has successfully processed the request, but that the client should avoid sending additional requests for 20 seconds: - -``` -HTTP/1.1 200 OK -Backoff: 20 -Content-Type: application/json - -{} -``` - If the server is under too much load to handle the client's request, it will return a `503 Service Unavailable` HTTP response. The response will include `Retry-After` header giving the number of seconds that the client should wait before issuing any further requests. It will also include a [JSON error response](#response-format) with `errno` of 201, and with a `retryAfter` field that matches the value in the `Retry-After` header. For example, the following response would indicate that the server could not process the request and the client should avoid sending additional requests for 30 seconds: ```