Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <chrono>
       4             : #include <cstdint>
       5             : #include <memory>
       6             : #include <string>
       7             : 
       8             : #include "envoy/buffer/buffer.h"
       9             : #include "envoy/common/pure.h"
      10             : #include "envoy/common/scope_tracker.h"
      11             : #include "envoy/event/deferred_deletable.h"
      12             : #include "envoy/network/address.h"
      13             : #include "envoy/network/filter.h"
      14             : #include "envoy/network/listen_socket.h"
      15             : #include "envoy/network/socket.h"
      16             : #include "envoy/ssl/connection.h"
      17             : #include "envoy/stream_info/stream_info.h"
      18             : 
      19             : namespace Envoy {
      20             : namespace Event {
      21             : class Dispatcher;
      22             : }
      23             : 
      24             : namespace Network {
      25             : 
      26             : /**
      27             :  * Events that occur on a connection.
      28             :  */
      29             : enum class ConnectionEvent {
      30             :   RemoteClose,
      31             :   LocalClose,
      32             :   Connected,
      33             :   ConnectedZeroRtt,
      34             : };
      35             : 
      36             : /**
      37             :  * Connections have both a read and write buffer.
      38             :  */
      39             : enum class ConnectionBufferType { Read, Write };
      40             : 
      41             : /**
      42             :  * Network level callbacks that happen on a connection.
      43             :  */
      44             : class ConnectionCallbacks {
      45             : public:
      46        3948 :   virtual ~ConnectionCallbacks() = default;
      47             : 
      48             :   /**
      49             :    * Callback for connection events.
      50             :    * @param events supplies the ConnectionEvent that occurred.
      51             :    */
      52             :   virtual void onEvent(ConnectionEvent event) PURE;
      53             : 
      54             :   /**
      55             :    * Called when the write buffer for a connection goes over its high watermark.
      56             :    */
      57             :   virtual void onAboveWriteBufferHighWatermark() PURE;
      58             : 
      59             :   /**
      60             :    * Called when the write buffer for a connection goes from over its high
      61             :    * watermark to under its low watermark.
      62             :    */
      63             :   virtual void onBelowWriteBufferLowWatermark() PURE;
      64             : };
      65             : 
      66             : /**
      67             :  * Type of connection close to perform.
      68             :  */
      69             : enum class ConnectionCloseType {
      70             :   FlushWrite, // Flush pending write data before raising ConnectionEvent::LocalClose
      71             :   NoFlush, // Do not flush any pending data. Write the pending data to buffer and then immediately
      72             :            // raise ConnectionEvent::LocalClose
      73             :   FlushWriteAndDelay, // Flush pending write data and delay raising a ConnectionEvent::LocalClose
      74             :                       // until the delayed_close_timeout expires
      75             :   Abort, // Do not write/flush any pending data and immediately raise ConnectionEvent::LocalClose
      76             :   AbortReset // Do not write/flush any pending data and immediately raise
      77             :              // ConnectionEvent::LocalClose. Envoy will try to close the connection with RST flag.
      78             : };
      79             : 
      80             : /**
      81             :  * Type of connection close which is detected from the socket.
      82             :  */
      83             : enum class DetectedCloseType {
      84             :   Normal,      // The normal socket close from Envoy's connection perspective.
      85             :   LocalReset,  // The local reset initiated from Envoy.
      86             :   RemoteReset, // The peer reset detected by the connection.
      87             : };
      88             : 
      89             : /**
      90             :  * An abstract raw connection. Free the connection or call close() to disconnect.
      91             :  */
      92             : class Connection : public Event::DeferredDeletable,
      93             :                    public FilterManager,
      94             :                    public ScopeTrackedObject {
      95             : public:
      96             :   enum class State { Open, Closing, Closed };
      97             : 
      98             :   enum class ReadDisableStatus {
      99             :     NoTransition,
     100             :     StillReadDisabled,
     101             :     TransitionedToReadEnabled,
     102             :     TransitionedToReadDisabled
     103             :   };
     104             : 
     105             :   /**
     106             :    * Callback function for when bytes have been sent by a connection.
     107             :    * @param bytes_sent supplies the number of bytes written to the connection.
     108             :    * @return indicates if callback should be called in the future. If true is returned
     109             :    * the callback will be called again in the future. If false is returned, the callback
     110             :    * will be removed from callback list.
     111             :    */
     112             :   using BytesSentCb = std::function<bool(uint64_t bytes_sent)>;
     113             : 
     114             :   struct ConnectionStats {
     115             :     Stats::Counter& read_total_;
     116             :     Stats::Gauge& read_current_;
     117             :     Stats::Counter& write_total_;
     118             :     Stats::Gauge& write_current_;
     119             :     // Counter* as this is an optional counter. Bind errors will not be tracked if this is nullptr.
     120             :     Stats::Counter* bind_errors_;
     121             :     // Optional counter. Delayed close timeouts will not be tracked if this is nullptr.
     122             :     Stats::Counter* delayed_close_timeouts_;
     123             :   };
     124             : 
     125        3541 :   ~Connection() override = default;
     126             : 
     127             :   /**
     128             :    * Register callbacks that fire when connection events occur.
     129             :    */
     130             :   virtual void addConnectionCallbacks(ConnectionCallbacks& cb) PURE;
     131             : 
     132             :   /**
     133             :    * Unregister callbacks which previously fired when connection events occur.
     134             :    */
     135             :   virtual void removeConnectionCallbacks(ConnectionCallbacks& cb) PURE;
     136             : 
     137             :   /**
     138             :    * Register for callback every time bytes are written to the underlying TransportSocket.
     139             :    */
     140             :   virtual void addBytesSentCallback(BytesSentCb cb) PURE;
     141             : 
     142             :   /**
     143             :    * Enable half-close semantics on this connection. Reading a remote half-close
     144             :    * will not fully close the connection. This is off by default.
     145             :    * @param enabled Whether to set half-close semantics as enabled or disabled.
     146             :    */
     147             :   virtual void enableHalfClose(bool enabled) PURE;
     148             : 
     149             :   /**
     150             :    * @return true if half-close semantics are enabled, false otherwise.
     151             :    */
     152             :   virtual bool isHalfCloseEnabled() const PURE;
     153             : 
     154             :   /**
     155             :    * Close the connection.
     156             :    * @param type the connection close type.
     157             :    */
     158             :   virtual void close(ConnectionCloseType type) PURE;
     159             : 
     160             :   /**
     161             :    * Close the connection.
     162             :    * @param type the connection close type.
     163             :    * @param details the reason the connection is being closed.
     164             :    */
     165             :   virtual void close(ConnectionCloseType type, absl::string_view details) PURE;
     166             : 
     167             :   /**
     168             :    * @return the detected close type from socket.
     169             :    */
     170             :   virtual DetectedCloseType detectedCloseType() const PURE;
     171             : 
     172             :   /**
     173             :    * @return Event::Dispatcher& the dispatcher backing this connection.
     174             :    */
     175             :   virtual Event::Dispatcher& dispatcher() const PURE;
     176             : 
     177             :   /**
     178             :    * @return uint64_t the unique local ID of this connection.
     179             :    */
     180             :   virtual uint64_t id() const PURE;
     181             : 
     182             :   /**
     183             :    * @param vector of bytes to which the connection should append hash key data. Any data already in
     184             :    * the key vector must not be modified.
     185             :    */
     186             :   virtual void hashKey(std::vector<uint8_t>& hash) const PURE;
     187             : 
     188             :   /**
     189             :    * @return std::string the next protocol to use as selected by network level negotiation. (E.g.,
     190             :    *         ALPN). If network level negotiation is not supported by the connection or no protocol
     191             :    *         has been negotiated the empty string is returned.
     192             :    */
     193             :   virtual std::string nextProtocol() const PURE;
     194             : 
     195             :   /**
     196             :    * Enable/Disable TCP NO_DELAY on the connection.
     197             :    */
     198             :   virtual void noDelay(bool enable) PURE;
     199             : 
     200             :   /**
     201             :    * Disable socket reads on the connection, applying external back pressure. When reads are
     202             :    * enabled again if there is data still in the input buffer it will be re-dispatched through
     203             :    * the filter chain.
     204             :    * @param disable supplies TRUE is reads should be disabled, FALSE if they should be enabled.
     205             :    * @return status enum indicating the outcome of calling readDisable on the underlying socket.
     206             :    *
     207             :    * Note that this function reference counts calls. For example
     208             :    * readDisable(true);  // Disables data
     209             :    * readDisable(true);  // Notes the connection is blocked by two sources
     210             :    * readDisable(false);  // Notes the connection is blocked by one source
     211             :    * readDisable(false);  // Marks the connection as unblocked, so resumes reading.
     212             :    */
     213             :   virtual ReadDisableStatus readDisable(bool disable) PURE;
     214             : 
     215             :   /**
     216             :    * Set if Envoy should detect TCP connection close when readDisable(true) is called.
     217             :    * By default, this is true on newly created connections.
     218             :    *
     219             :    * @param should_detect supplies if disconnects should be detected when the connection has been
     220             :    * read disabled
     221             :    */
     222             :   virtual void detectEarlyCloseWhenReadDisabled(bool should_detect) PURE;
     223             : 
     224             :   /**
     225             :    * @return bool whether reading is enabled on the connection.
     226             :    */
     227             :   virtual bool readEnabled() const PURE;
     228             : 
     229             :   /**
     230             :    * @return the connection info provider backing this connection.
     231             :    */
     232             :   virtual ConnectionInfoSetter& connectionInfoSetter() PURE;
     233             :   virtual const ConnectionInfoProvider& connectionInfoProvider() const PURE;
     234             :   virtual ConnectionInfoProviderSharedPtr connectionInfoProviderSharedPtr() const PURE;
     235             : 
     236             :   /**
     237             :    * Credentials of the peer of a socket as decided by SO_PEERCRED.
     238             :    */
     239             :   struct UnixDomainSocketPeerCredentials {
     240             :     /**
     241             :      * The process id of the peer.
     242             :      */
     243             :     int32_t pid;
     244             :     /**
     245             :      * The user id of the peer.
     246             :      */
     247             :     uint32_t uid;
     248             :     /**
     249             :      * The group id of the peer.
     250             :      */
     251             :     uint32_t gid;
     252             :   };
     253             : 
     254             :   /**
     255             :    * @return The unix socket peer credentials of the remote client. Note that this is only
     256             :    * supported for unix socket connections.
     257             :    */
     258             :   virtual absl::optional<UnixDomainSocketPeerCredentials> unixSocketPeerCredentials() const PURE;
     259             : 
     260             :   /**
     261             :    * Set the stats to update for various connection state changes. Note that for performance reasons
     262             :    * these stats are eventually consistent and may not always accurately represent the connection
     263             :    * state at any given point in time.
     264             :    */
     265             :   virtual void setConnectionStats(const ConnectionStats& stats) PURE;
     266             : 
     267             :   /**
     268             :    * @return the const SSL connection data if this is an SSL connection, or nullptr if it is not.
     269             :    */
     270             :   // TODO(snowp): Remove this in favor of StreamInfo::downstreamSslConnection.
     271             :   virtual Ssl::ConnectionInfoConstSharedPtr ssl() const PURE;
     272             : 
     273             :   /**
     274             :    * @return requested server name (e.g. SNI in TLS), if any.
     275             :    */
     276             :   virtual absl::string_view requestedServerName() const PURE;
     277             : 
     278             :   /**
     279             :    * @return State the current state of the connection.
     280             :    */
     281             :   virtual State state() const PURE;
     282             : 
     283             :   /**
     284             :    * @return true if the connection has not completed connecting, false if the connection is
     285             :    * established.
     286             :    */
     287             :   virtual bool connecting() const PURE;
     288             : 
     289             :   /**
     290             :    * Write data to the connection. Will iterate through network filters with the buffer if any
     291             :    * are installed.
     292             :    * @param data Supplies the data to write to the connection.
     293             :    * @param end_stream If true, this indicates that this is the last write to the connection. If
     294             :    *        end_stream is true, the connection is half-closed. This may only be set to true if
     295             :    *        enableHalfClose(true) has been set on this connection.
     296             :    */
     297             :   virtual void write(Buffer::Instance& data, bool end_stream) PURE;
     298             : 
     299             :   /**
     300             :    * Set a soft limit on the size of buffers for the connection.
     301             :    * For the read buffer, this limits the bytes read prior to flushing to further stages in the
     302             :    * processing pipeline.
     303             :    * For the write buffer, it sets watermarks. When enough data is buffered it triggers a call to
     304             :    * onAboveWriteBufferHighWatermark, which allows subscribers to enforce flow control by disabling
     305             :    * reads on the socket funneling data to the write buffer. When enough data is drained from the
     306             :    * write buffer, onBelowWriteBufferHighWatermark is called which similarly allows subscribers
     307             :    * resuming reading.
     308             :    */
     309             :   virtual void setBufferLimits(uint32_t limit) PURE;
     310             : 
     311             :   /**
     312             :    * Get the value set with setBufferLimits.
     313             :    */
     314             :   virtual uint32_t bufferLimit() const PURE;
     315             : 
     316             :   /**
     317             :    * @return boolean telling if the connection is currently above the high watermark.
     318             :    */
     319             :   virtual bool aboveHighWatermark() const PURE;
     320             : 
     321             :   /**
     322             :    * Get the socket options set on this connection.
     323             :    */
     324             :   virtual const ConnectionSocket::OptionsSharedPtr& socketOptions() const PURE;
     325             : 
     326             :   /**
     327             :    * The StreamInfo object associated with this connection. This is typically
     328             :    * used for logging purposes. Individual filters may add specific information
     329             :    * via the FilterState object within the StreamInfo object. The StreamInfo
     330             :    * object in this context is one per connection i.e. different than the one in
     331             :    * the http ConnectionManager implementation which is one per request.
     332             :    *
     333             :    * @return StreamInfo object associated with this connection.
     334             :    */
     335             :   virtual StreamInfo::StreamInfo& streamInfo() PURE;
     336             :   virtual const StreamInfo::StreamInfo& streamInfo() const PURE;
     337             : 
     338             :   /**
     339             :    * Set the timeout for delayed connection close()s.
     340             :    * This can only be called prior to issuing a close() on the connection.
     341             :    * @param timeout The timeout value in milliseconds
     342             :    */
     343             :   virtual void setDelayedCloseTimeout(std::chrono::milliseconds timeout) PURE;
     344             : 
     345             :   /**
     346             :    * @return absl::string_view the failure reason of the underlying transport socket, if no failure
     347             :    *         occurred an empty string view is returned.
     348             :    */
     349             :   virtual absl::string_view transportFailureReason() const PURE;
     350             : 
     351             :   /**
     352             :    * @return absl::string_view the local close reason of the underlying socket, if local close
     353             :    *         did not occur an empty string view is returned.
     354             :    */
     355             :   virtual absl::string_view localCloseReason() const PURE;
     356             : 
     357             :   /**
     358             :    * Instructs the connection to start using secure transport.
     359             :    * Note: Not all underlying transport sockets support such operation.
     360             :    * @return boolean telling if underlying transport socket was able to
     361             :              start secure transport.
     362             :    */
     363             :   virtual bool startSecureTransport() PURE;
     364             : 
     365             :   /**
     366             :    *  @return absl::optional<std::chrono::milliseconds> An optional of the most recent round-trip
     367             :    *  time of the connection. If the platform does not support this, then an empty optional is
     368             :    *  returned.
     369             :    */
     370             :   virtual absl::optional<std::chrono::milliseconds> lastRoundTripTime() const PURE;
     371             : 
     372             :   /**
     373             :    * Try to configure the connection's initial congestion window.
     374             :    * The operation is advisory - the connection may not support it, even if it's supported, it may
     375             :    * not do anything after the first few network round trips with the peer.
     376             :    * @param bandwidth_bits_per_sec The estimated bandwidth between the two endpoints of the
     377             :    * connection.
     378             :    * @param rtt The estimated round trip time between the two endpoints of the connection.
     379             :    *
     380             :    * @note Envoy does not provide an implementation for TCP connections because
     381             :    * there is no portable system api to do so. Applications can implement it
     382             :    * with a proprietary api in a customized TransportSocket.
     383             :    */
     384             :   virtual void configureInitialCongestionWindow(uint64_t bandwidth_bits_per_sec,
     385             :                                                 std::chrono::microseconds rtt) PURE;
     386             : 
     387             :   /**
     388             :    * @return the current congestion window in bytes, or unset if not available or not
     389             :    * congestion-controlled.
     390             :    * @note some congestion controller's cwnd is measured in number of packets, in that case the
     391             :    * return value is cwnd(in packets) times the connection's MSS.
     392             :    */
     393             :   virtual absl::optional<uint64_t> congestionWindowInBytes() const PURE;
     394             : };
     395             : 
     396             : using ConnectionPtr = std::unique_ptr<Connection>;
     397             : 
     398             : /**
     399             :  * Connections servicing inbound connects.
     400             :  */
     401             : class ServerConnection : public virtual Connection {
     402             : public:
     403             :   /**
     404             :    * Set the amount of time allowed for the transport socket to report that a connection is
     405             :    * established. The provided timeout is relative to the current time. If this method is called
     406             :    * after a connection has already been established, it is a no-op.
     407             :    *
     408             :    * If a timeout occurs, `timeout_stat` will be incremented.
     409             :    */
     410             :   virtual void setTransportSocketConnectTimeout(std::chrono::milliseconds timeout,
     411             :                                                 Stats::Counter& timeout_stat) PURE;
     412             : };
     413             : 
     414             : using ServerConnectionPtr = std::unique_ptr<ServerConnection>;
     415             : 
     416             : /**
     417             :  * Connections capable of outbound connects.
     418             :  */
     419             : class ClientConnection : public virtual Connection {
     420             : public:
     421             :   /**
     422             :    * Connect to a remote host. Errors or connection events are reported via the event callback
     423             :    * registered via addConnectionCallbacks().
     424             :    */
     425             :   virtual void connect() PURE;
     426             : };
     427             : 
     428             : using ClientConnectionPtr = std::unique_ptr<ClientConnection>;
     429             : 
     430             : } // namespace Network
     431             : } // namespace Envoy