| // 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/time.mojom"; |
| import "services/network/public/mojom/address_list.mojom"; |
| import "services/network/public/mojom/ip_address.mojom"; |
| import "services/network/public/mojom/ip_endpoint.mojom"; |
| import "services/network/public/mojom/network_isolation_key.mojom"; |
| import "services/network/public/mojom/network_param.mojom"; |
| import "services/network/public/mojom/request_priority.mojom"; |
| |
| struct DnsOverHttpsServerConfig { |
| string server_template; |
| array<array<network.mojom.IPAddress>> endpoints; |
| }; |
| |
| // The DNS over HTTPS configuration, containing zero or more servers. |
| struct DnsOverHttpsConfig { |
| array<DnsOverHttpsServerConfig> servers; |
| }; |
| |
| // The secure DNS mode specifies what types of lookups (secure/insecure) should |
| // be performed and in what order when resolving a specific query. This is |
| // an expanded version of net::SecureDnsMode that includes representation of an |
| // optional SecureDnsMode. Needed because Mojo does not support optional enums. |
| enum OptionalSecureDnsMode { |
| NO_OVERRIDE, |
| OFF, |
| AUTOMATIC, |
| SECURE, |
| }; |
| |
| // This enum corresponds to net::SecureDnsMode. |
| enum SecureDnsMode { |
| OFF, |
| AUTOMATIC, |
| SECURE, |
| }; |
| |
| // This enum corresponds to net::SecureDnsPolicy |
| enum SecureDnsPolicy { |
| ALLOW, |
| DISABLE, |
| // The "bootstrap" policy is only used within the network process, so it is |
| // not exposed via Mojo. |
| }; |
| |
| // Overridable DNS configuration values for host resolution. All fields default |
| // to a non-overriding state where the relevant value will be used from system |
| // DNS configuration. |
| struct DnsConfigOverrides { |
| // Representation of an optional boolean. Needed because Mojo does not support |
| // optional primitive types. |
| enum Tristate { |
| NO_OVERRIDE, |
| TRISTATE_TRUE, |
| TRISTATE_FALSE, |
| }; |
| |
| // List of nameserver addresses. |
| array<IPEndPoint>? nameservers; |
| |
| // Suffix search list, used on first lookup when number of dots in given name |
| // is less than |ndots|. |
| array<string>? search; |
| |
| // Whether suffix search should be performed for multi-label names. |
| Tristate append_to_multi_label_name = Tristate.NO_OVERRIDE; |
| |
| // Minimum number of dots before global resolution precedes |search|. |
| int8 ndots = -1; // -1 for no override. |
| |
| // Time between retransmissions, see res_state.retrans. |
| mojo_base.mojom.TimeDelta? fallback_period; |
| |
| // Maximum number of attempts, see res_state.retry. |
| int32 attempts = -1; // -1 for no override. |
| |
| // Whether to roundrobin entries in |nameservers| for subsequent requests. |
| Tristate rotate = Tristate.NO_OVERRIDE; |
| |
| // Whether system configuration uses local IPv6 connectivity, e.g., |
| // DirectAccess. This is exposed for HostResolver to skip IPv6 probes, |
| // as it may cause them to return incorrect results. |
| Tristate use_local_ipv6 = Tristate.NO_OVERRIDE; |
| |
| // DNS over HTTPS configuration, containing servers to query. |
| DnsOverHttpsConfig? dns_over_https_config; |
| |
| // The SecureDnsMode to use when resolving queries. If set, it overrides |
| // the resolver's current configured mode, and can in turn be overridden by |
| // ResolveHostParameters.secure_dns_policy. |
| OptionalSecureDnsMode secure_dns_mode = OptionalSecureDnsMode.NO_OVERRIDE; |
| |
| // Whether automatic upgrade to DNS over HTTPS servers is permitted. |
| Tristate allow_dns_over_https_upgrade = Tristate.NO_OVERRIDE; |
| |
| // Whether to clear data read from the system HOSTS file. |
| bool clear_hosts = false; |
| }; |
| |
| // Control handle used to control outstanding NetworkContext::ResolveHost |
| // requests. Handle is optional for all requests, and may be closed at any time |
| // without affecting the request. |
| // |
| // TODO(crbug.com/821021): Add support to change priority. |
| interface ResolveHostHandle { |
| // Requests cancellation of the resolution request. Doing so may have no |
| // effect if a result was already sent. If successful, cancellation results in |
| // ResolveHostClient::OnComplete being invoked with |result|, which should be |
| // a non-OK network error code. |
| Cancel(int32 result); |
| }; |
| |
| // Response interface used to receive results of NetworkContext::ResolveHost |
| // requests. |
| // |
| // If only some result types are expected for an implementation, e.g. only |
| // address types will be queried, see |
| // services/network/public/cpp/resolve_host_client_base.h for a partial C++ |
| // implementation that allows overriding just expected result types. |
| interface ResolveHostClient { |
| // Called on completion of a resolve host request. Results are a network error |
| // code, additional error info, and on success (result == OK, |
| // resolve_error_info.error == OK) and when results are in address form, an |
| // AddressList. The error code in |resolve_error_info.error| should be used |
| // when detailed error information is needed, whereas the error code in |
| // |result| should be used when less specific error information (i.e. OK vs |
| // ERR_NAME_NOT_RESOLVED) is sufficient. |
| // |
| // Always called last to signal completion of the ResolveHost() request. |
| // Unless the ResolveHostClient is closed, this method will always be called |
| // exactly once, and afterwards, no more methods in the interface will be |
| // called. |
| OnComplete(int32 result, |
| ResolveErrorInfo resolve_error_info, |
| AddressList? resolved_addresses); |
| |
| // One or more On...Results() methods may be called when non-address results |
| // are available. Always called before OnComplete(). |
| OnTextResults(array<string> text_results); |
| OnHostnameResults(array<HostPortPair> hosts); |
| }; |
| |
| // DNS query type for a ResolveHostRequest. |
| // See: |
| // https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-4 |
| enum DnsQueryType { |
| UNSPECIFIED, |
| A, |
| AAAA, |
| TXT, |
| PTR, |
| SRV, |
| HTTPS, |
| }; |
| |
| // Parameter-grouping struct for additional optional parameters for |
| // HostResolver::ResolveHost() calls. All fields are optional and have a |
| // reasonable default. |
| struct ResolveHostParameters { |
| // Requested DNS query type. If UNSPECIFIED, resolver will pick A or AAAA (or |
| // both) based on IPv4/IPv6 settings. |
| DnsQueryType dns_query_type = DnsQueryType.UNSPECIFIED; |
| |
| // The initial net priority for the host resolution request. |
| RequestPriority initial_priority = RequestPriority.kLowest; |
| |
| // Enumeration to specify the allowed results source for requests. |
| enum Source { |
| // Resolver will pick an appropriate source. Results could come from DNS, |
| // MulticastDNS, HOSTS file, etc. |
| ANY, |
| |
| // Results will only be retrieved from the system or OS, e.g. via the |
| // getaddrinfo() system call. |
| SYSTEM, |
| |
| // Results will only come from DNS queries. |
| DNS, |
| |
| // Results will only come from Multicast DNS queries. |
| MULTICAST_DNS, |
| |
| // No external sources will be used. Results will only come from fast local |
| // sources that are available no matter the source setting, e.g. cache, |
| // hosts file, IP literal resolution, etc. |
| LOCAL_ONLY, |
| }; |
| |
| // The source to use for resolved addresses. Default allows the resolver to |
| // pick an appropriate source. Only affects use of big external sources (eg |
| // calling the system for resolution or using DNS). Even if a source is |
| // specified, results can still come from cache, resolving "localhost" or IP |
| // literals, etc. |
| Source source = Source.ANY; |
| |
| // Cache usage mode for ResolveHostRequest. Values corresponding to |
| // HostResolver::ResolveHostParameters::CacheUsage |
| enum CacheUsage { |
| // Results may come from the host cache if non-stale. |
| ALLOWED, |
| |
| // Results may come from the host cache even if stale (by expiration or |
| // network changes). |
| STALE_ALLOWED, |
| |
| // Results will not come from the host cache. |
| DISALLOWED, |
| }; |
| |
| // Indicates what DNS cache entries, if any, can be used to provide a |
| // response. |
| CacheUsage cache_usage = CacheUsage.ALLOWED; |
| |
| // If set, the outstanding request can be controlled, eg cancelled, via the |
| // handle. |
| pending_receiver<ResolveHostHandle>? control_handle; |
| |
| // If |true|, requests that the resolver include AddressList::canonical_name |
| // in the results. If the resolver can do so without significant performance |
| // impact, canonical_name may still be included even if parameter is set to |
| // |false|. |
| bool include_canonical_name = false; |
| |
| // Hint to the resolver that resolution is only being requested for loopback |
| // hosts. |
| bool loopback_only = false; |
| |
| // Set |true| iff the host resolve request is only being made speculatively |
| // to fill the cache and the result addresses will not be used. The request |
| // will receive special logging/observer treatment, and |
| // ResolveHostClient::OnComplete will not receive any addresses. |
| bool is_speculative = false; |
| |
| // Controls the resolver's Secure DNS behavior for this request. |
| SecureDnsPolicy secure_dns_policy = SecureDnsPolicy.ALLOW; |
| |
| // Enumeration for specifying the purpose of a host resolve request. |
| // These values are used for UMA. Entries should not be reordered. Keep this |
| // in sync with tools/metrics/histograms/enums.xml. |
| // TODO(crbug.com/1232623): Consider adding more values if kPreconnect isn't |
| // a majority of the purpose of host resolve requests. |
| enum Purpose { |
| kUnspecified, |
| kPreconnect, |
| }; |
| |
| // Specifies the purpose of the request. |
| Purpose purpose = Purpose.kUnspecified; |
| }; |
| |
| // Response interface used to receive notifications from |
| // HostResolver::MdnsListen requests. All methods have a |query_type| field to |
| // allow a single BindingSet and implementation to be used to listen for updates |
| // for multiple types for the same host. |
| interface MdnsListenClient { |
| enum UpdateType { |
| ADDED, |
| CHANGED, |
| REMOVED |
| }; |
| |
| OnAddressResult(UpdateType update_type, |
| DnsQueryType query_type, |
| IPEndPoint endpoint); |
| OnTextResult(UpdateType update_type, |
| DnsQueryType query_type, |
| array<string> text_records); |
| OnHostnameResult(UpdateType update_type, |
| DnsQueryType query_type, |
| HostPortPair host); |
| |
| // For results which may be valid MDNS but are not handled/parsed by network |
| // service, e.g. pointers to the root domain. |
| OnUnhandledResult(UpdateType update_type, DnsQueryType query_type); |
| }; |
| |
| // Interface that can be passed to code/processes without direct access to |
| // NetworkContext to make ResolveHost requests. If destroyed, all outstanding |
| // ResolveHost and MdnsListen requests from the destroyed interface will be |
| // cancelled. |
| interface HostResolver { |
| // Resolves the given hostname (or IP address literal). Results are a network |
| // error code, and on success (network error code OK), an AddressList. All |
| // results are sent via the passed |response_client|. |
| // |
| // |network_isolation_key| specifies what NetworkIsolationKey to use as an |
| // index into the host cache. This both allows a URLLoader created with the |
| // same NetworkIsolationKey to access the host cache entry populated by a |
| // call to the HostResolver, and prevents the result from being leaked to |
| // URLLoaders made using a different NetworkIsolationKey. |
| // |
| // Additional optional parameters may be set using |optional_parameters|. If |
| // unset, reasonable defaults will be used, equivalent to using a |
| // ResolveHostParameters struct without changing any fields from their default |
| // values. |
| // |
| // Results in ERR_NAME_NOT_RESOLVED if hostname is invalid, or if it is an |
| // incompatible IP literal (e.g. IPv6 is disabled and it is an IPv6 literal). |
| // |
| // All outstanding requests are cancelled if the HostResolver or parent |
| // NetworkContext are destroyed. Such requests will receive ERR_FAILED via |
| // |response_client|. |
| ResolveHost(HostPortPair host, |
| NetworkIsolationKey network_isolation_key, |
| ResolveHostParameters? optional_parameters, |
| pending_remote<ResolveHostClient> response_client); |
| |
| // Starts a listener to watch for updates to a multicast DNS result. Result is |
| // a network error code indicating the success of starting the listener. On |
| // success (result OK), |response_client| will begin receiving update |
| // notifications. |
| // |
| // All outstanding listeners are cancelled and will receive no further |
| // notifications if the HostResolver or parent NetworkContext are destroyed. |
| MdnsListen(HostPortPair host, |
| DnsQueryType query_type, |
| pending_remote<MdnsListenClient> response_client) |
| => (int32 result); |
| }; |
| |
| // A client interface that subscribes to DNS config change events from |
| // DnsConfigChangeManager. |
| interface DnsConfigChangeManagerClient { |
| // Notifies that a potential change has been detected in the DNS configuration |
| // that may affect results of host resolution. May be a change in system DNS |
| // settings or effective changes added on top by Chrome net code. |
| OnDnsConfigChanged(); |
| }; |
| |
| // An interface that broadcasts DNS config change events. |
| interface DnsConfigChangeManager { |
| // Requests to receive notification when there is a DNS config change. |
| RequestNotifications(pending_remote<DnsConfigChangeManagerClient> client); |
| }; |