From c57b764fef30b0e6a01866f43ef888998abeb39d Mon Sep 17 00:00:00 2001
From: Jorge Canizales <jcanizales@google.com>
Date: Thu, 3 Sep 2015 03:42:02 -0700
Subject: [PATCH] Make the error domain and codes public and documented.
---
src/objective-c/GRPCClient/GRPCCall.h | 82 +++++++++++++++++++
.../GRPCClient/private/NSError+GRPC.h | 23 ------
2 files changed, 82 insertions(+), 23 deletions(-)
diff --git a/src/objective-c/GRPCClient/GRPCCall.h b/src/objective-c/GRPCClient/GRPCCall.h
index 4eda499b1a..b2968b8e98 100644
--- a/src/objective-c/GRPCClient/GRPCCall.h
+++ b/src/objective-c/GRPCClient/GRPCCall.h
@@ -48,11 +48,93 @@
#import <Foundation/Foundation.h>
#import <RxLibrary/GRXWriter.h>
+#pragma mark gRPC errors
+
+// Domain of NSError objects produced by gRPC.
+extern NSString *const kGRPCErrorDomain;
+
+// gRPC error codes.
+// Note that a few of these are never produced by the gRPC libraries, but are of general utility for
+// server applications to produce.
+typedef NS_ENUM(NSUInteger, GRPCErrorCode) {
+ // The operation was cancelled (typically by the caller).
+ GRPCErrorCodeCancelled = 1,
+
+ // Unknown error. Errors raised by APIs that do not return enough error information may be
+ // converted to this error.
+ GRPCErrorCodeUnknown = 2,
+
+ // 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
+ // server (e.g., a malformed file name).
+ GRPCErrorCodeInvalidArgument = 3,
+
+ // Deadline expired before operation could complete. For operations that change the state of the
+ // server, this error may be returned even if the operation has completed successfully. For
+ // example, a successful response from the server could have been delayed long enough for the
+ // deadline to expire.
+ GRPCErrorCodeDeadlineExceeded = 4,
+
+ // Some requested entity (e.g., file or directory) was not found.
+ GRPCErrorCodeNotFound = 5,
+
+ // Some entity that we attempted to create (e.g., file or directory) already exists.
+ GRPCErrorCodeAlreadyExists = 6,
+
+ // The caller does not have permission to execute the specified operation. PERMISSION_DENIED isn't
+ // used for rejections caused by exhausting some resource (RESOURCE_EXHAUSTED is used instead for
+ // those errors). PERMISSION_DENIED doesn't indicate a failure to identify the caller
+ // (UNAUTHENTICATED is used instead for those errors).
+ GRPCErrorCodePermissionDenied = 7,
+
+ // The request does not have valid authentication credentials for the operation (e.g. the caller's
+ // identity can't be verified).
+ GRPCErrorCodeUnauthenticated = 16,
+
+ // Some resource has been exhausted, perhaps a per-user quota.
+ GRPCErrorCodeResourceExhausted = 8,
+
+ // The RPC was rejected because the server is not in a state required for the procedure's
+ // execution. For example, a directory to be deleted may be non-empty, etc.
+ // The client should not retry until the server state has been explicitly fixed (e.g. by
+ // performing another RPC). The details depend on the service being called, and should be found in
+ // the NSError's userInfo.
+ GRPCErrorCodeFailedPrecondition = 9,
+
+ // The RPC was aborted, typically due to a concurrency issue like sequencer check failures,
+ // transaction aborts, etc. The client should retry at a higher-level (e.g., restarting a read-
+ // modify-write sequence).
+ GRPCErrorCodeAborted = 10,
+
+ // The RPC was attempted past the valid range. E.g., enumerating past the end of a list.
+ // Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state
+ // changes. For example, an RPC to get elements of a list will generate INVALID_ARGUMENT if asked
+ // to return the element at a negative index, but it will generate OUT_OF_RANGE if asked to return
+ // the element at an index past the current size of the list.
+ GRPCErrorCodeOutOfRange = 11,
+
+ // The procedure is not implemented or not supported/enabled in this server.
+ GRPCErrorCodeUnimplemented = 12,
+
+ // Internal error. Means some invariant expected by the server application or the gRPC library has
+ // been broken.
+ GRPCErrorCodeInternal = 13,
+
+ // The server is currently unavailable. This is most likely a transient condition and may be
+ // corrected by retrying with a backoff.
+ GRPCErrorCodeUnavailable = 14,
+
+ // Unrecoverable data loss or corruption.
+ GRPCErrorCodeDataLoss = 15,
+};
+
// Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by
// the server.
extern id const kGRPCHeadersKey;
extern id const kGRPCTrailersKey;
+#pragma mark GRPCCall
+
// Represents a single gRPC remote call.
@interface GRPCCall : GRXWriter
diff --git a/src/objective-c/GRPCClient/private/NSError+GRPC.h b/src/objective-c/GRPCClient/private/NSError+GRPC.h
index e712791271..f4729dc8a1 100644
--- a/src/objective-c/GRPCClient/private/NSError+GRPC.h
+++ b/src/objective-c/GRPCClient/private/NSError+GRPC.h
@@ -34,29 +34,6 @@
#import <Foundation/Foundation.h>
#include <grpc/grpc.h>
-// TODO(jcanizales): Make the domain string public.
-extern NSString *const kGRPCErrorDomain;
-
-// TODO(jcanizales): Make this public and document each code.
-typedef NS_ENUM(NSInteger, GRPCErrorCode) {
- GRPCErrorCodeCancelled = 1,
- GRPCErrorCodeUnknown = 2,
- GRPCErrorCodeInvalidArgument = 3,
- GRPCErrorCodeDeadlineExceeded = 4,
- GRPCErrorCodeNotFound = 5,
- GRPCErrorCodeAlreadyExists = 6,
- GRPCErrorCodePermissionDenied = 7,
- GRPCErrorCodeUnauthenticated = 16,
- GRPCErrorCodeResourceExhausted = 8,
- GRPCErrorCodeFailedPrecondition = 9,
- GRPCErrorCodeAborted = 10,
- GRPCErrorCodeOutOfRange = 11,
- GRPCErrorCodeUnimplemented = 12,
- GRPCErrorCodeInternal = 13,
- GRPCErrorCodeUnavailable = 14,
- GRPCErrorCodeDataLoss = 15
-};
-
@interface NSError (GRPC)
// Returns nil if the status code is OK. Otherwise, a NSError whose code is one of |GRPCErrorCode|
// and whose domain is |kGRPCErrorDomain|.
--
GitLab