Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <vector>
       4             : 
       5             : #include "envoy/api/io_error.h"
       6             : #include "envoy/buffer/buffer.h"
       7             : #include "envoy/common/optref.h"
       8             : #include "envoy/common/pure.h"
       9             : #include "envoy/network/io_handle.h"
      10             : #include "envoy/network/listen_socket.h"
      11             : #include "envoy/network/post_io_action.h"
      12             : #include "envoy/network/proxy_protocol.h"
      13             : #include "envoy/ssl/connection.h"
      14             : #include "envoy/ssl/context.h"
      15             : #include "envoy/stream_info/filter_state.h"
      16             : 
      17             : #include "absl/types/optional.h"
      18             : 
      19             : namespace quic {
      20             : class QuicCryptoClientConfig;
      21             : }
      22             : 
      23             : namespace Envoy {
      24             : 
      25             : namespace Upstream {
      26             : class HostDescription;
      27             : }
      28             : namespace Ssl {
      29             : class ClientContextConfig;
      30             : }
      31             : 
      32             : namespace Network {
      33             : 
      34             : class Connection;
      35             : enum class ConnectionEvent;
      36             : 
      37             : /**
      38             :  * Result of each I/O event.
      39             :  */
      40             : struct IoResult {
      41             :   IoResult(PostIoAction action, uint64_t bytes_processed, bool end_stream_read)
      42             :       : action_(action), bytes_processed_(bytes_processed), end_stream_read_(end_stream_read),
      43           0 :         err_code_(absl::nullopt) {}
      44             : 
      45             :   IoResult(PostIoAction action, uint64_t bytes_processed, bool end_stream_read,
      46             :            absl::optional<Api::IoError::IoErrorCode> err_code)
      47             :       : action_(action), bytes_processed_(bytes_processed), end_stream_read_(end_stream_read),
      48       10326 :         err_code_(err_code) {}
      49             : 
      50             :   PostIoAction action_;
      51             : 
      52             :   /**
      53             :    * Number of bytes processed by the I/O event.
      54             :    */
      55             :   uint64_t bytes_processed_;
      56             : 
      57             :   /**
      58             :    * True if an end-of-stream was read from a connection. This
      59             :    * can only be true for read operations.
      60             :    */
      61             :   bool end_stream_read_;
      62             : 
      63             :   /**
      64             :    * The underlying I/O error code.
      65             :    */
      66             :   absl::optional<Api::IoError::IoErrorCode> err_code_;
      67             : };
      68             : 
      69             : /**
      70             :  * Callbacks used by transport socket instances to communicate with connection.
      71             :  */
      72             : class TransportSocketCallbacks {
      73             : public:
      74        2370 :   virtual ~TransportSocketCallbacks() = default;
      75             : 
      76             :   /**
      77             :    * @return reference to the IoHandle associated with the connection.
      78             :    */
      79             :   virtual IoHandle& ioHandle() PURE;
      80             : 
      81             :   /**
      82             :    * @return const reference to the IoHandle associated with the connection.
      83             :    */
      84             :   virtual const IoHandle& ioHandle() const PURE;
      85             : 
      86             :   /**
      87             :    * @return Network::Connection& the connection interface.
      88             :    */
      89             :   virtual Network::Connection& connection() PURE;
      90             : 
      91             :   /**
      92             :    * @return bool whether the read buffer should be drained. This is used to enforce yielding for
      93             :    *         configured read limits.
      94             :    */
      95             :   virtual bool shouldDrainReadBuffer() PURE;
      96             : 
      97             :   /**
      98             :    * Mark the transport socket as readable in order to force a read in a future iteration of the
      99             :    * event loop. This is used when yielding following shouldDrainReadBuffer().
     100             :    */
     101             :   virtual void setTransportSocketIsReadable() PURE;
     102             : 
     103             :   /**
     104             :    * Raise a connection event to the connection. This can be used by a secure socket (e.g. TLS)
     105             :    * to raise a connected event when handshake is done.
     106             :    * @param event supplies the connection event
     107             :    */
     108             :   virtual void raiseEvent(ConnectionEvent event) PURE;
     109             : 
     110             :   /**
     111             :    * If the callbacks' write buffer is not empty, try to drain the buffer.
     112             :    * As of 2/20, used by Google.
     113             :    */
     114             :   virtual void flushWriteBuffer() PURE;
     115             : };
     116             : 
     117             : /**
     118             :  * A transport socket that does actual read / write. It can also do some transformations on
     119             :  * the data (e.g. TLS).
     120             :  */
     121             : class TransportSocket {
     122             : public:
     123        2438 :   virtual ~TransportSocket() = default;
     124             : 
     125             :   /**
     126             :    * Called by connection once to initialize the transport socket callbacks that the transport
     127             :    * socket should use.
     128             :    * @param callbacks supplies the callbacks instance.
     129             :    */
     130             :   virtual void setTransportSocketCallbacks(TransportSocketCallbacks& callbacks) PURE;
     131             : 
     132             :   /**
     133             :    * @return std::string the protocol to use as selected by network level negotiation. (E.g., ALPN).
     134             :    *         If network level negotiation is not supported by the connection or no protocol
     135             :    *         has been negotiated the empty string is returned.
     136             :    */
     137             :   virtual std::string protocol() const PURE;
     138             : 
     139             :   /**
     140             :    * @return std::string the last failure reason occurred on the transport socket. If no failure
     141             :    *         has been occurred the empty string is returned.
     142             :    */
     143             :   virtual absl::string_view failureReason() const PURE;
     144             : 
     145             :   /**
     146             :    * @return bool whether the socket can be flushed and closed.
     147             :    */
     148             :   virtual bool canFlushClose() PURE;
     149             : 
     150             :   /**
     151             :    * Connect the underlying transport.
     152             :    * @param socket provides the socket to connect.
     153             :    * @return int the result from connect.
     154             :    */
     155        1328 :   virtual Api::SysCallIntResult connect(Network::ConnectionSocket& socket) {
     156        1328 :     return socket.connect(socket.connectionInfoProvider().remoteAddress());
     157        1328 :   }
     158             : 
     159             :   /**
     160             :    * Closes the transport socket.
     161             :    * @param event supplies the connection event that is closing the socket.
     162             :    */
     163             :   virtual void closeSocket(Network::ConnectionEvent event) PURE;
     164             : 
     165             :   /**
     166             :    * @param buffer supplies the buffer to read to.
     167             :    * @return IoResult the result of the read action.
     168             :    */
     169             :   virtual IoResult doRead(Buffer::Instance& buffer) PURE;
     170             : 
     171             :   /**
     172             :    * @param buffer supplies the buffer to write from
     173             :    * @param end_stream supplies whether this is the end of the stream. If true and all
     174             :    *        data in buffer is written, the connection will be half-closed.
     175             :    * @return IoResult the result of the write action.
     176             :    */
     177             :   virtual IoResult doWrite(Buffer::Instance& buffer, bool end_stream) PURE;
     178             : 
     179             :   /**
     180             :    * Called when underlying transport is established.
     181             :    */
     182             :   virtual void onConnected() PURE;
     183             : 
     184             :   /**
     185             :    * @return the const SSL connection data if this is an SSL connection, or nullptr if it is not.
     186             :    */
     187             :   virtual Ssl::ConnectionInfoConstSharedPtr ssl() const PURE;
     188             : 
     189             :   /**
     190             :    * Instructs a transport socket to start using secure transport.
     191             :    * It is up to the caller of this method to manage the coordination between the client
     192             :    * and server with regard to when to start secure transport. This is typically done via
     193             :    * some signal message. See STARTTLS for an example of such negotiation.
     194             :    * Note: Not all transport sockets support such operation.
     195             :    * @return boolean indicating if the transport socket was able to start secure transport.
     196             :    */
     197             :   virtual bool startSecureTransport() PURE;
     198             : 
     199             :   /**
     200             :    * Try to configure the connection's initial congestion window.
     201             :    * The operation is advisory - the connection may not support it, even if it's supported, it may
     202             :    * not do anything after the first few network round trips with the peer.
     203             :    * @param bandwidth_bits_per_sec The estimated bandwidth between the two endpoints of the
     204             :    * connection.
     205             :    * @param rtt The estimated round trip time between the two endpoints of the connection.
     206             :    */
     207             :   virtual void configureInitialCongestionWindow(uint64_t bandwidth_bits_per_sec,
     208             :                                                 std::chrono::microseconds rtt) PURE;
     209             : };
     210             : 
     211             : using TransportSocketPtr = std::unique_ptr<TransportSocket>;
     212             : 
     213             : /**
     214             :  * Options for creating transport sockets.
     215             :  */
     216             : class TransportSocketOptions {
     217             : public:
     218         404 :   virtual ~TransportSocketOptions() = default;
     219             : 
     220             :   /**
     221             :    * @return the const optional server name to set in the transport socket, for example SNI for
     222             :    *         SSL, regardless of the upstream cluster configuration. Filters that influence
     223             :    *         upstream connection selection, such as tcp_proxy, should take this option into account
     224             :    *         and should pass it through to the connection pool to ensure the correct endpoints are
     225             :    *         selected and the upstream connection is set up accordingly.
     226             :    */
     227             :   virtual const absl::optional<std::string>& serverNameOverride() const PURE;
     228             : 
     229             :   /**
     230             :    * @return the optional overridden SAN names to verify, if the transport socket supports SAN
     231             :    *         verification.
     232             :    */
     233             :   virtual const std::vector<std::string>& verifySubjectAltNameListOverride() const PURE;
     234             : 
     235             :   /**
     236             :    * The application protocols to use when negotiating an upstream connection. When an application
     237             :    * protocol override is provided, it will *always* be used.
     238             :    * @return the optional overridden application protocols.
     239             :    */
     240             :   virtual const std::vector<std::string>& applicationProtocolListOverride() const PURE;
     241             : 
     242             :   /**
     243             :    * The application protocol(s) to use when negotiating an upstream connection and no other
     244             :    * application protocol has been configured. Both
     245             :    * TransportSocketOptions::applicationProtocolListOverride and application protocols configured
     246             :    * in the CommonTlsContext on the Cluster will take precedence.
     247             :    *
     248             :    * Note that this option is intended for intermediate code (e.g. the HTTP connection pools) to
     249             :    * specify a default ALPN when no specific values are specified elsewhere. As such, providing a
     250             :    * value here might not make sense prior to load balancing.
     251             :    * @return the optional fallback(s) for application protocols, for when they are not specified in
     252             :    *         the TLS configuration.
     253             :    */
     254             :   virtual const std::vector<std::string>& applicationProtocolFallback() const PURE;
     255             : 
     256             :   /**
     257             :    * @return optional PROXY protocol address information.
     258             :    */
     259             :   virtual absl::optional<Network::ProxyProtocolData> proxyProtocolOptions() const PURE;
     260             : 
     261             :   // Information for use by the http_11_proxy transport socket.
     262             :   struct Http11ProxyInfo {
     263             :     Http11ProxyInfo(std::string hostname, Network::Address::InstanceConstSharedPtr address)
     264           0 :         : hostname(hostname), proxy_address(address) {}
     265             :     // The hostname of the original request, to be used in CONNECT request if
     266             :     // the underlying transport is TLS.
     267             :     std::string hostname;
     268             :     // The address of the proxy, where connections should be routed to.
     269             :     Network::Address::InstanceConstSharedPtr proxy_address;
     270             :   };
     271             : 
     272             :   /**
     273             :    * @return any proxy information if sending to an intermediate proxy over HTTP/1.1.
     274             :    */
     275             :   virtual OptRef<const Http11ProxyInfo> http11ProxyInfo() const PURE;
     276             : 
     277             :   /**
     278             :    * @return filter state objects from the downstream request or connection
     279             :    * that are marked as shared with the upstream connection.
     280             :    */
     281             :   virtual const StreamInfo::FilterState::Objects& downstreamSharedFilterStateObjects() const PURE;
     282             : };
     283             : 
     284             : using TransportSocketOptionsConstSharedPtr = std::shared_ptr<const TransportSocketOptions>;
     285             : 
     286             : /**
     287             :  * A factory for creating transport sockets.
     288             :  **/
     289             : class TransportSocketFactoryBase {
     290             : public:
     291        4791 :   virtual ~TransportSocketFactoryBase() = default;
     292             : 
     293             :   /**
     294             :    * @return bool whether the transport socket implements secure transport.
     295             :    */
     296             :   virtual bool implementsSecureTransport() const PURE;
     297             : };
     298             : 
     299             : /**
     300             :  * A factory for creating upstream transport sockets. It will be associated to clusters.
     301             :  */
     302             : class UpstreamTransportSocketFactory : public virtual TransportSocketFactoryBase {
     303             : public:
     304        4791 :   ~UpstreamTransportSocketFactory() override = default;
     305             : 
     306             :   /**
     307             :    * @param options for creating the transport socket
     308             :    * @param host description for the destination upstream host
     309             :    * @return Network::TransportSocketPtr a transport socket to be passed to client connection.
     310             :    */
     311             :   virtual TransportSocketPtr
     312             :   createTransportSocket(TransportSocketOptionsConstSharedPtr options,
     313             :                         std::shared_ptr<const Upstream::HostDescription> host) const PURE;
     314             : 
     315             :   /**
     316             :    * Returns true if the transport socket created by this factory supports some form of ALPN
     317             :    * negotiation.
     318             :    */
     319         159 :   virtual bool supportsAlpn() const { return false; }
     320             : 
     321             :   /**
     322             :    * Returns the default SNI for transport sockets created by this factory.
     323             :    * This will return an empty string view if the transport sockets created are
     324             :    * not client-side TLS sockets.
     325             :    */
     326             :   virtual absl::string_view defaultServerNameIndication() const PURE;
     327             : 
     328             :   /**
     329             :    * @param key supplies a vector of bytes to which the option should append hash key data that will
     330             :    *        be used to separate connections based on the option. Any data already in the key vector
     331             :    *        must not be modified.
     332             :    * @param options supplies the transport socket options.
     333             :    */
     334             :   virtual void hashKey(std::vector<uint8_t>& key,
     335             :                        TransportSocketOptionsConstSharedPtr options) const PURE;
     336             : 
     337             :   /*
     338             :    * @return the pointer to the SSL context, or nullptr for non-TLS factories.
     339             :    */
     340           0 :   virtual Envoy::Ssl::ClientContextSharedPtr sslCtx() { return nullptr; }
     341             : 
     342             :   /*
     343             :    * @return the ClientContextConfig, or absl::nullopt for non-TLS factories.
     344             :    */
     345           0 :   virtual OptRef<const Ssl::ClientContextConfig> clientContextConfig() const { return {}; }
     346             : 
     347             :   /*
     348             :    * @return the QuicCryptoClientConfig or nullptr for non-QUIC factories.
     349             :    */
     350           0 :   virtual std::shared_ptr<quic::QuicCryptoClientConfig> getCryptoConfig() { return nullptr; }
     351             : };
     352             : 
     353             : /**
     354             :  * A factory for creating downstream transport sockets. It will be associated to listeners.
     355             :  */
     356             : class DownstreamTransportSocketFactory : public virtual TransportSocketFactoryBase {
     357             : public:
     358        3055 :   ~DownstreamTransportSocketFactory() override = default;
     359             : 
     360             :   /**
     361             :    * @return Network::TransportSocketPtr a transport socket to be passed to server connection.
     362             :    */
     363             :   virtual TransportSocketPtr createDownstreamTransportSocket() const PURE;
     364             : };
     365             : 
     366             : using UpstreamTransportSocketFactoryPtr = std::unique_ptr<UpstreamTransportSocketFactory>;
     367             : using DownstreamTransportSocketFactoryPtr = std::unique_ptr<DownstreamTransportSocketFactory>;
     368             : 
     369             : } // namespace Network
     370             : } // namespace Envoy