include/grpcpp/impl/codegen/interceptor.h

   1 /*
   2  *
   3  * Copyright 2018 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPCPP_IMPL_CODEGEN_INTERCEPTOR_H
  20 #define GRPCPP_IMPL_CODEGEN_INTERCEPTOR_H
  21
  22 #include <grpc/impl/codegen/grpc_types.h>
  23 #include <grpcpp/impl/codegen/byte_buffer.h>
  24 #include <grpcpp/impl/codegen/config.h>
  25 #include <grpcpp/impl/codegen/core_codegen_interface.h>
  26 #include <grpcpp/impl/codegen/metadata_map.h>
  27
  28 namespace grpc {
  29
  30 class ChannelInterface;
  31 class Status;
  32
  33 namespace experimental {
  34
  35 /// An enumeration of different possible points at which the \a Intercept
  36 /// method of the \a Interceptor interface may be called. Any given call
  37 /// to \a Intercept will include one or more of these hook points, and
  38 /// each hook point makes certain types of information available to the
  39 /// interceptor.
  40 /// In these enumeration names, PRE_SEND means that an interception has taken
  41 /// place between the time the application provided a certain type of data
  42 /// (e.g., initial metadata, status) and the time that that data goes to the
  43 /// other side. POST_SEND means that the data has been committed for going to
  44 /// the other side (even if it has not yet been received at the other side).
  45 /// PRE_RECV means an interception between the time that a certain
  46 /// operation has been requested and it is available. POST_RECV means that a
  47 /// result is available but has not yet been passed back to the application.
  48 /// A batch of interception points will only contain either PRE or POST hooks
  49 /// but not both types. For example, a batch with PRE_SEND hook points will not
  50 /// contain POST_RECV or POST_SEND ops. Likewise, a batch with POST_* ops can
  51 /// not contain PRE_* ops.
  52 enum class InterceptionHookPoints {
  53   /// The first three in this list are for clients and servers
  54   PRE_SEND_INITIAL_METADATA,
  55   PRE_SEND_MESSAGE,
  56   POST_SEND_MESSAGE,
  57   PRE_SEND_STATUS,  // server only
  58   PRE_SEND_CLOSE,   // client only: WritesDone for stream; after write in unary
  59   /// The following three are for hijacked clients only. A batch with PRE_RECV_*
  60   /// hook points will never contain hook points of other types.
  61   PRE_RECV_INITIAL_METADATA,
  62   PRE_RECV_MESSAGE,
  63   PRE_RECV_STATUS,
  64   /// The following two are for all clients and servers
  65   POST_RECV_INITIAL_METADATA,
  66   POST_RECV_MESSAGE,
  67   POST_RECV_STATUS,  // client only
  68   POST_RECV_CLOSE,   // server only
  69   /// This is a special hook point available to both clients and servers when
  70   /// TryCancel() is performed.
  71   ///  - No other hook points will be present along with this.
  72   ///  - It is illegal for an interceptor to block/delay this operation.
  73   ///  - ALL interceptors see this hook point irrespective of whether the
  74   ///    RPC was hijacked or not.
  75   PRE_SEND_CANCEL,
  76   NUM_INTERCEPTION_HOOKS
  77 };
  78
  79 /// Class that is passed as an argument to the \a Intercept method
  80 /// of the application's \a Interceptor interface implementation. It has five
  81 /// purposes:
  82 ///   1. Indicate which hook points are present at a specific interception
  83 ///   2. Allow an interceptor to inform the library that an RPC should
  84 ///      continue to the next stage of its processing (which may be another
  85 ///      interceptor or the main path of the library)
  86 ///   3. Allow an interceptor to hijack the processing of the RPC (only for
  87 ///      client-side RPCs with PRE_SEND_INITIAL_METADATA) so that it does not
  88 ///      proceed with normal processing beyond that stage
  89 ///   4. Access the relevant fields of an RPC at each interception point
  90 ///   5. Set some fields of an RPC at each interception point, when possible
  91 class InterceptorBatchMethods {
  92  public:
  93   virtual ~InterceptorBatchMethods() {}
  94   /// Determine whether the current batch has an interception hook point
  95   /// of type \a type
  96   virtual bool QueryInterceptionHookPoint(InterceptionHookPoints type) = 0;
  97   /// Signal that the interceptor is done intercepting the current batch of the
  98   /// RPC. Every interceptor must either call Proceed or Hijack on each
  99   /// interception. In most cases, only Proceed will be used. Explicit use of
 100   /// Proceed is what enables interceptors to delay the processing of RPCs
 101   /// while they perform other work.
 102   /// Proceed is a no-op if the batch contains PRE_SEND_CANCEL. Simply returning
 103   /// from the Intercept method does the job of continuing the RPC in this case.
 104   /// This is because PRE_SEND_CANCEL is always in a separate batch and is not
 105   /// allowed to be delayed.
 106   virtual void Proceed() = 0;
 107   /// Indicate that the interceptor has hijacked the RPC (only valid if the
 108   /// batch contains send_initial_metadata on the client side). Later
 109   /// interceptors in the interceptor list will not be called. Later batches
 110   /// on the same RPC will go through interception, but only up to the point
 111   /// of the hijacking interceptor.
 112   virtual void Hijack() = 0;
 113
 114   /// Send Message Methods
 115   /// GetSerializedSendMessage and GetSendMessage/ModifySendMessage are the
 116   /// available methods to view and modify the request payload. An interceptor
 117   /// can access the payload in either serialized form or non-serialized form
 118   /// but not both at the same time.
 119   /// gRPC performs serialization in a lazy manner, which means
 120   /// that a call to GetSerializedSendMessage will result in a serialization
 121   /// operation if the payload stored is not in the serialized form already; the
 122   /// non-serialized form will be lost and GetSendMessage will no longer return
 123   /// a valid pointer, and this will remain true for later interceptors too.
 124   /// This can change however if ModifySendMessage is used to replace the
 125   /// current payload. Note that ModifySendMessage requires a new payload
 126   /// message in the non-serialized form. This will overwrite the existing
 127   /// payload irrespective of whether it had been serialized earlier. Also note
 128   /// that gRPC Async API requires early serialization of the payload which
 129   /// means that the payload would be available in the serialized form only
 130   /// unless an interceptor replaces the payload with ModifySendMessage.
 131
 132   /// Returns a modifable ByteBuffer holding the serialized form of the message
 133   /// that is going to be sent. Valid for PRE_SEND_MESSAGE interceptions.
 134   /// A return value of nullptr indicates that this ByteBuffer is not valid.
 135   virtual ByteBuffer* GetSerializedSendMessage() = 0;
 136
 137   /// Returns a non-modifiable pointer to the non-serialized form of the message
 138   /// to be sent. Valid for PRE_SEND_MESSAGE interceptions. A return value of
 139   /// nullptr indicates that this field is not valid.
 140   virtual const void* GetSendMessage() = 0;
 141
 142   /// Overwrites the message to be sent with \a message. \a message should be in
 143   /// the non-serialized form expected by the method. Valid for PRE_SEND_MESSAGE
 144   /// interceptions. Note that the interceptor is responsible for maintaining
 145   /// the life of the message till it is serialized or it receives the
 146   /// POST_SEND_MESSAGE interception point, whichever happens earlier. The
 147   /// modifying interceptor may itself force early serialization by calling
 148   /// GetSerializedSendMessage.
 149   virtual void ModifySendMessage(const void* message) = 0;
 150
 151   /// Checks whether the SEND MESSAGE op succeeded. Valid for POST_SEND_MESSAGE
 152   /// interceptions.
 153   virtual bool GetSendMessageStatus() = 0;
 154
 155   /// Returns a modifiable multimap of the initial metadata to be sent. Valid
 156   /// for PRE_SEND_INITIAL_METADATA interceptions. A value of nullptr indicates
 157   /// that this field is not valid.
 158   virtual std::multimap<grpc::string, grpc::string>*
 159   GetSendInitialMetadata() = 0;
 160
 161   /// Returns the status to be sent. Valid for PRE_SEND_STATUS interceptions.
 162   virtual Status GetSendStatus() = 0;
 163
 164   /// Overwrites the status with \a status. Valid for PRE_SEND_STATUS
 165   /// interceptions.
 166   virtual void ModifySendStatus(const Status& status) = 0;
 167
 168   /// Returns a modifiable multimap of the trailing metadata to be sent. Valid
 169   /// for PRE_SEND_STATUS interceptions. A value of nullptr indicates
 170   /// that this field is not valid.
 171   virtual std::multimap<grpc::string, grpc::string>*
 172   GetSendTrailingMetadata() = 0;
 173
 174   /// Returns a pointer to the modifiable received message. Note that the
 175   /// message is already deserialized but the type is not set; the interceptor
 176   /// should static_cast to the appropriate type before using it. This is valid
 177   /// for PRE_RECV_MESSAGE and POST_RECV_MESSAGE interceptions; nullptr for not
 178   /// valid
 179   virtual void* GetRecvMessage() = 0;
 180
 181   /// Returns a modifiable multimap of the received initial metadata.
 182   /// Valid for PRE_RECV_INITIAL_METADATA and POST_RECV_INITIAL_METADATA
 183   /// interceptions; nullptr if not valid
 184   virtual std::multimap<grpc::string_ref, grpc::string_ref>*
 185   GetRecvInitialMetadata() = 0;
 186
 187   /// Returns a modifiable view of the received status on PRE_RECV_STATUS and
 188   /// POST_RECV_STATUS interceptions; nullptr if not valid.
 189   virtual Status* GetRecvStatus() = 0;
 190
 191   /// Returns a modifiable multimap of the received trailing metadata on
 192   /// PRE_RECV_STATUS and POST_RECV_STATUS interceptions; nullptr if not valid
 193   virtual std::multimap<grpc::string_ref, grpc::string_ref>*
 194   GetRecvTrailingMetadata() = 0;
 195
 196   /// Gets an intercepted channel. When a call is started on this interceptor,
 197   /// only interceptors after the current interceptor are created from the
 198   /// factory objects registered with the channel. This allows calls to be
 199   /// started from interceptors without infinite regress through the interceptor
 200   /// list.
 201   virtual std::unique_ptr<ChannelInterface> GetInterceptedChannel() = 0;
 202
 203   /// On a hijacked RPC, an interceptor can decide to fail a PRE_RECV_MESSAGE
 204   /// op. This would be a signal to the reader that there will be no more
 205   /// messages, or the stream has failed or been cancelled.
 206   virtual void FailHijackedRecvMessage() = 0;
 207
 208   /// On a hijacked RPC/ to-be hijacked RPC, this can be called to fail a SEND
 209   /// MESSAGE op
 210   virtual void FailHijackedSendMessage() = 0;
 211 };
 212
 213 /// Interface for an interceptor. Interceptor authors must create a class
 214 /// that derives from this parent class.
 215 class Interceptor {
 216  public:
 217   virtual ~Interceptor() {}
 218
 219   /// The one public method of an Interceptor interface. Override this to
 220   /// trigger the desired actions at the hook points described above.
 221   virtual void Intercept(InterceptorBatchMethods* methods) = 0;
 222 };
 223
 224 }  // namespace experimental
 225 }  // namespace grpc
 226
 227 #endif  // GRPCPP_IMPL_CODEGEN_INTERCEPTOR_H