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