Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <functional>
       4             : #include <memory>
       5             : 
       6             : #include "envoy/common/conn_pool.h"
       7             : #include "envoy/common/pure.h"
       8             : #include "envoy/event/deferred_deletable.h"
       9             : #include "envoy/http/codec.h"
      10             : #include "envoy/upstream/upstream.h"
      11             : 
      12             : namespace Envoy {
      13             : namespace Http {
      14             : namespace ConnectionPool {
      15             : 
      16             : using PoolFailureReason = ::Envoy::ConnectionPool::PoolFailureReason;
      17             : using Cancellable = ::Envoy::ConnectionPool::Cancellable;
      18             : 
      19             : /**
      20             :  * Pool callbacks invoked in the context of a newStream() call, either synchronously or
      21             :  * asynchronously.
      22             :  */
      23             : class Callbacks {
      24             : public:
      25         251 :   virtual ~Callbacks() = default;
      26             : 
      27             :   /**
      28             :    * Called when a pool error occurred and no connection could be acquired for making the request.
      29             :    * @param reason supplies the failure reason.
      30             :    * @param transport_failure_reason supplies the details of the transport failure reason.
      31             :    * @param host supplies the description of the host that caused the failure. This may be nullptr
      32             :    *             if no host was involved in the failure (for example overflow).
      33             :    */
      34             :   virtual void onPoolFailure(PoolFailureReason reason, absl::string_view transport_failure_reason,
      35             :                              Upstream::HostDescriptionConstSharedPtr host) PURE;
      36             : 
      37             :   /**
      38             :    * Called when a connection is available to process a request/response.
      39             :    * @param encoder supplies the request encoder to use.
      40             :    * @param host supplies the description of the host that will carry the request. For logical
      41             :    *             connection pools the description may be different each time this is called.
      42             :    * @param info supplies the stream info object associated with the upstream L4 connection.
      43             :    * @param protocol supplies the protocol associated with the stream, or absl::nullopt for raw TCP.
      44             :    */
      45             :   virtual void onPoolReady(RequestEncoder& encoder, Upstream::HostDescriptionConstSharedPtr host,
      46             :                            StreamInfo::StreamInfo& info,
      47             :                            absl::optional<Http::Protocol> protocol) PURE;
      48             : };
      49             : 
      50             : class Instance;
      51             : 
      52             : /**
      53             :  * Pool callbacks invoked to track the lifetime of connections in the pool.
      54             :  */
      55             : class ConnectionLifetimeCallbacks {
      56             : public:
      57           0 :   virtual ~ConnectionLifetimeCallbacks() = default;
      58             : 
      59             :   /**
      60             :    * Called when a connection is open for requests in a pool.
      61             :    * @param pool which the connection is associated with.
      62             :    * @param hash_key the hash key used for this connection.
      63             :    * @param connection newly open connection.
      64             :    */
      65             :   virtual void onConnectionOpen(Instance& pool, std::vector<uint8_t>& hash_key,
      66             :                                 const Network::Connection& connection) PURE;
      67             : 
      68             :   /**
      69             :    * Called when a connection is draining and may no longer be used for requests.
      70             :    * @param pool which the connection is associated with.
      71             :    * @param hash_key the hash key used for this connection.
      72             :    * @param connection newly open connection.
      73             :    */
      74             :   virtual void onConnectionDraining(Instance& pool, std::vector<uint8_t>& hash_key,
      75             :                                     const Network::Connection& connection) PURE;
      76             : };
      77             : 
      78             : /**
      79             :  * An instance of a generic connection pool.
      80             :  */
      81             : class Instance : public Envoy::ConnectionPool::Instance, public Event::DeferredDeletable {
      82             : public:
      83             :   struct StreamOptions {
      84             :     // True if the request can be sent as early data.
      85             :     bool can_send_early_data_;
      86             :     // True if the request can be sent over HTTP/3.
      87             :     bool can_use_http3_;
      88             :   };
      89             : 
      90         381 :   ~Instance() override = default;
      91             : 
      92             :   /**
      93             :    * Determines whether the connection pool is actively processing any requests.
      94             :    * @return true if the connection pool has any pending requests or any active requests.
      95             :    */
      96             :   virtual bool hasActiveConnections() const PURE;
      97             : 
      98             :   /**
      99             :    * Create a new stream on the pool.
     100             :    * @param response_decoder supplies the decoder events to fire when the response is
     101             :    *                         available.
     102             :    * @param cb supplies the callbacks to invoke when the connection is ready or has failed. The
     103             :    *           callbacks may be invoked immediately within the context of this call if there is a
     104             :    *           ready connection or an immediate failure. In this case, the routine returns nullptr.
     105             :    * @param options specifies how to create the requested stream.
     106             :    * @return Cancellable* If no connection is ready, the callback is not invoked, and a handle
     107             :    *                      is returned that can be used to cancel the request. Otherwise, one of the
     108             :    *                      callbacks is called and the routine returns nullptr. NOTE: Once a callback
     109             :    *                      is called, the handle is no longer valid and any further cancellation
     110             :    *                      should be done by resetting the stream.
     111             :    * @warning Do not call cancel() from the callbacks, as the request is implicitly canceled when
     112             :    *          the callbacks are called.
     113             :    */
     114             :   virtual Cancellable* newStream(Http::ResponseDecoder& response_decoder, Callbacks& callbacks,
     115             :                                  const StreamOptions& options) PURE;
     116             : 
     117             :   /**
     118             :    * Returns a user-friendly protocol description for logging.
     119             :    * @return absl::string_view a protocol description for logging.
     120             :    */
     121             :   virtual absl::string_view protocolDescription() const PURE;
     122             : };
     123             : 
     124             : using InstancePtr = std::unique_ptr<Instance>;
     125             : 
     126             : } // namespace ConnectionPool
     127             : } // namespace Http
     128             : } // namespace Envoy