blob: 34f9b56d1a4ebfe22c716943f208e0d1fa998668 [file] [log] [blame]
// 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 "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/values.mojom";
import "mojo/public/mojom/base/time.mojom";
import "net/interfaces/address_list.mojom";
import "net/interfaces/ip_endpoint.mojom";
import "services/network/public/mojom/cookie_manager.mojom";
import "services/network/public/mojom/ct_log_info.mojom";
import "services/network/public/mojom/mutable_network_traffic_annotation_tag.mojom";
import "services/network/public/mojom/proxy_config.mojom";
import "services/network/public/mojom/proxy_config_with_annotation.mojom";
import "services/network/public/mojom/ssl_config.mojom";
import "services/network/public/mojom/tcp_socket.mojom";
import "services/network/public/mojom/udp_socket.mojom";
import "services/network/public/mojom/url_loader.mojom";
import "services/network/public/mojom/url_loader_factory.mojom";
import "services/network/public/mojom/websocket.mojom";
import "services/proxy_resolver/public/mojom/proxy_resolver.mojom";
import "services/network/public/mojom/restricted_cookie_manager.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.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;
// String to send as the Accept-Language header. This can be changed later
// by calling SetAcceptLanguage on the NetworkContext. If empty, the header
// will not be added.
string accept_language;
// 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_base.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_base.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_base.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_base.mojom.FilePath? http_server_properties_path;
// The directory in which to store cached transport security properties (like
// HSTS). The file itself will be called "TransportSecurity". If null, or the
// file can't be opened, an in-memory store will be used instead.
mojo_base.mojom.FilePath? transport_security_persister_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;
// True if the "Certificate Transparency in Chrome" policy (see
// https://github.com/chromium/ct-policy/blob/master/ct_policy.md) should
// be enforced for certificates and connections.
//
// See //net/docs/certificate-transparency.md before setting this flag to
// true.
bool enforce_chrome_ct_policy = 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;
// SSL configuration. |intial_proxy_config| is the initial SSL configuration
// to use. If nullptr, uses the default configuration. Updated SSL
// configurations can be passed in via |ssl_config_client_request|.
SSLConfig? initial_ssl_config;
SSLConfigClient&? ssl_config_client_request;
// 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.
ProxyConfigWithAnnotation? 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;
// When PAC quick checking is enabled, DNS lookups for PAC script's host are
// timed out aggressively. This prevents hanging all network request on DNS
// lookups that are slow or are blockholed, at the cost of making it more
// likely that the network service erroneously fails to fetch a PAC file.
bool pac_quick_check_enabled = true;
// When enabled, exposes full URLs to PAC scripts. This setting will be
// removed in the future.
// See https://crbug.com/619087
bool dangerously_allow_pac_access_to_secure_urls = false;
// Only used on OS_CHROMEOS platform.
bool allow_gssapi_library_load = false;
// The GSSAPI library name.
// Only used on (OS_POSIX && !OS_ANDROID) platform.
string gssapi_library_name;
// Enables reporting certain SSL errors, such as HTTP Public Key Pinning, to
// servers, so they can discover misconfigurations.
bool enable_certificate_reporting = false;
// The Certificate Transparency logs that are known to the client. SCTs from
// these logs will be extracted and verified; other SCTs will be treated as
// unrecognized.
array<CTLogInfo> ct_logs;
// Sets whether the NetworkContext should be used by all other
// NetworkContexts to validate certs (OCSP, AIA, etc) on some platforms.
// May only be set to true the first NetworkContext created using the
// NetworkService. Destroying a NetworkContext created with this set to true
// will destroy all other NetworkContexts.
//
// A failure to mark a NetworkContext as being used by certificate verification may result in incorrect certificate validation behaviors, such as the inability to verify EV certificates, to build paths when intermediates are missing, and to enforce revocation checking when it was requested via policy.
//
// TODO(mmenke): Once NSS is not used on any platform for certificate verification, we should consider using each URLRequestContext to do its own validation and
// removing this parameter.
bool use_to_validate_certs = false;
};
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_base.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;
};
// Used in some clearing methods of URL-keyed data to specify the resources to
// keep/delete.
struct ClearDataFilter {
enum Type {DELETE_MATCHES, KEEP_MATCHES};
Type type;
// A list of registrable domains (e.g. google.com), internal hostnames
// (e.g. localhost), or IP addresses (e.g. 127.0.0.1). Other domains, such as
// third and lower level domains (e.g. www.google.com) are not accepted.
// Formally, it must hold that GetDomainAndRegistry(|domain|, _) is |domain|
// itself or an empty string.
array<string> domains;
// List of URL origins.
array<url.mojom.Origin> origins;
};
// Represents the accumulated network usage for a consumer.
struct NetworkUsage {
// |process_id| is 0 for the browser process, otherwise it's the child process
// ID.
uint32 process_id;
// The ID of the IPC route for the consumer, which identifies the RenderFrame
// or like-thing.
uint32 routing_id;
// Raw bytes received from the network since the start/restart of the service.
int64 total_bytes_received;
// Raw bytes sent to the network since the start/restart of the service.
int64 total_bytes_sent;
};
// Manages export of ongoing NetLog events to a file.
// Both Start and Stop must succeed, in that order, for the export to
// be complete and have a well-formed file. You may call Start again after
// Stop's callback has been invoked, but doing things like calling Start twice
// without intervening successful stops will result in an error.
interface NetLogExporter {
enum CaptureMode {
// Log all events, but do not include the actual transferred bytes, and
// remove cookies and HTTP credentials and HTTP/2 GOAWAY frame debug data.
DEFAULT,
// Log all events, but do not include the actual transferred bytes as
// parameters for bytes sent/received events.
INCLUDE_COOKIES_AND_CREDENTIALS,
// Log everything possible, even if it is slow and memory expensive.
// Includes logging of transferred bytes.
INCLUDE_SOCKET_BYTES
};
const uint64 kUnlimitedFileSize = 0xFFFFFFFFFFFFFFFF;
// Starts logging to |destination|, including definitions of |extra_constants|
// in the log in addition to the standard constants required by the log.
// Contents in |destination| might not be complete until Stop() is called
// successfully.
//
// If |max_file_size| is kUnlimitedFileSize log size will not be limited.
//
// Returns network error code.
Start(
mojo_base.mojom.File destination,
mojo_base.mojom.DictionaryValue extra_constants,
CaptureMode capture_mode,
uint64 max_file_size) => (int32 net_error);
// Finalizes the log file. If |polled_values| is provided, it will be
// included alongside net configuration info inside the 'polledData' field
// of the log object.
//
// Returns network error code; if successful this will occur only after
// the file has been fully written.
Stop(mojo_base.mojom.DictionaryValue polled_values) => (int32 net_error);
};
const uint32 kBrowserProcessId = 0;
const uint32 kInvalidProcessId = 0xffffffff;
struct URLLoaderFactoryParams {
// Process requesting the URLLoaderFactory.
// Set to kBrowserProcessId to indicate the brower process.
uint32 process_id = kInvalidProcessId;
// Cross-origin read blocking (CORB) configuration.
bool is_corb_enabled = true;
string corb_excluded_initiator_scheme;
};
// Represents a distinct context for making network requests, with its own
// storage (e.g. cookies and cache).
interface NetworkContext {
// Creates a new URLLoaderFactory with the given |params|.
CreateURLLoaderFactory(URLLoaderFactory& url_loader_factory,
URLLoaderFactoryParams params);
// Gets the CookieManager associated with this network context.
//
// The CookieManager must only be passed to trusted processes. Whenever
// possible, a RestrictedCookieManager should be handed out instead.
GetCookieManager(CookieManager& cookie_manager);
// Gets a RestrictedCookieManager scoped to a given origin.
//
// This interface can be safely handed out to a process that is known to
// represent the given origin, such as a renderer process.
GetRestrictedCookieManager(RestrictedCookieManager& restricted_cookie_manager,
url.mojom.Origin origin);
// 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_base.mojom.Time start_time) => ();
// Clears content from the HTTP cache. A specific range of time can be
// specified with |start_time| and |end_time|. This supports unbounded deletes
// in either direction by using null Time values for either argument.
ClearHttpCache(mojo_base.mojom.Time start_time,
mojo_base.mojom.Time end_time,
ClearDataFilter? filter) => ();
// Clears channel IDs. A specific range of time can be specified with
// |start_time| and |end_time|. This supports unbounded deletes in either
// direction by using null Time values for either argument.
//
// If a non-null |filter| is specified, will clear only IDs matching the
// filter. Filtering by origins is not supported. If |filter| is non-null,
// |filter.origins| must be empty.
ClearChannelIds(mojo_base.mojom.Time start_time,
mojo_base.mojom.Time end_time,
ClearDataFilter? filter) => ();
// Clears the host cache. This will affect all NetworkContexts that share the
// same HostResolved as the NetworkContext this is called on.
//
// If a non-null |filter| is specified, will clear only entries for domains
// matching the filter. Filtering by origins is not supported. If |filter| is
// non-null, |filter.origins| must be empty.
ClearHostCache(ClearDataFilter? filter) => ();
// Clears all entries from the HTTP Auth cache that were added since
// |start_time|. Supports unbounded delete using null Time value.
ClearHttpAuthCache(mojo_base.mojom.Time start_time) => ();
// Clears all report entries from the reporting cache. Should not be called if
// the ENABLE_REPORTING build flag is false.
//
// If a non-null |filter| is specified, will clear only entries matching the
// filter.
ClearReportingCacheReports(ClearDataFilter? filter) => ();
// Clears all client entries from the reporting cache. Should not be called if
// the ENABLE_REPORTING build flag is false.
//
// If a non-null |filter| is specified, will clear only entries matching the
// filter.
ClearReportingCacheClients(ClearDataFilter? filter) => ();
// Clears policy entries from the NetworkErrorLoggingService. Should not be
// called if the ENABLE_REPORTING build flag is false.
//
// If a non-null |filter| is specified, will clear only entries matching the
// filter.
ClearNetworkErrorLogging(ClearDataFilter? filter) => ();
// 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);
// Updates the Accept-Language header to be used for requests.
SetAcceptLanguage(string new_accept_language);
// Updates the CT policy to be used for requests. Only applies if the
// NetworkContextParams set enforce_chrome_ct_policy to true.
// TODO(rsleevi): Remove this once Chrome-specific policies are moved out
// of the network service.
SetCTPolicy(array<string> required_hosts,
array<string> excluded_hosts,
array<string> excluded_spkis,
array<string> excluded_legacy_spkis);
// 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(UDPSocket& request, UDPSocketReceiver? receiver);
// Creates a TCP server socket that listens on |local_addr|. The socket
// created can only be used for the purpose specified in |traffic_annotation|,
// and cannot be re-used for other purposes. Caller must specify an address
// family in |local_addr| to be either IPv4 or IPv6. If port in |local_addr|
// is 0, the OS will pick an available port. If address bytes are 0, the OS
// will pick a local address of the specified address family. |backlog| will
// be passed to the OS to set the size of accept queue.
// On success, the resulting local address will be written to |local_addr_out|
// and |result| is net::OK. On failure, |result| is a network error code.
//
// Any sockets that are created but are yet to be destroyed will be destroyed
// when NetworkContext goes away.
CreateTCPServerSocket(net.interfaces.IPEndPoint local_addr,
uint32 backlog,
MutableNetworkTrafficAnnotationTag traffic_annotation,
TCPServerSocket& socket)
=> (int32 result, net.interfaces.IPEndPoint? local_addr_out);
// Creates a TCP socket connected to |remote_addr|. |observer| if non-null
// will be used to listen for any network connection error on the newly
// established connection. The socket created can only be used for the purpose
// specified in |traffic_annotation|, and cannot be re-used for other
// purposes. |local_addr| should be set to null unless the caller wants to
// bind the socket to a specific address and port. 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.
//
// Any sockets that are created but are yet to be destroyed will be destroyed
// when NetworkContext goes away.
CreateTCPConnectedSocket(
net.interfaces.IPEndPoint? local_addr,
net.interfaces.AddressList remote_addr_list,
MutableNetworkTrafficAnnotationTag traffic_annotation,
TCPConnectedSocket& socket,
SocketObserver? observer)
=> (int32 result,
net.interfaces.IPEndPoint? local_addr,
net.interfaces.IPEndPoint? peer_addr,
handle<data_pipe_consumer>? receive_stream,
handle<data_pipe_producer>? send_stream);
// Creates a WebSocket connection.
CreateWebSocket(WebSocket& request,
int32 process_id,
int32 render_frame_id,
url.mojom.Origin origin);
// Create a NetLogExporter, which helps export NetLog to an existing file.
// Note that the log is generally global, including all NetworkContexts
// managed by the same NetworkService. The particular NetworkContext this is
// called on will determine which NetworkContext gets its information and
// configuration summary written out at the end of the log.
CreateNetLogExporter(NetLogExporter& exporter);
// Enables/Disables blocking of third-party cookies.
BlockThirdPartyCookies(bool block);
[Sync]
// Adds explicitly-specified data as if it was processed from an
// HSTS header.
AddHSTSForTesting(string host,
mojo_base.mojom.Time expiry,
bool include_subdomains) => ();
[Sync]
// Will force the transaction to fail with the given error code.
SetFailingHttpTransactionForTesting(int32 rv) => ();
};