Skip to content

Latest commit

 

History

History
94 lines (77 loc) · 6.82 KB

0028-enhanced_error_messages.md

File metadata and controls

94 lines (77 loc) · 6.82 KB
Raw

Meta

  • RFC Name: Enhanced Error Messages
  • RFC ID: 0028
  • Start Date: 2017-04-24
  • Owner: Brett Lawson
  • Current Status: ACCEPTED

Summary

As of Couchbase Server 5.0.0, the server will be improving its error handling behaviours to enable the inclusion of additional, per-operation contextual information. This will take the form of JSON-formatted error objects included in the response body of server error responses. This change will not affect operations which already customize the error response body (multi-mutation subdocument operations when status code is SUCCESS (0x00) or SUBDOC_MULTI_PATH_FAILURE (0xCC), and NOT_MY_VBUCKET error responses for other operations).

The primary driver of this change is to enable correlation of security-sensitive authentication error context between the client and the server. This change will also enable the server to provide further detail to developers on the reason an operation has failed, beyond what is available with status codes alone.

Changelog

  • April 24 2017: Initial Draft

Description

The server will be switching to a new error response format (we no longer will receive text such as not_found). These responses will be encoded in the following format: { "error" : { "context" : "textual context information", "ref" : "error reference to be found in the server logs" }}. Each component of this error body will be optional, and if none of these optional fields are available, the error response will be blank. In addition, all JSON error responses will be tagged with the JSON data type bit to signal the client that the error response is parseable JSON. Note that in the case of no error body being returned (due to no additional error details being available), the JSON bit will NOT be set.

Should a client wish to log any particular error, they are are required to log all components of this enhanced error information. This log message MUST include the the error message as defined by the client as well as the context and ref fields from the error response body if they are defined. If the client does not have an error message defined for the status code received, it must include the status code directly along with any enhanced error information; clients may also optionally include the error code even if an error message is known. Clients MUST NOT include the response body within the log messages or client error objects if the the JSON bit is not set, or if the response body is empty.

In the case of SDKs which have an error wrapping object (Java and .NET Exception, Go error structures, etc…), the client MUST, at minimum include the additional context within the error message that would be displayed if the developer were to print the object directly. This string can be generated by concatenating all information that is available about an error, IE: "Client Error Message (Context: Server Error Context, Ref #: Server Error Reference)". Additionally, clients with error wrapping objects SHOULD include the additional information as individual, independent fields.

In the case of clients which do not have error wrapping objects, the clients may optionally include methods to fetch the additional information provided by the server for the most recent operation that failed (similar to errno()). This information is not required to be persisted any longer than what is reasonable for the client (i.e.: libcouchbase may only allow fetching the latest error information within the context of the error callback for the specific operation, or only until the next operation is dispatched or received).

Language Specifics

.NET

.NET creates a custom TemporaryLockFailureException if the response status is "TemporaryFailure" (0x0086) and the response body contains "lock_error". For backward compatibility, the response body must always be checked to see if the string is found, whether a direct string or in JSON.

Questions

  • (Brett) Won't the server context string being concatenated with the client-side error message cause a duplication of information in the final message? No. The server context string will never duplicate the information that is already provided by the error code, and will only include additional contextual information which is not represented by the error code itself. If no additional context information is available beyond what is represented by the error code, the server will simply omit that field.

  • (Brett) Won't this change mean that our error messages change between versions? The full error strings may change, but the initial client-message component will continue to be the same as it was before, and the enhanced error information will be concatenated to the end.

  • (Mark) Won't this mean that we will receive garbage or useless error contexts from older server versions? This specification states that we will only be utilizing error responses that are marked with the JSON bit, and that all other error responses (except in the case of already-customized handlers as indicated above) will be ignored and assumed not to convey any enhanced contextual information. Additionally, it's only expected to be used in situations where an error reply is not the most common path, so the additional memory usage won't be the bulk of the operations and meets a clear need for the users.

  • (Brett) Will this not cause older clients which used the response body to change their error messages, potentially causing backwards-compatibility issues? A: The only SDK affected by this RFC which is known to include the server-side response body in the error message is the .NET SDK, which will be treating this as a bug and will be correcting it to be in line with this SDK.

  • (Mark) How does this affect or get affected by the inclusion of KV Error Map features? This RFC is tangential to the KV Error Map RFC. The only overlap that exists being that the 'client error message' as described above, will come from the KV Error Map rather than from a static map in the client.

  • (Michael) any reason this is not behind a HELLO? The user-visible changes of this RFC are already behind a bit (the JSON bit). I'm not sure what benefit would be provided by putting it behind another flag.

  • (Matt) Should the error messages be documented as being volatile? Yes

Signoff

Language Representative Date
Java Michael N. 2017-05-05
C Mark N. 2017-04-26
Python Mark N. 2017-04-26
.NET Jeff M. 2017-04-22
node.js Brett L. 2017-04-22
PHP Sergey A. 2017-05-10
Go Brett L. 2017-04-22