Make the error domain and codes public and documented.

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|.