services/network/public/mojom/proxy_resolving_socket.mojom

// Copyright 2018 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "services/network/public/mojom/ip_endpoint.mojom";
import "services/network/public/mojom/mutable_network_traffic_annotation_tag.mojom";
import "services/network/public/mojom/network_isolation_key.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/ssl_config.mojom";
import "services/network/public/mojom/tcp_socket.mojom";
import "services/network/public/mojom/tls_socket.mojom";
import "url/mojom/url.mojom";

// Represents a connected socket that respects system's proxy settings. Writes
// and Reads are through the data pipes supplied upon construction. Consumer
// can close the socket by destroying the interface pointer.
interface ProxyResolvingSocket {
  // TODO(xunjieli): Add methods to configure the socket connection and allow
  // consumers to specify whether they want to disconnect or return the socket
  // to socket pools.

  // Upgrades a proxy socket to a TLS client socket.
  // IMPORTANT: Caller needs close the previous send and receive pipes before
  // this method can complete asynchronously.
  //
  // On success, |net_error| is net::OK. Caller is to use |send_stream| to send
  // data and |receive_stream| to receive data over the connection. On failure,
  // |result| is a network error code.
  UpgradeToTLS(HostPortPair host_port_pair,
               MutableNetworkTrafficAnnotationTag traffic_annotation,
               pending_receiver<TLSClientSocket> receiver,
               pending_remote<SocketObserver>? observer)
      => (int32 net_error,
          handle<data_pipe_consumer>? receive_stream,
          handle<data_pipe_producer>? send_stream);
};

struct ProxyResolvingSocketOptions {
  // Establish a TLS connection on top of the TCP connection.
  bool use_tls = false;

  // Tries to do a fake TLS handshake on the connection.
  // This is sometimes used with XMPP to pass through proxies.
  // See jingle_glue::FakeSSLClientSocket for more details.
  // Should not be used with |use_tls| set to true.
  bool fake_tls_handshake = false;
};

// Factory interface for creating ProxyResolvingSocket. Each factory instance
// has separate socket pools from the NetworkContext which created the
// factory instance.
interface ProxyResolvingSocketFactory {
  // Creates a socket connected to |url|. This connection might be done through
  // proxies if any is set in system's proxy settings.
  //
  // |network_isolation_key| indicates the network storage shard to use for
  // shared resources, such as the DNS cache and shared proxy connections.
  //
  // On success, |result| is net::OK. Caller is to use |send_stream| to send
  // data and |receive_stream| to receive data over the connection. On failure,
  // |result| is a network error code. |local_addr| contains the local address
  // of the socket. |peer_addr| contains the peer address. If socket is
  // connected to a proxy, |peer_addr| will be null.
  //
  // If socket is closed before the callback can be completed, the callback will
  // be invoked with net::ERR_ABORTED.
  //
  // Any sockets that are created but are yet to be destroyed will be destroyed
  // when the implementation of this factory goes away.
  CreateProxyResolvingSocket(
      url.mojom.Url url,
      NetworkIsolationKey network_isolation_key,
      ProxyResolvingSocketOptions? options,
      MutableNetworkTrafficAnnotationTag traffic_annotation,
      pending_receiver<ProxyResolvingSocket> socket,
      pending_remote<SocketObserver>? observer)
     => (int32 result,
         network.mojom.IPEndPoint? local_addr,
         network.mojom.IPEndPoint? peer_addr,
         handle<data_pipe_consumer>? receive_stream,
         handle<data_pipe_producer>? send_stream);
};