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