1 /* 2 * 3 * Copyright 2018 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 #import "GRPCTypes.h" 22 23 NS_ASSUME_NONNULL_BEGIN 24 25 @protocol GRPCInterceptorFactory; 26 27 /** 28 * Immutable user configurable options for a gRPC call. 29 * Caller can obtain a mutable copy of type \b GRPCMutableCallOptions by calling [option 30 * mutableCopy] 31 */ 32 @interface GRPCCallOptions : NSObject <NSCopying, NSMutableCopying> 33 34 // Call parameters 35 /** 36 * The authority for the RPC. If nil, the default authority will be used. 37 * 38 * Note: This property does not have effect on Cronet transport and will be ignored. 39 * Note: This property cannot be used to validate a self-signed server certificate. It control the 40 * :authority header field of the call and performs an extra check that server's certificate 41 * matches the :authority header. 42 */ 43 @property(nonatomic, copy, readonly, nullable) NSString *serverAuthority; 44 45 /** 46 * The timeout for the RPC call in seconds. If set to 0, the call will not timeout. If set to 47 * positive, the gRPC call returns with status GRPCErrorCodeDeadlineExceeded if it is not completed 48 * within \a timeout seconds. A negative value is not allowed. 49 */ 50 @property(nonatomic, readonly) NSTimeInterval timeout; 51 52 /** 53 * Enable flow control of a gRPC call. The option is default to NO. If set to YES, writeData: method 54 * should only be called at most once before a didWriteData callback is issued, and 55 * receiveNextMessage: must be called each time before gRPC call issues a didReceiveMessage 56 * callback. 57 */ 58 @property(nonatomic, readonly) BOOL flowControlEnabled; 59 60 /** 61 * An array of interceptor factories. When a call starts, interceptors are created 62 * by these factories and chained together with the same order as the factories in 63 * this array. This parameter should not be modified by any interceptor and will 64 * not take effect if done so. 65 */ 66 @property(nonatomic, copy, readonly) NSArray<id<GRPCInterceptorFactory>> *interceptorFactories; 67 68 // OAuth2 parameters. Users of gRPC may specify one of the following two parameters. 69 70 /** 71 * The OAuth2 access token string. The string is prefixed with "Bearer " then used as value of the 72 * request's "authorization" header field. This parameter should not be used simultaneously with 73 * \a authTokenProvider. 74 */ 75 @property(nonatomic, copy, readonly, nullable) NSString *oauth2AccessToken; 76 77 /** 78 * The interface to get the OAuth2 access token string. gRPC will attempt to acquire token when 79 * initiating the call. This parameter should not be used simultaneously with \a oauth2AccessToken. 80 */ 81 @property(nonatomic, readonly, nullable) id<GRPCAuthorizationProtocol> authTokenProvider; 82 83 /** 84 * Initial metadata key-value pairs that should be included in the request. 85 * Dictionary key is of type NSString, value should be either NSString or NSData containing binary 86 * bytes data. 87 */ 88 @property(nonatomic, copy, readonly, nullable) GRPCMetadataDictionary *initialMetadata; 89 90 // Channel parameters; take into account of channel signature. 91 92 /** 93 * Custom string that is prefixed to a request's user-agent header field before gRPC's internal 94 * user-agent string. 95 */ 96 @property(nonatomic, copy, readonly, nullable) NSString *userAgentPrefix; 97 98 /** 99 * Custom string that is suffixed to a request's user-agent header field after gRPC's internal 100 * user-agent string. 101 */ 102 @property(nonatomic, copy, readonly, nullable) NSString *userAgentSuffix; 103 104 /** 105 * The size limit for the response received from server. If it is exceeded, an error with status 106 * code GRPCErrorCodeResourceExhausted is returned. 107 */ 108 @property(nonatomic, readonly) NSUInteger responseSizeLimit; 109 110 /** 111 * The compression algorithm to be used by the gRPC call. For more details refer to 112 * https://github.com/grpc/grpc/blob/master/doc/compression.md 113 */ 114 @property(nonatomic, readonly) GRPCCompressionAlgorithm compressionAlgorithm; 115 116 /** 117 * Enable/Disable gRPC call's retry feature. The default is enabled. For details of this feature 118 * refer to 119 * https://github.com/grpc/proposal/blob/master/A6-client-retries.md 120 */ 121 @property(nonatomic, readonly) BOOL retryEnabled; 122 123 /** 124 * Maximum interval in seconds between two consecutive retries. 125 * Internal-only property used for GTMSessionFetcher transport retry policy. 126 */ 127 @property(nonatomic, readonly) NSTimeInterval maxRetryInterval; 128 129 /** 130 * Minimum interval in seconds between two consecutive retries. 131 * Internal-only property used for GTMSessionFetcher transport retry policy. 132 */ 133 @property(nonatomic, readonly) NSTimeInterval minRetryInterval; 134 135 /** 136 * Multiplier used to increase the interval between retries. 137 * Internal-only property used for GTMSessionFetcher transport retry policy. 138 */ 139 @property(readonly) double retryFactor; 140 141 // HTTP/2 keep-alive feature. The parameter \a keepaliveInterval specifies the interval between two 142 // PING frames. The parameter \a keepaliveTimeout specifies the length of the period for which the 143 // call should wait for PING ACK. If PING ACK is not received after this period, the call fails. 144 // Negative values are not allowed. 145 @property(nonatomic, readonly) NSTimeInterval keepaliveInterval; 146 @property(nonatomic, readonly) NSTimeInterval keepaliveTimeout; 147 148 // Parameters for connection backoff. Negative values are not allowed. 149 // For details of gRPC's backoff behavior, refer to 150 // https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md 151 @property(nonatomic, readonly) NSTimeInterval connectMinTimeout; 152 @property(nonatomic, readonly) NSTimeInterval connectInitialBackoff; 153 @property(nonatomic, readonly) NSTimeInterval connectMaxBackoff; 154 155 /** 156 * Specify channel args to be used for this call. For a list of channel args available, see 157 * grpc/grpc_types.h 158 */ 159 @property(nonatomic, copy, readonly, nullable) GRPCMetadataDictionary *additionalChannelArgs; 160 161 // Parameters for SSL authentication. 162 163 /** 164 * PEM format root certifications that is trusted. If set to nil, gRPC uses a list of default 165 * root certificates. 166 */ 167 @property(nonatomic, copy, readonly, nullable) NSString *PEMRootCertificates; 168 169 /** 170 * PEM format private key for client authentication, if required by the server. 171 */ 172 @property(nonatomic, copy, readonly, nullable) NSString *PEMPrivateKey; 173 174 /** 175 * PEM format certificate chain for client authentication, if required by the server. 176 */ 177 @property(nonatomic, copy, readonly, nullable) NSString *PEMCertificateChain; 178 179 /** 180 * Deprecated: this option is deprecated. Please use the property \a transport 181 * instead. 182 * 183 * Select the transport type to be used for this call. 184 */ 185 @property(nonatomic, readonly) GRPCTransportType transportType; 186 187 /** 188 * The transport to be used for this call. Users may choose a native transport 189 * identifier defined in \a GRPCTransport or provided by a non-native transport 190 * implementation. If the option is left to be NULL, gRPC will use its default 191 * transport. 192 * 193 * This is currently an experimental option. 194 */ 195 @property(nonatomic, readonly) GRPCTransportID transport; 196 197 /** 198 * Override the hostname during the TLS hostname validation process. 199 */ 200 @property(nonatomic, copy, readonly, nullable) NSString *hostNameOverride; 201 202 /** 203 * A string that specify the domain where channel is being cached. Channels with different domains 204 * will not get cached to the same connection. 205 */ 206 @property(nonatomic, copy, readonly, nullable) NSString *channelPoolDomain; 207 208 /** 209 * Channel id allows control of channel caching within a channelPoolDomain. A call with a unique 210 * channelID will create a new channel (connection) instead of reusing an existing one. Multiple 211 * calls in the same channelPoolDomain using identical channelID are allowed to share connection 212 * if other channel options are also the same. 213 */ 214 @property(nonatomic, readonly) NSUInteger channelID; 215 216 /** 217 * Hash for channel options. 218 */ 219 @property(nonatomic, readonly) NSUInteger channelOptionsHash; 220 221 /** 222 * Return if the channel options are equal to another object. 223 */ 224 - (BOOL)hasChannelOptionsEqualTo:(GRPCCallOptions *)callOptions; 225 226 @end 227 228 /** 229 * Mutable user configurable options for a gRPC call. 230 * Caller can obtain an immutable copy of type \b GRPCCallOptions by calling [option copy] 231 */ 232 @interface GRPCMutableCallOptions : GRPCCallOptions <NSCopying, NSMutableCopying> 233 234 // Call parameters 235 /** 236 * The authority for the RPC. If nil, the default authority will be used. 237 * 238 * Note: This property does not have effect on Cronet transport and will be ignored. 239 * Note: This property cannot be used to validate a self-signed server certificate. It control the 240 * :authority header field of the call and performs an extra check that server's certificate 241 * matches the :authority header. 242 */ 243 @property(nonatomic, copy, readwrite, nullable) NSString *serverAuthority; 244 245 /** 246 * The timeout for the RPC call in seconds. If set to 0, the call will not timeout. If set to 247 * positive, the gRPC call returns with status GRPCErrorCodeDeadlineExceeded if it is not completed 248 * within \a timeout seconds. Negative value is invalid; setting the parameter to negative value 249 * will reset the parameter to 0. 250 */ 251 @property(nonatomic, readwrite) NSTimeInterval timeout; 252 253 /** 254 * Enable flow control of a gRPC call. The option is default to NO. If set to YES, writeData: method 255 * should only be called at most once before a didWriteData callback is issued, and 256 * receiveNextMessage: must be called each time before gRPC call can issue a didReceiveMessage 257 * callback. 258 * 259 * If writeData: method is called more than once before issuance of a didWriteData callback, gRPC 260 * will continue to queue the message and write them to gRPC core in order. However, the user 261 * assumes their own responsibility of flow control by keeping tracking of the pending writes in 262 * the call. 263 */ 264 @property(nonatomic, readwrite) BOOL flowControlEnabled; 265 266 /** 267 * An array of interceptor factories. When a call starts, interceptors are created 268 * by these factories and chained together with the same order as the factories in 269 * this array. This parameter should not be modified by any interceptor and will 270 * not take effect if done so. 271 */ 272 @property(nonatomic, copy, readwrite) NSArray<id<GRPCInterceptorFactory>> *interceptorFactories; 273 274 // OAuth2 parameters. Users of gRPC may specify one of the following two parameters. 275 276 /** 277 * The OAuth2 access token string. The string is prefixed with "Bearer " then used as value of the 278 * request's "authorization" header field. This parameter should not be used simultaneously with 279 * \a authTokenProvider. 280 */ 281 @property(nonatomic, copy, readwrite, nullable) NSString *oauth2AccessToken; 282 283 /** 284 * The interface to get the OAuth2 access token string. gRPC will attempt to acquire token when 285 * initiating the call. This parameter should not be used simultaneously with \a oauth2AccessToken. 286 */ 287 @property(nonatomic, readwrite, nullable) id<GRPCAuthorizationProtocol> authTokenProvider; 288 289 /** 290 * Initial metadata key-value pairs that should be included in the request. 291 * Dictionary key is of type NSString, value should be either NSString or NSData containing binary 292 * bytes data. 293 */ 294 @property(nonatomic, nonatomic, copy, readwrite, nullable) GRPCMetadataDictionary *initialMetadata; 295 296 // Channel parameters; take into account of channel signature. 297 298 /** 299 * Custom string that is prefixed to a request's user-agent header field before gRPC's internal 300 * user-agent string. 301 */ 302 @property(nonatomic, copy, readwrite, nullable) NSString *userAgentPrefix; 303 304 /** 305 * Custom string that is suffixed to a request's user-agent header field after gRPC's internal 306 * user-agent string. 307 */ 308 @property(nonatomic, copy, readwrite, nullable) NSString *userAgentSuffix; 309 310 /** 311 * The size limit for the response received from server. If it is exceeded, an error with status 312 * code GRPCErrorCodeResourceExhausted is returned. 313 */ 314 @property(nonatomic, readwrite) NSUInteger responseSizeLimit; 315 316 /** 317 * The compression algorithm to be used by the gRPC call. For more details refer to 318 * https://github.com/grpc/grpc/blob/master/doc/compression.md 319 */ 320 @property(nonatomic, readwrite) GRPCCompressionAlgorithm compressionAlgorithm; 321 322 /** 323 * Enable/Disable gRPC call's retry feature. The default is enabled. For details of this feature 324 * refer to 325 * https://github.com/grpc/proposal/blob/master/A6-client-retries.md 326 */ 327 @property(nonatomic, readwrite) BOOL retryEnabled; 328 329 /** 330 * Maximum interval in seconds between two consecutive retries. Pass 0 to use default. 331 * Internal-only property used for GTMSessionFetcher transport retry policy. 332 */ 333 @property(nonatomic, readwrite) NSTimeInterval maxRetryInterval; 334 335 /** 336 * Minimum interval in seconds between two consecutive retries. Pass 0 to use default. 337 * Internal-only property used for GTMSessionFetcher transport retry policy. 338 */ 339 @property(nonatomic, readwrite) NSTimeInterval minRetryInterval; 340 341 /** 342 * Multiplier used to increase the interval between retries. Pass 0 to use default. 343 * Internal-only property used for GTMSessionFetcher transport retry policy. 344 */ 345 @property(nonatomic, readwrite) double retryFactor; 346 347 // HTTP/2 keep-alive feature. The parameter \a keepaliveInterval specifies the interval between two 348 // PING frames. The parameter \a keepaliveTimeout specifies the length of the period for which the 349 // call should wait for PING ACK. If PING ACK is not received after this period, the call fails. 350 // Negative values are invalid; setting these parameters to negative value will reset the 351 // corresponding parameter to 0. 352 @property(nonatomic, readwrite) NSTimeInterval keepaliveInterval; 353 @property(nonatomic, readwrite) NSTimeInterval keepaliveTimeout; 354 355 // Parameters for connection backoff. Negative value is invalid; setting the parameters to negative 356 // value will reset corresponding parameter to 0. 357 // For details of gRPC's backoff behavior, refer to 358 // https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md 359 @property(nonatomic, readwrite) NSTimeInterval connectMinTimeout; 360 @property(nonatomic, readwrite) NSTimeInterval connectInitialBackoff; 361 @property(nonatomic, readwrite) NSTimeInterval connectMaxBackoff; 362 363 /** 364 * Specify channel args to be used for this call. For a list of channel args available, see 365 * grpc/grpc_types.h 366 */ 367 @property(nonatomic, copy, readwrite, nullable) GRPCMetadataDictionary *additionalChannelArgs; 368 369 // Parameters for SSL authentication. 370 371 /** 372 * PEM format root certifications that is trusted. If set to nil, gRPC uses a list of default 373 * root certificates. 374 */ 375 @property(nonatomic, copy, readwrite, nullable) NSString *PEMRootCertificates; 376 377 /** 378 * PEM format private key for client authentication, if required by the server. 379 */ 380 @property(nonatomic, copy, readwrite, nullable) NSString *PEMPrivateKey; 381 382 /** 383 * PEM format certificate chain for client authentication, if required by the server. 384 */ 385 @property(nonatomic, copy, readwrite, nullable) NSString *PEMCertificateChain; 386 387 /** 388 * Deprecated: this option is deprecated. Please use the property \a transport 389 * instead. 390 * 391 * Select the transport type to be used for this call. 392 */ 393 @property(nonatomic, readwrite) GRPCTransportType transportType; 394 395 /** 396 * The transport to be used for this call. Users may choose a native transport 397 * identifier defined in \a GRPCTransport or provided by a non-native ttransport 398 * implementation. If the option is left to be NULL, gRPC will use its default 399 * transport. 400 * 401 * An interceptor must not change the value of this option. 402 */ 403 @property(nonatomic, readwrite) GRPCTransportID transport; 404 405 /** 406 * Override the hostname during the TLS hostname validation process. 407 */ 408 @property(nonatomic, copy, readwrite, nullable) NSString *hostNameOverride; 409 410 /** 411 * A string that specify the domain where channel is being cached. Channels with different domains 412 * will not get cached to the same channel. For example, a gRPC example app may use the channel pool 413 * domain 'io.grpc.example' so that its calls do not reuse the channel created by other modules in 414 * the same process. 415 */ 416 @property(nonatomic, copy, readwrite, nullable) NSString *channelPoolDomain; 417 418 /** 419 * Channel id allows a call to force creating a new channel (connection) rather than using a cached 420 * channel. Calls using distinct channelID's will not get cached to the same channel. 421 */ 422 @property(nonatomic, readwrite) NSUInteger channelID; 423 424 @end 425 426 NS_ASSUME_NONNULL_END 427