grpc/src/objective-c/GRPCClient/GRPCInterceptor.h

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

/**
 * 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.
 *
 *
 *                                   -----------
 *                                  | GRPCCall2 |
 *                                   -----------
 *                                        |
 *                                        |
 *                           --------------------------
 *                          | GRPCInterceptorManager 1 |
 *                           --------------------------
 *                          | GRPCInterceptor 1        |
 *                           --------------------------
 *                                        |
 *                                       ...
 *                                        |
 *                           --------------------------
 *                          | GRPCInterceptorManager N |
 *                           --------------------------
 *                          | GRPCInterceptor N        |
 *                           --------------------------
 *                                        |
 *                                        |
 *                               ------------------
 *                              | GRPCCallInternal |
 *                               ------------------
 *
 * 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.
 *
 *                                      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
 *
 * 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"

NS_ASSUME_NONNULL_BEGIN

@class GRPCInterceptorManager;
@class GRPCInterceptor;

/**
 * The GRPCInterceptorInterface defines the request events that can occur to an interceptr.
 */
@protocol GRPCInterceptorInterface<NSObject>

/**
 * The queue on which all methods of this interceptor should be dispatched on. The queue must be a
 * serial queue.
 */
@property(readonly) dispatch_queue_t requestDispatchQueue;

/**
 * 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 should be 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

/**
 * The interceptor manager object retains reference to the next and previous interceptor object in
 * the interceptor chain, and forward corresponding events to them. When a call terminates, it must
 * invoke shutDown method of its corresponding manager so that references to other interceptors can
 * be released.
 */
@interface GRPCInterceptorManager : NSObject

- (instancetype)init NS_UNAVAILABLE;

+ (instancetype) new NS_UNAVAILABLE;

- (nullable instancetype)initWithNextInterceptor:(id<GRPCInterceptorInterface>)nextInterceptor
    NS_DESIGNATED_INITIALIZER;

/** Set the previous interceptor in the chain. Can only be set once. */
- (void)setPreviousInterceptor:(id<GRPCResponseHandler>)previousInterceptor;

/** Indicate shutdown of the interceptor; release the reference to other interceptors */
- (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
                               requestDispatchQueue:(dispatch_queue_t)requestDispatchQueue
                              responseDispatchQueue:(dispatch_queue_t)responseDispatchQueue
    NS_DESIGNATED_INITIALIZER;

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