1 /* 2 * 3 * Copyright 2019 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #import <Foundation/Foundation.h> 20 21 /** 22 * gRPC error codes. 23 * Note that a few of these are never produced by the gRPC libraries, but are of 24 * general utility for server applications to produce. 25 */ 26 typedef NS_ENUM(NSUInteger, GRPCErrorCode) { 27 /** The operation was cancelled (typically by the caller). */ 28 GRPCErrorCodeCancelled = 1, 29 30 /** 31 * Unknown error. Errors raised by APIs that do not return enough error 32 * information may be converted to this error. 33 */ 34 GRPCErrorCodeUnknown = 2, 35 36 /** 37 * The client specified an invalid argument. Note that this differs from 38 * FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are 39 * problematic regardless of the state of the server (e.g., a malformed file 40 * name). 41 */ 42 GRPCErrorCodeInvalidArgument = 3, 43 44 /** 45 * Deadline expired before operation could complete. For operations that 46 * change the state of the server, this error may be returned even if the 47 * operation has completed successfully. For example, a successful response 48 * from the server could have been delayed long enough for the deadline to 49 * expire. 50 */ 51 GRPCErrorCodeDeadlineExceeded = 4, 52 53 /** Some requested entity (e.g., file or directory) was not found. */ 54 GRPCErrorCodeNotFound = 5, 55 56 /** Some entity that we attempted to create (e.g., file or directory) already 57 exists. */ 58 GRPCErrorCodeAlreadyExists = 6, 59 60 /** 61 * The caller does not have permission to execute the specified operation. 62 * PERMISSION_DENIED isn't used for rejections caused by exhausting some 63 * resource (RESOURCE_EXHAUSTED is used instead for those errors). 64 * PERMISSION_DENIED doesn't indicate a failure to identify the caller 65 * (UNAUTHENTICATED is used instead for those errors). 66 */ 67 GRPCErrorCodePermissionDenied = 7, 68 69 /** 70 * The request does not have valid authentication credentials for the 71 * operation (e.g. the caller's identity can't be verified). 72 */ 73 GRPCErrorCodeUnauthenticated = 16, 74 75 /** Some resource has been exhausted, perhaps a per-user quota. */ 76 GRPCErrorCodeResourceExhausted = 8, 77 78 /** 79 * The RPC was rejected because the server is not in a state required for the 80 * procedure's execution. For example, a directory to be deleted may be 81 * non-empty, etc. The client should not retry until the server state has been 82 * explicitly fixed (e.g. by performing another RPC). The details depend on 83 * the service being called, and should be found in the NSError's userInfo. 84 */ 85 GRPCErrorCodeFailedPrecondition = 9, 86 87 /** 88 * The RPC was aborted, typically due to a concurrency issue like sequencer 89 * check failures, transaction aborts, etc. The client should retry at a 90 * higher-level (e.g., restarting a read- modify-write sequence). 91 */ 92 GRPCErrorCodeAborted = 10, 93 94 /** 95 * The RPC was attempted past the valid range. E.g., enumerating past the end 96 * of a list. Unlike INVALID_ARGUMENT, this error indicates a problem that may 97 * be fixed if the system state changes. For example, an RPC to get elements 98 * of a list will generate INVALID_ARGUMENT if asked to return the element at 99 * a negative index, but it will generate OUT_OF_RANGE if asked to return the 100 * element at an index past the current size of the list. 101 */ 102 GRPCErrorCodeOutOfRange = 11, 103 104 /** The procedure is not implemented or not supported/enabled in this server. 105 */ 106 GRPCErrorCodeUnimplemented = 12, 107 108 /** 109 * Internal error. Means some invariant expected by the server application or 110 * the gRPC library has been broken. 111 */ 112 GRPCErrorCodeInternal = 13, 113 114 /** 115 * The server is currently unavailable. This is most likely a transient 116 * condition and may be corrected by retrying with a backoff. Note that it is 117 * not always safe to retry non-idempotent operations. 118 */ 119 GRPCErrorCodeUnavailable = 14, 120 121 /** Unrecoverable data loss or corruption. */ 122 GRPCErrorCodeDataLoss = 15, 123 }; 124 125 /** 126 * Safety remark of a gRPC method as defined in RFC 2616 Section 9.1 127 */ 128 typedef NS_ENUM(NSUInteger, GRPCCallSafety) { 129 /** 130 * Signal that there is no guarantees on how the call affects the server 131 * state. 132 */ 133 GRPCCallSafetyDefault = 0, 134 }; 135 136 /** 137 * Compression algorithm to be used by a gRPC call. 138 * 139 * <b>This enumeration and corresponding call option GRPCCallOptions.transportType are deprecated by 140 * the call option GRPCCallOptions.transport. </b> 141 */ 142 typedef NS_ENUM(NSUInteger, GRPCCompressionAlgorithm) { 143 GRPCCompressNone = 0, 144 GRPCCompressDeflate, 145 GRPCCompressGzip, 146 GRPCStreamCompressGzip, 147 }; 148 149 /** GRPCCompressAlgorithm is deprecated. */ 150 typedef GRPCCompressionAlgorithm GRPCCompressAlgorithm; 151 152 /** The transport to be used by a gRPC call */ 153 typedef NS_ENUM(NSUInteger, GRPCTransportType) { 154 GRPCTransportTypeDefault = 0, 155 /** gRPC internal HTTP/2 stack with BoringSSL */ 156 GRPCTransportTypeChttp2BoringSSL = 0, 157 /** Cronet stack */ 158 GRPCTransportTypeCronet, 159 /** Insecure channel. FOR TEST ONLY! */ 160 GRPCTransportTypeInsecure, 161 }; 162 163 /** Domain of NSError objects produced by gRPC. */ 164 extern NSString* _Nonnull const kGRPCErrorDomain; 165 166 /** 167 * Keys used in |NSError|'s |userInfo| dictionary to store the response headers 168 * and trailers sent by the server. 169 */ 170 extern NSString* _Nonnull const kGRPCHeadersKey; 171 extern NSString* _Nonnull const kGRPCTrailersKey; 172 173 /** The id of a transport implementation. */ 174 typedef const char* _Nonnull GRPCTransportID; 175 176 /** 177 * Implement this protocol to provide a token to gRPC when a call is initiated. 178 */ 179 @protocol GRPCAuthorizationProtocol 180 181 /** 182 * This method is called when gRPC is about to start the call. When OAuth token is acquired, 183 * \a handler is expected to be called with \a token being the new token to be used for this call. 184 */ 185 - (void)getTokenWithHandler:(void (^_Nonnull)(NSString* _Nullable token))handler; 186 187 @end 188 189 /** gRPC metadata dictionary typedef */ 190 typedef NSDictionary<NSString*, id> GRPCMetadataDictionary; 191