From 31bf8302c3077d624fe61f40efc8eb92702dc491 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 30 Aug 2017 17:04:49 -0700 Subject: [PATCH] Synchronize new proto changes. --- google/rpc/README.md | 2 +- google/rpc/code.proto | 18 ++++++++++++------ google/rpc/error_details.proto | 31 ++++++++++++++++++++++++++++++- google/rpc/status.proto | 10 +++++----- 4 files changed, 48 insertions(+), 13 deletions(-) diff --git a/google/rpc/README.md b/google/rpc/README.md index 3a612228..50988142 100644 --- a/google/rpc/README.md +++ b/google/rpc/README.md @@ -2,4 +2,4 @@ This package contains type definitions for general RPC systems. While [gRPC](https://github.com/grpc) is using these defintions, they -are not designed specifically to support gRPC. \ No newline at end of file +are not designed specifically to support gRPC. diff --git a/google/rpc/code.proto b/google/rpc/code.proto index 9a450956..8fef4117 100644 --- a/google/rpc/code.proto +++ b/google/rpc/code.proto @@ -1,4 +1,4 @@ -// Copyright 2016 Google Inc. +// Copyright 2017 Google Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -68,9 +68,12 @@ 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 rights to the entity, though such usage is - // discouraged. + // + // Note to server developers: if a request is denied for an entire class + // of users, such as gradual feature rollout or undocumented whitelist, + // `NOT_FOUND` may be used. If a request is denied for some users within + // a class of users, such as user-based access control, `PERMISSION_DENIED` + // must be used. // // HTTP Mapping: 404 Not Found NOT_FOUND = 5; @@ -86,7 +89,9 @@ enum Code { // 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). + // instead for those errors). This error code does not imply the + // request is valid or the requested entity exists or satisfies + // other pre-conditions. // // HTTP Mapping: 403 Forbidden PERMISSION_DENIED = 7; @@ -112,7 +117,8 @@ enum Code { // 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). + // (e.g., when a client-specified test-and-set fails, indicating the + // client should restart a read-modify-write sequence). // (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` diff --git a/google/rpc/error_details.proto b/google/rpc/error_details.proto index 4732d421..f24ae009 100644 --- a/google/rpc/error_details.proto +++ b/google/rpc/error_details.proto @@ -1,4 +1,4 @@ -// Copyright 2016 Google Inc. +// Copyright 2017 Google Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -86,6 +86,35 @@ message QuotaFailure { repeated Violation violations = 1; } +// Describes what preconditions have failed. +// +// For example, if an RPC failed because it required the Terms of Service to be +// acknowledged, it could list the terms of service violation in the +// PreconditionFailure message. +message PreconditionFailure { + // A message type used to describe a single precondition failure. + message Violation { + // The type of PreconditionFailure. We recommend using a service-specific + // enum type to define the supported precondition violation types. For + // example, "TOS" for "Terms of Service violation". + string type = 1; + + // The subject, relative to the type, that failed. + // For example, "google.com/cloud" relative to the "TOS" type would + // indicate which terms of service is being referenced. + string subject = 2; + + // A description of how the precondition failed. Developers can use this + // description to understand how to fix the failure. + // + // For example: "Terms of service not accepted". + string description = 3; + } + + // Describes all precondition violations. + repeated Violation violations = 1; +} + // Describes violations in a client request. This error type focuses on the // syntactic aspects of the request. message BadRequest { diff --git a/google/rpc/status.proto b/google/rpc/status.proto index bc6097b2..0839ee96 100644 --- a/google/rpc/status.proto +++ b/google/rpc/status.proto @@ -1,4 +1,4 @@ -// Copyright 2016 Google Inc. +// Copyright 2017 Google Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -42,7 +42,7 @@ option objc_class_prefix = "RPC"; // 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. +// in the package `google.rpc` that can be used for common error conditions. // // # Language mapping // @@ -65,7 +65,7 @@ option objc_class_prefix = "RPC"; // errors. // // - Workflow errors. A typical workflow has multiple steps. Each step may -// have a `Status` message for error reporting purpose. +// have a `Status` message for error reporting. // // - Batch operations. If a client uses batch request and batch response, the // `Status` message should be used directly inside batch response, one for @@ -86,7 +86,7 @@ message Status { // [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. string message = 2; - // A list of messages that carry the error details. There will be a - // common set of message types for APIs to use. + // A list of messages that carry the error details. There is a common set of + // message types for APIs to use. repeated google.protobuf.Any details = 3; }