From 16b971c46e2f6a9015a9faf60eb38e40c0133ff2 Mon Sep 17 00:00:00 2001 From: Ethan Bao Date: Tue, 28 Jul 2015 11:00:32 -0700 Subject: [PATCH] Update changes of google/rpc protos. --- google/rpc/README.md | 1 + google/rpc/code.proto | 104 ++++++++++++++++----------------- google/rpc/error_details.proto | 8 +-- google/rpc/status.proto | 24 ++++---- 4 files changed, 70 insertions(+), 67 deletions(-) diff --git a/google/rpc/README.md b/google/rpc/README.md index 7bd360817..aa8877db8 100644 --- a/google/rpc/README.md +++ b/google/rpc/README.md @@ -1,4 +1,5 @@ # Google RPC + This package contains type definitions for general RPC systems. While [gRPC](https://github.com/grpc) is using these defintions, but they are not designed specifically to support gRPC. diff --git a/google/rpc/code.proto b/google/rpc/code.proto index 03c803067..f9ceddcbc 100644 --- a/google/rpc/code.proto +++ b/google/rpc/code.proto @@ -18,7 +18,6 @@ package google.rpc; option java_multiple_files = true; option java_outer_classname = "CodeProto"; -option javanano_use_deprecated_package = true; option java_package = "com.google.rpc"; @@ -26,42 +25,42 @@ option java_package = "com.google.rpc"; // Warnings: // // - Do not change any numeric assignments. -// - Changes to this list should only be made if there is a compelling +// - Changes to this list should be made only if there is a compelling // need that can't be satisfied in another way. // // Sometimes multiple error codes may apply. Services should return // the most specific error code that applies. For example, prefer -// OUT_OF_RANGE over FAILED_PRECONDITION if both codes apply. -// Similarly prefer NOT_FOUND or ALREADY_EXISTS over FAILED_PRECONDITION. +// `OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply. +// Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`. enum Code { // Not an error; returned on success // // HTTP Mapping: 200 OK OK = 0; - // The operation was cancelled (typically by the caller). + // The operation was cancelled, typically by the caller. // // HTTP Mapping: 499 Client Closed Request CANCELLED = 1; - // Unknown error. An example of where this error may be returned is - // if a Status value received from another address space belongs to - // an error-space that is not known in this address space. Also + // Unknown error. For example, this error may be returned when + // a `Status` value received from another address space belongs to + // an error space that is not known in this address space. Also // errors raised by APIs that do not return enough error information // may be converted to this error. // // HTTP Mapping: 500 Internal Server Error UNKNOWN = 2; - // Client specified an invalid argument. Note that this differs - // from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments + // The client specified an invalid argument. Note that this differs + // from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments // that are problematic regardless of the state of the system // (e.g., a malformed file name). // // HTTP Mapping: 400 Bad Request INVALID_ARGUMENT = 3; - // Deadline expired before operation could complete. For operations + // The deadline expired before the operation could complete. For operations // that change the state of the system, this error may be returned // even if the operation has completed successfully. For example, a // successful response from a server could have been delayed long @@ -71,23 +70,23 @@ enum Code { DEADLINE_EXCEEDED = 4; // Some requested entity (e.g., file or directory) was not found. - // For privacy reasons, this code *may* be returned when the client - // does not have the access right to the entity. + // For privacy reasons, this code *might* be returned when the client + // does not have the access rights to the entity. // // HTTP Mapping: 404 Not Found NOT_FOUND = 5; - // Some entity that we attempted to create (e.g., file or directory) + // The entity that a client attempted to create (e.g., file or directory) // already exists. // // HTTP Mapping: 409 Conflict ALREADY_EXISTS = 6; // The caller does not have permission to execute the specified - // operation. PERMISSION_DENIED must not be used for rejections - // caused by exhausting some resource (use RESOURCE_EXHAUSTED - // instead for those errors). PERMISSION_DENIED must not be - // used if the caller can not be identified (use UNAUTHENTICATED + // operation. `PERMISSION_DENIED` must not be used for rejections + // caused by exhausting some resource (use `RESOURCE_EXHAUSTED` + // instead for those errors). `PERMISSION_DENIED` must not be + // used if the caller can not be identified (use `UNAUTHENTICATED` // instead for those errors). // // HTTP Mapping: 403 Forbidden @@ -105,80 +104,81 @@ enum Code { // HTTP Mapping: 429 Too Many Requests RESOURCE_EXHAUSTED = 8; - // Operation was rejected because the system is not in a state - // required for the operation's execution. For example, directory - // to be deleted may be non-empty, an rmdir operation is applied to + // The operation was rejected because the system is not in a state + // required for the operation's execution. For example, the directory + // to be deleted is non-empty, an rmdir operation is applied to // a non-directory, etc. // - // A litmus test that may help a service implementor in deciding - // between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: - // (a) Use UNAVAILABLE if the client can retry just the failing call. - // (b) Use ABORTED if the client should retry at a higher-level + // Service implementors can use the following guidelines to decide + // between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`: + // (a) Use `UNAVAILABLE` if the client can retry just the failing call. + // (b) Use `ABORTED` if the client should retry at a higher level // (e.g., restarting a read-modify-write sequence). - // (c) Use FAILED_PRECONDITION if the client should not retry until + // (c) Use `FAILED_PRECONDITION` if the client should not retry until // the system state has been explicitly fixed. E.g., if an "rmdir" - // fails because the directory is non-empty, FAILED_PRECONDITION + // fails because the directory is non-empty, `FAILED_PRECONDITION` // should be returned since the client should not retry unless - // they have first fixed up the directory by deleting files from it. - // (d) Use FAILED_PRECONDITION if the client performs conditional + // the files are deleted from the directory. + // (d) Use `FAILED_PRECONDITION` if the client performs conditional // REST Get/Update/Delete on a resource and the resource on the // server does not match the condition. E.g., conflicting // read-modify-write on the same resource. // // HTTP Mapping: 400 Bad Request // - // NOTE: HTTP spec says 412 Precondition Failed should only be used if - // the request contains Etag related headers. So if the server does see - // Etag related headers in the request, it may choose to return 412 + // NOTE: HTTP spec says `412 Precondition Failed` should be used only if + // the request contains Etag-related headers. So if the server does see + // Etag-related headers in the request, it may choose to return 412 // instead of 400 for this error code. FAILED_PRECONDITION = 9; - // The operation was aborted, typically due to a concurrency issue - // like sequencer check failures, transaction aborts, etc. + // The operation was aborted, typically due to a concurrency issue such as + // a sequencer check failure or transaction abort. // - // See litmus test above for deciding between FAILED_PRECONDITION, - // ABORTED, and UNAVAILABLE. + // See the guidelines above for deciding between `FAILED_PRECONDITION`, + // `ABORTED`, and `UNAVAILABLE`. // // HTTP Mapping: 409 Conflict ABORTED = 10; - // Operation was attempted past the valid range. E.g., seeking or - // reading past end of file. + // The operation was attempted past the valid range. E.g., seeking or + // reading past end-of-file. // - // Unlike INVALID_ARGUMENT, this error indicates a problem that may + // Unlike `INVALID_ARGUMENT`, this error indicates a problem that may // be fixed if the system state changes. For example, a 32-bit file - // system will generate INVALID_ARGUMENT if asked to read at an + // system will generate `INVALID_ARGUMENT` if asked to read at an // offset that is not in the range [0,2^32-1], but it will generate - // OUT_OF_RANGE if asked to read from an offset past the current + // `OUT_OF_RANGE` if asked to read from an offset past the current // file size. // - // There is a fair bit of overlap between FAILED_PRECONDITION and - // OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific + // There is a fair bit of overlap between `FAILED_PRECONDITION` and + // `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific // error) when it applies so that callers who are iterating through - // a space can easily look for an OUT_OF_RANGE error to detect when + // a space can easily look for an `OUT_OF_RANGE` error to detect when // they are done. // // HTTP Mapping: 400 Bad Request OUT_OF_RANGE = 11; - // Operation is not implemented or not supported/enabled in this service. + // The operation is not implemented or is not supported/enabled in this + // service. // // HTTP Mapping: 501 Not Implemented UNIMPLEMENTED = 12; - // Internal errors. Means some invariants expected by underlying - // system has been broken. If you see one of these errors, - // something is very broken. + // Internal errors. This means that some invariants expected by the + // underlying system have been broken. This error code is reserved + // for serious errors. // // HTTP Mapping: 500 Internal Server Error INTERNAL = 13; - // The service is currently unavailable. This is a most likely a - // transient condition and may be corrected by retrying with + // The service is currently unavailable. This is most likely a + // transient condition, which can be corrected by retrying with // a backoff. // - // See litmus test above for deciding between FAILED_PRECONDITION, - // ABORTED, and UNAVAILABLE. + // See the guidelines above for deciding between `FAILED_PRECONDITION`, + // `ABORTED`, and `UNAVAILABLE`. // // HTTP Mapping: 503 Service Unavailable UNAVAILABLE = 14; diff --git a/google/rpc/error_details.proto b/google/rpc/error_details.proto index e0a7b5587..82472b8b2 100644 --- a/google/rpc/error_details.proto +++ b/google/rpc/error_details.proto @@ -75,7 +75,7 @@ message QuotaFailure { // public documentation, or find the relevant quota limit to adjust through // developer console. // - // For example: "Service disabled" or "Daily Limit for read opetions + // For example: "Service disabled" or "Daily Limit for read operations // exceeded". string description = 2; } @@ -118,15 +118,15 @@ message RequestInfo { message ResourceInfo { // A name for the type of resource being accessed, e.g. "sql table", // "cloud storage bucket", "file", "Google calendar"; or the type URL - // of the resource: e.g. "https://types.googleapis.com/com.google.Calendar". + // of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic". string resource_type = 1; // The name of the resource being accessed. For example, a shared calendar // name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current - // error is PERMISSION_DENIED. + // error is [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED]. string resource_name = 2; - // The owner of the resource. + // The owner of the resource (optional). // For example, "user:" or "project:". string owner = 3; diff --git a/google/rpc/status.proto b/google/rpc/status.proto index be97fa4ea..8fca6ab22 100644 --- a/google/rpc/status.proto +++ b/google/rpc/status.proto @@ -23,25 +23,27 @@ option java_outer_classname = "StatusProto"; option java_package = "com.google.rpc"; -// The `Status` defines a logical error model that is suitable for different +// The `Status` type defines a logical error model that is suitable for different // programming environments, including REST APIs and RPC APIs. It is used by // [gRPC](https://github.com/grpc). The error model is designed to be: // -// - Simple to use and understand for most users. -// - Flexible enough to meet unexpected needs. +// - Simple to use and understand for most users +// - Flexible enough to meet unexpected needs // // # Overview -// The `Status` message contains 3 pieces of data: error code, error message, +// +// The `Status` message contains three pieces of data: error code, error message, // and error details. The error code should be an enum value of // [google.rpc.Code][google.rpc.Code], but it may accept additional error codes if needed. The // error message should be a developer-facing English message that helps // developers *understand* and *resolve* the error. If a localized user-facing -// error message is needed, it can be sent in the error details or localized by -// the client. The optional error details may contain arbitrary information -// about the error. There is a predefined set of error detail types in the -// package `google.rpc` which can be used for common error conditions. +// error message is needed, put the localized message in the error details or +// localize it in the client. The optional error details may contain arbitrary +// information about the error. There is a predefined set of error detail types +// in the package `google.rpc` which can be used for common error conditions. // // # Language mapping +// // The `Status` message is the logical representation of the error model, but it // is not necessarily the actual wire format. When the `Status` message is // exposed in different client libraries and different wire protocols, it can be @@ -49,9 +51,10 @@ option java_package = "com.google.rpc"; // in Java, but more likely mapped to some error codes in C. // // # Other uses +// // The error model and the `Status` message can be used in a variety of -// environments - either with or without APIs - to provide consistent developer -// experience across different environments. +// environments, either with or without APIs, to provide a +// consistent developer experience across different environments. // // Example uses of this error model include: // @@ -72,7 +75,6 @@ option java_package = "com.google.rpc"; // // - Logging. If some API errors are stored in logs, the message `Status` could // be used directly after any stripping needed for security/privacy reasons. -// message Status { // The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. int32 code = 1;