services/network/public/mojom/network_service.mojom - chromium/src - Git at Google

 // Copyright 2017 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 "cookie_manager.mojom";
 import "network_change_manager.mojom";
 import "proxy_config.mojom";
 import "net/interfaces/ip_endpoint.mojom";
 import "url_loader.mojom";
 import "url_loader_factory.mojom";
 import "restricted_cookie_manager.mojom";
 import "mojo/common/file_path.mojom";
 import "mojo/common/time.mojom";
 import "url/mojom/url.mojom";
 import "services/network/public/mojom/udp_socket.mojom";
 import "services/proxy_resolver/public/mojom/proxy_resolver.mojom";

 // Parameters for constructing a network context.
 struct NetworkContextParams {
   // Name used by memory tools to identify the context.
   string? context_name;

   // The user agent string.
   string user_agent;

   // Whether Brotli content-encoding should be enabled for HTTPS responses.
   bool enable_brotli = true;

   // QUIC user agent.
   string quic_user_agent_id;

   // Handles PAC script execution. If not populated, will attempt to use
   // platform implementation to execute PAC scripts, if available (Only
   // available on Windows and Mac).
   proxy_resolver.mojom.ProxyResolverFactory? proxy_resolver_factory;

   // Points to the cookie file. An in-memory cookie store is used if it's empty.
   mojo.common.mojom.FilePath? cookie_path;

   // If the cookie file is given, this controls whether previously written
   // session cookies are restored. Otherwise it should be false.
   bool restore_old_session_cookies = false;

   // If the cookie file is given, this controls whether to persist session
   // cookies. Otherwise it should be false.
   bool persist_session_cookies = false;

   // Points to the channel ID file. If a cookie file is specified, this must be
   // specifed as well. Otherwise an in-memory store is used.
   mojo.common.mojom.FilePath? channel_id_path;

   // True if an HTTP cache should be used.
   bool http_cache_enabled = true;
   // Maximum size of the HTTP cache. 0 means to use the default size.
   // Ignored if the cache is disabled.
   int32 http_cache_max_size = 0;
   // Points to the HTTP cache directory. Ignored if the cache is disabled.
   // If null and the cache is enabled, an in-memory database is used.
   mojo.common.mojom.FilePath? http_cache_path;

   // The file to store cached server properties (Like HTTP2 and QUIC support).
   // This information is used as a performance optimization in connection
   // logic. If null, an in-memory cache will be used instead.
   mojo.common.mojom.FilePath? http_server_properties_path;

   // Enabled protocols. Note that these apply to all fetches, including those
   // used to fetch PAC scripts.

   // True if data URLs should be supported.
   bool enable_data_url_support = false;
   // True if file URLs should be supported.
   // Must be false if built without file support.
   bool enable_file_url_support = false;
   // True if ftp URLs should be supported.
   // Must be false if built without FTP support.
   bool enable_ftp_url_support = false;

   // Enables HTTP/0.9 on ports other than 80 for HTTP and 443 for HTTPS.
   bool http_09_on_non_default_ports_enabled = false;

   // Proxy configuration. If |intial_proxy_config| is set, it's the initial
   // proxy configuration. Updated proxy configuration can be passed in via
   // |proxy_config_client_request|. If |initial_proxy_config| is not set,
   // proxy lookups will be deferred until a configuration is received via
   // |proxy_config_client_request|.
   //
   // If both are null, the NetworkContext will not use a proxy.
   ProxyConfig? initial_proxy_config;
   ProxyConfigClient&? proxy_config_client_request;

   // If |proxy_config_client_request| is non-null, this is called during
   // periods of network activity, and can be used as a signal for polling-based
   // logic to determine the proxy config.
   //
   // TODO(mmenke): Can the consumer piggy back on other network events through
   // other channels (navigation, issuing requests, etc)? Or can
   // ProxyConfigServices be modified not to need this notification?
   ProxyConfigPollerClient? proxy_config_poller_client;
 };

 struct NetworkConditions {
   // If set, the offline state is simulated and other fields are ignored.
   bool offline;

   // Channel round-trip latency, i.e. minimum time between request sent and
   // response received.
   mojo.common.mojom.TimeDelta latency;

   // Maximal aggregated download throughput (bytes/sec). 0 disables download throttling.
   double download_throughput;

   // Maximal aggregated upload throughput (bytes/sec). 0 disables upload throttling.
   double upload_throughput;
 };

 // Represents a distinct context for making network requests, with its own
 // storage (e.g. cookies and cache).
 interface NetworkContext {
   // |process_id| is 0 for requests initiated in the browser process, otherwise
   // it's the child process ID.
   CreateURLLoaderFactory(URLLoaderFactory& url_loader_factory,
                          uint32 process_id);

   // Gets the CookieManager associated with this network context.
   GetCookieManager(CookieManager& cookie_manager);

   // TODO(crbug.com/729800): Switch from {process,frame}_id to the network
   //                         service's representation of security principals.
   GetRestrictedCookieManager(
       RestrictedCookieManager& restricted_cookie_manager,
       int32 render_process_id, int32 render_frame_id);

   // Clears network objects with implicit URL history information. Data related
   // to events that happened prior to |start_time| may be retained. Only applies
   // to network objects without more specific methods (Channel ID, Cookies,
   // and the cache have, or will have, their own clearing APIs). This currently
   // only covers server properties and transport security state.
   //
   // The callback will be invoked once the data has been deleted.
   ClearNetworkingHistorySince(mojo.common.mojom.Time start_time) => ();

   // Configures network conditions for the specified throttling profile.
   // The throttling will be applied only to requests that have
   // X-DevTools-Emulate-Network-Conditions-Client-Id: <profile_id>
   // header with matching <profile_id>.
   // Passing null NetworkConditions disables the throttling.
   // TODO(caseq): get rid of header, make profile_id part of ResourceRequest.
   SetNetworkConditions(string profile_id, NetworkConditions? conditions);

   // Creates a UDP socket. Caller can supply a |receiver| interface pointer
   // to listen for incoming datagrams. A null |receiver| is acceptable if caller
   // is not interested in incoming data.
   // Any sockets that are created but are yet to be destroyed will be destroyed
   // when NetworkContext goes away.
   CreateUDPSocket(network.mojom.UDPSocket& request,
                   network.mojom.UDPSocketReceiver? receiver);

   [Sync]
   // Adds explicitly-specified data as if it was processed from an
   // HSTS header.
   AddHSTSForTesting(string host,
                     mojo.common.mojom.Time expiry,
                     bool include_subdomains) => ();
 };

 // The content/browser implementation of this SSLPrivateKey interface wraps the
 // scoped_refptr<net::SSLPrivateKey> that is received from
 // SSLClientAuthDelegate::ContinueWithCertificate(), and this mojo interface is
 // sent from content/browser to services/network so that services/network can
 // have its own net::SSLPrivateKey implementation that internally uses this mojo
 // interface.
 // The |algorithm| and |input| parameters correspond to the |algorithm| and
 // |input| parameters in net::SSLPrivateKey::Sign().
 // The |net_error| and |signature| parameters correspond to the parameters in
 // net::SSLPrivateKey::SignCallback.
 interface SSLPrivateKey {
   Sign(uint16 algorithm,
        array<uint8> input) => (int32 net_error, array<uint8> signature);
 };

 // Network service interface to the browser.
 interface NetworkServiceClient {
   // Called when an SSL certificate requested message is received for client
   // authentication.
   // The |algorithm_preferences| parameter corresponds to the return value
   // of net::SSLPrivateKey::GetAlgorithmPreferences().
   // The |cancel_certificate_selection| parameter is used to distinguish
   // between the following two cases because the |x509_certificate| will be
   // nullptr in both cases:
   // 1. The connection is continued with no client cert,
   // net::URLRequest::ContinueWithCertificate(nullptr, nullptr) needs to be
   // called.
   // 2. The request is aborted, net::URLRequest::CancelWithError() needs to be
   // called.
   OnCertificateRequested(uint32 process_id,
                          uint32 routing_id,
                          network.mojom.SSLCertRequestInfo cert_info) => (
                              network.mojom.X509Certificate x509_certificate,
                              array<uint16> algorithm_preferences,
                              SSLPrivateKey ssl_private_key,
                              bool cancel_certificate_selection);
   // Called when an SSL certificate is encountered.
   // The callback argument is a net::ERROR value. If it's net::OK, then the
   // request is resumed. Otherwise it's cancelled with the given error.
   OnSSLCertificateError(int32 resource_type,
                         url.mojom.Url url,
                         uint32 process_id,
                         uint32 routing_id,
                         SSLInfo ssl_info,
                         bool fatal) => (int32 net_error);
 };

 // Browser interface to the network service.
 interface NetworkService {
   SetClient(NetworkServiceClient client);

   // Creates a new network context with the given parameters.
   CreateNetworkContext(NetworkContext& context,
                        NetworkContextParams params);

   // Disables QUIC for the NetworkService. Affects all existing NetworkContexts,
   // and all new ones that are created. Once called, QUIC cannot be re-enabled.
   DisableQuic();

   // Specifies whether requests for raw headers coming through URLLoaderFactory
   // associated with the specified process will be granted. Granting such a
   // permission increases risks in case the child process becomes compromised,
   // so this should be done only in specific cases (e.g. DevTools attached).
   SetRawHeadersAccess(uint32 process_id, bool allow);

   // Gets the NetworkChangeManager.
   GetNetworkChangeManager(
       NetworkChangeManager& network_change_manager);
 };
	// Copyright 2017 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 "cookie_manager.mojom";
	import "network_change_manager.mojom";
	import "proxy_config.mojom";
	import "net/interfaces/ip_endpoint.mojom";
	import "url_loader.mojom";
	import "url_loader_factory.mojom";
	import "restricted_cookie_manager.mojom";
	import "mojo/common/file_path.mojom";
	import "mojo/common/time.mojom";
	import "url/mojom/url.mojom";
	import "services/network/public/mojom/udp_socket.mojom";
	import "services/proxy_resolver/public/mojom/proxy_resolver.mojom";

	// Parameters for constructing a network context.
	struct NetworkContextParams {
	// Name used by memory tools to identify the context.
	string? context_name;

	// The user agent string.
	string user_agent;

	// Whether Brotli content-encoding should be enabled for HTTPS responses.
	bool enable_brotli = true;

	// QUIC user agent.
	string quic_user_agent_id;

	// Handles PAC script execution. If not populated, will attempt to use
	// platform implementation to execute PAC scripts, if available (Only
	// available on Windows and Mac).
	proxy_resolver.mojom.ProxyResolverFactory? proxy_resolver_factory;

	// Points to the cookie file. An in-memory cookie store is used if it's empty.
	mojo.common.mojom.FilePath? cookie_path;

	// If the cookie file is given, this controls whether previously written
	// session cookies are restored. Otherwise it should be false.
	bool restore_old_session_cookies = false;

	// If the cookie file is given, this controls whether to persist session
	// cookies. Otherwise it should be false.
	bool persist_session_cookies = false;

	// Points to the channel ID file. If a cookie file is specified, this must be
	// specifed as well. Otherwise an in-memory store is used.
	mojo.common.mojom.FilePath? channel_id_path;

	// True if an HTTP cache should be used.
	bool http_cache_enabled = true;
	// Maximum size of the HTTP cache. 0 means to use the default size.
	// Ignored if the cache is disabled.
	int32 http_cache_max_size = 0;
	// Points to the HTTP cache directory. Ignored if the cache is disabled.
	// If null and the cache is enabled, an in-memory database is used.
	mojo.common.mojom.FilePath? http_cache_path;

	// The file to store cached server properties (Like HTTP2 and QUIC support).
	// This information is used as a performance optimization in connection
	// logic. If null, an in-memory cache will be used instead.
	mojo.common.mojom.FilePath? http_server_properties_path;

	// Enabled protocols. Note that these apply to all fetches, including those
	// used to fetch PAC scripts.

	// True if data URLs should be supported.
	bool enable_data_url_support = false;
	// True if file URLs should be supported.
	// Must be false if built without file support.
	bool enable_file_url_support = false;
	// True if ftp URLs should be supported.
	// Must be false if built without FTP support.
	bool enable_ftp_url_support = false;

	// Enables HTTP/0.9 on ports other than 80 for HTTP and 443 for HTTPS.
	bool http_09_on_non_default_ports_enabled = false;

	// Proxy configuration. If \|intial_proxy_config\| is set, it's the initial
	// proxy configuration. Updated proxy configuration can be passed in via
	// \|proxy_config_client_request\|. If \|initial_proxy_config\| is not set,
	// proxy lookups will be deferred until a configuration is received via
	// \|proxy_config_client_request\|.
	//
	// If both are null, the NetworkContext will not use a proxy.
	ProxyConfig? initial_proxy_config;
	ProxyConfigClient&? proxy_config_client_request;

	// If \|proxy_config_client_request\| is non-null, this is called during
	// periods of network activity, and can be used as a signal for polling-based
	// logic to determine the proxy config.
	//
	// TODO(mmenke): Can the consumer piggy back on other network events through
	// other channels (navigation, issuing requests, etc)? Or can
	// ProxyConfigServices be modified not to need this notification?
	ProxyConfigPollerClient? proxy_config_poller_client;
	};

	struct NetworkConditions {
	// If set, the offline state is simulated and other fields are ignored.
	bool offline;

	// Channel round-trip latency, i.e. minimum time between request sent and
	// response received.
	mojo.common.mojom.TimeDelta latency;

	// Maximal aggregated download throughput (bytes/sec). 0 disables download throttling.
	double download_throughput;

	// Maximal aggregated upload throughput (bytes/sec). 0 disables upload throttling.
	double upload_throughput;
	};

	// Represents a distinct context for making network requests, with its own
	// storage (e.g. cookies and cache).
	interface NetworkContext {
	// \|process_id\| is 0 for requests initiated in the browser process, otherwise
	// it's the child process ID.
	CreateURLLoaderFactory(URLLoaderFactory& url_loader_factory,
	uint32 process_id);

	// Gets the CookieManager associated with this network context.
	GetCookieManager(CookieManager& cookie_manager);

	// TODO(crbug.com/729800): Switch from {process,frame}_id to the network
	// service's representation of security principals.
	GetRestrictedCookieManager(
	RestrictedCookieManager& restricted_cookie_manager,
	int32 render_process_id, int32 render_frame_id);

	// Clears network objects with implicit URL history information. Data related
	// to events that happened prior to \|start_time\| may be retained. Only applies
	// to network objects without more specific methods (Channel ID, Cookies,
	// and the cache have, or will have, their own clearing APIs). This currently
	// only covers server properties and transport security state.
	//
	// The callback will be invoked once the data has been deleted.
	ClearNetworkingHistorySince(mojo.common.mojom.Time start_time) => ();

	// Configures network conditions for the specified throttling profile.
	// The throttling will be applied only to requests that have
	// X-DevTools-Emulate-Network-Conditions-Client-Id: <profile_id>
	// header with matching <profile_id>.
	// Passing null NetworkConditions disables the throttling.
	// TODO(caseq): get rid of header, make profile_id part of ResourceRequest.
	SetNetworkConditions(string profile_id, NetworkConditions? conditions);

	// Creates a UDP socket. Caller can supply a \|receiver\| interface pointer
	// to listen for incoming datagrams. A null \|receiver\| is acceptable if caller
	// is not interested in incoming data.
	// Any sockets that are created but are yet to be destroyed will be destroyed
	// when NetworkContext goes away.
	CreateUDPSocket(network.mojom.UDPSocket& request,
	network.mojom.UDPSocketReceiver? receiver);

	[Sync]
	// Adds explicitly-specified data as if it was processed from an
	// HSTS header.
	AddHSTSForTesting(string host,
	mojo.common.mojom.Time expiry,
	bool include_subdomains) => ();
	};

	// The content/browser implementation of this SSLPrivateKey interface wraps the
	// scoped_refptr<net::SSLPrivateKey> that is received from
	// SSLClientAuthDelegate::ContinueWithCertificate(), and this mojo interface is
	// sent from content/browser to services/network so that services/network can
	// have its own net::SSLPrivateKey implementation that internally uses this mojo
	// interface.
	// The \|algorithm\| and \|input\| parameters correspond to the \|algorithm\| and
	// \|input\| parameters in net::SSLPrivateKey::Sign().
	// The \|net_error\| and \|signature\| parameters correspond to the parameters in
	// net::SSLPrivateKey::SignCallback.
	interface SSLPrivateKey {
	Sign(uint16 algorithm,
	array<uint8> input) => (int32 net_error, array<uint8> signature);
	};

	// Network service interface to the browser.
	interface NetworkServiceClient {
	// Called when an SSL certificate requested message is received for client
	// authentication.
	// The \|algorithm_preferences\| parameter corresponds to the return value
	// of net::SSLPrivateKey::GetAlgorithmPreferences().
	// The \|cancel_certificate_selection\| parameter is used to distinguish
	// between the following two cases because the \|x509_certificate\| will be
	// nullptr in both cases:
	// 1. The connection is continued with no client cert,
	// net::URLRequest::ContinueWithCertificate(nullptr, nullptr) needs to be
	// called.
	// 2. The request is aborted, net::URLRequest::CancelWithError() needs to be
	// called.
	OnCertificateRequested(uint32 process_id,
	uint32 routing_id,
	network.mojom.SSLCertRequestInfo cert_info) => (
	network.mojom.X509Certificate x509_certificate,
	array<uint16> algorithm_preferences,
	SSLPrivateKey ssl_private_key,
	bool cancel_certificate_selection);
	// Called when an SSL certificate is encountered.
	// The callback argument is a net::ERROR value. If it's net::OK, then the
	// request is resumed. Otherwise it's cancelled with the given error.
	OnSSLCertificateError(int32 resource_type,
	url.mojom.Url url,
	uint32 process_id,
	uint32 routing_id,
	SSLInfo ssl_info,
	bool fatal) => (int32 net_error);
	};

	// Browser interface to the network service.
	interface NetworkService {
	SetClient(NetworkServiceClient client);

	// Creates a new network context with the given parameters.
	CreateNetworkContext(NetworkContext& context,
	NetworkContextParams params);

	// Disables QUIC for the NetworkService. Affects all existing NetworkContexts,
	// and all new ones that are created. Once called, QUIC cannot be re-enabled.
	DisableQuic();

	// Specifies whether requests for raw headers coming through URLLoaderFactory
	// associated with the specified process will be granted. Granting such a
	// permission increases risks in case the child process becomes compromised,
	// so this should be done only in specific cases (e.g. DevTools attached).
	SetRawHeadersAccess(uint32 process_id, bool allow);

	// Gets the NetworkChangeManager.
	GetNetworkChangeManager(
	NetworkChangeManager& network_change_manager);
	};