| /* |
| * |
| * Copyright 2019 gRPC authors. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| * |
| */ |
| |
| /** |
| * \file GRPCInterceptor.h |
| * API for interceptors implementation. This feature is currently EXPERIMENTAL |
| and is subject to |
| * breaking changes without prior notice. |
| * |
| * The interceptors in the gRPC system forms a chain. When a call is made by the |
| user, each |
| * interceptor on the chain has chances to react to events of the call and make |
| necessary |
| * modifications to the call's parameters, data, metadata, or flow. |
| * |
| * \verbatim |
| ----------- |
| | GRPCCall2 | |
| ----------- |
| | |
| | |
| -------------------------- |
| | GRPCInterceptorManager 1 | |
| -------------------------- |
| | GRPCInterceptor 1 | |
| -------------------------- |
| | |
| ... |
| | |
| -------------------------- |
| | GRPCInterceptorManager N | |
| -------------------------- |
| | GRPCInterceptor N | |
| -------------------------- |
| | |
| | |
| ------------------ |
| | GRPCCallInternal | |
| ------------------ |
| \endverbatim |
| * |
| * The chain of interceptors is initialized when the corresponding GRPCCall2 |
| object or proto call |
| * object (GRPCUnaryProtoCall and GRPCStreamingProtoCall) is initialized. The |
| initialization of the |
| * chain is controlled by the property interceptorFactories in the callOptions |
| parameter of the |
| * corresponding call object. Property interceptorFactories is an array of |
| * id<GRPCInterceptorFactory> objects provided by the user. When a call object |
| is initialized, each |
| * interceptor factory generates an interceptor object for the call. gRPC |
| internally links the |
| * interceptors with each other and with the actual call object. The order of |
| the interceptors in |
| * the chain is exactly the same as the order of factory objects in |
| interceptorFactories property. |
| * All requests (start, write, finish, cancel, receive next) initiated by the |
| user will be processed |
| * in the order of interceptors, and all responses (initial metadata, data, |
| trailing metadata, write |
| * data done) are processed in the reverse order. |
| * |
| * Each interceptor in the interceptor chain should behave as a user of the next |
| interceptor, and at |
| * the same time behave as a call to the previous interceptor. Therefore |
| interceptor implementations |
| * must follow the state transition of gRPC calls and must also forward events |
| that are consistent |
| * with the current state of the next/previous interceptor. They should also |
| make sure that the |
| * events they forwarded to the next and previous interceptors will, in the end, |
| make the neighbour |
| * interceptor terminate correctly and reaches "finished" state. The diagram |
| below shows the state |
| * transitions. Any event not appearing on the diagram means the event is not |
| permitted for that |
| * particular state. |
| * |
| * \verbatim |
| writeData |
| receiveNextMessages |
| didReceiveInitialMetadata |
| didReceiveData |
| didWriteData receiveNextmessages |
| writeData ----- ----- ---- |
| didReceiveInitialMetadata receiveNextMessages | | | | | | |
| didReceiveData | V | V | V didWriteData |
| ------------- start --------- finish ------------ |
| | initialized | -----> | started | --------> | half-close | |
| ------------- --------- ------------ |
| | | | |
| | | didClose | didClose |
| |cancel | cancel | cancel |
| | V | |
| | ---------- | |
| --------------> | finished | <-------------- |
| ---------- |
| | ^ writeData |
| | | finish |
| ------ cancel |
| receiveNextMessages |
| \endverbatim |
| * |
| * An interceptor must forward responses to its previous interceptor in the |
| order of initial |
| * metadata, message(s), and trailing metadata. Forwarding responses out of this |
| order (e.g. |
| * forwarding a message before initial metadata) is not allowed. |
| * |
| * Events of requests and responses are dispatched to interceptor objects using |
| the interceptor's |
| * dispatch queue. The dispatch queue should be serial queue to make sure the |
| events are processed |
| * in order. Interceptor implementations must derive from GRPCInterceptor class. |
| The class makes |
| * some basic implementation of all methods responding to an event of a call. If |
| an interceptor does |
| * not care about a particular event, it can use the basic implementation of the |
| GRPCInterceptor |
| * class, which simply forward the event to the next or previous interceptor in |
| the chain. |
| * |
| * The interceptor object should be unique for each call since the call context |
| is not passed to the |
| * interceptor object in a call event. However, the interceptors can be |
| implemented to share states |
| * by receiving state sharing object from the factory upon construction. |
| */ |
| |
| #import "GRPCCall.h" |
| #import "GRPCDispatchable.h" |
| |
| NS_ASSUME_NONNULL_BEGIN |
| |
| @class GRPCInterceptorManager; |
| @class GRPCInterceptor; |
| @class GRPCRequestOptions; |
| @class GRPCCallOptions; |
| @protocol GRPCResponseHandler; |
| |
| /** |
| * The GRPCInterceptorInterface defines the request events that can occur to an |
| * interceptor. |
| */ |
| @protocol GRPCInterceptorInterface <NSObject, GRPCDispatchable> |
| |
| /** |
| * To start the call. This method will only be called once for each instance. |
| */ |
| - (void)startWithRequestOptions:(GRPCRequestOptions *)requestOptions |
| callOptions:(GRPCCallOptions *)callOptions; |
| |
| /** |
| * To write data to the call. |
| */ |
| - (void)writeData:(id)data; |
| |
| /** |
| * To finish the stream of requests. |
| */ |
| - (void)finish; |
| |
| /** |
| * To cancel the call. |
| */ |
| - (void)cancel; |
| |
| /** |
| * To indicate the call that the previous interceptor is ready to receive more |
| * messages. |
| */ |
| - (void)receiveNextMessages:(NSUInteger)numberOfMessages; |
| |
| @end |
| |
| /** |
| * An interceptor factory object is used to create interceptor object for the |
| * call at the call start time. |
| */ |
| @protocol GRPCInterceptorFactory |
| |
| /** |
| * Create an interceptor object. gRPC uses the returned object as the |
| * interceptor for the current call |
| */ |
| - (GRPCInterceptor *)createInterceptorWithManager:(GRPCInterceptorManager *)interceptorManager; |
| |
| @end |
| |
| /** |
| * GRPCInterceptorManager is a helper class to forward messages between the |
| * interceptors. The interceptor manager object retains reference to the next |
| * and previous interceptor object in the interceptor chain, and forward |
| * corresponding events to them. |
| * |
| * All methods except the initializer of the class can only be called on the |
| * manager's dispatch queue. Since the manager's dispatch queue targets |
| * corresponding interceptor's dispatch queue, it is also safe to call the |
| * manager's methods in the corresponding interceptor instance's methods that |
| * implement GRPCInterceptorInterface. |
| * |
| * When an interceptor is shutting down, it must invoke -shutDown method of its |
| * corresponding manager so that references to other interceptors can be |
| * released and proper clean-up is made. |
| */ |
| @interface GRPCInterceptorManager : NSObject <GRPCInterceptorInterface, GRPCResponseHandler> |
| |
| - (instancetype)init NS_UNAVAILABLE; |
| |
| + (instancetype)new NS_UNAVAILABLE; |
| |
| - (nullable instancetype)initWithFactories:(nullable NSArray<id<GRPCInterceptorFactory>> *)factories |
| previousInterceptor:(nullable id<GRPCResponseHandler>)previousInterceptor |
| transportID:(GRPCTransportID)transportID; |
| |
| /** |
| * Notify the manager that the interceptor has shut down and the manager should |
| * release references to other interceptors and stop forwarding |
| * requests/responses. |
| */ |
| - (void)shutDown; |
| |
| // Methods to forward GRPCInterceptorInterface calls to the next interceptor |
| |
| /** Notify the next interceptor in the chain to start the call and pass |
| * arguments */ |
| - (void)startNextInterceptorWithRequest:(GRPCRequestOptions *)requestOptions |
| callOptions:(GRPCCallOptions *)callOptions; |
| |
| /** Pass a message to be sent to the next interceptor in the chain */ |
| - (void)writeNextInterceptorWithData:(id)data; |
| |
| /** Notify the next interceptor in the chain to finish the call */ |
| - (void)finishNextInterceptor; |
| |
| /** Notify the next interceptor in the chain to cancel the call */ |
| - (void)cancelNextInterceptor; |
| |
| /** Notify the next interceptor in the chain to receive more messages */ |
| - (void)receiveNextInterceptorMessages:(NSUInteger)numberOfMessages; |
| |
| // Methods to forward GRPCResponseHandler callbacks to the previous object |
| |
| /** Forward initial metadata to the previous interceptor in the chain */ |
| - (void)forwardPreviousInterceptorWithInitialMetadata:(nullable NSDictionary *)initialMetadata; |
| |
| /** Forward a received message to the previous interceptor in the chain */ |
| - (void)forwardPreviousInterceptorWithData:(nullable id)data; |
| |
| /** Forward call close and trailing metadata to the previous interceptor in the |
| * chain */ |
| - (void)forwardPreviousInterceptorCloseWithTrailingMetadata: |
| (nullable NSDictionary *)trailingMetadata |
| error:(nullable NSError *)error; |
| |
| /** Forward write completion to the previous interceptor in the chain */ |
| - (void)forwardPreviousInterceptorDidWriteData; |
| |
| @end |
| |
| /** |
| * Base class for a gRPC interceptor. The implementation of the base class |
| * provides default behavior of an interceptor, which is simply forward a |
| * request/callback to the next/previous interceptor in the chain. The base |
| * class implementation uses the same dispatch queue for both requests and |
| * callbacks. |
| * |
| * An interceptor implementation should inherit from this base class and |
| * initialize the base class with [super |
| * initWithInterceptorManager:dispatchQueue:] for the default implementation to |
| * function properly. |
| */ |
| @interface GRPCInterceptor : NSObject <GRPCInterceptorInterface, GRPCResponseHandler> |
| |
| - (instancetype)init NS_UNAVAILABLE; |
| + (instancetype)new NS_UNAVAILABLE; |
| |
| /** |
| * Initialize the interceptor with the next interceptor in the chain, and |
| * provide the dispatch queue that this interceptor's methods are dispatched |
| * onto. |
| */ |
| - (nullable instancetype)initWithInterceptorManager:(GRPCInterceptorManager *)interceptorManager |
| dispatchQueue:(dispatch_queue_t)dispatchQueue; |
| |
| // Default implementation of GRPCInterceptorInterface |
| |
| - (void)startWithRequestOptions:(GRPCRequestOptions *)requestOptions |
| callOptions:(GRPCCallOptions *)callOptions; |
| - (void)writeData:(id)data; |
| - (void)finish; |
| - (void)cancel; |
| - (void)receiveNextMessages:(NSUInteger)numberOfMessages; |
| |
| // Default implementation of GRPCResponeHandler |
| |
| - (void)didReceiveInitialMetadata:(nullable NSDictionary *)initialMetadata; |
| - (void)didReceiveData:(id)data; |
| - (void)didCloseWithTrailingMetadata:(nullable NSDictionary *)trailingMetadata |
| error:(nullable NSError *)error; |
| - (void)didWriteData; |
| |
| @end |
| |
| NS_ASSUME_NONNULL_END |
