Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <functional>
       4             : #include <memory>
       5             : 
       6             : #include "envoy/buffer/buffer.h"
       7             : #include "envoy/common/conn_pool.h"
       8             : #include "envoy/common/pure.h"
       9             : #include "envoy/event/deferred_deletable.h"
      10             : #include "envoy/upstream/upstream.h"
      11             : 
      12             : namespace Envoy {
      13             : namespace Tcp {
      14             : namespace ConnectionPool {
      15             : 
      16             : /*
      17             :  * UpstreamCallbacks for connection pool upstream connection callbacks and data. Note that
      18             :  * onEvent(Connected) is never triggered since the event always occurs before a ConnectionPool
      19             :  * caller is assigned a connection.
      20             :  */
      21             : class UpstreamCallbacks : public Network::ConnectionCallbacks {
      22             : public:
      23           0 :   ~UpstreamCallbacks() override = default;
      24             : 
      25             :   /*
      26             :    * Invoked when data is delivered from the upstream connection while the connection is owned by a
      27             :    * ConnectionPool::Instance caller.
      28             :    * @param data supplies data from the upstream
      29             :    * @param end_stream whether the data is the last data frame
      30             :    */
      31             :   virtual void onUpstreamData(Buffer::Instance& data, bool end_stream) PURE;
      32             : };
      33             : 
      34             : /**
      35             :  * ConnectionState is a base class for connection state maintained across requests. For example, a
      36             :  * protocol may maintain a connection-specific request sequence number or negotiate options that
      37             :  * affect the behavior of requests for the duration of the connection. A ConnectionState subclass
      38             :  * is assigned to the ConnectionData to track this state when the connection is returned to the
      39             :  * pool so that the state is available when the connection is re-used for a subsequent request.
      40             :  * The ConnectionState assigned to a connection is automatically destroyed when the connection is
      41             :  * closed.
      42             :  */
      43             : class ConnectionState {
      44             : public:
      45           0 :   virtual ~ConnectionState() = default;
      46             : };
      47             : 
      48             : using ConnectionStatePtr = std::unique_ptr<ConnectionState>;
      49             : 
      50             : /*
      51             :  * ConnectionData wraps a ClientConnection allocated to a caller. Open ClientConnections are
      52             :  * released back to the pool for re-use when their containing ConnectionData is destroyed.
      53             :  */
      54             : class ConnectionData {
      55             : public:
      56         208 :   virtual ~ConnectionData() = default;
      57             : 
      58             :   /**
      59             :    * @return the ClientConnection for the connection.
      60             :    */
      61             :   virtual Network::ClientConnection& connection() PURE;
      62             : 
      63             :   /**
      64             :    * Sets the ConnectionState for this connection. Any existing ConnectionState is destroyed.
      65             :    * @param ConnectionStatePtr&& new ConnectionState for this connection.
      66             :    */
      67             :   virtual void setConnectionState(ConnectionStatePtr&& state) PURE;
      68             : 
      69             :   /**
      70             :    * @return T* the current ConnectionState or nullptr if no state is set or if the state's type
      71             :    *            is not T.
      72             :    */
      73           0 :   template <class T> T* connectionStateTyped() { return dynamic_cast<T*>(connectionState()); }
      74             : 
      75             :   /**
      76             :    * Sets the ConnectionPool::UpstreamCallbacks for the connection. If no callback is attached,
      77             :    * data from the upstream will cause the connection to be closed. Callbacks cease when the
      78             :    * connection is released.
      79             :    * @param callback the UpstreamCallbacks to invoke for upstream data
      80             :    */
      81             :   virtual void addUpstreamCallbacks(ConnectionPool::UpstreamCallbacks& callback) PURE;
      82             : 
      83             : protected:
      84             :   /**
      85             :    * @return ConnectionState* pointer to the current ConnectionState or nullptr if not set
      86             :    */
      87             :   virtual ConnectionState* connectionState() PURE;
      88             : };
      89             : 
      90             : using ConnectionDataPtr = std::unique_ptr<ConnectionData>;
      91             : using PoolFailureReason = ::Envoy::ConnectionPool::PoolFailureReason;
      92             : using Cancellable = ::Envoy::ConnectionPool::Cancellable;
      93             : using CancelPolicy = ::Envoy::ConnectionPool::CancelPolicy;
      94             : 
      95             : /**
      96             :  * Pool callbacks invoked in the context of a newConnection() call, either synchronously or
      97             :  * asynchronously.
      98             :  */
      99             : class Callbacks {
     100             : public:
     101           0 :   virtual ~Callbacks() = default;
     102             : 
     103             :   /**
     104             :    * Called when a pool error occurred and no connection could be acquired for making the request.
     105             :    * @param reason supplies the failure reason.
     106             :    * @param transport_failure_reason supplies the details of the transport failure reason.
     107             :    * @param host supplies the description of the host that caused the failure. This may be nullptr
     108             :    *             if no host was involved in the failure (for example overflow).
     109             :    */
     110             :   virtual void onPoolFailure(PoolFailureReason reason, absl::string_view transport_failure_reason,
     111             :                              Upstream::HostDescriptionConstSharedPtr host) PURE;
     112             : 
     113             :   /**
     114             :    * Called when a connection is available to process a request/response. Connections may be
     115             :    * released back to the pool for re-use by resetting the ConnectionDataPtr. If the connection is
     116             :    * no longer viable for reuse (e.g. due to some kind of protocol error), the underlying
     117             :    * ClientConnection should be closed to prevent its reuse.
     118             :    *
     119             :    * @param conn supplies the connection data to use.
     120             :    * @param host supplies the description of the host that will carry the request. For logical
     121             :    *             connection pools the description may be different each time this is called.
     122             :    */
     123             :   virtual void onPoolReady(ConnectionDataPtr&& conn,
     124             :                            Upstream::HostDescriptionConstSharedPtr host) PURE;
     125             : };
     126             : 
     127             : /**
     128             :  * An instance of a generic connection pool.
     129             :  */
     130             : class Instance : public Envoy::ConnectionPool::Instance, public Event::DeferredDeletable {
     131             : public:
     132             :   /**
     133             :    * Immediately close all existing connection pool connections. This method can be used in cases
     134             :    * where the connection pool is not being destroyed, but the caller wishes to terminate all
     135             :    * existing connections. For example, when a health check failure occurs.
     136             :    */
     137             :   virtual void closeConnections() PURE;
     138             : 
     139             :   /**
     140             :    * Create a new connection on the pool.
     141             :    * @param cb supplies the callbacks to invoke when the connection is ready or has failed. The
     142             :    *           callbacks may be invoked immediately within the context of this call if there is a
     143             :    *           ready connection or an immediate failure. In this case, the routine returns nullptr.
     144             :    * @return Cancellable* If no connection is ready, the callback is not invoked, and a handle
     145             :    *                      is returned that can be used to cancel the request. Otherwise, one of the
     146             :    *                      callbacks is called and the routine returns nullptr. NOTE: Once a callback
     147             :    *                      is called, the handle is no longer valid and any further cancellation
     148             :    *                      should be done by resetting the connection.
     149             :    */
     150             :   virtual Cancellable* newConnection(Callbacks& callbacks) PURE;
     151             : };
     152             : 
     153             : using InstancePtr = std::unique_ptr<Instance>;
     154             : 
     155             : } // namespace ConnectionPool
     156             : } // namespace Tcp
     157             : } // namespace Envoy