diff options
Diffstat (limited to 'src/objective-c/GRPCClient')
| -rw-r--r-- | src/objective-c/GRPCClient/GRPCCall+OAuth2.h | 16 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/GRPCCall+Tests.h | 28 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/GRPCCall+Tests.m | 3 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/GRPCCall.h | 245 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/GRPCCall.m | 21 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCChannel.h | 12 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCCompletionQueue.h | 20 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCHost.h | 6 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCRequestHeaders.h | 52 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCRequestHeaders.m | 118 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCSecureChannel.h | 8 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCWrappedCall.h | 5 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/GRPCWrappedCall.m | 2 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/NSDictionary+GRPC.m | 47 | ||||
| -rw-r--r-- | src/objective-c/GRPCClient/private/NSError+GRPC.h | 29 |
15 files changed, 446 insertions, 166 deletions
diff --git a/src/objective-c/GRPCClient/GRPCCall+OAuth2.h b/src/objective-c/GRPCClient/GRPCCall+OAuth2.h index 2e379a7157..6b443877e9 100644 --- a/src/objective-c/GRPCClient/GRPCCall+OAuth2.h +++ b/src/objective-c/GRPCClient/GRPCCall+OAuth2.h @@ -33,17 +33,19 @@ #import "GRPCCall.h" -// Helpers for setting and reading headers compatible with OAuth2. +/** Helpers for setting and reading headers compatible with OAuth2. */ @interface GRPCCall (OAuth2) -// Setting this property is equivalent to setting "Bearer <passed token>" as the value of the -// request header with key "authorization" (the authorization header). Setting it to nil removes the -// authorization header from the request. -// The value obtained by getting the property is the OAuth2 bearer token if the authorization header -// of the request has the form "Bearer <token>", or nil otherwise. +/** + * Setting this property is equivalent to setting "Bearer <passed token>" as the value of the + * request header with key "authorization" (the authorization header). Setting it to nil removes the + * authorization header from the request. + * The value obtained by getting the property is the OAuth2 bearer token if the authorization header + * of the request has the form "Bearer <token>", or nil otherwise. + */ @property(atomic, copy) NSString *oauth2AccessToken; -// Returns the value (if any) of the "www-authenticate" response header (the challenge header). +/** Returns the value (if any) of the "www-authenticate" response header (the challenge header). */ @property(atomic, readonly) NSString *oauth2ChallengeHeader; @end diff --git a/src/objective-c/GRPCClient/GRPCCall+Tests.h b/src/objective-c/GRPCClient/GRPCCall+Tests.h index cca1614606..ccc5723ec7 100644 --- a/src/objective-c/GRPCClient/GRPCCall+Tests.h +++ b/src/objective-c/GRPCClient/GRPCCall+Tests.h @@ -33,22 +33,28 @@ #import "GRPCCall.h" -// Methods to let tune down the security of gRPC connections for specific hosts. These shouldn't be -// used in releases, but are sometimes needed for testing. +/** + * Methods to let tune down the security of gRPC connections for specific hosts. These shouldn't be + * used in releases, but are sometimes needed for testing. + */ @interface GRPCCall (Tests) -// Establish all SSL connections to the provided host using the passed SSL target name and the root -// certificates found in the file at |certsPath|. -// -// Must be called before any gRPC call to that host is made. It's illegal to pass the same host to -// more than one invocation of the methods of this category. +/** + * Establish all SSL connections to the provided host using the passed SSL target name and the root + * certificates found in the file at |certsPath|. + * + * Must be called before any gRPC call to that host is made. It's illegal to pass the same host to + * more than one invocation of the methods of this category. + */ + (void)useTestCertsPath:(NSString *)certsPath testName:(NSString *)testName forHost:(NSString *)host; -// Establish all connections to the provided host using cleartext instead of SSL. -// -// Must be called before any gRPC call to that host is made. It's illegal to pass the same host to -// more than one invocation of the methods of this category. +/** + * Establish all connections to the provided host using cleartext instead of SSL. + * + * Must be called before any gRPC call to that host is made. It's illegal to pass the same host to + * more than one invocation of the methods of this category. + */ + (void)useInsecureConnectionsForHost:(NSString *)host; @end diff --git a/src/objective-c/GRPCClient/GRPCCall+Tests.m b/src/objective-c/GRPCClient/GRPCCall+Tests.m index bade0b2920..c8e8133703 100644 --- a/src/objective-c/GRPCClient/GRPCCall+Tests.m +++ b/src/objective-c/GRPCClient/GRPCCall+Tests.m @@ -40,6 +40,9 @@ + (void)useTestCertsPath:(NSString *)certsPath testName:(NSString *)testName forHost:(NSString *)host { + if (!host || !certsPath || !testName) { + [NSException raise:NSInvalidArgumentException format:@"host, path and name must be provided."]; + } GRPCHost *hostConfig = [GRPCHost hostWithAddress:host]; hostConfig.pathToCertificates = certsPath; hostConfig.hostNameOverride = testName; diff --git a/src/objective-c/GRPCClient/GRPCCall.h b/src/objective-c/GRPCClient/GRPCCall.h index 4eda499b1a..5918f8857a 100644 --- a/src/objective-c/GRPCClient/GRPCCall.h +++ b/src/objective-c/GRPCClient/GRPCCall.h @@ -31,77 +31,214 @@ * */ -// The gRPC protocol is an RPC protocol on top of HTTP2. -// -// While the most common type of RPC receives only one request message and returns only one response -// message, the protocol also supports RPCs that return multiple individual messages in a streaming -// fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and -// responses. -// -// Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of -// the "non-streaming type" sending only one message in the corresponding direction (the protocol -// doesn't make any distinction). -// -// Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed -// transparently on the same TCP connection. +/** + * The gRPC protocol is an RPC protocol on top of HTTP2. + * + * While the most common type of RPC receives only one request message and returns only one response + * message, the protocol also supports RPCs that return multiple individual messages in a streaming + * fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and + * responses. + * + * Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of + * the "non-streaming type" sending only one message in the corresponding direction (the protocol + * doesn't make any distinction). + * + * Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed + * transparently on the same TCP connection. + */ #import <Foundation/Foundation.h> #import <RxLibrary/GRXWriter.h> -// Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by -// the server. +#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; -// Represents a single gRPC remote call. +#pragma mark GRPCCall + +/** + * The container of the request headers of an RPC conforms to this protocol, which is a subset of + * NSMutableDictionary's interface. It will become a NSMutableDictionary later on. + * The keys of this container are the header names, which per the HTTP standard are case- + * insensitive. They are stored in lowercase (which is how HTTP/2 mandates them on the wire), and + * can only consist of ASCII characters. + * A header value is a NSString object (with only ASCII characters), unless the header name has the + * suffix "-bin", in which case the value has to be a NSData object. + */ +@protocol GRPCRequestHeaders <NSObject> + +@property(nonatomic, readonly) NSUInteger count; + +- (id)objectForKeyedSubscript:(NSString *)key; +- (void)setObject:(id)obj forKeyedSubscript:(NSString *)key; + +- (void)removeAllObjects; +- (void)removeObjectForKey:(NSString *)key; + +@end + +/** Represents a single gRPC remote call. */ @interface GRPCCall : GRXWriter -// These HTTP headers will be passed to the server as part of this call. Each HTTP header is a -// name-value pair with string names and either string or binary values. -// -// The passed dictionary has to use NSString keys, corresponding to the header names. The value -// associated to each can be a NSString object or a NSData object. E.g.: -// -// call.requestHeaders = @{@"authorization": @"Bearer ..."}; -// -// call.requestHeaders[@"my-header-bin"] = someData; -// -// After the call is started, trying to modify this property is an error. -// -// For convenience, the property is initialized to an empty NSMutableDictionary, and the setter -// accepts (and copies) both mutable and immutable dictionaries. -- (NSMutableDictionary *)requestHeaders; // nonatomic -- (void)setRequestHeaders:(NSDictionary *)requestHeaders; // nonatomic, copy - -// This dictionary is populated with the HTTP headers received from the server. This happens before -// any response message is received from the server. It has the same structure as the request -// headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a -// NSData value; the others have a NSString value. -// -// The value of this property is nil until all response headers are received, and will change before -// any of -writeValue: or -writesFinishedWithError: are sent to the writeable. +/** + * These HTTP headers will be passed to the server as part of this call. Each HTTP header is a + * name-value pair with string names and either string or binary values. + * + * The passed dictionary has to use NSString keys, corresponding to the header names. The value + * associated to each can be a NSString object or a NSData object. E.g.: + * + * call.requestHeaders = @{@"authorization": @"Bearer ..."}; + * + * call.requestHeaders[@"my-header-bin"] = someData; + * + * After the call is started, trying to modify this property is an error. + * + * The property is initialized to an empty NSMutableDictionary. + */ +@property(atomic, readonly) id<GRPCRequestHeaders> requestHeaders; + +/** + * This dictionary is populated with the HTTP headers received from the server. This happens before + * any response message is received from the server. It has the same structure as the request + * headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a + * NSData value; the others have a NSString value. + * + * The value of this property is nil until all response headers are received, and will change before + * any of -writeValue: or -writesFinishedWithError: are sent to the writeable. + */ @property(atomic, readonly) NSDictionary *responseHeaders; -// Same as responseHeaders, but populated with the HTTP trailers received from the server before the -// call finishes. -// -// The value of this property is nil until all response trailers are received, and will change -// before -writesFinishedWithError: is sent to the writeable. +/** + * Same as responseHeaders, but populated with the HTTP trailers received from the server before the + * call finishes. + * + * The value of this property is nil until all response trailers are received, and will change + * before -writesFinishedWithError: is sent to the writeable. + */ @property(atomic, readonly) NSDictionary *responseTrailers; -// The request writer has to write NSData objects into the provided Writeable. The server will -// receive each of those separately and in order as distinct messages. -// A gRPC call might not complete until the request writer finishes. On the other hand, the request -// finishing doesn't necessarily make the call to finish, as the server might continue sending -// messages to the response side of the call indefinitely (depending on the semantics of the -// specific remote method called). -// To finish a call right away, invoke cancel. +/** + * The request writer has to write NSData objects into the provided Writeable. The server will + * receive each of those separately and in order as distinct messages. + * A gRPC call might not complete until the request writer finishes. On the other hand, the request + * finishing doesn't necessarily make the call to finish, as the server might continue sending + * messages to the response side of the call indefinitely (depending on the semantics of the + * specific remote method called). + * To finish a call right away, invoke cancel. + */ - (instancetype)initWithHost:(NSString *)host path:(NSString *)path requestsWriter:(GRXWriter *)requestsWriter NS_DESIGNATED_INITIALIZER; -// Finishes the request side of this call, notifies the server that the RPC should be cancelled, and -// finishes the response side of the call with an error of code CANCELED. +/** + * Finishes the request side of this call, notifies the server that the RPC should be cancelled, and + * finishes the response side of the call with an error of code CANCELED. + */ - (void)cancel; // TODO(jcanizales): Let specify a deadline. As a category of GRXWriter? diff --git a/src/objective-c/GRPCClient/GRPCCall.m b/src/objective-c/GRPCClient/GRPCCall.m index ff5d1c5aaf..b6986bf59c 100644 --- a/src/objective-c/GRPCClient/GRPCCall.m +++ b/src/objective-c/GRPCClient/GRPCCall.m @@ -37,6 +37,7 @@ #include <grpc/support/time.h> #import <RxLibrary/GRXConcurrentWriteable.h> +#import "private/GRPCRequestHeaders.h" #import "private/GRPCWrappedCall.h" #import "private/NSData+GRPC.h" #import "private/NSDictionary+GRPC.h" @@ -93,7 +94,7 @@ NSString * const kGRPCTrailersKey = @"io.grpc.TrailersKey"; // the response arrives. GRPCCall *_retainSelf; - NSMutableDictionary *_requestHeaders; + GRPCRequestHeaders *_requestHeaders; } @synthesize state = _state; @@ -124,21 +125,11 @@ NSString * const kGRPCTrailersKey = @"io.grpc.TrailersKey"; _requestWriter = requestWriter; - _requestHeaders = [NSMutableDictionary dictionary]; + _requestHeaders = [[GRPCRequestHeaders alloc] initWithCall:self]; } return self; } -#pragma mark Metadata - -- (NSMutableDictionary *)requestHeaders { - return _requestHeaders; -} - -- (void)setRequestHeaders:(NSDictionary *)requestHeaders { - _requestHeaders = [NSMutableDictionary dictionaryWithDictionary:requestHeaders]; -} - #pragma mark Finish - (void)finishWithError:(NSError *)errorOrNil { @@ -230,10 +221,10 @@ NSString * const kGRPCTrailersKey = @"io.grpc.TrailersKey"; #pragma mark Send headers -- (void)sendHeaders:(NSDictionary *)headers { +- (void)sendHeaders:(id<GRPCRequestHeaders>)headers { // TODO(jcanizales): Add error handlers for async failures - [_wrappedCall startBatchWithOperations:@[[[GRPCOpSendMetadata alloc] - initWithMetadata:headers ?: @{} handler:nil]]]; + [_wrappedCall startBatchWithOperations:@[[[GRPCOpSendMetadata alloc] initWithMetadata:headers + handler:nil]]]; } #pragma mark GRXWriteable implementation diff --git a/src/objective-c/GRPCClient/private/GRPCChannel.h b/src/objective-c/GRPCClient/private/GRPCChannel.h index 2a7b701576..e2d19d506a 100644 --- a/src/objective-c/GRPCClient/private/GRPCChannel.h +++ b/src/objective-c/GRPCClient/private/GRPCChannel.h @@ -35,12 +35,16 @@ struct grpc_channel; -// Each separate instance of this class represents at least one TCP connection to the provided host. -// Create them using one of the subclasses |GRPCSecureChannel| and |GRPCUnsecuredChannel|. +/** + * Each separate instance of this class represents at least one TCP connection to the provided host. + * Create them using one of the subclasses |GRPCSecureChannel| and |GRPCUnsecuredChannel|. + */ @interface GRPCChannel : NSObject @property(nonatomic, readonly) struct grpc_channel *unmanagedChannel; -// This initializer takes ownership of the passed channel, and will destroy it when this object is -// deallocated. It's illegal to pass the same grpc_channel to two different GRPCChannel objects. +/** + * This initializer takes ownership of the passed channel, and will destroy it when this object is + * deallocated. It's illegal to pass the same grpc_channel to two different GRPCChannel objects. + */ - (instancetype)initWithChannel:(struct grpc_channel *)unmanagedChannel NS_DESIGNATED_INITIALIZER; @end diff --git a/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h b/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h index ab8d714d22..fe3b8f39d1 100644 --- a/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h +++ b/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h @@ -36,15 +36,17 @@ typedef void(^GRPCQueueCompletionHandler)(bool success); -// This class lets one more easily use |grpc_completion_queue|. To use it, pass the value of the -// |unmanagedQueue| property of an instance of this class to |grpc_channel_create_call|. Then for -// every |grpc_call_*| method that accepts a tag, you can pass a block of type -// |GRPCQueueCompletionHandler| (remembering to cast it using |__bridge_retained|). The block is -// guaranteed to eventually be called, by a concurrent queue, and then released. Each such block is -// passed a |bool| that tells if the operation was successful. -// -// Release the GRPCCompletionQueue object only after you are not going to pass any more blocks to -// the |grpc_call| that's using it. +/** + * This class lets one more easily use |grpc_completion_queue|. To use it, pass the value of the + * |unmanagedQueue| property of an instance of this class to |grpc_channel_create_call|. Then for + * every |grpc_call_*| method that accepts a tag, you can pass a block of type + * |GRPCQueueCompletionHandler| (remembering to cast it using |__bridge_retained|). The block is + * guaranteed to eventually be called, by a concurrent queue, and then released. Each such block is + * passed a |bool| that tells if the operation was successful. + * + * Release the GRPCCompletionQueue object only after you are not going to pass any more blocks to + * the |grpc_call| that's using it. + */ @interface GRPCCompletionQueue : NSObject @property(nonatomic, readonly) grpc_completion_queue *unmanagedQueue; diff --git a/src/objective-c/GRPCClient/private/GRPCHost.h b/src/objective-c/GRPCClient/private/GRPCHost.h index f0bbd53023..6b4f98746d 100644 --- a/src/objective-c/GRPCClient/private/GRPCHost.h +++ b/src/objective-c/GRPCClient/private/GRPCHost.h @@ -40,18 +40,18 @@ struct grpc_call; @property(nonatomic, readonly) NSString *address; -// The following properties should only be modified for testing: +/** The following properties should only be modified for testing: */ @property(nonatomic, getter=isSecure) BOOL secure; @property(nonatomic, copy) NSString *pathToCertificates; @property(nonatomic, copy) NSString *hostNameOverride; -// Host objects initialized with the same address are the same. +/** Host objects initialized with the same address are the same. */ + (instancetype)hostWithAddress:(NSString *)address; - (instancetype)initWithAddress:(NSString *)address NS_DESIGNATED_INITIALIZER; -// Create a grpc_call object to the provided path on this host. +/** Create a grpc_call object to the provided path on this host. */ - (struct grpc_call *)unmanagedCallWithPath:(NSString *)path completionQueue:(GRPCCompletionQueue *)queue; diff --git a/src/objective-c/GRPCClient/private/GRPCRequestHeaders.h b/src/objective-c/GRPCClient/private/GRPCRequestHeaders.h new file mode 100644 index 0000000000..cf5a1be9d6 --- /dev/null +++ b/src/objective-c/GRPCClient/private/GRPCRequestHeaders.h @@ -0,0 +1,52 @@ +/* + * + * Copyright 2015, Google Inc. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following disclaimer + * in the documentation and/or other materials provided with the + * distribution. + * * Neither the name of Google Inc. nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ + +#import <Foundation/Foundation.h> +#include <grpc/grpc.h> + +#import "../GRPCCall.h" + +@interface GRPCRequestHeaders : NSObject<GRPCRequestHeaders> + +@property(nonatomic, readonly) NSUInteger count; +@property(nonatomic, readonly) grpc_metadata *grpc_metadataArray; + +- (instancetype)initWithCall:(GRPCCall *)call; + +- (id)objectForKeyedSubscript:(NSString *)key; +- (void)setObject:(id)obj forKeyedSubscript:(NSString *)key; + +- (void)removeAllObjects; +- (void)removeObjectForKey:(NSString *)key; + +@end diff --git a/src/objective-c/GRPCClient/private/GRPCRequestHeaders.m b/src/objective-c/GRPCClient/private/GRPCRequestHeaders.m new file mode 100644 index 0000000000..d23f21c0f9 --- /dev/null +++ b/src/objective-c/GRPCClient/private/GRPCRequestHeaders.m @@ -0,0 +1,118 @@ +/* + * + * Copyright 2015, Google Inc. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following disclaimer + * in the documentation and/or other materials provided with the + * distribution. + * * Neither the name of Google Inc. nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ + +#import "GRPCRequestHeaders.h" + +#import <Foundation/Foundation.h> + +#import "NSDictionary+GRPC.h" + +// Used by the setter. +static void CheckIsNonNilASCII(NSString *name, NSString* value) { + if (!value) { + [NSException raise:NSInvalidArgumentException format:@"%@ cannot be nil", name]; + } + if (![value canBeConvertedToEncoding:NSASCIIStringEncoding]) { + [NSException raise:NSInvalidArgumentException + format:@"%@ %@ contains non-ASCII characters", name, value]; + } +} + +// Precondition: key isn't nil. +static void CheckKeyValuePairIsValid(NSString *key, id value) { + if ([key hasSuffix:@"-bin"]) { + if (![value isKindOfClass:NSData.class]) { + [NSException raise:NSInvalidArgumentException + format:@"Expected NSData value for header %@ ending in \"-bin\", " + @"instead got %@", key, value]; + } + } else { + if (![value isKindOfClass:NSString.class]) { + [NSException raise:NSInvalidArgumentException + format:@"Expected NSString value for header %@ not ending in \"-bin\", " + @"instead got %@", key, value]; + } + CheckIsNonNilASCII(@"Text header value", (NSString *)value); + } +} + +@implementation GRPCRequestHeaders { + __weak GRPCCall *_call; + NSMutableDictionary *_delegate; +} + +- (instancetype)initWithCall:(GRPCCall *)call { + if ((self = [super init])) { + _call = call; + _delegate = [NSMutableDictionary dictionary]; + } + return self; +} + +- (void)checkCallIsNotStarted { + if (_call.state != GRXWriterStateNotStarted) { + [NSException raise:@"Invalid modification" + format:@"Cannot modify request headers after call is started"]; + } +} + +- (id)objectForKeyedSubscript:(NSString *)key { + return _delegate[key.lowercaseString]; +} + +- (void)setObject:(id)obj forKeyedSubscript:(NSString *)key { + [self checkCallIsNotStarted]; + CheckIsNonNilASCII(@"Header name", key); + key = key.lowercaseString; + CheckKeyValuePairIsValid(key, obj); + _delegate[key] = obj; +} + +- (void)removeObjectForKey:(NSString *)key { + [self checkCallIsNotStarted]; + [_delegate removeObjectForKey:key.lowercaseString]; +} + +- (void)removeAllObjects { + [self checkCallIsNotStarted]; + [_delegate removeAllObjects]; +} + +- (NSUInteger)count { + return _delegate.count; +} + +- (grpc_metadata *)grpc_metadataArray { + return _delegate.grpc_metadataArray; +} +@end diff --git a/src/objective-c/GRPCClient/private/GRPCSecureChannel.h b/src/objective-c/GRPCClient/private/GRPCSecureChannel.h index 74257eb058..4e0881e5a2 100644 --- a/src/objective-c/GRPCClient/private/GRPCSecureChannel.h +++ b/src/objective-c/GRPCClient/private/GRPCSecureChannel.h @@ -40,13 +40,15 @@ struct grpc_credentials; @interface GRPCSecureChannel : GRPCChannel - (instancetype)initWithHost:(NSString *)host; -// Only in tests shouldn't pathToCertificates or hostNameOverride be nil. Passing nil for -// pathToCertificates results in using the default root certificates distributed with the library. +/** + * Only in tests shouldn't pathToCertificates or hostNameOverride be nil. Passing nil for + * pathToCertificates results in using the default root certificates distributed with the library. + */ - (instancetype)initWithHost:(NSString *)host pathToCertificates:(NSString *)path hostNameOverride:(NSString *)hostNameOverride; -// The passed arguments aren't required to be valid beyond the invocation of this initializer. +/** The passed arguments aren't required to be valid beyond the invocation of this initializer. */ - (instancetype)initWithHost:(NSString *)host credentials:(struct grpc_credentials *)credentials args:(grpc_channel_args *)args NS_DESIGNATED_INITIALIZER; diff --git a/src/objective-c/GRPCClient/private/GRPCWrappedCall.h b/src/objective-c/GRPCClient/private/GRPCWrappedCall.h index da11cbb761..7747aa53ef 100644 --- a/src/objective-c/GRPCClient/private/GRPCWrappedCall.h +++ b/src/objective-c/GRPCClient/private/GRPCWrappedCall.h @@ -35,16 +35,17 @@ #include <grpc/grpc.h> #import "GRPCChannel.h" +#import "GRPCRequestHeaders.h" @interface GRPCOperation : NSObject @property(nonatomic, readonly) grpc_op op; -// Guaranteed to be called when the operation has finished. +/** Guaranteed to be called when the operation has finished. */ - (void)finish; @end @interface GRPCOpSendMetadata : GRPCOperation -- (instancetype)initWithMetadata:(NSDictionary *)metadata +- (instancetype)initWithMetadata:(GRPCRequestHeaders *)metadata handler:(void(^)())handler NS_DESIGNATED_INITIALIZER; @end diff --git a/src/objective-c/GRPCClient/private/GRPCWrappedCall.m b/src/objective-c/GRPCClient/private/GRPCWrappedCall.m index fe3d51da53..cea7c479e0 100644 --- a/src/objective-c/GRPCClient/private/GRPCWrappedCall.m +++ b/src/objective-c/GRPCClient/private/GRPCWrappedCall.m @@ -65,7 +65,7 @@ return [self initWithMetadata:nil handler:nil]; } -- (instancetype)initWithMetadata:(NSDictionary *)metadata handler:(void (^)())handler { +- (instancetype)initWithMetadata:(GRPCRequestHeaders *)metadata handler:(void (^)())handler { if (self = [super init]) { _op.op = GRPC_OP_SEND_INITIAL_METADATA; _op.data.send_initial_metadata.count = metadata.count; diff --git a/src/objective-c/GRPCClient/private/NSDictionary+GRPC.m b/src/objective-c/GRPCClient/private/NSDictionary+GRPC.m index 99c890e4ee..7477da7619 100644 --- a/src/objective-c/GRPCClient/private/NSDictionary+GRPC.m +++ b/src/objective-c/GRPCClient/private/NSDictionary+GRPC.m @@ -40,8 +40,8 @@ @interface NSData (GRPCMetadata) + (instancetype)grpc_dataFromMetadataValue:(grpc_metadata *)metadata; -// Fill a metadata object with the binary value in this NSData and the given key. -- (void)grpc_initMetadata:(grpc_metadata *)metadata withKey:(NSString *)key; +// Fill a metadata object with the binary value in this NSData. +- (void)grpc_initMetadata:(grpc_metadata *)metadata; @end @implementation NSData (GRPCMetadata) @@ -50,9 +50,7 @@ return [self dataWithBytes:metadata->value length:metadata->value_length]; } -- (void)grpc_initMetadata:(grpc_metadata *)metadata withKey:(NSString *)key { - // TODO(jcanizales): Encode Unicode chars as ASCII. - metadata->key = [key stringByAppendingString:@"-bin"].UTF8String; +- (void)grpc_initMetadata:(grpc_metadata *)metadata { metadata->value = self.bytes; metadata->value_length = self.length; } @@ -63,8 +61,8 @@ @interface NSString (GRPCMetadata) + (instancetype)grpc_stringFromMetadataValue:(grpc_metadata *)metadata; -// Fill a metadata object with the textual value in this NSString and the given key. -- (void)grpc_initMetadata:(grpc_metadata *)metadata withKey:(NSString *)key; +// Fill a metadata object with the textual value in this NSString. +- (void)grpc_initMetadata:(grpc_metadata *)metadata; @end @implementation NSString (GRPCMetadata) @@ -74,22 +72,8 @@ encoding:NSASCIIStringEncoding]; } -- (void)grpc_initMetadata:(grpc_metadata *)metadata withKey:(NSString *)key { - if ([key hasSuffix:@"-bin"]) { - // Disallow this, as at best it will confuse the server. If the app really needs to send a - // textual header with a name ending in "-bin", it can be done by removing the suffix and - // encoding the NSString as a NSData object. - // - // Why raise an exception: In the most common case, the developer knows this won't happen in - // their code, so the exception isn't triggered. In the rare cases when the developer can't - // tell, it's easy enough to add a sanitizing filter before the header is set. There, the - // developer can choose whether to drop such a header, or trim its name. Doing either ourselves, - // silently, would be very unintuitive for the user. - [NSException raise:NSInvalidArgumentException - format:@"Metadata keys ending in '-bin' are reserved for NSData values."]; - } - // TODO(jcanizales): Encode Unicode chars as ASCII. - metadata->key = key.UTF8String; +// Precondition: This object contains only ASCII characters. +- (void)grpc_initMetadata:(grpc_metadata *)metadata { metadata->value = self.UTF8String; metadata->value_length = self.length; } @@ -105,8 +89,6 @@ + (instancetype)grpc_dictionaryFromMetadata:(grpc_metadata *)entries count:(size_t)count { NSMutableDictionary *metadata = [NSMutableDictionary dictionaryWithCapacity:count]; for (grpc_metadata *entry = entries; entry < entries + count; entry++) { - // TODO(jcanizales): Verify in a C library test that it's converting header names to lower case - // automatically. NSString *name = [NSString stringWithCString:entry->key encoding:NSASCIIStringEncoding]; if (!name || metadata[name]) { // Log if name is nil? @@ -114,7 +96,6 @@ } id value; if ([name hasSuffix:@"-bin"]) { - name = [name substringToIndex:name.length - 4]; value = [NSData grpc_dataFromMetadataValue:entry]; } else { value = [NSString grpc_stringFromMetadataValue:entry]; @@ -124,19 +105,21 @@ return metadata; } +// Preconditions: All keys are ASCII strings. Keys ending in -bin have NSData values; the others +// have NSString values. - (grpc_metadata *)grpc_metadataArray { grpc_metadata *metadata = gpr_malloc([self count] * sizeof(grpc_metadata)); - int i = 0; - for (id key in self) { + grpc_metadata *current = metadata; + for (NSString* key in self) { id value = self[key]; - grpc_metadata *current = &metadata[i]; - if ([value respondsToSelector:@selector(grpc_initMetadata:withKey:)]) { - [value grpc_initMetadata:current withKey:key]; + current->key = key.UTF8String; + if ([value respondsToSelector:@selector(grpc_initMetadata:)]) { + [value grpc_initMetadata:current]; } else { [NSException raise:NSInvalidArgumentException format:@"Metadata values must be NSString or NSData."]; } - i += 1; + ++current; } return metadata; } diff --git a/src/objective-c/GRPCClient/private/NSError+GRPC.h b/src/objective-c/GRPCClient/private/NSError+GRPC.h index e712791271..e0c1efc1f9 100644 --- a/src/objective-c/GRPCClient/private/NSError+GRPC.h +++ b/src/objective-c/GRPCClient/private/NSError+GRPC.h @@ -34,31 +34,10 @@ #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|. +/** + * Returns nil if the status code is OK. Otherwise, a NSError whose code is one of |GRPCErrorCode| + * and whose domain is |kGRPCErrorDomain|. + */ + (instancetype)grpc_errorFromStatusCode:(grpc_status_code)statusCode details:(char *)details; @end |